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 — 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

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

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

docker-compose.yml

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.

---

Next step

Connect to Open WebUI →