What Open Terminal is

05 — Open Terminal & Tooling

Giving the model a shell: Open Terminal as a hosted, API-driven terminal that agents can drive, plus how it fits the wider tooling layer.

What Open Terminal is

Open Terminal is a containerised terminal service that exposes a real shell over a REST API rather than a browser-only web terminal. That API surface is the point: it lets a model — not just a human — open sessions, send commands, and read output, which turns “the LLM can talk” into “the LLM can do.”

It’s part of the Open WebUI family and plugs in next to the chat UI, so the same authentication and multi-user model carries over.

How it’s deployed here

open-terminal:
    image: ghcr.io/open-webui/open-terminal
    container_name: open-terminal
    ports:
      - "8080:8080"
    volumes:
      - /var/local/docker-files/open-terminal:/home
    environment:
      - OPEN_TERMINAL_API_KEY=<REDACTED>
      - OPEN_TERMINAL_MULTI_USER=true
    networks:
      - ai-network
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

Key choices, and why:

• OPEN_TERMINAL_MULTI_USER=true — the box serves more than one person, so sessions are isolated per user. If you run a single-user instance you can drop it.
• OPEN_TERMINAL_API_KEY=<REDACTED> — the API is gated by a key. Treat it like a credential: it authorises someone to run shell commands. Never commit the real value (it’s redacted in these docs) and rotate it if it ever leaks.
• /home volume persisted to the host — user workspaces and any files the terminal creates survive container restarts/rebuilds. Without this, an agent’s scratch work vanishes on every image upgrade.
• extra_hosts: host-gateway — the container can reach host services (e.g. the native llama-servers) via host.docker.internal, same pattern as every other container here.
• No published port needed for agent use. It’s reachable from other containers on ai-network by service name, and from the host via the published 8080. Expose only what you actually need from outside.

Why the model needs a shell

A chat model with no tools can only describe what to do. A terminal tool closes that gap: the model can inspect the filesystem, run scripts, check command output, and iterate. This is the same “application tier calls a tool, gets a result, feeds it back into context” loop from 01 — Architecture — Open Terminal is just the most general tool you can give it.

The design consequence: the terminal is a sub-agent-style capability. Just as you’d delegate a coding sub-task to a smaller model, you can have the main agent plan and the terminal (driven by a model) execute. Keeping the executing model small and the planning model big mirrors the sub-agent split.

Security: this is the sharp edge

Giving a model shell access is the highest-risk part of a local AI stack. Guardrails that matter in practice:

• Authenticate with the API key — never expose an unauthenticated terminal API, even on a home LAN.
• Contain the blast radius. Run the terminal in its own container (as here) so a runaway command can’t reach host services or other containers’ data by default. The persisted /home is the intended workspace; keep host-critical paths out of the mount.
• Prefer a non-root user inside the container for day-to-day sessions; reserve root for the specific step that needs it.
• Rotate the key and store it outside version control. The compose file here kept the key inline — a practical choice for a single trusted box, but the safer default is a secrets file or manager that is git-ignored.
• Log and review. Because the model can run arbitrary commands, keep an eye on what it’s actually executing, especially when it’s acting autonomously.

How it relates to the other tools

• Open WebUI is the chat front-end and the place where you wire models and tools together in the UI.
• Open WebUI Pipelines is the plugin/orchestration server — where you build pipelines that chain models, tools, and agents (including calls into Open Terminal).
• Open Terminal is the execution end of that pipeline: the tool that turns a decision into an action on a real system.

A typical agentic flow: user asks the Open WebUI chat → the (primary) model decides it needs to run something → the pipeline invokes Open Terminal’s API → a command runs in a session → output is returned → the model reasons over it and either answers or runs the next command.

Related

• 01 — Architecture — the tiers and how containers reach the host
• Sub-agents — delegating work, which is what a shell tool enables
• Skills — packaging repeatable procedures the model can follow through these tools

Source Disclaimer

• AI Generated
• Human Generated
• AI Edited
• Human Edited