refac

docs/ecosystem/computer/_category_.json

@@ -1,5 +1,5 @@
 {
-	"label": "Open WebUI Computer (cptr)",
+	"label": "Open WebUI Computer",
 	"position": 36,
 	"collapsible": true,
 	"collapsed": true

docs/ecosystem/computer/agents/_category_.json

@@ -0,0 +1,10 @@
+{
+	"label": "AI and coding agents",
+	"position": 20,
+	"collapsible": true,
+	"collapsed": true,
+	"link": {
+		"type": "generated-index",
+		"description": "Choose, connect, supervise, and safely use an AI agent in the workspace already on your machine."
+	}
+}

docs/ecosystem/computer/agents/capabilities.md

@@ -0,0 +1,35 @@
+---
+title: Skills, memory, sub-agents, web, voice, and images
+sidebar_position: 5
+---
+
+# Extend an agent’s useful context
+
+## Use this when
+
+Rina repeats a workflow, wants the agent to remember durable project facts, needs parallel investigation, or wants to supply web, voice, or image input rather than typing everything.
+
+## Before you start
+
+- Connect any required model, search, speech, image, browser, MCP, or OpenAPI provider in Settings.
+- Decide whether the task may leave the host: web search, hosted speech/image APIs, and browser automation have their own external endpoints.
+- Keep reusable skills in a workspace when they are project-specific; use global skills only for instructions you want available everywhere.
+
+## Do it
+
+1. Add a `SKILL.md` to the workspace or a configured global location; type `$` in chat to mention a discovered skill.
+2. Enable Memory in Settings when durable user/project facts should be recalled in future chats. Review, edit, or delete memories there.
+3. Ask for parallel investigation only when each subtask is independent; sub-agent work is represented as inspectable chat work.
+4. Use web search/browser tools for current external facts, voice for hands-free chat or memos, and image features for supported image input or generation/editing.
+
+## Verify it worked
+
+A skill appears in the `$` suggestions and its instructions affect the next task. Memory items are visible in the Memory view. A sub-agent produces a distinct result/chat; web/browser, voice, or image output appears as a tool/result row or saved workspace artifact.
+
+## If it did not
+
+Check the file is named `SKILL.md` and is in a discovered scope, then start a chat with real prior context before trying skill authoring. For memory, confirm it is enabled and review settings. For media/web failures, check the configured endpoint/credential and the host’s browser availability.
+
+## Trust boundary
+
+Skills are executable guidance, not harmless labels: they can steer an agent toward tools. Sub-agents receive full tool access for their workspace task. Web, browser, speech, and image integrations can disclose prompt content or captured data to their configured providers.

docs/ecosystem/computer/agents/continuity.md

@@ -0,0 +1,44 @@
+---
+title: Plans, queues, resume, and context
+sidebar_position: 4
+---
+
+# Plans, queues, resume, and context
+
+The useful part of remote work is continuity: you can leave a task, reconnect on another device, and see the chat, workspace layout, terminal output, and next action without reconstructing the situation.
+
+## Use this when
+
+Rina starts an investigation before leaving her desk, or Jules needs to steer a long-running agent task from a smaller screen.
+
+## Before you start
+
+- Use a named workspace rather than an ad-hoc directory.
+- Know whether new messages should **queue** behind a response or **interrupt** it; the choice is in General settings.
+- For a risky request, turn on Plan mode before sending it.
+
+## Do it
+
+1. Send the task; use the visible task list to track pending and in-progress work.
+2. Queue a concise follow-up instead of opening a duplicate chat. Cancel only when the present task should stop.
+3. Close the browser and reopen the same workspace/chat from another device. Reconnect to terminal or command-session output as needed.
+4. When the conversation becomes long, use the context indicator and compact the chat when necessary. Compaction summarizes older context so the agent can continue inside the selected model’s limit.
+5. Fork from a message when you want to explore an alternative without overwriting the original branch.
+
+## Verify it worked
+
+The same workspace URL restores its tabs/layout, the chat shows its prior messages and task state, and an active terminal replays recent scrollback after reconnect. After compaction, the chat reports lower context use while retaining a summary for subsequent turns.
+
+## If it did not
+
+Refresh the chat or use the sidebar to reopen it; if a command is still running, open its command session rather than starting it again. If a task is stuck after an app restart, inspect its partial output and either resume with a new bounded request or cancel it. A terminal session survives browser disconnects, not a host restart or process exit.
+
+| What happened | What to expect | Recover by |
+| --- | --- | --- |
+| Browser disconnect | Workspace layout, chats, and a running terminal can reconnect. | Reopen the same workspace and chat; open the existing terminal or command session. |
+| Host restart | Terminal and browser sessions end; in-flight work may have partial output only. | Inspect chat status and partial output, then resend a bounded continuation or restart the command deliberately. |
+| Provider interruption | The chat can retain the partial response, but the provider request does not resume itself. | Check the visible error, then resend a small continuation that names the next action. |
+
+## Trust boundary
+
+Persistence is state continuity, not a backup or a guarantee that external providers, host processes, or browser sessions survive a reboot. Context compaction sends/uses a summary with the selected model; do not treat it as deletion of the underlying chat history.

docs/ecosystem/computer/agents/models.md

@@ -0,0 +1,38 @@
+---
+title: API models or native coding agents
+sidebar_position: 1
+---
+
+# API models or native coding agents
+
+Open WebUI Computer can run an agent through an API connection, or through a coding agent already installed and signed in on the host. Both work in the selected workspace. The choice is about credentials and control, not a different filesystem.
+
+## Use this when
+
+Rina has an OpenAI, Anthropic, Ollama, or OpenAI-compatible endpoint and wants a model to inspect or change her project. Jules already pays for Codex or Claude Code and wants that subscription to work in the browser without adding an API key.
+
+## Before you start
+
+- Open a workspace that contains the files the agent should work on.
+- For an API model, have its base URL and credential ready.
+- For a native coding agent, install and sign in to its CLI on the same host that runs Open WebUI Computer.
+
+## Do it
+
+1. Add an API connection in **Settings → Connections**, or add a native profile in **Settings → Admin → Agents**.
+2. Pick the resulting model in the chat model selector.
+3. Start with a bounded request: “Read `README.md` and explain the test command. Do not change files.”
+
+Use an API model when you need a provider or local endpoint that is not one of the installed coding-agent backends. Use a native profile for Codex, Claude Code, Cursor, Grok, OpenCode, Cline, or Pi when the host already has its subscription and login. Native profiles are host programs: they can expose the models available to that account and may have their own provider-side permissions.
+
+## Verify it worked
+
+The chosen model appears in the selector and the response identifies a real file in the active workspace. A native profile also shows a ready detection result before you select it.
+
+## If it did not
+
+For API models, recheck the connection URL, credential, and model name in **Connections**. For native models, follow [set up and detect a coding agent](./setup-and-detection); a model that is missing from the selector is not a workspace problem.
+
+## Trust boundary
+
+An API model sends the prompt, selected context, and tool results to its provider. A native agent runs on the host under its installed login. Either can receive workspace content and can be allowed to invoke tools, so use only providers and host accounts you trust.

docs/ecosystem/computer/agents/setup-and-detection.md

@@ -0,0 +1,42 @@
+---
+title: Set up and detect a coding agent
+sidebar_position: 2
+---
+
+# Set up and detect a coding agent
+
+Native profiles connect the browser UI to a coding-agent command already present on the Computer host. Detection checks the command, its version, required local dependency where applicable, and whether models can be discovered.
+
+## Use this when
+
+Jules has a Codex, Claude Code, Cursor, Grok, OpenCode, Cline, or Pi subscription and wants to use it from a Computer chat in the same repository.
+
+## Before you start
+
+- Install the agent CLI and complete its normal login on the host, not merely on the phone or browser you will use later.
+- Know the executable path if it is not on `PATH`.
+- Open **Settings → Admin → Agents** as an administrator.
+
+## Do it
+
+1. Add or edit the profile for the agent.
+2. Set its command path; set the agent-specific home path only when the profile needs a non-default login/configuration directory.
+3. Run detection, then save the profile after it reports **ready**.
+4. Select one of its discovered models in a workspace chat and send a small read-only request.
+
+Detection is deliberately separate from starting a task: it prevents a remote browser session from discovering halfway through work that its host command or login is unavailable.
+
+## Verify it worked
+
+The profile reports **ready**, with the resolved command/version and available models where that backend can discover them. The selected model streams a response in the workspace chat.
+
+## If it did not
+
+- **Command not found:** install the CLI or provide its absolute executable path.
+- **Missing dependency:** install the dependency named in the result; Claude Code additionally requires its local SDK support.
+- **Auth unknown/no models:** run the agent’s normal login or provider configuration on the host, then detect again.
+- **Unsupported app-server capability:** update the agent CLI and rerun detection.
+
+## Trust boundary
+
+Detection starts local commands to inspect their version and capability. A ready profile confirms local availability, not that a task is safe: the agent still receives the active workspace and can be given host tool permissions.

docs/ecosystem/computer/agents/supervise-work.md

@@ -0,0 +1,39 @@
+---
+title: Supervise agent work safely
+sidebar_position: 3
+---
+
+# Supervise agent work safely
+
+Open WebUI Computer keeps the agent beside the files, terminal, git view, and task state it is acting on. Use it to make the review loop visible, especially when you are away from the host.
+
+## Use this when
+
+Jules wants an agent to investigate a bug from a phone, while retaining the ability to inspect a diff, answer a question, or stop the task before it turns into a broad rewrite.
+
+## Before you start
+
+- Select the correct workspace and model.
+- Choose an approval mode in the chat controls: **ask**, **auto**, or **full**.
+- Start with a precise goal and an explicit boundary, such as “inspect and propose a fix; do not commit or push.”
+
+## Do it
+
+1. Use **Plan mode** for unfamiliar or high-impact work. It instructs the agent to research with read-only tools and wait for explicit approval before implementation.
+2. Watch tool rows, task progress, and resulting files or git diff.
+3. Approve, reject, or cancel a pending action. Send a follow-up while the agent is working; the default queue can preserve it for the next turn.
+4. Review changes in the editor or Git panel before committing or pushing.
+
+**Ask** pauses tool actions for your decision. **Auto** reduces routine prompts according to the selected agent/tool behavior. **Full** is only for work you are willing to let proceed with no interactive gate. Native coding agents may also show their own approval request because their host protocol has a separate permission model.
+
+## Verify it worked
+
+In plan mode, the agent produces a plan and does not edit a file before you approve implementation. In ask mode, a pending tool request is visible and only runs after you choose. After a task, the Git panel or file editor shows exactly what changed.
+
+## If it did not
+
+Cancel the active task to preserve partial output, lower the approval mode to **ask**, and restate the workspace boundary. If an expected approval never appears, inspect the selected native profile’s permission configuration; it may be operating under its own agent policy.
+
+## Trust boundary
+
+Computer is not a sandbox. A terminal and `run_command` execute with host access. Its built-in file tools scope ordinary file operations to the workspace and avoid `.env` reads/writes, but that does not constrain shell commands or a separately configured native agent. Do not grant **full** approval to unreviewed prompts, untrusted workspaces, or a public/shared instance.

docs/ecosystem/computer/capabilities.md

@@ -1,41 +1,20 @@
 ---
-title: "Capabilities"
-sidebar_position: 2
+title: "What Open WebUI Computer can do"
+sidebar_position: 5
 ---
 
-# Capabilities
+# What Open WebUI Computer can do
 
-Everything Open WebUI Computer gives you, grouped by what it is for. The [overview](/ecosystem/computer) has the short version; this is the full list.
+This is a map to the documentation, not a feature checklist. Start with the job you need to complete; each guide explains the prerequisites, verification, and trust boundary.
 
-## The computer you operate
+| Need | Documentation |
+| --- | --- |
+| Reach the same workspace, terminal, and git state from another device | [Your workspace](./workspace/workspace-paths) and [remote access](./remote-access/security-model) |
+| Let an AI or coding-agent subscription work in a real repository | [AI and coding agents](./agents/models) |
+| Review an agent, a diff, or a local service while away | [Use cases](./use-cases/malik-agent-supervision) |
+| Keep a task running and hear about the result | [Automations and notifications](./integrations/automations-and-notifications) |
+| Work from Open WebUI while the action happens in Computer | [Use Open WebUI with a Computer workspace](./integrations/open-webui-gateway) |
+| Give an agent a vetted external capability | [MCP and OpenAPI tool servers](./integrations/messaging-and-tools) |
+| Run, secure, back up, or repair the service | [Operations](./operate/data-and-backups) and [troubleshooting](./troubleshooting/install-and-login) |
 
-- **Terminal.** A real PTY-backed shell in the browser (macOS, Linux and Windows). Anything you would do over SSH.
-- **File browser and editor.** Navigate, view, edit and manage files, with icons by type. Markdown previews inline.
-- **Git, without the command line.** See status, stage and commit from a git panel, manage branches (create, rename, delete and search) with stash-aware switching, or drop into the terminal if you prefer.
-- **Workspaces.** Manage several project directories from one instance and switch between them without losing your place.
-- **Global search and shortcuts.** `Cmd+K` / `Cmd+Shift+F` searches chats (by id, title, summary and message content, best matches ranked first) and files (by name) across every workspace, with optional filtering by workspace and whether to include sub-agent chats, plus a customisable keybinding system.
-- **Port preview.** A built-in reverse proxy detects ports your processes open, so you can preview a running app in another tab.
-- **System info.** A "System info" entry in the sidebar menu opens a modal showing the machine's hostname, OS, CPU, memory, disk and running processes.
-- **Voice memos.** Record audio from the `+` menu or `Cmd+Shift+M`. Recordings save to the workspace as audio files with an auto-generated transcript, via any OpenAI-compatible speech-to-text API (Whisper and similar), configured in Settings > Audio.
-- **Installable app (PWA).** Install Open WebUI Computer to a phone, tablet or desktop home screen for a standalone, app-like experience, with offline caching and a fallback page when the server is unreachable. Home screen shortcuts jump straight to a new chat, workspace, note, terminal or search, a share target sends files, text or links from other apps into a chat, and opening a supported file with Open WebUI Computer imports it into a workspace you choose. Manage install status and the offline cache from Settings > PWA.
-
-## The AI agent (optional)
-
-- **Optional AI agent.** A chat panel with multi-provider support (Anthropic, OpenAI, Ollama and OpenAI-compatible endpoints). With a key it reads, searches and edits files, runs shell commands, searches the web and reads URLs. It also reads and describes images in your workspace and can drive a real browser (navigate, click, type, screenshot, run JavaScript) via local Chrome, Firecrawl or Browser-Use. Web search runs through Exa, Tavily, Brave, DuckDuckGo, Perplexity (with a configurable base URL for proxies such as LiteLLM), Firecrawl (with a self-hosted endpoint option) or any OpenAI-compatible endpoint. For bigger tasks it can draft an implementation plan to approve before it starts (plan mode), and long conversations are compacted automatically, with a context-usage indicator showing how full the window is. Every edit or command waits for your approval, and its file tools refuse to read or write `.env` files. Mention files with `@` and queue follow-up messages while it works.
-- **Coding agents as backends.** Connect coding agents you already subscribe to as native AI backends, configured from the **Agents** admin tab where you set the command path, the model list and an approval/permission mode (install status and auto-detect are shown). Supported: Codex, Claude Code, Cursor, Grok and OpenCode. They appear as selectable models, run in the workspace with full tool access and resume across sessions. 0.7.1 added live streaming output and approval-request handling.
-- **Voice mode and text-to-speech.** Talk to the AI hands-free: tap the voice button, speak, and Open WebUI Computer transcribes your message, sends it and reads the reply back aloud, re-arming the mic for a back-and-forth. Connect any OpenAI-compatible TTS API in Settings > Audio, pick a voice and a playback speed (0.5x to 2x), or click the speaker on any message to hear it. An auto-stream toggle in Settings > Audio reads each AI response aloud as it arrives.
-- **Reasoning display.** Models that think before answering (such as o3 or Claude with extended thinking) show their reasoning as collapsible steps in the chat. Tool calls and reasoning render as compact, groupable rows with live status.
-- **Memory.** The AI remembers facts about you and your projects, stored per user and per workspace and pulled into future conversations automatically. View, edit and delete them from the Memory tab in Settings. Admins can enable background memory review, which lets the AI pick up preferences and patterns quietly as you chat. Memories are stored as an organized Markdown "memory vault" the AI can link, move, split and merge to keep things tidy.
-- **Image generation and editing.** Ask the AI to create or edit images right in the chat. Results save to your workspace and display inline. Works with any OpenAI-compatible image API, configured in the Images admin tab.
-- **Tool servers.** Connect external tools over MCP or OpenAPI from the Tool Servers admin tab (bearer auth and custom headers supported). Once verified, the AI uses them alongside its built-in tools.
-- **Sub-agents and parallel tools.** The AI can spin up sub-agents that work on tasks in parallel, each with full tool access and inspectable afterwards as its own chat. Multiple tool calls in a single response also run concurrently. Sub-agents can also run in the **background**: the AI kicks off a long task, keeps chatting with you and brings the results back when they are done (labeled as a background sub-agent). Set concurrency and limits in the Subagents admin tab.
-- **Skills.** Drop reusable `SKILL.md` instruction sets in a workspace or globally. The AI discovers them and loads them on demand, and you can pull one in with `$` in the chat input.
-- **Model configuration.** Set parameters and a system prompt per model or as a global default, and pick a **default model** (Settings > Models) that new chats and gateway requests use automatically. System prompts take `{{VARIABLE}}` placeholders (workspace name, file tree, OS, date, skills, plus runtime environment, hostname, platform, architecture, shell, home directory and Open WebUI Computer version), and a workspace `.cptr/system.md` file overrides the prompt for that project.
-
-## Automation and reach
-
-- **Automations.** Schedule recurring tasks on a timer, or ask the AI to set one up. Each automation runs as a real chat with full tool access, and can alert you when it finishes by browser notification or a webhook (Slack, Discord, Teams).
-- **Messaging bots.** Connect the AI to Telegram, Discord, Slack, WhatsApp or Signal from Settings. Each bot has full tool access, streams its replies and syncs the conversation back to the web UI. Send `/workspace` to switch projects and `/new` to start a fresh chat.
-- **OpenAI-compatible gateway.** Expose each workspace as a model over `/v1/models` and `/v1/chat/completions`, so Open WebUI or any OpenAI-compatible client can drive the full Open WebUI Computer agent loop as if it were a model. See [**Connect to Open WebUI**](/ecosystem/computer/open-webui) for setup and the first-class Open WebUI integration (branching, background-task filtering).
-
-Chats are stored as files too, so your AI conversations are searchable, editable and commit-able alongside your code.
+Every capability is tied to the same boundary: it acts on the machine and workspace you select. Read the [security model](./remote-access/security-model) before enabling remote or unattended access.

docs/ecosystem/computer/choose.md

@@ -0,0 +1,46 @@
+---
+title: "Open WebUI, Open WebUI Computer, or both?"
+sidebar_position: 2
+---
+
+# Open WebUI, Open WebUI Computer, or both?
+
+Choose the product that owns the thing you need to do—not the product with the longest feature list.
+
+| Your starting point | Choose | Why |
+| --- | --- | --- |
+| “Which model, knowledge, prompt, tool, or AI workflow should I use?” | **Open WebUI** | Open WebUI is the AI interface and workflow platform, whether you use it alone or with a group. |
+| “The answer is in my machine’s checkout, dirty files, terminal, local service, credentials, or agent session.” | **Open WebUI Computer** | Computer gives one owner their existing machine and workspace in a browser. AI is optional. |
+| “I want Open WebUI as the familiar AI front door, but the work must happen in this particular repository.” | **Both** | This is the recommended combined workflow: the Computer gateway presents an accessible workspace as an OpenAI-compatible model to Open WebUI. |
+
+## Jules’s choice: use both
+
+Jules keeps her research and model selection in Open WebUI. Her Mac has the cloned docs repository, scripts, browser login, and local state that an AI must use. She connects that Computer workspace through the gateway, chooses it in Open WebUI, and asks for a narrowly scoped local task.
+
+Use both whenever you want Open WebUI's model, knowledge, prompt, and conversation experience **and** want the answer to be grounded in a real machine. Open WebUI is the place to decide and converse; Open WebUI Computer is the place where the selected workspace, terminal, git state, and agent activity actually live.
+
+**Verify it worked:** the workspace appears in Open WebUI's model picker; the request creates visible activity in the selected Computer workspace; a follow-up continues that same Computer chat when the documented headers are configured.
+
+**If it did not:** verify the gateway key and `/v1` base URL, confirm the workspace is available, then add the [header template and continuity checks](./integrations/open-webui-gateway).
+
+## Important boundary
+
+The gateway exposes workspaces as OpenAI-compatible models. It does **not** synchronize Open WebUI chats, knowledge bases, users, or general configuration into Open WebUI Computer. The products can work together without becoming the same application.
+
+## Shared AI space vs your personal computer
+
+Open WebUI is built around the question, “How do I use AI well?” It is where one person or a group can work with models, knowledge, prompts, tools, and AI workflows.
+
+Open WebUI is useful as a personal AI workspace, and its potential expands naturally when a team shares models, knowledge, and workflows. Open WebUI Computer is different by design: its full potential is personal continuity—one owner reaching the particular machine where their work is already alive.
+
+Open WebUI Computer is built around the question, “How do I reach **my** real machine and direct work there?” It is intentionally high-trust and personal: an authenticated user can reach the host filesystem and shell. It does not provide a safe, isolated machine for each teammate.
+
+The loose mental model is **ChatGPT versus Codex**. A chat product is where you ask, compare, and organize AI help—alone or with others. A coding-agent product works inside your project and environment. Open WebUI Computer is broader than coding, but it follows the second model: it is about doing work in the machine you already own, not moving that work into a chat surface.
+
+**Verify the fit:** if you would be comfortable giving the person access equivalent to an SSH login on the host, Computer may fit. If you need to give many people safely separated access, choose a team-oriented, isolated platform instead.
+
+## Choose your next guide
+
+- Need the machine itself? [Try Open WebUI Computer locally](./getting-started/local-trial).
+- Want the combined workflow? [Connect Open WebUI to a Computer workspace](./integrations/open-webui-gateway).
+- Need an agent in a real repository? [Choose an AI backend](./agents/models).

docs/ecosystem/computer/concepts.md

@@ -0,0 +1,34 @@
+---
+title: "Core concepts"
+sidebar_position: 3
+---
+
+# Core concepts
+
+Open WebUI Computer is easiest to understand when you separate the machine from the view of that machine.
+
+| Term | Meaning |
+| --- | --- |
+| **Host** | The macOS, Linux, or Windows machine where Open WebUI Computer runs. Its filesystem and shell are the real ones. |
+| **Instance** | One running Open WebUI Computer server and its local application state. |
+| **User** | A person authenticated to that instance. App users do not make the host a sandbox or grant isolation from the host account. |
+| **Workspace** | An existing directory on the host. It has a path, name, and remembered browser layout for each user. |
+| **Tab and layout** | The saved working view: files, chats, terminals, browser sessions, and split panes. |
+| **Terminal session** | A PTY-backed shell that can keep running after the browser tab closes. |
+| **Chat** | A workspace-associated conversation that can use an AI provider or native coding agent. |
+| **Native agent** | A locally installed coding-agent CLI, such as Codex or Claude Code, selected as an AI backend. |
+| **Gateway** | The optional `/v1` interface that lets Open WebUI or another OpenAI-compatible client drive a selected workspace. |
+
+## The important mental model
+
+Open WebUI Computer does not reconstruct a project somewhere else. It reconnects you to the host and directory you chose. That is why Nora can see the same dirty branch from her phone, and why Malik can continue an agent session that started at his desk.
+
+## Verify it worked
+
+Open any workspace, create a terminal, close the browser tab, and open the same workspace again. The terminal tab and its output should still be available.
+
+If the workspace or session is missing, first confirm that you reopened the same host and workspace path; then use [workspace troubleshooting](./troubleshooting/access-and-workspaces).
+
+## Trust boundary
+
+A workspace is a useful organizing surface, not a security sandbox. The terminal and authenticated user can access the host according to the host account's permissions. Read [the security model](./remote-access/security-model) before making the instance remotely reachable.

docs/ecosystem/computer/getting-started/_category_.json

@@ -0,0 +1,8 @@
+{
+	"label": "Get started",
+	"position": 1,
+	"link": {
+		"type": "generated-index",
+		"description": "Try Open WebUI Computer on the machine and workspace you already use."
+	}
+}

docs/ecosystem/computer/getting-started/air-gapped.md

@@ -0,0 +1,51 @@
+---
+title: Air-gapped installation
+sidebar_position: 4
+---
+
+# Air-gapped installation
+
+## Use this when
+
+Your host cannot reach the internet, but a connected staging machine can download release artifacts for transfer.
+
+## Before you start
+
+Bring a Python wheelhouse or the Docker image from a connected machine. Open WebUI Computer itself runs locally after installation; hosted models, Git remotes, web search, messaging services, and external MCP/OpenAPI servers still need reachable endpoints.
+
+## Do it
+
+On a connected machine:
+
+```bash
+pip download --dest wheelhouse 'cptr[all]'
+docker pull ghcr.io/open-webui/computer:latest
+docker save ghcr.io/open-webui/computer:latest -o cptr-image.tar
+```
+
+Transfer the artifacts. On the offline host, either install from the wheelhouse:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install --no-index --find-links ./wheelhouse 'cptr[all]'
+cptr run
+```
+
+Or load and run the saved image with `docker load -i cptr-image.tar`, then the [Docker command](./docker) with `--network=none`.
+
+## Verify it worked
+
+Disconnect the host from the network, start the server, and request `http://127.0.0.1:8000/api/health`. Open the local URL and browse a workspace. The health response and local files must work without DNS or internet connectivity.
+
+## If it did not
+
+If pip tries to contact an index, confirm both `--no-index` and `--find-links ./wheelhouse` are present and that the transferred wheelhouse contains dependencies for the offline host's platform. If an AI or integration fails, determine whether it requires an external endpoint rather than retrying the local install.
+
+## Trust boundary
+
+Offline installation removes a network dependency; it does not remove host access. Review artifacts and transfer media according to your organization's software-supply policy.
+
+## Not a fit
+
+This is not an offline AI guarantee. Choose a locally reachable model and local tools if the work must never leave the network; hosted providers and remote integrations cannot work without a route to them.

docs/ecosystem/computer/getting-started/docker.md

@@ -0,0 +1,45 @@
+---
+title: Docker
+sidebar_position: 3
+---
+
+# Run with Docker
+
+## Use this when
+
+You want a repeatable app runtime while deliberately choosing the host directories Open WebUI Computer can see. The project mount is still real host data.
+
+## Before you start
+
+Install Docker on the host. Pick a writable persistent volume for application state and a project directory you are comfortable exposing to the container.
+
+## Do it
+
+From the project directory:
+
+```bash
+docker run --rm -it \
+  -p 8000:8000 \
+  -v cptr-data:/data \
+  -v "$PWD:/workspace" \
+  -w /workspace \
+  ghcr.io/open-webui/computer:latest
+```
+
+Open the tokenized URL printed in the logs. `/data` holds the app database and configuration; `/workspace` is the project available inside the container.
+
+## Verify it worked
+
+Run `docker volume inspect cptr-data`, then open `/workspace` in the setup wizard. In a terminal tab, `pwd` reports `/workspace` and `git status` reports the same checkout you mounted. `curl http://127.0.0.1:8000/api/health` returns `status: ok` from the host.
+
+## If it did not
+
+If state disappears, verify that `-v cptr-data:/data` is present. If startup cannot write `app.db` with a bind-mounted `/data`, fix ownership or choose a Docker-managed volume; host permissions override the image defaults. For container-specific recovery, see [Docker and state troubleshooting](/ecosystem/computer/troubleshooting/docker-and-state).
+
+## Trust boundary
+
+The container can read and modify every mounted directory and can run commands there. Docker narrows the view only to what you mount; it does not make an untrusted user safe.
+
+## Not a fit
+
+Docker is useful for repeatable operation, not for safely offering a shared hosted shell. If you need separate tenants, policy-enforced project isolation, or public SaaS access, Open WebUI Computer is not that service.

docs/ecosystem/computer/getting-started/first-workspace.md

@@ -0,0 +1,32 @@
+---
+title: Your first workspace
+sidebar_position: 6
+---
+
+# Open your first workspace
+
+**Persona:** Nora needs a real answer to “am I looking at the checkout that has the bug?”, not a disposable cloud copy.
+
+## Use this when
+
+The server is running and you need to complete first-time setup around an existing project.
+
+## Before you start
+
+Know the folder you want to expose. Choose a small non-sensitive project first if you are learning the interface. An AI connection is optional and can be skipped in the setup wizard.
+
+## Do it
+
+Use the wizard's **Open folder** step to select the project, then either connect an AI provider or choose **Skip**. Finish setup. Create a terminal tab, inspect a file, and open the Git view.
+
+## Verify it worked
+
+The workspace path is visible in the sidebar. In its terminal, `pwd` identifies that path and `git status` shows the branch and changes you see in your regular shell. Close the browser tab, reopen the server URL, and verify the workspace remains available.
+
+## If it did not
+
+If the folder picker cannot reach the project, run the server under the OS account that owns or can read that folder. If the wrong workspace opens, use the workspace picker to add the intended path instead of moving files into the data directory.
+
+## Trust boundary
+
+Adding a workspace makes its files available to the signed-in user and to any configured AI or integration acting in that workspace. It does not copy the project into a protected sandbox.

docs/ecosystem/computer/getting-started/index.md

@@ -0,0 +1,19 @@
+---
+title: Get started with Open WebUI Computer
+sidebar_position: 1
+---
+
+# Get started
+
+Start locally. The first useful proof is not an AI demo: open an existing project and see its real files, terminal, and git state in the browser. You can add an AI provider or private remote access later.
+
+| If you need to… | Start here |
+| --- | --- |
+| Try it on the machine in front of you | [Local trial](./local-trial) |
+| Run it in a container with an explicit project mount | [Docker](./docker) |
+| Install where internet access is unavailable | [Air-gapped installation](./air-gapped) |
+| Set up a Windows host | [Windows](./windows) |
+| Choose a real project and finish first-time setup | [Your first workspace](./first-workspace) |
+| Make it feel like an app or update safely | [PWA and updates](./pwa-and-updates) |
+
+Open WebUI Computer is deliberately useful without an AI connection. AI setup is covered separately in [AI and coding agents](/ecosystem/computer/agents/models).

docs/ecosystem/computer/getting-started/local-trial.md

@@ -0,0 +1,47 @@
+---
+title: Local trial
+sidebar_position: 2
+---
+
+# Local trial
+
+**Persona:** Nora, a Rails consultant, wants to see the actual `payments` branch and terminal on her iMac before she entrusts it to another screen.
+
+## Use this when
+
+You want to prove Open WebUI Computer works with an existing machine and project before exposing it to another device, adding AI, or configuring Docker. Its value is continuity: instead of re-cloning a repo into a cloud IDE or reconstructing a terminal, you pick up the files, branch, process, and shell already on this computer.
+
+## Before you start
+
+Use Python 3.10 or newer on the host. Install into the Python environment you intend to keep. This command starts on `127.0.0.1`, so it is not reachable from another device.
+
+## Do it
+
+```bash
+pip install cptr
+cptr run
+```
+
+Open the one-time URL printed by the command. Complete the setup wizard, choose an existing project folder, and open a terminal tab. `cptr run --headless` is useful on a host that should not open a local browser.
+
+## Verify it worked
+
+In a second terminal on the host, run:
+
+```bash
+curl http://127.0.0.1:8000/api/health
+```
+
+It returns JSON with `"status":"ok"`. In the browser, the selected workspace shows its existing files; run `pwd` and `git status` in its terminal and compare them with your normal shell.
+
+## If it did not
+
+If `cptr` is not found, activate the Python environment where it was installed or run `python -m pip install cptr` there. If the port is occupied, choose another one: `cptr run --port 8001`. See [install and login troubleshooting](/ecosystem/computer/troubleshooting/install-and-login).
+
+## Trust boundary
+
+Local mode still exposes the host filesystem and shell to anyone who can use the signed-in browser profile. Do not treat it as a sandbox; it is your real machine.
+
+## Not a fit
+
+Choose a cloud development environment when you need an isolated disposable machine, or a shared team platform when untrusted people need separate accounts and filesystem boundaries. Open WebUI Computer is for one trusted owner reaching their own machine.

docs/ecosystem/computer/getting-started/pwa-and-updates.md

@@ -0,0 +1,32 @@
+---
+title: PWA and updates
+sidebar_position: 7
+---
+
+# Install the app and update it
+
+## Use this when
+
+Theo wants a one-tap way back to the host from a phone, or you need to update a trusted single-host installation without losing its state.
+
+## Before you start
+
+Keep the data directory or Docker `/data` volume persistent. Read the release notes before changing a working host. PWA installation depends on browser and device support.
+
+## Do it
+
+Open Open WebUI Computer in the browser. Use the browser's **Install app** or **Add to Home Screen** action; on iPhone and iPad, use Safari's Share menu. PWA preferences appear in Settings when the app is installed.
+
+For a Python installation, stop the process, upgrade the same environment with `pip install --upgrade cptr`, then start `cptr run`. For Docker, pull the desired image and recreate the container with the exact same `/data` volume and project mounts.
+
+## Verify it worked
+
+The installed app opens the same instance and the existing workspace remains in the sidebar. After an update, Settings reports the expected version or the update notification is gone; `curl http://127.0.0.1:8000/api/health` still returns `status: ok`.
+
+## If it did not
+
+If the app opens a stale interface, reload once or remove and reinstall the PWA. If workspaces disappear after an update, stop and restore the original `~/.cptr` directory or `/data` volume before experimenting further; see [data and backups](/ecosystem/computer/operate/data-and-backups).
+
+## Trust boundary
+
+A PWA is another browser surface for the same machine. A phone home-screen icon does not add a new access-control layer.

docs/ecosystem/computer/getting-started/windows.md

@@ -0,0 +1,41 @@
+---
+title: Windows
+sidebar_position: 5
+---
+
+# Windows host setup
+
+## Use this when
+
+You are running Open WebUI Computer on a Windows workstation and want the same real files, terminal, and workspace available in the browser.
+
+## Before you start
+
+Install Python 3.10 or newer and ensure its Scripts directory is on `PATH`. Decide which Windows account should own the process: that account's permissions define what the terminal and file browser can access.
+
+## Do it
+
+In PowerShell:
+
+```powershell
+py -m pip install cptr
+cptr run
+```
+
+Open the URL printed by the command and select an existing project folder in the setup wizard.
+
+## Verify it worked
+
+Open a terminal tab and run `pwd` plus `git status` in the selected folder. In PowerShell on the host, run `Invoke-RestMethod http://127.0.0.1:8000/api/health`; it returns an object whose `status` is `ok`.
+
+## If it did not
+
+If creating a terminal reports `VCRUNTIME140.dll` or a Universal CRT DLL is missing, install Microsoft's [Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist), restart Open WebUI Computer, and retry. If `cptr` is not recognized, reopen PowerShell or invoke it with `py -m` from the environment where it was installed.
+
+## Trust boundary
+
+Open WebUI Computer operates with the rights of the Windows account that starts it. Do not use an administrator account merely to make a project easier to reach.
+
+## Not a fit
+
+Use a dedicated managed development environment if the job requires strict per-user Windows isolation. This app is a browser surface for the account and machine you choose.

docs/ecosystem/computer/index.md

@@ -9,7 +9,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 # Open WebUI Computer
 
 <ThemedImage
-  alt="Open WebUI Computer workspace running on a desktop screen and a phone, the same session across devices, with optional AI"
+  alt="Open WebUI Computer showing a real workspace from a desktop and phone"
   sources={{
     light: useBaseUrl('/images/banners/computer-light.svg'),
     dark: useBaseUrl('/images/banners/computer-dark.svg'),
@@ -17,99 +17,69 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
   style={{ width: '100%', margin: '0.25rem 0 1.75rem' }}
 />
 
-**Your computer, in a browser tab. From anywhere.**
+**Your actual computer, available from the browser you have with you.**
 
-Open WebUI Computer runs on a machine you own and serves the whole thing to a browser: files, a code editor, a terminal and git, all in one tab. Open it from your phone on the train, your laptop at a cafe, or a tablet on the couch. Push a hotfix, check a deploy, stage and commit, or drop into the terminal and work the old way. Close the tab and come back tomorrow on any device; sessions survive disconnects and everything is where you left it.
+Open WebUI Computer runs on a machine you control and gives you its real workspaces: files, terminal sessions, git state, local services, and optional AI agents. It does not copy your project into a new cloud environment. When you open a workspace from another device, you are looking at the same checkout, branch, process, and agent work that were already there.
 
-AI is built in but optional. Bring your own key and it becomes an agent that can read, search, edit and run things in your project. Leave the key out and Open WebUI Computer is still a full computer, just without the assistant.
+New here? Start with [Is Open WebUI Computer right for me?](./is-it-right) before learning any product terms.
 
-[**View on GitHub →**](https://github.com/open-webui/computer) · [**Read the Manifesto →**](https://github.com/open-webui/computer/blob/main/MANIFESTO.md)
+## Start with the problem in front of you
 
-:::info Separate product
-Open WebUI Computer is a **separate product** from Open WebUI, not a plugin or an integration. The [GitHub repo](https://github.com/open-webui/computer) is the source of truth for the latest.
-:::
+| If this sounds like you | Start here | You will know it worked when |
+| --- | --- | --- |
+| **Avery** has never used a terminal or git, but a project already lives on her laptop and she wants to understand whether Computer is useful before changing anything. | [Is Open WebUI Computer right for me?](./is-it-right) | She opens her existing folder locally and sees that Computer did not make a copy somewhere else. |
+| **Mira** is a product designer with a live prototype and assets on her Mac; she wants to test it on a real phone and capture feedback without learning a terminal workflow. | [Preview a local app on another device](./use-cases/theo-real-device-preview) | She sees the live prototype on the device and sends a note or link into the same project. |
+| **Nora** has ten minutes on a train to investigate a bug in the dirty branch on her home iMac. | [Fix something away from your desk](./use-cases/nora-remote-fix) | Your phone shows the existing branch, terminal output, and changed diff. |
+| **Malik** needs to decide what a coding agent should do while he is away from his mini PC. | [Supervise an agent from anywhere](./use-cases/malik-agent-supervision) | You can inspect the existing chat and continue the same task. |
+| **Theo** needs to check a local app on a real iPad. | [Preview a local app on another device](./use-cases/theo-real-device-preview) | The live app opens while its original terminal keeps running. |
+| **Jules** already uses Open WebUI but needs an AI to work in a particular machine and repository. | [Open WebUI, Computer, or both?](./choose) | You know which product owns the job and why. |
+| **Elena** needs a private machine to run a repeatable check and alert her when it fails. | [Run and verify an automation](./integrations/automations-and-notifications) | A manual run creates a linked chat and a test alert arrives. |
+| **Ravi** already runs private infrastructure, coding agents, and Open WebUI; he is excited to compose them around his own machine without giving up control of the workspace. | [Connect Open WebUI to a Computer workspace](./integrations/open-webui-gateway) | A bounded workspace appears as a model, with its real activity visible in Computer. |
 
-## Open WebUI Computer vs Open Terminal
+## Try it locally first
 
-These two look related because both involve a terminal and an AI, but they sit on opposite sides of the same idea. The short version: **[Open Terminal](/features/open-terminal) gives the Open WebUI chat AI a computer to work on; Open WebUI Computer gives _you_ your computer, with AI as an optional helper.**
-
-| | [Open Terminal](/features/open-terminal) | Open WebUI Computer |
-| :--- | :--- | :--- |
-| **What it is** | A shell-execution backend you connect to Open WebUI as a tool | A standalone app: your machine (files, editor, terminal, git) in a browser |
-| **Who drives** | The AI runs commands for you during a chat | You operate the machine; the AI assists when asked |
-| **Center of gravity** | Chat first. The terminal is a tool the model calls | Computer first. Chat is one panel beside files, editor and git |
-| **Runs as** | A component connected to an Open WebUI instance | Its own app (`pip install cptr`), not connected to Open WebUI |
-| **Interface** | The Open WebUI chat UI | A mobile-first workspace: file browser, editor, terminal, git |
-| **AI** | Required (it exists for the chat model to use) | Optional (bring your own key; works without it) |
-| **License** | MIT | Open Use License (source-available) |
-
-If you want the model to build software for you inside a chat, that is Open Terminal. If you want to _be_ at your computer from your phone, with the model as an extra pair of hands, that is Open WebUI Computer.
-
-## What you can do
-
-Open WebUI Computer is a full workspace with an optional AI agent on top:
-
-- **The computer you operate.** A browser-based terminal, file browser, code editor and git across multiple project workspaces, with global search, live port previews and voice memos.
-- **An optional AI agent.** With your own key it reads, edits and runs code, browses the web, uses external MCP/OpenAPI tool servers and spins up sub-agents, following skills you define. Every change waits for your approval.
-- **Coding agents as backends.** Connect a coding agent you already subscribe to (Codex, Claude Code, Cursor, Grok, OpenCode) as a native backend, no API key needed. It shows up in the model picker and runs in the workspace with full tool access.
-- **Automation and reach.** Scheduled automations, messaging bots (Telegram, Discord, Slack, WhatsApp, Signal) and an OpenAI-compatible gateway that lets Open WebUI drive a workspace as a model.
-
-See the [**full capability list**](/ecosystem/computer/capabilities), and [**Connect to Open WebUI**](/ecosystem/computer/open-webui) to use an Open WebUI Computer workspace as a model from your own Open WebUI instance.
-
-## Install and run
-
-Open WebUI Computer is distributed as a Python package named `cptr` (Python 3.10 or newer):
+The quickest safe trial stays on the machine in front of you. Install the `cptr` package, start it on localhost, and open one existing project before thinking about remote access or AI providers.
 
 ```bash
 pip install cptr
-```
-
-To pull in every optional dependency (MCP tool servers, document support, PAM login) at once, install the `all` extra instead: `pip install cptr[all]`.
-
-Start the server and it opens in your browser:
-
-```bash
 cptr run
 ```
 
-By default `cptr run` listens on `127.0.0.1`, so it is reachable only from the machine it runs on. To open it to other devices on your network, bind to all interfaces:
+[Try Open WebUI Computer locally →](./getting-started/local-trial)
 
-```bash
-cptr run --host 0.0.0.0
-```
+**Verify it worked:** the command prints a one-time setup URL. Open it on the host, finish setup, choose an existing folder, and create a terminal. If you cannot reach the page, use [install and login troubleshooting](./troubleshooting/install-and-login) before changing network settings.
 
-`cptr run` prints a one-time setup URL with a token, for example `http://localhost:8000/?token=...`. Other flags: `--port` (default `8000`), `--headless` (do not auto-open a browser) and `--reload` (for development).
+## What Open WebUI Computer is—and is not
 
-State lives in `~/.cptr` by default; set `CPTR_DATA_DIR` to change it. After first-time setup you log in with a username and password, and sessions use JWTs.
+It is a persistent workstation surface and an optional agent harness for the machine where your work already lives. It is useful even with no AI configured.
 
-For operations, Open WebUI Computer can write structured logs and an audit trail. Set `CPTR_AUDIT_LOG_LEVEL` to log every mutating API request (POST, PUT, PATCH, DELETE) to a JSON file with passwords and API keys redacted, and `CPTR_LOG_UPSTREAM_REQUESTS=true` to log outgoing AI API calls (provider, model, endpoint) to a separate file for debugging and cost tracking.
+It is not a disposable cloud IDE, a sandbox around an untrusted user, or a service to expose directly to the public internet. An authenticated user can access the host filesystem and shell, so treat it like an SSH endpoint you own.
 
-### Docker
+[Read the security model →](./remote-access/security-model) · [Learn the core concepts →](./concepts) · [See who it is for →](./personas)
 
-```bash
-docker run --rm -it \
-  -p 8000:8000 \
-  -v cptr-data:/data \
-  -v "$PWD:/workspace" \
-  -w /workspace \
-  ghcr.io/open-webui/computer:latest
-```
+## Use it with Open WebUI
 
-State is stored in `/data`. Mount the project you want to work on into the container with `-v "$PWD:/workspace"` so Open WebUI Computer can reach it. A `:dev` image tracks the `main` branch.
+Many people should use both products. Keep Open WebUI as the place to choose models, organize AI conversations, and work with knowledge. Connect Open WebUI Computer when the request must inspect or change the selected workspace on your own machine. The [gateway guide](./integrations/open-webui-gateway) shows the combined workflow and its high-trust boundary.
 
-## Security model
+## Open WebUI Computer vs Open Terminal
 
-:::danger Treat a shared Open WebUI Computer instance like an open SSH port
-Once a user is authenticated, Open WebUI Computer gives them **full access to the host filesystem and shell**, the same as an SSH session. There is **no path sandboxing and no per-user isolation**. The AI's file read and edit tools are confined to the active workspace, but shell access (the terminal, and the AI's run-command tool) is not.
-:::
+Both products can put AI near a terminal, but the starting point is different. **Open Terminal** gives an Open WebUI chat model a computing environment to drive. **Open WebUI Computer** gives you the existing computer you operate—files, terminal, editor, git, and running sessions—with AI as an optional helper.
 
-Open WebUI Computer is designed as "your computer, served to you", so that level of access is the point, not a flaw. It is safe **only** when both of these hold:
+Choose Open Terminal when the chat AI needs an execution environment. Choose Open WebUI Computer when you need to reach the machine where the work already exists.
 
-- you are the only user, and
-- you control the network it is exposed on.
+## Explore the documentation
 
-It is **not** safe if untrusted users share the instance, it is reachable from the public internet, or a reverse proxy in front of it forwards spoofable authentication headers. By default Open WebUI Computer binds to localhost only, so reaching it from another machine is an explicit opt-in (`cptr run --host 0.0.0.0`, or publishing the Docker port). When you do open it up, put it behind a VPN or a tunnel rather than a public port, the same way you would treat SSH.
+- [Get started](./getting-started/local-trial): install, sign in, open a workspace, and return from another device.
+- [Is it right for me?](./is-it-right): understand the value in plain language and recognize a bad fit early.
+- [Use cases](./use-cases/nora-remote-fix): solve a real interruption, not a toy exercise.
+- [Your workspace](./workspace/workspace-paths): files, terminal, git, tabs, browser preview, search, and PWA behavior.
+- [AI and coding agents](./agents/models): choose, supervise, and continue agent work in a real workspace.
+- [Remote access and security](./remote-access/security-model): reach your machine without pretending it is safe for everyone.
+- [Automations and integrations](./integrations/open-webui-gateway): connect Open WebUI, notifications, bots, and external tools.
+- [Operate Open WebUI Computer](./operate/data-and-backups): keep state, logs, upgrades, and recovery under control.
+- [Reference](./reference/cli-and-storage): exact commands, configuration, permissions, and API contracts.
+- [Troubleshooting](./troubleshooting/install-and-login): diagnose a concrete failed verification.
 
-## License
+## Next step
 
-Open WebUI Computer is released under the **Open Use License**: the source is available, and all rights are reserved. [Commercial licenses](https://openwebui.com/computer/license) and [enterprise licenses](mailto:sales@openwebui.com) are available. See the [LICENSE](https://github.com/open-webui/computer/blob/main/LICENSE) file for the exact terms.
+Start with [Open WebUI, Open WebUI Computer, or both?](./choose) if you are choosing a product. Otherwise, [try it locally](./getting-started/local-trial) and prove that it can open the workspace you already use.

docs/ecosystem/computer/integrations/_category_.json

@@ -0,0 +1,10 @@
+{
+	"label": "Automations and integrations",
+	"position": 21,
+	"collapsible": true,
+	"collapsed": true,
+	"link": {
+		"type": "generated-index",
+		"description": "Bring a real Computer workspace to Open WebUI, schedules, notifications, messaging, and trusted external tools."
+	}
+}

docs/ecosystem/computer/integrations/automations-and-notifications.md

@@ -0,0 +1,39 @@
+---
+title: Schedule trusted work and get notified
+sidebar_position: 2
+---
+
+# Schedule trusted work and get notified
+
+Automations are useful when a repeated check belongs beside the repository and tools that actually perform it: run a test suite, inspect a build result, or prepare a report in a known workspace. They are not a safe way to accept arbitrary instructions from the internet.
+
+## Use this when
+
+Priya wants a known prompt to run on a recurring schedule in one known workspace, then wants a browser, webhook, or bot notification when it finishes or fails.
+
+## Before you start
+
+- Choose a stable workspace, model, and narrowly written prompt.
+- Confirm the host stays on and the selected provider/model is available at the scheduled time.
+- Configure the notification target first and use its test action.
+
+## Do it
+
+1. Open **Automations**, create an automation, select its workspace/model, write its prompt, and set its schedule.
+2. Save it, inspect the shown next run, then use **Run now** before relying on the schedule.
+3. In **Settings → Notifications**, create a browser, webhook, or bot target; select the finished/failed events it should receive.
+4. Review run history. Pause the automation before changing a broad prompt or replacing its model.
+
+Automations can also have an authenticated webhook trigger. Treat that URL as a secret trigger, revoke it when no longer needed, and do not place it in public clients or issue trackers.
+
+## Verify it worked
+
+The automation displays an upcoming run and **Run now** creates a run-history entry with a linked chat. That proves the agent task launched; open the linked chat and confirm the terminal/test result before treating the run as a pass or failure. The notification target’s test succeeds before you rely on an automatic notification.
+
+## If it did not
+
+Check the schedule’s next-run value, model availability, and run history error. Re-test the notification target and confirm the browser/device permits notifications. If a webhook invocation fails, regenerate the URL rather than weakening authentication.
+
+## Trust boundary
+
+Automations execute with full tool approval/high trust in their configured workspace because no person is present to approve each tool call. Give them only stable, reviewed prompts, models, workspaces, and notification endpoints. Do not use them for untrusted user input, destructive deploys, or a host you cannot monitor.

docs/ecosystem/computer/integrations/messaging-and-tools.md

@@ -0,0 +1,60 @@
+---
+title: Message a workspace and add external tools
+sidebar_position: 3
+---
+
+# Message a workspace and add external tools
+
+Messaging bots are useful when the fastest way to ask your machine a question is the chat app already on your phone. MCP and OpenAPI tools are useful when the agent needs a narrow, declared bridge to another service. Neither should be treated as a casual public chatbot integration.
+
+## Use this when
+
+Jules wants to ask from Telegram, Discord, Slack, WhatsApp, or Signal whether a build passed in a known workspace. Priya wants an agent to call a trusted MCP or OpenAPI service with an explicit credential and tool list.
+
+## Before you start
+
+- Enter at least one exact platform user ID in **Allowed senders** before starting the bot. An empty list accepts every sender who can reach the bot.
+- Use a private bot account or channel that you control; do not add the bot to groups, shared workspaces, or public channels. Sender allowlisting is not channel allowlisting.
+- Assign the bot a deliberate workspace and model; do not default it to a sensitive host directory. Bots are not workspace-pinned: `/workspace` can switch the bot to any workspace owned by that Computer user.
+- For MCP/OpenAPI, obtain the server URL/command, authentication material, and a clear description of the operations it exposes.
+
+## Do it
+
+1. In **Settings → Admin → Bots**, create the adapter configuration, verify its token, select workspace/model, and start it.
+2. From an allowed account, send a read-only test such as “Which branch is checked out?” Use `/new` for a fresh conversation where the adapter supports it. Do not use `/workspace` as part of a safe single-workspace deployment.
+3. In **Settings → Admin → Tool Servers**, add a stdio/remote MCP or OpenAPI server, set its authentication/custom headers, and run verification before enabling it in a chat.
+4. Ask the agent to use one non-destructive external operation and inspect the tool row/result.
+
+Not a fit: do not connect a public community channel, an untrusted group, or a third-party tool server whose data handling and permissions you cannot explain. Use a normal support bot or a constrained service API for that job instead.
+
+## Verify it worked
+
+The bot’s status is running and its allowed test message appears as a Computer chat associated with the selected workspace. Before trusting it, send a harmless message from an unlisted account and confirm no Computer chat is created. A verified tool server lists its available tools, and the test tool call returns the expected non-destructive result.
+
+## If it did not
+
+Stop the bot and recheck its token/webhook configuration, exact Allowed senders IDs, private channel/account boundary, and workspace/model selection. If you need a bot that cannot switch among the owner's workspaces, use a dedicated Computer account or instance containing only the intended workspace. For a tool server, use its verification error to fix the command/URL/auth header; do not bypass verification by granting broader host access.
+
+## Trust boundary
+
+Bots use full approval/high trust: an inbound message can start agent work with host tools in its configured workspace. An empty Allowed senders list accepts every sender, and an allowed sender can switch the bot among the owner’s workspaces with `/workspace`. Use a private account or channel, require exact sender IDs, and prefer a dedicated Computer account or instance when the bot must be confined. MCP/OpenAPI tools run with the credentials and external permissions you provide, and their inputs/results can leave the host. Give each integration the least powerful credential available, and disable it when not needed.
+
+## Choose the external-tool transport
+
+### Stdio MCP
+
+Computer starts a local command on the host under the Computer service account and talks to it through standard input/output. Use this only for commands you would trust that host account to run.
+
+**Verify it worked:** verification lists tools, then a harmless read-only tool call succeeds. **If it did not:** disable the server, check command, arguments, environment, working directory, and the `cptr[mcp]` dependency. Remove it and rotate any credential passed in its environment if you cannot explain the failure.
+
+### Remote MCP
+
+Computer connects to a remote Streamable HTTP MCP endpoint. Prompt arguments and tool results can leave the host for that service.
+
+**Verify it worked:** verification discovers the expected named tools, then a read-only call succeeds. **If it did not:** disable the server, check endpoint and authentication, then revoke or rotate the remote credential before retrying.
+
+### OpenAPI
+
+Computer reads an API description and calls the external service with the headers or bearer credential you configure. A tool can mutate that external system even when it does not touch local files.
+
+**Verify it worked:** verification lists the expected operations; first use a read-only endpoint. **If it did not:** disable the server, correct the specification URL or authentication, and revoke the credential if it may have reached an untrusted endpoint. Do not enable write-capable operations until the read-only verification is understood.

docs/ecosystem/computer/integrations/open-webui-gateway.md

@@ -0,0 +1,57 @@
+---
+title: Use a Computer workspace from Open WebUI
+sidebar_position: 1
+---
+
+# Use a Computer workspace from Open WebUI
+
+Open WebUI is the place to organize AI conversations, models, knowledge, and shared workflows. Open WebUI Computer is the place where a particular machine’s real files, terminal, git state, and running processes live. The gateway lets an Open WebUI chat choose one Computer workspace as its model, so the chat’s agent work happens in that real workspace.
+
+It is valuable when you want Open WebUI as the front door without copying a repository or pretending a remote agent has your local machine context. It is not a general two-way sync product: it does not import Computer’s standalone chats into Open WebUI and does not make Open WebUI knowledge bases automatically available to Computer.
+
+:::danger Gateway requests are unattended
+Gateway requests run with **full tool approval**. Open WebUI cannot pause a file edit, command, or external tool call for a per-tool confirmation round trip. Connect only trusted Open WebUI clients to deliberately bounded workspaces and models. For interactive approval, open the same workspace directly in Open WebUI Computer.
+:::
+
+## Use this when
+
+Elena already works in Open WebUI but needs an agent to inspect, edit, or run commands in the project on her Computer host. Choose Open WebUI alone for knowledge/chat work that does not need a specific machine. Choose Computer alone when you mainly need files, terminal, or git with optional AI.
+
+## Before you start
+
+- Run both services where Open WebUI can reach the Computer `/v1` endpoint securely.
+- Create the target workspace in Computer and configure its default agent/model.
+- Create a gateway API key in **Computer → Settings → Admin → Gateway**; copy it immediately because keys are stored hashed.
+
+## Do it
+
+1. In Open WebUI, add an **OpenAI API** connection whose base URL is `https://your-computer-host/v1`.
+2. Add the Computer gateway key as its bearer credential.
+3. Add the following custom headers to the Open WebUI connection so Computer can preserve chat lineage and filter Open WebUI utility requests:
+
+   ```json
+   {
+     "X-OpenWebUI-Chat-Id": "{{CHAT_ID}}",
+     "X-OpenWebUI-Message-Id": "{{MESSAGE_ID}}",
+     "X-OpenWebUI-User-Message-Id": "{{USER_MESSAGE_ID}}",
+     "X-OpenWebUI-User-Message-Parent-Id": "{{USER_MESSAGE_PARENT_ID}}",
+     "X-OpenWebUI-Task": "{{TASK}}"
+   }
+   ```
+
+   `{{USER_MESSAGE_ID}}`, `{{USER_MESSAGE_PARENT_ID}}`, and `{{TASK}}` require Open WebUI 0.10.0 or newer. Without them, basic chat works, but edit/regeneration branches and background-task filtering do not.
+4. Save, select the `cptr/<workspace>` model in Open WebUI, and ask a small read-only question about a file in that workspace.
+
+The lineage headers let Computer reuse the correct chat for subsequent turns, preserve edits/regenerations as branches, and avoid treating Open WebUI title/tag/follow-up utility requests as agent tasks.
+
+## Verify it worked
+
+The workspace appears as `cptr/<workspace>` in Open WebUI’s model picker. Its answer cites real workspace state, and the associated conversation appears in the Computer sidebar. Send a follow-up, then edit or regenerate a message: the Computer sidebar should show the related branch rather than an unrelated chat. Open WebUI title/tag requests should not create a workspace-agent chat.
+
+## If it did not
+
+Call `GET /v1/models` with the same bearer key to distinguish connectivity/authentication from model selection. Recheck the base URL has `/v1`, the key belongs to the intended Computer user, and the workspace exists for that user. If normal chat works but branches or background-task filtering do not, recopy the Open WebUI lineage headers and check the Open WebUI version supports those placeholders.
+
+## Trust boundary
+
+The gateway key authorizes access to the owning user’s Computer workspaces. It is not an Open WebUI user-to-host isolation layer, and gateway work uses full tool approval. Treat it like a credential for shell-capable agent work; keep the Computer instance private and do not expose the gateway as a public model endpoint.

docs/ecosystem/computer/is-it-right.md

@@ -0,0 +1,79 @@
+---
+title: "Is Open WebUI Computer right for me?"
+sidebar_position: 2
+---
+
+# Is Open WebUI Computer right for me?
+
+You do not need to know anything about Open WebUI Computer to answer this.
+
+## Avery's zero-jargon path
+
+Avery has a project folder on her laptop, but words like *terminal*, *git*, *workspace*, and *agent* are new to her. She should not start by opening a router port, connecting a bot, or giving an AI credentials. Her safe first question is much smaller: **can this show me the project I already have, without moving or copying it?**
+
+The [five-minute proof](#the-five-minute-proof) below answers that question. It requires copying two commands into the host machine's terminal, then choosing an existing folder in the browser. If copying those commands feels unsafe or confusing, Avery should ask the person who manages that computer to help with the local trial. She should not attempt remote access until the local proof makes sense.
+
+Think about the computer where your work already lives. It may be a laptop on your desk, a Mac mini at home, or a Linux machine in a closet. It already has your projects, downloaded dependencies, half-finished branches, terminal windows, local databases, and processes that took time to set up.
+
+When you leave that machine, most tools make you start somewhere else: a blank cloud workspace, a new chat, or a remote shell with none of the visual context. Open WebUI Computer puts **that same machine** in a browser. From a phone, tablet, laptop, or another desktop, you can open the same project, inspect the same terminal, see the same git diff, and optionally direct an AI agent that is working in that exact place.
+
+It is not magic remote access to every computer. It is a service you run on a machine you control.
+
+## Personal computer, not shared team machine
+
+Open WebUI Computer is designed for one person reaching the computer they own or operate. It is closer to the difference between **ChatGPT and Codex**: ChatGPT is a conversation space you can use alone or share with a team; Codex works inside a developer's project and environment. Open WebUI is the AI platform in this comparison. Open WebUI Computer is the personal, high-trust workspace surface.
+
+That distinction matters. Computer gives an authenticated user host filesystem and shell access. It is excellent when that user is you. It is not the right way to give untrusted teammates separate, isolated machines.
+
+## Use Open WebUI Computer when
+
+| You have this problem | What Computer changes |
+| --- | --- |
+| “The fix is on my machine, but I only have my phone.” | You can inspect the existing workspace, terminal, and git state instead of recreating it elsewhere. |
+| “A process or coding agent is already running at home.” | You can check, guide, and resume the same work from another browser. |
+| “I need to test my local app on a real device.” | You can keep the local server and open its preview from that device. |
+| “I want AI to work where my real project and tools live.” | An agent can work in the selected workspace, with the approvals and limits you choose. |
+| “I want to check small things without turning them into a desk session.” | A short interruption can stay short: read a log, review a diff, answer an agent, or run a command. |
+
+## It may not be right when
+
+| Your actual need | Better starting point |
+| --- | --- |
+| You only want an AI chat, models, knowledge, prompts, or shared AI workflows. | [Open WebUI](https://docs.openwebui.com/) |
+| You need a new, disposable, isolated development environment. | A cloud IDE, virtual machine, or container designed for isolation. |
+| Teammates or untrusted people need separate, safely isolated access to a host. | A multi-user platform with tenant isolation; Open WebUI Computer is not that. |
+| You want to publish a shell/filesystem interface on the public internet. | Do not use a direct public deployment; use a private network pattern instead. |
+| You do not control a machine that can stay available. | Start with a hosted service or wait until you have a machine you can operate. |
+
+## The five-minute proof
+
+The best way to decide is to try it without changing your network or adding AI.
+
+1. On the machine that already has a project you care about, install and start Open WebUI Computer:
+
+   ```bash
+   pip install cptr
+   cptr run
+   ```
+
+2. Open the one-time setup URL it prints in a browser on that same machine.
+3. Choose the existing project folder as a workspace.
+4. Open a terminal tab and run a harmless command such as `pwd` or `git status`.
+
+## Verify it worked
+
+The browser should show the project you chose, and the terminal should report that project's real path or git state. You have proven the important part: Open WebUI Computer is connected to your existing environment, not a replacement copy.
+
+## If it did not
+
+If the setup URL does not open, use [install and login troubleshooting](./troubleshooting/install-and-login). If the wrong folder or project state appears, use [workspace paths](./workspace/workspace-paths). Do not bind the service to your network or add a tunnel to solve a local startup problem.
+
+## Trust boundary
+
+This test is local-only by default. Keep it that way until you understand [the security model](./remote-access/security-model). An authenticated user can use the host filesystem and shell, which is exactly why Computer can be useful—but it is not a sandbox.
+
+## Next step
+
+- Want the machine itself? [Try it locally](./getting-started/local-trial).
+- Want an AI workflow? [Choose Open WebUI, Computer, or both](./choose).
+- Want a concrete story? [Read Nora's remote-fix workflow](./use-cases/nora-remote-fix).

docs/ecosystem/computer/open-webui.md

@@ -1,42 +1,12 @@
 ---
-title: "Connect to Open WebUI"
-sidebar_position: 3
+title: "Use Open WebUI with Open WebUI Computer"
+sidebar_position: 6
 ---
 
-# Connect Open WebUI Computer to Open WebUI
+# Use Open WebUI with Open WebUI Computer
 
-Open WebUI Computer ships an **OpenAI-compatible gateway**: it exposes each workspace as a model over `/v1/models` and `/v1/chat/completions`. Point Open WebUI at it as an OpenAI connection and every workspace shows up as a model named `cptr/<workspace>`. Chatting with that model in Open WebUI runs the full Open WebUI Computer agent loop, reading files, editing code and running commands, in that workspace, and the conversation appears in both Open WebUI and the Open WebUI Computer sidebar.
+This page keeps the original route for existing links. The maintained guide is now part of the integrations section.
 
-:::info What this does, and what it does not
-This lets Open WebUI **drive** an Open WebUI Computer workspace as a model: new chats you start in Open WebUI run through Open WebUI Computer. It is **not** a sync of Open WebUI Computer's existing standalone chats into Open WebUI, and it does not share Open WebUI knowledge bases into Open WebUI Computer.
-:::
+[Open the Open WebUI gateway guide →](./integrations/open-webui-gateway)
 
-## Setup
-
-1. **Create a gateway API key in Open WebUI Computer.** Open the **Gateway** admin tab, create a key and copy it. Keys are stored hashed and shown only once.
-2. **Note the base URL.** The Gateway tab shows it: your Open WebUI Computer server origin plus `/v1`, for example `http://localhost:8000/v1` (use your host's address if Open WebUI Computer runs elsewhere).
-3. **Add Open WebUI Computer as a connection in Open WebUI.** In **Admin Panel > Settings > Connections**, add an **OpenAI API** connection. Set the base URL to the gateway URL from step 2 and paste the API key from step 1.
-4. **Add the recommended headers.** The Gateway tab has a one-click copy of the header config. Paste it into the connection's custom headers:
-
-   ```json
-   {
-     "X-OpenWebUI-Chat-Id": "{{CHAT_ID}}",
-     "X-OpenWebUI-Message-Id": "{{MESSAGE_ID}}",
-     "X-OpenWebUI-User-Message-Id": "{{USER_MESSAGE_ID}}",
-     "X-OpenWebUI-User-Message-Parent-Id": "{{USER_MESSAGE_PARENT_ID}}",
-     "X-OpenWebUI-Task": "{{TASK}}"
-   }
-   ```
-
-5. **Pick a workspace and chat.** Your workspaces now appear in the Open WebUI model picker as `cptr/<workspace>`. Select one and start a conversation; it runs the Open WebUI Computer agent loop in that workspace.
-
-## Why the headers matter
-
-The `{{...}}` values are Open WebUI's [custom-header placeholders](/reference/env-configuration#enable_forward_user_info_headers), filled in per request from the chat metadata. They give Open WebUI Computer the chat and message lineage it needs to:
-
-- **Branch correctly.** Regenerating or editing a message in Open WebUI creates a matching branch in the Open WebUI Computer sidebar (via `X-OpenWebUI-User-Message-Id` and `X-OpenWebUI-User-Message-Parent-Id`), instead of appending in the wrong place.
-- **Ignore background work.** Open WebUI also calls the gateway for title generation, tag extraction and follow-up suggestions. `X-OpenWebUI-Task` tells Open WebUI Computer which requests are background tasks, so it skips them instead of spawning ghost chats or running a full agent loop.
-
-:::caution Requires Open WebUI 0.10.0 or newer
-The `{{USER_MESSAGE_ID}}`, `{{USER_MESSAGE_PARENT_ID}}` and `{{TASK}}` placeholders were added in Open WebUI 0.10.0. On 0.9.6 the basic gateway connection still works, you can chat with a workspace as a model, but those three headers are not filled in, so branching and background-task filtering do not work yet.
-:::
+Use Open WebUI when you want its AI interface and choose Open WebUI Computer when the requested work must happen in a particular real workspace. The gateway combines those roles without synchronizing their chats, knowledge bases, users, or configuration.

docs/ecosystem/computer/operate/_category_.json

@@ -0,0 +1,8 @@
+{
+	"label": "Operate Open WebUI Computer",
+	"position": 7,
+	"link": {
+		"type": "generated-index",
+		"description": "Keep a private, persistent single-host installation healthy and recoverable."
+	}
+}

docs/ecosystem/computer/operate/data-and-backups.md

@@ -0,0 +1,30 @@
+---
+title: Data and backups
+sidebar_position: 2
+---
+
+# Data and backups
+
+## Use this when
+
+Priya wants to move or protect the persistent state of a private installation before an upgrade, host migration, or risky configuration change.
+
+## Before you start
+
+By default, Open WebUI Computer stores its database and configuration in `~/.cptr`: `app.db` and `config.toml`. Change the location before startup with `CPTR_DATA_DIR`. Docker stores the equivalent state in `/data`, normally backed by the `cptr-data` volume.
+
+## Do it
+
+Stop Open WebUI Computer cleanly. Copy the entire data directory, not only the database, to protected local or encrypted backup storage. For Docker, create a backup from the `cptr-data` volume while the container is stopped. Keep the backup separate from the project workspaces; those files need their own backup policy.
+
+## Verify it worked
+
+List the backup and confirm it contains both `app.db` and `config.toml` (or the Docker volume contents). For a restore drill, point a stopped test installation at a copy of the backup with `CPTR_DATA_DIR`, start it, sign in, and confirm a known workspace and setting are present.
+
+## If it did not
+
+If SQLite reports locks or the backup is inconsistent, stop the process and retry; do not copy a live database while writes are in flight. If restoring loses access, restore the complete directory and verify file ownership before attempting account or config changes.
+
+## Trust boundary
+
+The data directory can contain account, configuration, workspace metadata, and service secrets. Treat backups as sensitive host data and encrypt them where your threat model requires it.

docs/ecosystem/computer/operate/docker-and-upgrades.md

@@ -0,0 +1,39 @@
+---
+title: Docker volumes and upgrades
+sidebar_position: 3
+---
+
+# Docker volumes and safe upgrades
+
+## Use this when
+
+You run Open WebUI Computer in Docker and need to replace the image without replacing its identity or state.
+
+## Before you start
+
+Back up the `cptr-data` volume and note every project bind mount. Pin a release image if you need repeatability; `:dev` follows the main branch and is not a stability promise.
+
+## Do it
+
+Stop the current container, pull the intended tag, then recreate it with the same persistent volume and mounts:
+
+```bash
+docker pull ghcr.io/open-webui/computer:latest
+docker run --rm -it -p 8000:8000 \
+  -v cptr-data:/data -v "$PWD:/workspace" -w /workspace \
+  ghcr.io/open-webui/computer:latest
+```
+
+For a Python installation, use `pip install --upgrade cptr` in the same environment after backing up `~/.cptr`.
+
+## Verify it worked
+
+The new process prints a setup URL, `curl http://127.0.0.1:8000/api/health` returns `status: ok`, and the browser shows the preexisting account and workspace rather than a new setup state. Run `docker volume inspect cptr-data` to confirm the named volume remains attached.
+
+## If it did not
+
+If setup starts from scratch, stop immediately and verify the `-v cptr-data:/data` mount was preserved. If the upgrade fails, restore the backup and use the previous image tag; collect logs before trying another version.
+
+## Trust boundary
+
+Pulling a new image changes code that can access mounted projects and data. Review the release and keep the scope of mounted directories minimal.

docs/ecosystem/computer/operate/index.md

@@ -0,0 +1,12 @@
+---
+title: Operate Open WebUI Computer
+sidebar_position: 1
+---
+
+# Operate Open WebUI Computer
+
+These pages cover a persistent single-host instance: where state lives, how to back it up, how to upgrade it, and how to prove it is healthy. They do not turn Open WebUI Computer into a multi-replica or untrusted shared service.
+
+- [Data and backups](./data-and-backups)
+- [Docker volumes and upgrades](./docker-and-upgrades)
+- [Logs, health, and configuration](./logs-health-and-configuration)

docs/ecosystem/computer/operate/logs-health-and-configuration.md

@@ -0,0 +1,36 @@
+---
+title: Logs, health, and configuration
+sidebar_position: 4
+---
+
+# Logs, health, and configuration
+
+## Use this when
+
+You need a quick health signal, a durable diagnostic record, or a controlled location for instance configuration.
+
+## Before you start
+
+The unauthenticated health endpoint is `/api/health`. Environment variables are read when the process starts. `config.toml` lives in the data directory and mirrors server and app configuration; avoid editing it while the app is running.
+
+## Do it
+
+Check the instance:
+
+```bash
+curl http://127.0.0.1:8000/api/health
+```
+
+Set `CPTR_LOG_LEVEL=DEBUG` for more server detail or `CPTR_LOG_FORMAT=json` for structured stdout, then restart. Use `CPTR_AUDIT_LOG_LEVEL=METADATA` for a low-content mutation trail. Use `CPTR_DATA_DIR=/path/to/data` only before start, and make the selected directory persistent and writable.
+
+## Verify it worked
+
+Health returns JSON with `status`, `uptime_seconds`, and `pid`. Restart with the chosen log setting and observe the requested output format in the process log. When changing the data directory, confirm it contains `app.db` and `config.toml` after a clean start.
+
+## If it did not
+
+If health fails locally, inspect the server's stdout and verify the chosen port. If config changes do not appear, restart and confirm you changed the directory actually selected by `CPTR_DATA_DIR`. If the app cannot write data, correct ownership rather than running it with broader privileges.
+
+## Trust boundary
+
+`/api/health` intentionally does not require login, so do not place secrets or sensitive diagnostics in it. Debug and audit logs may contain operational data and need protected storage.

docs/ecosystem/computer/personas.md

@@ -0,0 +1,62 @@
+---
+title: "Who Open WebUI Computer is for"
+sidebar_position: 4
+---
+
+# Who Open WebUI Computer is for
+
+Open WebUI Computer is for people whose useful work already exists on a machine they control. It is especially useful when the interruption is small but the environment would be expensive to recreate.
+
+## Avery: start without knowing the jargon
+
+Avery has never used a terminal, git, SSH, or an AI coding agent. A project folder already exists on her laptop, perhaps from a tutorial or someone helping her build a small site. She does not need to understand every technical term before deciding whether Computer is useful.
+
+Her first goal is deliberately simple: start Computer locally, choose that existing folder, and see the same files it already contains. No remote networking, AI key, agent, or public URL is needed. If that proof is not useful, Avery should stop there; she has learned the product is not solving a real problem for her.
+
+[Take Avery's zero-jargon first-time path →](./is-it-right)
+
+## Mira: review the real prototype, not a screenshot
+
+Mira is a product designer at a small team. The prototype, images, and notes are already in a project on her Mac. She is not trying to become a terminal expert; she wants to open the live prototype on a real phone, compare the interaction to the design, and put feedback back into the same project while the context is fresh.
+
+Her first success is opening the project’s existing preview on her phone or tablet, then sharing a link, a short note, or a voice memo into the workspace. A technical owner should set up the local project, private remote access, and any agent permissions first. Mira can then use the browser, files, preview, notes, and a narrowly instructed agent without needing to understand git commands.
+
+[Follow the real-device preview workflow →](./use-cases/theo-real-device-preview) · [Share feedback into a workspace →](./workspace/pwa-share-shortcuts)
+
+## Nora: the real fix is on the machine at home
+
+Nora's client reports an invoice bug while she is on a train. Her home iMac already has the local database, a dirty branch, and the terminal output she needs. She does not need a fresh cloud environment; she needs to inspect and make a narrow change in the existing one.
+
+[Follow Nora's remote-fix workflow →](./use-cases/nora-remote-fix)
+
+## Malik: the agent has context, but he supplies judgment
+
+Malik's mini PC is already running a coding-agent task. From dinner, he needs to inspect a migration decision and let the same task continue. Open WebUI Computer is the control surface for work in the repository, not a replacement chat transcript.
+
+[Follow Malik's agent-supervision workflow →](./use-cases/malik-agent-supervision)
+
+## Theo: test where the user will use it
+
+Theo's local app server is running on his Mac. He wants to check the actual app on an iPad without moving the code or mirroring the development environment.
+
+[Follow Theo's real-device preview workflow →](./use-cases/theo-real-device-preview)
+
+## Elena: a private machine can report back
+
+Elena's NUC runs a repeatable release check. She needs a run history, a linked chat, and a failure notification—not an unattended public shell. Automations are powerful because they can act on the selected workspace, so they are high-trust by design.
+
+[Follow Elena's automation workflow →](./integrations/automations-and-notifications)
+
+## Ravi: compose the whole system deliberately
+
+Ravi already understands private networks, coding agents, model providers, and external tools. What excites him is not another hosted agent dashboard. It is the possibility of keeping the real machine, its local state, and its existing tools under his control while composing Open WebUI, native agents, automations, messaging, MCP/OpenAPI tools, and the gateway around it.
+
+His first success is intentionally bounded: use Open WebUI to select one Computer workspace as a model, ask it to perform a harmless read-only task, and watch the real workspace activity in Computer. He adds one integration at a time, verifies it, and treats every bot, automation, gateway key, and tool server as a new capability that expands the trust boundary.
+
+[Connect Open WebUI to a Computer workspace →](./integrations/open-webui-gateway) · [Add a verified external tool →](./integrations/messaging-and-tools) · [Read the security model →](./remote-access/security-model)
+
+## Who should choose something else
+
+Choose a cloud IDE when you need an isolated, disposable environment. Choose a shared, governed platform when untrusted people need separate access. Do not expose Open WebUI Computer directly to the public internet or treat it as a sandbox for strangers.
+
+Read [Open WebUI, Open WebUI Computer, or both?](./choose) if your primary question is about AI workflow rather than access to a machine.

docs/ecosystem/computer/reference/_category_.json

@@ -0,0 +1,10 @@
+{
+	"label": "Reference",
+	"position": 22,
+	"collapsible": true,
+	"collapsed": true,
+	"link": {
+		"type": "generated-index",
+		"description": "Commands, storage, permissions, compatibility, and the OpenAI-compatible gateway."
+	}
+}

docs/ecosystem/computer/reference/agent-compatibility.md

@@ -0,0 +1,42 @@
+---
+title: Agent and feature compatibility
+sidebar_position: 3
+---
+
+# Agent and feature compatibility
+
+Use this page to identify the host-side requirement behind a model choice. “Supported” means Computer has an adapter path; it does not mean the host already has the program, login, dependency, or entitlement required to use it.
+
+| Backend | What Computer checks | Common corrective action |
+|---|---|---|
+| API connection | Provider URL, credential, selected model | Correct endpoint/key/model in Connections |
+| Codex | Command, app-server capability, available models | Update/install Codex and sign in on the host |
+| Claude Code | Command, version, local SDK support, models | Install/update CLI and required SDK, then sign in |
+| Cursor | Command, agent setup/login, discoverable models | Complete Cursor CLI setup/login |
+| Grok, OpenCode, Cline, Pi | Command and provider/login/model discovery | Configure that agent’s provider/authentication on the host |
+
+Native profiles run through their installed host command. Other terminal agents can still be used in a normal Computer terminal tab even when they are not configured as a native chat backend.
+
+## Use this when
+
+Jules sees an empty model list, a “not found” status, or needs to decide whether a normal terminal workflow is sufficient.
+
+## Before you start
+
+Know which host owns the CLI. A browser connected from a phone cannot supply a CLI installed only on that phone.
+
+## Do it
+
+Run the profile’s detection in **Settings → Admin → Agents**, correct the reported dependency/authentication issue, then rerun detection. Use the native profile for conversational, supervised agent work; use a terminal tab if you want to operate an unsupported or manually controlled CLI directly.
+
+## Verify it worked
+
+Detection is **ready** and at least one intended model is selectable. A short read-only task completes inside the expected workspace.
+
+## If it did not
+
+Use the detection status as the source of truth. Do not replace a missing local login with a random API key unless you deliberately want to switch to the API connection model.
+
+## Trust boundary
+
+Compatibility detection establishes host capability, not security. Every ready native backend still inherits the host account, workspace content, and configured permission mode.

docs/ecosystem/computer/reference/cli-and-storage.md

@@ -0,0 +1,41 @@
+---
+title: CLI, installation options, and stored state
+sidebar_position: 1
+---
+
+# CLI, installation options, and stored state
+
+The product is named **Open WebUI Computer**; `cptr` is the package and command name. A local install is the fastest way to learn whether the product solves your problem before you make any remote-access decision.
+
+## Use this when
+
+Priya is installing or operating Computer on a workstation or private server and needs to know which command starts it, where its state lives, and what to preserve during an upgrade.
+
+## Before you start
+
+- Use Python 3.10 or newer for the package installation.
+- Decide whether Computer should access the host directly or a Docker-mounted workspace.
+- Keep the data directory on persistent storage.
+
+## Do it
+
+```bash
+pip install cptr
+cptr run
+```
+
+Use `cptr[all]` when you need all optional feature groups, including MCP support. `uvx cptr@latest run` is an alternative one-command trial. `cptr run` is local-only by default; use `--host`, `--port`, `--headless`, or `--reload` only when their behavior is intentional.
+
+The default data directory is `~/.cptr`; `CPTR_DATA_DIR` changes it. It contains `app.db`, `config.toml`, and logs such as `logs/audit.jsonl` when audit logging is enabled. In Docker, mount `/data` persistently and mount the actual host project into the container, for example at `/workspace`.
+
+## Verify it worked
+
+`cptr run` prints a first-time setup URL and the browser opens the setup/login flow. After creating a workspace and restarting, the workspace remains in the sidebar; in Docker, its state remains after recreating a container with the same `/data` volume.
+
+## If it did not
+
+If the browser cannot reach the service, confirm the printed host/port and local firewall. If state disappeared, confirm `CPTR_DATA_DIR` or the Docker `/data` volume is writable and persistent. On Windows terminal errors mentioning `VCRUNTIME140.dll`, install the Microsoft Visual C++ Redistributable and restart Computer.
+
+## Trust boundary
+
+Changing `--host` from loopback changes who can attempt to reach a shell-capable service. A persistent database also contains account, workspace, chat, and configuration state; back it up as sensitive application data.

docs/ecosystem/computer/reference/gateway-api.md

@@ -0,0 +1,43 @@
+---
+title: OpenAI-compatible gateway API
+sidebar_position: 4
+---
+
+# OpenAI-compatible gateway API
+
+The gateway exposes each workspace owned by the gateway-key user as an OpenAI-compatible model. It is intended for a trusted client such as Open WebUI, not as a public general-purpose API.
+
+:::danger Full approval only
+Gateway-created tasks use `tool_approval_mode: full`. There is no per-tool approval callback in the OpenAI-compatible API. Use only trusted clients, bounded workspaces, and models you intend to give host-capable tool access.
+:::
+
+## Use this when
+
+Elena is connecting a trusted OpenAI-compatible client and needs the exact endpoints, authentication, and conversation-continuity semantics.
+
+## Before you start
+
+- Create a gateway API key in Computer; raw keys are shown once and stored hashed.
+- Create the workspace and configure the model it should use.
+- Ensure the client can reach Computer privately.
+
+## Do it
+
+1. Request `GET /v1/models` with `Authorization: Bearer <gateway-key>`.
+2. Select a returned `cptr/<workspace>` model.
+3. Send `POST /v1/chat/completions` with `model`, `messages`, and optional `stream`.
+4. Send `X-Chat-Id` or `X-OpenWebUI-Chat-Id` to reuse a Computer chat across turns. Open WebUI should additionally send its message/task lineage headers.
+
+Computer accepts extra OpenAI-style request fields for compatibility, but the selected workspace’s configured agent/model runs the task. Utility requests that Open WebUI labels as title/tag/follow-up work are handled without starting a full workspace agent task.
+
+## Verify it worked
+
+`/v1/models` returns only the key owner’s workspaces. A streamed completion returns server-sent events, and repeating the same client chat header continues the same Computer conversation.
+
+## If it did not
+
+`401` means the bearer key is missing, malformed, revoked, or belongs to no valid key record. A missing model usually means the workspace was not created for that key user. A connection that can list models but cannot complete a task needs the workspace’s agent/model configuration fixed.
+
+## Trust boundary
+
+A gateway bearer key is a capability for the corresponding user’s agent workspaces. Protect it like an SSH credential. The gateway does not confer a sandbox, does not merge identity/RBAC semantics with the calling client, and cannot provide interactive approval for a request in progress.

docs/ecosystem/computer/reference/security-and-configuration.md

@@ -0,0 +1,39 @@
+---
+title: Security, permissions, and configuration
+sidebar_position: 2
+---
+
+# Security, permissions, and configuration
+
+Open WebUI Computer is a private window into a real host. That is why it is useful for a dirty branch, local credentials, running process, or existing terminal session. It is also why its primary security rule is simple: treat an authenticated Computer user like an SSH user on that host.
+
+## Use this when
+
+Priya is deciding how to reach Computer from another device, set authentication/logging, or determine whether an instance is appropriate for a team or public network.
+
+## Before you start
+
+- Confirm every intended user is trusted with the host filesystem and shell.
+- Prefer local-only use first, then a private VPN/tunnel such as Tailscale for remote access.
+- Decide whether structured/audit logging is needed and where those logs will be retained.
+
+## Do it
+
+1. Keep the default loopback bind for a local trial.
+2. For remote use, put Computer behind a private, authenticated network path; then test from a second trusted device.
+3. Configure username/password setup and, if used, reverse-proxy trusted-header authentication only when the proxy prevents spoofed headers.
+4. Set `CPTR_AUDIT_LOG_LEVEL` for mutation audit records and `CPTR_LOG_LEVEL`/`CPTR_LOG_FORMAT` for diagnostics. Set `CPTR_CORS_ALLOWED_ORIGINS` deliberately when embedding/cross-origin access is needed.
+
+Not a fit: Computer is not a multi-tenant host, a browser-only sandbox, or a service to place on the open internet for strangers. Use an isolated developer environment, traditional SSH access controls, or a purpose-built multi-user platform instead.
+
+## Verify it worked
+
+The second trusted device can log in through the private route, while an untrusted/public route cannot reach the service. A permitted mutation produces an audit entry when enabled, without recording plaintext passwords or API keys.
+
+## If it did not
+
+Return to localhost-only access while you diagnose network and proxy configuration. Do not solve a failed trusted-header setup by accepting arbitrary inbound headers. If logs are absent, verify the configured path is writable and audit logging is not set to `NONE`.
+
+## Trust boundary
+
+There is no path sandboxing or per-user isolation. Terminal and shell-capable agent tools have host-level effects. Built-in agent file tools place some limits on ordinary workspace file operations, but those are not a substitute for host isolation or a safe public deployment.

docs/ecosystem/computer/remote-access/_category_.json

@@ -0,0 +1,8 @@
+{
+	"label": "Remote access and security",
+	"position": 5,
+	"link": {
+		"type": "generated-index",
+		"description": "Reach your own machine deliberately, with the same caution you would apply to SSH."
+	}
+}

docs/ecosystem/computer/remote-access/authentication-and-audit.md

@@ -0,0 +1,36 @@
+---
+title: Authentication and audit logging
+sidebar_position: 5
+---
+
+# Authentication and audit logging
+
+## Use this when
+
+You operate a personal instance and need an evidence trail for configuration changes or a way to distinguish an access problem from a server problem.
+
+## Before you start
+
+The default password sign-in establishes JWT sessions. Configuration is stored under the data directory. Audit logging is off by default and records mutating HTTP requests, not a full terminal transcript.
+
+## Do it
+
+Start the server with an audit level appropriate to your privacy needs:
+
+```bash
+CPTR_AUDIT_LOG_LEVEL=METADATA cptr run
+```
+
+Use `REQUEST` to include redacted request bodies or `REQUEST_RESPONSE` to include redacted request and response bodies. The default file is `~/.cptr/logs/audit.jsonl`; set `CPTR_AUDIT_LOG_PATH` to store it elsewhere. Use a strong unique password at first setup and keep signup disabled unless you have a trusted-user workflow.
+
+## Verify it worked
+
+Make a harmless change such as opening a workspace or saving a preference, then inspect the last JSON line in the audit log. It contains the method, path, status, source IP, and authenticated user metadata. Passwords, API keys, tokens, authorization, cookies, and secrets are redacted.
+
+## If it did not
+
+Restart after changing environment variables; they are read when the process starts. If the file is absent, verify the process can create its parent directory and that the level is one of `METADATA`, `REQUEST`, or `REQUEST_RESPONSE`. A `401` means sign in again or inspect the configured auth mode; do not bypass it with proxy headers.
+
+## Trust boundary
+
+Audit records can contain operational metadata and, at higher levels, redacted request data. Protect and retain them accordingly. Trusted-header authentication exists as an integration mode, but this documentation does not treat it as a supported reverse-proxy setup.

docs/ecosystem/computer/remote-access/index.md

@@ -0,0 +1,14 @@
+---
+title: Remote access and security
+sidebar_position: 1
+---
+
+# Remote access and security
+
+Open WebUI Computer is **your computer, served to you**. An authenticated user can access the host filesystem and shell. There is no per-user filesystem sandbox or isolation.
+
+Start with [local-only access](./local-and-lan). For another network, prefer [Tailscale](./tailscale-and-tunnels). Read the [security model](./security-model) before inviting any other user or publishing a route, and use [authentication and audit logging](./authentication-and-audit) to operate a private instance.
+
+:::danger Not a shared shell service
+Do not expose Open WebUI Computer directly to the public internet or let untrusted people share it. Treat it like an open SSH port, not a multi-tenant web application.
+:::

docs/ecosystem/computer/remote-access/local-and-lan.md

@@ -0,0 +1,36 @@
+---
+title: Local-only and LAN access
+sidebar_position: 3
+---
+
+# Local-only and LAN access
+
+## Use this when
+
+Theo is at home with an iPad and needs the local app and terminal running on his Mac, or you are testing access before setting up a private remote network.
+
+## Before you start
+
+`cptr run` binds to `127.0.0.1` by default. Only use LAN access on a network you control. Know the host's private IP address and ensure the host firewall permits the chosen port only as broadly as intended.
+
+## Do it
+
+Start the service on all network interfaces:
+
+```bash
+cptr run --host 0.0.0.0
+```
+
+On the other device, open `http://<host-private-ip>:8000` and sign in. Keep the host powered and awake while you use it.
+
+## Verify it worked
+
+On the second device, open the same existing workspace and terminal. Run a harmless command such as `pwd`; it reports the host workspace, not a new environment. Back on the host, run `curl http://127.0.0.1:8000/api/health` and confirm it remains healthy.
+
+## If it did not
+
+If the second device cannot connect, confirm both devices are on the same private network, use the host's LAN address rather than `localhost`, and inspect the host firewall. If the host sleeps, wake it and reconnect; Open WebUI Computer cannot serve a powered-off machine.
+
+## Trust boundary
+
+`0.0.0.0` makes the service reachable by devices that can route to the host. It is not authentication, encryption, or a recommendation to forward the port from your router.

docs/ecosystem/computer/remote-access/security-model.md

@@ -0,0 +1,30 @@
+---
+title: Security model and non-supported deployments
+sidebar_position: 2
+---
+
+# Security model
+
+## Use this when
+
+You are deciding whether a device, person, network, automation, or agent should be allowed to reach an instance.
+
+## Before you start
+
+Understand the core boundary: Open WebUI Computer runs commands and accesses files as the operating-system account that starts it. That is why it can resume the work you left on a machine, including its dirty checkout and local service. Browser login controls access to the application; it does not turn the host into a sandbox.
+
+## Do it
+
+Keep the default localhost binding for first use. If you need another device, put access behind a private network you control, such as Tailscale. Give every automation and messaging bot a narrowly selected workspace and constrained prompt. Bots use full approval; enter at least one exact Allowed sender ID because an empty list accepts every sender. Review configured AI providers and tool servers because they may receive workspace data or perform external actions.
+
+## Verify it worked
+
+From an untrusted network or unsigned-in browser, protected API calls return `401 unauthorized`. From the approved device, sign in and verify only the intended existing workspace is accessible. Confirm the server is not listening on a public address with your normal host firewall or network inspection tooling.
+
+## If it did not
+
+If access works from a network or user you did not intend, stop the service or return it to `127.0.0.1`, revoke affected credentials, and inspect [audit logs](./authentication-and-audit). Do not solve an exposure problem by adding more application users.
+
+## Trust boundary
+
+The supported model is one trusted owner on a controlled network. The following are not supported safe deployments: untrusted multi-user instances, direct public-internet exposure, or a reverse proxy that passes spoofable identity headers. Do not use trusted-header authentication as a deployment recipe until you have independently validated its entire proxy boundary.

docs/ecosystem/computer/remote-access/tailscale-and-tunnels.md

@@ -0,0 +1,47 @@
+---
+title: Private remote access with Tailscale or a tunnel
+sidebar_position: 4
+---
+
+# Reach a machine away from home
+
+## Use this when
+
+Nora needs the real branch and terminal from a phone outside her home network, without opening a public router port.
+
+## Before you start
+
+- Complete the [local trial](/ecosystem/computer/getting-started/local-trial) and [first workspace](/ecosystem/computer/getting-started/first-workspace) on the host first.
+- Keep Open WebUI Computer on its default localhost binding (`127.0.0.1`).
+- Enrol only devices you control in a private Tailscale network. Tailscale Serve may prompt an administrator to enable HTTPS certificates for that network.
+
+## Do it
+
+1. Install and sign in to Tailscale on the host and remote device, following [Tailscale's setup instructions](https://tailscale.com/docs).
+2. On the host, with Computer already running on localhost, publish a private Tailscale Serve reverse proxy:
+
+   ```bash
+   tailscale serve --bg localhost:8000
+   ```
+
+3. Ask Tailscale for the configured private URL:
+
+   ```bash
+   tailscale serve status
+   ```
+
+4. Open that URL from the enrolled phone or laptop and sign in to Computer.
+
+If you deliberately bind Computer to a non-loopback address instead, it can become reachable on other host interfaces too. That is an advanced network/firewall design, not the default remote-access recipe.
+
+## Verify it worked
+
+Turn off Wi-Fi on the remote phone so it uses a different network. Open the URL reported by `tailscale serve status`, sign in, and confirm the same workspace and existing terminal session appear. The local `cptr run` process should still listen only on `127.0.0.1`.
+
+## If it did not
+
+If Serve cannot reach Computer, first verify `http://127.0.0.1:8000/api/health` on the host. Then rerun `tailscale serve status` and confirm both devices are enrolled and allowed by the tailnet policy. Do not solve a private-access failure by opening a router port. To remove the proxy, run `tailscale serve reset`.
+
+## Trust boundary
+
+Tailscale Serve limits reachability to enrolled devices and policy, but it does not reduce what a signed-in Computer user can do. A public tunnel URL has a different threat model: do not publish one without an independent access-control design. See [the Tailscale Serve documentation](https://tailscale.com/docs/reference/tailscale-cli/serve) for current command behavior.

docs/ecosystem/computer/troubleshooting/_category_.json

@@ -0,0 +1,8 @@
+{
+	"label": "Troubleshooting",
+	"position": 10,
+	"link": {
+		"type": "generated-index",
+		"description": "Diagnose the host, network, state, and access paths without guessing."
+	}
+}

docs/ecosystem/computer/troubleshooting/access-and-workspaces.md

@@ -0,0 +1,30 @@
+---
+title: Remote access and workspace problems
+sidebar_position: 3
+---
+
+# Remote access and workspace problems
+
+## Use this when
+
+A phone cannot reach the host, a workspace is missing, or the terminal does not look like the expected project.
+
+## Before you start
+
+Decide whether the failure is local, LAN, or private-remote. `localhost` on a phone means the phone itself, not the machine running Open WebUI Computer.
+
+## Do it
+
+On the host, run `curl http://127.0.0.1:8000/api/health`. For LAN testing, start with `cptr run --host 0.0.0.0` and use the host's private IP from the second device. For remote use, follow [Tailscale or tunnels](/ecosystem/computer/remote-access/tailscale-and-tunnels), then select the project again through the workspace picker if it has not yet been added.
+
+## Verify it worked
+
+The second device signs in and sees the same workspace path. `pwd` and `git status` in its terminal match the host's normal shell. Closing and reopening the browser does not replace the running host process or workspace with a new copy.
+
+## If it did not
+
+If health fails on the host, return to [install and login](./install-and-login). If it works locally but not on the LAN, check the host firewall and private IP. If a workspace is missing, verify the server's OS account can read it and add its real path; do not copy repositories into `~/.cptr`. If the host sleeps, wake it: no remote route can serve a sleeping machine.
+
+## Trust boundary
+
+Do not turn an unreachable host into a publicly forwarded port. Remote access should remain limited to devices and networks you trust.

docs/ecosystem/computer/troubleshooting/docker-and-state.md

@@ -0,0 +1,37 @@
+---
+title: Docker and persistent-state problems
+sidebar_position: 4
+---
+
+# Docker and persistent-state problems
+
+## Use this when
+
+A Docker instance cannot write data, a project is absent in the container, or an apparent update has created a new empty instance.
+
+## Before you start
+
+Do not remove the data volume while diagnosing. Application state is in `/data`; the host project is only visible where you mount it, such as `/workspace`.
+
+## Do it
+
+Inspect the running configuration:
+
+```bash
+docker volume inspect cptr-data
+docker inspect <container-name>
+```
+
+Confirm the container has `cptr-data` mounted at `/data` and the intended host project mounted at `/workspace`. For a writable bind-mounted data directory, ensure the container user can create and update `app.db` there.
+
+## Verify it worked
+
+The container starts without SQLite write errors, the browser shows the preexisting account/workspaces, and a terminal tab reports `pwd` as `/workspace`. `curl http://127.0.0.1:8000/api/health` from the host returns `status: ok`.
+
+## If it did not
+
+If the setup wizard reappears, recreate the container with the original `/data` volume. If a workspace is empty, correct the project bind mount and working directory. If SQLite cannot write, repair the host directory ownership or replace a broken bind mount with a Docker volume; do not run the container privileged as a permissions shortcut.
+
+## Trust boundary
+
+Container mounts define the data and project files the service can change. Minimizing mounts limits blast radius, but a signed-in user can still use the shell within those mounts.

docs/ecosystem/computer/troubleshooting/index.md

@@ -0,0 +1,14 @@
+---
+title: Troubleshooting
+sidebar_position: 1
+---
+
+# Troubleshooting
+
+Start with the observable state. A healthy process answers `/api/health`; a useful workspace shows the same path, git state, and terminal as the host. These pages separate installation, network, and persistent-state problems so you do not erase the wrong thing.
+
+- [Install and login](./install-and-login)
+- [Access and workspaces](./access-and-workspaces)
+- [Docker and persistent state](./docker-and-state)
+
+If the host is publicly reachable or an untrusted user can sign in, stop and read [the security model](/ecosystem/computer/remote-access/security-model) before debugging further.

docs/ecosystem/computer/troubleshooting/install-and-login.md

@@ -0,0 +1,37 @@
+---
+title: Install and login problems
+sidebar_position: 2
+---
+
+# Install and login problems
+
+## Use this when
+
+The server will not start, the first setup URL fails, or a known account cannot sign in on the host.
+
+## Before you start
+
+Keep the terminal where `cptr run` was started open. Its printed tokenized URL is for first-time setup and is different from a normal login URL. Do not delete `~/.cptr` to solve a login problem; it holds persistent state.
+
+## Do it
+
+Confirm the package and process:
+
+```bash
+cptr run --headless
+curl http://127.0.0.1:8000/api/health
+```
+
+Use the exact printed URL for initial setup. On Windows, use [the Windows setup guide](/ecosystem/computer/getting-started/windows) if the terminal reports a missing Visual C++ runtime.
+
+## Verify it worked
+
+The command prints a URL, health returns `status: ok`, and the browser presents either the setup wizard or the sign-in screen. A successful login returns you to your preexisting workspace list.
+
+## If it did not
+
+`Address already in use` means choose `--port 8001` or stop the process owning 8000. `cptr: command not found` means activate the correct environment or reinstall with `python -m pip install cptr`. A repeated `401` means the account/session is invalid; verify the URL and password rather than modifying the database. If the server exits, capture its stdout before reinstalling.
+
+## Trust boundary
+
+The setup URL contains a one-time bootstrap token. Do not paste it into a ticket, chat, shell history, or a public terminal recording.

docs/ecosystem/computer/use-cases/_category_.json

@@ -0,0 +1,11 @@
+{
+	"label": "Use cases",
+	"position": 10,
+	"collapsible": true,
+	"collapsed": true,
+	"link": {
+		"type": "generated-index",
+		"title": "Use cases",
+		"description": "Start with the job you need to finish on your real machine."
+	}
+}

docs/ecosystem/computer/use-cases/malik-agent-supervision.md

@@ -0,0 +1,45 @@
+---
+title: "Supervise a coding agent away from your desk"
+sidebar_position: 2
+---
+
+# Supervise a coding agent away from your desk
+
+**Persona: Malik, a SaaS founder.** His mini PC is running a native coding-agent task in the actual repository. At dinner, the agent reaches a migration decision. Malik wants to inspect the work and give a precise direction without losing the session or handing the agent an unlimited instruction.
+
+This is valuable because the agent works where the code already lives, while Malik stays in control. A **coding agent** is an AI program that can inspect files and run development commands; Open WebUI Computer gives Malik one place to see what it did, ask it a question, and review the resulting changed lines before accepting more work. He does not need to recreate the repository or blindly trust a chat transcript.
+
+## Use this when
+
+Use this when a coding agent is already working in a workspace you trust and a human decision, review, or small course correction is needed. It is for supervision, not for asking an unattended agent to make irreversible production changes.
+
+## Before you start
+
+- **Not set up yet?** Complete the [local trial](/ecosystem/computer/getting-started/local-trial), add [your first workspace](/ecosystem/computer/getting-started/first-workspace), configure [private remote access](/ecosystem/computer/remote-access/tailscale-and-tunnels), and [set up/detect the coding agent](/ecosystem/computer/agents/setup-and-detection) before leaving the host.
+- Configure the coding agent and its permission mode on the host before leaving. Confirm its detection status with a harmless task while at the machine.
+- Scope the chat to the intended workspace and state the deliverable, constraints, and test command in the initial instruction.
+- Ensure Malik can reach the host privately from his phone. A browser disconnect does not grant the agent a new permission level.
+
+## Do it
+
+1. Open the existing workspace and chat, not a new generic chat. Read the latest assistant message, the rows in the chat showing commands or files the agent touched, and any approval request.
+2. Open the git status strip at the bottom of the workspace and inspect the changed paths and diff. Ask the agent a specific question if the decision is unclear: for example, “Do not create a migration yet. Explain the existing data shape and show the affected callers.”
+3. Approve only the action Malik understands and wants. If he needs a different approach, send a concrete follow-up in the same chat so it retains the workspace context.
+4. When the agent reports completion, review the diff and run or request the focused test. Keep the task open for a desktop review if the change is broad.
+
+See [Search and chats](/ecosystem/computer/workspace/search-chats) for finding and resuming the right chat, and [Git, branches, stashes, and worktrees](/ecosystem/computer/workspace/git) for checking the real repository state.
+
+## Verify it worked
+
+The chat shows the agent's continuing tool activity in the existing workspace, not a detached copy of the repo. The git panel reflects its edits, and a follow-up message appears in the same conversation. A read-only task or focused test produces an observable result before Malik authorizes a broader change.
+
+## If it did not
+
+- **The agent is unavailable or not detected:** do not replace it with a different model mid-task. Check the agent configuration on the host, then resume after detection succeeds.
+- **The chat looks unfamiliar:** verify the workspace path and chat history before approving anything. Use global search to find the original chat rather than recreating its context.
+- **The agent proposes a destructive command:** decline it, request an explanation or a dry-run, and move the decision to a reviewed desktop session if needed.
+- **The agent stopped after a disconnect:** reopen the same chat and inspect the last tool result. Do not assume an unfinished command completed.
+
+## Trust boundary
+
+A native coding agent works in the real workspace and may use the host tools allowed by its configured mode. Its output is not a security boundary and its suggestions are not automatically safe. Malik remains responsible for approvals, credentials available to the host, and every command or diff he accepts.

docs/ecosystem/computer/use-cases/nora-remote-fix.md

@@ -0,0 +1,46 @@
+---
+title: "Fix a production issue from your phone"
+sidebar_position: 1
+---
+
+# Fix a production issue from your phone
+
+**Persona: Nora, a Rails consultant.** Her iMac at home has the `payments` branch, a local database, and the terminal that reproduced an invoice bug. A client reports the problem while Nora is on a train with her iPhone. She needs to inspect the real branch and make a small, reviewable correction, not rebuild her environment in the cloud.
+
+This is valuable when the answer is already on your machine. Instead of waiting to reach your desk or creating a second development setup, Open WebUI Computer lets you see the same project state from your phone: the current branch, the files that changed, and the terminal that was already running. A **diff** is simply the list of changed lines that you review before keeping a change.
+
+## Use this when
+
+The repository, local service, credentials, or uncommitted work you need already live on the machine running Open WebUI Computer. This is a good fit for a narrow diagnosis, a one-file correction, or checking a deploy. It is not a reason to merge an unreviewed change from a phone.
+
+## Before you start
+
+- **Not set up yet?** Complete the [local trial](/ecosystem/computer/getting-started/local-trial), add [your first workspace](/ecosystem/computer/getting-started/first-workspace), then configure [private remote access](/ecosystem/computer/remote-access/tailscale-and-tunnels). Do those from the host before you are on the train.
+- Open WebUI Computer is already running on Nora's iMac and reachable over a private network path. It must not be exposed as a public service.
+- The `payments` workspace is added, and Nora can sign in from her phone.
+- Nora knows the affected file or has a reproducible command. If the issue could damage data, she starts with a read-only check and leaves the migration or rollback for a reviewed desktop session.
+
+## Do it
+
+1. From the phone, sign in and open the **payments** workspace. The file browser, git bar, and terminal are the same host workspace Nora left behind.
+2. Expand the git status strip at the bottom of the workspace to see the current branch and changed files. Open the relevant diff before editing. If the working tree contains unrelated changes, do not discard them.
+3. Open a terminal and run the smallest read-only diagnostic that confirms the report, such as the focused test or log query Nora would use at her desk.
+4. Open the affected file from the file browser, make the narrow correction, and save it. Use the git panel to inspect the resulting diff.
+5. Run the focused test again. If it passes, stage and commit only the intended files, or leave the diff ready for Nora to review on a larger screen.
+
+For the details of file editing, see [Files, editor, tabs, and splits](/ecosystem/computer/workspace/files-editor). For a fuller git workflow, see [Git, branches, stashes, and worktrees](/ecosystem/computer/workspace/git).
+
+## Verify it worked
+
+The phone shows the same active branch and pre-existing terminal output as the iMac. The git panel shows only Nora's intended changed file and the focused command reports the expected result. Close the browser, reopen the workspace, and confirm the saved file and git diff are still present.
+
+## If it did not
+
+- **The workspace is missing or points at the wrong project:** stop before editing. Check the absolute path in the workspace picker and use [Workspace paths](/ecosystem/computer/workspace/workspace-paths) to add or switch to the correct directory.
+- **The terminal is disconnected:** refresh the tab and reopen the terminal. If the host slept, woke, or rebooted, rerun the harmless diagnostic rather than assuming the previous process continued.
+- **The diff contains unexpected changes:** do not use a blanket discard action. Copy the paths, inspect them on the host, and preserve changes you did not create.
+- **The phone cannot reach the service:** return to [private access setup](/ecosystem/computer/remote-access/tailscale-and-tunnels) or the host network. Do not solve this by publishing the service directly to the internet.
+
+## Trust boundary
+
+Signing in gives Nora the host-level file and shell access that makes this useful. Treat the instance like private SSH: one trusted user on a network she controls. A terminal command may access more than the active workspace, and a commit or push changes the real repository. Keep the task narrow, inspect the diff, and use a desktop review for high-impact work.

docs/ecosystem/computer/use-cases/theo-real-device-preview.md

@@ -0,0 +1,45 @@
+---
+title: "Preview your local app on a real device"
+sidebar_position: 3
+---
+
+# Preview your local app on a real device
+
+**Persona: Theo, a mobile developer.** His Mac is already running a local app server. He needs to verify a touch interaction on an iPad without copying the project to another service or guessing from a desktop viewport.
+
+This is valuable because a phone or tablet can reveal problems a desktop browser hides. A **local app server** is the development copy of an app that is already running on Theo's Mac. Open WebUI Computer lets him open that same running app from an iPad, while keeping the source files and terminal logs from the original machine close by.
+
+## Use this when
+
+Use this when a process in a workspace has opened a local port and you want to view that process through Open WebUI Computer from another signed-in device. This is especially useful for checking a real browser, touch layout, or a quick internal demo.
+
+## Before you start
+
+- **Not set up yet?** Complete the [local trial](/ecosystem/computer/getting-started/local-trial), add [your first workspace](/ecosystem/computer/getting-started/first-workspace), then configure [private remote access](/ecosystem/computer/remote-access/tailscale-and-tunnels) before testing from the iPad.
+- The app is started from the intended workspace on the host. Note its usual port and command.
+- Theo can sign in to Open WebUI Computer from the test device through a private network path.
+- The app itself is safe to view in this context. A preview can expose whatever the local process serves to every user who can use this trusted instance.
+
+## Do it
+
+1. Open the workspace and start the app in the terminal if it is not already running.
+2. In the file browser, find the **Ports** row above the file list. Select the detected `:port` for the process, or use the port notification when it appears.
+3. Open the preview tab on the iPad and exercise the real interaction. Keep the terminal visible in another tab or split when watching logs.
+4. Make a small code change if needed, save it, and refresh the preview if the development server does not hot-reload.
+
+For the underlying terminal behavior, see [Persistent terminals](/ecosystem/computer/workspace/terminals). For browser and preview details, see [Browser sessions and local-port previews](/ecosystem/computer/workspace/browser-port-preview).
+
+## Verify it worked
+
+The file browser lists the running port, the preview opens content served by Theo's existing process, and the terminal continues to show the same process output. Close and reopen the browser session: the process is still running unless Theo deliberately stopped it or the host changed state.
+
+## If it did not
+
+- **No port appears:** confirm the process is still running and listening on a port from its terminal output. Restart it from the workspace if needed.
+- **The preview is blank or wrong:** verify the selected port and app route. Check the terminal logs before changing the app.
+- **The process stopped when the browser closed:** inspect the terminal session and host sleep/restart history. Start the process again and use the terminal output as the source of truth.
+- **The test device cannot open the app:** confirm it is signed in to the same private Open WebUI Computer instance; do not bind the service publicly as a workaround.
+
+## Trust boundary
+
+The preview proxies a service running on the host. It is not a public deployment mechanism or a substitute for application authentication. Anyone who can use the trusted Computer instance may be able to open that preview, so do not run an unsafe debug server or disclose a preview URL outside that trust boundary.

docs/ecosystem/computer/workspace/_category_.json

@@ -0,0 +1,11 @@
+{
+	"label": "Your workspace",
+	"position": 20,
+	"collapsible": true,
+	"collapsed": true,
+	"link": {
+		"type": "generated-index",
+		"title": "Your workspace",
+		"description": "Use the files, terminal, git state, and running processes already on your machine."
+	}
+}

docs/ecosystem/computer/workspace/browser-port-preview.md

@@ -0,0 +1,39 @@
+---
+title: "Browser sessions and local-port previews"
+sidebar_position: 5
+---
+
+# Browser sessions and local-port previews
+
+**Useful for Theo.** Open WebUI Computer can show a local service that is already running on the host through a workspace preview tab. This is how Theo checks his app from an iPad while keeping the original terminal, logs, and source files in reach.
+
+## Use this when
+
+Preview a development server, inspect a local web UI, or pair a browser view with terminal output. Use a normal deployment path for a public demo or an application that must be reached by people outside the trusted Computer instance.
+
+## Before you start
+
+- Start the service in the intended workspace and confirm the listening port from its output.
+- Sign in to the same private Open WebUI Computer instance from the browser or device you will use for testing.
+- Know whether the local app assumes `localhost`, a particular origin, or its own authentication. The preview does not rewrite the app's security model.
+
+## Do it
+
+1. Open the file browser in the workspace. When a process opens a port, its `:port` appears in the **Ports** row.
+2. Select the port to open a preview tab. Switch back to the terminal or arrange the preview beside source files as needed.
+3. Navigate through the app and inspect terminal logs while testing. Save source edits and let the development server reload, or refresh the preview when its toolchain requires it.
+4. Close the preview when finished; stop the server separately from the terminal if it should no longer run.
+
+## Verify it worked
+
+The preview displays content from the expected local process, and requests or logs appear in that process's terminal. A change made in the selected workspace is reflected after the normal reload path. Reopening the preview shows the same host service while it remains running.
+
+## If it did not
+
+- **There is no Ports row:** inspect the terminal for a failed start or a different port. Ensure the process is listening rather than merely compiling.
+- **The page fails to load:** try the displayed port again and check server logs. Some apps need their configured host or origin adjusted for proxying; fix the app deliberately rather than exposing the service publicly.
+- **A page works on desktop but not the test device:** check the device browser, app authentication, and responsive behavior. The preview proves the real-device request path, not every platform-specific behavior.
+
+## Trust boundary
+
+The preview is a private convenience for services on the host. It can make a development server visible to anyone able to use this instance. Do not use it as a public URL, and do not assume it protects a service that lacks its own authentication.

docs/ecosystem/computer/workspace/files-editor.md

@@ -0,0 +1,39 @@
+---
+title: "Files, editor, tabs, and splits"
+sidebar_position: 2
+---
+
+# Files, editor, tabs, and splits
+
+**Useful for Nora.** The file browser is for the files already in the selected workspace: open a source file, inspect a Markdown or media preview, keep related files open, and arrange the view around the small decision you need to make.
+
+## Use this when
+
+Use this to inspect or change a real workspace file, compare a source file with a test or diff, or manage a small set of open files while away from your desk. For a large refactor, use the editor to investigate but reserve broad review for a screen and workflow that suit it.
+
+## Before you start
+
+- Select the correct workspace and confirm its path before opening or editing files.
+- Ensure the host account can write the file. Read-only mounts and source-control permissions still apply.
+- If a file contains secrets, do not paste it into an AI chat or share screenshots of it.
+
+## Do it
+
+1. Browse with the file tree or type a name in its filter. Use the breadcrumb to move back through directories.
+2. Select a file to open it in an editor tab. Use the file's preview control where available for Markdown and supported visual formats.
+3. Keep two files open in tabs, then drag a tab into a split when comparing an implementation with its test or configuration.
+4. Save the smallest intended edit and return to the git bar to inspect the diff. Use the file context menu to copy a path, rename, download, or manage an entry only when that is really the change you intend.
+
+## Verify it worked
+
+The editor title and breadcrumb identify the expected workspace path. After saving, reopening the file shows the same content and the git panel reports the intended modification. In a split, each pane remains bound to the file you selected instead of replacing the other view.
+
+## If it did not
+
+- **A file will not save:** check the workspace path, host permissions, and whether the directory is mounted read-only. Do not copy the content elsewhere and assume the real file changed.
+- **The wrong tab changed:** use the tab title and path before saving, then inspect the git diff. Restore only a line you can identify.
+- **A visual preview is unavailable:** open the source form or use the terminal's native tool. Not every file type is editable or previewable in the browser.
+
+## Trust boundary
+
+File actions operate on the host filesystem. Rename, delete, upload, and save are real operations, not a disposable browser draft. Keep the instance private and verify the path before making changes, especially from a small screen.

docs/ecosystem/computer/workspace/git.md

@@ -0,0 +1,41 @@
+---
+title: "Git, branches, stashes, and worktrees"
+sidebar_position: 4
+---
+
+# Git, branches, stashes, and worktrees
+
+**Useful for Nora and Malik.** The git bar reflects the repository in the selected workspace. It gives you a fast answer to the question that matters during remote work: what changed here, on which branch, and is this safe to continue?
+
+## Use this when
+
+Inspect a diff, stage and commit a small fix, switch branches with uncommitted work, recover a known stash, or move to a separate git worktree. Use a worktree when two tasks need separate checked-out files at the same time; it is safer than repeatedly switching a busy working tree.
+
+## Before you start
+
+- Select the workspace that contains the actual checkout and read the branch name and changed-file count.
+- Inspect the diff before staging. A dirty working tree may include work made earlier on the host.
+- Ensure you understand the repository's branch and push policy. The UI does not make a remote push or a migration review safe by itself.
+
+## Do it
+
+1. Expand the git bar to review changed files, diffs, staged state, and ahead/behind status.
+2. Stage only the paths that belong to the task, write a specific commit message, and commit after the focused test passes.
+3. Use the branch picker to create, find, rename, delete, or switch branches. When a switch needs a clean tree, review the offered stash behavior and name the stash so it is recoverable.
+4. Use the worktree picker to see existing worktrees or create a branch-backed worktree. Switch to it as its own workspace path; it contains a distinct checkout, not a magic view of the first branch.
+5. Use the stash view to inspect and restore the intended stash. Resolve conflicts in the real files and re-check the diff.
+
+## Verify it worked
+
+The git bar shows the intended branch or worktree path, the diff matches only the files you selected, and the commit appears in history. After a worktree switch, the file browser and terminal show that worktree's files and branch. After restoring a stash, the expected changes appear in the diff rather than silently disappearing.
+
+## If it did not
+
+- **A branch cannot switch:** inspect uncommitted changes and either commit, preserve them in a clearly named stash, or use a separate worktree. Do not discard work to force a switch.
+- **A worktree is missing:** refresh the worktree picker and confirm it exists in git. Add its target path as a workspace if it is not already available.
+- **A stash will not apply cleanly:** stop and resolve the conflict from the checkout. Keep the stash until the result is verified.
+- **The diff is surprising:** unstage first, inspect paths and history, and avoid pushing until you can explain every change.
+
+## Trust boundary
+
+Git commands alter the real checkout and may communicate with configured remotes. A worktree reduces collisions between tasks; it does not isolate credentials, hooks, or shell access. Treat every stage, commit, branch deletion, and push as a host and repository action.

docs/ecosystem/computer/workspace/pwa-share-shortcuts.md

@@ -0,0 +1,41 @@
+---
+title: "Install the app, share into a workspace, and use shortcuts"
+sidebar_position: 7
+---
+
+# Install the app, share into a workspace, and use shortcuts
+
+**Useful for Nora and Theo.** Installing Open WebUI Computer as a PWA makes the private machine feel available from a phone or tablet: it opens in an app-like window, can receive a shared link or file, and keeps the first useful actions close at hand.
+
+## Use this when
+
+Use this after the normal browser workflow already works. Install it to reduce friction for private, repeatable tasks such as opening a workspace, finding a chat, taking a note, or sending a link into the project context. It is not a replacement for securing remote access first.
+
+## Before you start
+
+- Confirm the app is reachable through the private URL you intend to use regularly and that signing in works in the browser.
+- On the device, allow the browser or operating system to install web apps. Installation prompts vary by platform.
+- Decide where shared files should land. A file import writes to the real workspace, so choose a path you are comfortable receiving data into.
+
+## Do it
+
+1. Open Open WebUI Computer in the device browser and use its install action or the browser's **Add to Home Screen** / install command. Launch the new app icon and sign in.
+2. Open Settings and select **PWA** to choose how shared text and links behave: ask each time, create a chat draft, or create a note file.
+3. In the same PWA settings, choose file-import behavior: the workspace root, ask for a folder, or a configured folder.
+4. If the browser and operating system support PWA share targets, use the operating system's Share action and choose Open WebUI Computer. Confirm the destination before sending a file, URL, or text into the workspace. On unsupported devices, copy the link/text into a new chat or note manually, or upload the file from the workspace file browser.
+5. Use keyboard shortcuts when a hardware keyboard is available: `Cmd+K` for quick search and `Cmd+Shift+F` for broad search. On Windows and Linux, use `Ctrl` in place of `Cmd`.
+
+## Verify it worked
+
+The installed icon opens the same private instance and workspace, not a blank unrelated browser profile. On a browser that supports share targets, a harmless shared note or link appears according to the PWA preference you selected. On an unsupported browser, the manual chat/note or file-browser fallback reaches the same workspace. A test file arrives in the selected workspace location, and the search shortcut opens the expected search dialog.
+
+## If it did not
+
+- **No install option appears:** use the browser's menu or verify that the device/browser supports PWA installation. Continue in the browser if it does not.
+- **A shared item went to the wrong place:** stop before acting on it, find it in the file browser, and adjust PWA import settings before sending another. Do not delete an unfamiliar file without checking its source.
+- **The installed app cannot connect:** verify the private host URL and network path in the regular browser first. Offline fallback does not make the remote host or its files available without a connection.
+- **A shortcut does nothing:** check that focus is not inside another input and use the platform's `Ctrl` equivalent where appropriate.
+
+## Trust boundary
+
+The PWA stores a convenient entry point to the same powerful host service; it does not reduce access. Shared files, links, and text may become workspace data, and an installed app on an unlocked device can be a direct path to the instance. Use device lock, sign out when appropriate, and keep the instance on a private network.

docs/ecosystem/computer/workspace/search-chats.md

@@ -0,0 +1,39 @@
+---
+title: "Search and chats"
+sidebar_position: 6
+---
+
+# Search and chats
+
+**Useful for Malik.** A workspace chat is part of the project record: it holds the question, tool activity, decisions, and follow-ups for work in that actual directory. Global search lets you recover a chat or file without recreating the context from memory.
+
+## Use this when
+
+Find a previous agent task, jump to a file across workspaces, resume the correct conversation after changing device, or separate one line of work from another. Start a fresh chat when the task has genuinely changed; do not reuse a long conversation just because it is open.
+
+## Before you start
+
+- Identify the workspace or project where the work belongs. Workspace-scoped search narrows results; searching outside a workspace can cover all configured workspaces.
+- Treat chat content as project data. It may include task details, filenames, command output, or sensitive business context.
+- If an agent session is involved, confirm its current workspace before sending a follow-up.
+
+## Do it
+
+1. Press `Cmd+K` (or `Ctrl+K` on Windows and Linux) to open quick search. With an active workspace, search results stay scoped to it; without one, search can cover configured workspaces.
+2. Enter a chat title, message phrase, file name, or path fragment. Select a result to open the matching chat or file.
+3. Use `Cmd+Shift+F` (or `Ctrl+Shift+F`) for the broader search shortcut. With an empty query, the search dialog shows recent chats; `Cmd+1` through `Cmd+9` selects a recent result.
+4. Resume the exact chat for a continuing task. Add a concise follow-up that names the decision, constraint, or test instead of repeating the entire task.
+
+## Verify it worked
+
+The opened result shows the expected workspace path and prior messages or file. A resumed chat preserves its existing conversation history, and a new message lands in that chat rather than creating a similarly named duplicate. Switching device and searching again finds the same project record.
+
+## If it did not
+
+- **Search finds too much:** first open the intended workspace, then search again with a distinctive path, title, or phrase.
+- **Search finds nothing:** check spelling and whether the workspace has been added to this instance. Browse the workspace directly if the file name changed.
+- **The wrong chat is open:** do not approve work or send context-sensitive instructions. Return to search and select the chat whose workspace and prior tool activity match the task.
+
+## Trust boundary
+
+Chats are stored alongside the workspace experience and can be searched by the trusted instance user. Do not use chat titles or messages as a place to put secrets. Sharing access to the instance also shares the ability to recover its project conversations.

docs/ecosystem/computer/workspace/terminals.md

@@ -0,0 +1,39 @@
+---
+title: "Persistent terminals"
+sidebar_position: 3
+---
+
+# Persistent terminals
+
+**Useful for Nora and Theo.** The terminal is a PTY-backed shell on the host. It is useful precisely because it sees the running services, credentials, checkout, and local tools you already use at the machine.
+
+## Use this when
+
+Run a focused test, inspect logs, start a local development server, or resume a command from another device. The terminal is often the quickest way to establish what is really happening, but it has the same power and risk as a direct host shell.
+
+## Before you start
+
+- Confirm the selected workspace and the terminal's current directory before running a command.
+- Know whether the command reads, changes, or deletes data. Start with status, logs, or a focused test when diagnosing.
+- Keep the host awake and connected if the task must continue. Browser reconnection cannot recover a process after a host shutdown or sleep policy stops it.
+
+## Do it
+
+1. Open a terminal in the selected workspace and run `pwd` or an equivalent harmless command to confirm context.
+2. Run the narrow diagnostic or task. For Theo's app, start the usual development command and watch its port and output.
+3. Leave the terminal open while you use another tab, a split, or another device. Return to the same workspace to review later output.
+4. Stop a server or long-running command deliberately when finished; do not assume closing the browser tab is the same as shutting it down.
+
+## Verify it worked
+
+The terminal reports the expected working directory and command output. A running server remains visible in the terminal and its detected port appears in the file browser. Reconnecting to the workspace shows the existing session output unless the host or process itself changed state.
+
+## If it did not
+
+- **The shell opens in an unexpected directory:** `cd` to the intended project and confirm with `pwd`; then check the workspace configuration before relying on it again.
+- **The session reconnects but a command is gone:** inspect the final output and host state. Rerun a safe diagnostic rather than assuming success.
+- **Input or display is awkward on mobile:** use a short command, keyboard accessory, or return to a desktop browser. Do not turn a risky one-liner into a longer one just to avoid review.
+
+## Trust boundary
+
+Terminal commands are not limited to AI file-tool restrictions or the workspace tree. They run with the host account's permissions. Never give an untrusted person access to the instance, and do not treat a private browser tab as a sandbox.

docs/ecosystem/computer/workspace/workspace-paths.md

@@ -0,0 +1,39 @@
+---
+title: "Workspace paths"
+sidebar_position: 1
+---
+
+# Workspace paths
+
+**Useful for Nora and Malik.** A workspace is a directory on the machine running Open WebUI Computer, not an uploaded project copy. Selecting a workspace determines the file browser, editor, git panel, chat context, and the starting context for work in that project.
+
+## Use this when
+
+Add a repository or project directory, switch between existing projects, or verify that a chat and its files refer to the directory you intended. Use a new workspace for a distinct checkout or worktree; do not point two unrelated projects at a convenient parent directory just to make them appear together.
+
+## Before you start
+
+- Know the absolute path on the host, for example `/Users/nora/src/payments`, not a path from the phone or a cloud drive.
+- The service account that runs Open WebUI Computer can read the directory and, if you intend to edit, write to it.
+- Review what is inside the path. Workspaces are convenience boundaries for the UI and AI file tools, not a sandbox for the terminal.
+
+## Do it
+
+1. Open the workspace picker in the sidebar and add or select the directory on the host.
+2. Confirm the displayed workspace name and path, then open the file browser and git bar.
+3. For a separate checkout or git worktree, add its own directory as a separate workspace. This preserves the branch and files already checked out there.
+4. Switch projects from the workspace list instead of changing directories in an unrelated terminal and assuming the rest of the UI followed.
+
+## Verify it worked
+
+The file browser root, git branch, terminal working directory, and new chats all correspond to the same selected path. Switch away and back: the intended workspace returns with its own open tabs and history rather than showing another repository's files.
+
+## If it did not
+
+- **The path is missing:** check the exact host path and whether the service account can read it. In Docker, confirm the path is mounted into the container.
+- **The git bar shows no repository:** select the repository root or a directory beneath a valid checkout, then refresh the workspace.
+- **The wrong files appear in chat:** verify the active workspace before adding a file mention or approving agent work. Open a new chat only after selecting the correct path.
+
+## Trust boundary
+
+Adding a path makes that real host directory available through the instance to its trusted user. Do not add a broad home directory or secrets directory merely for convenience. A terminal remains capable of moving outside the active workspace, so the host account and network boundary still matter.