centersl/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-03-26 13:18:42 +07:00
Code Issues Packages Projects Releases Wiki Activity

doc: open terminal

Browse Source
This commit is contained in:
Timothy Jaeryang Baek
2026-03-21 02:47:33 -05:00
parent 1c7049a43f
commit 6da202b77a
32 changed files with 2163 additions and 386 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/features/ai-knowledge/skills.md
View File

@@ -104,7 +104,7 @@ Open Terminal is a FastAPI application that automatically exposes an [OpenAPI sp
**1. Start an Open Terminal instance**
Follow the [Open Terminal setup guide](/features/extensibility/open-terminal#getting-started) to launch an instance using Docker or pip.
Follow the [Open Terminal setup guide](/features/open-terminal#getting-started) to launch an instance using Docker or pip.
**2. Connect to Open WebUI**
@@ -119,7 +119,7 @@ Once connected, the Open Terminal tools (execute, file upload, file download) ap
For the best experience, pair Open Terminal with a [Skill](/features/ai-knowledge/skills) that teaches the model how to use the tool effectively — for example, instructing it to always check exit codes, handle errors gracefully, and use streaming for long-running commands.
:::
See the [Open Terminal documentation](/features/extensibility/open-terminal) for the full API reference and detailed setup instructions.
See the [Open Terminal documentation](/features/open-terminal) for the full API reference and detailed setup instructions.
## Access Control

382
docs/features/extensibility/open-terminal/index.md
View File

@@ -1,382 +0,0 @@
---
sidebar_position: 3
title: "Open Terminal"
---
# ⚡ Open Terminal
## Overview
[Open Terminal](https://github.com/open-webui/open-terminal) gives your AI a real computer. Instead of running code in a sandboxed browser snippet, the model gets a full operating system where it can install software, run code in any language, manage files, and execute multi-step workflows, all from your chat.
When connected to Open WebUI, every terminal capability is **automatically available** to the model with no manual setup per chat. You also get a **built-in file browser** right in the conversation, so you can see, edit, and manage everything the AI creates.
## What Can You Do With It?
### A developer working on a project
> *"Clone this repo, install the dependencies, and run the test suite"*
The AI runs real `git`, `npm`, and `pytest` commands in the terminal. You watch the output, browse the cloned files in the file browser, and fix a failing test by editing the file inline, all without leaving the chat.
On **bare metal**, the AI works directly on your actual project directory. On **Docker**, it gets its own isolated copy.
### A data analyst processing files
> *"Here's a CSV of sales data. Clean the headers, remove duplicates, and make a chart of revenue by quarter"*
Drop the file onto the file browser (drag-and-drop upload), and the AI picks it up. It installs pandas, cleans the data, generates a matplotlib chart, and saves the output. You preview the chart in the file browser, then download the cleaned CSV and the PNG to your local machine.
### A student or researcher exploring a new tool
> *"Install ffmpeg and convert this video to a GIF, keeping only the first 10 seconds"*
The AI runs `apt-get install ffmpeg` (in Docker, it has `sudo`), then runs the conversion. You upload the video through the file browser, and download the resulting GIF. The AI has access to the full OS, so any tool you can install on Linux, it can use.
### A team lead setting up shared environments
An admin configures one or more Open Terminal instances and makes them available to the whole team (or specific groups) through Open WebUI. Users pick a terminal from a dropdown and start working. They never see API keys or server URLs. All requests go through the Open WebUI backend, so the terminal only needs to be reachable from the server, not from every user's machine.
## Getting Started
### Docker (Recommended)
Run Open Terminal in an isolated container with a full toolkit pre-installed: Python, git, build tools, data science libraries, and more. Great for giving AI agents a safe playground without touching your host system.
```bash
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
```
You're up and running at `http://localhost:8000`.
The `-v open-terminal:/home/user` flag creates a **named volume** so files survive container restarts. The container runs as a non-root user with passwordless `sudo` available when needed.
:::tip
If you don't set an API key, one is generated automatically. Grab it with `docker logs open-terminal`.
:::
<details>
<summary><b>Pre-installed tools and libraries</b></summary>
| Category | Included |
| :--- | :--- |
| **Core utilities** | coreutils, findutils, grep, sed, gawk, diffutils, patch, less, file, tree, bc |
| **Networking** | curl, wget, net-tools, iputils-ping, dnsutils, netcat, socat, openssh-client, rsync |
| **Editors** | vim, nano |
| **Version control** | git |
| **Build tools** | build-essential, cmake, make |
| **Languages** | Python 3.12, Perl, Ruby, Lua 5.4 |
| **Data processing** | jq, xmlstarlet, sqlite3 |
| **Compression** | zip, unzip, tar, gzip, bzip2, xz, zstd, p7zip |
| **System** | procps, htop, lsof, strace, sysstat, sudo, tmux, screen |
| **Container tools** | Docker CLI, Docker Compose, Docker Buildx |
| **Python libraries** | numpy, pandas, scipy, scikit-learn, matplotlib, seaborn, plotly, jupyter, ipython, requests, beautifulsoup4, lxml, sqlalchemy, pyyaml, rich, and more |
You can customize the image by forking the repo and editing the [Dockerfile](https://github.com/open-webui/open-terminal/blob/main/Dockerfile).
</details>
#### Customizing the Docker Environment
The easiest way to add extra packages is with environment variables — no fork needed:
```bash
docker run -d --name open-terminal -p 8000:8000 \
-e OPEN_TERMINAL_PACKAGES="cowsay figlet" \
-e OPEN_TERMINAL_PIP_PACKAGES="httpx polars" \
ghcr.io/open-webui/open-terminal
```
| Variable | Description |
| :--- | :--- |
| `OPEN_TERMINAL_PACKAGES` | Space-separated list of **apt** packages to install at startup |
| `OPEN_TERMINAL_PIP_PACKAGES` | Space-separated list of **pip** packages to install at startup |
:::note
Packages are installed each time the container starts, so startup will take longer with large package lists. For heavy customization, build a custom image instead.
:::
#### Docker Access
The container image includes the Docker CLI, Compose, and Buildx. To let agents build images, run containers, and manage Docker resources, mount the host's Docker socket:
```bash
docker run -d --name open-terminal -p 8000:8000 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v open-terminal:/home/user \
ghcr.io/open-webui/open-terminal
```
The entrypoint automatically fixes socket group permissions so `docker` commands work without `sudo`.
:::warning
Mounting the Docker socket gives the container full access to the host's Docker daemon. Only do this in trusted environments.
:::
### Bare Metal
Want your AI to work directly on **your machine**, with **your files**, **your tools**, and **your environment**? Bare metal mode is for you. No container boundary. The AI gets the same access you do.
```bash
# 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 with pip
pip install open-terminal
open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key
```
This is the most powerful way to use Open Terminal. Point it at your project directory with `--cwd` and let the AI help you run tests, refactor code, manage dependencies, search through files, and write scripts. Everything happens on your real machine with your real tools.
:::info Windows Support
Open Terminal works on Windows too. As of v0.8.0, commands and interactive terminals run under a real pseudo-terminal via [pywinpty](https://github.com/andfoy/pywinpty), which is automatically installed on Windows. You get colored output, interactive programs, and TUI apps — just like on Linux/macOS.
:::
:::warning
Bare metal means the AI can run any command with your user's permissions. This is powerful but comes with real risk. Don't run this in a shared or production environment. If you want sandboxed execution, use Docker instead.
:::
### Docker Compose (with Open WebUI)
```yaml title="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
ports:
- "8000:8000"
volumes:
- open-terminal:/home/user
environment:
- OPEN_TERMINAL_API_KEY=your-secret-key
deploy:
resources:
limits:
memory: 2G
cpus: "2.0"
volumes:
open-webui:
open-terminal:
```
:::tip
When both services run in the same Docker Compose stack, use the **service name** as the hostname. For the admin-configured Open Terminal URL in Open WebUI, use `http://open-terminal:8000`, not `localhost:8000`.
:::
### Configuration
| CLI Option | Default | Environment Variable | Description |
| :--- | :--- | :--- | :--- |
| `--host` | `0.0.0.0` | | Bind address |
| `--port` | `8000` | | Bind port |
| `--cwd` | Current directory | | Working directory for the server process |
| `--api-key` | Auto-generated | `OPEN_TERMINAL_API_KEY` | Bearer API key for authentication |
| `--config` | (see below) | | Path to a custom TOML config file |
| | `~/.local/state/open-terminal/logs` | `OPEN_TERMINAL_LOG_DIR` | Directory for process log files |
| | `16` | `OPEN_TERMINAL_MAX_SESSIONS` | Maximum concurrent interactive terminal sessions |
| | `true` | `OPEN_TERMINAL_ENABLE_TERMINAL` | Enable or disable the interactive terminal feature |
| | `true` | `OPEN_TERMINAL_ENABLE_NOTEBOOKS` | Enable or disable the notebook execution endpoints |
| | | `OPEN_TERMINAL_API_KEY_FILE` | Load the API key from a file instead of an env var (for Docker secrets) |
| | `xterm-256color` | `OPEN_TERMINAL_TERM` | TERM environment variable set in terminal sessions (controls color support) |
| | Unset | `OPEN_TERMINAL_EXECUTE_TIMEOUT` | Default wait time (seconds) for command execution when the caller omits the `wait` parameter. Helps smaller models get output inline. |
| | Unset | `OPEN_TERMINAL_EXECUTE_DESCRIPTION` | Custom text appended to the execute endpoint's OpenAPI description, letting you tell AI models about installed tools, capabilities, or conventions. |
When no API key is provided, Open Terminal generates a random key and prints it to the console on startup.
<details>
<summary><b>TOML configuration file</b></summary>
Instead of passing everything via CLI flags or environment variables, you can use a TOML config file. Open Terminal checks two locations:
1. **System config** — `/etc/open-terminal/config.toml`
2. **User config** — `~/.config/open-terminal/config.toml`
User values override system values. CLI flags and env vars always win. Use `--config /path/to/config.toml` to point to a custom file.
```toml title="config.toml"
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
term = "xterm-256color"
execute_timeout = 5
execute_description = "This terminal has ffmpeg and ImageMagick pre-installed."
```
Using a config file keeps the API key out of `ps` / `htop` output.
</details>
<details>
<summary><b>Docker secrets</b></summary>
You can load the API key from a file using `OPEN_TERMINAL_API_KEY_FILE`, following the convention used by the official PostgreSQL Docker image:
```yaml title="docker-compose.yml"
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
```
`OPEN_TERMINAL_API_KEY` and `OPEN_TERMINAL_API_KEY_FILE` are mutually exclusive — setting both is an error.
</details>
## Connecting to Open WebUI
There are two ways to connect Open Terminal to Open WebUI. Make sure to add it under the **Open Terminal** section in integrations settings. This is a dedicated integration, not a generic tool server.
### Admin-Configured (Recommended)
Administrators can set up Open Terminal connections that are available to all users (or specific groups). All requests are **proxied through the Open WebUI backend**, which means the terminal's API key never reaches the browser and access control is enforced server-side.
1. Go to **Admin Settings → Integrations**
2. Scroll to the **Open Terminal** section
3. Click **+** to add a new connection
4. Enter the **URL** (e.g. `http://open-terminal:8000`) and **API key**
5. Choose an **authentication type** (Bearer is recommended for most setups)
6. Optionally restrict access to specific groups via **access grants**
Each connection has an enable/disable toggle. You can add multiple terminal connections and control them independently.
:::info
Terminal connections can also be pre-configured via the [`TERMINAL_SERVER_CONNECTIONS`](/reference/env-configuration#terminal_server_connections) environment variable.
:::
<details>
<summary><b>Authentication types and access control</b></summary>
| Type | Description |
| :--- | :--- |
| **Bearer** | Sends the configured API key as a `Bearer` token to the terminal server. Default and recommended. |
| **Session** | Forwards the user's Open WebUI session credentials. Useful when the terminal validates against the same auth backend. |
| **OAuth** | Forwards the user's OAuth access token. Requires OAuth to be configured in Open WebUI. |
| **None** | No authentication header. Only for terminals on a trusted internal network. |
By default, all users can access admin-configured terminals. To restrict access, add **access grants** to limit to specific [user groups](/features/access-security/rbac/groups).
</details>
### User-Configured (Direct)
Individual users can add their own terminals under **Settings → Integrations → Open Terminal**. This is ideal for a personal terminal running on your local machine, such as bare metal mode pointed at your project directory.
1. Go to **Settings → Integrations**
2. Scroll to the **Open Terminal** section
3. Click **+** to add a new connection
4. Enter the **URL** and **API key**
:::note
User-configured terminals connect **directly from the browser**. The terminal must be reachable from your machine, and the API key is stored in the browser. For production deployments, prefer the admin-configured approach.
:::
### Networking Tips
Admin-configured and user-configured connections work differently at the network level. **The same URL can work for one but fail for the other.**
| Connection Type | Request Origin | What `localhost` Means |
| :--- | :--- | :--- |
| **Admin (System)** | Open WebUI **backend server** | The machine/container running Open WebUI |
| **User (Direct)** | User's **browser** | The machine running the browser |
**Common issues:**
| Symptom | Likely Cause | Fix |
| :--- | :--- | :--- |
| **502 Bad Gateway** | Backend can't reach the terminal URL | Use a URL the backend can resolve: container name, internal IP, or `host.docker.internal` |
| **User connection works, admin doesn't** | URL resolves from browser but not from backend container | Use different URLs: public URL for user connections, internal URL for admin |
| **Connection timeout** | Firewall or network isolation | Ensure both containers are on the same Docker network |
:::tip Quick Test
To verify the backend can reach your terminal, exec into the Open WebUI container and test:
```bash
curl -s http://open-terminal:8000/health
```
If this returns `{"status": "ok"}`, the backend can reach it.
:::
## The File Browser
When a terminal is selected, the chat controls panel gains a **Files** tab. This isn't just a file list. It's a full file manager connected to the terminal's filesystem.
- **Browse and preview.** Navigate directories, view text files, images, PDFs, CSV/TSV tables (rendered as formatted tables), and Markdown with a source/preview toggle. Great for inspecting what the AI created without leaving the chat.
- **Edit inline.** Click the edit icon on any text file to modify it directly. Useful for quick fixes to a config, a script, or a file the AI generated.
- **Upload (drag-and-drop).** Drop files onto the directory listing to send them to the terminal. This is how you give the AI data to work with: a dataset, an image to process, a document to analyze.
- **Download.** Pull any file from the terminal to your local machine. After the AI generates a chart, a cleaned dataset, a compiled binary, or a report, just download it.
- **Create and delete.** Create new files and folders, or delete ones you no longer need.
- **Attach to chat.** Share a file from the terminal filesystem with the AI as a chat attachment, so it can reference the contents directly.
The file browser remembers your last-visited directory and automatically reloads when you switch terminals.
## Interactive Terminal
Open Terminal can also provide a full interactive terminal session via WebSocket — a real shell running in the container that you can type into directly from Open WebUI. This is the same kind of terminal you'd get from SSH, but accessed through the browser.
This feature is **enabled by default** and is used by the native Open WebUI integration. When a terminal is connected, Open WebUI can open an interactive shell session without any extra setup.
You can control this feature with:
- **`OPEN_TERMINAL_ENABLE_TERMINAL=false`** — disables the interactive terminal entirely. Useful if you only want command execution and file operations.
- **`OPEN_TERMINAL_MAX_SESSIONS=16`** — limits the number of concurrent terminal sessions (default: 16). Prevents resource exhaustion from too many open terminals.
## Port Detection and Proxy
Open Terminal can discover TCP ports that servers (started via the terminal or `/execute`) are listening on and proxy HTTP traffic to them.
- **`GET /ports`** — returns a list of TCP ports listening on localhost, scoped to descendant processes of Open Terminal. Cross-platform: parses `/proc/net/tcp` on Linux, `lsof` on macOS, and `netstat` on Windows. No extra dependencies.
- **`/proxy/{port}/{path}`** — reverse-proxies HTTP requests to `localhost:{port}`. Supports all HTTP methods, forwards headers and body, and returns 502 on connection failure.
This is useful when the AI starts a development server (e.g. a Flask app, a Node.js server, or a static file server) inside the terminal and you want to interact with it from Open WebUI or your browser.
## Notebook Execution
Open Terminal includes built-in Jupyter notebook execution via REST endpoints, powered by `nbclient`. Each session gets its own kernel, and you can execute cells one at a time with full rich output support (images, HTML, LaTeX).
- **`POST /notebooks`** — create a new notebook session (starts a kernel)
- **`POST /notebooks/{id}/execute`** — execute a cell in the session
- **`GET /notebooks/{id}`** — get session status
- **`DELETE /notebooks/{id}`** — stop the kernel and clean up
Notebook execution is **enabled by default**. Disable it with `OPEN_TERMINAL_ENABLE_NOTEBOOKS=false` (or `enable_notebooks = false` in config.toml).
`nbclient` and `ipykernel` are core dependencies and included in the Docker image. For bare metal installs, they are included by default with `pip install open-terminal`.
## Security
- **Always use Docker in production.** Bare metal exposes your host to any command the model generates.
- **Set an API key.** Without one, anyone who can reach the port has full access. Consider using a [config file](#configuration) or Docker secrets to keep the key out of process listings.
- **Use resource limits.** Apply `--memory` and `--cpus` flags in Docker to prevent runaway processes.
- **Session limits.** The default limit of 16 concurrent terminal sessions prevents resource exhaustion. Adjust with `OPEN_TERMINAL_MAX_SESSIONS`.
- **Network isolation.** Place the terminal container on an internal Docker network that only Open WebUI can reach.
- **Use named volumes.** Files inside the container are lost when removed. The default `docker run` command mounts a volume at `/home/user` for persistence.
- **Disable the interactive terminal** if you don't need it, with `OPEN_TERMINAL_ENABLE_TERMINAL=false`.
- **Docker socket access.** Only mount the Docker socket (`/var/run/docker.sock`) in trusted environments. It gives the container full control over the host's Docker daemon.
## Further Reading
- [Open Terminal GitHub Repository](https://github.com/open-webui/open-terminal): source code, issue tracker, and full API documentation
- [Interactive API Docs](http://localhost:8000/docs): Swagger UI available when your instance is running
- [Python Code Execution](/features/chat-conversations/chat-features/code-execution/python): Pyodide and Jupyter backends
- [Terminals](https://github.com/open-webui/terminals): multi-tenant, provisions isolated Open Terminal containers per user

6
docs/features/open-terminal/_category_.json Normal file
View File

@@ -0,0 +1,6 @@
{
"label": "💻 Open Terminal",
"position": 35,
"collapsible": true,
"collapsed": true
}

6
docs/features/open-terminal/advanced/_category_.json Normal file
View File

@@ -0,0 +1,6 @@
{
"label": "Advanced",
"position": 20,
"collapsible": true,
"collapsed": true
}

127
docs/features/open-terminal/advanced/configuration.md Normal file
View File

@@ -0,0 +1,127 @@
---
sidebar_position: 2
title: "Configuration"
---
# 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` | — | Network address to listen on |
| **Port** | `8000` | — | Port number |
| **API Key** | Auto-generated | `OPEN_TERMINAL_API_KEY` | Password for connecting |
| **API Key File** | — | `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** | — | `OPEN_TERMINAL_EXECUTE_DESCRIPTION` | Custom text telling the AI about installed tools |
| **Multi-User** | `false` | `OPEN_TERMINAL_MULTI_USER` | Enable [per-user isolation](./multi-user) |
| **CORS Origins** | — | `OPEN_TERMINAL_CORS_ALLOWED_ORIGINS` | Allowed cross-origin domains |
| **Allowed Domains** | — | `OPEN_TERMINAL_ALLOWED_DOMAINS` | [Egress firewall](./security#egress-filtering): 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](https://github.com/open-webui/open-terminal) instead.
:::
---
## Config file
Instead of environment variables, you can put settings in a file:
```toml title="~/.config/open-terminal/config.toml"
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."
```
{/* TODO: Screenshot — A text editor showing a well-formatted config.toml file. */}
:::tip 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:
```bash
open-terminal run --config /path/to/my-config.toml
```
---
## Docker secrets
For production Docker deployments, you can load the API key from a secret file:
```yaml title="docker-compose.yml"
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
```
{/* TODO: Screenshot — Docker Compose file in an editor with the secrets section highlighted. */}
---
## 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.
{/* TODO: Screenshot — A visual comparison of the three image variants showing relative sizes and capabilities. */}
## Related
- [Security best practices →](./security)
- [Multi-user setup →](./multi-user)

86
docs/features/open-terminal/advanced/multi-user.md Normal file
View File

@@ -0,0 +1,86 @@
---
sidebar_position: 1
title: "Multi-User Setup"
---
# Setting Up Open Terminal for a Team
When multiple people on your team need terminal access through Open WebUI, you have two options.
| | Single Container | Per-User Containers |
| :--- | :--- | :--- |
| **How** | One container, separate accounts inside | Each user gets their own container |
| **Isolation** | Files are separate, but they share the same system | Fully isolated — separate everything |
| **Setup** | One extra setting | Additional orchestration service |
| **Best for** | Small teams you trust | Production, larger teams, untrusted users |
| **Included in** | Open Terminal (free) | [Terminals](https://github.com/open-webui/terminals) (enterprise) |
---
## Option 1: Built-in multi-user mode
The simplest approach. Add one setting and each person automatically gets a separate workspace.
```bash
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
```
{/* TODO: Screenshot — Docker run command in terminal with the MULTI_USER=true flag highlighted. */}
### What happens
When someone uses the terminal through Open WebUI, Open Terminal automatically:
1. Creates a personal account for that user (based on their Open WebUI user ID)
2. Sets up a private home folder at `/home/{user-id}`
3. Runs all their commands under their own account
4. Restricts their file access to their own folder
Each user sees only their own files in the file browser.
{/* TODO: Screenshot — Two views side by side: User A's file browser showing /home/user-a/ with their files, and User B's file browser showing /home/user-b/ with completely different files. */}
### What's shared vs. separate
| | Separate per user | Shared |
| :--- | :--- | :--- |
| Home folder and files | ✔ | |
| Running commands | ✔ | |
| System packages | | ✔ |
| CPU and memory | | ✔ |
| Network access | | ✔ |
:::warning Good for small teams, not production
This mode gives everyone their own workspace, but they're all running inside the same container. If one user runs a script that uses too much memory, it can slow things down for everyone. Use this for small, trusted groups — not for wide-open deployments.
:::
{/* TODO: Screenshot — A simple diagram showing a single container with multiple user accounts inside it. Each user has a private home directory but shares system resources. */}
---
## Option 2: Per-user containers with Terminals
For larger deployments or when you need real isolation, [**Terminals**](https://github.com/open-webui/terminals) gives each user their own container, completely separate from everyone else.
- **Full isolation** — each user's container is independent with its own files, processes, and resources
- **On-demand provisioning** — containers are created when users start a session and cleaned up when idle
- **Resource controls** — set CPU, memory, and storage limits per user or per environment
- **Multiple environments** — different setups for different teams (e.g., data science, development)
- **Kubernetes support** — works with Docker, Kubernetes, and k3s
{/* TODO: Screenshot — Architecture diagram showing Terminals as a management layer between Open WebUI and multiple Open Terminal containers (one per user). */}
See the [Terminals repository](https://github.com/open-webui/terminals) for setup instructions and documentation.
:::info Enterprise license required
Terminals requires an [Open WebUI Enterprise License](https://github.com/open-webui/terminals/blob/main/LICENSE).
:::
## Related
- [Security best practices →](./security)
- [All configuration options →](./configuration)

171
docs/features/open-terminal/advanced/security.md Normal file
View File

@@ -0,0 +1,171 @@
---
sidebar_position: 3
title: "Security"
---
# Security Best Practices
Open Terminal gives AI real power to run commands and manage files. Here's how to make sure that power is used safely.
---
## Use Docker
**Always use Docker** unless you specifically need direct access to your machine. Docker isolates Open Terminal in its own container: it has its own filesystem, its own processes, and can't access anything on your host computer unless you explicitly allow it.
```bash
docker run -d --name open-terminal -p 8000:8000 \
--memory 2g --cpus 2 \
-v open-terminal:/home/user \
-e OPEN_TERMINAL_API_KEY=your-secret-key \
ghcr.io/open-webui/open-terminal
```
The `--memory 2g` and `--cpus 2` flags prevent runaway processes from consuming all your machine's resources.
{/* TODO: Screenshot — A simple diagram showing your computer on the left, a Docker container in the middle (labeled "Open Terminal — isolated"), and an arrow showing that only the /home/user volume is shared. The rest of the host filesystem is blocked off. */}
:::warning Running without Docker
Without Docker (bare metal mode), the AI can run any command with your user's permissions — including deleting files, installing software, or accessing anything your account can access. Only use bare metal on your own personal machine for personal projects.
:::
---
## Always set a password
Without an API key, **anyone who can reach the port has full access** — they can run commands, read files, and control the terminal.
```bash
-e OPEN_TERMINAL_API_KEY=a-strong-password-here
```
For production, use a [config file](./configuration#config-file) or [Docker secrets](./configuration#docker-secrets) instead of putting the key on the command line.
{/* TODO: Screenshot — Example showing the docker logs command revealing an auto-generated API key, with a note saying "change this to your own strong password". */}
---
## Use admin connections (not user connections)
When connecting to Open WebUI, prefer the **admin-configured** approach:
| | Admin-configured | User-configured |
| :--- | :--- | :--- |
| API key visibility | Hidden on the server | Stored in the user's browser |
| Requests go through | Open WebUI's backend | Directly from the browser |
| Terminal network access needed from | Just the Open WebUI server | Every user's computer |
Admin-configured connections keep the API key out of users' browsers and let you control who has access.
{/* TODO: Screenshot — Admin settings showing the Open Terminal connection. The API key field shows dots (masked). A note points out that this key never reaches users' browsers. */}
---
## Limit resources
Prevent a runaway script from consuming all available CPU and memory:
```yaml title="docker-compose.yml"
deploy:
resources:
limits:
memory: 2G
cpus: "2.0"
```
If a process exceeds these limits, Docker throttles it (CPU) or kills it (memory). Your server stays healthy.
{/* TODO: Screenshot — Docker stats or htop inside the container showing CPU and memory usage within the configured limits. */}
---
## Network isolation
For the most secure setup, put Open Terminal on a **private Docker network** that only Open WebUI can reach:
```yaml title="docker-compose.yml"
services:
open-webui:
image: ghcr.io/open-webui/open-webui:latest
ports:
- "3000:8080"
networks:
- public
- internal
open-terminal:
image: ghcr.io/open-webui/open-terminal
# Notice: no ports exposed to the outside
networks:
- internal
networks:
public:
internal:
internal: true # No internet access from this network
```
This means:
- Open WebUI can reach Open Terminal at `http://open-terminal:8000`
- Open Terminal is **not accessible** from the internet
- Open Terminal **cannot make outbound internet requests**
{/* TODO: Screenshot — Network diagram showing the public network (internet → Open WebUI) and the internal network (Open WebUI → Open Terminal). The internal network has no path to the internet. */}
---
## Egress filtering
If Open Terminal needs *some* internet access (to install packages, for example), you can restrict it to specific domains:
```bash
-e OPEN_TERMINAL_ALLOWED_DOMAINS="pypi.org,github.com,*.npmjs.org"
```
Only these domains will be reachable. Everything else is blocked. This prevents:
- Unauthorized data leaving the container
- Downloading unexpected software
- Accessing internal services you didn't intend
{/* TODO: Screenshot — Terminal showing two curl commands: one to an allowed domain (succeeds) and one to a blocked domain (fails with "connection refused"). */}
---
## Docker socket warning
The Docker container can optionally access your host's Docker (to let the AI build images, run containers, etc.):
```bash
-v /var/run/docker.sock:/var/run/docker.sock
```
:::danger Only for trusted environments
Mounting the Docker socket gives the container **full control** over your host's Docker. This is effectively root access on your machine. Anyone with terminal access could:
- Run containers that mount your entire filesystem
- Access your host's network
- Manage every container on your machine
Only do this if you fully trust everyone who has access to the terminal.
:::
{/* TODO: Screenshot — A warning diagram showing the Docker socket as a direct bridge to the host, with arrows pointing to "can access host filesystem", "can access host network", "can manage all containers". */}
---
## Security checklist
| ✅ | Recommendation |
| :--- | :--- |
| ☐ | Use Docker, not bare metal |
| ☐ | Set a strong API key |
| ☐ | Use admin-configured connections |
| ☐ | Set memory and CPU limits |
| ☐ | Use network isolation (internal Docker network) |
| ☐ | Enable egress filtering if internet access isn't needed |
| ☐ | Don't mount the Docker socket unless necessary |
| ☐ | Use `slim` or `alpine` images if you don't need runtime package installs |
## Related
- [All configuration options →](./configuration)
- [Multi-user setup →](./multi-user)

117
docs/features/open-terminal/file-browser.md Normal file
View File

@@ -0,0 +1,117 @@
---
sidebar_position: 10
title: "File Browser"
---
# The File Browser
When Open Terminal is connected, a **file browser** appears in the sidebar of your chat. It works like the file explorer on your computer — you can browse folders, open files, upload things, and download results. Everything the AI creates shows up here automatically.
{/* TODO: Screenshot — The full Open WebUI interface with a chat conversation on the left and the file browser sidebar open on the right. The sidebar shows a directory tree with folders like /home/user/projects/, /home/user/data/, with files visible inside. */}
---
## Browsing
Click folders to navigate, and click files to preview them. A breadcrumb bar at the top shows where you are.
{/* TODO: Screenshot — File browser showing an expanded directory tree. The breadcrumb bar shows "/home/user/projects/my-app". Inside, folders like src/, tests/, and files like README.md, package.json are visible. */}
---
## Previewing files
Click any file to see a preview. Different file types display differently:
### Text and code
Source code and text files are shown with syntax highlighting and line numbers.
{/* TODO: Screenshot — File browser previewing a Python script (.py file). The code is syntax-highlighted with different colors for keywords, strings, and comments. Line numbers are visible on the left. */}
### PDFs
PDF documents render directly in the browser — you can read them without downloading.
{/* TODO: Screenshot — File browser previewing a multi-page PDF document. The page is readable with headers, paragraphs, and a table visible. */}
### Spreadsheets (CSV, TSV)
Data files render as **formatted tables** with headers and clean rows — much easier to read than raw comma-separated text.
{/* TODO: Screenshot — File browser previewing a CSV file rendered as a clean table. Column headers are bold, rows alternate in color for readability. The data shows something like names, dates, and amounts. */}
### Markdown
Markdown files show a **rendered preview** (with formatted headings, links, bold text) and a toggle to switch to raw source.
{/* TODO: Screenshot — File browser showing a Markdown file rendered with a heading, bullet points, a link, and bold text. A "Source" toggle button is visible in the corner. */}
### Images
Images display inline at a comfortable size.
{/* TODO: Screenshot — File browser previewing a chart.png file — a bar chart generated by the AI. The image is displayed at a readable size with the filename shown above. */}
---
## Uploading files
**Drag and drop** files from your computer directly onto the file browser to upload them. This is how you share data with the AI — drop a spreadsheet, a PDF, an image, or any file you want the AI to work with.
{/* TODO: Screenshot — A file being dragged over the file browser sidebar. A highlighted drop zone or "Drop files here" indicator is visible. */}
{/* TODO: Screenshot — The file browser after uploading, showing the new file in the directory listing with its name and size. */}
:::tip Upload to any folder
Navigate to the folder you want first, then drag and drop. The file uploads to whatever directory you're currently viewing.
:::
---
## Downloading files
Click the **download button** on any file to save it to your computer. This is how you get results back: after the AI generates a chart, creates a spreadsheet, processes an image, or writes a report, just download it.
{/* TODO: Screenshot — File browser with a file selected (e.g., report_summary.pdf). A download icon/button is clearly visible next to the filename. */}
---
## Editing files
Click the **edit icon** on any text file to open it in an editor. Make your changes and save. This is handy for quick fixes — editing a config value, correcting a typo, or tweaking something the AI generated.
{/* TODO: Screenshot — File browser in edit mode. A text file is open in an editable text area with the file's content visible. A "Save" button is at the top or bottom. */}
---
## Creating and deleting
You can create new files and folders, or delete things you don't need anymore, directly from the file browser.
{/* TODO: Screenshot — File browser showing a context menu or action bar with options: "New File", "New Folder", "Delete". */}
---
## Sharing files with the AI
Click the **attach** button on a file to send it directly into your chat. The AI can then reference that file's contents in its response — useful when you want to ask about a specific file.
{/* TODO: Screenshot — The attach button on a file in the file browser. After clicking, the file appears as an attachment in the chat input area at the bottom, ready to be sent with a message. */}
---
## Good to know
:::tip Files update automatically
When the AI creates or changes files, the file browser refreshes automatically. You don't need to manually reload.
:::
:::tip Remembers where you were
The file browser remembers which folder you were in, even when you switch between chats or terminals.
:::
:::tip Multiple terminals
If you have more than one terminal connected, switching between them in the dropdown updates the file browser to show that terminal's files.
:::
## More things to try
- **[Analyze documents & data →](./use-cases/file-analysis)** — drag in a spreadsheet or PDF and ask about it
- **[Run code from chat →](./use-cases/code-execution)** — the AI creates files you can see here
- **[Build & preview websites →](./use-cases/web-development)** — the files the AI creates appear in the browser

78
docs/features/open-terminal/index.md Normal file
View File

@@ -0,0 +1,78 @@
---
sidebar_position: 3
title: "Open Terminal"
---
# ⚡ Open Terminal
**Give your AI a real computer to work on.**
Open Terminal connects a sandboxed Linux environment to Open WebUI, allowing the AI to execute code, manage files, install packages, and return results directly in the chat.
{/* TODO: Screenshot — A chat conversation where a user asks "What's 2+2 in Python?" and the AI creates and runs a script, showing the result "4" inline. The file browser is visible on the right side of the screen. */}
---
## Capabilities
### Data analysis and reporting
Upload spreadsheets, CSVs, or databases. The AI reads the data, runs analysis scripts, and generates charts or reports.
{/* TODO: Screenshot — A user dragging an .xlsx file into the file browser sidebar. The AI responds with a text summary of the data and an embedded chart image showing expenses by category. */}
### Document search and extraction
Point the AI at a folder of PDFs, Word docs, or emails. It reads all of them and returns structured results — summaries, extracted fields, or cross-references.
{/* TODO: Screenshot — A chat where the user asks about the Johnson contract. The AI lists the files it found in a folder (contract_v2.docx, notes.pdf, invoice.xlsx) and provides a consolidated summary of relevant information from each. */}
### Web development with live preview
The AI builds HTML/CSS/JS projects, starts a preview server, and renders the result inside Open WebUI. Iterate by describing changes in chat.
{/* TODO: Screenshot — A chat on the left side of the screen. On the right, a live website preview panel shows a clean event landing page with a banner, date, and registration button. */}
### Software development
Clone repos, run test suites, debug failures, refactor code, and work with Git — all through natural language.
### File and system automation
Bulk rename, sort, deduplicate, convert, compress, and organize files. Manage disk space, schedule backups, process logs.
{/* TODO: Screenshot — A chat where the user asks "rename all the photos to include the date". The AI responds confirming "Renamed 43 files" with a before/after example: IMG_4521.jpg → 2025-03-15_IMG_4521.jpg. */}
---
## Key Features
| | |
| :--- | :--- |
| 🖥️ **Code execution** | Runs real commands and returns output |
| 📁 **File browser** | Browse, upload, download, and edit files in the sidebar |
| 📄 **Document reading** | PDF, Word, Excel, PowerPoint, RTF, EPUB, email |
| 🌐 **Website preview** | Live preview of web projects inside Open WebUI |
| 🔒 **Sandboxed** | Runs in an isolated container by default |
---
## Get Started
**[Installation →](./setup/installation)** · **[Connect to Open WebUI →](./setup/connecting)**
:::info Model requirements
Open Terminal requires models with **native function calling** support. Frontier models (GPT-5, Claude Sonnet 4, Gemini 3 Pro) handle complex multi-step tasks well. Smaller models may work for simple commands but can struggle with longer workflows. [Enable native function calling](./setup/connecting#8-enable-native-function-calling) on your model.
:::
---
## Use Cases
- **[Code execution](./use-cases/code-execution)** — write, run, and debug scripts
- **[Software development](./use-cases/software-development)** — repos, tests, debugging, refactoring, Git
- **[Document & data analysis](./use-cases/file-analysis)** — spreadsheets, PDFs, Word docs, emails
- **[Web development](./use-cases/web-development)** — build and preview websites
- **[System automation](./use-cases/system-automation)** — file management, backups, batch operations
- **[Advanced workflows](./use-cases/advanced-workflows)** — skills for data reports, research, code review, and more
- **[File browser](./file-browser)** — uploading, previewing, editing files

6
docs/features/open-terminal/setup/_category_.json Normal file
View File

@@ -0,0 +1,6 @@
{
"label": "Setup",
"position": 1,
"collapsible": true,
"collapsed": false
}

161
docs/features/open-terminal/setup/connecting.md Normal file
View File

@@ -0,0 +1,161 @@
---
sidebar_position: 2
title: "Connecting to Open WebUI"
---
# Connecting Open Terminal to Open WebUI
Open Terminal is [installed and running](./installation). This guide covers connecting it to Open WebUI.
---
## Recommended: Admin Panel
Recommended for all deployments, including single-user. The Admin Panel keeps the API key server-side.
### 1. Open the Admin Panel
Click your **name** at the bottom of the left sidebar to open the user menu, then click **Admin Panel**.
{/* TODO: Screenshot — Open WebUI sidebar with the user menu open at the bottom, showing "Settings", "Admin Panel", and "Sign Out" options. An arrow points to "Admin Panel". */}
### 2. Go to Settings → Integrations
In the Admin Panel, click **Settings** in the top nav, then click **Integrations**.
{/* TODO: Screenshot — Admin Panel with "Settings" selected in the top nav and "Integrations" visible in the sidebar. */}
### 3. Find the "Open Terminal" section
Scroll down until you see the **Open Terminal** section.
{/* TODO: Screenshot — The Admin Integrations page scrolled to show the "Open Terminal" section with a "+" button to add a connection. */}
:::warning Don't confuse it with "Tools"
Open Terminal has its **own section** under Integrations — don't add it under "External Tools" or "Tool Servers". Using the dedicated section gives you the built-in file browser and terminal sidebar.
:::
### 4. Click + and fill in the details
| Field | What to enter |
| :--- | :--- |
| **URL** | `http://localhost:8000` (or `http://open-terminal:8000` if using Docker Compose) |
| **API Key** | The password you chose during installation |
| **Auth Type** | Leave as `Bearer` (the default) |
{/* TODO: Screenshot — The "Add connection" form filled in with the URL "http://open-terminal:8000" and an API key. Auth type shows "Bearer" selected. */}
### 5. Save
Click **Save**. A green "Connected" indicator confirms the connection.
{/* TODO: Screenshot — The saved connection showing a green "Connected" indicator next to the Open Terminal entry. */}
### 6. (Optional) Restrict access to specific groups
Limit terminal access to specific user groups via the access control button.
{/* TODO: Screenshot — The Access Grants dropdown showing available user groups with checkboxes. */}
### 7. Select a terminal in chat
In the chat input area, click the **terminal button** (cloud icon ☁). Your admin-configured terminals appear under **System**. Select one to activate it for the conversation.
{/* TODO: Screenshot — The chat input bar with the Terminal button (cloud icon) highlighted. */}
{/* TODO: Screenshot — The Terminal dropdown open, showing a "System" section with the admin-configured terminal listed. A checkmark appears next to the selected terminal. */}
The selected terminal name appears next to the cloud icon. The AI can now execute commands, read files, and run code through it.
### 8. Enable native function calling
For the AI to use terminal tools reliably, you need to enable **native function calling** on your model:
1. Go to **Workspace → Models**
2. Click the edit button on the model you're using
3. Under **Capabilities**, enable **Native Function Calling** (also called "tool use")
4. Save
{/* TODO: Screenshot — The Model Editor showing the Capabilities section with "Native Function Calling" toggled on. */}
:::warning Without this, tools may not work
Native function calling lets the model invoke tools directly using the provider's built-in tool-calling format. Without it, Open WebUI falls back to prompt-based tool calling, which is less reliable and may not trigger terminal commands at all.
:::
:::tip Performance depends on the model
Not all models are equally capable with tools. Frontier models (GPT-5, Claude Sonnet 4, Gemini 3 Pro) handle multi-step terminal workflows well. Smaller or older models may struggle with complex tasks, fail to invoke tools, or produce malformed tool calls. If results are poor, try a more capable model.
:::
### 9. Try it out
Ask your AI something like:
> "What operating system are you running on?"
The AI should use Open Terminal to run a command and tell you the answer.
{/* TODO: Screenshot — The AI responding to "What operating system are you running on?" by executing a command and showing output like "Linux 5.15, Debian 12 (bookworm)". */}
:::tip Pre-configure via environment variable
For Docker deployments, you can configure terminal connections automatically using the `TERMINAL_SERVER_CONNECTIONS` environment variable — useful when you want everything set up at startup without manual steps.
:::
---
## Personal Settings (testing only)
:::caution Not recommended for regular use
Adding a terminal connection via personal Settings sends the API key to your browser and routes requests directly from it. This is fine for **quick testing**, but for anything beyond that, use Admin Settings instead — it's more secure and works for all users automatically.
:::
If you need to test a connection without admin access, you can add one from **Settings → Integrations → Open Terminal**. The same URL and API key fields apply.
---
## Troubleshooting
### "Connection failed" or timeout
This almost always means Open WebUI can't reach Open Terminal over the network. What URL to use depends on your setup:
| Your setup | URL to use |
| :--- | :--- |
| Docker Compose (recommended) | `http://open-terminal:8000` |
| Separate Docker containers | `http://host.docker.internal:8000` |
| Both on same machine, no Docker | `http://localhost:8000` |
| Open Terminal on another machine | `http://that-machines-ip:8000` |
{/* TODO: Screenshot — A simple diagram showing Open WebUI and Open Terminal as two boxes, with an arrow between them labeled with the URL. Shows correct URLs for Docker Compose (service name) vs separate containers (host.docker.internal). */}
:::tip Quick check
Run this command to see if Open WebUI can reach Open Terminal:
```bash
docker exec open-webui curl -s http://open-terminal:8000/health
```
If it prints `{"status": "ok"}`, the connection works. If it errors, the containers can't see each other.
:::
### Terminal shows up but AI doesn't use it
Make sure:
- The toggle switch next to the connection is **turned on**
- You've **refreshed the page** after adding the connection
- Your model supports tool calling (most modern models do)
### Wrong API key
If you see "unauthorized" or "invalid key":
- Double-check the key matches what you set during installation
- If you forgot it, run `docker logs open-terminal` and look for the `API key:` line
## Next steps
- **[Code execution](../use-cases/code-execution)**
- **[Document & data analysis](../use-cases/file-analysis)**
- **[Software development](../use-cases/software-development)**
- **[File browser](../file-browser)**

145
docs/features/open-terminal/setup/installation.mdx Normal file
View File

@@ -0,0 +1,145 @@
---
sidebar_position: 1
title: "Installation"
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Installation
<Tabs>
<TabItem value="docker" label="Docker" default>
Runs Open Terminal in an isolated container. The AI operates in a sandbox — nothing affects your host system.
Requires [Docker](https://www.docker.com/products/docker-desktop/).
```bash
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.
{/* TODO: Screenshot — Terminal showing the docker run command with Docker pulling the image. */}
<details>
<summary><b>Command breakdown</b></summary>
| 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 |
</details>
#### Verify
Open `http://localhost:8000/docs` in your browser. You should see the Open Terminal API page.
:::tip Auto-generated API key
If no API key was set, one is generated automatically. Find it with:
```bash
docker logs open-terminal
```
:::
</TabItem>
<TabItem value="bare-metal" label="Bare Metal">
Runs Open Terminal directly on your machine. The AI has access to your real filesystem, installed tools, and environment.
:::warning
The AI can do anything your user account can do, including modifying and deleting files.
:::
**Option A — Run without installing:**
```bash
uvx open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key
```
Downloads and runs via [uv](https://docs.astral.sh/uv/) with no permanent installation.
**Option B — Install with pip:**
```bash
pip install open-terminal
open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key
```
{/* TODO: Screenshot — Terminal showing Open Terminal starting up with server address and API key. */}
#### Working directory
Open Terminal serves files from the current directory. To scope it to a specific project:
```bash
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](https://github.com/andfoy/pywinpty). Full PowerShell support with colored output and interactive programs.
</TabItem>
<TabItem value="compose" label="Docker Compose">
If Open WebUI already runs via Docker Compose, add Open Terminal to the same file:
```yaml title="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:
```
```bash
docker compose up -d
```
{/* TODO: Screenshot — Terminal showing docker compose up -d with both containers starting. */}
:::tip 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.
:::
</TabItem>
</Tabs>
---
## Next step
[**Connect to Open WebUI →**](./connecting)

6
docs/features/open-terminal/use-cases/_category_.json Normal file
View File

@@ -0,0 +1,6 @@
{
"label": "Use Cases",
"position": 5,
"collapsible": true,
"collapsed": false
}

6
docs/features/open-terminal/use-cases/advanced-workflows/_category_.json Normal file
View File

@@ -0,0 +1,6 @@
{
"label": "Advanced Workflows",
"position": 10,
"collapsible": true,
"collapsed": true
}

53
docs/features/open-terminal/use-cases/advanced-workflows/app-builder.md Normal file
View File

@@ -0,0 +1,53 @@
---
sidebar_position: 9
title: "App Builder"
---
# 🏗️ Build a Complete Application
Describe what you want and get a working app with frontend, backend, and database.
> **You:** $App Builder <br/>
> Build me an inventory tracker. I need to add products with name, quantity, and price. Show total value and low-stock alerts.
## What the AI does
1. Designs the database schema
2. Builds a Python API (Flask) with CRUD endpoints
3. Creates a polished frontend with dashboard, charts, and search
4. Seeds it with sample data
5. Starts the server and tests every endpoint
6. The port preview shows the running app
{/* TODO: Screenshot — The port preview showing a polished dashboard: summary cards (Total Items: 156, Total Value: $24,350, Low Stock: 3), a bar chart by category, and a searchable product table. */}
{/* TODO: Screenshot — File browser showing the project structure: app.py, database.py, templates/, static/. */}
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: app-builder
description: Builds complete web applications with frontend, backend, and database
---
## Full-Stack Application Builder
When building a web app:
1. **Clarify requirements**: What data is managed? What should the UI show?
2. **Design the database first**: Use SQLite with proper schema
3. **Build the API** with Flask or FastAPI: CRUD, search, filtering, error handling
4. **Build a polished frontend**:
- Modern CSS (not a skeleton — make it look demo-ready)
- Dashboard with key metrics and charts (Chart.js)
- Responsive tables with search
- Forms for data entry
5. **Seed with realistic sample data** so the demo looks good
6. **Start the server** and test every endpoint with curl
7. **Verify the full flow**: create, read, update, delete, search
Build something polished enough to demo, not a wireframe.
```

60
docs/features/open-terminal/use-cases/advanced-workflows/code-review.md Normal file
View File

@@ -0,0 +1,60 @@
---
sidebar_position: 10
title: "Code Review"
---
# 🔍 Automated Code Review
Point the AI at a pull request, a branch diff, or a file, and get a detailed code review — security issues, performance problems, style violations, and suggestions for improvement.
> **You:** $Code Reviewer <br/>
> Review the changes in the `feature/auth-refactor` branch compared to `main`.
## What the AI does
1. Runs `git diff main..feature/auth-refactor` to see all changes
2. Reads each modified file in full context (not just the diff — it understands surrounding code)
3. Categorizes findings: security, performance, correctness, style, documentation
4. Prioritizes issues from critical to nitpick
5. Suggests specific fixes with code snippets
6. Saves a structured review report
{/* TODO: Screenshot — Chat showing the AI reviewing a branch diff. The response lists findings organized by severity: "🔴 Critical: SQL injection in user_query() — use parameterized queries. 🟡 Warning: N+1 query in get_orders(). 🔵 Suggestion: Extract validation logic into a helper." */}
{/* TODO: Screenshot — The generated review report in the file browser: a markdown file with sections for each file reviewed, findings with line numbers, and suggested fixes with code blocks. */}
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: code-reviewer
description: Reviews code changes for security, performance, correctness, and style issues
---
## Code Review
When asked to review code:
1. **Get the diff**: Use `git diff`, `git log`, or read the specified files to understand what changed
2. **Read full context**: Don't just look at changed lines — read the entire file to understand the surrounding logic, imports, and how the changes fit in
3. **Check for these categories**:
- **Security**: SQL injection, XSS, hardcoded credentials, missing auth checks, unsafe deserialization, path traversal
- **Correctness**: Logic errors, off-by-one bugs, unhandled edge cases, race conditions, missing error handling
- **Performance**: N+1 queries, unnecessary loops, missing indexes, large memory allocations, blocking calls in async code
- **Style & maintainability**: Inconsistent naming, overly complex functions, missing docstrings, dead code, magic numbers
- **Testing**: Missing test coverage for new code paths, edge cases not tested
4. **Prioritize findings**:
- 🔴 Critical: Must fix before merge (security, data loss, crashes)
- 🟡 Warning: Should fix (performance, correctness edge cases)
- 🔵 Suggestion: Nice to have (style, refactoring opportunities)
- 💬 Nitpick: Optional (naming preferences, formatting)
5. **For each finding**:
- Cite the exact file and line number
- Explain WHY it's a problem (not just what's wrong)
- Provide a concrete fix with a code snippet
6. **Write a summary**: Overall assessment, number of findings by severity, recommendation (approve / request changes)
Be thorough but fair. Acknowledge good patterns and well-written code, not just problems.
```

50
docs/features/open-terminal/use-cases/advanced-workflows/competitive-analysis.md Normal file
View File

@@ -0,0 +1,50 @@
---
sidebar_position: 8
title: "Competitive Analysis"
---
# 🌐 Competitive Analysis
Scrape competitor pricing pages and build a comparison.
> **You:** $Competitive Analyst <br/>
> Check these 5 competitor websites and compare their pricing plans to ours.
## What the AI does
1. Fetches each competitor's pricing page
2. Parses HTML to extract plan names, prices, and feature lists
3. Normalizes pricing (monthly vs. annual)
4. Builds a comparison spreadsheet and highlights key differences
5. Writes strategic observations
{/* TODO: Screenshot — File browser previewing competitor_pricing.csv as a table: rows for features, columns for competitors, with prices and ✓/✗ marks. */}
{/* TODO: Screenshot — The summary: "Key findings: Competitor A has a free tier, Competitor C is 30% cheaper on Pro, but we're the only one with 24/7 support included." */}
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: competitive-analyst
description: Scrapes competitor websites and builds pricing/feature comparison tables
---
## Competitive Analysis
When analyzing competitors:
1. **Use curl** to fetch pages. Set a user-agent header, handle redirects
2. **Parse HTML** with beautifulsoup4 to extract:
- Plan names and prices
- Feature lists
- Promotional offers (free trials, discounts)
3. **Normalize data**: Convert annual to monthly prices where needed
4. **Create a comparison CSV** with competitors as columns and features as rows
5. **Write strategic observations**: Where are we cheaper/more expensive? What features do competitors have that we don't?
6. **Note the date** (pricing changes frequently)
Present findings as actionable insights, not just raw data.
```

53
docs/features/open-terminal/use-cases/advanced-workflows/data-reports.md Normal file
View File

@@ -0,0 +1,53 @@
---
sidebar_position: 1
title: "Data Reports"
---
# 📊 Turn Raw Data into a Polished Report
Upload messy data, and the AI cleans it, analyzes it, builds charts, and produces a downloadable PDF report.
> **You:** $Data Report Generator <br/>
> *(drag-drop `survey_responses.csv` into the file browser)* <br/>
> Analyze this survey data and create a report for our team meeting.
## What the AI does
1. Reads the CSV and identifies data quality issues
2. Cleans the data (fixes formatting, removes duplicates, handles missing values)
3. Computes statistics — response rates, averages, distributions
4. Generates charts (bar charts, pie charts, trend lines)
5. Assembles everything into a formatted PDF with title page, summary, charts, and data tables
6. Saves the PDF to the file browser for download
{/* TODO: Screenshot — File browser showing three outputs: survey_cleaned.csv, charts/ folder with .png files, and survey_report.pdf. The PDF is previewed showing a professional title page. */}
{/* TODO: Screenshot — A page inside the generated PDF showing a bar chart, key findings, and a summary table. */}
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: data-report-generator
description: Analyzes data files and creates professional PDF reports with charts and summaries
---
## Data Analysis & Reporting
When asked to analyze data:
1. **Profile the data first**: Read the file and report row count, column types, missing values, duplicates
2. **Clean the data**: Standardize formats, fill or flag missing values, remove exact duplicates. Save the cleaned version as a separate file
3. **Find the story**: Identify distributions, outliers, correlations, and trends. Focus on the 3-5 most interesting findings
4. **Create charts**: Use matplotlib with a consistent color palette. Label all axes clearly. Save each chart as a PNG in a /charts directory
5. **Build the PDF**: Use reportlab or weasyprint to create a report with:
- Title page with report name and date
- Executive summary (3-5 bullet points)
- One section per major finding with chart and interpretation
- Data tables in an appendix
6. **Save everything** to a /reports directory
Always explain findings in plain English, not statistical jargon.
```

95
docs/features/open-terminal/use-cases/advanced-workflows/database-analysis.md Normal file
View File

@@ -0,0 +1,95 @@
---
sidebar_position: 2
title: "Database Analysis"
---
# 🗄️ Connect to a Database and Analyze It
Connect to your PostgreSQL, MySQL, or SQLite database directly and let the AI explore the schema, run queries, and produce insights — all without writing SQL yourself.
> **You:** $Database Analyst <br/>
> Connect to my PostgreSQL database at `db.example.com` and analyze the `orders` table. What are our top-selling products this quarter? Any trends I should know about?
## What the AI does
1. Installs the database driver if needed (`pip install psycopg2-binary` or `pymysql`)
2. Connects to the database using your credentials
3. Explores the schema — lists tables, columns, relationships
4. Writes and runs SQL queries to answer your question
5. Pulls results into pandas for analysis
6. Generates charts (revenue trends, top products, regional breakdowns)
7. Saves everything as a report
{/* TODO: Screenshot — Chat showing the AI connecting to a PostgreSQL database, listing tables, and then running a query. Results show a formatted table with product names, quantities sold, and revenue. */}
{/* TODO: Screenshot — Charts generated from the database query: a bar chart of top 10 products by revenue, a line chart showing monthly order trends, and a pie chart of sales by region. */}
:::tip Keep credentials safe
Pass database credentials as environment variables when starting Open Terminal, or store them in a `.env` file in the container. Never paste passwords directly in chat — they get saved in chat history. Example:
```bash
docker run -d --name open-terminal \
-e DB_HOST=db.example.com \
-e DB_USER=analyst \
-e DB_PASS=your-password \
-e DB_NAME=production \
ghcr.io/open-webui/open-terminal
```
Then tell the skill to read from environment variables.
:::
## Supported databases
| Database | Python driver | Install command |
| :--- | :--- | :--- |
| PostgreSQL | psycopg2 | `pip install psycopg2-binary` |
| MySQL / MariaDB | pymysql | `pip install pymysql` |
| SQLite | sqlite3 | Built-in (no install needed) |
| Microsoft SQL Server | pymssql | `pip install pymssql` |
| MongoDB | pymongo | `pip install pymongo` |
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: database-analyst
description: Connects to SQL databases, explores schemas, runs queries, and creates analysis reports
---
## Database Analysis
When asked to analyze a database:
1. **Connect safely**: Read credentials from environment variables (DB_HOST, DB_USER, DB_PASS, DB_NAME). Never hardcode passwords. Use `psycopg2` for PostgreSQL, `pymysql` for MySQL, `sqlite3` for SQLite
2. **Explore the schema first**:
- List all tables and their row counts
- Show column names, types, and sample values for relevant tables
- Identify primary keys and foreign key relationships
- Present the schema summary before running analysis queries
3. **Write efficient SQL**:
- Use appropriate JOINs (not subqueries) where possible
- Add LIMIT clauses to prevent accidentally pulling millions of rows
- Use aggregate functions (COUNT, SUM, AVG, GROUP BY) for summaries
- Always include ORDER BY for readability
4. **Analyze results in Python**:
- Load query results into a pandas DataFrame
- Compute additional metrics: growth rates, percentages, rankings
- Identify trends, anomalies, and notable patterns
5. **Create visualizations**:
- Use matplotlib with clear labels and consistent styling
- Time series → line charts
- Rankings → horizontal bar charts
- Proportions → pie or donut charts
- Save each chart as a PNG
6. **Produce a report** with:
- Schema overview (what tables exist and how they relate)
- Key findings with supporting data
- Charts embedded in context
- The actual SQL queries used (so the user can re-run them)
7. **Close the connection** when done
Always show the SQL query before showing results so the user can verify it's correct.
```

54
docs/features/open-terminal/use-cases/advanced-workflows/document-comparison.md Normal file
View File

@@ -0,0 +1,54 @@
---
sidebar_position: 5
title: "Document Comparison"
---
# 📑 Compare Two Versions of a Document
Upload two versions of a contract or proposal and get a clear summary of what changed.
> **You:** $Document Comparator <br/>
> *(upload contract_v1.docx and contract_v2.docx)* <br/>
> Compare these two versions. Focus on payment terms and liability changes.
## What the AI does
1. Reads both documents (Open Terminal handles .docx natively)
2. Computes a text diff at the paragraph/sentence level
3. Categorizes changes: formatting-only, minor wording, substantive changes
4. Highlights the specific areas you asked about (payment terms, liability)
5. Creates a comparison report with side-by-side views of key changes
{/* TODO: Screenshot — Chat showing the AI's analysis: "Found 14 changes. 3 substantive:" followed by a highlighted comparison showing a payment term change ("Net 30" → "Net 60") with surrounding context. */}
{/* TODO: Screenshot — A generated diff report showing additions in green and removals in red, with change categories labeled. */}
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: document-comparator
description: Compares two document versions and highlights meaningful changes
---
## Document Comparison
When asked to compare documents:
1. **Read both versions** and extract full text
2. **Compute differences** at the paragraph or sentence level using Python's difflib
3. **Categorize each change**:
- Formatting only (spacing, capitalization)
- Minor wording (synonyms, clarifications)
- Substantive (numbers, dates, terms, obligations, new/removed clauses)
4. **If the user mentions areas of interest** (e.g., "payment terms"), search both documents for those sections and present a focused comparison
5. **Create a report** with:
- Summary of changes by category
- Substantive changes with full surrounding context
- Side-by-side view of key sections
6. **Save** as Markdown and HTML
Always flag changes affecting financial terms, legal obligations, or deadlines.
```

55
docs/features/open-terminal/use-cases/advanced-workflows/email-processing.md Normal file
View File

@@ -0,0 +1,55 @@
---
sidebar_position: 4
title: "Email Processing"
---
# 📧 Process a Folder of Emails
Drop a batch of `.eml` files and get a structured spreadsheet with action items and deadlines.
> **You:** $Email Processor <br/>
> Go through the /project-emails folder and extract all action items and deadlines.
## What the AI does
1. Lists all `.eml` files in the folder
2. Reads each email: headers (from, to, subject, date) and body
3. Identifies action items, deadlines, decisions, and open questions
4. Creates a CSV with structured columns
5. Flags overdue items
6. Writes a summary of the most critical emails
{/* TODO: Screenshot — Chat showing the AI processing 45 email files and producing a summary. File browser previews email_actions.csv as a formatted table with Date, From, Subject, Action Item, Deadline, Status columns. */}
{/* TODO: Screenshot — The summary output listing the 5 most critical action items with their deadlines and which email they came from. */}
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: email-processor
description: Reads .eml email files and extracts action items, deadlines, and key decisions
---
## Email Processing
When asked to process email files:
1. **List all .eml files** in the specified directory
2. **For each email, extract**:
- Headers: From, To, CC, Date, Subject
- Body: prefer plain text, strip HTML tags as fallback
- Attachment filenames (if any)
3. **Analyze each body for**:
- Action items (tasks assigned to someone)
- Deadlines or due dates
- Decisions made
- Questions that need answers
4. **Create a CSV** with columns: Date, From, Subject, Action Items, Deadline, Priority
5. **Sort by date** and flag anything overdue
6. **Write a summary** highlighting the 5 most critical items
Preserve original email context so findings are traceable.
```

55
docs/features/open-terminal/use-cases/advanced-workflows/finance-dashboard.md Normal file
View File

@@ -0,0 +1,55 @@
---
sidebar_position: 6
title: "Finance Dashboard"
---
# 💰 Personal Finance Dashboard
Upload bank statements and get a spending analysis with charts.
> **You:** $Finance Analyzer <br/>
> *(drop 3 CSV bank statements into the file browser)* <br/>
> Analyze my spending over the last 3 months. Where is my money going?
## What the AI does
1. Reads all CSV files and normalizes the different formats
2. Categorizes transactions: groceries, dining, subscriptions, transport, etc.
3. Identifies recurring charges and flags anything unusual
4. Creates a dashboard with monthly trends, category breakdown, and top merchants
5. Flags anomalies: unusually large charges, new subscriptions, possible duplicates
{/* TODO: Screenshot — File browser previewing a generated spending_dashboard.html: pie chart of spending categories, bar chart of monthly trends, table of top merchants. */}
{/* TODO: Screenshot — The anomaly report: "3 things to check: $450 charge to 'TECHSTORE' on Feb 15 (unusually large), new $14.99/month subscription to 'StreamPlus', possible duplicate $89.00 charge on March 3 and 5." */}
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: finance-analyzer
description: Analyzes bank statements and creates spending reports with charts
---
## Financial Analysis
When analyzing bank statements:
1. **Read all files** and normalize columns (date, description, amount, type). Handle different CSV formats (detect delimiters, date formats, debit/credit conventions)
2. **Categorize transactions** using keyword matching:
- Groceries: walmart, costco, trader joe, whole foods
- Dining: restaurant, cafe, doordash, uber eats
- Subscriptions: netflix, spotify, recurring monthly charges
- Transport: gas, uber, lyft, parking
- (Add more categories as needed)
3. **Generate charts**:
- Monthly spending trend (line chart)
- Category breakdown (pie chart)
- Top 10 merchants (bar chart)
4. **Detect anomalies**: charges >2x average for that merchant, new recurring charges, possible duplicates (same amount within 3 days)
5. **Create an HTML dashboard** viewable in the file browser
Use proper currency formatting and round to 2 decimal places.
```

48
docs/features/open-terminal/use-cases/advanced-workflows/image-processing.md Normal file
View File

@@ -0,0 +1,48 @@
---
sidebar_position: 7
title: "Image Processing"
---
# 📸 Batch Process Images
Resize, watermark, convert, or generate thumbnails for a folder of images.
> **You:** $Image Processor <br/>
> I have product photos in /photos. Resize them to 800x800, add a watermark, and make thumbnails.
## What the AI does
1. Processes all images with PIL/Pillow (pre-installed)
2. Creates full-size versions with watermark
3. Creates thumbnails at the requested size
4. Generates a contact sheet (grid of all thumbnails)
5. Reports file count and size savings
{/* TODO: Screenshot — File browser showing three output folders: processed/ (watermarked), thumbnails/ (200x200), plus a contact_sheet.png previewed as a grid of product images. */}
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: image-processor
description: Batch processes images - resize, watermark, convert, and generate thumbnails
---
## Image Processing
When processing images:
1. **Survey first**: Count files, check formats, note total size
2. **Process one file as a test**: Show the result before processing the rest
3. **Use Pillow (PIL)**:
- Resize with aspect ratio preservation (use thumbnail or fit)
- Watermarks: semi-transparent text in lower-right corner
- Format conversion: handle RGBA→RGB for PNG→JPEG
4. **Organize output** into clear subdirectories (processed/, thumbnails/, etc.)
5. **Generate a summary**: files processed, size before/after
6. **For large batches**, report progress: "Processed 25/50..."
Always preview the first result before batch-processing.
```

124
docs/features/open-terminal/use-cases/advanced-workflows/index.md Normal file
View File

@@ -0,0 +1,124 @@
---
sidebar_position: 0
title: "Advanced Workflows"
---
# Advanced Workflows with Skills
These workflows combine multiple Open Terminal capabilities into powerful multi-step pipelines. Each one includes a **Skill** — a reusable set of instructions you create in Open WebUI that tells the AI exactly how to approach a specific type of task.
---
## What are Skills?
A **Skill** is a reusable set of markdown instructions that you save in Open WebUI. When you invoke a skill, its instructions are injected into the AI's system prompt for that conversation, making the AI an expert at that specific task.
Think of it like giving someone a detailed SOP (standard operating procedure) before asking them to do a job — except the AI follows it perfectly every time.
### Creating a Skill
1. Go to **Workspace** in the left sidebar
2. Click **Skills**
3. Click **Create** (+ button)
4. Give it a **name** (e.g., "Data Report Generator") and a **description**
5. Write the instructions in markdown in the **content area**
6. Click **Save & Create**
{/* TODO: Screenshot — The Workspace → Skills page showing a list of existing skills (e.g., "Data Report Generator", "Research Assistant", "Email Processor"). The Create button is visible in the top-right corner. */}
{/* TODO: Screenshot — The Skill Editor showing a skill being created. The name field says "Data Report Generator", the description says "Analyzes data files and creates professional PDF reports". The content area shows markdown instructions with numbered steps. */}
:::tip Frontmatter shortcut
If your skill instructions start with YAML frontmatter, the name and description fields auto-populate:
```markdown
---
name: data-report-generator
description: Analyzes data files and creates professional PDF reports
---
## Instructions
When asked to analyze data:
1. First, read the file...
```
:::
### Using a Skill
There are two ways to use a skill:
**Option 1: Mention it in chat (`$`)**
Type `$` in the chat input, then search for your skill by name. Select it, and the AI receives the **full instructions** for that conversation. This is best when you want to explicitly tell the AI to follow a specific skill right now.
{/* TODO: Screenshot — The chat input showing the $ mention dropdown. The user has typed "$Data" and the autocomplete shows "Data Report Generator" as a suggestion, with its description visible. */}
{/* TODO: Screenshot — A chat where the user has $mentioned a skill and then asked a question. The skill name appears as a tag in the message. The AI's response clearly follows the skill's structured approach. */}
**Option 2: Attach it to a Model (auto-discovery)**
This is the more powerful option. Go to **Workspace → Models → Edit** and check the skill under the **Skills** section. Now the AI **automatically discovers and uses it when relevant** — you don't need to mention the skill at all.
Here's how it works behind the scenes:
1. The AI receives a manifest listing each attached skill's **name and description** (not the full instructions — that would waste context)
2. When your request matches a skill's description, the AI **autonomously calls a built-in `view_skill` tool** to load the full instructions
3. The AI then follows those instructions to handle your request
This means you can attach a "Data Report Generator" skill to your model, and any time you drop a CSV and say "analyze this," the AI will automatically load and follow the reporting instructions — without you needing to remember the skill exists.
{/* TODO: Screenshot — The Model Editor showing the Skills section with checkboxes. "Data Report Generator" and "Research Assistant" are checked. A note says "To select skills here, add them to the Skills workspace first." */}
:::tip Attach multiple skills for a Swiss-army-knife model
Attach several skills to a single model and it becomes a multi-purpose expert. Drop a spreadsheet → it loads the data analysis skill. Ask "research EV batteries" → it loads the research skill. Build a landing page → it loads the web dev skill. All automatically.
:::
### Sharing Skills
Skills have access controls. You can:
- Keep them **private** (only you can use them)
- Share with **specific users or groups**
- Make them **public** (available to everyone on your instance)
Click the **Access** button in the skill editor to configure who can use your skill.
{/* TODO: Screenshot — The Access Control modal for a skill, showing options to set visibility: Private, specific users/groups, or Public. */}
---
## Workflow Library
Each page below is a complete workflow with a copy-pasteable skill:
| Workflow | What it does |
| :--- | :--- |
| **[Data Reports](./data-reports)** | Turn messy CSVs into polished PDF reports with charts |
| **[Database Analysis](./database-analysis)** | Connect to PostgreSQL/MySQL/SQLite, run queries, produce insights |
| **[Research Assistant](./research-assistant)** | Gather web sources and write structured briefings |
| **[Email Processing](./email-processing)** | Extract action items and deadlines from .eml files |
| **[Document Comparison](./document-comparison)** | Diff two versions of a contract or proposal |
| **[Finance Dashboard](./finance-dashboard)** | Analyze bank statements and chart spending |
| **[Image Processing](./image-processing)** | Batch resize, watermark, and convert images |
| **[Competitive Analysis](./competitive-analysis)** | Scrape competitor pricing and build comparisons |
| **[App Builder](./app-builder)** | Build a complete web app from a description |
| **[Code Review](./code-review)** | Review code changes for security, performance, and style issues |
---
## Tips for Writing Great Skills
### Keep instructions specific
Bad: "Analyze the data"
Good: "Read the file, count rows, identify columns, check for missing values, then compute averages per category"
### Number your steps
LLMs follow numbered instructions more reliably than prose paragraphs.
### Include output expectations
Tell the skill what the final deliverable should look like: "Create a PDF with a title page and 3 sections" is better than "make a report."
### Test and iterate
Create the skill, try it on a real task, and refine the instructions based on what the AI gets right or wrong.
### Combine with Open Terminal capabilities
The real power comes from combining skills with Open Terminal's tools: file reading, code execution, web preview, and the file browser. A skill that says "read the spreadsheet, generate a chart with Python, and save it as a PNG" leverages all of these.

54
docs/features/open-terminal/use-cases/advanced-workflows/research-assistant.md Normal file
View File

@@ -0,0 +1,54 @@
---
sidebar_position: 3
title: "Research Assistant"
---
# 🔍 Research and Summarize Any Topic
Give the AI a question, and it gathers information from the web, organizes it, and writes a structured briefing.
> **You:** $Research Assistant <br/>
> What's the current state of solid-state batteries? Who are the key players and what's the timeline for commercialization?
## What the AI does
1. Uses `curl` to fetch content from relevant tech news sites, company pages, and articles
2. Parses HTML to extract the useful text
3. Cross-references facts across multiple sources
4. Creates a structured Markdown briefing with sections, source citations, and comparison tables
5. Saves as both Markdown and PDF
{/* TODO: Screenshot — Chat showing the AI gathering information from 6+ sources and producing a structured briefing document. The file browser shows research_briefing.md being previewed with headers, bullet points, and a comparison table. */}
{/* TODO: Screenshot — The briefing document showing an executive summary, a comparison table of key companies and their technology approaches, and a source list with URLs. */}
## Skill content
Copy this into **Workspace → Skills → Create**:
```markdown
---
name: research-assistant
description: Researches topics from the web and creates structured briefing documents
---
## Research Assistant
When asked to research a topic:
1. **Plan first**: Identify 3-5 angles to investigate
2. **Gather information**: Use curl to fetch content from authoritative sources. Parse HTML with beautifulsoup4 to extract text
3. **For each source, note**:
- Key claims and data points
- Publication date
- Source authority/reliability
4. **Organize into a document**:
- Executive summary (3 sentences)
- Findings by theme
- Comparison tables where helpful
- Source list with URLs
5. **Flag conflicts**: Note where sources disagree
6. **Save** as Markdown and optionally PDF
Clearly distinguish facts from sources vs. your own analysis.
```

94
docs/features/open-terminal/use-cases/code-execution.md Normal file
View File

@@ -0,0 +1,94 @@
---
sidebar_position: 1
title: "Code Execution"
---
# Code Execution
Open Terminal allows the AI to write, execute, and debug code in real time. It handles the full cycle — writing the script, running it, reading errors, and iterating until the result is correct.
---
## Data visualization
> **You:** Create a chart showing the top 10 most populated countries.
The AI writes a Python script, executes it, and saves the output. Results are available in the file browser.
{/* TODO: Screenshot — Chat showing the AI responding with "I'll create a bar chart of the top 10 countries by population." The AI creates and runs a script. Below, the output shows "Chart saved to population_chart.png". */}
{/* TODO: Screenshot — The file browser previewing the generated population_chart.png — a clean bar chart with country names and populations. */}
---
## Downloading and processing files
> **You:** Download the images from this webpage and sort them by size.
The AI installs required packages, writes the script, downloads files, and organizes them:
{/* TODO: Screenshot — Chat showing the AI installing the requests library, running a download script, and reporting: "Downloaded 15 images. Sorted into 3 folders: small (under 100KB), medium (100KB–1MB), large (over 1MB)." */}
{/* TODO: Screenshot — File browser showing the three folders (small/, medium/, large/) with images sorted inside each. */}
:::tip Automatic dependency installation
In Docker mode, the AI can install packages as needed. If a task requires a library that isn't pre-installed, it installs it automatically before proceeding.
:::
---
## Self-correcting errors
When code fails, the AI reads the error output and adjusts:
> **You:** Scrape all the article titles from this news website.
The AI writes a scraper, hits an unexpected page layout, reads the `AttributeError` traceback, adjusts the CSS selectors, and re-runs successfully.
{/* TODO: Screenshot — Chat showing the AI's first attempt failing with an error: "AttributeError: 'NoneType' object has no attribute 'text'". The AI responds: "The page structure is different than expected — the titles are inside <h2> tags, not <h1>. Let me adjust..." Then it runs the fixed version successfully, listing 20 article titles. */}
---
## Multi-step project scaffolding
> **You:** Create a to-do list app with a web interface and a database.
The AI:
1. Creates project files (HTML, CSS, JavaScript, Python backend)
2. Installs dependencies
3. Sets up the database
4. Starts the server
5. Verifies the result in the web preview
{/* TODO: Screenshot — File browser showing a complete project structure: app.py, templates/ folder with HTML files, static/ folder with CSS, requirements.txt. */}
{/* TODO: Screenshot — The web preview panel showing the running to-do app with a text input, an "Add" button, and a list of example tasks with checkboxes. */}
---
## System queries
> **You:** Check what's using the most disk space.
{/* TODO: Screenshot — Chat showing the AI running a disk usage command and interpreting the results: "The /home/user/data directory is using 2.3 GB, mostly from log files. The largest single file is access.log at 800 MB. Would you like me to clean up old logs?" */}
---
## Available languages
| Language | Status |
| :--- | :--- |
| Python | Pre-installed |
| JavaScript (Node.js) | Pre-installed |
| Bash | Always available |
| Ruby | Pre-installed |
| C / C++ | Compiler pre-installed |
Additional languages (Rust, Go, Java, etc.) can be installed on the fly.
## Related
- **[Software development →](./software-development)** — repos, tests, debugging, refactoring
- **[Document & data analysis →](./file-analysis)** — spreadsheets, PDFs, Word docs
- **[Web development →](./web-development)** — build and preview websites
- **[System automation →](./system-automation)** — file management, backups, batch operations

100
docs/features/open-terminal/use-cases/file-analysis.md Normal file
View File

@@ -0,0 +1,100 @@
---
sidebar_position: 2
title: "Analyze Documents & Data"
---
# Analyze Your Documents and Data
Got a pile of spreadsheets, PDFs, Word documents, or emails you need to make sense of? Drop them into the file browser and let the AI read them for you. Open Terminal can open and understand all of these formats — no special setup needed.
## What file types can it read?
| Type | Formats |
| :--- | :--- |
| **Spreadsheets** | Excel (.xlsx, .xls), OpenDocument (.ods), CSV |
| **Documents** | Word (.docx), OpenDocument (.odt), Rich Text (.rtf), PDF |
| **Presentations** | PowerPoint (.pptx), OpenDocument (.odp) |
| **Other** | Email (.eml), E-books (.epub), plain text, HTML, Markdown, JSON, XML |
The AI can read all of these directly — it doesn't need to upload them to any external service. Everything stays on your server.
---
## "Summarize this report"
> **You:** *(drag-drop a PDF into the file browser)* <br/>
> Can you read this quarterly report and give me the key takeaways?
The AI opens the PDF, reads through it, and gives you a concise summary — pulling out revenue figures, key decisions, notable changes, whatever matters.
{/* TODO: Screenshot — File browser showing a quarterly_report.pdf file that was just uploaded. The chat shows the AI's response: a bulleted summary with key financial figures, decisions made, and upcoming milestones. */}
{/* TODO: Screenshot — A follow-up question: "What was the total revenue?" with the AI pulling the exact number from the document. */}
---
## "Go through all those invoices"
> **You:** There are about 30 invoices in the /invoices folder. Can you read them all and make a spreadsheet with the vendor name, date, and amount?
The AI opens every file in the folder — even if they're a mix of PDFs and Word documents — extracts the information, and creates a clean spreadsheet you can download.
{/* TODO: Screenshot — Chat showing the AI listing files found in /invoices (invoice_001.pdf, invoice_002.docx, invoice_003.pdf, etc.). The AI reports "Reading 30 files..." */}
{/* TODO: Screenshot — The AI's response: "Done! I created invoices_summary.csv with columns: Vendor, Date, Amount, File. Here's a preview:" followed by a table showing the first few rows. */}
{/* TODO: Screenshot — File browser showing invoices_summary.csv, previewed as a formatted table with the extracted data. */}
---
## "What do these emails say about the deadline?"
> **You:** *(upload several .eml files)* <br/>
> Read through these emails and find any mentions of deadlines or due dates.
The AI reads the email files — including sender, date, subject, and body — and pulls out the relevant information.
{/* TODO: Screenshot — Chat showing the AI reading 5 email files. It responds with a list: "I found 3 mentions of deadlines:" with the email subject, date, and the relevant sentence highlighted for each. */}
---
## "Analyze this data and make a chart"
> **You:** *(drop a sales_data.xlsx into the file browser)* <br/>
> Break down the sales by region and make a pie chart.
The AI reads the spreadsheet, processes the data, creates a chart, and saves it as an image you can preview and download.
{/* TODO: Screenshot — Chat showing the AI reading the spreadsheet (it reports the sheet names and row count), then confirming it created "sales_by_region.png". */}
{/* TODO: Screenshot — File browser previewing the generated pie chart showing sales broken down by region with percentages. */}
---
## "Search across all these documents"
> **You:** Search through everything in the /contracts folder for any mention of "termination clause" or "cancellation".
The AI searches across every file — PDFs, Word docs, spreadsheets, whatever's there — and tells you exactly where it found matches.
{/* TODO: Screenshot — Chat showing the AI searching through 12 files and finding matches in 3 of them. For each match, it shows the filename and the surrounding context: "...either party may invoke the termination clause with 30 days written notice..." */}
:::tip No indexing required
Unlike traditional search or RAG systems, the AI reads files live every time you ask. That means it always sees the latest version — no re-indexing, no sync delays, no database to manage.
:::
---
## Working with large files
If a document is very long, the AI is smart about reading it in sections rather than all at once. You can also ask it to focus on specific parts:
> "Read just the executive summary section of this report"
> "Show me rows 500 through 600 of this spreadsheet"
## More things to try
- **[Run code from chat →](./code-execution)** — the AI writes, runs, and debugs code
- **[Build & preview websites →](./web-development)** — create and iterate on web pages
- **[Explore the file browser →](../file-browser)** — upload, preview, download, and edit files

160
docs/features/open-terminal/use-cases/software-development.md Normal file
View File

@@ -0,0 +1,160 @@
---
sidebar_position: 2
title: "Software Development"
---
# Software Development
Open Terminal enables the AI to interact with real codebases — cloning repos, running tests, reading errors, installing dependencies, and iterating on fixes.
---
## Clone and explore a repo
> **You:** Clone https://github.com/user/project and give me an overview of the codebase. What's the architecture? Where are the entry points?
The AI:
1. Runs `git clone` to pull the repo
2. Scans the directory structure, reads key files (`README`, `package.json`, `pyproject.toml`, etc.)
3. Identifies the tech stack, entry points, and major components
4. Returns a structured summary with file counts, dependencies, and architecture notes
{/* TODO: Screenshot — Chat showing the AI cloning a repo, then providing a codebase overview: "This is a FastAPI app with 3 main modules: auth, users, and billing. Entry point is main.py. Database: PostgreSQL via SQLAlchemy. 47 files, 12 API endpoints." */}
{/* TODO: Screenshot — File browser showing the cloned repo's directory tree with folders like src/, tests/, docs/ expanded. */}
---
## Run the test suite and fix failures
> **You:** Run the tests. If anything fails, figure out why and fix it.
The AI:
1. Detects the test framework (`pytest`, `jest`, `go test`, etc.)
2. Installs dependencies if needed
3. Runs the full test suite
4. Reads failure output, traces the bug, edits the source code
5. Re-runs the failing tests to confirm the fix
{/* TODO: Screenshot — Chat showing the AI running pytest, getting 2 failures, reading the tracebacks, editing a source file, and re-running to show all tests passing. */}
:::tip Iterative debugging
The AI sees the same terminal output a developer would — stack traces, assertion errors, log messages. Multiple rounds of "run → read error → fix → re-run" happen automatically.
:::
---
## Set up a development environment
> **You:** Set up this project so I can develop on it. Install all dependencies, create the database, and run the dev server.
The AI:
1. Reads setup docs (`README`, `Makefile`, `docker-compose.yml`)
2. Installs system packages and language dependencies
3. Creates config files, sets up databases, runs migrations
4. Starts the dev server and confirms it's working
5. Reports the URL where you can access it
{/* TODO: Screenshot — Chat showing the AI reading a README, running pip install, running database migrations, starting a Flask dev server, and reporting "Server running on port 5000." */}
---
## Refactor with confidence
> **You:** Refactor the database queries in `users.py` to use async/await. Make sure the tests still pass.
The AI:
1. Reads the current implementation
2. Rewrites the code with your requested changes
3. Runs the test suite to verify nothing broke
4. If tests fail, adjusts the refactored code until they pass
5. Shows you a `git diff` of what changed
{/* TODO: Screenshot — Chat showing the AI refactoring code, running tests (all pass), then displaying a git diff with the changes highlighted: old synchronous queries removed, new async queries added. */}
---
## Git workflows
> **You:** Show me what changed since the last release tag. Summarize the commits.
The AI works with Git directly:
- `git log`, `git diff`, `git blame` to analyze history
- Create branches, stage changes, make commits
- Generate changelogs from commit history
- Find when a bug was introduced with `git bisect`
- Resolve merge conflicts
{/* TODO: Screenshot — Chat showing the AI running git log between two tags, then summarizing: "23 commits since v1.2.0. Key changes: new billing module (5 commits), auth refactor (8 commits), bug fixes (10 commits)." */}
---
## Write and run tests
> **You:** Write unit tests for the `calculate_shipping()` function in `orders.py`. Cover edge cases.
The AI:
1. Reads the function to understand its logic and parameters
2. Identifies edge cases (zero quantity, negative values, international vs domestic, free shipping threshold)
3. Writes test cases using the project's existing test framework
4. Runs them to verify they pass
5. If any fail, it determines whether it's a test bug or a code bug
{/* TODO: Screenshot — Chat showing the AI reading the function, writing 8 test cases, running pytest, and reporting "8 tests passed. Coverage for calculate_shipping: 94%." */}
---
## Debug a specific issue
> **You:** Users are reporting that the login endpoint returns 500 sometimes. Here's the error from the logs: `KeyError: 'session_token'`. Find and fix it.
The AI:
1. Searches the codebase for where `session_token` is used
2. Reads the surrounding code to understand the flow
3. Identifies the bug (e.g., missing key check when session expires)
4. Writes the fix with proper error handling
5. Adds a test case for the edge case
6. Runs the tests to confirm
{/* TODO: Screenshot — Chat showing the AI using grep to find the bug location, reading the code, explaining the root cause, applying a fix, and running the test suite. */}
---
## Build and verify an API
> **You:** Create a REST API for managing a bookstore. I need CRUD for books, authors, and categories. Use FastAPI and SQLite.
The AI:
1. Scaffolds the project structure
2. Defines database models and schemas
3. Implements all endpoints with validation
4. Creates seed data
5. Starts the server and tests every endpoint with `curl`
6. Shows you the Swagger docs page
{/* TODO: Screenshot — Chat showing the AI testing each endpoint with curl: POST /books (201 Created), GET /books (returns list), PUT /books/1 (updated), DELETE /books/1 (deleted). */}
{/* TODO: Screenshot — Port preview showing the FastAPI Swagger UI at /docs with all endpoints visible. */}
---
## What languages and tools are available?
The Docker image comes with common development tools pre-installed:
| Category | Tools available |
| :--- | :--- |
| **Languages** | Python, Node.js, Ruby, C/C++, Bash |
| **Package managers** | pip, npm, gem, apt |
| **Version control** | Git |
| **Editors** | nano, vim |
| **Build tools** | make, gcc, g++ |
The AI can install additional tools on the fly — Rust, Go, Java, Docker CLI, database clients, and anything else available via `apt` or language-specific package managers.
## Related
- **[Code execution →](./code-execution)** — quick scripts and one-off tasks
- **[Web development →](./web-development)** — build and preview websites
- **[Advanced workflows →](./advanced-workflows)** — skills for code review, database analysis, and more

91
docs/features/open-terminal/use-cases/system-automation.md Normal file
View File

@@ -0,0 +1,91 @@
---
sidebar_position: 4
title: "Automate Tasks"
---
# Automate Tasks
Open Terminal isn't just for code. The AI can manage files, organize folders, process data in bulk, handle backups, and automate repetitive work — all from a conversation.
---
## "Rename and organize these files"
> **You:** I have 200 photos in the /photos folder with names like IMG_4521.jpg. Rename them to include the date and sort them into folders by month.
The AI reads the file dates, renames everything, and creates monthly folders:
{/* TODO: Screenshot — Chat showing the AI processing 200 files. The response says "Done! Renamed 200 files and sorted into 8 monthly folders." An example shows: IMG_4521.jpg → 2025-03/2025-03-15_IMG_4521.jpg */}
{/* TODO: Screenshot — File browser showing the new folder structure: 2025-01/, 2025-02/, 2025-03/, etc., with renamed photos inside each. */}
---
## "Find and remove duplicates"
> **You:** Are there any duplicate files in my documents folder?
The AI checks file sizes and content to find exact duplicates, then asks you what to do:
{/* TODO: Screenshot — Chat showing the AI's report: "Found 12 duplicate pairs (saving 340 MB total). Here are the largest:" followed by a table showing file names, sizes, and locations of each duplicate pair. The AI asks "Would you like me to delete the duplicates?" */}
---
## "Back up this folder"
> **You:** Create a zip backup of the /projects folder with today's date in the filename.
{/* TODO: Screenshot — Chat showing the AI creating the backup: "Created backup: projects_2025-03-20.zip (245 MB). Saved to /backups/". The file browser shows the zip file. */}
---
## "Convert these files"
> **You:** Convert all the .png screenshots in this folder to .jpg and make them half the size.
The AI uses image tools (which come pre-installed in Docker) to batch-convert and resize:
{/* TODO: Screenshot — Chat showing the AI processing files: "Converted 25 images from PNG to JPG. Average file size reduced from 2.1 MB to 380 KB." */}
{/* TODO: Screenshot — File browser showing the converted .jpg files alongside or replacing the originals. */}
---
## "Check on the system"
> **You:** How much disk space is left? Are any big files I should clean up?
{/* TODO: Screenshot — Chat showing the AI running a disk usage analysis: "You have 12 GB free out of 50 GB. The largest directories are: /home/user/data (8.2 GB), /home/user/logs (3.1 GB). The single largest file is access.log at 1.4 GB — it's 6 months old. Want me to clean it up?" */}
---
## "Do this to every file in the folder"
> **You:** For every CSV file in /data, add a header row with "Name, Date, Amount" and save it.
The AI writes a script, processes every file, and reports back:
{/* TODO: Screenshot — Chat showing the AI processing CSV files: "Updated 15 CSV files with the header row. Here's a preview of the first one:" followed by a small table showing the first few rows with the new header. */}
---
## Pre-installed tools
The Docker image comes with common tools ready to use:
| What you want to do | Tools available |
| :--- | :--- |
| Download files from the internet | curl, wget |
| Work with JSON data | jq |
| Compress / decompress files | zip, tar, gzip, 7z |
| Process images | ffmpeg, ImageMagick (if installed) |
| Work with databases | sqlite3 |
| Transfer files between servers | rsync, scp |
If a tool isn't installed, the AI can install it on the fly (`sudo apt install ...`).
## More things to try
- **[Run code from chat →](./code-execution)** — the AI writes, runs, and debugs code
- **[Analyze documents & data →](./file-analysis)** — spreadsheets, PDFs, Word docs, emails
- **[Build & preview websites →](./web-development)** — create and iterate on web pages

98
docs/features/open-terminal/use-cases/web-development.md Normal file
View File

@@ -0,0 +1,98 @@
---
sidebar_position: 3
title: "Build & Preview Websites"
---
# Build and Preview Websites
One of the most impressive things Open Terminal can do: the AI builds a website, starts a server, and you **see it live in a preview panel** — all inside Open WebUI. Then you tell it what to change, and the preview updates in real time.
---
## How it works
1. You ask the AI to create a website (or web app, or landing page, or anything web-based)
2. The AI creates the files and starts a web server
3. Open Terminal **automatically detects** the running server
4. A **preview panel** appears in Open WebUI showing the live page
5. You ask for changes → the AI edits the files → the preview updates
{/* TODO: Screenshot — Full view of Open WebUI showing a chat on the left ("Create a landing page for a bakery") and a live website preview panel on the right displaying a beautiful bakery landing page with a hero image, menu section, and contact info. */}
---
## "Make me a landing page"
> **You:** Create a landing page for my photography business. Include a gallery, an about section, and a contact form.
The AI creates the HTML, CSS, and JavaScript files, starts a web server, and the preview appears automatically. It looks professional and polished — not a skeleton wireframe.
{/* TODO: Screenshot — The preview panel showing a photography business landing page with a hero banner, grid gallery of sample images, an "About" section, and a contact form. */}
{/* TODO: Screenshot — File browser showing the created files: index.html, styles.css, script.js. */}
---
## "Change the colors and layout"
Once the page is live, just keep talking to iterate:
> **You:** Make the background dark and use a warmer color palette. Move the gallery above the about section.
The AI edits the files, and the preview updates.
{/* TODO: Screenshot — Side-by-side or before/after: the original light-themed page, then the updated dark-themed page with warm accent colors and rearranged sections. */}
> **You:** Add a logo at the top and make the contact form prettier.
{/* TODO: Screenshot — The updated page with a logo header and a redesigned contact form with styled inputs and a gradient submit button. */}
---
## "Build me something interactive"
The AI can create interactive web applications, not just static pages:
> **You:** Build a simple calculator that runs in the browser.
{/* TODO: Screenshot — Preview panel showing a working calculator web app with number buttons, operation buttons, and a display showing a calculation result. */}
> **You:** Make a habit tracker where I can check off daily habits.
{/* TODO: Screenshot — Preview panel showing a habit tracker with a weekly grid, habit names on the left, and checkmarks for completed days. */}
---
## "Help me fix my website"
Got an existing website that's broken or needs changes? Upload the files and ask:
> **You:** *(uploads HTML/CSS files via the file browser)* <br/>
> The contact form doesn't submit. Can you fix it?
The AI reads your code, identifies the problem, fixes it, and you verify in the preview.
{/* TODO: Screenshot — Chat showing the AI reading the uploaded HTML, identifying the bug ("The form action URL is pointing to a non-existent endpoint"), fixing it, and confirming the form now works. The preview shows the working form. */}
---
## How port detection works
You don't need to do anything special for the preview to appear. Behind the scenes:
1. The AI starts a web server (like `python -m http.server 3000` or any other server)
2. Open Terminal monitors for new network ports
3. When it detects the server is running, it reports the port to Open WebUI
4. Open WebUI displays the preview panel, proxying the traffic through its own connection
This means **you don't need to open extra ports** or change any firewall settings. It just works.
:::tip Multiple previews
If the AI starts more than one server (say, a frontend on port 3000 and a backend API on port 5000), you can switch between them in the ports section.
:::
## More things to try
- **[Run code from chat →](./code-execution)** — the AI writes, runs, and debugs code
- **[Analyze documents & data →](./file-analysis)** — spreadsheets, PDFs, Word docs, emails
- **[Automate tasks →](./system-automation)** — file management, backups, batch operations

2
docs/reference/env-configuration.mdx
View File

@@ -1096,7 +1096,7 @@ The JSON data structure of `TOOL_SERVER_CONNECTIONS` might evolve over time as n
- Type: `str` (JSON array)
- Default: `[]`
- Description: Specifies a JSON array of Open Terminal server connection configurations. Each connection defines the parameters needed to connect to an [Open Terminal](/features/extensibility/open-terminal) instance. Unlike user-level tool server connections, these are admin-configured and proxied through Open WebUI, which means the terminal URL and API key are never exposed to the browser. Supports group-based access control via `access_grants`.
- Description: Specifies a JSON array of Open Terminal server connection configurations. Each connection defines the parameters needed to connect to an [Open Terminal](/features/open-terminal) instance. Unlike user-level tool server connections, these are admin-configured and proxied through Open WebUI, which means the terminal URL and API key are never exposed to the browser. Supports group-based access control via `access_grants`.
- Example:
```json
[

2
docs/troubleshooting/connection-error.mdx
View File

@@ -189,7 +189,7 @@ When you add a URL like `https://myserver.com/api` as a **user/direct** connecti
- Internal IPs (e.g. `http://192.168.1.50:8000`)
:::tip
This applies to **all** backend-proxied connections in Open WebUI — not just Open Terminal. The same pattern affects [Tool Server connections](/features/extensibility/plugin/tools/openapi-servers/open-webui#main-difference-where-are-requests-made-from), [Open Terminal admin connections](/features/extensibility/open-terminal#networking-tips), and Ollama/OpenAI API endpoints.
This applies to **all** backend-proxied connections in Open WebUI — not just Open Terminal. The same pattern affects [Tool Server connections](/features/extensibility/plugin/tools/openapi-servers/open-webui#main-difference-where-are-requests-made-from), [Open Terminal admin connections](/features/open-terminal#networking-tips), and Ollama/OpenAI API endpoints.
:::
## 🌟 Connection to Ollama Server