SKILLS & OPEN TERMINAL

2026-03-27 13:28:37 +07:00 · 2026-02-13 00:37:44 +01:00
parent 5923c5deda
commit b94d00a79b
3 changed files with 347 additions and 25 deletions
--- a/docs/features/chat-features/code-execution/index.md
+++ b/docs/features/chat-features/code-execution/index.md
@@ -15,4 +15,79 @@ Open WebUI offers powerful code execution capabilities directly within your chat

 - **Interactive Artifacts**: Generate and interact with rich content like HTML websites, SVG graphics, and JavaScript visualizations directly within your conversations.

+- **Open Terminal**: Connect a remote shell execution API as a tool for full OS-level access — run any command, install packages, and manage files inside an isolated Docker container.
+
 These execution capabilities bridge the gap between conversation and implementation, allowing you to explore ideas, analyze data, and create visual content seamlessly while chatting with AI models.
+
+## Choosing a Code Execution Backend
+
+Open WebUI supports multiple code execution backends, each suited to different use cases. The right choice depends on what you need — lightweight browser-based execution, a full Python environment, or unrestricted shell access.
+
+### Pyodide (Default)
+
+Pyodide runs Python in the browser via WebAssembly. It is sandboxed and safe for multi-user environments, but comes with constraints:
+
+- **No persistent storage** — the filesystem resets between executions.
+- **Limited library support** — only a subset of Python packages are available. Libraries that rely on C extensions or system calls may not work.
+- **No shell access** — cannot run shell commands, install packages, or interact with the OS.
+
+:::tip
+Pyodide works well for **text analysis, hash computation, chart generation**, and other self-contained tasks. Chart libraries like matplotlib produce base64-encoded images that Open WebUI automatically captures, uploads as files, and injects direct image links into the output — so models can display charts directly in chat without any extra setup.
+:::
+
+### Jupyter
+
+Jupyter provides a full Python environment and can handle virtually any task — file creation, package installation, and complex library usage. However, it has significant drawbacks in shared deployments:
+
+- **Shared environment** — all users share the same Python runtime and filesystem.
+- **Not sandboxed by default** — without careful configuration, users can access system resources or read other users' data.
+- **Not designed for multi-tenant use** — Jupyter was built for single-user workflows.
+
+:::warning
+If you are running a multi-user or organizational deployment, **Jupyter is not recommended** as the code execution backend. Open WebUI's Jupyter integration connects to a single shared instance with no per-user isolation. Jupyter is best suited for **single-user, development, or trusted-user setups** only.
+:::
+
+### Open Terminal
+
+[Open Terminal](/features/open-terminal) is a lightweight API for running shell commands remotely inside a Docker container. It provides full OS-level access — any language, any tool, any shell command — with container-level isolation.
+
+- **Full shell access** — models can install packages, run scripts in any language, use system tools like ffmpeg, git, curl, etc.
+- **Container isolation** — runs in its own Docker container, separate from Open WebUI and other services.
+- **Rich pre-installed toolset** — the Docker image comes with Python 3.12, data science libraries, build tools, networking utilities, and more.
+
+Open Terminal is connected to Open WebUI as an easy to connect [OpenAPI Tool Server](/features/plugin/tools/openapi-servers/open-webui), not as a built-in code execution engine.
+
+:::note
+Open Terminal currently operates as a **single shared instance** — there is no automatic per-user container provisioning yet. Each user connects to the same container unless separate instances are deployed manually.
+:::
+
+### Comparison
+
+| Consideration | Pyodide | Jupyter | Open Terminal |
+| :--- | :--- | :--- | :--- |
+| **Runs in** | Browser (WebAssembly) | Server (Python kernel) | Server (Docker container) |
+| **Library support** | Limited subset | Full Python ecosystem | Full OS — any language, any tool |
+| **Shell access** | ❌ None | ⚠️ Limited | ✅ Full shell |
+| **File persistence** | ❌ Resets each execution | ✅ Shared filesystem | ✅ Container filesystem (until removal) |
+| **Isolation** | ✅ Browser sandbox | ❌ Shared environment | ✅ Container-level (when using Docker) |
+| **Multi-user safety** | ✅ Per-user by design | ⚠️ Not isolated | ⚠️ Single instance (per-user containers planned) |
+| **File generation** | ❌ Very limited | ✅ Full support | ✅ Full support with upload/download |
+| **Setup** | None (built-in) | Admin configures globally | Each user adds as a Tool Server |
+| **Recommended for orgs** | ✅ Safe default | ❌ Not without isolation | ✅ Per-user by design |
+| **Enterprise scalability** | ✅ Client-side, no server load | ❌ Single shared instance | ⚠️ Manual per-user instances |
+
+:::tip On the Roadmap: Terminal Manager for Multi-Tenant Deployments
+
+For organizational and enterprise deployments, a **Terminal Manager** service is being explored that could automatically provision and manage per-user Docker containers. This would potentially:
+
+- Spin up isolated Open Terminal containers on demand, one per user
+- Route requests to the correct container based on user identity
+- Enforce resource limits (CPU, memory) per container
+- Automatically shut down idle containers (e.g., after 30 minutes of inactivity)
+- Clean up containers that haven't been used for a configurable period (e.g., 1 week)
+
+The idea is to configure this in the admin panel by adding a connection to a Terminal Manager (URL + API key), similar to how Jupyter is configured today. Individual users and self-hosters would continue using Open Terminal directly as a tool without needing the manager.
+
+This feature is on the roadmap but no timeline has been announced. Follow the [Open Terminal repository](https://github.com/open-webui/open-terminal) for updates.
+
+:::
--- a/docs/features/open-terminal/index.md
+++ b/docs/features/open-terminal/index.md
@@ -0,0 +1,256 @@
+---
+sidebar_position: 5
+title: "Open Terminal"
+---
+
+# ⚡ Open Terminal
+
+:::info
+
+This page is up-to-date with Open Terminal release version [v0.1.10](https://github.com/open-webui/open-terminal).
+
+:::
+
+## Overview
+
+[Open Terminal](https://github.com/open-webui/open-terminal) is a lightweight API for running shell commands remotely — with real-time streaming and secure access. When connected to Open WebUI as a [Tool](/features/plugin/tools), it gives models full shell access, file management, and the ability to execute arbitrary commands in an isolated environment.
+
+Unlike Pyodide (browser-based, limited libraries) or Jupyter (shared environment, no per-user isolation), Open Terminal runs in its own Docker container with full OS-level capabilities. This makes it ideal for tasks that require:
+
+- Installing and running any software package or language
+- Working with system tools like ffmpeg, pandoc, git, etc.
+- Running multi-step build, analysis, or data processing pipelines
+- Managing files with upload and download support
+
+:::warning
+Open Terminal provides **unrestricted shell access** to the environment it runs in. In production deployments, always run it inside a Docker container with appropriate resource limits. Never run it on bare metal in a shared or untrusted environment.
+:::
+
+## Getting Started
+
+### Docker (Recommended)
+
+```bash
+docker run -d --name open-terminal --restart unless-stopped -p 8000:8000 -e OPEN_TERMINAL_API_KEY=your-secret-key ghcr.io/open-webui/open-terminal
+```
+
+If no API key is provided, one is auto-generated and printed on startup (`docker logs open-terminal`).
+
+The Docker image is based on Python 3.12 and comes pre-installed with a rich set of tools:
+
+| 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, telnet, 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 |
+| **Python libraries** | numpy, pandas, scipy, scikit-learn, matplotlib, seaborn, plotly, jupyter, ipython, requests, beautifulsoup4, lxml, sqlalchemy, psycopg2, pyyaml, toml, jsonlines, tqdm, rich |
+
+### Build from Source
+
+```bash
+docker build -t open-terminal .
+docker run -p 8000:8000 open-terminal
+```
+
+### pip Install (Bare Metal)
+
+```bash
+pip install open-terminal
+open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key
+```
+
+:::warning
+Running bare metal gives the model shell access to your actual machine. Only use this for local development or testing.
+:::
+
+### 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"
+    environment:
+      - OPEN_TERMINAL_API_KEY=your-secret-key
+    deploy:
+      resources:
+        limits:
+          memory: 2G
+          cpus: "2.0"
+
+volumes:
+  open-webui:
+```
+
+## Configuration
+
+| CLI Option | Default | Environment Variable | Description |
+| :--- | :--- | :--- | :--- |
+| `--host` | `0.0.0.0` | — | Bind address |
+| `--port` | `8000` | — | Bind port |
+| `--api-key` | Auto-generated | `OPEN_TERMINAL_API_KEY` | Bearer API key for authentication |
+
+When no API key is provided, Open Terminal generates a random key using a cryptographically secure token and prints it to the console on startup.
+
+## Connecting to Open WebUI
+
+Open Terminal is a FastAPI application and automatically exposes an OpenAPI specification at `/openapi.json`. This means it works out of the box as an [OpenAPI Tool Server](/features/plugin/tools/openapi-servers/open-webui) — no manual tool creation required.
+
+- **As a User Tool Server**: Add it in **Settings → Tools** to connect directly from your browser. Ideal for personal or local instances.
+- **As a Global Tool Server**: Add it in **Admin Settings → Tools** to make it available to all users across the deployment.
+
+For step-by-step instructions with screenshots, see the [OpenAPI Tool Server Integration Guide](/features/plugin/tools/openapi-servers/open-webui).
+
+## API Reference
+
+All endpoints except `/health` and temporary download/upload links require Bearer token authentication.
+
+Interactive API documentation (Swagger UI) is available at `http://localhost:8000/docs` when the server is running.
+
+### Execute a Command
+
+**`POST /execute`**
+
+Runs a shell command and returns the result. Supports pipes, chaining (`&&`, `||`, `;`), and redirections.
+
+:::tip
+The `/execute` endpoint description in the OpenAPI spec automatically includes live system metadata — OS, hostname, current user, default shell, Python version, and working directory. When Open WebUI discovers this tool via the OpenAPI spec, models see this context in the tool description and can adapt their commands accordingly.
+:::
+
+**Request body:**
+
+| Field | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `command` | string | (required) | Shell command to execute |
+| `timeout` | number | `30` | Max execution time in seconds. Process is killed if exceeded. Set to `null` to disable. |
+
+**Query parameter:**
+
+| Parameter | Default | Description |
+| :--- | :--- | :--- |
+| `stream` | `false` | If `true`, stream output as JSONL instead of waiting for completion |
+
+**Synchronous response:**
+
+```bash
+curl -X POST http://localhost:8000/execute \
+  -H "Authorization: Bearer <api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"command": "echo hello"}'
+```
+
+```json
+{"exit_code": 0, "stdout": "hello\n", "stderr": ""}
+```
+
+Exit code `-1` indicates the command was killed due to timeout.
+
+**Streaming response:**
+
+```bash
+curl -X POST "http://localhost:8000/execute?stream=true" \
+  -H "Authorization: Bearer <api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"command": "for i in 1 2 3; do echo $i; sleep 1; done"}'
+```
+
+Streams as JSONL (`application/x-ndjson`):
+
+```jsonl
+{"type": "stdout", "data": "1\n"}
+{"type": "stdout", "data": "2\n"}
+{"type": "stdout", "data": "3\n"}
+{"type": "exit", "data": 0}
+```
+
+### Upload a File
+
+**`POST /files/upload`**
+
+Save a file to the container filesystem. Provide either a `url` to fetch remotely, or send the file directly via multipart form data.
+
+**From URL:**
+```bash
+curl -X POST "http://localhost:8000/files/upload?url=https://example.com/data.csv&dir=/tmp" \
+  -H "Authorization: Bearer <api-key>"
+```
+
+**Direct upload:**
+```bash
+curl -X POST "http://localhost:8000/files/upload?dir=/tmp" \
+  -H "Authorization: Bearer <api-key>" \
+  -F "file=@local_file.csv"
+```
+
+**Via temporary upload link (no auth needed to upload):**
+```bash
+# 1. Generate an upload link
+curl -X POST "http://localhost:8000/files/upload/link?dir=/tmp" \
+  -H "Authorization: Bearer <api-key>"
+# → {"url": "http://localhost:8000/files/upload/a1b2c3d4..."}
+
+# 2. Upload to the link (no auth required)
+curl -X POST "http://localhost:8000/files/upload/a1b2c3d4..." \
+  -F "file=@local_file.csv"
+```
+
+Opening a temporary upload link in a browser shows a simple file picker form — useful for manual uploads without curl.
+
+The filename is automatically derived from the uploaded file or the URL.
+
+### Download a File
+
+**`GET /files/download/link`**
+
+Returns a temporary download URL for a file. The link expires after 5 minutes and requires no authentication to use.
+
+```bash
+curl "http://localhost:8000/files/download/link?path=/tmp/output.csv" \
+  -H "Authorization: Bearer <api-key>"
+```
+
+```json
+{"url": "http://localhost:8000/files/download/a1b2c3d4..."}
+```
+
+### Health Check
+
+**`GET /health`**
+
+Returns service status. No authentication required.
+
+```json
+{"status": "ok"}
+```
+
+## Security Considerations
+
+- **Always use Docker** in production. Running Open Terminal on bare metal exposes the host system to any command the model generates.
+- **Set an API key**. Without one, anyone who can reach the port has full shell access. If you don't provide one, the auto-generated key is printed once at startup — save it.
+- **Use resource limits**. Apply `--memory` and `--cpus` flags in Docker to prevent runaway processes from consuming host resources.
+- **Network isolation**. Place the Open Terminal container on an internal Docker network that only Open WebUI can reach, rather than exposing it to the public internet.
+- **Container is ephemeral**. Files inside the container are lost when the container is removed. Mount a volume if you need persistence.
+
+## Further Reading
+
+- [Open Terminal GitHub Repository](https://github.com/open-webui/open-terminal)
+- [Interactive API Documentation](http://localhost:8000/docs) (available when running locally)
+- [Python Code Execution](/features/chat-features/code-execution/python) — Pyodide and Jupyter backends
+- [Jupyter Integration Tutorial](/tutorials/integrations/jupyter) — Setting up Jupyter as a code execution backend
+- [Skills](/features/workspace/skills) — Using skills with code execution
--- a/docs/features/workspace/skills.md
+++ b/docs/features/workspace/skills.md
@@ -84,43 +84,34 @@ From the Skills workspace list, you can perform the following actions via the el

 Each skill has an **active/inactive toggle** visible on the list page. Inactive skills are excluded from manifests and cannot be loaded by the model, even if they are bound to one or mentioned in chat.

-## Code Execution Limitations
+## Code Execution Backends

-Skills themselves are plain-text instructions, but many useful skills involve asking the model to execute code via the [Code Interpreter](/features/workspace/code-interpreter). The available code execution backends each have trade-offs to be aware of:
+The backend you choose affects what your skills can do — from simple text transformations (Pyodide) to full OS-level shell access (Open Terminal). Each has different trade-offs in library support, isolation, persistence, and multi-user safety.

-### Pyodide (Default)
+See the [Code Execution overview](/features/chat-features/code-execution) for a detailed comparison of all available backends and guidance on choosing the right one for your deployment.

-Pyodide runs Python in the browser via WebAssembly. It is sandboxed and safe for multi-user environments, but comes with significant constraints:
+### Setting Up Open Terminal

- **No persistent storage** — the filesystem resets between executions, so skills that need to save or accumulate files across messages will not work.
- **Limited library support** — only a subset of Python packages are available. Libraries that rely on C extensions or system calls (e.g., `python-docx`, `ffmpeg`, `pandas` with native backends) may not be available or may fail at runtime.
- **No shell access** — skills that require running shell commands, installing packages, or interacting with the OS cannot function.
+Open Terminal is a FastAPI application that automatically exposes an [OpenAPI specification](https://swagger.io/specification/). This means it works out of the box as an OpenAPI Tool Server — Open WebUI auto-discovers its endpoints and registers them as tools. No manual tool creation needed.

-> [!TIP]
-> Skills work best with Pyodide when they focus on **text transformation, analysis, and instruction-following** rather than file generation or system-level tasks.
+**1. Start an Open Terminal instance**

-### Jupyter
+Follow the [Open Terminal setup guide](/features/open-terminal#getting-started) to launch an instance using Docker or pip.

-Jupyter provides a full Python environment and can handle virtually any task — file creation, package installation, and complex library usage. However, it has serious drawbacks in shared deployments:
+**2. Connect to Open WebUI**

- **Shared environment** — all users share the same Python runtime and filesystem. One user's installed packages, files, or running processes are visible to (and can interfere with) others.
- **Not sandboxed by default** — without careful configuration, users can access system resources, read other users' data, or interfere with the host system.
- **Not designed for multi-tenant use** — Jupyter was built for single-user workflows. Running it as a shared backend in a multi-user Open WebUI deployment introduces security and isolation concerns.
+Add your Open Terminal instance as a Tool Server by following the [OpenAPI Tool Server Integration Guide](/features/plugin/tools/openapi-servers/open-webui). You can connect it as:

-> [!WARNING]
-> If you are running a multi-user or organizational deployment, **Jupyter is not recommended** as the code execution backend. Open WebUI's Jupyter integration connects to a single shared Jupyter instance with no per-user isolation.
+- A **User Tool Server** (in **Settings → Tools**) — connects from your browser, ideal for personal or local instances
+- A **Global Tool Server** (in **Admin Settings → Tools**) — connects from the backend, available to all users

-### Choosing the Right Backend
+Once connected, the Open Terminal tools (execute, file upload, file download) appear automatically in the chat interface.

-| Consideration | Pyodide | Jupyter |
-| :--- | :--- | :--- |
-| **Safety in multi-user setups** | ✅ Sandboxed | ⚠️ Shared environment |
-| **Library availability** | ⚠️ Limited | ✅ Full Python ecosystem |
-| **Persistent storage** | ❌ No | ✅ Yes |
-| **File generation** | ❌ Very limited | ✅ Full support |
-| **Recommended for orgs** | ✅ Safe default | ❌ Not without isolation |
+:::tip
+For the best experience, pair Open Terminal with a [Skill](/features/workspace/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.
+:::

-For organizational deployments that need powerful code execution, per-user sandboxed Docker containers are the recommended long-term approach but are not yet available as a built-in feature.
+See the [Open Terminal documentation](/features/open-terminal) for the full API reference and detailed setup instructions.

 ## Access Control