Configuration Reference

Open Terminal has sensible defaults out of the box. This page covers all the settings you can customize if you need to.

Settings are applied in this order (later ones override earlier ones):

1. Built-in defaults
2. System config file (/etc/open-terminal/config.toml)
3. User config file (~/.config/open-terminal/config.toml)
4. Environment variables (OPEN_TERMINAL_*)
5. CLI flags (--host, --port, etc.)

---

All settings

Setting	Default	Environment Variable	Description
Host	0.0.0.0	None	Network address to listen on
Port	8000	None	Port number
API Key	Auto-generated	OPEN_TERMINAL_API_KEY	Password for connecting
API Key File	None	OPEN_TERMINAL_API_KEY_FILE	Load the key from a file (for Docker secrets)
Log Directory	~/.local/state/open-terminal/logs	OPEN_TERMINAL_LOG_DIR	Where to save log files
Max Sessions	16	OPEN_TERMINAL_MAX_SESSIONS	Maximum concurrent terminal sessions
Enable Terminal	true	OPEN_TERMINAL_ENABLE_TERMINAL	Turn the interactive terminal on/off
Enable Notebooks	true	OPEN_TERMINAL_ENABLE_NOTEBOOKS	Turn Jupyter notebook execution on/off
TERM	xterm-256color	OPEN_TERMINAL_TERM	Terminal color support
Execute Timeout	Unset	OPEN_TERMINAL_EXECUTE_TIMEOUT	How long (seconds) to wait for command output
Execute Description	None	OPEN_TERMINAL_EXECUTE_DESCRIPTION	Custom text telling the AI about installed tools
Enable System Prompt	true	OPEN_TERMINAL_ENABLE_SYSTEM_PROMPT	Expose the /system prompt endpoint
System Prompt	Generated	OPEN_TERMINAL_SYSTEM_PROMPT	Replace the generated prompt with a custom template
Environment Info	None	OPEN_TERMINAL_INFO	Append operator-provided environment context to the generated prompt
File Browser Root	home	OPEN_TERMINAL_FILE_BROWSER_ROOT	Use home, an explicit path such as /workspace, or filesystem to opt out
Multi-User	false	OPEN_TERMINAL_MULTI_USER	Enable per-user isolation
CORS Origins	None	OPEN_TERMINAL_CORS_ALLOWED_ORIGINS	Allowed cross-origin domains
Allowed Domains	None	OPEN_TERMINAL_ALLOWED_DOMAINS	Egress firewall: only allow outbound connections to these domains

---

Docker-only settings

These only work with the Docker image:

Setting	Environment Variable	Description
System Packages	OPEN_TERMINAL_PACKAGES	Space-separated list of system packages to install at startup
Python Packages	OPEN_TERMINAL_PIP_PACKAGES	Space-separated list of Python packages to install at startup

note

These packages are reinstalled every time the container starts. If you need many packages, consider building a custom image instead.

OpenShift image

The ghcr.io/open-webui/open-terminal:openshift image does not support runtime package installation, OPEN_TERMINAL_ALLOWED_DOMAINS, Docker socket workflows, or OPEN_TERMINAL_MULTI_USER=true. Install required tools in a custom image before deploying to OpenShift.

---

Config file

Instead of environment variables, you can put settings in a file:

host = "0.0.0.0"
port = 8000
api_key = "your-secret-key"
log_dir = "/var/log/open-terminal"
max_terminal_sessions = 16
enable_terminal = true
enable_notebooks = true
execute_timeout = 5
execute_description = "This terminal has ffmpeg and ImageMagick installed."

Why use a config file?

It keeps your API key out of the command line and shell history. Anyone running ps or htop on the machine won't see it.

To use a config file in a custom location:

open-terminal run --config /path/to/my-config.toml

System prompt placeholders

When OPEN_TERMINAL_SYSTEM_PROMPT is set, Open Terminal expands these placeholders:

Placeholder	Value
{{os}}	Operating system name
{{kernel}}	Kernel or OS release
{{arch}}	Machine architecture
{{hostname}}	Hostname
{{user}}	Runtime user when available
{{shell}}	Shell path
{{python_version}}	Python version
{{home}}	Runtime home directory

Unknown placeholders are left unchanged.

---

Docker secrets

For production Docker deployments, you can load the API key from a secret file:

services:
  open-terminal:
    image: ghcr.io/open-webui/open-terminal
    environment:
      - OPEN_TERMINAL_API_KEY_FILE=/run/secrets/terminal_api_key
    secrets:
      - terminal_api_key

secrets:
  terminal_api_key:
    file: ./terminal_api_key.txt

---

Image variants

Open Terminal comes in three sizes:

	latest	slim	alpine
Best for	General use, AI agents	Smaller footprint	Smallest footprint
Size	~4 GB	~430 MB	~230 MB
Includes	Node.js, Python, compilers, ffmpeg, Docker CLI, data science libs	git, curl, jq	git, curl, jq
Can install packages	✔ (has sudo)	✘	✘
Multi-user	✔	✘	✘

If you're not sure, use latest. It has everything pre-installed so the AI can work with any tool without waiting for installs.

Related

• Security best practices →
• Multi-user setup →