refac

Author: tjbck

docs/features/open-terminal/index.md

@@ -21,7 +21,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 Open WebUI gives you the agent front door: models, chats, knowledge, prompts, users, permissions, builtin tools, MCP connections, automations, and shared workflows. Open Terminal adds the missing computer substrate: a working environment with a filesystem, shell, package manager, running processes, document and data handling, generated artifacts, and live previews.
 
-This is the difference between a chatbot with tools and an agentic AI workspace. The model can plan, create files, run code, inspect output, install dependencies, start servers, render previews, recover from errors, and continue until there is an artifact you can use: a script, report, patch, chart, website, migration, or organized folder.
+That means the agent can do real work. Not just answer questions about a task, and not just emit code you run somewhere else. It can plan, create files, run code, inspect output, install dependencies, start servers, render previews, recover from errors, and continue until there is an artifact you can use: a script, report, patch, chart, website, migration, or organized folder.
 
 Despite the name, Open Terminal is not just a terminal panel. It is the computer-like workspace the agent acts inside. Run it in Docker for isolation, or bare metal when the agent should work directly on the host.
 
@@ -43,7 +43,7 @@ Open Terminal is the computer substrate an **AI agent** drives from chat. If you
 | Feedback loop | Tool calls and chat state | Observe the workspace, change it, run it, inspect the result, fix, retry, verify |
 | Boundary | Open WebUI permissions and configuration | Docker sandbox or direct host access |
 
-Open WebUI is the control plane. Open Terminal is the agent's computer substrate for work that needs an operating system, not just a prompt.
+Open WebUI is the control plane. Open Terminal is the agent's computer substrate for real work that needs an operating system, not just a prompt.
 
 ---
 
@@ -65,7 +65,7 @@ Different teams describe this stack with different language. Open Terminal fits
 | **Orchestration** | The loop of choosing tools, sequencing steps, handling failures, and verifying results |
 | **Sandbox** | The isolation boundary around the agent's filesystem, processes, and network access |
 
-The practical point is simple: models got good enough to use tools, but agents need a computer-shaped place to do work. Open Terminal gives Open WebUI that place.
+The practical point is simple: models got good enough to use tools, but agents need a computer-shaped place to do real work. Open Terminal gives Open WebUI that place.
 
 ---
 

docs/features/open-terminal/terminals/index.mdx

@@ -11,7 +11,9 @@ import Kubernetes from './tab-deployment/Kubernetes.md';
 
 # Terminals (Orchestrator)
 
-**Terminals** is an enterprise orchestration layer for [Open Terminal](/features/open-terminal) that provisions a fully isolated terminal container for every user. Instead of sharing a single container, each person gets their own, complete with separate files, processes, resource limits, and network isolation.
+**Terminals** is the enterprise orchestration layer for [Open Terminal](/features/open-terminal). It provisions a dedicated computer substrate for every Open WebUI user: separate files, processes, package environment, resource limits, network boundary, and optional persistent storage.
+
+Open Terminal gives one chat an agent workspace where AI can do real work. Terminals turns that into managed fleet infrastructure, so every user or policy can get the right workspace without sharing state or hand-wiring containers.
 
 :::tip Quick navigation
 - **Need to operate per-user terminal environments?** → [Orchestration](/features/open-terminal/terminals/orchestration)
@@ -22,9 +24,9 @@ flowchart LR
     OW["Open WebUI"]
     OR["Orchestrator"]
     OW -->|X-User-Id| OR
-    OR --> TA["Open Terminal<br/>User A"]
-    OR --> TB["Open Terminal<br/>User B"]
-    OR --> TC["Open Terminal<br/>User C"]
+    OR --> TA["Agent workspace<br/>User A"]
+    OR --> TB["Agent workspace<br/>User B"]
+    OR --> TC["Agent workspace<br/>User C"]
 
     style OW fill:#4a90d9,color:#fff
     style OR fill:#e67e22,color:#fff
@@ -35,17 +37,31 @@ flowchart LR
 
 ---
 
-## How it works
+## How It Works
+
+The orchestrator sits between Open WebUI and the per-user Open Terminal workspaces:
+
+1. A user activates Open Terminal in Open WebUI.
+2. Open WebUI proxies the request to the **orchestrator**, which manages workspace lifecycle.
+3. The orchestrator resolves the selected policy: image, resources, storage, env vars, security context, and idle timeout.
+4. The orchestrator provisions or reuses a personal Open Terminal workspace for that user and policy.
+5. All traffic is proxied through the orchestrator. The user never connects to the workspace directly.
+6. Idle workspaces are cleaned up after a configurable timeout. Files can persist across sessions when storage is enabled.
+
+The orchestrator exposes the same OpenAPI-based tool interface as Open Terminal, so the AI can work with files, run code, execute commands, start servers, and inspect results, all scoped to the requesting user's workspace.
 
-The orchestrator sits between Open WebUI and the Open Terminal instances:
+## Why It Matters
 
-1. A user activates a terminal in Open WebUI.
-2. Open WebUI proxies the request to the **orchestrator**, a service that manages the lifecycle of terminal containers.
-3. The orchestrator provisions a personal Open Terminal container for that user (or reconnects to an existing one).
-4. All traffic is proxied through the orchestrator. The user never connects to their container directly.
-5. Idle containers are automatically cleaned up after a configurable timeout. Data optionally persists across sessions.
+Terminals is what makes agent computer substrates operable for teams. It lets admins give agents enough environment to do real work while still controlling the boundary:
 
-The orchestrator also exposes the same OpenAPI-based tool interface as Open Terminal, so the AI can execute commands, read files, and run code, all scoped to the requesting user's container.
+| Need | What Terminals provides |
+| :--- | :--- |
+| Isolation | One workspace per user and policy, with separate files and processes |
+| Governance | Policy-controlled images, env vars, resource limits, storage, and security context |
+| Repeatability | Custom images and startup packages so users get the right tools every time |
+| Lifecycle | Reuse, idle cleanup, refresh, and scheduled resets |
+| Scale | Docker for a single host, Kubernetes/operator mode for larger deployments |
+| Supportability | Admin UI, logs, status, policy APIs, and predictable routing |
 
 :::info Admin UI (new in 0.0.4)
 The orchestrator serves a built-in minimal admin UI at `/` for viewing terminal status, active sessions, and policies. It is on by default and toggled with `TERMINALS_ENABLE_UI`; set it to `false` for API-only deployments.
@@ -88,7 +104,7 @@ When deployed via Docker Compose or Helm, the shared API key is configured autom
 
 ### Terminal won't start
 
-1. **Check orchestrator logs.** The orchestrator logs the full provisioning flow, including image pull and container creation. Look for errors related to image availability or resource limits.
+1. **Check orchestrator logs.** The orchestrator logs the full provisioning flow, including image pull and workspace creation. Look for errors related to image availability, policy configuration, or resource limits.
 2. **Verify the API key.** Ensure `TERMINALS_API_KEY` matches between Open WebUI and the orchestrator. A mismatch causes silent auth failures.
 3. **Check image pull access.** If using a private container registry, make sure the orchestrator (Docker) or cluster (Kubernetes) has pull credentials configured.
 
@@ -98,9 +114,9 @@ When deployed via Docker Compose or Helm, the shared API key is configured autom
 - If using **API key mode**, confirm the key is set identically on both sides. Check for extra whitespace or newlines.
 - Check the orchestrator logs for `401` or `403` responses.
 
-### Container is reaped too quickly
+### Workspace is reaped too quickly
 
-Increase `TERMINALS_IDLE_TIMEOUT_MINUTES` (or `idle_timeout_minutes` in a policy). The default is `0` (disabled), but if set too low, containers may be cleaned up while users are still working. A value of `30` is typical.
+Increase `TERMINALS_IDLE_TIMEOUT_MINUTES` (or `idle_timeout_minutes` in a policy). The default is `0` (disabled), but if set too low, workspaces may be cleaned up while users are still working. A value of `30` is typical.
 
 ### Connection refused
 

docs/features/open-terminal/terminals/orchestration/index.md

@@ -5,17 +5,19 @@ title: "Orchestration"
 
 # Orchestration
 
-The Terminals orchestrator gives each Open WebUI user a dedicated Open Terminal container. Open WebUI stores the connection, the orchestrator resolves policy, and Open Terminal runs inside the per-user container.
+The Terminals orchestrator gives each Open WebUI user a dedicated agent workspace backed by Open Terminal. Open WebUI stores the connection, the orchestrator resolves policy, and Open Terminal runs inside the per-user computer substrate where the agent can do real work.
+
+Use this when Open Terminal needs to become managed team infrastructure: different users, groups, or workflows need different images, tools, limits, storage behavior, reset schedules, and security boundaries.
 
 ```mermaid
 flowchart LR
     A["Open WebUI"] --> B["Terminals orchestrator"]
-    B --> C["User A Open Terminal container"]
-    B --> D["User B Open Terminal container"]
-    B --> E["User C Open Terminal container"]
+    B --> C["User A agent workspace"]
+    B --> D["User B agent workspace"]
+    B --> E["User C agent workspace"]
 ```
 
-When a user opens a terminal, Open WebUI routes through `/p/{policy_id}/...`. The orchestrator provisions or reuses that user's container for the selected policy.
+When a user opens Open Terminal, Open WebUI routes through `/p/{policy_id}/...`. The orchestrator provisions or reuses that user's workspace for the selected policy.
 
 ## Read This Section
 
@@ -33,15 +35,15 @@ When a user opens a terminal, Open WebUI routes through `/p/{policy_id}/...`. Th
 
 | Layer | Responsibility |
 | :--- | :--- |
-| Open WebUI | Stores the orchestrator connection, selects the policy, and presents the terminal and file browser UI |
-| Terminals orchestrator | Authenticates requests, resolves policies, provisions containers, forwards env vars, applies idle timeout, and handles refresh/lifecycle work |
-| Policy | Defines image, env, resources, storage, and idle timeout |
-| Policy lifecycle | Defines maintenance behavior over time, such as scheduled resets of persisted terminal files |
-| Open Terminal container | Executes commands, serves files, exposes OpenAPI tools, and reports file-browser root metadata |
+| Open WebUI | Stores the orchestrator connection, selects the policy, and presents chat, terminal, file browser, and preview UI |
+| Terminals orchestrator | Authenticates requests, resolves policies, provisions workspaces, forwards env vars, applies idle timeout, and handles refresh/lifecycle work |
+| Policy | Defines the workspace image, env, resources, storage, security context, and idle timeout |
+| Policy lifecycle | Defines maintenance behavior over time, such as scheduled resets of persisted workspace files |
+| Open Terminal workspace | Executes commands, serves files, exposes OpenAPI tools, runs code and servers, and reports file-browser root metadata |
 
 ## Orchestrator Environment Variables
 
-These configure the orchestrator service itself, prefixed with `TERMINALS_` (or set in a `.env` file). They are distinct from the per-container `OPEN_TERMINAL_*` policy variables covered in [Environment Variables](/features/open-terminal/terminals/orchestration/environment-variables), which are forwarded into each user's container.
+These configure the orchestrator service itself, prefixed with `TERMINALS_` (or set in a `.env` file). They are distinct from the per-workspace `OPEN_TERMINAL_*` policy variables covered in [Environment Variables](/features/open-terminal/terminals/orchestration/environment-variables), which are forwarded into each user's Open Terminal workspace.
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
@@ -53,17 +55,17 @@ These configure the orchestrator service itself, prefixed with `TERMINALS_` (or
 | `TERMINALS_ENABLE_UI` | `true` | Serve the built-in minimal admin UI at `/`. Set `false` for API-only deployments |
 | `TERMINALS_LOG_LEVEL` | `INFO` | Minimum log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL` |
 | `TERMINALS_DATABASE_URL` | `sqlite+aiosqlite:///<data>/terminals.db` | SQLAlchemy database URL. SQLite is the default; PostgreSQL is optional |
-| `TERMINALS_IMAGE` | `ghcr.io/open-webui/open-terminal:latest` | Default container image when a policy sets none |
-| `TERMINALS_NETWORK` | *(unset)* | Docker network for terminal containers. When set, containers are reached by name instead of published ports |
+| `TERMINALS_IMAGE` | `ghcr.io/open-webui/open-terminal:latest` | Default workspace image when a policy sets none |
+| `TERMINALS_NETWORK` | *(unset)* | Docker network for Open Terminal workspaces. When set, containers are reached by name instead of published ports |
 | `TERMINALS_DOCKER_HOST` | `127.0.0.1` | Address used to reach published container ports (Docker backend) |
-| `TERMINALS_DATA_DIR` | `<data>/terminals` | Host directory holding per-user persisted files (Docker backend) |
+| `TERMINALS_DATA_DIR` | `<data>/terminals` | Host directory holding per-user persisted workspace files (Docker backend) |
 | `TERMINALS_IDLE_TIMEOUT_MINUTES` | `0` | Tear down terminals after N minutes of inactivity (`0` = disabled) |
-| `TERMINALS_MAX_CPU` | *(unset)* | Hard cap on CPU per container that policies cannot exceed |
-| `TERMINALS_MAX_MEMORY` | *(unset)* | Hard cap on memory per container that policies cannot exceed |
-| `TERMINALS_MAX_STORAGE` | *(unset)* | Hard cap on storage per container that policies cannot exceed |
+| `TERMINALS_MAX_CPU` | *(unset)* | Hard cap on CPU per workspace that policies cannot exceed |
+| `TERMINALS_MAX_MEMORY` | *(unset)* | Hard cap on memory per workspace that policies cannot exceed |
+| `TERMINALS_MAX_STORAGE` | *(unset)* | Hard cap on storage per workspace that policies cannot exceed |
 | `TERMINALS_ALLOWED_IMAGES` | *(unset)* | Comma-separated list of allowed image patterns (globs). Empty allows any image |
 | `TERMINALS_KUBERNETES_NAMESPACE` | `terminals` | Namespace for terminal pods (Kubernetes backends) |
-| `TERMINALS_KUBERNETES_IMAGE` | `ghcr.io/open-webui/open-terminal:latest` | Default image for terminal pods (Kubernetes backends) |
+| `TERMINALS_KUBERNETES_IMAGE` | `ghcr.io/open-webui/open-terminal:latest` | Default image for Open Terminal pods (Kubernetes backends) |
 | `TERMINALS_KUBERNETES_STORAGE_CLASS` | *(unset)* | StorageClass for PVCs. Empty uses the cluster default |
 | `TERMINALS_KUBERNETES_STORAGE_SIZE` | `1Gi` | Default PVC size when a policy sets none |
 | `TERMINALS_KUBERNETES_STORAGE_MODE` | `per-user` | Storage mode: `per-user`, `shared`, or `shared-rwo` |
@@ -72,14 +74,14 @@ These configure the orchestrator service itself, prefixed with `TERMINALS_` (or
 | `TERMINALS_KUBERNETES_LABELS` | *(unset)* | Extra labels applied to created resources as `k=v,k2=v2` |
 | `TERMINALS_KUBERNETES_RESTRICTED` | `false` | Enable restricted Kubernetes/OpenShift pod defaults globally |
 | `TERMINALS_KUBERNETES_POD_SECURITY_CONTEXT` | `{}` | JSON pod security context merged into terminal pods |
-| `TERMINALS_KUBERNETES_CONTAINER_SECURITY_CONTEXT` | `{}` | JSON container security context merged into terminal containers |
+| `TERMINALS_KUBERNETES_CONTAINER_SECURITY_CONTEXT` | `{}` | JSON container security context merged into Open Terminal containers |
 | `TERMINALS_KUBERNETES_CRD_GROUP` | `openwebui.com` | CRD group watched by the operator backend |
 | `TERMINALS_KUBERNETES_CRD_VERSION` | `v1alpha1` | CRD version watched by the operator backend |
 
 Any value omitted here falls back to the default shown. See [`config.py`](https://github.com/open-webui/terminals/blob/main/terminals/config.py) for the authoritative list.
 
 ## Important Behavior
 
-Policy changes apply to newly provisioned terminals. Existing running terminals keep their current image and environment until they are stopped, refreshed, or cleaned up by idle timeout.
+Policy changes apply to newly provisioned workspaces. Existing running workspaces keep their current image and environment until they are stopped, refreshed, or cleaned up by idle timeout.
 
 The visual file-browser boundary is for usability. Open Terminal reports a root path that clients can render as `Home` and use to hide parent folders, but it is not a security boundary.

docs/features/open-terminal/terminals/orchestration/policies.md

@@ -5,27 +5,29 @@ title: "Policies"
 
 # Policies
 
-A policy describes what a user's Open Terminal container should look like. It controls the image, resources, storage, environment variables, and idle timeout.
+A policy describes what a user's Open Terminal workspace should look like. It controls the image, tools, resources, storage, environment variables, security context, and idle timeout.
+
+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.
 
 ## Policy Fields
 
 | Policy field | Example | What it controls |
 | :--- | :--- | :--- |
-| `image` | `ghcr.io/acme/open-terminal:python` | Open Terminal image used for new containers |
+| `image` | `ghcr.io/acme/open-terminal:python` | Open Terminal image used for new workspaces |
 | `cpu_limit` | `2` or `500m` | CPU limit passed to Docker/Kubernetes |
 | `memory_limit` | `4Gi` | Memory limit passed to Docker/Kubernetes |
 | `storage` | `10Gi` | Persistent file storage on Kubernetes; Docker stores files under the orchestrator data dir. On Docker the cap is best-effort: it limits only the writable layer via `StorageOpt` and needs a quota-capable driver (overlay2 on XFS with `pquota`), and `/home/user` is bind-mounted and not quota-limited. Use a Kubernetes backend for hard storage caps |
 | `storage_mode` | `per-user` | Kubernetes storage mode: `per-user`, `shared`, or `shared-rwo` |
-| `env` | `OPENAI_API_KEY=sk-...` | Raw environment variables injected into the user container |
-| `idle_timeout_minutes` | `30` | Idle time before the terminal is stopped and removed |
+| `env` | `OPENAI_API_KEY=sk-...` | Raw environment variables injected into the user workspace |
+| `idle_timeout_minutes` | `30` | Idle time before the workspace is stopped and removed |
 | `restricted` | `true` | Run under a restricted security context (Kubernetes/OpenShift backends) |
 | `pod_security_context` | `{"fsGroup": 1000}` | Kubernetes pod `securityContext` overrides (Kubernetes/OpenShift backends) |
 | `container_security_context` | `{"runAsNonRoot": true}` | Kubernetes container `securityContext` overrides (Kubernetes/OpenShift backends) |
 
 All fields are optional. If a field is omitted, the orchestrator uses its global default, such as `TERMINALS_IMAGE` or `TERMINALS_KUBERNETES_STORAGE_MODE`.
 
-Policy changes apply when a terminal is newly provisioned. Existing running terminals keep their current image and environment until they are stopped, refreshed, or cleaned up by idle timeout. Open WebUI is an admin client for this policy state; Terminals remains the source of truth for both policy and lifecycle configuration.
+Policy changes apply when a workspace is newly provisioned. Existing running workspaces keep their current image and environment until they are stopped, refreshed, or cleaned up by idle timeout. Open WebUI is an admin client for this policy state; Terminals remains the source of truth for both policy and lifecycle configuration.
 
 Scheduled resets are configured through policy lifecycle, not policy fields. This keeps provisioning settings separate from ongoing maintenance.