From 14a0f2f7bdbe5d59a4cf975d984bf6b43a178dba Mon Sep 17 00:00:00 2001 From: silentoplayz Date: Wed, 9 Sep 2026 13:51:14 -0400 Subject: [PATCH] docs: correct the Terminals isolation, context, and settings path notes --- .../open-terminal/advanced/multi-user.md | 17 +++++++++-------- .../terminals/orchestration/contexts.md | 5 +++-- .../orchestration/environment-variables.md | 2 +- .../terminals/orchestration/policies.md | 2 +- .../terminals/tab-deployment/Docker.md | 2 +- 5 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/features/open-terminal/advanced/multi-user.md b/docs/features/open-terminal/advanced/multi-user.md index d6ac94b47f..1ece03b6d9 100644 --- a/docs/features/open-terminal/advanced/multi-user.md +++ b/docs/features/open-terminal/advanced/multi-user.md @@ -10,7 +10,7 @@ When multiple people on your team need terminal access through Open WebUI, you h | | 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 | +| **Isolation** | Files are separate, but they share the same system | Separate files, processes, and resources per user. On the Docker backend the workspaces share one network | | **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) | @@ -18,7 +18,7 @@ When multiple people on your team need terminal access through Open WebUI, you h :::danger Required for multi-user Open WebUI deployments If your Open WebUI instance has **more than one user account** and the same terminal-server connection is shared across users, you **must** use one of the two isolation modes below. A single Open Terminal container without `OPEN_TERMINAL_MULTI_USER=true` (or without per-user containers via Terminals) places every user inside the same shell, the same filesystem, and the same network namespace, which means any user can read, modify, or replace any other user's files, run commands as the shared user, and bind shared ports. This is not a supported configuration for multi-user Open WebUI. -For deployments with **untrusted users** (open signup, public-facing portals, mixed-tenant setups), Option 1 is also insufficient on its own. File isolation does not extend to network namespace, so users can still reach each other through bound ports on the shared container. Use **Option 2 (per-user containers via Terminals)** for these deployments, or layer `TERMINAL_PROXY_HEADERS` on top of Option 1 to restrict what proxied responses can do in the user's browser. +For deployments with **untrusted users** (open signup, public-facing portals, mixed-tenant setups), Option 1 is also insufficient on its own. File isolation does not extend to network namespace, so users can still reach each other through bound ports on the shared container. Use **Option 2 (per-user containers via Terminals)** on its Kubernetes backend with a NetworkPolicy for these deployments, or layer `TERMINAL_PROXY_HEADERS` on top of Option 1 to restrict what proxied responses can do in the user's browser. ::: --- @@ -63,7 +63,7 @@ Each user sees only their own files in the file browser. :::warning Good for small teams, not production This mode gives everyone their own workspace, but they're all running inside the same container. Resource pressure (memory, CPU) is shared, **and so is the network namespace**: a user who binds a port (e.g. `python -m http.server 8080`) is reachable from any other user's terminal-server proxy URL on that port. Per-user file isolation does **not** extend to per-user network isolation in this mode. -Use this for small, trusted groups, not for wide-open deployments. For untrusted multi-user deployments, use **Option 2 (per-user containers)** below, or layer the [`TERMINAL_PROXY_HEADERS`](/reference/env-configuration#terminal_proxy_headers) configuration on top to lock proxied responses into a sandbox CSP. +Use this for small, trusted groups, not for wide-open deployments. For untrusted multi-user deployments, use **Option 2 (per-user containers)** below on its Kubernetes backend, or layer the [`TERMINAL_PROXY_HEADERS`](/reference/env-configuration#terminal_proxy_headers) configuration on top to lock proxied responses into a sandbox CSP. ::: ```mermaid @@ -92,7 +92,7 @@ flowchart LR ## Option 2: Per-user containers with Terminals -For larger deployments or when you need real isolation, [**Terminals**](../terminals/) gives each user their own container, completely separate from everyone else. +For larger deployments or when you need real isolation, [**Terminals**](../terminals/) gives each user their own container, with files, processes, and resources separate from everyone else's. - **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 @@ -100,6 +100,7 @@ For larger deployments or when you need real isolation, [**Terminals**](../termi - **Multiple environments**: different setups for different teams (e.g., data science, development) - **Kubernetes support**: works with Docker, Kubernetes, and k3s - **Scoped workspaces**: optionally give each saved chat or each automation its own workspace instead of one per user, via [Terminal Contexts](/features/open-terminal/terminals/orchestration/contexts) +- **One network on the Docker backend**: every workspace sits on the same Docker network so the orchestrator can reach each one by name, which also lets a workspace reach a port another user's workspace has opened. Files and processes stay separate. For mutually untrusted users, run the Kubernetes backend and add a NetworkPolicy ```mermaid flowchart LR @@ -119,8 +120,8 @@ flowchart LR Two deployment backends are available: -- **[Docker Backend](../terminals/)**: runs on a single Docker host. Best for small-to-medium teams or environments without Kubernetes. -- **[Kubernetes Operator](../terminals/)**: production-grade deployment using a CRD-based operator. Deploys alongside Open WebUI via the Helm chart. +- **[Docker Backend](../terminals/#deployment)**: runs on a single Docker host. Best for small-to-medium teams or environments without Kubernetes. +- **[Kubernetes Operator](../terminals/#deployment)**: production-grade deployment using a CRD-based operator. Deploys alongside Open WebUI via the Helm chart. :::info Enterprise license required Terminals requires an [Open WebUI Enterprise License](https://openwebui.com/enterprise). See the [Terminals repository](https://github.com/open-webui/terminals) for license details. @@ -129,7 +130,7 @@ Terminals requires an [Open WebUI Enterprise License](https://openwebui.com/ente ## Related - [Terminals overview →](../terminals/) -- [Terminals: Docker Backend →](../terminals/) -- [Terminals: Kubernetes Operator →](../terminals/) +- [Terminals: Docker Backend →](../terminals/#deployment) +- [Terminals: Kubernetes Operator →](../terminals/#deployment) - [Security best practices →](./security.md) - [All configuration options →](./configuration.md) diff --git a/docs/features/open-terminal/terminals/orchestration/contexts.md b/docs/features/open-terminal/terminals/orchestration/contexts.md index 708fbf7b85..d47ae59f63 100644 --- a/docs/features/open-terminal/terminals/orchestration/contexts.md +++ b/docs/features/open-terminal/terminals/orchestration/contexts.md @@ -49,8 +49,9 @@ A terminal that is **Off** for chats is not listed in the chat terminal picker, A per chat workspace belongs to a specific conversation, so the conversation has to exist first. It does once the first message has been sent and the chat appears in the sidebar. - In a new conversation that has not been sent yet, the terminal panel and file browser for that terminal are not available. They appear once the chat is saved. -- In a [temporary chat](/features/chat-conversations/chat-features/url-params#8-temporary-chat-sessions), a per chat terminal is not listed in the terminal picker at all. A temporary chat is never saved, so there is nothing for the workspace to belong to. -- Nothing quietly falls back to the shared workspace. Before the chat is saved the terminal is refused, and a model told to use it reports an error naming the terminal. +- In a [temporary chat](/features/chat-conversations/chat-features/url-params#8-temporary-chat-sessions), a per chat terminal has nothing to attach to, because a temporary chat is never saved. The picker drops the terminal once the temporary chat exists. Before its first message the picker still lists it, and a message sent with it selected fails with `Terminal unavailable: Terminal server '' requires a saved chat context`. +- Nothing in the interface quietly falls back to the shared workspace. Before the chat is saved the terminal is refused, and a model told to use it reports an error naming the terminal. +- A request that reaches the proxy with no chat id at all, such as a direct API call, is not scoped to any chat and lands in the shared workspace even when the row is **Per chat**. The Open WebUI interface always sends the chat id. ## Capacity diff --git a/docs/features/open-terminal/terminals/orchestration/environment-variables.md b/docs/features/open-terminal/terminals/orchestration/environment-variables.md index 12a9f57213..dd67652a3f 100644 --- a/docs/features/open-terminal/terminals/orchestration/environment-variables.md +++ b/docs/features/open-terminal/terminals/orchestration/environment-variables.md @@ -44,7 +44,7 @@ Policy env vars are visible to the user inside their terminal. Do not put secret ## Automatically Injected Resource Vars -These are set automatically by the orchestrator from the policy's `cpu_limit` and `memory_limit`, so a system prompt or tool can read the container's resource budget. They are not user-configured. +These are set automatically by the orchestrator from the policy's `cpu_limit` and `memory_limit`, so a system prompt or tool can read the container's resource budget. They are not user-configured. Inside a capped workspace, `nproc` and `free` still report the host's cores and memory, so these variables are the only in-container source of the real limits. | Variable | Purpose | | :--- | :--- | diff --git a/docs/features/open-terminal/terminals/orchestration/policies.md b/docs/features/open-terminal/terminals/orchestration/policies.md index 400ea28894..8dcfbbf95c 100644 --- a/docs/features/open-terminal/terminals/orchestration/policies.md +++ b/docs/features/open-terminal/terminals/orchestration/policies.md @@ -9,7 +9,7 @@ A policy describes what a user's Open Terminal workspace should look like. It co Think of policies as agent workspace profiles. A data team might get Python, notebooks, and larger storage. A training lab might get a locked-down image and scheduled resets. A software team might get Git, build tools, language runtimes, and persistent files. -In Open WebUI, go to **Settings** -> **Admin** -> **Tools** -> **Integrations** -> Open Terminal**, add an orchestrator connection, verify it, then edit the policy fields. +In Open WebUI, go to **Settings > Admin > Integrations**, add an orchestrator connection in the **Open Terminal** section, verify it, then edit the policy fields. ## Policy Fields diff --git a/docs/features/open-terminal/terminals/tab-deployment/Docker.md b/docs/features/open-terminal/terminals/tab-deployment/Docker.md index 9faf01fd53..09fae4269f 100644 --- a/docs/features/open-terminal/terminals/tab-deployment/Docker.md +++ b/docs/features/open-terminal/terminals/tab-deployment/Docker.md @@ -108,7 +108,7 @@ The orchestrator needs access to the Docker socket (`/var/run/docker.sock`) to m
Container lifecycle details -**Naming.** Containers are named `terminals-` (where `` is the first 12 hex chars of the SHA-256 of the user ID, for a DNS-safe name), or `terminals--` for non-default policies. They are easy to filter with `docker ps --filter "label=app.kubernetes.io/managed-by=terminals"`. +**Naming.** Containers are named `terminals-` (where `` is the first 12 hex chars of the SHA-256 of the user ID, for a DNS-safe name), or `terminals--` for non-default policies. They are easy to filter with `docker ps --filter "label=app.kubernetes.io/managed-by=terminals"`. One container is also provisioned under the user id `system`, which Open WebUI uses to read a policy's tool list and system prompt, so a row for a user you do not recognize is expected. **Health checks.** After creating a container, the orchestrator polls its `/health` endpoint until it returns HTTP 200 (up to 15 seconds). Only then does it start proxying traffic.