Open Terminal Documentation

For small, trusted groups, you can enable per-user isolation within a single container. Each user receives a dedicated Linux account and home directory, with isolation enforced via standard Unix permissions.

Caution: This mode is not designed for production multi-user deployments. Users share the same kernel, network, and system resources. For true container-per-user isolation, use the Terminals project.

docker run -d --name open-terminal -p 8000:8000 \
  -v open-terminal:/home \
  -e OPEN_TERMINAL_MULTI_USER=true \
  -e OPEN_TERMINAL_API_KEY=your-secret-key \
  ghcr.io/open-webui/open-terminal

To use Open Terminal within Open WebUI, add it under Open Terminal in the integrations settings (do not add it as a tool server). There are two connection modes:

1. Direct Connection (User-level): Users connect their own instance via User Settings → Integrations → Open Terminal. Requests go directly from the user's browser to the terminal URL. Useful for local or private network terminals.
2. System-Level Connection (Admin-level): Admins configure connections for all users via Admin Settings → Integrations → Open Terminal. Requests are proxied through the Open WebUI backend. This allows the terminal to be reachable only by the server.

You can run Open Terminal directly on your host machine using uvx (no installation required) or via pip.

Warning: On bare metal, commands run with your user's permissions and have access to your real files and tools. Use Docker for sandboxed execution.

# One-liner with uvx (no install needed)
uvx open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

# Or install globally with pip
pip install open-terminal
open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

Run Open Terminal in a sandboxed Docker container. This is the recommended method for AI agent sandboxes as it provides an isolated environment with pre-installed tools like Python, Node.js, and git.

To start a standard instance, use the following command. If you do not set an OPEN_TERMINAL_API_KEY, one will be generated automatically; you can retrieve it using docker logs open-terminal.

docker run -d --name open-terminal --restart unless-stopped -p 8000:8000 -v open-terminal:/home/user -e OPEN_TERMINAL_API_KEY=your-secret-key ghcr.io/open-webui/open-terminal

Settings are resolved in this priority order: CLI flags > Environment variables > User config (~/.config/open-terminal/config.toml) > System config (/etc/open-terminal/config.toml) > Defaults.

Available configuration keys:

• host: Host address (e.g., 0.0.0.0)
• port: Port number
• api_key: Secret key for API access
• cors_allowed_origins: Allowed CORS origins
• log_dir: Directory for logs
• binary_mime_prefixes: MIME prefixes for binary files (e.g., image,audio)
• execute_timeout: Seconds to wait for command output
• file_browser_root: Visual root for the file browser

host = "0.0.0.0"
port = 8000
api_key = "sk-my-secret-key"
cors_allowed_origins = "*"
log_dir = "/var/log/open-terminal"
binary_mime_prefixes = "image,audio"
execute_timeout = 5
file_browser_root = "home"

Set the OPEN_TERMINAL_FILE_BROWSER_ROOT environment variable to provide UI hints to clients (like Open WebUI) regarding the visual starting point of the file browser. This does not restrict terminal or file API access.

• home: (Default) Reports the current user's home directory as Home.
• /workspace: Reports an explicit path as the visual root.
• {{home}}/project: Reports a path under the current user's home.
• filesystem: Opts out of reporting visual root metadata.

Use environment variables to install additional packages at container startup. This is supported in the latest image variant.

• OPEN_TERMINAL_PACKAGES: Space-separated list of apt packages.
• OPEN_TERMINAL_PIP_PACKAGES: Space-separated list of pip packages.
• OPEN_TERMINAL_NPM_PACKAGES: Space-separated list of npm packages to install globally.

docker run -d --name open-terminal -p 8000:8000 \
  -e OPEN_TERMINAL_PACKAGES="cowsay figlet" \
  -e OPEN_TERMINAL_PIP_PACKAGES="httpx polars" \
  -e OPEN_TERMINAL_NPM_PACKAGES="typescript tsx" \
  ghcr.io/open-webui/open-terminal

Open Terminal supports full interactive terminal sessions (PTY on Unix, WinPTY on Windows) via WebSockets.

Workflow:

1. Create: POST /api/terminals returns a session_id.
2. Connect: Open a WebSocket to ws://<host>/api/terminals/{session_id}.
3. Authenticate: The first message sent over the WebSocket must be a JSON text frame: {"type": "auth", "token": "<api_key>"}.
4. Interact: After auth, send keystrokes as binary frames and receive PTY output as binary frames.
5. Resize: Send a JSON text frame to resize the terminal: {"type": "resize", "cols": 120, "rows": 40}.
6. Cleanup: DELETE /api/terminals/{session_id} to kill the session.

The API key for the sandbox server can be provided through several mechanisms:

1. CLI Flag: --api-key <key>
2. Environment Variable: OPEN_TERMINAL_API_KEY
3. Docker Secrets: Set the OPEN_TERMINAL_API_KEY_FILE environment variable to the path of a file containing the key. The server will read the content of that file.
4. Config File: The api_key key in your TOML configuration file.
5. Auto-generation: If none of the above are provided, a random key is generated.

Select an image based on your requirements for footprint and tooling:

• latest: Full AI agent sandbox (~4 GB). Includes Node.js, gcc, ffmpeg, LaTeX, Docker CLI, and data science libs. Supports runtime package installation and multi-user mode.
• slim: Production/hardened (~430 MB). Includes git, curl, and jq. Uses Debian (glibc). Does not support runtime package installation or multi-user mode.
• alpine: Edge/CI/Minimal (~230 MB). Includes git, curl, and jq. Uses musl libc. Does not support runtime package installation or multi-user mode.
• openshift: Restricted SCC (~430 MB). Includes git, curl, and jq. Does not support runtime package installation, Docker socket access, egress firewall, or multi-user mode.

Perform file system write operations.

• Write File (POST /files/write): Overwrites or creates a file with the provided text content. Parent directories are created automatically.
  • Body: WriteRequest with path and content.
• Replace Content (POST /files/replace): Performs find-and-replace operations on a file.
  • Body: ReplaceRequest containing a list of ReplacementChunk objects.
  • ReplacementChunk fields: target (string to find), replacement (string to insert), start_line/end_line (optional range), allow_multiple (boolean).
• Create Directory (POST /files/mkdir): Creates a directory path.
  • Body: MkdirRequest with path.

You can expose the Open Terminal FastAPI application as a Model Context Protocol (MCP) server using FastMCP.from_fastapi. This automatically converts every FastAPI endpoint into an MCP tool. The server requires an API_KEY passed via the Authorization header in httpx_client_kwargs to authenticate requests to the underlying Open Terminal API.

from fastmcp import FastMCP
from open_terminal.main import app
from open_terminal.env import API_KEY

mcp = FastMCP.from_fastapi(
    app=app,
    name="Open Terminal",
    httpx_client_kwargs={
        "headers": {
            "Authorization": f"Bearer {API_KEY}",
        }
    },
)