refac

2026-07-21 01:55:22 -04:00 · 2026-07-10 17:53:18 -05:00
parent efc4a60bab
commit 9144abcae8
64 changed files with 775 additions and 299 deletions
@@ -1,10 +1,10 @@
 {
 	"label": "AI and coding agents",
-	"position": 20,
+	"position": 6,
 	"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."
+		"type": "doc",
+		"id": "ecosystem/computer/agents/index"
 	}
 }
@@ -7,7 +7,7 @@ sidebar_position: 5

 ## 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.
+Use this when you repeat a workflow, want the agent to remember durable project facts, need parallel investigation, or want to supply web, voice, or image input rather than typing everything.

 ## Before you start

@@ -9,7 +9,7 @@ The useful part of remote work is continuity: you can leave a task, reconnect on

 ## 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.
+Use this when you start an investigation before leaving the desk or need to steer a long-running agent task from a smaller screen.

 ## Before you start

@@ -0,0 +1,20 @@
+---
+title: AI and coding agents
+sidebar_position: 1
+---
+
+# AI and coding agents
+
+An agent is most useful here when the answer lives in the project already on your machine: its files, branch, terminal, local service, and installed tools. Open WebUI Computer lets you use an API model or a coding-agent subscription in that existing workspace, then inspect the result beside the real diff and terminal.
+
+Start small. Choose a model, ask it to explain one real file, then decide whether it should be allowed to make a change. You do not need an AI connection to use the rest of Computer.
+
+| Need | Read this |
+| --- | --- |
+| Decide between an API key/local endpoint and an installed agent subscription | [API models or native coding agents](./models) |
+| Make a native agent available on the host | [Set up and detect a coding agent](./setup-and-detection) |
+| Review changes and control approval | [Supervise agent work safely](./supervise-work) |
+| Continue work across devices or recover after an interruption | [Plans, queues, resume, and context](./continuity) |
+| Give an agent reusable guidance or more input modes | [Skills, memory, sub-agents, web, voice, and images](./capabilities) |
+
+Not a fit: use a normal chat product when you only need conversation, knowledge, or model comparison. Use a disposable environment when an untrusted agent or user must not reach the real host.
@@ -9,7 +9,7 @@ Open WebUI Computer can run an agent through an API connection, or through a cod

 ## 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.
+Use this when you have an OpenAI, Anthropic, Ollama, or OpenAI-compatible endpoint and want a model to inspect or change a project, or already pay for Codex or Claude Code and want that subscription to work in the browser without adding an API key.

 ## Before you start

@@ -9,7 +9,7 @@ Native profiles connect the browser UI to a coding-agent command already present

 ## 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.
+Use this when you have a Codex, Claude Code, Cursor, Grok, OpenCode, Cline, or Pi subscription and want to use it from a Computer chat in the same repository.

 ## Before you start

@@ -9,7 +9,7 @@ Open WebUI Computer keeps the agent beside the files, terminal, git view, and ta

 ## 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.
+Use this when you want 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

@@ -1,6 +1,6 @@
 ---
 title: "What Open WebUI Computer can do"
-sidebar_position: 5
+unlisted: true
 ---

 # What Open WebUI Computer can do
@@ -11,7 +11,7 @@ This is a map to the documentation, not a feature checklist. Start with the job
 | --- | --- |
 | 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) |
+| Review an agent, a diff, or a local service while away | [Use cases](./use-cases/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) |
@@ -5,7 +5,7 @@ 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.
+Choose the product that owns the thing you need to do, not the product with the longest feature list.

 | Your starting point | Choose | Why |
 | --- | --- | --- |
@@ -13,12 +13,20 @@ Choose the product that owns the thing you need to do—not the product with the
 | “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
+## Use both when the conversation needs a real machine

-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.
+Keep research and model selection in Open WebUI when it is the AI surface you prefer. If a machine has the repository, scripts, browser login, and local state that an AI must use, connect that Computer workspace through the gateway and choose it 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.

+| In a combined request | What it owns |
+| --- | --- |
+| **Open WebUI** | The caller conversation and interface. |
+| **`cptr/<workspace>`** | The selected real Computer workspace. |
+| **Open WebUI Computer** | The configured model or agent that executes the task in that workspace. |
+
+Open WebUI knowledge bases, model-agent tools, system prompts, users, and general configuration are not forwarded into Computer unless you configure equivalent capabilities in Computer.
+
 **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).
@@ -31,14 +39,24 @@ The gateway exposes workspaces as OpenAI-compatible models. It does **not** sync

 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 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, with 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.
+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.

+## For agent-native users
+
+If products such as Hermes Agent or OpenClaw have made you excited about AI that can actually do work, Open WebUI Computer answers a different but adjacent question: **where does that work live?**
+
+Computer is an agent platform, a workspace-centered control surface, and a personal machine workspace in one. It keeps the repository, installed tools, running processes, local browser state, terminal sessions, and review surface together. You can use an API model or supported native coding-agent backend, delegate work to sub-agents, schedule it, connect tools, and then see the real diff and process output instead of treating the agent as a detached conversation.
+
+Here, **meta-harness** means one place to choose, connect, and supervise several kinds of agent work. Each task uses its selected Computer workspace; bots, automations, and gateway models are configured separately, so check the workspace named by each integration before granting it trust.
+
+Hermes Agent and OpenClaw are not current native Computer backends. You can operate an installed CLI in a Computer terminal, but it will not become a selectable native chat backend or gain Computer task, approval, and session integration unless it is listed among [supported coding-agent backends](./agents/models). Choose Computer when you want a high-trust agent platform rooted in your own machine, and use [agent compatibility](./reference/agent-compatibility) for the current supported paths.
+
 ## Choose your next guide

 - Need the machine itself? [Try Open WebUI Computer locally](./getting-started/local-trial).
@@ -1,6 +1,6 @@
 ---
 title: "Core concepts"
-sidebar_position: 3
+unlisted: true
 ---

 # Core concepts
@@ -21,7 +21,7 @@ Open WebUI Computer is easiest to understand when you separate the machine from

 ## 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.
+Open WebUI Computer does not reconstruct a project somewhere else. It reconnects you to the host and directory you chose. That is why you can see the same dirty branch from a phone or continue an agent session that started at your desk.

 ## Verify it worked

@@ -1,8 +1,10 @@
 {
 	"label": "Get started",
-	"position": 1,
+	"position": 3,
+	"collapsible": true,
+	"collapsed": true,
 	"link": {
-		"type": "generated-index",
-		"description": "Try Open WebUI Computer on the machine and workspace you already use."
+		"type": "doc",
+		"id": "ecosystem/computer/getting-started/index"
 	}
 }
@@ -5,7 +5,7 @@ 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 to answer the important question: “Am I looking at the actual checkout that has the issue, not a disposable cloud copy?”

 ## Use this when

@@ -14,6 +14,8 @@ Start locally. The first useful proof is not an AI demo: open an existing projec
 | 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) |
+| Update a trusted installation without losing state | [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).
+
+Install the browser app only after private browser access already works; its share, import, and device-specific behavior belongs in [PWA, sharing, and shortcuts](/ecosystem/computer/workspace/pwa-share-shortcuts).
@@ -5,7 +5,7 @@ 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.
+Start by proving that Open WebUI Computer can show the existing project and terminal on your machine before you trust it from another screen.

 ## Use this when

@@ -1,32 +1,30 @@
 ---
-title: PWA and updates
+title: Update Open WebUI Computer
 sidebar_position: 7
 ---

-# Install the app and update it
+# Update Open WebUI Computer

 ## 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.
+Use this when you need to update a trusted single-host installation without losing its state. For installing the browser app, sharing files from a device, or PWA recovery, use [PWA, sharing, and shortcuts](/ecosystem/computer/workspace/pwa-share-shortcuts).

 ## 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.
+Keep the data directory or Docker `/data` volume persistent, and make a backup before changing a working host. Read the release notes and know whether the host was installed with Python or Docker.

 ## 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.
+For a Python installation, stop the process, upgrade the same environment with `pip install --upgrade cptr`, then start `cptr run`. For Docker, follow [Docker volumes and safe upgrades](/ecosystem/computer/operate/docker-and-upgrades) so the replacement container retains 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`.
+After an update, the existing account and workspace remain in the sidebar, and `curl http://127.0.0.1:8000/api/health` returns `status: ok`. If the browser still shows an older interface, reload it once after confirming the server is healthy.

 ## 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).
+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). If the browser app itself is stale or cannot connect, use the PWA guide's [recovery steps](/ecosystem/computer/workspace/pwa-share-shortcuts#if-it-did-not).

 ## 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.
+An update changes code that can access the host data directory and mounted projects. Keep backups protected, review releases, and retain the previous version until the new one passes the health and workspace checks.
@@ -17,69 +17,73 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
  style={{ width: '100%', margin: '0.25rem 0 1.75rem' }}
 />

-**Your actual computer, available from the browser you have with you.**
+**Your project is on your computer. Open WebUI Computer lets you reach that same project from the browser in your hand.**

-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.
+Imagine your website is running on the computer at home. Its files are there. A task may already be running. You only have your phone. Open WebUI Computer lets you open that **same computer** in a browser. It is not a copy of your project and it is not a blank cloud workspace.

-New here? Start with [Is Open WebUI Computer right for me?](./is-it-right) before learning any product terms.
+You can see the real files, the real app, the real terminal, and the real progress of an optional AI agent. Pick up the work, check it, guide it, or leave it alone until you are back at your desk.

-## Start with the problem in front of you
+## Why set up one more thing?

-| If this sounds like you | Start here | You will know it worked when |
+| Without Computer | With Computer |
 | --- | --- | --- |
-| **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. |
+| You recreate context: clone a repo, find the correct branch, restart a service, explain the task again. | You reopen the machine where that context already exists. |
+| You can use a chat AI, but it does not naturally have your local files, running app, or browser state. | An optional agent works in the selected real workspace, beside the files and tools you already use. |
+| You can SSH or remote-desktop into the host, but it is awkward to inspect a diff, preview an app, or guide an agent from a phone. | You get a mobile-first workspace for files, git, terminals, previews, and agent activity. |
+| You stop a small interruption until you can get back to the desk. | You can check the build, review a change, test the app, or answer an agent in a few minutes. |

-## Try it locally first
+## See a real job it can solve

-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.
+Open WebUI Computer is worth installing only if it removes a real interruption or keeps useful work continuous. Browse [real use cases](./use-cases/) before you install it:

-```bash
-pip install cptr
-cptr run
-```
+- Fix an issue, inspect a log, or check a dirty branch from another device.
+- Resume a workspace exactly where you left it.
+- Supervise an AI coding task in the actual repository.
+- Test a local app or prototype on a real phone or tablet.
+- Turn feedback, a note, a file, or a voice memo into context in the same project.
+- Triage an on-call interruption, run a recurring check, or use Open WebUI to direct work in a real workspace.
+
+## Start where you are
+
+| If you are... | Start here | What Computer adds |
+| --- | --- | --- |
+| New to terminals, agents, and self-hosting | [Is it right for me?](./is-it-right) | A local proof that you can see the project you already have, before networking or AI setup. |
+| A designer, student, or maker with a live prototype | [Test a local app on a real device](./use-cases/real-device-preview) | The real running prototype and its files, not a screenshot or recreated demo. |
+| A developer already using Codex, Claude Code, Cursor, Grok, OpenCode, Cline, or Pi | [AI and coding agents](./agents/) | A browser workspace around the same repository, terminal, git state, and agent session. |
+| An Open WebUI user | [Open WebUI, Computer, or both?](./choose) | An optional real-machine workspace behind the AI experience you already use. |
+| Comparing agent products such as Hermes Agent or OpenClaw | [What makes Computer different](./choose#for-agent-native-users) | An agent platform rooted in a personal machine and persistent workspace, not a detached agent conversation. |
+| A senior engineer or operator | [Remote access and security](./remote-access/) | The actual trust model, persistence, API, logging, and operational boundaries before you adopt it. |
+
+For advanced users, Computer is a workspace-centered control surface for the supported agents, tools, automations, and integrations you connect. You can call that a meta-harness, but the important boundary is simpler: **each task is attached to the Computer workspace selected for it.** Check that workspace before trusting an automation, bot, or gateway request.
+
+## Try the smallest useful version
+
+The first trial stays on the machine in front of you. It needs no remote network, AI key, agent, bot, or account with another service. Start it locally, open one existing folder, and decide whether seeing your real project this way is useful.

 [Try Open WebUI Computer locally →](./getting-started/local-trial)

-**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.
+If you have never used a terminal or git, start with [is it right for me?](./is-it-right). It explains the value in plain language and tells you when to stop.

-## What Open WebUI Computer is—and is not
+## Run it on your terms

-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.
+Open WebUI Computer is self-hosted. It runs on a machine you control, and its core workspace does not require a managed cloud account, cloud control plane, or AI provider. Your application state stays on that machine in `~/.cptr` by default, or in the Docker `/data` volume.

-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.
+You can add model APIs, coding-agent subscriptions, search, git remotes, messaging, and external tools when they are useful. Those services have their own network and data boundaries. The core value remains available without them: your files, terminal, git, editor, and local apps stay on your computer.

-[Read the security model →](./remote-access/security-model) · [Learn the core concepts →](./concepts) · [See who it is for →](./personas)
+## Use Open WebUI and Computer together

-## Use it with Open WebUI
+Use Open WebUI when you want an AI conversation, models, knowledge, prompts, or team workflows. Use Open WebUI Computer when the work must touch your personal machine. Use both when you want Open WebUI as the AI surface and Computer as the real workspace where the action happens.

-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.
+[Choose Open WebUI, Computer, or both →](./choose)

 ## Open WebUI Computer vs Open Terminal

-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.
+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.

 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.

-## Explore the documentation
+## Is it for you?

- [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.
+It is a strong fit if the project, app, terminal, files, or AI work you care about already exists on a machine you control. It is not the right fit if you need a disposable cloud environment, safely isolated machines for untrusted people, or a public shell service.

-## Next step
-
-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.
+Read [the fit guide](./is-it-right) before exposing it remotely. An authenticated user can access the host filesystem and shell, so treat it like private SSH, not a public web app.
@@ -1,10 +1,10 @@
 {
 	"label": "Automations and integrations",
-	"position": 21,
+	"position": 8,
 	"collapsible": true,
 	"collapsed": true,
 	"link": {
-		"type": "generated-index",
-		"description": "Bring a real Computer workspace to Open WebUI, schedules, notifications, messaging, and trusted external tools."
+		"type": "doc",
+		"id": "ecosystem/computer/integrations/index"
 	}
 }
@@ -1,15 +1,17 @@
 ---
-title: Schedule trusted work and get notified
-sidebar_position: 2
+title: Automations, notifications, and webhooks
+sidebar_position: 3
 ---

-# Schedule trusted work and get notified
+# Automations, notifications, and webhooks

-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.
+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. Notifications report what happened; authenticated webhooks trigger a known automation. They are not a safe way to accept arbitrary instructions from the internet.
+
+Use [Schedule trusted work](./automations) for the task itself and [Notifications and webhooks](./notifications-and-webhooks) for delivery and secret-trigger handling. This page explains the shared high-trust boundary.

 ## 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.
+Use this when you need a known prompt to run on a recurring schedule in one known workspace, then want a browser, webhook, or bot notification when it finishes or fails.

 ## Before you start

@@ -19,16 +21,15 @@ Priya wants a known prompt to run on a recurring schedule in one known workspace

 ## 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.
+1. Create and validate the task with [Schedule trusted work](./automations).
+2. Create and test its delivery or trigger with [Notifications and webhooks](./notifications-and-webhooks).
+3. Review run history before enabling a recurring schedule.

 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.
+The automation displays an upcoming run and **Run now** creates a run-history entry with a linked chat. Its notification target’s test succeeds before you rely on an automatic notification.

 ## If it did not

@@ -0,0 +1,35 @@
+---
+title: Schedule trusted work
+sidebar_position: 4
+---
+
+# Schedule trusted work
+
+Schedule a known task when its prompt, workspace, model, and expected output are stable. A good first automation runs one focused test or produces one report. It is not a substitute for reviewing a vague instruction later.
+
+## Use this when
+
+You need a recurring task to run in one workspace, such as a morning test, build check, or report.
+
+## Before you start
+
+- Choose the exact workspace, model, schedule, and bounded prompt.
+- Confirm the host and model will be available at the scheduled time.
+
+## Do it
+
+1. Open **Automations** and create the task with its workspace, model, prompt, and schedule.
+2. Save it, inspect the displayed next run, then use **Run now**.
+3. Open the resulting run-history entry and linked chat before enabling recurring use.
+
+## Verify it worked
+
+**Run now** produces a run-history entry and linked chat. Read the chat's terminal/test output to establish what a successful future run looks like.
+
+## If it did not
+
+Check the next-run value, the model connection, and the run-history error. Pause the automation while correcting its prompt or model; do not leave a failing task enabled.
+
+## Trust boundary
+
+Automations run with full tool approval/high trust because no person is present to approve tools. Never feed them untrusted input or use them for destructive actions you cannot monitor.
@@ -0,0 +1,18 @@
+---
+title: Automations and integrations
+sidebar_position: 1
+---
+
+# Automations and integrations
+
+Integrations make a real Computer workspace reachable from another product or let it act without the browser open. That is valuable only when the workspace, sender, credentials, and side effects are all deliberate. Start with a read-only proof and add one connection at a time.
+
+| What you want | Read this |
+| --- | --- |
+| Keep Open WebUI as the AI front door while work happens in a real workspace | [Use a Computer workspace from Open WebUI](./open-webui-gateway) |
+| Run a trusted recurring task in one workspace | [Schedule trusted work](./automations) |
+| Receive completion/failure results or trigger a run with a secret URL | [Notifications and webhooks](./notifications-and-webhooks) |
+| Ask a private messaging account to work in a selected workspace | [Messaging bots](./messaging-bots) |
+| Let an agent call a trusted tool server or API | [MCP tool servers](./mcp-tool-servers) and [OpenAPI tool servers](./openapi-tool-servers) |
+
+Not a fit: do not use these integrations to accept arbitrary internet requests, add a bot to a shared group, or hand a third-party service unrestricted credentials. Computer has no tenant isolation and its unattended paths run with high trust.
@@ -0,0 +1,36 @@
+---
+title: MCP tool servers
+sidebar_position: 8
+---
+
+# MCP tool servers
+
+MCP gives an agent named tools from another service. Use it when the service has a clear, narrow capability you trust the agent to call. Choose the transport carefully: a local stdio server runs a command on the Computer host; a remote server receives requests over the network.
+
+## Use this when
+
+You want a trusted agent to use an MCP server for a declared task, such as reading a private service or performing one controlled action.
+
+## Before you start
+
+- Install the MCP extra for local MCP support: `pip install 'cptr[mcp]'`.
+- For stdio, review the exact command, arguments, environment, and host account it will run under.
+- For remote MCP, review the endpoint, its data handling, and its least-privileged credential.
+
+## Do it
+
+1. In **Settings → Admin → Tool Servers**, add the stdio or remote MCP server and its authentication.
+2. Run verification and inspect the discovered tool names before enabling it in a chat.
+3. Make one read-only tool call, then consider whether write-capable tools are justified.
+
+## Verify it worked
+
+Verification lists the expected tools, and a read-only call returns the expected result in the chat tool row.
+
+## If it did not
+
+Disable the server. For stdio, correct the command, arguments, environment, working directory, or local dependency. For remote MCP, correct the endpoint/authentication and rotate the credential if it may have reached an untrusted endpoint.
+
+## Trust boundary
+
+Stdio MCP starts a local process under the Computer service account. Remote MCP sends arguments and receives results through the remote service. Both can expose workspace context or cause external effects; do not enable a server whose behavior you cannot explain.
@@ -1,60 +1,43 @@
 ---
-title: Message a workspace and add external tools
-sidebar_position: 3
+title: Messaging bots and external tools
+sidebar_position: 6
 ---

-# Message a workspace and add external tools
+# Messaging bots and 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.
+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 declared bridge to another service. They have different trust boundaries, so configure and review them separately.
+
+| Need | Read this |
+| --- | --- |
+| Message a private Computer workspace through Telegram, Discord, Slack, WhatsApp, or Signal | [Messaging bots](./messaging-bots) |
+| Run a trusted local or remote MCP server | [MCP tool servers](./mcp-tool-servers) |
+| Call a defined external HTTP API | [OpenAPI tool servers](./openapi-tool-servers) |

 ## 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.
+Use this when you are choosing the correct integration surface. Do not start with this overview when you need the actual configuration steps; use the specific guide above.

 ## 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.
+- Use only a private bot account or channel you control. Sender allowlisting is not channel allowlisting, so do not add the bot to groups, shared workspaces, or public channels.
+- For tools, obtain the command or endpoint, authentication material, and a clear description of its operations.

 ## 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.
+1. Pick the specific guide above.
+2. Complete its read-only verification before enabling a write-capable bot or tool.

 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.
+The selected guide's read-only test completes and its result appears in the intended Computer chat/tool row.

 ## 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.
+Stop the integration, correct the named command/endpoint/credential, then rerun the read-only test. If the desired boundary cannot be expressed, do not enable the integration.

 ## 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.
+Bots use full approval/high trust: an inbound message can start agent work with host tools. MCP and OpenAPI tools run with the credentials and external permissions you provide; their inputs/results can leave the host. Give each integration the least powerful credential available, and disable it when not needed.
@@ -0,0 +1,37 @@
+---
+title: Messaging bots
+sidebar_position: 7
+---
+
+# Messaging bots
+
+A messaging bot can be convenient when your phone is the only screen you have and the answer is in a trusted Computer workspace. It is not a general customer-support bot: an inbound message can start host-capable agent work.
+
+## Use this when
+
+You want to use a private Telegram, Discord, Slack, WhatsApp, or Signal account/channel to ask a narrow question about work on your own machine.
+
+## 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 only an account or channel you exclusively control. Sender allowlisting is not channel allowlisting, so do not install the bot in groups or shared channels.
+- Keep the bot out of groups, shared channels, and public communities.
+- Select a deliberate workspace and model; use a dedicated Computer account or instance when a bot must see only one project.
+
+## Do it
+
+1. In **Settings → Admin → Bots**, create the adapter configuration and verify its token.
+2. Select the workspace/model and start the bot.
+3. From the private account/channel, send a read-only test such as “Which branch is checked out?” Use `/new` for a fresh chat where supported.
+
+## Verify it worked
+
+The bot reports running, and the test creates a matching Computer chat in the intended workspace. Confirm the response identifies the expected branch or file without making a change.
+
+## If it did not
+
+Stop the bot; recheck its token/webhook configuration and the selected workspace/model. If you cannot guarantee a private sender boundary or need to confine it to one project, do not enable the bot on that instance.
+
+## Trust boundary
+
+Bots use full approval/high trust. An inbound message can invoke agent tools, and `/workspace` can select workspaces owned by that Computer user. Treat a bot token and its private platform account as access to the host, not as a harmless notification channel.
@@ -0,0 +1,35 @@
+---
+title: Notifications and webhooks
+sidebar_position: 5
+---
+
+# Notifications and webhooks
+
+Notifications tell you that a trusted chat or automation completed or failed. A webhook trigger starts a known automation. They help you leave the browser without losing awareness; they do not make unattended work safer.
+
+## Use this when
+
+You need a browser, webhook, or bot target to report a finished/failed run, or a private system to trigger an existing automation.
+
+## Before you start
+
+- Create and manually validate the automation or chat path first.
+- Use a notification endpoint you control and understand.
+
+## Do it
+
+1. In **Settings → Notifications**, create the target and select its events.
+2. Use the target's test action and confirm delivery.
+3. If an automation needs an inbound trigger, generate its webhook URL and store it as a secret in the calling system.
+
+## Verify it worked
+
+The target test arrives with the expected event. A manual automation run produces its selected completion/failure notification; an authorized webhook invocation creates only the intended automation run.
+
+## If it did not
+
+Re-test the endpoint, inspect its configured event selection, and check the destination's own delivery log. Revoke and regenerate a trigger URL that was exposed or sent to the wrong system.
+
+## Trust boundary
+
+A webhook URL is an authentication secret for running the associated high-trust automation. Do not put it in a public client, source repository, ticket, or chat transcript.
@@ -1,6 +1,6 @@
 ---
 title: Use a Computer workspace from Open WebUI
-sidebar_position: 1
+sidebar_position: 2
 ---

 # Use a Computer workspace from Open WebUI
@@ -15,7 +15,7 @@ Gateway requests run with **full tool approval**. Open WebUI cannot pause a file

 ## 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.
+Use this when you already work in Open WebUI but need an agent to inspect, edit, or run commands in a project on a 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

@@ -44,6 +44,14 @@ Elena already works in Open WebUI but needs an agent to inspect, edit, or run co

 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.

+| In a combined request | What it owns |
+| --- | --- |
+| **Open WebUI** | The caller conversation and interface. |
+| **`cptr/<workspace>`** | The selected real Computer workspace. |
+| **Open WebUI Computer** | The configured model or agent that executes the task in that workspace. |
+
+Open WebUI knowledge bases, model-agent tools, system prompts, users, and general configuration are not forwarded into Computer unless you configure equivalent capabilities in Computer.
+
 ## 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.
@@ -0,0 +1,36 @@
+---
+title: OpenAPI tool servers
+sidebar_position: 9
+---
+
+# OpenAPI tool servers
+
+An OpenAPI tool server lets an agent call operations described by an external HTTP API. This is useful for a service with a clear contract; it is not a generic way to hand an agent a broad administrative credential.
+
+## Use this when
+
+You want an agent to call a reviewed API with a documented specification and a scoped credential.
+
+## Before you start
+
+- Review the specification URL and the operations it exposes.
+- Create the least-privileged bearer credential or custom header the API supports.
+- Identify one safe read-only operation for the first test.
+
+## Do it
+
+1. In **Settings → Admin → Tool Servers**, add the OpenAPI server, specification URL, and its authentication/custom headers.
+2. Verify the server and inspect the operations Computer discovers.
+3. Enable it in one chat and request only the identified read-only operation.
+
+## Verify it worked
+
+The expected operations appear during verification and the read-only request returns the expected result without changing the external service.
+
+## If it did not
+
+Disable the server, correct the specification URL or authentication, and retest. Revoke/rotate the credential if it may have been sent to an untrusted endpoint. Do not enable write operations until the read-only path is understood.
+
+## Trust boundary
+
+OpenAPI calls leave the host with the headers and credentials you configure. An API action can mutate another system even when the Computer workspace remains unchanged.
@@ -1,17 +1,17 @@
 ---
 title: "Is Open WebUI Computer right for me?"
-sidebar_position: 2
+unlisted: true
 ---

 # 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
+## Start with no technical background

-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?**
+You may have a project folder on your laptop while words like *terminal*, *git*, *workspace*, and *agent* are new. Do not start by opening a router port, connecting a bot, or giving an AI credentials. Start with a smaller question: **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.
+The [local proof](#try-it-without-committing-to-the-whole-system) 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, ask the person who manages that computer to help with the local trial. Do 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.

@@ -25,6 +25,12 @@ Open WebUI Computer is designed for one person reaching the computer they own or

 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.

+## Self-hosted from the start
+
+Computer runs on a machine you control. Its core workspace does not require a managed cloud account, hosted control plane, or AI provider. You can start with local files, terminal, git, editor, and local apps, then add external models or integrations only when you choose to use them.
+
+External services still need their own network access. For example, a hosted model API, web search provider, Git remote, bot, or tool server can receive the data required for that feature. The point is that they are optional connections to your computer, not the place your core workspace must live.
+
 ## Use Open WebUI Computer when

 | You have this problem | What Computer changes |
@@ -45,35 +51,10 @@ That distinction matters. Computer gives an authenticated user host filesystem a
 | 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
+## Try it without committing to the whole system

-The best way to decide is to try it without changing your network or adding AI.
+Do not set up remote access, an AI provider, a bot, or an automation to answer the fit question. The first safe proof is local: open the project you already have and confirm that Computer shows its actual path, files, terminal, and git state.

-1. On the machine that already has a project you care about, install and start Open WebUI Computer:
+[Run the local trial →](./getting-started/local-trial)

-   ```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).
+Only add [private remote access](./remote-access/tailscale-and-tunnels) after that local proof is useful. An authenticated Computer user can access the host filesystem and shell, which is why it can be valuable and why it is not a sandbox.
@@ -1,6 +1,6 @@
 ---
 title: "Use Open WebUI with Open WebUI Computer"
-sidebar_position: 6
+unlisted: true
 ---

 # Use Open WebUI with Open WebUI Computer
@@ -1,8 +1,10 @@
 {
 	"label": "Operate Open WebUI Computer",
-	"position": 7,
+	"position": 9,
+	"collapsible": true,
+	"collapsed": true,
 	"link": {
-		"type": "generated-index",
-		"description": "Keep a private, persistent single-host installation healthy and recoverable."
+		"type": "doc",
+		"id": "ecosystem/computer/operate/index"
 	}
 }
@@ -7,7 +7,7 @@ sidebar_position: 2

 ## 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.
+Use this when you need to move or protect the persistent state of a private installation before an upgrade, host migration, or risky configuration change.

 ## Before you start

@@ -15,11 +15,52 @@ By default, Open WebUI Computer stores its database and configuration in `~/.cpt

 ## 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.
+Stop Open WebUI Computer cleanly. Copy the entire data directory, not only the database, to protected local or encrypted backup storage.
+
+For a Python installation, archive the default data directory while Computer is stopped:
+
+```bash
+tar -C "$HOME" -czf cptr-data-backup.tgz .cptr
+```
+
+For Docker, archive the stopped `cptr-data` volume into the current directory:
+
+```bash
+docker run --rm \
+  -v cptr-data:/data:ro \
+  -v "$PWD:/backup" \
+  alpine tar -C /data -czf /backup/cptr-data-backup.tgz .
+```
+
+Keep this state 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.
+List the backup and confirm it contains both `app.db` and `config.toml` (or the Docker volume contents):
+
+```bash
+tar -tzf cptr-data-backup.tgz | rg '(^|/)app\.db$|(^|/)config\.toml$'
+```
+
+For a restore drill, unpack a Python backup into a fresh test location and start a stopped test installation with `CPTR_DATA_DIR` pointing there:
+
+```bash
+mkdir -p /tmp/cptr-restore
+tar -C /tmp/cptr-restore -xzf cptr-data-backup.tgz
+CPTR_DATA_DIR=/tmp/cptr-restore/.cptr cptr run --port 8001
+```
+
+For Docker, restore into a new volume rather than overwriting the production volume:
+
+```bash
+docker volume create cptr-data-restore
+docker run --rm \
+  -v cptr-data-restore:/data \
+  -v "$PWD:/backup:ro" \
+  alpine tar -C /data -xzf /backup/cptr-data-backup.tgz
+```
+
+Start a test container with `cptr-data-restore`, sign in, and confirm a known workspace and setting are present. Restore workspace files separately as well; the Computer data backup does not contain the project directory.

 ## If it did not

@@ -21,15 +21,15 @@ Check the instance:
 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.
+Set `CPTR_LOG_LEVEL=DEBUG` for more server detail or `CPTR_LOG_FORMAT=json` for structured stdout, then restart. Set `CPTR_AUDIT_LOG_LEVEL=METADATA` for a low-content mutation trail. `REQUEST` adds redacted request bodies and `REQUEST_RESPONSE` adds redacted response bodies; the default audit file is `~/.cptr/logs/audit.jsonl`, and `CPTR_AUDIT_LOG_PATH` changes it. 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.
+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. After a harmless mutation, the selected audit file contains a redacted JSON entry. 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.
+If health fails locally, inspect the server's stdout and verify the chosen port. If the audit file is absent, restart and confirm its selected level and parent directory are writable. 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

@@ -1,62 +1,20 @@
 ---
-title: "Who Open WebUI Computer is for"
-sidebar_position: 4
+title: "Find your path"
+unlisted: true
 ---

-# Who Open WebUI Computer is for
+# Find your path

-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.
+Choose a guide from the work you need to do now. You do not need to understand every feature before starting.

-## Avery: start without knowing the jargon
+| Your situation | Start here |
+| --- | --- |
+| You have an existing project but do not know terminal, git, SSH, or agent vocabulary. | [Is Open WebUI Computer right for me?](./is-it-right) |
+| You design or review a live prototype and need to see it on a real device. | [Preview a local app on another device](./use-cases/real-device-preview) |
+| The useful branch, log, or running terminal is on a machine you left behind. | [Fix something away from your desk](./use-cases/remote-fix) |
+| A coding agent is working in a repository and needs supervision. | [Supervise an agent from anywhere](./use-cases/agent-supervision) |
+| You want a repeatable private check to report back when it finishes. | [Schedule trusted work](./integrations/automations-and-notifications) |
+| You use Open WebUI and want it to direct work in a real workspace. | [Connect Open WebUI to a Computer workspace](./integrations/open-webui-gateway) |
+| You already understand private infrastructure and want to add capabilities carefully. | [Explore integrations](./integrations/messaging-and-tools) |

-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.
+Start locally and add only the next capability you can explain and verify. If you do not control the host machine, need a disposable environment, or need safely isolated access for untrusted people, [read the fit guide](./is-it-right) before continuing.
@@ -1,10 +1,10 @@
 {
 	"label": "Reference",
-	"position": 22,
+	"position": 11,
 	"collapsible": true,
 	"collapsed": true,
 	"link": {
-		"type": "generated-index",
-		"description": "Commands, storage, permissions, compatibility, and the OpenAI-compatible gateway."
+		"type": "doc",
+		"id": "ecosystem/computer/reference/index"
 	}
 }
@@ -19,7 +19,7 @@ Native profiles run through their installed host command. Other terminal agents

 ## Use this when

-Jules sees an empty model list, a “not found” status, or needs to decide whether a normal terminal workflow is sufficient.
+Use this reference when you see an empty model list, a “not found” status, or need to decide whether a normal terminal workflow is sufficient.

 ## Before you start

@@ -9,7 +9,7 @@ The product is named **Open WebUI Computer**; `cptr` is the package and command

 ## 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.
+Use this reference when installing or operating Computer on a workstation or private server and you need to know which command starts it, where its state lives, and what to preserve during an upgrade.

 ## Before you start

@@ -13,7 +13,7 @@ Gateway-created tasks use `tool_approval_mode: full`. There is no per-tool appro

 ## Use this when

-Elena is connecting a trusted OpenAI-compatible client and needs the exact endpoints, authentication, and conversation-continuity semantics.
+Use this reference when connecting a trusted OpenAI-compatible client and you need the exact endpoints, authentication, and conversation-continuity semantics.

 ## Before you start

@@ -0,0 +1,17 @@
+---
+title: Open WebUI Computer reference
+sidebar_position: 1
+---
+
+# Reference
+
+Use these pages when you already know the workflow you want and need exact operating facts: command names, state locations, security boundaries, compatibility, and API behavior.
+
+| Need | Read this |
+| --- | --- |
+| Install, run, or preserve Computer state | [CLI, installation options, and stored state](./cli-and-storage) |
+| Decide whether a deployment or permission model is safe | [Security, permissions, and configuration](./security-and-configuration) |
+| Diagnose a native-agent model/profile | [Agent and feature compatibility](./agent-compatibility) |
+| Connect an OpenAI-compatible client programmatically | [OpenAI-compatible gateway API](./gateway-api) |
+
+If you are new to Computer, begin with [Get started](/ecosystem/computer/getting-started) instead of treating reference commands as a deployment recipe.
@@ -9,7 +9,7 @@ Open WebUI Computer is a private window into a real host. That is why it is usef

 ## 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.
+Use this reference when 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

@@ -1,8 +1,10 @@
 {
 	"label": "Remote access and security",
-	"position": 5,
+	"position": 7,
+	"collapsible": true,
+	"collapsed": true,
 	"link": {
-		"type": "generated-index",
-		"description": "Reach your own machine deliberately, with the same caution you would apply to SSH."
+		"type": "doc",
+		"id": "ecosystem/computer/remote-access/index"
 	}
 }
@@ -1,35 +1,29 @@
 ---
-title: Authentication and audit logging
+title: Authentication and audit boundaries
 sidebar_position: 5
 ---

-# Authentication and audit logging
+# Authentication and audit boundaries

 ## 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.
+You operate a personal instance and need to confirm who can sign in, what a `401` means, and what audit logging can and cannot prove.

 ## 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.
+The default password sign-in establishes JWT sessions. Audit logging is off by default and records mutating HTTP requests, not a full terminal transcript or a complete record of terminal activity.

 ## 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.
+Use a strong, unique password for the first account and keep sign-up disabled unless you have a deliberate trusted-user workflow. Keep the service on localhost or a private network. If you need audit records, configure the level, path, retention, and protected storage through [logs, health, and configuration](/ecosystem/computer/operate/logs-health-and-configuration).

 ## 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.
+An unsigned-in browser receives `401` for protected API routes, while the intended account can sign in and reach only the instance you operate. If audit logging is enabled, make a harmless mutation and confirm a redacted entry appears using the [operations guide](/ecosystem/computer/operate/logs-health-and-configuration).

 ## 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.
+A `401` means sign in again or inspect the configured auth mode; do not bypass it with proxy headers. If audit records are absent, follow the operations guide to verify the selected level, writable storage path, and restart requirement. If access works for an unintended network or user, stop the service, return it to localhost-only access, rotate affected credentials, and inspect the available audit records.

 ## Trust boundary

@@ -7,7 +7,7 @@ sidebar_position: 3

 ## 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.
+Use this when you are at home with a phone or tablet and need the local app and terminal running on the host, or are testing access before setting up a private remote network.

 ## Before you start

@@ -23,7 +23,7 @@ From an untrusted network or unsigned-in browser, protected API calls return `40

 ## 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.
+If access works from a network or user you did not intend, stop the service or return it to `127.0.0.1`, preserve [audit logs](./authentication-and-audit), and rotate credentials. Changing a password does not invalidate an existing browser JWT by itself. To sign every browser session out, replace the `[server]` `secret` in `~/.cptr/config.toml` with a new random value, restart Computer, then reset passwords and rotate gateway keys, bot tokens, and external credentials that may be affected. Do not solve an exposure problem by adding more application users.

 ## Trust boundary

@@ -7,7 +7,7 @@ sidebar_position: 4

 ## Use this when

-Nora needs the real branch and terminal from a phone outside her home network, without opening a public router port.
+Use this when you need the real branch and terminal from a phone outside the home network, without opening a public router port.

 ## Before you start

@@ -1,8 +1,10 @@
 {
 	"label": "Troubleshooting",
 	"position": 10,
+	"collapsible": true,
+	"collapsed": true,
 	"link": {
-		"type": "generated-index",
-		"description": "Diagnose the host, network, state, and access paths without guessing."
+		"type": "doc",
+		"id": "ecosystem/computer/troubleshooting/index"
 	}
 }
@@ -15,7 +15,9 @@ Decide whether the failure is local, LAN, or private-remote. `localhost` on a ph

 ## 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.
+On the host, run `curl http://127.0.0.1:8000/api/health`. For private remote use, keep the existing localhost-bound server running and follow [Tailscale or tunnels](/ecosystem/computer/remote-access/tailscale-and-tunnels).
+
+For intentional LAN-only testing, stop the existing server first, restart it with `cptr run --host 0.0.0.0`, and use the host's private IP from the second device. Verify the host firewall limits the port to the intended private subnet, then restore the default localhost binding when the test is complete.

 ## Verify it worked

@@ -23,7 +25,7 @@ The second device signs in and sees the same workspace path. `pwd` and `git stat

 ## 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.
+If health fails on the host, return to [install and login](./install-and-login). If it works locally but not through Tailscale Serve, inspect `tailscale serve status` and the tailnet policy before changing the Computer bind address. If intentional LAN testing fails, 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

@@ -1,11 +1,6 @@
 {
 	"label": "Use cases",
-	"position": 10,
+	"position": 4,
 	"collapsible": true,
-	"collapsed": true,
-	"link": {
-		"type": "generated-index",
-		"title": "Use cases",
-		"description": "Start with the job you need to finish on your real machine."
-	}
+	"collapsed": false
 }
@@ -1,13 +1,13 @@
 ---
 title: "Supervise a coding agent away from your desk"
-sidebar_position: 2
+sidebar_position: 4
 ---

 # 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.
+An agent is already running a task in the actual repository. While away from the host, it reaches a migration or design decision. You need 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.
+This is valuable because the agent works where the code already lives, while you stay in control. A **coding agent** is an AI program that can inspect files and run development commands; Open WebUI Computer gives you one place to see what it did, ask it a question, and review the resulting changed lines before accepting more work. You do not need to recreate the repository or blindly trust a chat transcript.

 ## Use this when

@@ -18,20 +18,20 @@ Use this when a coding agent is already working in a workspace you trust and a h
 - **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.
+- Ensure you can reach the host privately from a 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.
+3. Approve only the action you understand and want. If you need 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.
+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 you authorize a broader change.

 ## If it did not

@@ -42,4 +42,4 @@ The chat shows the agent's continuing tool activity in the existing workspace, n

 ## 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.
+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. You remain responsible for approvals, credentials available to the host, and every command or diff you accept.
@@ -0,0 +1,27 @@
+---
+title: "Use Open WebUI Computer for a real job"
+sidebar_position: 1
+---
+
+# Use Open WebUI Computer for a real job
+
+Open WebUI Computer is useful when the context that matters is already on one machine: a branch with uncommitted changes, a terminal that is still running, a local app, an authenticated browser session, or an AI task already in progress. It gives another device a view of that same state. It does not require a re-clone, a second setup, or a long explanation pasted into a generic chat.
+
+Start locally first, then add private remote access after the local proof works. Choose the job in front of you, not a feature name.
+
+| I need to… | Start here | The proof of value |
+| --- | --- | --- |
+| Check a real branch, log, or small correction away from my desk | [Fix an issue from another device](./remote-fix) | The branch, diff, and terminal match the host. |
+| Pick up exactly where I left off on another screen | [Resume a workspace from another device](./resume-workspace) | Existing files, tabs, and terminal output return. |
+| Review and steer an AI coding task | [Supervise a coding agent](./agent-supervision) | Agent activity and the real diff are visible together. |
+| Test the app already running on my machine from a phone or tablet | [Test a local app on a real device](./real-device-preview) | The preview is served by the existing local process. |
+| Turn a design review into a project artifact | [Review a prototype and capture feedback](./review-and-share-feedback) | The note, file, or link lands in the intended workspace. |
+| Investigate a failed build or service alert while away | [Triage an on-call interruption](./on-call-triage) | Logs, process state, and git state come from the host. |
+| Run a known recurring check and know whether it finished | [Run recurring checks](./recurring-checks) | A manual run creates a linked result before the schedule is trusted. |
+| Use Open WebUI while work happens in one repository | [Use Open WebUI with a real workspace](./open-webui-workspace) | Computer shows the workspace activity behind the answer. |
+
+If Open WebUI Computer is not installed yet, complete the [local trial](/ecosystem/computer/getting-started/local-trial). If a second device cannot reach the host yet, complete [remote access](/ecosystem/computer/remote-access) before following a remote scenario.
+
+## What these workflows are not
+
+They are not a reason to publish a shell to the internet, give untrusted people a login, or skip normal review for high-impact work. The advantage is continuity with a machine you own and already understand. Keep the instance private, keep the task narrow, and verify the real state before acting.
@@ -0,0 +1,39 @@
+---
+title: "Triage an on-call interruption"
+sidebar_position: 7
+---
+
+# Triage an on-call interruption
+
+Use this when a build fails, a deployment looks wrong, or a small service alert arrives while you are away from the machine that has the logs, checkout, and tools. Open WebUI Computer is more useful than a generic chat because you can inspect the real process and repository; it is less disruptive than rebuilding the environment somewhere else just to answer one question.
+
+## Use this when
+
+You need to determine what happened, collect enough evidence for the next action, or make a narrow, tested correction. It is not a substitute for a production runbook, incident process, or desktop review when the blast radius is high.
+
+## Before you start
+
+- Before an incident, complete the [local trial](/ecosystem/computer/getting-started/local-trial), [first workspace](/ecosystem/computer/getting-started/first-workspace), and [private remote access](/ecosystem/computer/remote-access/tailscale-and-tunnels).
+- Know the service’s normal status command, log location, focused test, or safe read-only diagnostic.
+- Decide which actions require a full workstation or another reviewer before the alert arrives.
+
+## Do it
+
+1. Open the intended workspace and terminal from the remote device.
+2. Confirm the active path and branch with `pwd` and `git status`, then inspect recent logs or the smallest safe diagnostic.
+3. Compare the observed failure with the current diff and running process. Record the exact error in the workspace chat or note if another person will continue the investigation.
+4. Make a narrow correction only when you can run its focused verification; otherwise leave the state and evidence ready for a reviewed handoff.
+
+## Verify it worked
+
+The terminal output, git state, and local process all come from the expected host workspace. You can state whether the failure reproduced, what command showed it, and whether the focused verification passed after any correction.
+
+## If it did not
+
+- If the host is unreachable, do not improvise public access. Use the established private route or escalate through the normal incident path.
+- If logs or the branch do not match expectations, stop and confirm the workspace path before acting.
+- If the needed action is destructive or unclear, preserve the evidence and hand it off rather than making a speculative fix.
+
+## Trust boundary
+
+Computer provides access to the real host, not a safe simulation. An on-call login can read files and run shell commands with the host account’s permissions. Keep access private and use least-risk diagnostics first.
@@ -0,0 +1,39 @@
+---
+title: "Use Open WebUI with a real workspace"
+sidebar_position: 9
+---
+
+# Use Open WebUI with a real workspace
+
+Use this when Open WebUI is where you choose models and organize AI conversations, but the actual work must happen in one machine’s repository, files, terminal, or authenticated local tools. The combined workflow avoids pretending that a generic chat already has your local environment; Open WebUI Computer supplies that real workspace behind the request.
+
+## Use this when
+
+You want Open WebUI as the AI front door and Open WebUI Computer as the place the agent performs work. Use Open WebUI alone for knowledge and chat that do not need a particular machine. Use Computer alone when you mainly need files, terminal, or git without an external AI front door.
+
+## Before you start
+
+- Complete the [local trial](/ecosystem/computer/getting-started/local-trial) and [first workspace](/ecosystem/computer/getting-started/first-workspace), then run both services where Open WebUI can reach Computer’s gateway over a private, trusted network.
+- Create the target workspace and configure its default agent or model in Computer.
+- Create a gateway key and follow the [combined setup guide](/ecosystem/computer/integrations/open-webui-gateway) for the exact connection and continuity headers.
+
+## Do it
+
+1. Add the Computer gateway as an OpenAI API connection in Open WebUI using the documented `/v1` base URL and gateway credential.
+2. Add the documented continuity headers, save the connection, and select the workspace model shown as `cptr/<workspace>`.
+3. Ask a small read-only question about a known file in that workspace.
+4. Open Computer and inspect the workspace chat and activity produced by the request before trying a task that edits files or runs commands.
+
+## Verify it worked
+
+The workspace appears in Open WebUI’s model picker, its answer refers to real workspace state, and the corresponding activity is visible in the selected Computer workspace. A follow-up continues the intended Computer conversation when the documented headers are configured.
+
+## If it did not
+
+- Call `GET /v1/models` with the same credential to separate a connection/authentication problem from model selection.
+- Recheck the base URL, gateway key, user access, and workspace availability.
+- If normal messages work but continuity does not, recopy the headers from the gateway setup page rather than creating an ad hoc integration.
+
+## Trust boundary
+
+The gateway credential authorizes shell-capable agent work in the owning user’s Computer workspaces. It does not synchronize users, chats, knowledge bases, or configuration between the products, and it is not an isolation boundary.
@@ -1,13 +1,13 @@
 ---
-title: "Preview your local app on a real device"
-sidebar_position: 3
+title: "Test a local app on a real device"
+sidebar_position: 5
 ---

-# Preview your local app on a real device
+# Test a 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.
+Your machine is already running a local app server. You need to verify a touch interaction on a phone or tablet 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.
+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 your machine. Open WebUI Computer lets you open that same running app from another device, while keeping the source files and terminal logs from the original machine close by.

 ## Use this when

@@ -17,7 +17,7 @@ Use this when a process in a workspace has opened a local port and you want to v

 - **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.
+- You 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
@@ -31,7 +31,7 @@ For the underlying terminal behavior, see [Persistent terminals](/ecosystem/comp

 ## 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.
+The file browser lists the running port, the preview opens content served by the existing process, and the terminal continues to show the same process output. Close and reopen the browser session: the process is still running unless you deliberately stopped it or the host changed state.

 ## If it did not

@@ -0,0 +1,39 @@
+---
+title: "Run recurring checks with a real workspace"
+sidebar_position: 8
+---
+
+# Run recurring checks with a real workspace
+
+Use this when a repeated check belongs beside the repository and tools that actually perform it: a test suite, build report, or known maintenance task. Open WebUI Computer runs the work in the chosen workspace instead of a generic chat with no local context or a separate automation environment that must be kept in sync.
+
+## Use this when
+
+You want a narrow, reviewed prompt to run on a schedule and alert you about completion or failure. Start with a task that is safe to repeat and has an observable outcome.
+
+## Before you start
+
+- Complete the [local trial](/ecosystem/computer/getting-started/local-trial) and [first workspace](/ecosystem/computer/getting-started/first-workspace), then confirm the task works manually in the selected workspace.
+- Choose a stable workspace, model, short prompt, and notification target.
+- Treat automations as high-trust: they can use tools without someone present to approve every action.
+
+## Do it
+
+1. Open **Automations**, create the task, choose its workspace and model, write the constrained prompt, and set a schedule.
+2. Save it and use **Run now** before trusting the schedule.
+3. Configure a browser, webhook, or bot notification target and use its test action.
+4. Review run history before widening the prompt, changing the model, or allowing it to perform a more consequential task.
+
+## Verify it worked
+
+**Run now** creates a run-history entry with a linked workspace chat or result. The notification test succeeds, and a completed or failed run produces the selected notification. Only then is the schedule worth relying on.
+
+## If it did not
+
+- Check the next-run value, selected workspace, model availability, and error shown in run history.
+- Re-test the notification target and confirm the device/browser permits notifications.
+- If a webhook trigger fails, regenerate its secret URL instead of weakening its authentication.
+
+## Trust boundary
+
+An automation runs without interactive per-tool approval. Give it only a stable workspace, reviewed prompt, trusted model, and narrowly scoped notification endpoint. Do not feed it untrusted input or use it for destructive deployment work.
@@ -1,11 +1,11 @@
 ---
-title: "Fix a production issue from your phone"
-sidebar_position: 1
+title: "Fix an issue from another device"
+sidebar_position: 2
 ---

-# Fix a production issue from your phone
+# Fix an issue from another device

-**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.
+The branch, local database, and terminal that reproduced an issue are on a machine at home. A report arrives while you only have a phone. You need to inspect the real branch and make a small, reviewable correction, not rebuild the 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.

@@ -16,23 +16,23 @@ The repository, local service, credentials, or uncommitted work you need already
 ## 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.
+- Open WebUI Computer is already running on the host and reachable over a private network path. It must not be exposed as a public service.
+- The intended workspace is added, and you can sign in from the phone.
+- You know the affected file or have a reproducible command. If the issue could damage data, start with a read-only check and leave 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.
+1. From the phone, sign in and open the intended workspace. The file browser, git bar, and terminal are the same host workspace you 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.
+3. Open a terminal and run the smallest read-only diagnostic that confirms the report, such as a focused test or log query.
 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.
+5. Run the focused test again. If it passes, stage and commit only the intended files, or leave the diff ready 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.
+The phone shows the same active branch and pre-existing terminal output as the host. The git panel shows only the 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

@@ -43,4 +43,4 @@ The phone shows the same active branch and pre-existing terminal output as the i

 ## 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.
+Signing in gives you the host-level file and shell access that makes this useful. Treat the instance like private SSH: one trusted user on a network you control. 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.
@@ -0,0 +1,39 @@
+---
+title: "Resume a workspace from another device"
+sidebar_position: 3
+---
+
+# Resume a workspace from another device
+
+Use this when the value is continuity, not another AI answer. You already have a project open, files under review, a running command, or a chat with useful decisions. Open WebUI Computer lets you return to that machine state from a phone, tablet, or laptop instead of rebuilding it in a fresh editor, shell, or cloud copy.
+
+## Use this when
+
+You need to check progress, continue a small task, or return to the exact workspace after changing devices. It is useful for a long-running build, local service, or repository with work that has not been committed yet.
+
+## Before you start
+
+- Complete the [local trial](/ecosystem/computer/getting-started/local-trial), add the workspace, and configure [private remote access](/ecosystem/computer/remote-access).
+- Leave the host powered and awake. Reopening a browser can recover the workspace view, but it cannot revive a process after the host sleeps, shuts down, or restarts.
+- Use a workspace path that identifies the actual checkout, not a broad parent directory.
+
+## Do it
+
+1. Sign in from the second device and choose the workspace by its name and path.
+2. Open the files, chat, terminal, or git view that matter for the task.
+3. Run `pwd`, `git status`, or another harmless command to confirm that the terminal is in the expected project.
+4. Continue only the next useful action: inspect output, send a short follow-up, or make a small edit.
+
+## Verify it worked
+
+The workspace shows the same project path, branch, files, and prior terminal output that were present on the host. Closing the second-device browser and reopening it returns to the same host workspace instead of a blank environment.
+
+## If it did not
+
+- If the workspace is absent, add the real host path through the workspace picker; do not copy the repository into application storage.
+- If a process stopped, inspect its final terminal output and host state, then restart it deliberately.
+- If the view is unfamiliar, verify the workspace path and chat history before sending instructions or changing files.
+
+## Trust boundary
+
+Cross-device continuity does not create isolation. The remote browser is another way into the same host account, files, and terminal. Keep the machine and access path private.
@@ -0,0 +1,39 @@
+---
+title: "Review a prototype and capture feedback"
+sidebar_position: 6
+---
+
+# Review a prototype and capture feedback
+
+Use this when a live local prototype needs feedback from the device in your hand, and that feedback belongs with the project rather than in a disconnected message thread. Open WebUI Computer keeps the preview, source files, terminal logs, and a workspace chat or note in one place. A generic chat cannot see the running prototype; a cloud copy may not reproduce it.
+
+## Use this when
+
+You are reviewing a private local app, checking a design on a real phone or tablet, or saving a link, file, or observation into the workspace that owns the work. This is for a trusted personal workflow, not public review collection.
+
+## Before you start
+
+- Complete the [local trial](/ecosystem/computer/getting-started/local-trial) and [first workspace](/ecosystem/computer/getting-started/first-workspace), then start the app and confirm its port using [the real-device preview guide](./real-device-preview).
+- Confirm the workspace is the one where review notes or shared files should live.
+- If sharing from a phone, check the browser and operating system support the PWA share flow; use a normal chat or note manually if it does not.
+
+## Do it
+
+1. Open the local-port preview on the review device and reproduce the interaction you want to assess.
+2. Capture a concise observation in the workspace chat or create a note file that names the page, device, and expected behavior.
+3. If your installed app supports it, use the device Share action to send a link, text, or file to Open WebUI Computer, then confirm its destination before saving it.
+4. Open the resulting workspace item beside the source file or terminal output so the feedback has immediate technical context.
+
+## Verify it worked
+
+The preview is served by the existing host process, and the observation, shared item, or note appears in the intended workspace. Reopening the workspace shows the feedback beside the project rather than only in a separate phone app.
+
+## If it did not
+
+- If the preview does not load, return to the terminal and confirm the process and port before changing the app.
+- If sharing is unsupported or unavailable, copy the link or write the observation in a workspace chat or note instead.
+- If an item lands in the wrong folder, move it only after confirming its source and update PWA import preferences before trying again.
+
+## Trust boundary
+
+Shared files, links, and notes become real workspace data. A preview may expose what the local service serves to anyone who can sign in to this trusted instance. Keep both the review group and the instance private.
@@ -1,11 +1,10 @@
 {
 	"label": "Your workspace",
-	"position": 20,
+	"position": 5,
 	"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."
+		"type": "doc",
+		"id": "ecosystem/computer/workspace/index"
 	}
 }
@@ -5,7 +5,7 @@ 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.
+Open WebUI Computer can show a local service that is already running on the host through a workspace preview tab. This lets you check an app from a phone or tablet while keeping the original terminal, logs, and source files in reach.

 ## Use this when

@@ -5,7 +5,7 @@ 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.
+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

@@ -5,7 +5,7 @@ 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?
+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

@@ -0,0 +1,28 @@
+---
+title: "Your workspace"
+sidebar_position: 1
+---
+
+# Your workspace
+
+This is the part that makes Open WebUI Computer more than a chat window. A workspace is an existing folder on your machine, with its files, terminal, git state, local services, chats, and remembered layout kept together.
+
+## Start with the thing you need to see
+
+| Need | Guide |
+| --- | --- |
+| Confirm you opened the real project, not a copy | [Workspace paths](./workspace-paths) |
+| Read, edit, or preview files | [Files and editor](./files-editor) |
+| Resume a command or start a local service | [Terminals](./terminals) |
+| Review a branch or diff | [Git](./git) |
+| Open a running local app from another device | [Browser and port preview](./browser-port-preview) |
+| Find an earlier chat, message, or file | [Search and chats](./search-chats) |
+| Make the workspace easy to reach from a phone | [PWA, sharing, and shortcuts](./pwa-share-shortcuts) |
+
+## Verify it worked
+
+Open one existing workspace and confirm that its path, files, and git state match the host. Then create a terminal tab and run a harmless command such as `pwd`. If any of those show a different project, stop and use [workspace paths](./workspace-paths) before editing.
+
+## Trust boundary
+
+Workspace selection organizes your work. It does not sandbox the host or turn the directory into a separate machine. Read [the security model](/ecosystem/computer/remote-access/security-model) before sharing access.
@@ -5,7 +5,7 @@ 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.
+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

@@ -5,7 +5,7 @@ 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.
+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

@@ -5,7 +5,7 @@ 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.
+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

@@ -20,7 +20,7 @@ Run a focused test, inspect logs, start a local development server, or resume a
 ## 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.
+2. Run the narrow diagnostic or task. For a local 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.

@@ -5,7 +5,7 @@ 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.
+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

@@ -13,7 +13,7 @@ Add a repository or project directory, switch between existing projects, or veri

 ## 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.
+- Know the absolute path on the host, for example `/Users/you/src/project`, 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.