open-terminal-guide · diff
git:20260902.6c69dd7 to git:20261013.df0a08f
92 added, 98 removed. Audit A to A.
---
name: open-terminal-guide
- description: >-
- Полная русскоязычная справка по Open Terminal: self-hosted REST API
- терминала для AI-агентов. Используй этот скилл при любых вопросах об Open
- Terminal: API-эндпоинты, развёртывание (Docker, bare-metal), конфигурация,
- интеграция с Open WebUI, архитектура, отладка, написание клиентского кода
- для взаимодействия с Open Terminal. Также используй при работе с кодовой
- базой open-terminal: структура проекта, runner.py, main.py, MCP-сервер,
- Jupyter-ноутбуки. Триггеры: open-terminal, open terminal, remote terminal
- API, /execute, /files, sandbox API, terminal sessions, Open WebUI terminal.
+ description: "Complete guide to Open Terminal, a self-hosted terminal REST API for AI agents. Use for any Open Terminal question: API endpoints, deployment (Docker, bare metal), configuration, Open WebUI integration, architecture, debugging, writing client code for Open Terminal. Also use when working on the open-terminal codebase: project structure, runner.py, main.py, MCP server, Jupyter notebooks. Triggers: open-terminal, open terminal, remote terminal API, /execute, /files, sandbox API, terminal sessions, Open WebUI terminal, терминал, выполнить команду, песочница."
---
- # Open Terminal — Полная справка
+ # Open Terminal — Complete Guide
- Open Terminal — это легковесный self-hosted REST API, который предоставляет AI-агентам и инструментам автоматизации выделенную среду для выполнения команд, управления файлами и запуска кода. Является частью экосистемы [Open WebUI](https://github.com/open-webui/open-webui).
+ Open Terminal is a lightweight self-hosted REST API that gives AI agents and automation tools a dedicated environment to run commands, manage files and execute code. It is part of the [Open WebUI](https://github.com/open-webui/open-webui) ecosystem.
- ## Два режима работы
+ ## Two modes
- | Режим | Описание | Безопасность |
+ | Mode | Description | Security |
|-------|----------|-------------|
- | **Docker** | Изолированный контейнер с предустановленными Python, Node.js, git, ffmpeg, LaTeX, data science библиотеками и др. | Песочница, безопасно для AI-агентов |
- | **Bare metal** | `pip install open-terminal` и запуск напрямую на машине | Команды выполняются с правами пользователя — без изоляции |
+ | **Docker** | Isolated container with preinstalled Python, Node.js, git, ffmpeg, LaTeX, data science libraries, etc. | Sandbox, safe for AI agents |
+ | **Bare metal** | `pip install open-terminal` and run directly on the machine | Commands run with the user's privileges — no isolation |
- ## Быстрый старт
+ ## Quick start
```bash
- # Задай ключ заранее через secret manager или env-file
+ # Set the key up front via a secret manager or env file
export OPEN_TERMINAL_API_KEY='<random-secret-from-secret-store>'
export OPEN_TERMINAL_IMAGE='ghcr.io/open-webui/open-terminal@sha256:<verified-digest>'
- # Docker (рекомендуется)
+ # Docker (recommended)
docker pull "$OPEN_TERMINAL_IMAGE"
docker run -d --name open-terminal --restart unless-stopped \
-p 127.0.0.1:8000:8000 \
-v open-terminal:/home/user \
-e OPEN_TERMINAL_API_KEY="$OPEN_TERMINAL_API_KEY" \
"$OPEN_TERMINAL_IMAGE"
- # Bare metal через uvx (без установки)
+ # Bare metal via uvx (no install)
uvx open-terminal run --host 127.0.0.1 --port 8000 --api-key "$OPEN_TERMINAL_API_KEY"
- # Bare metal через pip
+ # Bare metal via pip
pip install open-terminal
open-terminal run --host 127.0.0.1 --port 8000 --api-key "$OPEN_TERMINAL_API_KEY"
```
- Автогенерация API-ключа в логах годится только для локального одноразового теста. Для постоянного окружения задай ключ явно через env var или `_FILE` secret.
+ An API key auto-generated into the logs is only fine for a local throwaway test. For a persistent environment set the key explicitly via an env var or a `_FILE` secret.
- ## Аутентификация
+ ## Authentication
- Все эндпоинты кроме `/health` требуют Bearer-токен:
+ All endpoints except `/health` require a Bearer token:
```
Authorization: Bearer $OPEN_TERMINAL_API_KEY
```
- WebSocket-терминалы используют **first-message auth** — первое сообщение после подключения должно быть JSON:
+ WebSocket terminals use **first-message auth** — the first message after connecting must be JSON:
```json
{"type": "auth", "token": "$OPEN_TERMINAL_API_KEY"}
```
## Security Guardrails
- - Разворачивай Open Terminal только за VPN, reverse proxy или allowlist ACL. Не публикуй его напрямую в интернет без отдельного изоляционного контура.
- - Для production предпочитай Docker/VM/отдельного пользователя без привилегий. Bare metal допустим только в доверенной среде.
- - `/files/upload` с полем `url`, notebook `source` и `/proxy/{port}/{path}` используй только для доверенных источников. Не скачивай URL и не выполняй полученный контент без ручной проверки.
- - Если не нужны PTY, notebooks или proxy, отключай их конфигом/доступом на периметре.
- - Не вставляй реальные ключи в команды, логи, issue-трекер, примеры JSON и сообщения агенту.
+ - Deploy Open Terminal only behind a VPN, reverse proxy or allowlist ACL. Never expose it directly to the internet without a separate isolation layer.
+ - In production prefer Docker/VM/a dedicated unprivileged user. Bare metal is acceptable only in a trusted environment.
+ - Use `/files/upload` with a `url` field, notebook `source` and `/proxy/{port}/{path}` only for trusted sources. Do not download URLs or execute fetched content without manual review.
+ - If PTY, notebooks or proxy are not needed, disable them via config or at the perimeter.
+ - Never paste real keys into commands, logs, issue trackers, JSON examples or messages to the agent.
- ## Основные группы API
+ ## Main API groups
- | Группа | Назначение |
+ | Group | Purpose |
|--------|-----------|
- | `POST /execute` | Запуск команд как фоновых процессов |
- | `GET /execute/{id}/status` | Поллинг вывода и статуса |
- | `POST /execute/{id}/input` | Отправка stdin в процесс |
- | `DELETE /execute/{id}` | Завершение (kill) процесса |
- | `GET /files/list` | Листинг директории |
- | `GET /files/read` | Чтение файла (текст/PDF/бинарные) |
- | `POST /files/write` | Запись файла |
- | `POST /files/replace` | Find-and-replace в файле |
- | `GET /files/grep` | Поиск по содержимому файлов |
- | `GET /files/glob` | Поиск файлов по имени (glob-паттерны) |
- | `GET /files/display` | Открытие файла в UI пользователя |
- | `POST /files/upload` | Загрузка файла (multipart или URL) |
- | `POST /api/terminals` | Создание интерактивной PTY-сессии |
- | `WS /api/terminals/{id}` | WebSocket для терминала |
- | `GET /ports` | Детекция слушающих TCP-портов |
- | `/proxy/{port}/{path}` | Reverse-proxy к localhost:{port} |
- | `GET /health` | Health check (без аутентификации) |
+ | `POST /execute` | Run commands as background processes |
+ | `GET /execute/{id}/status` | Poll output and status |
+ | `POST /execute/{id}/input` | Send stdin to the process |
+ | `DELETE /execute/{id}` | Terminate (kill) the process |
+ | `GET /files/list` | List a directory |
+ | `GET /files/read` | Read a file (text/PDF/binary) |
+ | `POST /files/write` | Write a file |
+ | `POST /files/replace` | Find-and-replace in a file |
+ | `GET /files/grep` | Search file contents |
+ | `GET /files/glob` | Find files by name (glob patterns) |
+ | `GET /files/display` | Open a file in the user's UI |
+ | `POST /files/upload` | Upload a file (multipart or URL) |
+ | `POST /api/terminals` | Create an interactive PTY session |
+ | `WS /api/terminals/{id}` | WebSocket for the terminal |
+ | `GET /ports` | Detect listening TCP ports |
+ | `/proxy/{port}/{path}` | Reverse proxy to localhost:{port} |
+ | `GET /health` | Health check (no auth) |
- Подробная информация по каждому эндпоинту — в `references/api.md`.
+ Details for every endpoint are in `references/api.md`.
- ## Модель выполнения команд
+ ## Command execution model
- Команды запускаются через `POST /execute` как **фоновые процессы**:
+ Commands are started via `POST /execute` as **background processes**:
- 1. Команда спавнится в PTY (Unix) / WinPTY (Windows) / пайпы (fallback)
- 2. Получает UUID-идентификатор, вывод пишется в JSONL-лог в `LOG_DIR`
- 3. Статус: `running` → `done` (или `killed`)
- 4. Вывод читается через поллинг `GET /execute/{id}/status` с `offset` и `tail`
- 5. Готовые процессы автоматически удаляются через 5 минут после завершения
+ 1. The command is spawned in a PTY (Unix) / WinPTY (Windows) / pipes (fallback)
+ 2. It gets a UUID; output is written to a JSONL log in `LOG_DIR`
+ 3. Status: `running` → `done` (or `killed`)
+ 4. Output is read by polling `GET /execute/{id}/status` with `offset` and `tail`
+ 5. Finished processes are removed automatically 5 minutes after completion
- Параметр `wait` (0–300 сек.) позволяет дождаться завершения команды inline — удобно для коротких команд.
+ The `wait` parameter (0–300 s) lets you wait for completion inline — handy for short commands.
- ## Интерактивные терминалы
+ ## Interactive terminals
- PTY-сессии управляются через REST + WebSocket:
+ PTY sessions are managed via REST + WebSocket:
- 1. `POST /api/terminals` — создать сессию (лимит: `MAX_TERMINAL_SESSIONS`, по умолчанию 16)
- 2. `WS /api/terminals/{id}` — подключиться (first-message auth → бинарные фреймы ввода/вывода)
- 3. Resize: текстовый JSON-фрейм `{"type": "resize", "cols": 120, "rows": 40}`
- 4. Мёртвые сессии автоматически очищаются при листинге
+ 1. `POST /api/terminals` — create a session (limit: `MAX_TERMINAL_SESSIONS`, default 16)
+ 2. `WS /api/terminals/{id}` — connect (first-message auth → binary input/output frames)
+ 3. Resize: a text JSON frame `{"type": "resize", "cols": 120, "rows": 40}`
+ 4. Dead sessions are cleaned up automatically on listing
- ## Конфигурация
+ ## Configuration
- Приоритет (от высшего к низшему):
- 1. CLI-флаги (`--host`, `--port`, `--api-key`)
- 2. Переменные окружения (`OPEN_TERMINAL_*`)
+ Precedence (highest to lowest):
+ 1. CLI flags (`--host`, `--port`, `--api-key`)
+ 2. Environment variables (`OPEN_TERMINAL_*`)
3. User config: `~/.config/open-terminal/config.toml`
4. System config: `/etc/open-terminal/config.toml`
- 5. Встроенные значения по умолчанию
+ 5. Built-in defaults
- Подробная таблица всех переменных окружения и параметров — в `references/configuration.md`.
+ The full table of environment variables and parameters is in `references/configuration.md`.
- ### Docker-специфичные переменные
+ ### Docker-specific variables
- | Переменная | Описание |
+ | Variable | Description |
|-----------|----------|
- | `OPEN_TERMINAL_PACKAGES` | Пробелоразделённый список apt-пакетов для установки при старте |
- | `OPEN_TERMINAL_PIP_PACKAGES` | Пробелоразделённый список pip-пакетов для установки при старте |
+ | `OPEN_TERMINAL_PACKAGES` | Space-separated apt packages installed at startup |
+ | `OPEN_TERMINAL_PIP_PACKAGES` | Space-separated pip packages installed at startup |
- Обрабатываются в `entrypoint.sh` при каждом запуске контейнера.
+ Handled by `entrypoint.sh` on every container start.
### Docker secrets
- Поддерживается конвенция `_FILE` (как у PostgreSQL):
- - `OPEN_TERMINAL_API_KEY_FILE=/run/secrets/api_key` — значение читается из файла
- - Нельзя задавать одновременно `VAR` и `VAR_FILE`
+ The `_FILE` convention is supported (as in PostgreSQL):
+ - `OPEN_TERMINAL_API_KEY_FILE=/run/secrets/api_key` — the value is read from the file
+ - `VAR` and `VAR_FILE` cannot be set at the same time
### Docker socket
- Для доступа к Docker CLI из контейнера (сборка образов, запуск контейнеров):
+ For Docker CLI access from the container (build images, run containers):
```bash
docker run -d -p 8000:8000 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v open-terminal:/home/user \
"$OPEN_TERMINAL_IMAGE"
```
- `entrypoint.sh` автоматически добавляет пользователя в группу сокета.
+ `entrypoint.sh` adds the user to the socket's group automatically. Mounting the Docker socket is equivalent to root on the host — do it only in a trusted environment.
- ## Интеграция с Open WebUI
+ ## Open WebUI integration
- Open Terminal интегрируется с Open WebUI двумя способами:
+ Open Terminal integrates with Open WebUI in two ways:
- ### Direct Connection (из браузера)
- Пользователь подключает свой инстанс через **User Settings → Integrations → Open Terminal**. Запросы идут напрямую из браузера.
+ ### Direct Connection (from the browser)
+ The user connects their instance via **User Settings → Integrations → Open Terminal**. Requests go straight from the browser.
- ### System-Level (через бэкенд)
- Админ настраивает через **Admin Settings → Integrations → Open Terminal**. Запросы проксируются через бэкенд Open WebUI. Можно настроить несколько терминалов с контролем доступа по пользователям/группам.
+ ### System-Level (via the backend)
+ The admin configures it via **Admin Settings → Integrations → Open Terminal**. Requests are proxied through the Open WebUI backend. Several terminals can be configured with per-user/group access control.
- В обоих случаях подключение добавляется в секции **Open Terminal** (не как tool server) — это даёт файловый сайдбар для навигации, загрузки и редактирования файлов.
+ In both cases the connection is added in the **Open Terminal** section (not as a tool server) — this provides a file sidebar for browsing, uploading and editing files.
- ## Архитектура кодовой базы
+ ## Codebase architecture
- Для работы с исходным кодом open-terminal — см. `references/architecture.md`.
+ For working on the open-terminal source see `references/architecture.md`.
- ## MCP-сервер
+ ## MCP server
- Open Terminal может работать как MCP (Model Context Protocol) сервер:
+ Open Terminal can run as an MCP (Model Context Protocol) server:
```bash
- # Требует установки: pip install open-terminal[mcp]
+ # Requires: pip install open-terminal[mcp]
open-terminal mcp --transport stdio
open-terminal mcp --transport streamable-http --host 0.0.0.0 --port 8000
```
- Все FastAPI-эндпоинты автоматически экспонируются как MCP-инструменты через `FastMCP.from_fastapi()`.
+ All FastAPI endpoints are exposed as MCP tools automatically via `FastMCP.from_fastapi()`.
## Jupyter Notebooks
- Скрытые эндпоинты (не в OpenAPI-схеме) для per-cell выполнения ноутбуков:
+ Hidden endpoints (not in the OpenAPI schema) for per-cell notebook execution:
- 1. `POST /notebooks` — создать сессию (привязка к `.ipynb` файлу, запуск ядра)
- 2. `POST /notebooks/{session_id}/execute` — выполнить ячейку (по индексу, с возможностью override source)
- 3. `GET /notebooks/{session_id}` — статус сессии
- 4. `DELETE /notebooks/{session_id}` — остановить ядро
+ 1. `POST /notebooks` — create a session (bound to an `.ipynb` file, starts a kernel)
+ 2. `POST /notebooks/{session_id}/execute` — run a cell (by index, optionally overriding source)
+ 3. `GET /notebooks/{session_id}` — session status
+ 4. `DELETE /notebooks/{session_id}` — stop the kernel
- Сессии автоматически удаляются после 30 минут простоя. Ноутбук сохраняется на диск после каждого выполнения.
+ Sessions are removed after 30 minutes of inactivity. The notebook is saved to disk after each execution.
<!-- A-EVOLVE-ROUTING-SIGNALS:START -->
## Routing signals: open terminal rest api execute files sessions sandbox command notebook self-hosted terminal api agents open_terminal_api_key
<!-- A-EVOLVE-ROUTING-SIGNALS:END -->
+
+ Russian version: [`references/README.ru.md`](references/README.ru.md).