Installation

Choose an installation method based on your needs:

Method	When to use
Docker	Runs in an isolated container, separated from your host system.
Bare Metal	The AI works directly on your machine, on your real files, tools, and environment.
Docker Compose	You already run Open WebUI with Docker Compose and want to add Open Terminal to it.

Select your method below, then follow the steps.

Docker

Requires Docker.

1. Start the container

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

Replace your-secret-key with a password of your choice.

Command breakdown

Flag	Purpose
-d	Run in background
--name open-terminal	Container name for reference
--restart unless-stopped	Auto-restart on reboot
-p 8000:8000	Expose on http://localhost:8000
-v open-terminal:/home/user	Persist files across restarts
-e OPEN_TERMINAL_API_KEY=...	Authentication key

2. Verify

Open http://localhost:8000/docs in your browser. You should see the Open Terminal API page.

Auto-generated API key

If no API key was set, one is generated automatically. Find it with:

docker logs open-terminal

OpenShift

For OpenShift restricted SCC, use ghcr.io/open-webui/open-terminal:openshift through Terminals. That image supports restricted non-root pods, but not runtime package installs, Docker socket access, the iptables egress firewall, or OPEN_TERMINAL_MULTI_USER=true.

Bare Metal

warning

In this mode, the AI can do anything your user account can do, including modifying and deleting files.

1. Run Open Terminal

Option A: Run without installing:

uvx open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

Downloads and runs via uv with no permanent installation.

Option B: Install with pip:

pip install open-terminal
open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

2. Working directory

Open Terminal serves files from the current directory. To scope it to a specific project:

cd /path/to/your/project
uvx open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

Or skip the cd and point the server at the project with the --cwd flag:

uvx open-terminal run --cwd /path/to/your/project --host 0.0.0.0 --port 8000 --api-key your-secret-key
open-terminal run --cwd /path/to/your/project

Windows

Supported via pywinpty. Full PowerShell support with colored output and interactive programs.

Docker Compose

Add Open Terminal as a service in your existing docker-compose.yml:

1. Update your Compose file

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:latest
    container_name: open-webui
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data

  open-terminal:
    image: ghcr.io/open-webui/open-terminal
    container_name: open-terminal
    volumes:
      - open-terminal:/home/user
    environment:
      - OPEN_TERMINAL_API_KEY=your-secret-key

volumes:
  open-webui:
  open-terminal:

2. Start the services

docker compose up -d

Connection URL

When both services share a Docker Compose network, use the service name as the host:

http://open-terminal:8000

localhost won't resolve between containers.

---

Run as an MCP server

Open Terminal can also run as a Model Context Protocol server with open-terminal mcp, exposing the terminal to MCP-compatible clients. This needs the optional mcp extra (which pulls in FastMCP).

Option A: Run without installing:

uvx --from "open-terminal[mcp]" open-terminal mcp

Option B: Install with pip:

pip install "open-terminal[mcp]"
open-terminal mcp

By default the server uses the stdio transport (the client launches the process and talks to it over standard input/output), so most MCP clients just need the command above.

To serve over HTTP instead, switch to the streamable-http transport. The --host and --port flags apply only to this transport (defaults: host 0.0.0.0, port 8000):

open-terminal mcp --transport streamable-http --host 127.0.0.1 --port 8000

The --config (path to a TOML config file) and --cwd (working directory for the server process) flags work the same as for open-terminal run.

---

Looking for the whole machine?

Open WebUI Computer is your entire computer in a browser tab: files, terminal, git, editor, and AI, accessible from any device. It also connects to Open WebUI via its gateway API.

Next step

Connect to Open WebUI →