Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs: four sections and fewer, plainer pages (CUA-1863) (#5470)

Francesco Bonacci45898732fce2
diff --git a/.github/actions/cua-sandbox/lint-docs-yaml.py b/.github/actions/cua-sandbox/lint-docs-yaml.py
index ad82171058..5f3e502c02 100644
--- a/.github/actions/cua-sandbox/lint-docs-yaml.py
+++ b/.github/actions/cua-sandbox/lint-docs-yaml.py
@@ -22,8 +22,7 @@ from pathlib import Path
REPO = Path(__file__).resolve().parents[3]
PAGES = [
"docs/content/docs/cua-sdk/guides/test-in-ci.mdx",
- "docs/content/docs/cua-driver/guides/test-in-a-sandbox.mdx",
- "docs/content/docs/start-here/run-in-github-actions.mdx",
+ "docs/content/docs/cua-driver/guides/vms-and-remote.mdx",
]
FENCE = re.compile(r"^```yaml[^\n]*\n(.*?)^```", re.M | re.S)
REMOTE = re.compile(r"trycua/cua/\.github/actions/cua-sandbox@\S+")
diff --git a/.github/workflows/ci-check-docs.yml b/.github/workflows/ci-check-docs.yml
index 2a00b84196..5f039cf941 100644
--- a/.github/workflows/ci-check-docs.yml
+++ b/.github/workflows/ci-check-docs.yml
@@ -29,7 +29,7 @@ on:
- "libs/images/sandbox-images.json"
- "libs/images/bench/*/lock.json"
- "docs/content/docs/cua-sdk/quickstart.mdx"
- - "docs/content/docs/start-here/sandbox-images.mdx"
+ - "docs/content/docs/cua-sdk/guides/images.mdx"
- ".github/workflows/ci-check-docs.yml"
- ".gitattributes"
# Run every native check on demand, e.g. to produce the native Windows Driver
diff --git a/.github/workflows/ci-cua-contrib.yml b/.github/workflows/ci-cua-contrib.yml
index c9cd26fb62..8c1fd66545 100644
--- a/.github/workflows/ci-cua-contrib.yml
+++ b/.github/workflows/ci-cua-contrib.yml
@@ -24,7 +24,7 @@ on:
- "libs/cua/crates/cua-cli/**"
- "libs/python/cua-sandbox/**"
- "libs/cua-bench/cua_bench/**"
- - "docs/content/docs/cua-sdk/guides/contrib-providers.mdx"
+ - "docs/content/docs/cua-sdk/guides/local-runtimes.mdx"
- ".github/actions/cua-sandbox/**"
- "tests/e2e/cua-sdk/python/test_docs_blocks.py"
- ".github/workflows/ci-cua-contrib.yml"
diff --git a/.github/workflows/ci-cua-sandbox-action.yml b/.github/workflows/ci-cua-sandbox-action.yml
index f1f5c43d81..c4e5973a7a 100644
--- a/.github/workflows/ci-cua-sandbox-action.yml
+++ b/.github/workflows/ci-cua-sandbox-action.yml
@@ -10,8 +10,7 @@ on:
paths:
- ".github/actions/cua-sandbox/**"
- "docs/content/docs/cua-sdk/guides/test-in-ci.mdx"
- - "docs/content/docs/cua-driver/guides/test-in-a-sandbox.mdx"
- - "docs/content/docs/start-here/run-in-github-actions.mdx"
+ - "docs/content/docs/cua-driver/guides/vms-and-remote.mdx"
- ".github/workflows/ci-cua-sandbox-action.yml"
workflow_dispatch:
diff --git a/.github/workflows/nightly-contrib-doctor.yml b/.github/workflows/nightly-contrib-doctor.yml
index 9418366141..0580b22910 100644
--- a/.github/workflows/nightly-contrib-doctor.yml
+++ b/.github/workflows/nightly-contrib-doctor.yml
@@ -173,7 +173,7 @@ jobs:
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git checkout -B "$branch"
- git add libs/cua/crates/cua-contrib/matrix/ledger docs/content/docs/cua-sdk/guides/contrib-providers.mdx
+ git add libs/cua/crates/cua-contrib/matrix/ledger docs/content/docs/cua-sdk/guides/local-runtimes.mdx
git commit -m "docs(cua-contrib): measured support matrix from the nightly doctor lanes"
git push --force origin "$branch"
gh pr view "$branch" >/dev/null 2>&1 || gh pr create --head "$branch" \
diff --git a/README.md b/README.md
index 52ce51a6eb..89045581a4 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,7 @@ Bring your own agent and model, or explore CUA-S1 for specialized decisions. Cua
## Cua Spaces
-Cua Spaces is a desktop app that gives your agents full desktops. Each desktop is a Space: a macOS VM built locally on your Mac, or a Linux or Omarchy image. Spaces run on your Mac, on other machines you own, and in [your own cloud account](https://cua.ai/docs/cua-sdk/guides/your-cloud) (AWS, Google Cloud or Modal), and the app keeps them in your menu bar and notch.
+Cua Spaces is a desktop app that gives your agents full desktops. Each desktop is a Space: a macOS VM built locally on your Mac, or a Linux or Omarchy image. Spaces run on your Mac, on other machines you own, and in [your own cloud account](https://cua.ai/docs/cua-sdk/guides/local-runtimes#your-own-cloud) (AWS, Google Cloud or Modal), and the app keeps them in your menu bar and notch.
- **Teleport.** Move a signed-in app, such as Chrome or Slack, into a Space and it opens there still signed in. Your sessions stay in the Cua Keyvault, encrypted on your Mac, and reach a Space only after you approve.
- **Multiplayer.** You and your agents work on the same desktop, each with your own cursor. Step in to make a choice, then hand the desktop back.
@@ -84,7 +84,7 @@ On macOS the installer selects the Cua Spaces app by default and adds the `cua`
Spaces is free for individuals. Pro is $18 a month and Teams is $30 per seat a month, available now from 1 seat. See [pricing](https://cua.ai/pricing). The app is source-available under [FSL-1.1-MIT](#licensing).
-**[Quickstart](https://cua.ai/docs/spaces/quickstart)** | **[Teleport an app](https://cua.ai/docs/spaces/guides/teleport-an-app)** | **[Share a Space](https://cua.ai/docs/spaces/guides/share-a-space)** | **[Host Spaces on a spare Mac (relay, Tailscale or SSH)](https://cua.ai/docs/spaces/guides/host-spaces-on-your-spare-mac)** | **[Your own cloud](https://cua.ai/docs/cua-sdk/guides/your-cloud)** | **[App source](apps/cua-spaces-macos/README.md)**
+**[Quickstart](https://cua.ai/docs/spaces/quickstart)** | **[Teleport an app](https://cua.ai/docs/spaces/guides/teleport-an-app)** | **[Share a Space](https://cua.ai/docs/spaces/guides/share-a-space)** | **[Host Spaces on a spare Mac (relay, Tailscale or SSH)](https://cua.ai/docs/spaces/guides/add-a-computer#use-a-spare-mac-to-host-spaces)** | **[Your own cloud](https://cua.ai/docs/cua-sdk/guides/local-runtimes#your-own-cloud)** | **[App source](apps/cua-spaces-macos/README.md)**
---
@@ -224,7 +224,7 @@ uv tool run --from 'cua-bench[browser]' playwright install chromium
### Deprecated packages
-Cua no longer maintains these. They will not receive updates or fixes, and existing releases stay on npm and PyPI. See [Migrate from deprecated packages](https://cua.ai/docs/cua-sdk/guides/migrate-from-deprecated-packages).
+Cua no longer maintains these. They will not receive updates or fixes, and existing releases stay on npm and PyPI. See [Migrate from deprecated packages](https://cua.ai/docs/cua-sdk/guides/cua-cloud-ended#deprecated-packages).
| Package | Registry | Use instead |
| -------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
diff --git a/docs/2026-10-18-docs-simplify-map.md b/docs/2026-10-18-docs-simplify-map.md
new file mode 100644
index 0000000000..74123e4740
--- /dev/null
+++ b/docs/2026-10-18-docs-simplify-map.md
@@ -0,0 +1,234 @@
+# Docs simplification page map (18 Oct 2026, CUA-1863)
+
+Approved by Francesco on 18 Oct 2026. Data: cua.ai/docs page views over the last 30 days (PostHog), counted after following existing redirects.
+
+## Page counts
+
+| Section | Before | After |
+| --- | --- | --- |
+| Cua Spaces | 46 | 23 (20 guides and pages, 3 reference) |
+| Cua Driver | 45 | 22 (13 guides and pages, 9 reference) |
+| Cua CLI | 40 | 13 (4 guides and pages, 9 reference) |
+| Cua SDK | 136 | 56 (17 guides and pages, 39 reference; 53 once the Fleet removal PRs delete the 3 Fleet pages) |
+| Lume | 17 | 9 |
+| Cua Bench | 17 | 8 |
+| Start here | 5 | 0 (merged into the products) |
+| Home and Docs for agents | 2 | 2 |
+| Total | 308 | 133 |
+
+The gap to about 80 is the SDK reference: each method shows its signature in five languages, so the page budget (30 tab blocks, 150 code blocks) stops further merging. Next step: render signatures more compactly, then merge to one page per module.
+
+## Sections
+
+1. Cua Spaces: quickstart, task guides (install, connect your agent, create a Space, add a computer, plans and Teams, share, stream, teleport, Cua Volume, Keyvault, persistent agents, use Spaces from code, troubleshoot, uninstall), Advanced (what the relay can see), How Spaces works.
+2. Cua Driver: quickstart, guides, tool reference.
+3. Reference: Cua CLI (one page per command group), Cua SDK.
+4. More tools: Lume, Cua Bench.
+
+## Hand-written pages merged or removed (PR 1)
+
+| Old path | New path | Views (30 days) |
+| --- | --- | --- |
+| `/docs/start-here` | `/docs/spaces/quickstart` | |
+| `/docs/start-here/drive-your-first-app` | `/docs/cua-driver/quickstart` | 1205 |
+| `/docs/start-here/sandbox-images` | `/docs/cua-sdk/guides/images#every-published-image` | 45 |
+| `/docs/start-here/run-in-github-actions` | `/docs/cua-sdk/guides/test-in-ci` | 9 |
+| `/docs/start-here/create-a-local-macos-sandbox` | `/docs/cua-cli/quickstart#macos-sandbox` | 375 |
+| `/docs/start-here/your-first-cua-bench-task` | `/docs/cua-bench/quickstart#create-your-own-task` | 179 |
+| `/docs/cua-driver/guides/gemini` | `/docs/cua-driver/guides/connect-your-agent#gemini` | 11 |
+| `/docs/cua-driver/guides/trajectories` | `/docs/cua-driver/guides/operate#record-a-trajectory` | 45 |
+| `/docs/cua-driver/guides/test-in-a-sandbox` | `/docs/cua-driver/guides/vms-and-remote#test-a-driver-build-in-a-sandbox` | 9 |
+| `/docs/cua-driver/guides/cursor-motion` | `/docs/cua-driver/guides/recipes#design-a-cursor-motion` | 46 |
+| `/docs/cua-driver/concepts/perception-extension` | `/docs/cua-driver/concepts/how-cua-driver-works#the-optional-perception-extension` | 87 |
+| `/docs/cua-sdk/guides/migrate-from-deprecated-packages` | `/docs/cua-sdk/guides/cua-cloud-ended#deprecated-packages` | 14 |
+| `/docs/cua-sdk/guides/sidecars` | `/docs/cua-sdk/guides/services#sidecars` | 8 |
+| `/docs/cua-sdk/guides/your-cloud` | `/docs/cua-sdk/guides/local-runtimes#your-own-cloud` | 59 |
+| `/docs/cua-sdk/guides/secrets` | `/docs/cua-sdk/guides/services#secrets` | 8 |
+| `/docs/cua-sdk/guides/coding-agent-options` | `/docs/cua-sdk/guides/run-a-coding-agent#give-the-agent-mcp-servers` | 19 |
+| `/docs/cua-sdk/guides/browse-the-web` | `/docs/cua-sdk/guides/desktop#give-an-agent-a-browser` | 24 |
+| `/docs/cua-sdk/guides/thumbnails` | `/docs/cua-sdk/guides/desktop#thumbnails` | 5 |
+| `/docs/cua-sdk/guides/disk-usage` | `/docs/cua-sdk/guides/lifecycle#disk-usage-and-cleanup` | 7 |
+| `/docs/cua-sdk/guides/your-cloud-resources` | `/docs/cua-sdk/guides/local-runtimes#what-cua-creates` | 8 |
+| `/docs/cua-sdk/guides/contrib-providers` | `/docs/cua-sdk/guides/local-runtimes#other-sandbox-providers` | 10 |
+| `/docs/lume/guides/api-and-mcp` | `/docs/lume/guides/manage-vms#drive-lume-from-scripts-and-ai-clients` | 21 |
+| `/docs/cua-bench/guides/convert-benchmark-images` | `/docs/cua-bench/guides/benchmarks#build-a-benchmark-image` | 3 |
+| `/docs/spaces/guides/add-a-machine` | `/docs/spaces/guides/add-a-computer` | 0 |
+| `/docs/spaces/guides/unattended-access` | `/docs/spaces/guides/add-a-computer#add-a-computer-from-a-terminal` | 27 |
+| `/docs/spaces/guides/host-spaces-on-your-spare-mac` | `/docs/spaces/guides/add-a-computer#use-a-spare-mac-to-host-spaces` | 64 |
+| `/docs/spaces/guides/updates` | `/docs/spaces/guides/install#updates` | 4 |
+| `/docs/spaces/guides/use-from-an-agent` | `/docs/spaces/guides/connect-your-agent#what-your-agent-can-do` | 171 |
+| `/docs/spaces/guides/agent-keys` | `/docs/spaces/guides/connect-your-agent#agent-keys` | 2 |
+| `/docs/spaces/guides/plans` | `/docs/spaces/guides/teams#plans` | 6 |
+| `/docs/spaces/guides/teams/machines` | `/docs/spaces/guides/teams#team-computers` | 2 |
+| `/docs/spaces/guides/teams/faq` | `/docs/spaces/guides/teams#questions` | 1 |
+| `/docs/spaces/guides/send-files` | `/docs/spaces/guides/cua-volume#send-a-file-into-a-space` | 3 |
+| `/docs/spaces/guides/site-login` | `/docs/spaces/guides/keyvault#let-an-agent-sign-in-to-a-site` | 11 |
+| `/docs/spaces/guides/troubleshoot-create` | `/docs/spaces/guides/troubleshoot` | 0 |
+| `/docs/spaces/guides/mesh` | `/docs/spaces/guides/relay-security#end-to-end-encrypted-connections-beta` | 2 |
+| `/docs/spaces/examples/other-languages` | `/docs/spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages` | 5 |
+
+## Generated reference: CLI, Driver, Lume and Bench (PR 2)
+
+| Old path | New path | Views (30 days) |
+| --- | --- | --- |
+| `/docs/cua-cli/reference/cli/spaces` | `/docs/cua-cli/reference/cli/spaces-and-computers#cua-spaces` | 12 |
+| `/docs/cua-cli/reference/cli/host` | `/docs/cua-cli/reference/cli/spaces-and-computers#cua-host` | 6 |
+| `/docs/cua-cli/reference/cli/devices` | `/docs/cua-cli/reference/cli/spaces-and-computers#cua-devices` | 3 |
+| `/docs/cua-cli/reference/cli/team` | `/docs/cua-cli/reference/cli/spaces-and-computers#cua-team` | 3 |
+| `/docs/cua-cli/reference/cli/usage` | `/docs/cua-cli/reference/cli/spaces-and-computers#cua-usage` | 2 |
+| `/docs/cua-cli/reference/cli/spacesd` | `/docs/cua-cli/reference/cli/spaces-and-computers#cua-spacesd` | 4 |
+| `/docs/cua-cli/reference/cli/volume` | `/docs/cua-cli/reference/cli/files-teleport-and-keys#cua-volume` | 2 |
+| `/docs/cua-cli/reference/cli/teleport` | `/docs/cua-cli/reference/cli/files-teleport-and-keys#cua-teleport` | 2 |
+| `/docs/cua-cli/reference/cli/keyvault` | `/docs/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault` | 4 |
+| `/docs/cua-cli/reference/cli/sandbox` | `/docs/cua-cli/reference/cli/sandboxes#cua-sandbox` | 5 |
+| `/docs/cua-cli/reference/cli/image` | `/docs/cua-cli/reference/cli/sandboxes#cua-image` | 3 |
+| `/docs/cua-cli/reference/cli/runtime` | `/docs/cua-cli/reference/cli/sandboxes#cua-runtime` | 3 |
+| `/docs/cua-cli/reference/cli/cache` | `/docs/cua-cli/reference/cli/sandboxes#cua-cache` | 3 |
+| `/docs/cua-cli/reference/cli/cloud` | `/docs/cua-cli/reference/cli/sandboxes#cua-cloud` | 4 |
+| `/docs/cua-cli/reference/cli/viewer` | `/docs/cua-cli/reference/cli/sandboxes#cua-viewer` | 2 |
+| `/docs/cua-cli/reference/cli/do` | `/docs/cua-cli/reference/cli/computer-actions#cua-do` | 3 |
+| `/docs/cua-cli/reference/cli/trajectory` | `/docs/cua-cli/reference/cli/computer-actions#cua-trajectory` | 2 |
+| `/docs/cua-cli/reference/cli/agent` | `/docs/cua-cli/reference/cli/agents#cua-agent` | 8 |
+| `/docs/cua-cli/reference/cli/mcp` | `/docs/cua-cli/reference/cli/agents#cua-mcp` | 2 |
+| `/docs/cua-cli/reference/cli/skills` | `/docs/cua-cli/reference/cli/agents#cua-skills` | 5 |
+| `/docs/cua-cli/reference/cli/auth` | `/docs/cua-cli/reference/cli/account-and-setup#cua-auth` | 5 |
+| `/docs/cua-cli/reference/cli/config` | `/docs/cua-cli/reference/cli/account-and-setup#cua-config` | 2 |
+| `/docs/cua-cli/reference/cli/daemon` | `/docs/cua-cli/reference/cli/account-and-setup#cua-daemon` | 3 |
+| `/docs/cua-cli/reference/cli/doctor` | `/docs/cua-cli/reference/cli/account-and-setup#cua-doctor` | 3 |
+| `/docs/cua-cli/reference/cli/telemetry` | `/docs/cua-cli/reference/cli/account-and-setup#cua-telemetry` | 2 |
+| `/docs/cua-cli/reference/cli/sandbox-access` | `/docs/cua-cli/reference/cli/sandboxes#cua-sandbox-exec` | 5 |
+| `/docs/cua-cli/reference/mcp-tools/computer` | `/docs/cua-cli/reference/mcp-tools#computer-tools` | 7 |
+| `/docs/cua-cli/reference/mcp-tools/images` | `/docs/cua-cli/reference/mcp-tools#image-tools` | 1 |
+| `/docs/cua-cli/reference/mcp-tools/sandbox` | `/docs/cua-cli/reference/mcp-tools#sandbox-tools` | 2 |
+| `/docs/cua-cli/reference/mcp-tools/skills` | `/docs/cua-cli/reference/mcp-tools#skills-tools` | 3 |
+| `/docs/cua-cli/reference/mcp-tools/spaces` | `/docs/cua-cli/reference/mcp-tools#spaces-tools` | 2 |
+| `/docs/cua-cli/reference/mcp-tools/teleport` | `/docs/cua-cli/reference/mcp-tools#teleport-tools` | 2 |
+| `/docs/cua-driver/reference/cli/mcp` | `/docs/cua-driver/reference/cli/serve-and-configure#cua-driver-mcp` | 26 |
+| `/docs/cua-driver/reference/cli/daemon` | `/docs/cua-driver/reference/cli/serve-and-configure#cua-driver-serve` | 14 |
+| `/docs/cua-driver/reference/cli/permissions` | `/docs/cua-driver/reference/cli/serve-and-configure#cua-driver-permissions` | 21 |
+| `/docs/cua-driver/reference/cli/config` | `/docs/cua-driver/reference/cli/serve-and-configure#cua-driver-config` | 4 |
+| `/docs/cua-driver/reference/cli/updates` | `/docs/cua-driver/reference/cli/serve-and-configure#cua-driver-check-update` | 8 |
+| `/docs/cua-driver/reference/cli/extensions` | `/docs/cua-driver/reference/cli/skills-recording-and-history#cua-driver-skills` | 10 |
+| `/docs/cua-driver/reference/cli/recording` | `/docs/cua-driver/reference/cli/skills-recording-and-history#cua-driver-recording` | 3 |
+| `/docs/cua-driver/reference/cli/history` | `/docs/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history` | 3 |
+| `/docs/cua-driver/reference/mcp-tools/apps-and-windows` | `/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen#app-and-window-tools` | 16 |
+| `/docs/cua-driver/reference/mcp-tools/window-state` | `/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen#window-state-tools` | 14 |
+| `/docs/cua-driver/reference/mcp-tools/screen` | `/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen#screen-tools` | 5 |
+| `/docs/cua-driver/reference/mcp-tools/sessions` | `/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen#session-tools` | 3 |
+| `/docs/cua-driver/reference/mcp-tools/click` | `/docs/cua-driver/reference/mcp-tools/click-and-type#click-tool` | 16 |
+| `/docs/cua-driver/reference/mcp-tools/double-and-right-click` | `/docs/cua-driver/reference/mcp-tools/click-and-type#double-click-and-right-click-tools` | 3 |
+| `/docs/cua-driver/reference/mcp-tools/keyboard` | `/docs/cua-driver/reference/mcp-tools/click-and-type#typing-tools` | 7 |
+| `/docs/cua-driver/reference/mcp-tools/keys-and-shortcuts` | `/docs/cua-driver/reference/mcp-tools/click-and-type#key-and-shortcut-tools` | 5 |
+| `/docs/cua-driver/reference/mcp-tools/values-and-clipboard` | `/docs/cua-driver/reference/mcp-tools/click-and-type#value-and-clipboard-tools` | 6 |
+| `/docs/cua-driver/reference/mcp-tools/pointer` | `/docs/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#pointer-tools` | 12 |
+| `/docs/cua-driver/reference/mcp-tools/agent-cursor` | `/docs/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#agent-cursor-tools` | 154 |
+| `/docs/cua-driver/reference/mcp-tools/page` | `/docs/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#page-tools` | 6 |
+| `/docs/cua-driver/reference/mcp-tools/browser-input` | `/docs/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser-input-tools` | 8 |
+| `/docs/cua-driver/reference/mcp-tools/batch` | `/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings#batch-and-script-tools` | 14 |
+| `/docs/cua-driver/reference/mcp-tools/recording` | `/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings#recording-tools` | 11 |
+| `/docs/cua-driver/reference/mcp-tools/maintenance` | `/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings#configuration-and-maintenance-tools` | 7 |
+| `/docs/lume/reference/cli/vms` | `/docs/lume/reference/cli#vms` | 10 |
+| `/docs/lume/reference/cli/images` | `/docs/lume/reference/cli#images` | 4 |
+| `/docs/lume/reference/cli/guest` | `/docs/lume/reference/cli#guest-access` | 5 |
+| `/docs/lume/reference/cli/server` | `/docs/lume/reference/cli#server` | 3 |
+| `/docs/lume/reference/cli/config` | `/docs/lume/reference/cli#configuration` | 4 |
+| `/docs/lume/reference/cli/updates` | `/docs/lume/reference/cli#updates` | 1 |
+| `/docs/lume/reference/mcp-tools` | `/docs/lume/reference/http-api#mcp-tools` | 2 |
+| `/docs/cua-bench/reference/cli/run` | `/docs/cua-bench/reference/cli#cb-run` | 3 |
+| `/docs/cua-bench/reference/cli/task` | `/docs/cua-bench/reference/cli#cb-task` | 5 |
+| `/docs/cua-bench/reference/cli/dataset` | `/docs/cua-bench/reference/cli#cb-dataset` | 8 |
+| `/docs/cua-bench/reference/cli/trace` | `/docs/cua-bench/reference/cli#cb-trace` | 3 |
+| `/docs/cua-bench/reference/cli/env` | `/docs/cua-bench/reference/cli#sandboxes-and-account` | 3 |
+| `/docs/cua-bench/reference/cli/agent` | `/docs/cua-bench/reference/cli#cb-agent` | 3 |
+| `/docs/cua-bench/reference/cli/images` | `/docs/cua-bench/reference/cli#images-and-platforms` | 3 |
+| `/docs/cua-bench/reference/results` | `/docs/cua-bench/reference/task-definition#result-files` | 6 |
+
+## Generated reference: SDK and Spaces (PR 3)
+
+| Old path | New path | Views (30 days) |
+| --- | --- | --- |
+| `/docs/cua-sdk/reference/agent-setup` | `/docs/cua-sdk/reference/agents#agent-setup` | 5 |
+| `/docs/cua-sdk/reference/local` | `/docs/cua-sdk/reference/cua#local-runtimes` | 3 |
+| `/docs/cua-sdk/reference/telemetry` | `/docs/cua-sdk/reference/auth#telemetry` | 1 |
+| `/docs/cua-sdk/reference/sandbox/lifecycle` | `/docs/cua-sdk/reference/sandbox#lifecycle` | 4 |
+| `/docs/cua-sdk/reference/sandbox/options` | `/docs/cua-sdk/reference/image#create-options` | 2 |
+| `/docs/cua-sdk/reference/sandbox/without-spacesd` | `/docs/cua-sdk/reference/spacesd#without-cua-spacesd` | 13 |
+| `/docs/cua-sdk/reference/spacesd/shell` | `/docs/cua-sdk/reference/spacesd#processes` | 2 |
+| `/docs/cua-sdk/reference/spacesd/media` | `/docs/cua-sdk/reference/spacesd/computer#media` | 2 |
+| `/docs/cua-sdk/reference/spaces/create` | `/docs/cua-sdk/reference/spaces#create-options` | 4 |
+| `/docs/cua-sdk/reference/spaces/agents` | `/docs/cua-sdk/reference/spaces#agents-in-a-space` | 3 |
+| `/docs/cua-sdk/reference/spaces/windows` | `/docs/cua-sdk/reference/spaces/space#windows-icons-and-displays` | 3 |
+| `/docs/cua-sdk/reference/spaces/teleport` | `/docs/cua-sdk/reference/spaces/space#teleport` | 6 |
+| `/docs/cua-sdk/reference/spaces/cloud` | `/docs/cua-sdk/reference/spaces/persistent-agents#your-cloud` | 2 |
+| `/docs/cua-sdk/reference/spaces/volume-sync` | `/docs/cua-sdk/reference/spaces/volume#cua-volume-storage-and-sync` | 3 |
+| `/docs/cua-sdk/reference/spaces/devices` | `/docs/cua-sdk/reference/spaces/host#this-device-on-the-relay` | 2 |
+| `/docs/cua-sdk/reference/spaces/decoded-media` | `/docs/cua-sdk/reference/spacesd/computer#media` | 2 |
+| `/docs/cua-sdk/reference/spaces/teleport-host` | `/docs/cua-sdk/reference/spaces/space#teleport` | 2 |
+| `/docs/cua-sdk/reference/spaces/teleport-apps` | `/docs/cua-sdk/reference/spaces/space#teleport` | 5 |
+| `/docs/cua-sdk/reference/python/configuration` | `/docs/cua-sdk/reference/python/runtimes#configuration-and-errors` | 1 |
+| `/docs/cua-sdk/reference/python/image` | `/docs/cua-sdk/reference/python/sandbox#images-and-registries` | 15 |
+| `/docs/cua-sdk/reference/python/services` | `/docs/cua-sdk/reference/python/sandbox#services-tunnels-and-mcp` | 9 |
+| `/docs/cua-sdk/reference/python/pool` | `/docs/cua-sdk/guides/cua-cloud-ended` | 15 |
+| `/docs/cua-sdk/reference/typescript/spaces-host` | `/docs/cua-sdk/reference/typescript#trycuacuaspaceshost` | 2 |
+| `/docs/cua-sdk/reference/typescript/spaces-transport` | `/docs/cua-sdk/reference/typescript#trycuacuaspacestransport` | 1 |
+| `/docs/cua-sdk/reference/protocol/env-common` | `/docs/cua-sdk/reference/protocol/env-system` | 2 |
+| `/docs/cua-sdk/reference/protocol/env-diagnose` | `/docs/cua-sdk/reference/protocol/env-system` | 2 |
+| `/docs/cua-sdk/reference/protocol/env-filesystem` | `/docs/cua-sdk/reference/protocol/env-process` | 2 |
+| `/docs/cua-sdk/reference/protocol/env-windows` | `/docs/cua-sdk/reference/protocol/env-computer` | 3 |
+| `/docs/cua-sdk/reference/protocol/env-teleport-tunnel` | `/docs/cua-sdk/reference/protocol/env-stream` | 1 |
+| `/docs/cua-sdk/reference/protocol/env-host-spaces` | `/docs/cua-sdk/reference/protocol/env-stream` | 2 |
+| `/docs/cua-sdk/reference/protocol/daemon-sandboxes` | `/docs/cua-sdk/reference/protocol/daemon` | 6 |
+| `/docs/cua-sdk/reference/protocol/daemon-runtimes` | `/docs/cua-sdk/reference/protocol/daemon` | 3 |
+| `/docs/cua-sdk/reference/protocol/daemon-spaces` | `/docs/cua-sdk/reference/protocol/daemon` | 1 |
+| `/docs/cua-sdk/reference/protocol/daemon-service` | `/docs/cua-sdk/reference/protocol/daemon` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core` | `/docs/cua-sdk/reference/spaces` | 1 |
+| `/docs/cua-sdk/reference/spaces/account-app-core` | `/docs/cua-sdk/reference/spaces` | 1 |
+| `/docs/cua-sdk/reference/spaces/agents-app-core` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/machines-app-core` | `/docs/cua-sdk/reference/spaces` | 1 |
+| `/docs/cua-sdk/reference/spaces/volume-app-core` | `/docs/cua-sdk/reference/spaces/volume` | 13 |
+| `/docs/cua-sdk/reference/spaces/app-checklist-palette` | `/docs/cua-sdk/reference/spaces` | 1 |
+| `/docs/spaces/reference/lifecycle` | `/docs/spaces/reference/spaces#space-lifecycle` | 5 |
+| `/docs/spaces/reference/commands-and-files` | `/docs/spaces/reference/spaces#commands-and-files` | 3 |
+| `/docs/spaces/reference/streams-and-display` | `/docs/spaces/reference/spaces#streams-and-display` | 4 |
+| `/docs/spaces/reference/services` | `/docs/spaces/reference/spaces#services` | 4 |
+| `/docs/spaces/reference/hotspot` | `/docs/spaces/reference/spaces#hotspot` | 4 |
+| `/docs/spaces/reference/sharing` | `/docs/spaces/reference/spaces#sharing` | 4 |
+| `/docs/spaces/reference/cloud` | `/docs/spaces/reference/spaces#your-cloud` | 146 |
+| `/docs/spaces/reference/persistent-agents` | `/docs/spaces/reference/agents#persistent-agents` | 9 |
+| `/docs/spaces/reference/teleport` | `/docs/spaces/reference/agents#session-teleport` | 325 |
+| `/docs/spaces/reference/keyvault` | `/docs/spaces/reference/agents#keyvault` | 4 |
+| `/docs/spaces/reference/volume` | `/docs/spaces/reference/agents#cua-volume` | 4 |
+| `/docs/spaces/reference/errors` | `/docs/spaces/reference#errors` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/about` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/agent-keys` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/cloud` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/creates` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/devices` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/drag-trigger` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/experiments` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/images` | `/docs/cua-sdk/reference/spaces` | 5 |
+| `/docs/cua-sdk/reference/spaces/app-core/keyvault-screens` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/keyvault` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/new-space` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/notch` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/onboarding-settings` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/power` | `/docs/cua-sdk/reference/spaces` | 1 |
+| `/docs/cua-sdk/reference/spaces/app-core/run-on` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/share` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/spaces` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/stream` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/telemetry` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/teleport-grid` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/teleport-review` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/teleport-run` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/teleport-transfer` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/teleport` | `/docs/cua-sdk/reference/spaces` | 2 |
+| `/docs/cua-sdk/reference/spaces/app-core/this-machine` | `/docs/cua-sdk/reference/spaces` | 3 |
+| `/docs/cua-sdk/reference/spaces/app-core/window` | `/docs/cua-sdk/reference/spaces` | 5 |
+| `/docs/cua-sdk/reference/rust/cua-fleet` | `/docs/cua-sdk/guides/cua-cloud-ended` | 3 |
+| `/docs/cua-sdk/reference/rust/cua-sandbox-core` | `/docs/cua-sdk/reference/rust` | 2 |
+| `/docs/cua-sdk/reference/rust/cua-spaces` | `/docs/cua-sdk/reference/rust` | 3 |
+| `/docs/cua-sdk/reference/rust/cua-spaces-client` | `/docs/cua-sdk/reference/rust` | 0 |
+| `/docs/cua-sdk/reference/rust/cua-spaces-agents-mcp` | `/docs/cua-sdk/reference/rust` | 3 |
+
+Every old URL redirects (docs/content/docs/redirects.json). Existing redirects that pointed at a removed page were repointed at its new home.
diff --git a/docs/content/docs/cua-bench/guides/adapter-benchmarks.mdx b/docs/content/docs/cua-bench/guides/adapter-benchmarks.mdx
index ae5c9c131e..b36f820220 100644
--- a/docs/content/docs/cua-bench/guides/adapter-benchmarks.mdx
+++ b/docs/content/docs/cua-bench/guides/adapter-benchmarks.mdx
@@ -35,8 +35,8 @@ Both run cua-spacesd, and every result records `image_ref`, `image_variant`,
| [OSWorld-G](https://github.com/xlang-ai/OSWorld-G) | Click the described element | 564 | none |
| [ScreenSpot-Pro](https://huggingface.co/datasets/likaixin/ScreenSpot-Pro) | High-resolution professional app screenshots | ~1,581 | none |
-Images live under `ghcr.io/trycua/`. How they are built:
-[Convert benchmark images](/cua-bench/guides/convert-benchmark-images).
+Images live under `ghcr.io/trycua/`. To see how they are built, read
+[Build a benchmark image](/cua-bench/guides/benchmarks#build-a-benchmark-image).
## OSWorld-Verified
diff --git a/docs/content/docs/cua-bench/guides/benchmarks.mdx b/docs/content/docs/cua-bench/guides/benchmarks.mdx
index b73a502be7..693b3fd6d9 100644
--- a/docs/content/docs/cua-bench/guides/benchmarks.mdx
+++ b/docs/content/docs/cua-bench/guides/benchmarks.mdx
@@ -4,7 +4,7 @@ description: 'Pick a taskset from the Cua Bench registry, run it with one cb run
---
A benchmark in Cua Bench is a registry taskset: a versioned set of desktop
-tasks, each with a setup, an oracle and an evaluator. Browse them at
+tasks, each with a setup, an oracle (a built-in solution) and an evaluator. Browse them at
**[cua.ai/cuabench/registry](https://cua.ai/cuabench/registry)** and run one
by name.
@@ -111,6 +111,34 @@ tasks that set none:
pinned per task) are fetched as-is. To write tasks for it, see
[Write a task](/cua-bench/guides/write-a-task).
+## Build a benchmark image
+
+The [adapter benchmarks](/cua-bench/guides/adapter-benchmarks) run on converted
+images: an upstream benchmark's environment, rebuilt as one Cua image with a
+container variant and a VM variant. The pipeline lives in `scripts/bench-images/`.
+Each benchmark is described once in `libs/images/bench/<id>/bench.json` (pinned
+sources, license, redistribution class, server and variants). The pipeline
+fetches the sources, builds both variants, smoke-tests them and publishes them.
+
+```bash skip="no-runner"
+python3 scripts/bench-images/bench.py validate
+python3 scripts/bench-images/bench.py fetch osworld # sha256-checked downloads
+scripts/bench-images/build-qcow2.sh osworld # rootfs + containerdisk variants
+scripts/bench-images/publish.sh web # stage immutable pins, then --promote
+```
+
+| Variant | Tag | Runs on | Init |
+| --- | --- | --- | --- |
+| `rootfs` | `<ver>` | gVisor or runc | supervisord |
+| `containerdisk` | `<ver>-disk` | QEMU | systemd |
+
+`--promote` moves `<ver>` and `<ver>-disk` only after `cua-spacesd doctor`
+passes on every staged digest, architecture and variant.
+
+On an arm64 host, amd64 images run under x86 emulation, where Mesa's llvmpipe
+draws a black screen. Server, file and spacesd checks still work, but doctor and
+screen evidence for amd64 need a native amd64 host.
+
## Next
- [Adapter benchmarks](/cua-bench/guides/adapter-benchmarks):
diff --git a/docs/content/docs/cua-bench/guides/convert-benchmark-images.mdx b/docs/content/docs/cua-bench/guides/convert-benchmark-images.mdx
deleted file mode 100644
index ccb1d44ead..0000000000
--- a/docs/content/docs/cua-bench/guides/convert-benchmark-images.mdx
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: Convert benchmark images
-description: 'Turn an upstream benchmark environment into one Cua image with a container and a VM variant, publish it, and check eval parity.'
----
-
-The pipeline lives in `scripts/bench-images/`. Each benchmark is described once
-in `libs/images/bench/<id>/bench.json` (pinned sources, license,
-redistribution class, server, variants), then fetched, built as both variants,
-smoked, and published.
-
-```bash skip="no-runner"
-python3 scripts/bench-images/bench.py validate
-python3 scripts/bench-images/bench.py fetch osworld # sha256-checked downloads
-scripts/bench-images/build-qcow2.sh osworld # rootfs + containerdisk variants
-scripts/bench-images/publish.sh web # stage immutable pins, then --promote
-```
-
-| Variant | Tag | Runs on | Init |
-| --- | --- | --- | --- |
-| `rootfs` | `<ver>` | gVisor or runc | supervisord |
-| `containerdisk` | `<ver>-disk` | QEMU | systemd |
-
-`--promote` moves `<ver>` and `<ver>-disk` only after `cua-spacesd doctor`
-passes on every staged digest, arch and variant. The converted images are
-listed in [Adapter benchmarks](/cua-bench/guides/adapter-benchmarks).
-
-- On an arm64 host, amd64 images run under x86 emulation, where Mesa's
- llvmpipe draws a black screen; server, file and spacesd checks still work.
- Doctor and screen evidence for amd64 need a native amd64 host.
diff --git a/docs/content/docs/cua-bench/guides/meta.json b/docs/content/docs/cua-bench/guides/meta.json
index 1c81ca511a..31246a1bb1 100644
--- a/docs/content/docs/cua-bench/guides/meta.json
+++ b/docs/content/docs/cua-bench/guides/meta.json
@@ -3,7 +3,6 @@
"pages": [
"benchmarks",
"write-a-task",
- "adapter-benchmarks",
- "convert-benchmark-images"
+ "adapter-benchmarks"
]
}
diff --git a/docs/content/docs/cua-bench/guides/write-a-task.mdx b/docs/content/docs/cua-bench/guides/write-a-task.mdx
index e3b8aa8501..858a0140b8 100644
--- a/docs/content/docs/cua-bench/guides/write-a-task.mdx
+++ b/docs/content/docs/cua-bench/guides/write-a-task.mdx
@@ -102,8 +102,8 @@ native sandbox through cua-spacesd, so the image must ship it (the default
## Check it
-Scaffold a task, check its functions, then score it with its oracle in a local
-Linux sandbox:
+Scaffold a task, check that `cb` found its functions, then score it with its
+oracle in a local Linux sandbox:
```bash test="cli-shape" id="bench-task-create"
cb task create first-task
@@ -111,15 +111,10 @@ cb task info first-task
cb run first-task --variant-id 0 --oracle
```
-![cb task info: a native Linux task with 2 variants and setup, solve and evaluate](/img/cua-bench/cb-task-info.png)
+A missing check mark in `info` means a function is not decorated with the split
+being loaded. To solve the task yourself or hand it to an agent, follow
+[Create your own task](/cua-bench/quickstart#create-your-own-task) in the
+quickstart.
-A missing check mark in `info` means a function is not decorated with the
-split being loaded. To solve it yourself, `cb interact first-task --variant-id 0`
-opens the sandbox; press Enter to evaluate and release it:
-
-![cb interact: setup complete, evaluation result 1.0, sandbox released](/img/cua-bench/cb-interact.png)
-
-![The task sandbox mid-task: a terminal writing hello to /tmp/answer.txt](/img/cua-bench/cb-interact-desktop.png)
-
-To publish tasks as a taskset, pin their directory in a registry index: see
+To publish tasks as a taskset, pin their directory in a registry index. See
[Your own registry](/cua-bench/guides/benchmarks#your-own-registry).
diff --git a/docs/content/docs/cua-bench/index.mdx b/docs/content/docs/cua-bench/index.mdx
index 24c5e15d4b..2c511d35dd 100644
--- a/docs/content/docs/cua-bench/index.mdx
+++ b/docs/content/docs/cua-bench/index.mdx
@@ -2,7 +2,7 @@
title: Cua Bench
description: 'Run the Cua Bench registry tasksets against any computer-use agent on desktop sandboxes on your machine, or write your own verifiable tasks.'
landing:
- summary: 'Run and score computer-use benchmarks on desktops on your machine, or write your own tasks.'
+ summary: 'Run and score computer-use tests on your machine.'
cta: Evaluate an agent
---
@@ -47,8 +47,8 @@ Tasks run in a real sandbox from the [cua SDK](/cua-sdk) on this machine (`cb ru
## Next
-- [Quickstart](/cua-bench/quickstart): run a registry taskset, read the score, add an agent.
-- [Run a benchmark](/cua-bench/guides/benchmarks): every registry taskset, versions, pass@k.
+- [Quickstart](/cua-bench/quickstart): run a registry taskset, read the score, add an agent, create your own task.
+- [Run a benchmark](/cua-bench/guides/benchmarks): every registry taskset, versions, pass@k, and how benchmark images are built.
- [Write a task](/cua-bench/guides/write-a-task): the task module contract.
- [Adapter benchmarks](/cua-bench/guides/adapter-benchmarks): OSWorld-Verified, MiniWoB++, WebVoyager and other adapters.
diff --git a/docs/content/docs/cua-bench/quickstart.mdx b/docs/content/docs/cua-bench/quickstart.mdx
index 4d56098144..1e1065c1a2 100644
--- a/docs/content/docs/cua-bench/quickstart.mdx
+++ b/docs/content/docs/cua-bench/quickstart.mdx
@@ -1,17 +1,22 @@
---
title: Quickstart
-description: 'Run a Cua Bench registry taskset on a local desktop sandbox with one command, read the results, then run it with an agent.'
+description: 'Run a Cua Bench registry taskset on a local desktop sandbox, read the score, run it with an agent, then create and score your own task.'
---
-Pick a taskset from the [Cua Bench registry](https://cua.ai/cuabench/registry),
-run it on a local desktop sandbox, and read the score. No API key until the
-agent step.
+Run a ready-made taskset from the
+[Cua Bench registry](https://cua.ai/cuabench/registry) on your machine, read the
+score, and hand it to an agent. Then create a small task of your own. You need
+no API key until you run an agent.
-## Prerequisites
+## Before you start
- Python 3.12 or 3.13 and [uv](https://docs.astral.sh/uv/).
-- A local container runtime (Docker; gVisor when installed): check with
- `cua runtime doctor`.
+- A local container runtime: Docker, plus gVisor when installed. Check it with
+ the `cua` CLI:
+
+```bash test="cli-shape" id="cua-runtime-doctor"
+cua runtime doctor
+```
## Install
@@ -19,20 +24,23 @@ agent step.
uv tool install cua-bench
```
+This puts the `cb` command on your `PATH`. `cb --help` lists its command
+groups, including `run`, `interact`, `task` and `trace`.
+
## Run a registry taskset
-List the tasksets, then run one task of `cua-bench-basic` with its built-in
-oracle:
+List the tasksets, then run one task of `cua-bench-basic` with its oracle. The
+oracle is the task's built-in solution:
```bash test="cli-shape" id="bench-quickstart-run"
cb dataset list
cb run cua-bench-basic --task-filter click-button --max-variants 1
```
-`cb` fetches the taskset at its pinned version, starts a Linux desktop
-sandbox, opens the task's app as a window on it, runs the oracle, scores the
-result (`reward=1`) and releases the sandbox. A failing oracle means the task
-or your setup is broken, not the agent.
+`cb` fetches the taskset at its pinned version, starts a Linux desktop sandbox,
+opens the task's app as a window on it, runs the oracle, scores the result
+(`reward=1`) and releases the sandbox. If the oracle fails, the task or your
+setup is broken, not the agent.
## Read the results
@@ -50,22 +58,115 @@ Each variant's `result.json`, `run.log` and `trajectory.json` land in
cb run cua-bench-basic --agent cua-agent --model anthropic/claude-sonnet-4-20250514 -j 4
```
-It runs every task on this machine (`--on local` is the default).
+This runs every task on your machine. `--on local` is the default, and `--kind`,
+`--runtime`, `--image`, `--cpu` and `--memory` shape the sandboxes.
+
+## Create your own task
+
+A task has variants (the same goal asked in different ways), a setup function,
+an oracle and an evaluator. The same evaluator scores the oracle, you and an
+agent.
+
+### Scaffold it
+
+Create a working directory and scaffold a task in it:
+
+```bash skip="no-runner"
+mkdir cua-bench-tutorial && cd cua-bench-tutorial
+cb task create first-task
+```
+
+Answer the prompts, for example:
-## Try a task yourself
+```text output
+Author name: Your name
+Author email: [email protected]
+License [MIT]:
+Task description: Write a word to a file
+Task difficulty (easy|medium|hard) [easy]:
+Task category (e.g., grounding, software-engineering) [grounding]:
+Tags (comma-separated): starter,linux
+```
+
+The scaffold is two files:
+
+```text output
+first-task/
+├── main.py
+└── pyproject.toml
+```
+
+`main.py` defines the whole task. The starter has two variants, each asking for
+one word in `/tmp/answer.txt`, and four functions:
+
+```python skip="pseudo"
[email protected]_config(split="train")
+def load(): ... # the variants and the machine they run on (native Linux)
+
[email protected]_task(split="train")
+async def start(task_cfg, session): ... # remove any old answer
+
[email protected]_task(split="train")
+async def solve(task_cfg, session): ... # the oracle: write the right word
+
[email protected]_task(split="train")
+async def evaluate(task_cfg, session): ... # 1.0 if the file holds the word
+```
-`cb interact` sets up a task on a desktop you can see, waits while you solve
-it, then evaluates it and releases the sandbox:
+### Inspect it
-```bash test="cli-shape" id="bench-quickstart-interact"
-cb interact click-button --dataset cua-bench-basic
+```bash skip="no-runner"
+cb task info first-task
+```
+
+![cb task info: a native Linux task with 2 variants and setup, solve and evaluate](/img/cua-bench/cb-task-info.png)
+
+The provider is `native`: a real OS in a container or VM. The check marks mean
+Cua Bench found the setup, solve and evaluate functions.
+
+### Run the oracle
+
+```bash skip="no-runner"
+cb run first-task --variant-id 0 --oracle
+```
+
+`cb run` starts a Linux sandbox, runs the setup, the oracle and the evaluator,
+and releases the sandbox. It reports `reward=1`.
+
+### Solve it yourself
+
+Open the same variant without the oracle:
+
+```bash skip="no-runner"
+cb interact first-task --variant-id 0
+```
+
+`cb interact` sets the task up, prints the sandbox's `Display:` link and opens
+the viewer in your browser. Open a terminal on the sandbox desktop and write the
+answer:
+
+![The task sandbox mid-task: a terminal writing hello to /tmp/answer.txt](/img/cua-bench/cb-interact-desktop.png)
+
+Go back to your terminal and press Enter. Cua Bench evaluates the sandbox and
+releases it:
+
+![cb interact: setup complete, evaluation result 1.0, sandbox released](/img/cua-bench/cb-interact.png)
+
+### Give it to an agent
+
+```bash test="cli-shape" id="first-task-agent"
+cb run first-task --agent cua-agent --model anthropic/claude-sonnet-4-20250514
```
## Clean up
-Run results stay in `~/.local/share/cua-bench/runs` (a warning past 10 GiB,
-`CUA_BENCH_WARN_SIZE`). Keep fewer with `--keep-runs N`, `--max-age DAYS` or
-`--max-results-size SIZE` on `cb run`, or:
+```bash skip="destructive"
+cd .. && rm -rf cua-bench-tutorial
+```
+
+Run results stay in `~/.local/share/cua-bench/runs`, and `cb` warns when they
+pass 10 GiB (`CUA_BENCH_WARN_SIZE`). Keep fewer with `--keep-runs N`,
+`--max-age DAYS` or `--max-results-size SIZE` on `cb run`, or:
```bash test="cli-shape" id="bench-quickstart-prune"
cb prune --runs --keep 10
@@ -73,8 +174,8 @@ cb prune --runs --keep 10
## Next
-- [Run a benchmark](/cua-bench/guides/benchmarks): every registry taskset,
- selection, versions and pass@k.
-- [Write a task](/cua-bench/guides/write-a-task): make your own.
-- [Adapter benchmarks](/cua-bench/guides/adapter-benchmarks):
- OSWorld-Verified and other adapters.
+- [Run a benchmark](/cua-bench/guides/benchmarks): every registry taskset, selection, versions and pass@k.
+- [Write a task](/cua-bench/guides/write-a-task): richer setup, checks and HTML task windows.
+- [Adapter benchmarks](/cua-bench/guides/adapter-benchmarks): OSWorld-Verified and other adapters.
+- [Sandbox images](/cua-sdk/guides/images#every-published-image): the benchmark images and how to start them.
+- [CLI reference](/cua-bench/reference/cli)
diff --git a/docs/content/docs/cua-cli/guides/authentication.mdx b/docs/content/docs/cua-cli/guides/authentication.mdx
index 42c10ebc41..b83c1cde41 100644
--- a/docs/content/docs/cua-cli/guides/authentication.mdx
+++ b/docs/content/docs/cua-cli/guides/authentication.mdx
@@ -5,7 +5,7 @@ description: 'Sign in with cua auth login, see who is signed in, and sign out.'
import { Callout } from 'fumadocs-ui/components/callout';
-One sign-in covers the CLI, the SDK, `cua daemon` and the Cua Spaces app: they
+One sign-in covers the CLI, the SDK, `cua daemon` and the Cua Spaces app, which
share one credential store. Local sandboxes need no sign-in.
## Sign in
@@ -19,10 +19,10 @@ cua auth logout # revoke and remove the session
```
After an interactive login, `cua auth login` offers to set up your AI coding
-agents (skills plus the cua MCP server); `--agents claude,codex`, `--yes`,
-`--skills-only`, `--mcp-only` and `--no-onboarding` control it, and `never`
-is remembered in `~/.cua/config`. Tokens refresh automatically and are never
-printed.
+agents (the cua skills plus the cua MCP server). These flags control the offer:
+`--agents claude,codex`, `--yes`, `--skills-only`, `--mcp-only` and
+`--no-onboarding`. Answering `never` is remembered in `~/.cua/config`. Tokens
+refresh automatically and are never printed.
| Platform | Session stored in |
|----------|-------------------|
@@ -32,8 +32,8 @@ printed.
| Linux | `~/.cua/credentials.json`, mode 600 |
`CUA_CREDENTIAL_STORE=file` or `keychain` picks the store. A build from source
-is a new app to the Keychain every time it is rebuilt, so it uses the file and
-never asks for Keychain access.
+looks like a new app to the Keychain every time you rebuild it, so it uses the
+file and never asks for Keychain access.
Older versions kept the session, the device key and the other secrets under the
service `run.cua.ai` (`staging.run.cua.ai` for staging). The first `cua` that
@@ -45,26 +45,26 @@ not trust), `cua` leaves the old item as it is. Run `cua auth keychain --prompt`
in a terminal once and choose Always Allow, or sign in again.
`cua auth logout` removes both the new and the old items.
-On macOS, `cua` never waits on a Keychain dialog it cannot show. Run from a
-terminal it lets macOS ask for access. Run without one (by an agent, a script
-or a service) it fails within seconds with a message instead of hanging, also
-when a dialog is already open on the Mac's screen and macOS holds the read
-behind it. Answer the dialog, or run `cua auth keychain --prompt` in a
-terminal once and choose Always Allow. `CUA_KEYCHAIN_NONINTERACTIVE=1` turns
-prompts off, `0` allows them without a terminal, and
-`CUA_KEYCHAIN_TIMEOUT_SECS` (default 5) sets how long a call may take.
+On macOS, `cua` never waits on a Keychain dialog it cannot show. In a terminal,
+it lets macOS ask for access. Without a terminal (an agent, a script or a
+service), it fails within seconds with a message instead of hanging. That
+includes the case where a dialog is already open on the Mac's screen and macOS
+holds the read behind it. Answer the dialog, or run `cua auth keychain --prompt`
+in a terminal once and choose Always Allow. `CUA_KEYCHAIN_NONINTERACTIVE=1` turns
+prompts off, `0` allows them without a terminal, and `CUA_KEYCHAIN_TIMEOUT_SECS`
+(default 5) sets how many seconds a call may take.
<Callout type="warn">
- The stored refresh token mints access tokens until revoked. On shared hosts,
- run `cua auth logout` when done, or sign in again when you need it.
+ The stored refresh token keeps minting access tokens until you revoke it. On a
+ shared machine, run `cua auth logout` when you are done.
</Callout>
-## Targeting staging
+## Use the staging environment
`CUA_ENV=staging` points the CLI, the SDK, `cua daemon` and the Cua Spaces app
-at the Cua staging deployment, which is for testing Cua itself. Unset, or
-`prod`, is production. Any other value makes `cua` exit with code `2` rather
-than fall back to production.
+at Cua's staging deployment, which exists for testing Cua itself. Unset or
+`prod` means production. Any other value makes `cua` exit with code `2` instead
+of falling back to production.
```bash test="cli-shape" id="cua-env-staging"
export CUA_ENV=staging
@@ -83,23 +83,24 @@ cua auth status # starts with "Environment: staging (...)"
| Keychain / Credential Manager service | none | `ai.cua.session` (`ai.cua.session.staging` for staging) |
Each environment has its own session, host enrollment, Spaces registry and
-daemon, so signing in to staging never replaces or sends your production
-session, and the other way round.
-
-Usage telemetry follows the environment too: staging events go to the staging
-PostHog project, never to production's. `CUA_POSTHOG_KEY` overrides the
-project key; `CUA_TELEMETRY_ENDPOINT` overrides the ingest URL.
-
-Beta channel builds talk to staging by default. A `cua` compiled with
-`CUA_DEFAULT_ENV=staging` treats an unset `CUA_ENV` as `staging`, and the macOS
-app built with `scripts/build-release.sh --channel beta` carries `CuaEnv=staging`
-in its `Info.plist` and compiles its bundled `cua` the same way. `CUA_ENV=prod`
-still selects production in a beta build.
-
-For the macOS app, launch it with the variable set:
-`open -n --env CUA_ENV=staging -a "Cua Spaces"`. Quit the production app
-first. The host service (`cua host setup`) has one name on each machine, so pair
-a staging host on a separate machine or VM.
-
-Other variables (`CUA_OIDC_ISSUER`, `CUA_AUTH_FLOW`,
-`CUA_NO_BROWSER`, ...) are listed in the [CLI reference](/cua-cli/reference/cli).
+daemon. Signing in to staging never replaces or sends your production session,
+and the other way round. Usage telemetry follows the environment too: staging
+events go to the staging PostHog project, never to production's.
+`CUA_POSTHOG_KEY` overrides the project key, and `CUA_TELEMETRY_ENDPOINT`
+overrides the ingest URL.
+
+Beta builds of `cua` and the Cua Spaces app use staging when `CUA_ENV` is unset.
+`CUA_ENV=prod` still selects production in a beta build.
+
+To open the macOS app against staging, quit the production app first, then
+launch it with the variable set:
+
+```bash skip="host-install"
+open -n --env CUA_ENV=staging -a "Cua Spaces"
+```
+
+The host service (`cua host setup`) has one name on each machine, so pair a
+staging host on a separate machine or VM.
+
+Other variables (`CUA_AUTH_FLOW`, `CUA_NO_BROWSER` and more) are listed in the
+[CLI reference](/cua-cli/reference/cli).
diff --git a/docs/content/docs/cua-cli/guides/mcp-server.mdx b/docs/content/docs/cua-cli/guides/mcp-server.mdx
index 423865d8b3..19df6e4c0f 100644
--- a/docs/content/docs/cua-cli/guides/mcp-server.mdx
+++ b/docs/content/docs/cua-cli/guides/mcp-server.mdx
@@ -5,27 +5,27 @@ description: 'Serve Spaces, sandbox, computer and skills tools to an AI client w
import { Callout } from 'fumadocs-ui/components/callout';
-`cua mcp` is a stdio MCP server with the Spaces tools plus sandbox, computer
-and skills tools. `cua daemon mcp` is the same server through `cua daemon`
-(started if needed), so several agents share Spaces, streams and sandboxes.
-For the machine the agent itself runs on, use
-[Cua Driver](/cua-driver/quickstart) instead.
+`cua mcp` is an MCP server, over stdio, that gives an AI client the Spaces tools
+plus sandbox, computer and skills tools. `cua daemon mcp` is the same server
+running through `cua daemon` (started if needed), so several agents can share
+Spaces, streams and sandboxes. To control the machine the agent itself runs on,
+use [Cua Driver](/cua-driver/quickstart) instead.
```bash skip="third-party-cli"
claude mcp add cua -- cua daemon mcp
claude mcp add cua -- cua mcp --sandbox dev --permissions sandbox:readonly,computer:all
```
-`cua agents setup` adds this entry for detected agents. `--sandbox`
-(`CUA_SANDBOX`) is the default target of the computer tools; each call can pass
-`sandbox`.
-Every tool is in [MCP tools](/cua-cli/reference/mcp-tools).
+`cua agents setup` adds this entry for the agents it detects. `--sandbox`
+(`CUA_SANDBOX`) sets the default sandbox for the computer tools, and each call
+can pass its own `sandbox`. Every tool is listed in
+[MCP tools](/cua-cli/reference/mcp-tools).
## Supported agents
`cua agents setup --agents <id>` installs the cua skills and adds the `cua`
-server to these user-scope configs. Other servers and comments are kept, and
-`cua agents remove` takes out only what cua added.
+server to these user-level configs. It keeps your other servers and comments,
+and `cua agents remove` takes out only what cua added.
| Agent | id | Skills | MCP config |
|-------|----|--------|------------|
@@ -53,8 +53,9 @@ Start a new Hermes session (or run `/reload-mcp`) to load the server.
## Permissions
-`--permissions` (`CUA_MCP_PERMISSIONS`) takes `group:action` strings and groups,
-comma-separated. Only granted tools are listed; others are refused.
+`--permissions` (`CUA_MCP_PERMISSIONS`) takes a comma-separated list of
+`group:action` strings and groups. The server lists only the tools you grant and
+refuses the rest.
| Group | Expands to |
|-------|-----------|
@@ -75,7 +76,7 @@ comma-separated. Only granted tools are listed; others are refused.
## Choose a grant
`computer:shell`, `computer:file`, `spaces:space_bash` and `spaces:teleport_app`
-run commands, touch files or use your app sessions in the target;
+run commands, touch files or use your app sessions in the target.
`sandbox:delete` and `spaces:delete_space` destroy sandboxes.
| Intent | Grant |
@@ -88,4 +89,4 @@ run commands, touch files or use your app sessions in the target;
Computer-tool coordinates are in the pixel space of the last
`computer_screenshot` (capped at 1200 px on the long edge). Spaces tools that
need cua-spacesd return `capability_missing` on images without it; see
-[Use Spaces from an agent](/spaces/guides/use-from-an-agent).
+[Use Spaces from an agent](/spaces/guides/connect-your-agent#what-your-agent-can-do).
diff --git a/docs/content/docs/cua-cli/index.mdx b/docs/content/docs/cua-cli/index.mdx
index 745d3d85bf..d832f7f03e 100644
--- a/docs/content/docs/cua-cli/index.mdx
+++ b/docs/content/docs/cua-cli/index.mdx
@@ -1,11 +1,13 @@
---
title: Cua CLI
description: 'The cua command: sign-in, sandboxes local and in your cloud, one-shot computer actions, MCP, Spaces, unattended access and teleport.'
+landing:
+ summary: 'The cua command for Spaces, sandboxes, sign-in and MCP.'
---
-`cua` is one binary built on the [cua SDK](/cua-sdk). It creates and drives
-sandboxes on this machine or in your own cloud, serves them to AI agents over MCP,
-and manages Spaces.
+`cua` is one command-line tool built on the [cua SDK](/cua-sdk). It creates and
+drives sandboxes on this machine or in your own cloud, serves them to AI agents
+over MCP, and manages Spaces.
## Install
@@ -32,13 +34,13 @@ flags: [Install Cua Spaces](/spaces/guides/install).
| `cua mcp` | `serve-mcp` | Stdio MCP server ([MCP server](/cua-cli/guides/mcp-server)). |
| `cua daemon` | | Shared background runtime; `cua daemon mcp`. |
| `cua spaces` | | Registered Spaces and your relay machines ([Cua Spaces](/spaces)). |
-| `cua cloud` | | Your own AWS, Google Cloud or Modal account as a location ([Use your own cloud](/cua-sdk/guides/your-cloud)). |
-| `cua host` | | [Unattended access](/spaces/guides/unattended-access) to this machine. |
+| `cua cloud` | | Your own AWS, Google Cloud or Modal account as a location ([Choose where sandboxes run](/cua-sdk/guides/local-runtimes#your-own-cloud)). |
+| `cua host` | | [Unattended access](/spaces/guides/add-a-computer#add-a-computer-from-a-terminal) to this machine. |
| `cua teleport` | | [Move an app session](/spaces/guides/teleport-an-app) into a sandbox. |
| `cua image` | `img` | Local OCI images. |
| `cua spacesd` | | Talk to any cua-spacesd by URL. |
| `cua runtime` | | Inspect or provision local runtimes. |
-| `cua cache` | | Disk used by images, sandboxes and logs, and its cleanup ([Disk usage](/cua-sdk/guides/disk-usage)). |
+| `cua cache` | | Disk used by images, sandboxes and logs, and its cleanup ([Disk usage](/cua-sdk/guides/lifecycle#disk-usage-and-cleanup)). |
| `cua doctor` | | Check the host, an image and a sandbox's guest in one report. |
| `cua skills`, `cua trajectory` | `traj` | Recorded demonstrations and `cua do` sessions. |
@@ -61,4 +63,4 @@ and the [CLI reference](/cua-cli/reference/cli) list every option.
`cua sb exec` and `cua spacesd exec` exit with the command's own status. State
lives in `~/.cua` (`CUA_HOME` moves it).
-Start with the [Quickstart](/cua-cli/quickstart).
+Start with the [Quickstart](/cua-cli/quickstart), which also creates a local macOS sandbox.
diff --git a/docs/content/docs/cua-cli/quickstart.mdx b/docs/content/docs/cua-cli/quickstart.mdx
index d277e0e21c..6ae089a44a 100644
--- a/docs/content/docs/cua-cli/quickstart.mdx
+++ b/docs/content/docs/cua-cli/quickstart.mdx
@@ -1,44 +1,49 @@
---
title: Quickstart
-description: 'Install the cua CLI, start a local sandbox, run a command in it, and drive its desktop.'
+description: 'Install the cua CLI, start a local Linux or macOS sandbox, run a command in it, take a screenshot, and drive its desktop.'
---
-Start a Linux sandbox on this machine, run a command in it, take a screenshot
-and drive its desktop.
+Start a sandbox on your own machine, run a command in it, take a screenshot and
+drive its desktop. A Linux sandbox works on macOS, Linux and Windows. A macOS
+sandbox needs an Apple silicon Mac.
-## Prerequisites
+## Before you start
-- macOS, Linux or Windows with Docker (or another local runtime:
- `cua runtime doctor` lists them).
+- For a Linux sandbox: macOS, Linux or Windows with Docker, or another local
+ runtime (`cua runtime doctor` lists them).
+- For a macOS sandbox: an Apple silicon Mac on macOS 14 or later, with about
+ 40 GB of free disk and 8 GB of free memory.
-## Run
+## Install
```bash skip="host-install"
curl -fsSL https://cua.ai/install.sh | sh -s -- --cli-only # or: pip install cua, npm i -g @trycua/cua
```
+## Linux sandbox
+
+Create it, run a command in it and take a screenshot:
+
```bash test="cli-shape" id="cua-quickstart-local"
cua sb create linux --name dev
cua sb exec dev "uname -a"
cua sb screenshot dev -o dev.png
```
-## Result
-
![cua sb create, ls, exec and view for a local Linux sandbox](/img/cua-cli/cua-sb-create.png)
-`exec` prints the guest's kernel line and exits with the command's status;
+`exec` prints the guest's kernel line and exits with the command's status.
`dev.png` is the sandbox desktop. With `--json` the result is structured:
```bash test="cli-shape" id="cua-quickstart-json"
cua --json sb exec dev pwd # {"stdout": ..., "stderr": ..., "returncode": 0}
```
-## Drive the desktop
+### Drive the desktop
-`--wait desktop` returns once the desktop session takes input (display,
-window manager and Cua Driver). `cua do` input waits for it too, and fails
-when input reaches no window.
+`--wait desktop` returns once the desktop accepts input (display, window
+manager and Cua Driver). `cua do` input waits for it too, and fails when the
+input reaches no window.
```bash test="cli-shape" id="cua-quickstart-do"
cua sb create linux --name desk --wait desktop
@@ -48,15 +53,104 @@ cua do type "echo hello"
cua do key enter
```
-## Clean up
+### Remove the Linux sandboxes
```bash test="cli-shape" id="cua-quickstart-rm"
cua sb rm dev
cua sb rm desk
```
+## macOS sandbox
+
+### Set up the runtime
+
+```bash test="cli-shape" id="macos-runtime-setup"
+cua runtime doctor
+cua runtime setup lume # installs Lume if it is missing
+```
+
+### Create it
+
+```bash test="cli-shape" id="macos-sb-create"
+cua sb create macos --name mac
+```
+
+```text output
+ID STATUS LOCATION KIND RUNTIME EXPIRES
+local:mac ready local vm lume -
+```
+
+`macos` is `ghcr.io/trycua/macos:26` (Tahoe). `macos:sequoia` is `:15`. The first
+create pulls the image (23 GB, about 8 minutes). Later creates clone it and are
+ready in about 25 seconds. The Tahoe image starts cua-spacesd at login, with its
+screen and accessibility permissions already granted.
+
+### Run a command
+
+```bash test="cli-shape" id="macos-sb-exec"
+cua sb exec mac -- sw_vers
+```
+
+```text output
+ProductName: macOS
+ProductVersion: 26.5.2
+BuildVersion: 25F84
+```
+
+`exec` runs through cua-spacesd and keeps stdout, stderr and the exit code
+apart. The Sequoia image has no cua-spacesd, so there `exec` runs over SSH
+(`lume ssh`).
+
+### Take a screenshot and open the desktop
+
+```bash test="cli-shape" id="macos-sb-screenshot"
+cua sb screenshot mac -o desktop.png
+```
+
+```text output
+wrote desktop.png (1024x768)
+```
+
+![The desktop of a local macOS Tahoe sandbox](/img/cua-cli/macos-sandbox-desktop.png)
+
+```bash test="cli-shape" id="macos-sb-view"
+cua sb view mac
+```
+
+```text output
+Viewer for mac: http://192.168.64.63:3211/viewer/#ticket=****&files=%2FUsers%2Flume
+```
+
+`view` opens cua-spacesd's HTML5 viewer in your browser with a short-lived
+ticket (`--no-open` prints the URL instead). On Sequoia, screenshots come over
+the VM's VNC endpoint and `view` opens the display with `lume attach`.
+
+### Remove it
+
+```bash test="cli-shape" id="macos-sb-rm"
+cua sb rm mac
+```
+
+The pulled image stays as a stopped base VM for the next create. `cua cache ls`
+lists it.
+
+### Use the SDK instead
+
+```python skip="macos-vm"
+from cua_sandbox import Image, Sandbox
+
+async with Sandbox.ephemeral(Image.macos()) as sb:
+ print((await sb.shell.run("sw_vers")).stdout)
+ png = await sb.screen.screenshot()
+```
+
+`sb.shell` and `sb.screen` go through cua-spacesd, the same path as the CLI.
+
## Next
- [Authentication](/cua-cli/guides/authentication): sign in, check who is signed in, sign out.
- [MCP server](/cua-cli/guides/mcp-server): give an AI agent these sandboxes.
- [CLI reference](/cua-cli/reference/cli): every command and option.
+- [Local runtimes](/cua-sdk/guides/local-runtimes)
+- [Sandbox images](/cua-sdk/guides/images#every-published-image)
+- [Lume quickstart](/lume/quickstart): a vanilla macOS VM from Apple's restore image, with Lume alone.
diff --git a/docs/content/docs/cua-driver/concepts/how-cua-driver-works.mdx b/docs/content/docs/cua-driver/concepts/how-cua-driver-works.mdx
index 48626b17b9..b46934a040 100644
--- a/docs/content/docs/cua-driver/concepts/how-cua-driver-works.mdx
+++ b/docs/content/docs/cua-driver/concepts/how-cua-driver-works.mdx
@@ -1,8 +1,10 @@
---
title: How Cua Driver works
-description: Observation, targets, the background-first action ladder, verification, and who owns the runtime.
+description: Observation, targets, the background-first action ladder, verification, choosing an integration, who owns the runtime, and the optional perception extension.
---
+import { Callout } from 'fumadocs-ui/components/callout';
+
Cua Driver is the UI layer of a computer-use agent. The harness runs the model
and the loop; Cua Driver turns each proposed step into an observation or an
action on a real desktop, and reports what happened.
@@ -21,8 +23,8 @@ one, and shows what the tree omits or gets wrong. Pass
`get_desktop_state` captures the whole primary display.
When neither the tree nor typed browser state exposes the target, the optional
-[perception extension](/cua-driver/concepts/perception-extension) can parse
-that same screenshot into labelled regions.
+[perception extension](#the-optional-perception-extension) can parse that same
+screenshot into labelled regions.
## Act: one exact target per call
@@ -83,6 +85,22 @@ compositor's seat sends input to, so the driver refuses rather than risk typing
into the wrong app. A structured `background_unavailable` is part of the
contract, not a failure to hide.
+## Choose an integration
+
+Pick by who owns the runtime: the process that holds the OS permissions,
+sessions and browser connections.
+
+| You are building | Use | Runtime owner |
+| --------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------- |
+| An agent or harness (Claude Code, Codex, Cursor, …) | [MCP](/cua-driver/guides/connect-your-agent): `cua-driver mcp` | The MCP process; on macOS, the `CuaDriver.app` daemon |
+| An agent that can only run shell commands | [CLI](/cua-driver/reference/cli): `cua-driver call <tool>` | The `cua-driver serve` daemon |
+| An app with built-in computer use | [SDK](/cua-driver/guides/use-the-sdk): `CuaDriver.create()` | On macOS, the `CuaDriver.app` daemon; elsewhere your app process |
+| A signed desktop app that serves an external agent | [App-hosted service](/cua-driver/guides/use-the-sdk#expose-mcp-from-a-desktop-app) | The permission-owning desktop app |
+| Several clients sharing one desktop | `cua-driver serve --socket <path>` plus `cua-driver mcp --socket <path>` | The daemon |
+
+Inside a [Cua Sandbox](/cua-sdk) you do not install Cua Driver: the sandbox's
+guest service bundles its tools.
+
## Processes and sessions
The runtime owns permissions, sessions, element caches, recordings, and browser
@@ -123,6 +141,75 @@ CLI, MCP, SDK, and daemon calls all pass the same authorization check inside
the runtime. The launcher fixes the mode, manifest, and grants at startup; an
agent cannot widen them. See [Set permissions](/cua-driver/guides/permissions).
+## The optional perception extension
+
+Canvas apps, custom-drawn views, games, remote desktops, and some web pages
+have no useful accessibility tree or page structure, so an agent has nothing to
+address by role or label. The optional `cua-perception` extension gives those
+screens a structure: it parses one screenshot into labelled regions (text,
+icons, controls) on your own machine, without sending the screenshot to a
+remote model. Cua Driver then acts on exactly the region the agent chose.
+
+It never replaces the tree and never captures on its own. Without it installed,
+`parse_visual_regions` returns `not_installed`, and agents continue with the
+accessibility tree or page structure. To run the loop step by step, see
+[Parse visual regions](/cua-driver/guides/visual-regions).
+
+### Every action is bound to one screenshot
+
+A region only means something on the screen it was found on, so Cua Driver ties
+each perception-based action to its capture:
+
+| Situation | Result |
+| --- | --- |
+| The click carries the `capture_id` of the screenshot the region came from | Delivered |
+| The same capture is reused for another action | Refused with `capture_not_found` |
+| The capture is older than 60 seconds | Refused with `capture_expired` |
+
+Agents receive region bounds and text, never screenshot bytes, and Cua Driver
+keeps the authority to capture and to act. A stale or reused screen is refused
+instead of guessed at.
+
+### What it contains
+
+Each release packs local models and a CPU runtime, so parsing needs no GPU and
+no network access.
+
+| Component | Role | License |
+| --- | --- | --- |
+| OmniParser icon detector | Finds icons and controls | AGPL-3.0-only |
+| PP-OCR detector and recognizer | Finds and reads on-screen text | Apache-2.0 |
+| ONNX Runtime (CPU) | Runs the models locally | Shipped with its own notices |
+
+Releases are published as `cua-perception-v<version>` GitHub releases for macOS
+arm64, Linux x64, and Windows x64. Each target has a signed catalog, the
+archive, an SBOM, provenance, a runtime contract, and an install check, plus
+one `SHA256SUMS`. Cua Driver verifies the signed catalog before it installs
+anything, and a verified install reports `publisher-verified`.
+
+<Callout type="warning" title="License precautions">
+ The extension is not MIT licensed. Its OmniParser icon detector is AGPL-3.0-only, and Cua does
+ not relicense it. Installing the extension does not change Cua Driver's MIT license, but
+ redistributing the extension, or offering it to users over a network (for example, inside a
+ hosted product), can require you to provide the AGPL corresponding source. If your organization
+ does not accept AGPL components, skip the extension: Cua Driver keeps working, and
+ `parse_visual_regions` returns `not_installed`. This is not legal advice. See the [third-party
+ notices and
+ precautions](https://github.com/trycua/cua/blob/main/libs/cua-driver/docs/perception-third-party-notices.md#before-you-install-redistribute-or-host-the-extension).
+</Callout>
+
+### Install and speed
+
+Capture, parsing, Cua Driver startup, and update checks never install the
+extension. You inspect a catalog first, then install, check, update, or remove
+the extension with `cua-driver extension` commands. A running Driver picks up
+an install or removal without a restart.
+
+Parsing runs on the CPU. Measured per screenshot on the canonical harnesses:
+about 2 to 2.5 seconds on macOS, 3.5 to 4 seconds on Linux, and 8 to 9 seconds
+on Windows. Prefer accessibility or page targets when they exist, and keep
+perception for surfaces that expose nothing addressable.
+
## How it is validated
A tool returning `ok` is not evidence. Each supported behavior is a cell in one
diff --git a/docs/content/docs/cua-driver/concepts/meta.json b/docs/content/docs/cua-driver/concepts/meta.json
index 706f1cba5e..3aa6fbe5c1 100644
--- a/docs/content/docs/cua-driver/concepts/meta.json
+++ b/docs/content/docs/cua-driver/concepts/meta.json
@@ -2,7 +2,6 @@
"title": "Concepts",
"pages": [
"how-cua-driver-works",
- "perception-extension",
"platform-support"
]
}
diff --git a/docs/content/docs/cua-driver/concepts/perception-extension.mdx b/docs/content/docs/cua-driver/concepts/perception-extension.mdx
deleted file mode 100644
index de1b077c4d..0000000000
--- a/docs/content/docs/cua-driver/concepts/perception-extension.mdx
+++ /dev/null
@@ -1,106 +0,0 @@
----
-title: 'Perception extension'
-description: 'How the optional cua-perception extension turns one screenshot into regions an agent can act on, and how Cua Driver binds every resulting action to that exact screenshot.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-The perception extension lets an agent act on what it can see in a window when
-the application exposes no usable target. It turns one screenshot into
-labelled regions (text, icons, controls), and Cua Driver acts on exactly the
-region the agent chose, bound to the screenshot it came from.
-
-It is optional and runs entirely on the local machine. Cua Driver works without
-it: the accessibility tree and typed browser state remain the first choice for
-finding a target.
-
-## When it helps
-
-Many interfaces hide their targets. Canvas apps, custom-drawn views, games,
-remote desktops, and some web pages have no useful accessibility tree or page
-structure, so an agent has nothing to address by role or label. The extension
-gives those surfaces a structure without sending screenshots to a remote model.
-
-Every [`get_window_state`](/cua-driver/concepts/how-cua-driver-works#observe-tree-and-pixels-together) call
-already returns the accessibility tree and a screenshot together. The extension
-adds one step on top of that observation: it parses the screenshot into
-regions. It does not replace the tree, and it never captures on its own.
-
-## The loop
-
-1. **Capture.** `get_window_state` captures the exact window and returns a
- `capture_id` with the screenshot.
-2. **Parse.** `parse_visual_regions` turns that screenshot into typed regions
- with bounds and, for text, the recognized words.
-3. **Choose.** The agent, or an external chooser such as a decision model,
- selects one region.
-4. **Act.** Cua Driver clicks the region using the same `capture_id`, trying
- background delivery first.
-5. **Reobserve.** The agent takes a fresh capture to confirm the result before
- the next step.
-
-Without the extension installed, `parse_visual_regions` returns
-`not_installed`, and agents continue with the accessibility tree or page
-structure. Nothing is downloaded automatically.
-
-## Every action is bound to one screenshot
-
-A region only means something on the screen it was found on. Cua Driver
-therefore ties each perception-based action to its capture:
-
-| Situation | Result |
-| --- | --- |
-| The click carries the `capture_id` of the screenshot the region came from | Delivered |
-| The same capture is reused for another action | Refused with `capture_not_found` |
-| The capture is older than 60 seconds | Refused with `capture_expired` |
-
-Agents receive region bounds and text, never screenshot bytes, and Cua Driver
-keeps the authority to capture and to act. A stale or reused screen is refused
-instead of guessed at.
-
-## What the extension contains
-
-Each release packs local models and a CPU runtime, so parsing needs no GPU and
-no network access.
-
-| Component | Role | License |
-| --- | --- | --- |
-| OmniParser icon detector | Finds icons and controls | AGPL-3.0-only |
-| PP-OCR detector and recognizer | Finds and reads on-screen text | Apache-2.0 |
-| ONNX Runtime (CPU) | Runs the models locally | Shipped with its own notices |
-
-Releases are published as `cua-perception-v<version>` GitHub releases for macOS
-arm64, Linux x64, and Windows x64. Each target has a signed catalog, the
-archive, an SBOM, provenance, a runtime contract, and an install check, plus
-one `SHA256SUMS`. Cua Driver verifies the signed catalog before it installs
-anything, and a verified install reports `publisher-verified`.
-
-<Callout type="warning" title="License precautions">
- The extension is not MIT licensed. Its OmniParser icon detector is AGPL-3.0-only, and Cua does
- not relicense it. Installing the extension does not change Cua Driver's MIT license, but
- redistributing the extension, or offering it to users over a network (for example, inside a
- hosted product), can require you to provide the AGPL corresponding source. If your organization
- does not accept AGPL components, skip the extension: Cua Driver keeps working, and
- `parse_visual_regions` returns `not_installed`. This is not legal advice. See the [third-party
- notices and
- precautions](https://github.com/trycua/cua/blob/main/libs/cua-driver/docs/perception-third-party-notices.md#before-you-install-redistribute-or-host-the-extension).
-</Callout>
-
-## Install is always explicit
-
-Capture, parsing, Cua Driver startup, and update checks never install the
-extension. You inspect a catalog first and then install, check, update, or
-remove the extension with `cua-driver extension` commands. A running Driver
-picks up an install or removal without a restart.
-
-## Performance
-
-Parsing runs on the CPU. Measured per screenshot on the canonical harnesses:
-about 2–2.5 seconds on macOS, 3.5–4 seconds on Linux, and 8–9 seconds on
-Windows. Prefer accessibility or page targets when they exist, and reserve
-perception for surfaces that expose nothing addressable.
-
-## Related pages
-
-- [Parse visual regions](/cua-driver/guides/visual-regions): install the extension, run the loop step by step, and let a decision model such as jev-use choose among regions.
-- [How Cua Driver works](/cua-driver/concepts/how-cua-driver-works): how observation, action rungs, and delivery fit together.
diff --git a/docs/content/docs/cua-driver/guides/connect-your-agent.mdx b/docs/content/docs/cua-driver/guides/connect-your-agent.mdx
index a67f26f159..ce2ad22b0d 100644
--- a/docs/content/docs/cua-driver/guides/connect-your-agent.mdx
+++ b/docs/content/docs/cua-driver/guides/connect-your-agent.mdx
@@ -1,6 +1,6 @@
---
title: Connect your agent
-description: Register Cua Driver with Claude Code, Codex, Cursor, Hermes, OpenClaw, local models, and agent SDKs.
+description: Register Cua Driver with Claude Code, Codex, Cursor, Hermes, OpenClaw, Gemini, local models, and agent SDKs.
---
import { Callout } from 'fumadocs-ui/components/callout';
@@ -31,7 +31,7 @@ cua-driver mcp-config --client <client>
| Claude Code | `claude mcp add --transport stdio cua-driver -- cua-driver mcp`, or `--client claude` for the computer-use compatibility profile | Install the skill for native skill activation. |
| Codex (CLI, IDE, app) | `--client codex`, which prints `codex mcp add cua-driver -- <path> mcp` | Codex's own approval policy also applies. |
| Cursor | `--client cursor`; paste into `~/.cursor/mcp.json` or `.cursor/mcp.json` | |
-| Antigravity CLI (Gemini) | `--client antigravity`; merge into `~/.gemini/config/mcp_config.json` | `--client gemini` is a legacy alias. Building on the Gemini API directly? See [Computer use with Gemini](/cua-driver/guides/gemini). |
+| Antigravity CLI (Gemini) | `--client antigravity`; merge into `~/.gemini/config/mcp_config.json` | `--client gemini` is a legacy alias. Building on the Gemini API directly? See [Gemini](#gemini). |
| OpenClaw | `--client openclaw`, which prints `openclaw mcp set cua-driver '{…}'` | On macOS, a gateway-spawned server does not inherit OpenClaw.app's grants. |
| Hermes | Built in: `hermes tools enable computer_use --platform cli`, then `hermes -t computer_use chat` | Repair with `hermes computer-use install` and `doctor`. Do not add a second raw MCP server. |
| Prime Agent | `cua-driver skills install`, then `/reload` and `/skill:cua-driver` | Calls the CLI; no MCP. |
@@ -60,7 +60,7 @@ mcp-config` with no flag):
Model providers map to harnesses: Claude through Claude Code, OpenAI through
Codex, Gemini through Antigravity, Kimi through Kimi
Code, Qwen through Qwen Code. To call Gemini 4 Argon from your own agent
-loop instead, see [Computer use with Gemini](/cua-driver/guides/gemini). MiniMax documents setups for
+loop instead, see [Gemini](#gemini). MiniMax documents setups for
[Codex](https://platform.minimax.io/docs/token-plan/codex) and
[Claude Code](https://platform.minimax.io/docs/token-plan/claude-code).
@@ -109,6 +109,257 @@ Examples in `libs/cua-driver/examples/agent-sdks` (Python and TypeScript):
They remove interactive approval prompts: run only trusted tasks.
+## Gemini
+
+Two ways to use Gemini 4 Argon (`gemini-4-argon`) with Cua Driver: add Cua Driver
+to Antigravity and write no code, or call the Gemini API from your own agent
+loop. Both need Cua Driver 0.35.2 or later on a Mac (check with
+`cua-driver --version`) with the permissions from the
+[Quickstart](/cua-driver/quickstart) granted. Windows and Linux use the same MCP
+server and SDKs: change "macOS apps" in the system instruction below to your
+platform.
+
+In each recording, Gemini works in the Mac apps on the left while a person
+types a long message into a chat app on the right with a real keyboard. The bar
+at the bottom counts the keystrokes the chat app received against the ones that
+were typed. The middle of each clip is sped up.
+
+<VideoDemo
+ src="https://github.com/user-attachments/assets/70e9cc74-0020-43cd-b974-3fb930288ec9"
+ poster="https://github.com/user-attachments/assets/619dc845-2af0-464e-8a03-b7ce945edec4"
+ title="Gemini 4 Argon turns a whiteboard photo into a Keynote deck with Cua Driver"
+>
+ Whiteboard photo to Keynote. Gemini read a photo of a hand-drawn product plan
+ in Preview and built a three-slide deck in Keynote: a title slide, the three
+ phases (skipping the crossed-out items), and a diagram of the system flow. The
+ run took about 8 minutes and 173 tool calls. All 2,541 of the person's
+ keystrokes reached the chat app.
+</VideoDemo>
+
+<VideoDemo
+ src="https://github.com/user-attachments/assets/28b57899-5681-4a64-8fca-f70762e5c95c"
+ poster="https://github.com/user-attachments/assets/84058332-45e0-49dd-a736-428ef4fd93d8"
+ title="Gemini 4 Argon summarizes a dashboard into Notes with Cua Driver"
+>
+ Dashboard to Notes. Gemini read a dense metrics dashboard in Preview, picked
+ the three largest changes from the previous period, and wrote them into a new
+ note with the old value, the new value, and the change. The run took about a
+ minute. All 503 keystrokes reached the chat app.
+</VideoDemo>
+
+<VideoDemo
+ src="https://github.com/user-attachments/assets/358b5547-2d38-4868-ba28-91e90b3c41b7"
+ poster="https://github.com/user-attachments/assets/38cb5c14-121f-42c5-a642-b4e92d8a59f9"
+ title="Gemini 4 Argon enters expenses into a native app with Cua Driver"
+>
+ Expenses into Ledger, a small native app with no scripting interface. Gemini
+ entered eight expenses through the app's form fields, and the app's total
+ matched the expected $3,271.29. The run took under two minutes. All 722
+ keystrokes reached the chat app.
+</VideoDemo>
+
+### With Antigravity, no code
+
+[Antigravity](https://antigravity.google/docs/home) runs agents on Gemini and
+supports local MCP servers. Gemini 4 Argon in Antigravity is available to Google
+AI Ultra subscribers. These steps use the Antigravity CLI, `agy`; the desktop
+app and IDE read the same MCP configuration.
+
+```bash skip="host-install"
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+```
+
+Add Cua Driver as an MCP server. This writes it to
+`~/.gemini/config/mcp_config.json`.
+
+```bash skip="third-party-cli"
+agy mcp add cua-driver "$(command -v cua-driver)" mcp
+agy mcp list
+```
+
+```text output
+NAME TYPE STATUS COMMAND/URL
+cua-driver stdio enabled /Users/you/.local/bin/cua-driver mcp
+```
+
+To approve Cua Driver's tools once instead of on every call, add an allow rule
+to `~/.gemini/antigravity-cli/settings.json`:
+
+```json test="config" id="gemini-agy-settings"
+{
+ "permissions": {
+ "allow": ["mcp(cua-driver/*)"]
+ }
+}
+```
+
+Start `agy`, choose Gemini 4 Argon, and give it a task. Name the tools you want
+and say that someone is using the computer:
+
+```text output
+Use only the cua-driver tools. In Contacts, open Daniel Reyes and add this note
+to his card: "Met at the Design Systems Meetup booth." Save the card. Work in
+the background; I'm using the computer.
+```
+
+To run without the interactive interface, use print mode. Antigravity cannot
+ask you to approve a tool in print mode, so it denies any tool your allow list
+does not cover, such as shell commands.
+
+```bash skip="third-party-cli"
+agy -p "Use only the cua-driver tools. List the windows that are open right now."
+```
+
+### From your own agent loop
+
+To control the prompt, the tool set, and the loop, call the Gemini
+[Interactions API](https://ai.google.dev/gemini-api/docs/interactions) from your
+own process and run each tool call through Cua Driver. You need a Gemini API key
+from [Google AI Studio](https://aistudio.google.com/apikey) on a paid tier
+(Gemini 4 Argon is not on the free tier), and Python 3.10+ or Node.js 20+.
+
+![The agent loop: your script sends Gemini the task and Cua Driver's tool declarations, runs each function call through Cua Driver, and sends the result back until Gemini answers.](https://github.com/user-attachments/assets/bdfff431-0f7f-440c-867a-2905fbda4a98)
+
+The loop has three parts:
+
+- **Tool declarations.** `list_tools_json()` returns each tool with a JSON
+ Schema, which Gemini accepts as a function declaration unchanged.
+- **Tool calls.** `call_tool(name, arguments_json)` runs one tool and returns a
+ summary, structured details such as window IDs and element tokens, and
+ screenshots.
+- **Results.** Send each result back as a `function_result` with text and image
+ parts. Include the structured details: the window IDs and element tokens the
+ model needs next are there, not in the summary.
+
+`CuaDriver.connect(None)` attaches to the Cua Driver service you started. That
+service holds the macOS permissions, so the terminal that runs the script does
+not need them, and it draws the agent's own cursor on screen. This Python
+version uses `pip install google-genai "cua-driver>=0.35.2"` and
+`GEMINI_API_KEY`. The TypeScript SDK has the same calls (`listToolsJson`,
+`callTool`) with `@google/genai` and `@trycua/cua-driver`.
+
+```python skip="no-runner"
+import asyncio, json, os, time
+
+from cua_driver import CuaDriver
+from google import genai
+
+MODEL = os.environ.get("GEMINI_MODEL", "gemini-4-argon")
+
+# launch_app and invoke_menu are left out because both can bring an app to the front.
+TOOLS = {"list_apps", "list_windows", "get_window_state", "click", "type_text",
+ "set_value", "press_key", "hotkey", "scroll", "verify_state",
+ "run_steps", "run_script"}
+
+SYSTEM_INSTRUCTION = """\
+You operate macOS apps through Cua Driver tools while the user keeps working on
+the same computer. Stay in the background: do not bring windows to the front.
+Before acting on a window, call get_window_state(pid, window_id) and use the
+element_token values from that snapshot; take a fresh snapshot after any change.
+Prefer accessibility actions over pixel coordinates. When the task is done,
+reply with a short summary and call no more tools."""
+
+TIMEOUT_S = 20 * 60 # One Gemini call can take several minutes.
+
+
+async def run(task: str, max_turns: int = 200) -> str:
+ client = genai.Client()
+ driver = CuaDriver.connect(None) # the Cua Driver service started earlier
+ session = f"gemini-{int(time.time())}"
+
+ async def call_tool(name: str, args: dict):
+ return await driver.call_tool(name, json.dumps(args))
+
+ try:
+ await call_tool("start_session", {"session": session})
+ await call_tool("set_agent_cursor_enabled", {"session": session, "enabled": True})
+
+ catalog = json.loads(await driver.list_tools_json())["tools"]
+ tools = [
+ {"type": "function", "name": t["name"], "description": t["description"],
+ "parameters": t["inputSchema"]}
+ for t in catalog if t["name"] in TOOLS
+ ]
+ takes_session = {
+ t["name"] for t in catalog if "session" in t["inputSchema"].get("properties", {})
+ }
+ request = dict(
+ model=MODEL, tools=tools, system_instruction=SYSTEM_INSTRUCTION,
+ generation_config={"thinking_level": "low", "max_output_tokens": 65536},
+ timeout=TIMEOUT_S,
+ )
+ interaction = await client.aio.interactions.create(input=task, **request)
+
+ for _ in range(max_turns):
+ calls = [s for s in interaction.steps or [] if s.type == "function_call"]
+ if not calls:
+ return interaction.output_text or ""
+
+ results = []
+ for call in calls:
+ args = dict(call.arguments)
+ if call.name in takes_session:
+ args["session"] = session
+ result = await call_tool(call.name, args)
+ content = [{"type": "text", "text": result.text or "ok"}]
+ if result.structured_json: # window IDs, element tokens and other details
+ content.append({"type": "text", "text": result.structured_json})
+ content += [
+ {"type": "image", "mime_type": i.mime_type, "data": i.data_base64}
+ for i in result.images
+ ]
+ results.append({"type": "function_result", "name": call.name,
+ "call_id": call.id, "result": content,
+ "is_error": result.is_error})
+
+ interaction = await client.aio.interactions.create(
+ input=results, previous_interaction_id=interaction.id, **request
+ )
+ return f"Stopped after {max_turns} turns."
+ finally:
+ await call_tool("end_session", {"session": session})
+ await driver.shutdown()
+
+
+print(asyncio.run(run("Add each person in signups.pdf (open in Preview) to Contacts")))
+```
+
+Open the apps the task needs before you run it. Keep working in another app
+while it runs.
+
+Settings that follow Google's
+[Gemini 4 Argon guidance](https://ai.google.dev/gemini-api/docs/latest-model):
+
+- **Use `thinking_level`, not `thinking_budget`.** Argon accepts `low`,
+ `medium`, and `high`. Most UI steps are routine, so `low` keeps the loop
+ responsive. Raise it when a task needs real planning.
+- **Set `max_output_tokens` to 65,536.** A low limit can stop the model before
+ it finishes thinking.
+- **Allow long HTTP timeouts.** Google recommends at least 15 minutes per
+ request. Give the whole task its own wall-clock budget instead of a short
+ per-call limit.
+- **Leave out sampling parameters.** Argon ignores `temperature`, `top_p`, and
+ `top_k`.
+- **Pass thought signatures back unchanged.** With `previous_interaction_id`,
+ the server keeps them. If you keep history yourself (`store=False`), resend
+ every model step exactly as you received it.
+
+Tips for long tasks:
+
+- With `previous_interaction_id`, every snapshot stays in the conversation, and
+ a large window can return tens of thousands of tokens per snapshot. For long
+ tasks, keep history yourself and drop old snapshots and screenshots.
+- Call `get_window_state` with `include_screenshot: false` when the agent only
+ needs fresh element tokens.
+- Offer about a dozen tools, not all 50. Add the `browser_*` tools when the
+ task is in a web page.
+- Run unattended agents in a separate macOS user account or a
+ [VM](/cua-driver/guides/vms-and-remote), and keep purchases, messages,
+ deletions, and credentials out of unattended tasks.
+
+For Google's built-in computer use tool, see the
+[computer use reference](https://ai.google.dev/gemini-api/docs/computer-use).
+
## Local models
Tested: Meta's Muse Glimmer 30B with Claude Code as the harness, served by
diff --git a/docs/content/docs/cua-driver/guides/cursor-motion.mdx b/docs/content/docs/cua-driver/guides/cursor-motion.mdx
deleted file mode 100644
index 8d69224795..0000000000
--- a/docs/content/docs/cua-driver/guides/cursor-motion.mdx
+++ /dev/null
@@ -1,189 +0,0 @@
----
-title: Design cursor motions
-description: Cua Cursor Motion, the open-source library behind Cua Driver's agent cursor. Plan the six motions, design your own, and play them on a web page.
----
-
-Cua Driver moves its agent cursor with **Cua Cursor Motion**, an MIT-licensed
-library you can use on its own. It comes in two packages that give the same
-trajectories:
-
-- `cua-cursor-motion` (`libs/cua-driver/rust/crates/cua-cursor-motion`),
- the Rust crate the driver plans every move with;
-- `@trycua/cursor-motion` (`libs/typescript/cursor-motion`), a TypeScript
- port with a canvas player that draws the Cua cursor.
-
-Both are tested against the same golden trajectories, so a motion you tune on
-a web page plays the same way in the driver.
-
-## Use it from the repository
-
-Cua Cursor Motion is not published to crates.io or npm. Use it straight from
-[trycua/cua](https://github.com/trycua/cua).
-
-In Rust, add a git dependency. Cargo finds the crate inside the repository:
-
-```toml skip="no-runner"
-[dependencies]
-cua-cursor-motion = { git = "https://github.com/trycua/cua" }
-```
-
-On the web, build the single-file ES module once and copy it with its types
-into your project:
-
-```bash skip="host-install"
-git clone --depth 1 https://github.com/trycua/cua
-cd cua/libs/typescript
-pnpm install
-pnpm --filter @trycua/cursor-motion build
-cp cursor-motion/dist/index.js ../../../my-app/src/vendor/cua-cursor-motion.js
-cp cursor-motion/dist/index.d.ts ../../../my-app/src/vendor/cua-cursor-motion.d.ts
-```
-
-The file has no imports, so it also loads from a plain
-`<script type="module">`. In a TypeScript project with a bundler you can copy
-`libs/typescript/cursor-motion/src/` instead.
-
-## From the Cua Driver SDKs
-
-The Cua Driver SDKs export the planner through the same UniFFI boundary as
-the rest of the driver, so Python and TypeScript hosts plan moves with the
-Rust code itself. A planned move is a `CursorTrajectory`: read its samples
-once with `samples()` and interpolate locally each frame.
-
-```python skip="no-runner"
-import cua_driver as cd
-
-params = cd.default_cursor_motion_params()
-params.style = cd.CursorMotionStyle.SPRING_SETTLE
-trajectory = cd.plan_cursor_move(
- params,
- cd.CursorMoveRequest(
- from_point=cd.CursorMotionPoint(x=100, y=100),
- to_point=cd.CursorMotionPoint(x=700, y=400),
- from_heading=None,
- end_heading=None,
- target=cd.CursorMotionRect(x=660, y=380, width=80, height=40),
- seed="demo",
- reduced_motion=False,
- ),
-)
-samples = trajectory.samples()
-```
-
-```ts skip="no-runner"
-import { CursorMotionStyle, defaultCursorMotionParams, planCursorMove } from '@trycua/cua-driver';
-
-const trajectory = planCursorMove(
- { ...defaultCursorMotionParams(), style: CursorMotionStyle.SpringSettle },
- {
- fromPoint: { x: 100, y: 100 },
- toPoint: { x: 700, y: 400 },
- target: { x: 660, y: 380, width: 80, height: 40 },
- seed: 'demo',
- reducedMotion: false,
- }
-);
-const samples = trajectory.samples();
-```
-
-`plan_cursor_spec` takes a custom `CursorMotionSpec`, and
-`CursorTrajectory.effect_frame(t, blend)` returns the trail, glow and magnet to
-paint. For a web page without the native library, use the single-file web port
-(see [Use it from the repository](#use-it-from-the-repository)).
-
-## Plan a move
-
-A move is planned once, as samples at 120 Hz, then played back by time. It
-takes a style (`signature_arc`, `spring_settle`, `magnetic`, `comet_swoop`,
-`adaptive` or `classic`), a timing mode (`native`, `fitts` or `fixed`) and
-the shape knobs of `set_agent_cursor_motion`.
-
-```ts skip="no-runner"
-import { planMove } from './vendor/cua-cursor-motion.js';
-
-const trajectory = planMove(
- { style: 'spring_settle', timing: 'fitts' },
- { from: { x: 100, y: 100 }, to: { x: 700, y: 400 }, target: [660, 380, 80, 40] }
-);
-const { x, y, heading } = trajectory.sampleAt(0.3);
-```
-
-```rust skip="no-runner"
-use cua_cursor_motion::{plan_move, MotionParams, MotionStyle, MotionTiming, MoveRequest, Pt};
-
-let params = MotionParams { style: MotionStyle::SpringSettle, timing: MotionTiming::Fitts, ..Default::default() };
-let request = MoveRequest {
- target: Some([660.0, 380.0, 80.0, 40.0]),
- ..MoveRequest::new(Pt::new(100.0, 100.0), Pt::new(700.0, 400.0))
-};
-let sample = plan_move(&params, &request).sample_at(0.3);
-```
-
-`arrivalT` (`arrival_t` in Rust) is when the tip first reaches the target.
-Cua Driver clicks then and lets any follow-through or bounce finish during the
-click. The target rect sets the Fitts width: smaller targets take longer.
-
-## Play it on a web page
-
-`MotionPlayer` draws the Cua cursor, its glow, the comet trail and the click
-ripple inside a `<canvas>`. It never moves, hides or restyles the page's own
-mouse pointer.
-
-```ts skip="no-runner"
-import { MotionPlayer } from './vendor/cua-cursor-motion.js';
-
-const player = new MotionPlayer(document.querySelector('canvas')!);
-player.place({ x: 80, y: 300 });
-await player.moveTo(
- { x: 640, y: 120 },
- { params: { style: 'comet_swoop' }, target: [600, 104, 80, 32], click: true }
-);
-```
-
-## Design your own motion
-
-A custom motion is a `MotionSpec`: a path shape (`straight`, `arc`, `bow`), a
-speed curve (named easings or `cubic_bezier`), an overshoot or settle
-(`follow_through`, `spring`), a duration model (`fitts`, `fixed`, `distance`),
-a heading mode, effects and a trail. `signature_arc`, `spring_settle` and
-`comet_swoop` are specs themselves, so start from one:
-
-```ts skip="no-runner"
-import { planSpec, specForStyle } from './vendor/cua-cursor-motion.js';
-
-const spec = specForStyle('signature_arc')!;
-spec.ease = { type: 'cubic_bezier', x1: 0.3, y1: 0, x2: 0.1, y2: 1 };
-spec.settle = { type: 'follow_through', amount: 0.04, maxPt: 14, at: 0.75 };
-spec.effects.trail = true;
-
-const trajectory = planSpec(spec, { from: { x: 100, y: 500 }, to: { x: 900, y: 200 } });
-```
-
-Custom specs play in your own renderer. Cua Driver itself takes one of the six
-styles and its knobs.
-
-## The playground
-
-The playground lets you pick a style, drag the start and end points, tune the
-curve with a live speed plot, and copy the result as TypeScript or as Cua
-Driver config. Run it from a checkout:
-
-```bash skip="host-install"
-cd libs/typescript
-pnpm install
-pnpm --filter @trycua/cursor-motion playground
-```
-
-It opens at `http://127.0.0.1:4173/playground/`. For a built-in style, the
-exported Cua Driver config looks like this:
-
-```bash test="cli-shape" id="cua-driver-design-cursor-motion"
-cua-driver config set cursor.motion.style comet_swoop
-cua-driver config set cursor.motion.timing fitts
-cua-driver cursor motion --session demo --style comet_swoop --timing fitts --effects trail=on
-```
-
-The arc knobs (`arc_size`, `arc_flow`, `start_handle`, `end_handle`) and the
-classic glide's `spring` and `turn_radius` travel only through
-`set_agent_cursor_motion`. See [Choose your cursor](/cua-driver/guides/operate#choose-your-cursor)
-for how saved defaults, `start_session` and per-call settings combine.
diff --git a/docs/content/docs/cua-driver/guides/gemini.mdx b/docs/content/docs/cua-driver/guides/gemini.mdx
deleted file mode 100644
index 4e7dda2099..0000000000
--- a/docs/content/docs/cua-driver/guides/gemini.mdx
+++ /dev/null
@@ -1,567 +0,0 @@
----
-title: Computer use with Gemini
-description: Build a Gemini 4 Argon agent that works in native desktop apps through Cua Driver while you keep using your computer.
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
-
-This guide shows how to build a Gemini agent that operates real desktop apps
-on your computer while you keep working. Cua Driver reads each app through its
-accessibility tree and screenshots, and sends clicks and keystrokes to that app
-in the background, so the agent works while you keep working.
-
-We had early access to Gemini 4 Argon (`gemini-4-argon`) and recorded the demos
-below on the public model with Cua Driver 0.35.2.
-
-You can connect Gemini to Cua Driver in two ways:
-
-- **Path A: Antigravity.** Add Cua Driver as an MCP server and let the
- Antigravity agent use it. No code.
-- **Path B: your own agent loop.** Use the `google-genai` SDK and the Cua Driver
- SDK to turn Cua Driver's tools into Gemini function declarations. About 150
- lines of Python or TypeScript.
-
-## See it work
-
-In each recording, Gemini works in the Mac apps on the left while a person
-types a long message into a chat app on the right with a real keyboard. The bar
-at the bottom counts the keystrokes the chat app received against the ones that
-were typed. The middle of each clip is sped up.
-
-<VideoDemo
- src="https://github.com/user-attachments/assets/70e9cc74-0020-43cd-b974-3fb930288ec9"
- poster="https://github.com/user-attachments/assets/619dc845-2af0-464e-8a03-b7ce945edec4"
- title="Gemini 4 Argon turns a whiteboard photo into a Keynote deck with Cua Driver"
->
- Whiteboard photo to Keynote. Gemini read a photo of a hand-drawn product plan
- in Preview and built a three-slide deck in Keynote: a title slide, the three
- phases (skipping the crossed-out items), and a diagram of the system flow. The
- run took about 8 minutes and 173 tool calls. All 2,541 of the person's
- keystrokes reached the chat app.
-</VideoDemo>
-
-<VideoDemo
- src="https://github.com/user-attachments/assets/28b57899-5681-4a64-8fca-f70762e5c95c"
- poster="https://github.com/user-attachments/assets/84058332-45e0-49dd-a736-428ef4fd93d8"
- title="Gemini 4 Argon summarizes a dashboard into Notes with Cua Driver"
->
- Dashboard to Notes. Gemini read a dense metrics dashboard in Preview, picked
- the three largest changes from the previous period, and wrote them into a new
- note with the old value, the new value, and the change. The run took about a
- minute. All 503 keystrokes reached the chat app.
-</VideoDemo>
-
-<VideoDemo
- src="https://github.com/user-attachments/assets/358b5547-2d38-4868-ba28-91e90b3c41b7"
- poster="https://github.com/user-attachments/assets/38cb5c14-121f-42c5-a642-b4e92d8a59f9"
- title="Gemini 4 Argon enters expenses into a native app with Cua Driver"
->
- Expenses into Ledger, a small native app with no scripting interface. Gemini
- entered eight expenses through the app's form fields, and the app's total
- matched the expected $3,271.29. The run took under two minutes. All 722
- keystrokes reached the chat app.
-</VideoDemo>
-
-## Before you begin
-
-You need:
-
-- A Mac with macOS 14 or later. For Windows and Linux, see
- [Next steps](#next-steps).
-- For Path A, Antigravity. Gemini 4 Argon in Antigravity is available to
- Google AI Ultra subscribers.
-- For Path B, a Gemini API key from
- [Google AI Studio](https://aistudio.google.com/apikey) on a paid tier
- (Gemini 4 Argon is not on the free tier), and Python 3.10 or later or
- Node.js 20 or later.
-
-### Install Cua Driver
-
-**1. Install Cua Driver and start its background service:**
-
-```bash test="cli-shape" id="gemini-install"
-/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
-open -n -g -a CuaDriver --args serve
-cua-driver permissions grant
-```
-
-When macOS asks, choose **Open System Settings** and turn on **CuaDriver**
-under **Accessibility** and **Screen & System Audio Recording**.
-
-**2. Check the result:**
-
-```bash test="cli-shape" id="gemini-check"
-cua-driver --version
-cua-driver permissions status
-```
-
-The version should be 0.35.2 or later, and both **Accessibility** and
-**Screen Recording** should show as granted.
-
-## Path A: Antigravity with Cua Driver
-
-[Antigravity](https://antigravity.google/docs/home) runs agents on Gemini and
-supports local MCP servers. These steps use the Antigravity CLI, `agy`. The
-Antigravity desktop app and IDE read the same MCP configuration.
-
-**1. Install the Antigravity CLI:**
-
-```bash skip="host-install"
-curl -fsSL https://antigravity.google/cli/install.sh | bash
-```
-
-**2. Add Cua Driver as an MCP server:**
-
-```bash skip="third-party-cli"
-agy mcp add cua-driver "$(command -v cua-driver)" mcp
-agy mcp list
-```
-
-```text output
-NAME TYPE STATUS COMMAND/URL
-cua-driver stdio enabled /Users/you/.local/bin/cua-driver mcp
-```
-
-This writes the server to `~/.gemini/config/mcp_config.json`. To edit that file
-yourself instead, `cua-driver mcp-config --client antigravity` prints the entry
-to paste.
-
-**3. Let the agent use Cua Driver's tools without asking each time.** Add an
-allow rule to `~/.gemini/antigravity-cli/settings.json`:
-
-```json test="config" id="gemini-agy-settings"
-{
- "permissions": {
- "allow": ["mcp(cua-driver/*)"]
- }
-}
-```
-
-Without the rule, Antigravity asks you to approve each tool call.
-
-**4. Start `agy`, choose Gemini 4 Argon as the model, and give it a task.**
-Name the tools you want it to use, and say that someone is using the computer:
-
-```text output
-Use only the cua-driver tools. In Contacts, open Daniel Reyes and add this note
-to his card: "Met at the Design Systems Meetup booth." Save the card. Work in
-the background; I'm using the computer.
-```
-
-To run a task without the interactive interface, use print mode:
-
-```bash skip="third-party-cli"
-agy -p "Use only the cua-driver tools. List the windows that are open right now."
-```
-
-In print mode, Antigravity can't ask you to approve a tool, so it denies any
-tool your allow list doesn't cover, such as shell commands.
-
-## Path B: build your own loop
-
-To control the prompt, the tool set, and the loop yourself, call the Gemini
-[Interactions API](https://ai.google.dev/gemini-api/docs/interactions) and
-connect to Cua Driver from your own process.
-
-![The agent loop: your script sends Gemini the task and Cua Driver's tool declarations, runs each function call through Cua Driver, and sends the result back until Gemini answers.](https://github.com/user-attachments/assets/bdfff431-0f7f-440c-867a-2905fbda4a98)
-
-**1. Install the two SDKs and export your key:**
-
-<Tabs groupId="language" persist items={['Python', 'TypeScript']}>
- <Tab value="Python">
-
-```bash skip="host-install"
-pip install google-genai "cua-driver>=0.35.2"
-export GEMINI_API_KEY="YOUR_API_KEY"
-```
-
- </Tab>
- <Tab value="TypeScript">
-
-```bash skip="host-install"
-npm install @google/genai "@trycua/cua-driver@>=0.35.2" tsx
-export GEMINI_API_KEY="YOUR_API_KEY"
-```
-
- </Tab>
-</Tabs>
-
-**2. Write the agent.** The loop has three parts:
-
-- **Tool declarations.** `list_tools_json()` returns each Cua Driver tool with
- a JSON Schema, which Gemini accepts as a function declaration unchanged.
-- **Tool calls.** `call_tool(name, arguments_json)` runs one tool and returns a
- summary, structured details such as window IDs and element tokens, and
- screenshots.
-- **Results.** Each result goes back to Gemini as a `function_result` with
- text and image parts. Include the structured details: the window IDs and
- element tokens the model needs for its next call are there, not in the
- summary.
-
-The script connects to the Cua Driver service you started with
-`CuaDriver.connect(None)`. The service holds the macOS permissions, so the
-terminal you run the script from doesn't need them, and it draws the agent's
-own cursor on screen so you can follow what the agent does.
-
-<Tabs groupId="language" persist items={['Python', 'TypeScript']}>
- <Tab value="Python">
-
-```python skip="no-runner"
-"""A Gemini agent that operates desktop apps in the background with Cua Driver.
-
- pip install google-genai "cua-driver>=0.35.2"
- export GEMINI_API_KEY=...
- python gemini_cua_agent.py "Add each person in signups.pdf (open in Preview) to Contacts"
-"""
-
-import argparse
-import asyncio
-import json
-import os
-import time
-
-from cua_driver import CuaDriver
-from google import genai
-
-MODEL = os.environ.get("GEMINI_MODEL", "gemini-4-argon")
-
-# A focused subset of Cua Driver's tools. launch_app and invoke_menu are left
-# out because both can bring an app to the front. Batch tools are added when
-# the installed Cua Driver offers them.
-TOOLS = [
- "list_apps",
- "list_windows",
- "get_window_state",
- "click",
- "type_text",
- "set_value",
- "press_key",
- "hotkey",
- "scroll",
- "verify_state",
- "run_steps",
- "run_script",
-]
-
-SYSTEM_INSTRUCTION = """\
-You operate macOS apps through Cua Driver tools while the user keeps working
-on the same computer.
-
-- Stay in the background. Don't bring windows to the front, and keep the
- default background delivery for every action.
-- Find the apps you need with list_apps and list_windows.
-- Before acting on a window, call get_window_state(pid, window_id) and use the
- element_token values from that snapshot. Take a fresh snapshot after any
- change; old tokens go stale.
-- Prefer accessibility actions (element_token, set_value) over pixel
- coordinates.
-- Check the result of each change in a fresh snapshot before moving on.
-- When the task is done, reply with a short summary and call no more tools.
-"""
-
-TIMEOUT_S = 20 * 60 # One Gemini call can take several minutes.
-
-
-def to_function(tool: dict) -> dict:
- """Map one Cua Driver tool to a Gemini function declaration."""
- return {
- "type": "function",
- "name": tool["name"],
- "description": tool["description"],
- "parameters": tool["inputSchema"],
- }
-
-
-def to_result(call, result) -> dict:
- """Map a Cua Driver ToolResult to a Gemini function_result input."""
- content = [{"type": "text", "text": result.text or "ok"}]
- if result.structured_json: # window IDs, element tokens and other details
- content.append({"type": "text", "text": result.structured_json})
- content += [
- {"type": "image", "mime_type": image.mime_type, "data": image.data_base64}
- for image in result.images
- ]
- return {
- "type": "function_result",
- "name": call.name,
- "call_id": call.id,
- "result": content,
- "is_error": result.is_error,
- }
-
-
-async def run(task: str, max_turns: int, thinking_level: str) -> str:
- client = genai.Client()
- driver = CuaDriver.connect(None) # the Cua Driver service started earlier
- session = f"gemini-{int(time.time())}"
-
- async def call_tool(name: str, args: dict):
- return await driver.call_tool(name, json.dumps(args))
-
- try:
- # Show this session's agent cursor while it works.
- await call_tool("start_session", {"session": session})
- await call_tool("set_agent_cursor_enabled", {"session": session, "enabled": True})
-
- catalog = json.loads(await driver.list_tools_json())["tools"]
- tools = [to_function(t) for t in catalog if t["name"] in TOOLS]
- takes_session = {
- t["name"] for t in catalog if "session" in t["inputSchema"].get("properties", {})
- }
-
- request = dict(
- model=MODEL,
- tools=tools,
- system_instruction=SYSTEM_INSTRUCTION,
- generation_config={"thinking_level": thinking_level, "max_output_tokens": 65536},
- timeout=TIMEOUT_S,
- )
- interaction = await client.aio.interactions.create(input=task, **request)
-
- for turn in range(1, max_turns + 1):
- calls = [s for s in interaction.steps or [] if s.type == "function_call"]
- if not calls:
- return interaction.output_text or ""
-
- results = []
- for call in calls:
- args = dict(call.arguments)
- if call.name in takes_session:
- args["session"] = session
- started = time.monotonic()
- result = await call_tool(call.name, args)
- status = "error" if result.is_error else "ok"
- print(f"[{turn}] {call.name} {json.dumps(call.arguments)[:100]} -> {status} "
- f"({time.monotonic() - started:.1f}s)")
- results.append(to_result(call, result))
-
- interaction = await client.aio.interactions.create(
- input=results, previous_interaction_id=interaction.id, **request
- )
- return f"Stopped after {max_turns} turns."
- finally:
- await call_tool("end_session", {"session": session})
- await driver.shutdown()
-
-
-def main() -> None:
- parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
- parser.add_argument("task")
- parser.add_argument("--max-turns", type=int, default=200)
- parser.add_argument("--thinking-level", default="low", choices=["low", "medium", "high"])
- args = parser.parse_args()
- print(asyncio.run(run(args.task, args.max_turns, args.thinking_level)))
-
-
-if __name__ == "__main__":
- main()
-```
-
- </Tab>
- <Tab value="TypeScript">
-
-```ts skip="no-runner"
-// A Gemini agent that operates desktop apps in the background with Cua Driver.
-//
-// npm install @google/genai "@trycua/cua-driver@>=0.35.2" tsx
-// export GEMINI_API_KEY=...
-// npx tsx gemini-cua-agent.ts "Add each person in signups.pdf (open in Preview) to Contacts"
-
-import { GoogleGenAI } from "@google/genai";
-import { CuaDriver } from "@trycua/cua-driver";
-
-const MODEL = process.env.GEMINI_MODEL ?? "gemini-4-argon";
-
-// launch_app and invoke_menu are left out because both can bring an app to
-// the front. Batch tools are used when the installed Cua Driver offers them.
-const TOOLS = new Set([
- "list_apps", "list_windows", "get_window_state",
- "click", "type_text", "set_value", "press_key", "hotkey", "scroll",
- "verify_state", "run_steps", "run_script",
-]);
-
-const SYSTEM_INSTRUCTION = `You operate macOS apps through Cua Driver tools while the user keeps working on the same computer.
-- Stay in the background. Don't bring windows to the front, and keep the default background delivery.
-- Find the apps you need with list_apps and list_windows.
-- Before acting on a window, call get_window_state(pid, window_id) and use element_token values from that snapshot.
-- Prefer accessibility actions (element_token, set_value) over pixel coordinates.
-- Check each change in a fresh snapshot. When done, reply with a short summary and call no more tools.`;
-
-const TIMEOUT_MS = 20 * 60 * 1000; // One Gemini call can take several minutes.
-
-async function run(task: string, maxTurns = 200): Promise<string> {
- const ai = new GoogleGenAI({});
- const driver = CuaDriver.connect(undefined); // the Cua Driver service started earlier
- const session = `gemini-${Math.floor(Date.now() / 1000)}`;
- const callTool = (name: string, args: object) => driver.callTool(name, JSON.stringify(args));
-
- try {
- // Show this session's agent cursor while it works.
- await callTool("start_session", { session });
- await callTool("set_agent_cursor_enabled", { session, enabled: true });
-
- const catalog = JSON.parse(await driver.listToolsJson()).tools as Array<{
- name: string; description: string; inputSchema: { properties?: object };
- }>;
- const takesSession = new Set(
- catalog.filter((t) => "session" in (t.inputSchema.properties ?? {})).map((t) => t.name),
- );
- const tools = catalog
- .filter((t) => TOOLS.has(t.name))
- .map((t) => ({
- type: "function" as const,
- name: t.name,
- description: t.description,
- parameters: t.inputSchema,
- }));
-
- const request = {
- model: MODEL,
- tools,
- system_instruction: SYSTEM_INSTRUCTION,
- generation_config: { thinking_level: "low" as const, max_output_tokens: 65536 },
- };
- let interaction = await ai.interactions.create(
- { ...request, input: task }, { timeout: TIMEOUT_MS },
- );
-
- for (let turn = 1; turn <= maxTurns; turn++) {
- const calls = (interaction.steps ?? []).filter((s) => s.type === "function_call");
- if (calls.length === 0) return interaction.output_text ?? "";
-
- const results = [];
- for (const call of calls) {
- const args = { ...call.arguments, ...(takesSession.has(call.name) ? { session } : {}) };
- const result = await callTool(call.name, args);
- console.log(`[${turn}] ${call.name} ${JSON.stringify(call.arguments).slice(0, 100)} -> ${result.isError ? "error" : "ok"}`);
- results.push({
- type: "function_result" as const,
- name: call.name,
- call_id: call.id,
- is_error: result.isError,
- result: [
- { type: "text" as const, text: result.text || "ok" },
- // window IDs, element tokens and other details
- ...(result.structuredJson ? [{ type: "text" as const, text: result.structuredJson }] : []),
- ...result.images.map((image) => ({
- type: "image" as const,
- mime_type: image.mimeType,
- data: image.dataBase64,
- })),
- ],
- });
- }
- interaction = await ai.interactions.create(
- { ...request, input: results, previous_interaction_id: interaction.id },
- { timeout: TIMEOUT_MS },
- );
- }
- return `Stopped after ${maxTurns} turns.`;
- } finally {
- await callTool("end_session", { session });
- await driver.shutdown();
- // shutdown() drains the runtime; this releases the native handle.
- (driver as unknown as { uniffiDestroy(): void }).uniffiDestroy();
- }
-}
-
-console.log(await run(process.argv[2] ?? "List the apps that are running."));
-```
-
- </Tab>
-</Tabs>
-
-<Callout>
- `CuaDriver.create()` loads Cua Driver into your own process instead. On macOS
- that runtime can't draw the agent cursor and needs its own permission grants.
- A coming release makes `create()` connect to the service automatically on
- macOS ([#5090](https://github.com/trycua/cua/pull/5090)); until then, use
- `connect()` as shown.
-</Callout>
-
-**3. Open the apps and run it.** The script expects the apps it works in to be
-open already. For example, with a PDF of sign-ups open in Preview and Contacts
-open:
-
-```bash skip="no-runner"
-python gemini_cua_agent.py "signups.pdf is open in Preview. Add each person in \
-its table to Contacts as a new contact with their name, company and email. \
-Contacts is already open. Work in the background: I'm typing in another app, so \
-don't bring any window to the front. When you're done, tell me what you added."
-```
-
-Keep working in another app while it runs. Each line the script prints is one
-Cua Driver call. These lines are from the Ledger run above:
-
-```text output
-[1] list_windows {"app": "Ledger"} -> ok (0.0s)
-[2] get_window_state {"window_id": 842, "pid": 16196} -> ok (0.2s)
-[3] run_steps {"window_id": 842, "observe": {"since": null, "include_screenshot": false}, "steps": [{"tool": "set_ -> ok (5.8s)
-[4] run_steps {"window_id": 842, "steps": [{"tool": "set_value", "args": {"element_token": "s00000002:1", "value": -> ok (5.8s)
-```
-
-When Gemini answers without calling a tool, the script prints that answer and
-stops.
-
-## Settings for Gemini 4 Argon
-
-These follow Google's
-[Gemini 4 Argon guidance](https://ai.google.dev/gemini-api/docs/latest-model).
-For Google's built-in computer use tool, see the
-[computer use reference](https://ai.google.dev/gemini-api/docs/computer-use).
-
-- **Use `thinking_level`, not `thinking_budget`.** Argon accepts `low`,
- `medium`, and `high`. Most UI steps are routine, so `low` keeps the loop
- responsive; raise it when a task needs real planning, such as reconciling
- two documents.
-- **Set `max_output_tokens` to 65,536.** A low limit can stop the model before
- it finishes thinking. For outputs past 64K tokens, see
- [Long Decode](https://ai.google.dev/gemini-api/docs/long-decode).
-- **Allow long HTTP timeouts.** Google recommends at least 15 minutes per
- request; the examples use 20. Give the whole task its own wall-clock budget
- instead of a short per-call limit.
-- **Leave out sampling parameters.** Argon ignores `temperature`, `top_p`, and
- `top_k`.
-- **Pass thought signatures back unchanged.** With `previous_interaction_id`,
- the server keeps the conversation, including thoughts and their signatures.
- If you keep history yourself (`store=False`), resend every model step
- exactly as you received it, `thought_signature` included.
-
-## Tips
-
-- **Watch context on long tasks.** With `previous_interaction_id`, every
- snapshot stays in the conversation. A large window such as a Keynote
- document can return tens of thousands of tokens per snapshot, so a long task
- can reach the 1M-token input limit. For long tasks, keep history yourself,
- drop old snapshots and screenshots, and keep the model's steps unchanged.
-- **Keep observations lean.** When the agent only needs fresh element tokens,
- it can call `get_window_state` with `include_screenshot: false`.
-- **Prefer accessibility actions.** `set_value` and clicks by `element_token`
- work on background windows and don't depend on pixel coordinates.
-- **Batch steps.** `run_steps` and `run_script` run several actions in one tool
- call, which cuts round trips to Gemini.
-- **Offer a focused tool set.** Cua Driver has more than 50 tools. The examples
- offer about a dozen for desktop work. Add the `browser_*` tools when the task
- is in a web page.
-- **Keep risky actions supervised.** Run unattended agents in a separate macOS
- user account or a [virtual machine](/cua-driver/guides/vms-and-remote), and
- keep purchases, messages, deletions, and credentials out of unattended
- tasks.
-
-## Next steps
-
-- **Windows and Linux.** Cua Driver runs on Windows 10 and 11 and on x86_64
- Linux desktops (X11 or XWayland, with AT-SPI 2), with the same MCP server and
- SDKs. See the [Quickstart](/cua-driver/quickstart) for the install steps,
- and change "macOS apps" in the system instruction to your platform.
-- **Shared computers for teams.** [Cua Spaces](https://cua.ai/spaces) gives
- your team and its agents shared computers that everyone can watch, so an
- agent can work on a computer other than your own.
-- **Reference.**
- - [Use the SDK](/cua-driver/guides/use-the-sdk) and the
- [MCP tool reference](/cua-driver/reference/mcp-tools)
- - [Antigravity MCP configuration](https://antigravity.google/docs/mcp)
- - [Gemini Interactions API](https://ai.google.dev/gemini-api/docs/interactions),
- [function calling](https://ai.google.dev/gemini-api/docs/function-calling),
- and [computer use](https://ai.google.dev/gemini-api/docs/computer-use)
diff --git a/docs/content/docs/cua-driver/guides/meta.json b/docs/content/docs/cua-driver/guides/meta.json
index 704e3c5746..aec9033f16 100644
--- a/docs/content/docs/cua-driver/guides/meta.json
+++ b/docs/content/docs/cua-driver/guides/meta.json
@@ -2,17 +2,13 @@
"title": "Guides",
"pages": [
"connect-your-agent",
- "use-the-sdk",
- "gemini",
+ "permissions",
"browsers",
"visual-regions",
- "trajectories",
- "permissions",
- "vms-and-remote",
- "test-in-a-sandbox",
"operate",
- "cursor-motion",
- "troubleshoot",
- "recipes"
+ "vms-and-remote",
+ "use-the-sdk",
+ "recipes",
+ "troubleshoot"
]
}
diff --git a/docs/content/docs/cua-driver/guides/operate.mdx b/docs/content/docs/cua-driver/guides/operate.mdx
index 4cbe94d32a..469570b8a9 100644
--- a/docs/content/docs/cua-driver/guides/operate.mdx
+++ b/docs/content/docs/cua-driver/guides/operate.mdx
@@ -1,10 +1,15 @@
---
-title: Keep Cua Driver running and updated
-description: Keep the Cua Driver daemon running, update it, choose a release channel, personalize the agent cursor, and control telemetry.
+title: Operate Cua Driver
+description: Keep the Cua Driver daemon running, update it, choose a release channel, personalize the agent cursor, record what an agent did, and control telemetry.
---
+import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+How to run Cua Driver day to day: keep the daemon up, update it, change how
+the agent cursor looks and moves, record what an agent did, and decide what
+telemetry it sends.
+
## Keep it running
MCP clients on macOS and all one-shot `cua-driver call` commands need a
@@ -417,6 +422,133 @@ short straight glide with no effects, whatever you chose.
Cua Driver has no settings window, so there is no cursor picker in the app. Use
`cua-driver config set` or `start_session`.
+## Record a trajectory
+
+A recording saves every action with its arguments and before-and-after
+screenshots, plus an optional display video. Rendering needs `ffmpeg` on every
+platform; capture also needs it on Windows and Linux (macOS 15+ uses
+ScreenCaptureKit).
+
+<VideoDemo
+ src="https://github.com/user-attachments/assets/9eafceca-1738-4e34-949a-2fb0dbe1832e"
+ poster="https://github.com/user-attachments/assets/d896dd2f-3f0a-4978-93a3-c9a5c562c3e8"
+ title="Turn an agent trajectory into a zoom-on-click demo"
+ sourceUrl="https://x.com/trycua/status/2047383207612645426"
+>
+ The agent clicks cells in a numbered grid, then Cua Driver renders the recorded actions.
+</VideoDemo>
+
+Have your agent call `start_recording` before the task:
+
+```json test="config" id="json-config"
+{
+ "output_dir": "~/cua-trajectories/calendar-demo",
+ "record_video": true
+}
+```
+
+Actions such as `click`, `type_text`, `press_key`, and `scroll` are added
+automatically, one `turn-NNNNN` folder each. Call `stop_recording` with `{}`
+and wait for it: it finalizes `recording.mp4`. Then render:
+
+```bash test="cli-shape" id="cua-driver-recording-render"
+cua-driver recording render \
+ ~/cua-trajectories/calendar-demo \
+ ~/cua-trajectories/calendar-demo.mp4 \
+ --scale 2.5
+```
+
+The renderer zooms around each recorded action; `--scale` sets the strength
+and `--no-zoom` gives a plain render. All options:
+[`cua-driver recording`](/cua-driver/reference/cli) and the
+[recording tools](/cua-driver/reference/mcp-tools).
+
+## Computer History
+
+Computer History keeps an encrypted local record of actions performed through
+Cua Driver, so an agent can pick up where a previous run stopped. It is an
+opt-in preview in nightly builds (see [Channels](#channels)) on macOS, Windows, and Linux, and
+records nothing outside Cua-mediated actions.
+
+```bash test="cli-shape" id="cua-driver-history-enable"
+cua-driver channel set nightly
+cua-driver update --apply
+cua-driver history enable
+cua-driver history status
+```
+
+`enable` creates a key in the macOS Keychain, Windows Credential Manager, or
+Linux Secret Service (which must be unlocked; there is no plaintext fallback)
+and starts capture. Defaults: 7-day retention, 100 MiB quota, no network I/O.
+
+| Command | Effect |
+| --- | --- |
+| `cua-driver history list 50` | Newest 50 events. Add `--json` for scripts. |
+| `cua-driver history show 42` | One event by sequence number. |
+| `cua-driver history pause` / `resume` / `disable` | Stop or restart capture; existing history is kept. |
+| `cua-driver history delete --yes` | Destroy the key and the encrypted store. |
+
+```bash test="cli-shape" id="cua-driver-history-list"
+cua-driver history list 50
+cua-driver history show 42
+cua-driver history pause
+cua-driver history resume
+cua-driver history delete --yes
+```
+
+History stores timestamps, opaque IDs, capability names, app identity, and
+fixed outcome categories. It never stores screenshots, typed text,
+keystrokes, clipboard, tool arguments or results, accessibility trees, file
+paths, window titles, or URLs. Deleting destroys the key; it cannot erase
+backups or snapshots of the ciphertext.
+
+### Let an agent read history
+
+A runtime that admits the preview exposes two read-only tools:
+`history_status` (capability `history.status`) and `history_query`
+(`history.query`, at most 200 events, filters `limit`, `session_id`,
+`since_sequence`, `until_sequence`). Every call passes the normal
+[permission stack](/cua-driver/guides/permissions); a bounded manifest must
+name both:
+
+```yaml test="config" id="yaml-config"
+version: 3
+expires_after: 1h
+idle_timeout: 10m
+resources:
+ computer_history:
+ operations:
+ - status
+ - query
+allow:
+ tools:
+ - history_status
+ - history_query
+```
+
+Having the tools does not make a model use them. For "continue" or "what did I
+do" requests, give the agent a trusted instruction (or run the
+status-then-query preflight in your host) to check history first, treat events
+as metadata, and verify current state before acting. A query that returns
+events appends an encrypted access record. Agents cannot enable, pause,
+delete, or export history.
+
+| Error | Fix |
+| --- | --- |
+| `history_preview_not_admitted` | Restart a development daemon with `cua-driver serve --experimental-history`. |
+| `history_key_locked`, `history_key_unavailable` | Unlock the login keychain or start a Secret Service. |
+| `history_quota_reached` | Delete history; the action that hit the limit still ran. |
+| `history_storage_corrupt` | `cua-driver history delete --yes`, then enable again. |
+
+The event schema (CloudEvents 1.0, `urn:cua-driver:schema:history-event:v0`)
+and storage profile are specified in the
+[agent integration RFC](https://github.com/trycua/cua/blob/main/libs/cua-driver/docs/computer-history-agent-integration-rfc.md).
+
+<Callout type="info">
+ To return to stable: `cua-driver history disable`, `cua-driver channel set stable`,
+ `cua-driver update --apply`. History is kept unless you delete it.
+</Callout>
+
## Telemetry
Cua Driver sends content-free, pseudonymous usage events to PostHog's EU
diff --git a/docs/content/docs/cua-driver/guides/recipes.mdx b/docs/content/docs/cua-driver/guides/recipes.mdx
index 592970f88a..32d9a0ce4a 100644
--- a/docs/content/docs/cua-driver/guides/recipes.mdx
+++ b/docs/content/docs/cua-driver/guides/recipes.mdx
@@ -1,6 +1,6 @@
---
title: Recipes
-description: Real desktop workflows with Cua Driver, each with the prompt to give your agent and how to check the result.
+description: Real desktop workflows with Cua Driver, each with the prompt to give your agent and how to check the result. The last section shows how to design your own cursor motion.
---
Each recipe assumes Cua Driver is installed and connected to your agent
@@ -279,3 +279,161 @@ field from the PDF, and submit the form.
Watch the field mapping and correct it in plain language ("use the resume
email for Work Email").
+
+## Design a cursor motion
+
+This one is for developers, not agents. Cua Driver plans every agent cursor
+move with **Cua Cursor Motion**, an MIT-licensed library you can use on its
+own. It comes in two packages that produce the same trajectories:
+
+- `cua-cursor-motion` (`libs/cua-driver/rust/crates/cua-cursor-motion`), the
+ Rust crate the driver plans every move with;
+- `@trycua/cursor-motion` (`libs/typescript/cursor-motion`), a TypeScript port
+ with a canvas player that draws the Cua cursor.
+
+Both are tested against the same golden trajectories, so a motion you tune on a
+web page plays the same way in the driver. Neither is published to crates.io or
+npm. Use them from [trycua/cua](https://github.com/trycua/cua).
+
+In Rust, add a git dependency. Cargo finds the crate inside the repository:
+
+```toml skip="no-runner"
+[dependencies]
+cua-cursor-motion = { git = "https://github.com/trycua/cua" }
+```
+
+On the web, build the single-file ES module once and copy it with its types
+into your project. The file has no imports, so it also loads from a plain
+`<script type="module">`.
+
+```bash skip="host-install"
+git clone --depth 1 https://github.com/trycua/cua
+cd cua/libs/typescript
+pnpm install
+pnpm --filter @trycua/cursor-motion build
+cp cursor-motion/dist/index.js ../../../my-app/src/vendor/cua-cursor-motion.js
+cp cursor-motion/dist/index.d.ts ../../../my-app/src/vendor/cua-cursor-motion.d.ts
+```
+
+### Plan a move
+
+A move is planned once, as samples at 120 Hz, then played back by time. It
+takes a style (`signature_arc`, `spring_settle`, `magnetic`, `comet_swoop`,
+`adaptive`, or `classic`), a timing mode (`native`, `fitts`, or `fixed`), and
+the shape knobs of `set_agent_cursor_motion`.
+
+```ts skip="no-runner"
+import { planMove } from './vendor/cua-cursor-motion.js';
+
+const trajectory = planMove(
+ { style: 'spring_settle', timing: 'fitts' },
+ { from: { x: 100, y: 100 }, to: { x: 700, y: 400 }, target: [660, 380, 80, 40] }
+);
+const { x, y, heading } = trajectory.sampleAt(0.3);
+```
+
+```rust skip="no-runner"
+use cua_cursor_motion::{plan_move, MotionParams, MotionStyle, MotionTiming, MoveRequest, Pt};
+
+let params = MotionParams { style: MotionStyle::SpringSettle, timing: MotionTiming::Fitts, ..Default::default() };
+let request = MoveRequest {
+ target: Some([660.0, 380.0, 80.0, 40.0]),
+ ..MoveRequest::new(Pt::new(100.0, 100.0), Pt::new(700.0, 400.0))
+};
+let sample = plan_move(&params, &request).sample_at(0.3);
+```
+
+`arrivalT` (`arrival_t` in Rust) is when the tip first reaches the target. Cua
+Driver clicks then and lets any follow-through or bounce finish during the
+click. The target rectangle sets the Fitts width: smaller targets take longer.
+
+The Cua Driver Python and TypeScript SDKs export the same planner through the
+driver's native boundary (`plan_cursor_move` and `planCursorMove`), so a host
+can plan moves with the Rust code itself. A planned move is a
+`CursorTrajectory`: read its samples once with `samples()` and interpolate
+locally each frame.
+
+```python skip="no-runner"
+import cua_driver as cd
+
+params = cd.default_cursor_motion_params()
+params.style = cd.CursorMotionStyle.SPRING_SETTLE
+trajectory = cd.plan_cursor_move(
+ params,
+ cd.CursorMoveRequest(
+ from_point=cd.CursorMotionPoint(x=100, y=100),
+ to_point=cd.CursorMotionPoint(x=700, y=400),
+ from_heading=None,
+ end_heading=None,
+ target=cd.CursorMotionRect(x=660, y=380, width=80, height=40),
+ seed="demo",
+ reduced_motion=False,
+ ),
+)
+samples = trajectory.samples()
+```
+
+### Play it on a web page
+
+`MotionPlayer` draws the Cua cursor, its glow, the comet trail, and the click
+ripple inside a `<canvas>`. It never moves, hides, or restyles the page's own
+mouse pointer.
+
+```ts skip="no-runner"
+import { MotionPlayer } from './vendor/cua-cursor-motion.js';
+
+const player = new MotionPlayer(document.querySelector('canvas')!);
+player.place({ x: 80, y: 300 });
+await player.moveTo(
+ { x: 640, y: 120 },
+ { params: { style: 'comet_swoop' }, target: [600, 104, 80, 32], click: true }
+);
+```
+
+### Design your own motion
+
+A custom motion is a `MotionSpec`: a path shape (`straight`, `arc`, `bow`), a
+speed curve (named easings or `cubic_bezier`), an overshoot or settle
+(`follow_through`, `spring`), a duration model (`fitts`, `fixed`, `distance`), a
+heading mode, effects, and a trail. `signature_arc`, `spring_settle`, and
+`comet_swoop` are specs themselves, so start from one:
+
+```ts skip="no-runner"
+import { planSpec, specForStyle } from './vendor/cua-cursor-motion.js';
+
+const spec = specForStyle('signature_arc')!;
+spec.ease = { type: 'cubic_bezier', x1: 0.3, y1: 0, x2: 0.1, y2: 1 };
+spec.settle = { type: 'follow_through', amount: 0.04, maxPt: 14, at: 0.75 };
+spec.effects.trail = true;
+
+const trajectory = planSpec(spec, { from: { x: 100, y: 500 }, to: { x: 900, y: 200 } });
+```
+
+Custom specs play in your own renderer. Cua Driver itself takes one of the six
+styles and its knobs.
+
+### Try it in the playground
+
+The playground lets you pick a style, drag the start and end points, tune the
+curve with a live speed plot, and copy the result as TypeScript or as Cua
+Driver config. Run it from a checkout; it opens at
+`http://127.0.0.1:4173/playground/`.
+
+```bash skip="host-install"
+cd libs/typescript
+pnpm install
+pnpm --filter @trycua/cursor-motion playground
+```
+
+For a built-in style, the exported Cua Driver config looks like this:
+
+```bash test="cli-shape" id="cua-driver-design-cursor-motion"
+cua-driver config set cursor.motion.style comet_swoop
+cua-driver config set cursor.motion.timing fitts
+cua-driver cursor motion --session demo --style comet_swoop --timing fitts --effects trail=on
+```
+
+The arc knobs (`arc_size`, `arc_flow`, `start_handle`, `end_handle`) and the
+classic glide's `spring` and `turn_radius` travel only through
+`set_agent_cursor_motion`. See [Choose your cursor](/cua-driver/guides/operate#choose-your-cursor)
+for how saved defaults, `start_session`, and per-call settings combine.
diff --git a/docs/content/docs/cua-driver/guides/test-in-a-sandbox.mdx b/docs/content/docs/cua-driver/guides/test-in-a-sandbox.mdx
deleted file mode 100644
index 0d7a433ddb..0000000000
--- a/docs/content/docs/cua-driver/guides/test-in-a-sandbox.mdx
+++ /dev/null
@@ -1,88 +0,0 @@
----
-title: Test cua-driver in a sandbox
-description: Run a cua-driver build against a disposable Linux desktop, locally or in CI, and prove the build under test is the one that runs.
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-A sandbox gives cua-driver a real desktop (Xvfb, XFCE, AT-SPI) that you can
-throw away, on your machine or on a CI runner. Put your build into it with
-`--overlay`, then check that it is the one running.
-
-## On your machine
-
-Build the driver for Linux, then create a sandbox with it:
-
-```bash test="cli-shape" id="driver-sandbox-create"
-cua sb create linux --name drv --wait desktop \
- --overlay cua-driver=./target/release/cua-driver
-```
-
-The overlay replaces `/usr/local/bin/cua-driver` in the guest, records its
-sha256 and stops any older copy still running. Check it:
-
-```bash test="cli-shape" id="driver-sandbox-doctor"
-cua doctor local:drv --no-host --only build --expect cua-driver=git:<commit sha>
-cua sb exec local:drv cua-driver doctor --json
-```
-
-`cua-driver doctor --json` and the `health_report` tool report the running
-build under `build`:
-
-- `git_sha`: the commit it was built from;
-- `exe_sha256`: the executable that actually runs.
-
-A process started before the file was replaced still reports its old hash.
-
-Run your tests against the desktop, then delete the sandbox:
-
-```bash test="cli-shape" id="driver-sandbox-run"
-cua sb cp ./tests/smoke.sh drv:/tmp/smoke.sh
-cua sb shell drv "set -a; . /run/cua-desktop/desktop.env; set +a; bash /tmp/smoke.sh"
-cua sb rm local:drv --force
-```
-
-## The driver inside cua-spacesd
-
-cua-spacesd links the driver core and serves its tools on `/mcp`. To test
-driver changes through spacesd, inject a cua-spacesd built from the same
-commit. The overlay restarts the daemon and waits until the new process runs
-it:
-
-```bash test="cli-shape" id="driver-sandbox-spacesd"
-cua sb overlay drv cua-spacesd=./target/release/cua-spacesd
-cua doctor local:drv --no-host --only build \
- --expect cua-spacesd=git:<commit sha> --expect cua-driver=git:<commit sha>
-```
-
-With both injected, `cua-driver=git:` must hold for the linked driver and the
-standalone binary.
-
-## In GitHub Actions
-
-```yaml test="config" id="driver-sandbox-ci"
- - uses: trycua/cua/.github/actions/cua-sandbox@main
- with:
- image: linux
- overlay: cua-driver=libs/cua-driver/rust/target/release/cua-driver
- expect: cua-driver=git:${{ github.sha }}
- guest-setup: apt-get update -qq && apt-get install -y -qq jq ffmpeg
- run: |
- cua sb cp scripts/ci/linux/preflight-rust-e2e.sh "$CUA_SANDBOX:/tmp/preflight.sh"
- cua sb shell "$CUA_SANDBOX" "set -a; . /run/cua-desktop/desktop.env; set +a;
- export CUA_E2E_SOURCE_SHA=${{ github.sha }} CUA_TEST_DRIVER_BIN=/usr/local/bin/cua-driver;
- bash /tmp/preflight.sh"
-```
-
-This is how the repository's own Linux driver preflight runs. The preflight
-fails with `stale driver` when the driver's embedded commit differs from
-`CUA_E2E_SOURCE_SHA`.
-
-<Callout type="info">
-On the runner, the action puts a `PATH` first where `cua-driver` is the
-injected build, and `cua-spacesd` is a stub that fails. A copy installed on
-the runner is never picked up.
-</Callout>
-
-See [Test in CI with Cua sandboxes](/cua-sdk/guides/test-in-ci) for every
-input and output.
diff --git a/docs/content/docs/cua-driver/guides/trajectories.mdx b/docs/content/docs/cua-driver/guides/trajectories.mdx
deleted file mode 100644
index b58cf2890f..0000000000
--- a/docs/content/docs/cua-driver/guides/trajectories.mdx
+++ /dev/null
@@ -1,134 +0,0 @@
----
-title: Record trajectories and history
-description: Record an agent's actions, render them as a zoom-on-click video, and keep an encrypted local Computer History.
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
-
-## Record a trajectory
-
-A recording saves every action with its arguments and before-and-after
-screenshots, plus an optional display video. Rendering needs `ffmpeg` on every
-platform; capture also needs it on Windows and Linux (macOS 15+ uses
-ScreenCaptureKit).
-
-<VideoDemo
- src="https://github.com/user-attachments/assets/9eafceca-1738-4e34-949a-2fb0dbe1832e"
- poster="https://github.com/user-attachments/assets/d896dd2f-3f0a-4978-93a3-c9a5c562c3e8"
- title="Turn an agent trajectory into a zoom-on-click demo"
- sourceUrl="https://x.com/trycua/status/2047383207612645426"
->
- The agent clicks cells in a numbered grid, then Cua Driver renders the recorded actions.
-</VideoDemo>
-
-Have your agent call `start_recording` before the task:
-
-```json test="config" id="json-config"
-{
- "output_dir": "~/cua-trajectories/calendar-demo",
- "record_video": true
-}
-```
-
-Actions such as `click`, `type_text`, `press_key`, and `scroll` are added
-automatically, one `turn-NNNNN` folder each. Call `stop_recording` with `{}`
-and wait for it: it finalizes `recording.mp4`. Then render:
-
-```bash test="cli-shape" id="cua-driver-recording-render"
-cua-driver recording render \
- ~/cua-trajectories/calendar-demo \
- ~/cua-trajectories/calendar-demo.mp4 \
- --scale 2.5
-```
-
-The renderer zooms around each recorded action; `--scale` sets the strength
-and `--no-zoom` gives a plain render. All options:
-[`cua-driver recording`](/cua-driver/reference/cli) and the
-[recording tools](/cua-driver/reference/mcp-tools).
-
-## Computer History
-
-Computer History keeps an encrypted local record of actions performed through
-Cua Driver, so an agent can pick up where a previous run stopped. It is an
-opt-in preview in nightly builds on macOS, Windows, and Linux, and records
-nothing outside Cua-mediated actions.
-
-```bash test="cli-shape" id="cua-driver-history-enable"
-cua-driver channel set nightly
-cua-driver update --apply
-cua-driver history enable
-cua-driver history status
-```
-
-`enable` creates a key in the macOS Keychain, Windows Credential Manager, or
-Linux Secret Service (which must be unlocked; there is no plaintext fallback)
-and starts capture. Defaults: 7-day retention, 100 MiB quota, no network I/O.
-
-| Command | Effect |
-| --- | --- |
-| `cua-driver history list 50` | Newest 50 events. Add `--json` for scripts. |
-| `cua-driver history show 42` | One event by sequence number. |
-| `cua-driver history pause` / `resume` / `disable` | Stop or restart capture; existing history is kept. |
-| `cua-driver history delete --yes` | Destroy the key and the encrypted store. |
-
-```bash test="cli-shape" id="cua-driver-history-list"
-cua-driver history list 50
-cua-driver history show 42
-cua-driver history pause
-cua-driver history resume
-cua-driver history delete --yes
-```
-
-History stores timestamps, opaque IDs, capability names, app identity, and
-fixed outcome categories. It never stores screenshots, typed text,
-keystrokes, clipboard, tool arguments or results, accessibility trees, file
-paths, window titles, or URLs. Deleting destroys the key; it cannot erase
-backups or snapshots of the ciphertext.
-
-### Let an agent read history
-
-A runtime that admits the preview exposes two read-only tools:
-`history_status` (capability `history.status`) and `history_query`
-(`history.query`, at most 200 events, filters `limit`, `session_id`,
-`since_sequence`, `until_sequence`). Every call passes the normal
-[permission stack](/cua-driver/guides/permissions); a bounded manifest must
-name both:
-
-```yaml test="config" id="yaml-config"
-version: 3
-expires_after: 1h
-idle_timeout: 10m
-resources:
- computer_history:
- operations:
- - status
- - query
-allow:
- tools:
- - history_status
- - history_query
-```
-
-Having the tools does not make a model use them. For "continue" or "what did I
-do" requests, give the agent a trusted instruction (or run the
-status-then-query preflight in your host) to check history first, treat events
-as metadata, and verify current state before acting. A query that returns
-events appends an encrypted access record. Agents cannot enable, pause,
-delete, or export history.
-
-| Error | Fix |
-| --- | --- |
-| `history_preview_not_admitted` | Restart a development daemon with `cua-driver serve --experimental-history`. |
-| `history_key_locked`, `history_key_unavailable` | Unlock the login keychain or start a Secret Service. |
-| `history_quota_reached` | Delete history; the action that hit the limit still ran. |
-| `history_storage_corrupt` | `cua-driver history delete --yes`, then enable again. |
-
-The event schema (CloudEvents 1.0, `urn:cua-driver:schema:history-event:v0`)
-and storage profile are specified in the
-[agent integration RFC](https://github.com/trycua/cua/blob/main/libs/cua-driver/docs/computer-history-agent-integration-rfc.md).
-
-<Callout type="info">
- To return to stable: `cua-driver history disable`, `cua-driver channel set stable`,
- `cua-driver update --apply`. History is kept unless you delete it.
-</Callout>
diff --git a/docs/content/docs/cua-driver/guides/use-the-sdk.mdx b/docs/content/docs/cua-driver/guides/use-the-sdk.mdx
index 7182934392..d194d0d2d5 100644
--- a/docs/content/docs/cua-driver/guides/use-the-sdk.mdx
+++ b/docs/content/docs/cua-driver/guides/use-the-sdk.mdx
@@ -216,9 +216,7 @@ try {
</Tab>
</Tabs>
-Version 0.25 does not expose these typed window methods (`ActionTarget`,
-`ClickPosition`); upgrade the bindings and native library together. Rules the
-example follows:
+Rules the example follows:
- `click` returns `ActionResult` and raises `DriverError.Tool` on refusal. A
returned action does not prove the UI changed; the second snapshot does.
diff --git a/docs/content/docs/cua-driver/guides/vms-and-remote.mdx b/docs/content/docs/cua-driver/guides/vms-and-remote.mdx
index 9692bcf137..41c93e1263 100644
--- a/docs/content/docs/cua-driver/guides/vms-and-remote.mdx
+++ b/docs/content/docs/cua-driver/guides/vms-and-remote.mdx
@@ -1,12 +1,13 @@
---
-title: Run in a VM or over SSH
-description: Run Cua Driver inside a macOS Lume VM or drive a Windows desktop over SSH.
+title: Run in a VM, over SSH, or in a sandbox
+description: Run Cua Driver inside a macOS Lume VM, drive a Windows desktop over SSH, or test a driver build in a disposable Linux sandbox.
---
import { Callout } from 'fumadocs-ui/components/callout';
Cua Driver always runs on the machine whose desktop it drives. To reach a VM or
-a remote computer, run the driver there and carry MCP over SSH.
+a remote computer, run the driver there and carry MCP over SSH. To test a
+driver build, use a disposable Linux sandbox.
## macOS Lume VM
@@ -137,3 +138,89 @@ Still empty? Check that `whoami /user` shows the same SID over SSH and on the
desktop, that `cua-driver --version` matches over SSH, that
`cua-driver autostart status` shows the task, and that `cua-driver doctor` from
RDP reports `session N has an attached interactive desktop`.
+
+## Test a driver build in a sandbox
+
+A [Cua sandbox](/cua-sdk) gives a driver build a real Linux desktop (Xvfb, XFCE,
+AT-SPI) that you can throw away, on your machine or on a CI runner. Put your
+build into it with `--overlay`, then check that it is the one running. This is
+for testing Cua Driver itself. Inside a sandbox you do not install the driver
+to use it: the sandbox's guest service bundles its tools.
+
+### On your machine
+
+Build the driver for Linux, then create a sandbox with it:
+
+```bash test="cli-shape" id="driver-sandbox-create"
+cua sb create linux --name drv --wait desktop \
+ --overlay cua-driver=./target/release/cua-driver
+```
+
+The overlay replaces `/usr/local/bin/cua-driver` in the guest, records its
+sha256 and stops any older copy still running. Check it:
+
+```bash test="cli-shape" id="driver-sandbox-doctor"
+cua doctor local:drv --no-host --only build --expect cua-driver=git:<commit sha>
+cua sb exec local:drv cua-driver doctor --json
+```
+
+`cua-driver doctor --json` and the `health_report` tool report the running
+build under `build`:
+
+- `git_sha`: the commit it was built from;
+- `exe_sha256`: the executable that actually runs.
+
+A process started before the file was replaced still reports its old hash.
+
+Run your tests against the desktop, then delete the sandbox:
+
+```bash test="cli-shape" id="driver-sandbox-run"
+cua sb cp ./tests/smoke.sh drv:/tmp/smoke.sh
+cua sb shell drv "set -a; . /run/cua-desktop/desktop.env; set +a; bash /tmp/smoke.sh"
+cua sb rm local:drv --force
+```
+
+### The driver inside cua-spacesd
+
+cua-spacesd links the driver core and serves its tools on `/mcp`. To test
+driver changes through spacesd, inject a cua-spacesd built from the same
+commit. The overlay restarts the daemon and waits until the new process runs
+it:
+
+```bash test="cli-shape" id="driver-sandbox-spacesd"
+cua sb overlay drv cua-spacesd=./target/release/cua-spacesd
+cua doctor local:drv --no-host --only build \
+ --expect cua-spacesd=git:<commit sha> --expect cua-driver=git:<commit sha>
+```
+
+With both injected, `cua-driver=git:` must hold for the linked driver and the
+standalone binary.
+
+### In GitHub Actions
+
+```yaml test="config" id="driver-sandbox-ci"
+ - uses: trycua/cua/.github/actions/cua-sandbox@main
+ with:
+ image: linux
+ overlay: cua-driver=libs/cua-driver/rust/target/release/cua-driver
+ expect: cua-driver=git:${{ github.sha }}
+ guest-setup: apt-get update -qq && apt-get install -y -qq jq ffmpeg
+ run: |
+ cua sb cp scripts/ci/linux/preflight-rust-e2e.sh "$CUA_SANDBOX:/tmp/preflight.sh"
+ cua sb shell "$CUA_SANDBOX" "set -a; . /run/cua-desktop/desktop.env; set +a;
+ export CUA_E2E_SOURCE_SHA=${{ github.sha }} CUA_TEST_DRIVER_BIN=/usr/local/bin/cua-driver;
+ bash /tmp/preflight.sh"
+```
+
+This is how the repository's own Linux driver preflight runs. The preflight
+fails with `stale driver` when the driver's embedded commit differs from
+`CUA_E2E_SOURCE_SHA`.
+
+<Callout type="info">
+On the runner, the action puts a `PATH` first where `cua-driver` is the
+injected build, and `cua-spacesd` is a stub that fails. A copy installed on
+the runner is never picked up.
+</Callout>
+
+See [Test in CI with Cua sandboxes](/cua-sdk/guides/test-in-ci) for every
+input and output.
diff --git a/docs/content/docs/cua-driver/index.mdx b/docs/content/docs/cua-driver/index.mdx
index 09ecfbc70a..6434cc3ba9 100644
--- a/docs/content/docs/cua-driver/index.mdx
+++ b/docs/content/docs/cua-driver/index.mdx
@@ -1,68 +1,60 @@
---
title: Cua Driver
-description: Drive native apps on macOS, Windows and Linux in the background.
+description: Let an AI agent use the apps on your computer while you keep working.
landing:
+ summary: 'Let an agent use the apps on your computer in the background, on macOS, Windows and Linux.'
cta: Drive a real app
---
-Cua Driver gives an agent the apps on a real computer. It reads each window's
-accessibility tree and screenshot, then clicks, types, scrolls, and drives
-browser tabs, in the background where the operating system allows it. The
-person at the keyboard keeps their focus and cursor; the agent gets its own
-cursor overlay.
+Cua Driver lets an AI agent use the apps on your computer: it can click
+buttons, type, scroll and move between browser tabs. It works in the
+background, so you can keep using your mouse and keyboard while the agent
+works. The agent gets its own cursor, so you can see what it is doing.
-Use it from any agent through **MCP** (`cua-driver mcp`), from a shell through
-the **CLI** (`cua-driver call <tool>`), or inside your own app through the
-Python and TypeScript **SDK** (`CuaDriver.create()`). On macOS the SDK
-uses the `CuaDriver.app` daemon, which draws the agent cursor and holds the
-permission grants.
+It works with agents such as Claude Code, Codex and Cursor. You install it
+once, add it to your agent, and then ask the agent to do things in your apps.
<VideoDemo
src="https://github.com/user-attachments/assets/e9344780-e780-46e7-bcce-91f61eda9599"
poster="/media/workflow-demos/highlights-poster.jpg"
- title="Real desktop workflows with GPT-6 Astra + Cua Driver"
+ title="An agent at work in QGIS, Preview, GIMP and Inkscape"
aspectRatio={8 / 5}
autoPlay={false}
loop={false}
preload="metadata"
>
- Selected interactions from QGIS, Preview, GIMP, and Inkscape, with the recorded agent cursor and
- action captions.
+ Recorded on macOS with GPT-6 Astra and Cua Driver. Setup and waits are cut.
+ Try these tasks yourself in [Recipes](/cua-driver/guides/recipes).
</VideoDemo>
-Recorded on macOS with GPT-6 Astra + Cua Driver; selected gestures at 1x, with
-setup and waits cut. Try them in [Recipes](/cua-driver/guides/recipes).
-
-## Platforms
-
-| Platform | Requirements | Automation APIs | Status |
-| ------------- | -------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------- |
-| macOS | macOS 14+, Apple Silicon or Intel; Accessibility and Screen Recording | Accessibility (AX), ScreenCaptureKit, Quartz | Supported |
-| Windows | Windows 10/11 or Server, interactive desktop session | UI Automation, Win32 input and window messages | Supported |
-| Linux X11 | x86_64 desktop session, AT-SPI 2 | AT-SPI, X11/EWMH, XTest | Supported with toolkit limits |
-| Linux Wayland | x86_64 desktop session, AT-SPI 2 | AT-SPI, compositor-specific capture and input | Supported with compositor limits |
-
-See [Platform support](/cua-driver/concepts/platform-support) for proven
-surfaces and limits.
-
-## Choose an integration
-
-Pick by who owns the runtime: the process that holds the OS permissions,
-sessions, and browser connections.
-
-| You are building | Use | Runtime owner |
-| --------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------- |
-| An agent or harness (Claude Code, Codex, Cursor, …) | [MCP](/cua-driver/guides/connect-your-agent): `cua-driver mcp` | The MCP process; on macOS, the `CuaDriver.app` daemon |
-| An agent that can only run shell commands | [CLI](/cua-driver/reference/cli): `cua-driver call <tool>` | The `cua-driver serve` daemon |
-| An app with built-in computer use | [SDK](/cua-driver/guides/use-the-sdk): `CuaDriver.create()` | On macOS, the `CuaDriver.app` daemon; elsewhere your app process |
-| A signed desktop app that serves an external agent | [App-hosted service](/cua-driver/guides/use-the-sdk#expose-mcp-from-a-desktop-app) | The permission-owning desktop app |
-| Several clients sharing one desktop | `cua-driver serve --socket <path>` plus `cua-driver mcp --socket <path>` | The daemon |
-
-Inside a [Cua Sandbox](/cua-sdk) you do not install Cua Driver: the sandbox's
-guest service bundles its tools.
-
-## Next
-
-- [Quickstart](/cua-driver/quickstart): install and drive your first app.
-- [Connect your agent](/cua-driver/guides/connect-your-agent): every supported harness.
-- [How Cua Driver works](/cua-driver/concepts/how-cua-driver-works): background delivery, targets, and sessions.
+## Get started
+
+1. [Quickstart](/cua-driver/quickstart): install Cua Driver and have your agent
+ use a calculator. About five minutes.
+2. [Connect your agent](/cua-driver/guides/connect-your-agent): add Cua Driver
+ to Claude Code, Codex, Cursor and other agents.
+3. [Recipes](/cua-driver/guides/recipes): real tasks to try next.
+
+## Where it works
+
+| Computer | What you need | Works? |
+| --- | --- | --- |
+| Mac | macOS 14 or later. You allow Accessibility and Screen Recording once. | Yes |
+| Windows | Windows 10, 11 or Server, with a user signed in at the desktop | Yes |
+| Linux | A 64-bit (x86_64) desktop | Yes, with some limits |
+
+Some apps and some Linux desktops only work while the app is in front. See
+[Platform support](/cua-driver/concepts/platform-support) for the details.
+
+## What do you want to do?
+
+| I want to | Go to |
+|---|---|
+| Install it and try a first task | [Quickstart](/cua-driver/quickstart) |
+| Add it to my agent | [Connect your agent](/cua-driver/guides/connect-your-agent) |
+| Control what the agent may do | [Set permissions](/cua-driver/guides/permissions) |
+| Let the agent use web pages | [Drive a browser](/cua-driver/guides/browsers) |
+| Use it from my own app's code | [Use the SDK](/cua-driver/guides/use-the-sdk) |
+| Pick the right way to connect, or understand how it works | [How Cua Driver works](/cua-driver/concepts/how-cua-driver-works) |
+| Fix something that isn't working | [Troubleshoot](/cua-driver/guides/troubleshoot) |
+| Look up a command or tool | [Reference](/cua-driver/reference) |
diff --git a/docs/content/docs/cua-driver/quickstart.mdx b/docs/content/docs/cua-driver/quickstart.mdx
index f7f89bb5ca..3c9c3cc699 100644
--- a/docs/content/docs/cua-driver/quickstart.mdx
+++ b/docs/content/docs/cua-driver/quickstart.mdx
@@ -4,19 +4,35 @@ description: Install Cua Driver, connect your agent, and have it compute 6 × 7
---
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
Install Cua Driver on your computer and let your agent operate the calculator
-app, in the background.
-
-## Prerequisites
+app in the background. By the end, the agent opens Calculator, computes 6 × 7,
+and reports 42 from the app itself.
+
+<VideoDemo
+ src="https://github.com/user-attachments/assets/11b248e5-d505-4349-aaae-ad9f95a1162f"
+ poster="https://github.com/user-attachments/assets/0fb62243-56ec-4d51-8771-35640a5e6031"
+ title="Drive a legacy postal app with Cua Driver"
+ sourceUrl="https://x.com/trycua/status/2059693301276565841"
+ className="my-8"
+>
+ Cua Driver fills shipment details and prints receipts in a Windows desktop app with no API. You
+ will start with a smaller Calculator task below.
+</VideoDemo>
+
+## Before you start
- macOS 14+, Windows 10/11, or an x86_64 Linux desktop (X11 or XWayland, with AT-SPI 2)
-- An MCP-capable agent, such as Claude Code or Codex
-- A desktop calculator app
+- An agent that supports MCP or skills, such as Claude Code or Codex
+- A desktop calculator app. On Linux, use your distribution's, such as GNOME Calculator.
+
+Run every step in the desktop session you want the agent to drive.
-## Run
+## 1. Install and start Cua Driver
-**1. Install and start the daemon.** No administrator access needed.
+No administrator access is needed. The installer picks the right path for your
+platform.
<Tabs items={['macOS', 'Windows', 'Linux']}>
<Tab value="macOS">
@@ -28,12 +44,37 @@ cua-driver permissions grant
```
Starting through the app bundle makes macOS attribute the prompts to
-CuaDriver. Choose **Open System Settings** and switch CuaDriver on under
-**Accessibility** and **Screen & System Audio Recording**; accept the relaunch.
-Rerun `cua-driver permissions grant` if only one prompt appeared.
+CuaDriver, so the grant sticks to the driver.
+
+macOS asks once for each permission. Neither prompt grants anything by
+itself: both offer **Open System Settings**, not **Allow**.
+
+![The macOS Accessibility Access prompt for CuaDriver, offering Open System Settings or Deny](https://github.com/user-attachments/assets/b7a5a0c0-f297-4249-81f9-ca42c6b6f8ba)
+
+![The macOS Screen Recording prompt for CuaDriver, offering Open System Settings or Deny](https://github.com/user-attachments/assets/69efc964-a375-495e-8a27-400c9dd08e17)
+
+**Open System Settings** adds CuaDriver to that permission's list, switched
+off. Switching it on is what grants access.
![CuaDriver listed under Accessibility in System Settings with its toggle switched off](https://github.com/user-attachments/assets/d149fe5a-28cb-460c-8868-4eda80d540a4)
+![CuaDriver listed under Screen & System Audio Recording in System Settings with its toggle switched off](https://github.com/user-attachments/assets/469308b5-84d7-4fd6-a580-e62925120337)
+
+<Callout type="warn">
+ Switch on both **Accessibility** and **Screen & System Audio Recording**. If you choose
+ **Deny**, the driver cannot see or drive your desktop. macOS may offer to quit and reopen
+ CuaDriver when you flip a toggle. Accept: the driver only picks up a changed grant after a full
+ relaunch. If the daemon does not come back, run `open -n -g -a CuaDriver --args serve`.
+</Callout>
+
+macOS does not always show both prompts in one pass. Check what landed:
+
+```bash test="cli-shape" id="cua-driver-permissions-status"
+cua-driver permissions status
+```
+
+If one is still missing, run `cua-driver permissions grant` again.
+
</Tab>
<Tab value="Windows">
@@ -42,7 +83,10 @@ irm https://cua.ai/driver/install.ps1 | iex
cua-driver autostart kick
```
-Run it from your desktop session. Over SSH, see
+The installer tries to register Cua Driver to start at sign-in, and `kick`
+starts that task now. If registration was skipped or failed, run
+`cua-driver serve` in a terminal in your desktop session and leave it open. Use
+a second terminal for the checks below. Over SSH, see
[Windows over SSH](/cua-driver/guides/vms-and-remote#windows-over-ssh).
</Tab>
@@ -53,8 +97,10 @@ Run it from your desktop session. Over SSH, see
cua-driver serve
```
-Run it in a terminal inside the desktop session and leave it open. On a
-minimal image, first `sudo apt install libxi6 at-spi2-core`.
+Run it in a terminal inside the desktop session, so the driver can reach its
+display and accessibility bus, and leave it open. Use a second terminal for the
+checks below. On a minimal Debian or Ubuntu image, first run
+`sudo apt install libxi6 at-spi2-core`.
On GNOME, also install the bundled WinRects helper (no `sudo` needed), then
log out and back in once so Shell loads it:
@@ -67,25 +113,71 @@ gnome-extensions info winrects@cua # State: ACTIVE
</Tab>
</Tabs>
-**2. Check that it sees your apps** (in a second terminal):
+The daemon starts in the default `standard` permission mode, which is right for
+this walkthrough. Before a real workload, read [Permissions](/cua-driver/guides/permissions)
+to decide whether it should be `bounded`. If macOS grants look stale, see
+[Troubleshoot](/cua-driver/guides/troubleshoot#reset-stale-macos-permissions).
+
+## 2. Check that it sees your apps
+
+Run these in a second terminal. First confirm the daemon is reachable. You
+should see `Cua Driver daemon is running`:
+
+```bash test="cli-shape" id="cua-driver-status"
+cua-driver status
+```
+
+Then check the environment. Read the whole report, warnings included: a zero
+exit code does not prove the desktop is ready.
+
+```bash test="cli-shape" id="cua-driver-doctor"
+cua-driver doctor
+```
+
+Then list the GUI apps the driver can reach:
```bash test="cli-shape" id="cua-driver-call"
cua-driver call list_apps
```
-You should see the GUI apps you have open. An empty list means the driver
-cannot reach the desktop; run `cua-driver doctor`.
+The list should include an app you recognize. An empty list means the driver
+cannot reach the desktop: open Calculator in that session and retry, and fix
+any permission or display error `doctor` reports before you go on.
+
+## 3. Connect your agent
+
+Pick one way in. A skill teaches the agent to run the Cua Driver CLI. An MCP
+registration exposes Cua Driver as a tool server. `mcp-config` prints the
+registration command, which you run, and installs the skill for that agent
+(add `--no-skills` to skip it). It uses the paths on your machine, not the
+example paths below.
-**3. Connect your agent and ask.** To set up every agent it finds at once
-(skill and MCP server), run
-`curl -fsSL https://cua.ai/install.sh | sh -s -- --select cua-driver` instead;
-it also installs the `cua` CLI.
+To set up every agent on the machine at once (skill and MCP server), run
+`curl -fsSL https://cua.ai/install.sh | sh -s -- --select cua-driver` instead.
+It also installs the `cua` CLI.
-<Tabs items={['Claude Code', 'Codex', 'Other']}>
+<Tabs items={['Claude Code', 'Codex', 'Prime Agent', 'OpenClaw', 'Hermes', 'Other']}>
<Tab value="Claude Code">
+Install the Cua Driver skill:
+
```bash test="cli-shape" id="cua-driver-skills-install"
cua-driver skills install
+cua-driver skills status
+```
+
+Confirm that the status lists a Claude Code skill link, then start a fresh
+Claude Code session. If the link is missing, see
+[Install the agent skill](/cua-driver/guides/connect-your-agent#install-the-agent-skill).
+
+To use plain MCP instead of the skill, print the registration command:
+
+```bash test="cli-shape" id="cua-driver-mcp-config-claude"
+cua-driver mcp-config --client claude
+```
+
+```bash output
+claude mcp add-json --scope user cua-computer-use '{"args":["mcp"],"command":"/Users/you/.local/bin/cua-driver"}'
```
</Tab>
@@ -95,29 +187,112 @@ cua-driver skills install
cua-driver mcp-config --client codex
```
-Run the `codex mcp add …` command it prints.
+Run the command it prints, which uses the absolute path of the installed binary:
+
+```bash output
+codex mcp add cua-driver -- /Users/you/.local/bin/cua-driver mcp
+```
+
+Run `codex mcp list` to confirm the `cua-driver` entry. Start a fresh Codex
+session and use `/mcp` to check that the server is active. See the
+[official Codex MCP instructions](https://learn.chatgpt.com/docs/extend/mcp).
+
+ </Tab>
+ <Tab value="Prime Agent">
+
+Install the skill pack. Prime Agent finds it in its own skill directory and
+calls Cua Driver from its persistent IPython environment, so it needs no MCP
+registration.
+
+```bash test="cli-shape" id="cua-driver-skills-install-2"
+cua-driver skills install
+cua-driver skills status
+```
+
+Run `/reload` in Prime Agent or start a new session so the skill appears. Use
+`/skill:cua-driver` to load it explicitly.
+
+ </Tab>
+ <Tab value="OpenClaw">
+
+```bash test="cli-shape" id="cua-driver-mcp-config-openclaw"
+cua-driver mcp-config --client openclaw
+```
+
+Run the command it prints:
+
+```bash output
+openclaw mcp set cua-driver '{"command":"/Users/you/.local/bin/cua-driver","args":["mcp"]}'
+```
+
+<Callout type="warn">
+ On macOS, a server started this way by the gateway does not inherit OpenClaw.app's own
+ Accessibility and Screen Recording grants. To let the host app own the grants, see
+ [Expose MCP from a desktop app](/cua-driver/guides/use-the-sdk#expose-mcp-from-a-desktop-app).
+</Callout>
+
+ </Tab>
+ <Tab value="Hermes">
+
+Hermes has a built-in `computer_use` toolset. Turn it on for the CLI instead of
+adding a second raw MCP server, then start a chat with it:
+
+```bash skip="third-party-cli"
+hermes tools enable computer_use --platform cli
+hermes -t computer_use chat
+```
+
+If it cannot reach Cua Driver, run `hermes computer-use install`, then check
+with `hermes computer-use doctor`.
</Tab>
<Tab value="Other">
-See [Connect your agent](/cua-driver/guides/connect-your-agent).
+For Cursor, Antigravity, OpenCode, Pi, a local model, or another harness, see
+[Connect your agent](/cua-driver/guides/connect-your-agent).
</Tab>
</Tabs>
-Start a fresh agent session and send:
+## 4. Ask your agent
+
+Start a fresh agent session and send this prompt. It asks the agent to read
+the calculator's display after acting, so the agent checks the app instead of
+answering the arithmetic from memory.
```text output
-Using Cua Driver, open the installed calculator app, compute 6 × 7,
-and read the displayed result back from a fresh snapshot.
+Using the Cua Driver skill, open the installed calculator app,
+compute 6 × 7, and read the displayed result back from a fresh snapshot.
```
-## Result
+Name the setup you chose in place of "the Cua Driver skill":
+
+| Your setup | Say |
+| --- | --- |
+| Claude Code or Prime Agent, with the skill | the Cua Driver skill |
+| Claude Code, with MCP registration | the cua-computer-use MCP server |
+| Codex or OpenClaw | the cua-driver MCP server |
+| Hermes | the computer_use toolset |
+
+The app name, the controls, and the steps differ by platform and calculator.
+The agent finds them from fresh state, and element indices from another run
+do not carry over. If no calculator is installed, install one from your
+platform's app store or package manager, then send the prompt again.
+
+## 5. Check the result
+
+The calculator shows **42**, and the agent reports that value from its last
+read of the app. A correct answer alone does not prove the agent operated the
+app.
-The calculator shows **42** and the agent reports it from the app. Your own
-window and pointer stay where they were: the moving cursor is the agent's
-overlay. Some apps only accept foreground input; see
-[How Cua Driver works](/cua-driver/concepts/how-cua-driver-works).
+Your own window, keyboard focus, and pointer should have stayed where they
+were. The moving cursor is the agent's overlay, not your pointer. Watch for
+this yourself: do not infer it from the answer. Cua Driver delivers input in
+the background where the operating system allows it, and a few cases still
+need the foreground: some apps accept only foreground input, launching an app
+can raise its window, and native Wayland depends on the compositor. See
+[Platform mechanisms](/cua-driver/concepts/how-cua-driver-works#platform-mechanisms)
+and [Known limits](/cua-driver/guides/troubleshoot#known-limits).
## Clean up
@@ -151,6 +326,11 @@ Driver skill has the example profile, the VNC helper and the exact steps: see
## Next
-- [Connect your agent](/cua-driver/guides/connect-your-agent): every supported harness and local models.
-- [Recipes](/cua-driver/guides/recipes): real workflows with prompts and checks.
-- [Use the SDK](/cua-driver/guides/use-the-sdk): drive apps from Python or TypeScript.
+- [Recipes](/cua-driver/guides/recipes): real workflows with prompts and checks, such as
+ [building a map](/cua-driver/guides/recipes#build-and-inspect-a-map) and
+ [redacting a PDF](/cua-driver/guides/recipes#redact-and-annotate-a-pdf). These runs use foreground
+ input, so run them on a spare desktop or in a [VM](/cua-driver/guides/vms-and-remote).
+- [Connect your agent](/cua-driver/guides/connect-your-agent): every supported harness, agent SDKs, and local models.
+- [Use the SDK](/cua-driver/guides/use-the-sdk): drive apps from Python or TypeScript inside your own program.
+- [Keep Cua Driver running](/cua-driver/guides/operate): autostart, permission modes, and updates.
+- [How Cua Driver works](/cua-driver/concepts/how-cua-driver-works): how it avoids stealing your focus and cursor.
diff --git a/docs/content/docs/cua-sdk/concepts/how-sandboxes-work.mdx b/docs/content/docs/cua-sdk/concepts/how-sandboxes-work.mdx
index 7a5f82238c..6ef80adf21 100644
--- a/docs/content/docs/cua-sdk/concepts/how-sandboxes-work.mdx
+++ b/docs/content/docs/cua-sdk/concepts/how-sandboxes-work.mdx
@@ -29,7 +29,7 @@ Every create takes the same three choices, all optional:
| Axis | SDK | CLI | Values | Default |
| --- | --- | --- | --- | --- |
-| Where | `on=` (cua-sandbox also `local=True`) | `--on` | `local`, `aws`, `gcp`, `modal` ([your cloud](/cua-sdk/guides/your-cloud)), `direct:<addr>` (an existing machine running cua-spacesd), a registered provider | `default.on`, else `local` |
+| Where | `on=` (cua-sandbox also `local=True`) | `--on` | `local`, `aws`, `gcp`, `modal` ([your cloud](/cua-sdk/guides/local-runtimes#your-own-cloud)), `direct:<addr>` (an existing machine running cua-spacesd), a registered provider | `default.on`, else `local` |
| What kind | `kind=` | `--kind` | `auto`, `container`, `vm` | `auto` |
| Which engine | `runtime=` | `--runtime` | `auto` or an engine below | `auto` |
diff --git a/docs/content/docs/cua-sdk/guides/agent-frameworks.mdx b/docs/content/docs/cua-sdk/guides/agent-frameworks.mdx
index 8be67ec908..52f7152434 100644
--- a/docs/content/docs/cua-sdk/guides/agent-frameworks.mdx
+++ b/docs/content/docs/cua-sdk/guides/agent-frameworks.mdx
@@ -7,7 +7,7 @@ import { Callout } from 'fumadocs-ui/components/callout';
Each recipe gives a third-party agent its own desktop instead of yours.
Sandboxes run on this machine by default; to run them in your own AWS, Google
-Cloud or Modal account, see [Use your own cloud](/cua-sdk/guides/your-cloud).
+Cloud or Modal account, see [Choose where sandboxes run](/cua-sdk/guides/local-runtimes#your-own-cloud).
The Python script needs Python `>=3.11,<3.14` with
[`uv`](https://docs.astral.sh/uv/) and pins `cua-sandbox==0.9.1`. Your
controller owns the sandbox and must delete it.
@@ -48,7 +48,7 @@ interactive.
Cursor's self-hosted Team Pool worker can run in a Linux Space on your Mac or
on a machine you set up with
-[`cua host setup --provide-spaces`](/spaces/guides/host-spaces-on-your-spare-mac)
+[`cua host setup --provide-spaces`](/spaces/guides/add-a-computer#use-a-spare-mac-to-host-spaces)
(add `--on "<machine>"` and use the id `create` prints). It needs Cursor
Enterprise with [Self-Hosted Machines](https://cursor.com/docs/cloud-agent/self-hosted)
allowed and a service-account API key. Create the Space, install the Cursor
@@ -123,8 +123,8 @@ For Omarchy on Apple silicon, see [Lume](/lume).
## Minecraft
-Build the Prism launcher into an image once, then run it in the cloud or
-locally. Describe it as `minecraft.json`:
+Build the Prism launcher into an image once, then run it locally or in your
+own cloud. Describe it as `minecraft.json`:
```json title="minecraft.json" test="config" id="json-config" schema="cua-image"
{
@@ -149,7 +149,7 @@ locally. Describe it as `minecraft.json`:
}
```
-Build on an x86_64 host with KVM (the cloud runs amd64), push, and run it:
+Build on an x86_64 host with KVM, push, and run it:
```bash test="cli-shape" id="cua-image-build"
cua image build minecraft.json \
diff --git a/docs/content/docs/cua-sdk/guides/browse-the-web.mdx b/docs/content/docs/cua-sdk/guides/browse-the-web.mdx
deleted file mode 100644
index 25d9b04150..0000000000
--- a/docs/content/docs/cua-sdk/guides/browse-the-web.mdx
+++ /dev/null
@@ -1,153 +0,0 @@
----
-title: Browse the web from your agent with Cua
-description: Give a coding agent (Claude Code, Codex, Cursor and others) a real browser inside a disposable sandbox with nothing but the cua MCP server. Discover an image, create a browser sandbox, read, click, fill and screenshot pages, teleport a signed-in session with consent, and clean up.
----
-
-Once Cua is installed, a coding agent can browse the web with no other tool or
-setup. The browser runs inside a sandbox, never on your machine: a local
-container (gVisor when installed), or a VM. The agent
-drives it through the sandbox's own Cua Driver, whose typed browser tools the
-`cua` MCP server reaches with `call_tool`.
-
-## Set up your agent
-
-`cua agents setup` installs the Cua skills (the `cua-sandboxes` skill carries
-the browsing recipe) and adds the `cua` MCP server to every agent it finds.
-
-```bash test="cli-shape" id="browse-setup"
-cua agents setup --agents claude,codex,cursor -y
-```
-
-Restart the agent. Everything below is what it does with the `cua` MCP tools.
-
-## 1. Pick an image
-
-`images_list` returns the image catalog the
-[image catalog details](/cua-sdk/reference/os-image-catalog) is generated from:
-each image's OS, container or VM form, runtimes, whether it ships cua-spacesd,
-and its browsers. `browser_tools: true` marks the images whose browser the
-Cua Driver browser tools drive.
-
-```python test="excerpt" id="browse-discover" source="tests/e2e/browse/e2e_browse.py#discover"
-cat = await agent.ok("images_list", {"browser": True})
-images = [i for i in cat["images"] if i["browser_tools"]]
-```
-
-The same list from a terminal:
-
-```bash test="cli-shape" id="browse-images"
-cua images ls --browser
-```
-
-## 2. Create a sandbox with a browser
-
-`sandbox_create` with `browser: true` starts the canonical Linux image
-(`ghcr.io/trycua/linux:24.04`), launches Chromium with a fresh throwaway
-profile inside it, binds the window for the browser tools and, with `url`,
-opens a first page. It runs on this machine by default. It returns the
-sandbox `id` and the `session`, `target_id` and `tab_id` every browser call
-takes.
-
-```python test="excerpt" id="browse-create" source="tests/e2e/browse/e2e_browse.py#create"
-sb = await agent.ok("sandbox_create", create)
-space = sb["id"]
-ids = {
- "session": sb["session"],
- "target_id": sb["browser"]["target_id"],
- "tab_id": sb["browser"]["tab_id"],
-}
-```
-
-From a terminal, the same sandbox (watch it with `cua sb view`):
-
-```bash test="cli-shape" id="browse-create-cli"
-cua sb create --browser --open https://example.com --name web
-```
-
-## 3. Read, click, type
-
-Every browser action is a `call_tool` on the sandbox with the ids above plus
-the tool's own arguments:
-
-| Tool | Arguments | Does |
-|---|---|---|
-| `get_browser_state` | `snapshot_format: "semantic_v2"`, `include_screenshot` | Reads the page: an outline and refs such as `p2:0`; optionally the tab as an image |
-| `browser_navigate` | `url` | Opens a URL |
-| `browser_click` | `ref`, `delivery_mode: "foreground"` | Clicks an element |
-| `browser_type` | `ref`, `text`, `replace` | Types; `replace: true` fills a field; text `"\n"` with `mode: "keystrokes"` presses Enter |
-| `browser_pointer` | `action`, `ref` | Hover, double-click, right-click, scroll, drag |
-
-A small helper keeps the calls short:
-
-```python test="excerpt" id="browse-helpers" source="tests/e2e/browse/e2e_browse.py#helpers"
-async def driver(tool: str, **args) -> dict:
- return await agent.ok(
- "call_tool", {"space": space, "tool": tool, "arguments": {**ids, **args}}
- )
-
-async def read() -> dict:
- return await driver("get_browser_state", snapshot_format="semantic_v2")
-
-async def click(ref: str) -> None:
- # In a sandbox nobody else uses the browser window, so the
- # trusted route may activate it (Linux Chromium needs that).
- await driver("browser_click", ref=ref, delivery_mode="foreground")
-```
-
-Refs belong to the read that returned them and stay valid until the page
-changes. Read again after a navigation or a submit.
-
-## 4. Test a page served in the sandbox
-
-The sandbox is a whole computer: serve your app in it (`space_write`,
-`space_bash`) and browse `http://127.0.0.1:<port>`. This fills and submits a
-form:
-
-```python test="excerpt" id="browse-fill" source="tests/e2e/browse/e2e_browse.py#fill"
-await driver("browser_navigate", url=f"http://127.0.0.1:{FORM_PORT}/")
-# One read; its refs stay valid until the page changes.
-page = await read()
-name_ref = find_ref(page, "textbox", "Name")
-agree_ref = find_ref(page, "checkbox", "I agree")
-submit_ref = find_ref(page, "button", "Submit")
-await driver("browser_type", ref=name_ref, text="Ada Lovelace", replace=True)
-await click(agree_ref)
-await click(submit_ref)
-```
-
-## 5. Sign in with your own session (with consent)
-
-To browse as you on a site you are signed in to, the agent can teleport that
-site's session from your browser (Firefox or Chrome) into the sandbox with
-`teleport_browser_session`. It names the exact sites; nothing is selected by
-default and there is no "all sessions" option. The first call moves nothing:
-it returns what would move and a consent requirement, which the agent shows
-you. Only your explicit approval moves those sites' sessions into the
-sandbox. Delete the sandbox, or sign out there, to end them.
-
-## 6. Clean up
-
-```python test="excerpt" id="browse-cleanup" source="tests/e2e/browse/e2e_browse.py#cleanup"
-await agent.call("sandbox_delete", {"name": space})
-```
-
-## Run the whole session
-
-[`tests/e2e/browse/e2e_browse.py`](https://github.com/trycua/cua/blob/main/tests/e2e/browse/e2e_browse.py)
-runs every step above as an MCP client (the official MCP Python SDK) against
-`cua mcp`, with no model in the loop. CI runs it in the container lane.
-
-```bash skip="host-install"
-pip install mcp
-CUA_E2E_BROWSE=1 python tests/e2e/browse/e2e_browse.py
-```
-
-## What the browser tools cover
-
-Reading pages (outline, refs, text, a scoped `query`), navigation, clicks,
-typing and filling, Enter, hover, scroll, drag, uploads (`browser_set_input_files`),
-downloads (`browser_download`), page dialogs (`browser_dialog`) and tab
-screenshots. They drive Chromium-family browsers over the Chrome DevTools
-Protocol. Firefox ships in the image too; drive it with the desktop tools
-(`computer_screenshot`, `computer_click`). Waiting is a bounded loop of reads;
-there is no JavaScript `eval`, network interception or cookie editing tool.
diff --git a/docs/content/docs/cua-sdk/guides/coding-agent-options.mdx b/docs/content/docs/cua-sdk/guides/coding-agent-options.mdx
deleted file mode 100644
index 3ecee70a06..0000000000
--- a/docs/content/docs/cua-sdk/guides/coding-agent-options.mdx
+++ /dev/null
@@ -1,128 +0,0 @@
----
-title: Configure coding agents
-description: Give a sandboxed coding agent MCP servers, a custom endpoint, and credentials; the supported harnesses and the event kinds they emit.
----
-
-These options extend [Run a coding agent in a sandbox](/cua-sdk/guides/run-a-coding-agent).
-The examples are regions of
-[`examples/agents-in-sandboxes/tour.py`](https://github.com/trycua/cua/blob/main/examples/agents-in-sandboxes/tour.py).
-
-## Give the agent MCP servers
-
-Every run gets the sandbox's own MCP tools (cua-driver: screen, input,
-windows) unless `sandbox_mcp=False` or the harness cannot take them (Pi has no MCP client, Hermes and OpenClaw read MCP only from their own config;
-Antigravity is off by default, see the table). Add more with `mcp_servers`: a URL
-(streamable HTTP, as reachable from inside the sandbox) or a command (stdio,
-run in the sandbox). Header values may be secrets; they are handled like keys.
-
-```python test="excerpt" id="mcp" source="examples/agents-in-sandboxes/tour.py#mcp"
-run = await agents.run(
- "openai-codex",
- "Use the docs server to look up our API style guide, then review api.py.",
- cua.AgentRunOptions(
- env_from_host=["OPENAI_API_KEY"],
- mcp_servers=[
- cua.AgentRunMcpServer(name="docs", url="https://mcp.example.com/mcp",
- headers={"Authorization": "Bearer <token>"}),
- cua.AgentRunMcpServer(name="fs", command="npx",
- args=["-y", "@modelcontextprotocol/server-filesystem", "/srv"]),
- ],
- exit_when_idle=True,
- ),
-)
-```
-
-```bash test="cli-shape" id="cli-mcp"
-cua agent run local:dev openai-codex "Review api.py" --env-from-host OPENAI_API_KEY \
- --mcp docs=https://mcp.example.com/mcp --no-sandbox-mcp
-```
-
-## Use a custom endpoint or proxy
-
-`base_url` points the harness at a gateway, proxy or compatible server;
-`wire` picks its format (`anthropic`, `openai-responses`, `openai-chat`,
-`gemini`) when it differs from the harness's own.
-
-```python test="excerpt" id="endpoint" source="examples/agents-in-sandboxes/tour.py#endpoint"
-run = await agents.run(
- "claude-code",
- "Summarize the repository in five bullet points.",
- cua.AgentRunOptions(
- env={"ANTHROPIC_API_KEY": "<gateway key>"},
- base_url="https://llm-gateway.internal.example.com",
- model="claude-sonnet-4-5",
- exit_when_idle=True,
- ),
-)
-```
-
-```bash test="cli-shape" id="cli-endpoint"
-cua agent run local:dev claude-code "Summarize the repository" \
- --env-from-host ANTHROPIC_API_KEY --base-url https://llm-gateway.internal.example.com \
- --model <model-id>
-```
-
-## Harnesses
-
-```bash test="cli-shape" id="cli-harnesses"
-cua agent harnesses
-```
-
-```python test="docs" id="harness-ids"
-import json
-
-import cua
-
-print([h["id"] for h in json.loads(cua.agent_harnesses())])
-# ['claude-code', 'openai-codex', 'gemini-cli', 'google-antigravity', 'opencode', 'goose', 'pi', 'hermes', 'openclaw']
-```
-
-| Harness | Key variables (any one) | Endpoint wire | Notes |
-| --- | --- | --- | --- |
-| `claude-code` | `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN` | `anthropic` | |
-| `openai-codex` | `OPENAI_API_KEY`, `CODEX_API_KEY` | `openai-responses` | |
-| `gemini-cli` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | `gemini` | Needs a paid API key |
-| `google-antigravity` | `GEMINI_API_KEY` | `gemini` | Headless ACP server, no terminal CLI; sandbox MCP off by default |
-| `opencode` | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY` | `openai-chat` | |
-| `goose` | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `OPENROUTER_API_KEY` | `openai-chat` | |
-| `pi` | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY` | `openai-chat` | Community ACP adapter; no MCP client |
-| `hermes` | `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | `openai-chat` | Needs git; ignores run MCP servers |
-| `openclaw` | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY` | `openai-chat` | Starts its own loopback Gateway; no per-run MCP servers |
-
-`cua agent harnesses` (or `cua.agent_harnesses()`) prints the full record:
-what each installs, its interactive CLI, and known limits.
-
-## Credentials
-
-- Keys reach a run only as explicit per-run env (`env`, `env_from_host`,
- `--env-from-host`). They are written with mode 0600 in the run's directory,
- redacted from its event log, and never passed in argv.
-- Nothing is copied from your machine's agent config (`~/.claude`, `~/.codex`,
- and so on).
-- To use a signed-in session instead of a key, move it with
- [teleport](/spaces/guides/teleport-an-app) (`claude-code` is a
- built-in app), which shows what will move and asks for approval first.
-- See also [Pass secrets safely](/cua-sdk/guides/secrets).
-
-## Event kinds
-
-Each event has `seq`, `turn`, `kind`, optional `text` and tool fields, a
-one-line `line` rendering, and `json` (the raw record, ACP payload included).
-
-| Kind | Meaning |
-| --- | --- |
-| `install` | Installing the harness or its dependencies |
-| `initialized`, `authenticated`, `session`, `mode` | ACP setup |
-| `turn_started` | A prompt or follow-up began (`text` is the prompt) |
-| `message`, `thought` | Agent text and reasoning |
-| `user_message` | A user message the agent echoed |
-| `tool_call`, `tool_update` | A tool call and its progress (`tool_title`, `tool_kind`, `tool_status`) |
-| `plan` | The agent's plan entries |
-| `usage` | Token usage update |
-| `permission` | A permission request, auto-approved (the sandbox is the boundary) |
-| `commands`, `info`, `notice` | Available commands and informational updates |
-| `cancel_requested` | `interrupt()` was received |
-| `turn_ended` | The turn finished (`stop_reason`, usage) |
-| `error` | A harness or provider error |
-| `exited` | The run's process ended |
-| `other` | Anything else the harness sent |
diff --git a/docs/content/docs/cua-sdk/guides/contrib-providers.mdx b/docs/content/docs/cua-sdk/guides/contrib-providers.mdx
deleted file mode 100644
index 2a38407d6b..0000000000
--- a/docs/content/docs/cua-sdk/guides/contrib-providers.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: Run on other sandbox providers (contrib)
-description: Run cua sandboxes on E2B, Daytona or Modal with --on e2b, --on daytona or --on modal, from the same registry images, with cua-spacesd, services and cua doctor.
----
-
-Contrib providers run the same images (the canonical `ghcr.io/trycua/linux`, or any registry image) on third-party sandbox platforms. The location is one more `--on` word: `--on e2b`, `--on daytona`, `--on modal`. Everything above the location works unchanged: services, `sb.spacesd()`, `cua doctor`, cua-bench.
-
-To run in a cloud account you own (AWS, Google Cloud, Modal), see [Use your own cloud](/cua-sdk/guides/your-cloud): it needs no provider key, and its sandboxes join the cua.ai relay. Contrib providers are opt-in. The default `cua` build knows the words and tells you how to get the provider; a build with `--features contrib` includes them.
-
-## Set up
-
-```bash skip="host-install"
-cargo install --locked --path libs/cua/crates/cua-cli --features contrib
-cua auth provider set e2b # reads E2B_API_KEY from stdin, never echoed
-cua auth provider ls # where each key comes from, never the value
-```
-
-An environment variable wins over a stored key: `E2B_API_KEY`, `DAYTONA_API_KEY`, or `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET`.
-
-Modal documents no HTTP API, so `--on modal` goes through Modal's official Go SDK in a small helper, `cua-modal-helper`. Build it once and put it next to `cua` or on `PATH` (or point `CUA_MODAL_HELPER` at it):
-
-```bash skip="host-install"
-(cd libs/cua/crates/cua-contrib/modal-helper && go build -o ~/.local/bin/cua-modal-helper .)
-```
-
-## Create a sandbox
-
-```bash test="cli-shape" id="contrib-cli"
-cua sb create linux --on e2b --name demo
-cua doctor e2b:demo --strict
-cua sb delete e2b:demo
-```
-
-The ref is `<provider>:<name>` (`e2b:demo`, `daytona:demo`). `--claim-ttl` sets the platform's lifetime backstop (default one hour).
-
-```python test="contrib" id="contrib-python" prelude="contrib"
-from cua_sandbox import Image, Sandbox
-
-async with Sandbox.ephemeral(Image.linux(), on="daytona") as sb:
- await sb.files.write_text("/tmp/hello.txt", "hello from daytona")
- print(await sb.files.read_text("/tmp/hello.txt")) # hello from daytona
-```
-
-cua-bench takes the same word: `cb run task <task> --on e2b`.
-
-## What happens to the image
-
-The SDK resolves and pins the image first, then maps it onto the platform:
-
-| Provider | Image step | Cached by | Entrypoint |
-|---|---|---|---|
-| E2B | a template built `fromImage` | digest, start command, shape | runs once at build (E2B snapshots it); the SDK installs the cua-spacesd token |
-| Daytona | a snapshot from `imageName` | digest, entrypoint, shape | runs in every sandbox, with the token in its environment |
-| Modal | `FROM` the pinned image, `ENTRYPOINT []` | Modal's image cache | the image's `ENTRYPOINT` and `CMD` as the command, with the token in its environment |
-
-A moved tag gets a new template. Requests a provider cannot run fail before any API call, with a typed error: VM variants (`--vm`), images without an amd64 build, Windows and macOS images, `network="none"`, sidecars, and (Daytona, Modal) private registries. Modal tunnels are fixed at create: declare every port with `--port`.
-
-## Ports and services
-
-Declared services and cua-spacesd (3211) are reachable through the provider's HTTPS URLs; `sb.service(name).url()` and `sb.tunnel.forward(port)` return them. Ports are public on the provider's proxy: cua-spacesd authenticates with its own token, so keep other services authenticated too.
-
-## Support matrix
-
-Measured nightly: each provider's lane creates `ghcr.io/trycua/linux:24.04`, runs `cua doctor <ref> --strict --json` inside it, and the table below is generated from the latest reports. A regression shows up here on the next run.
-
-{/* GENERATED:contrib-matrix:start */}
-
-| Provider | Kind | Verdict | display | input | streaming | audio | files | process | teleport | tunnels | mcp | auth | Measured |
-|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
-| e2b | container | not measured | - | - | - | - | - | - | - | - | - | - | never |
-| daytona | container | not measured | - | - | - | - | - | - | - | - | - | - | never |
-| modal | container | not measured | - | - | - | - | - | - | - | - | - | - | never |
-
-{/* GENERATED:contrib-matrix:end */}
-
-`full`: the desktop works (display, input through cua-driver, streaming, files, auth). `container-only`: cua-spacesd answers but the desktop does not. `headless-only`: no cua-spacesd answered. `not measured`: no run yet.
diff --git a/docs/content/docs/cua-sdk/guides/cua-cloud-ended.mdx b/docs/content/docs/cua-sdk/guides/cua-cloud-ended.mdx
index f231294a53..ea19389475 100644
--- a/docs/content/docs/cua-sdk/guides/cua-cloud-ended.mdx
+++ b/docs/content/docs/cua-sdk/guides/cua-cloud-ended.mdx
@@ -1,23 +1,26 @@
---
-title: Cua Cloud (Fleets) has ended
-description: Cua Cloud and Cua Fleets ended on 18 October 2026. What changed and where to run sandboxes now.
+title: Migrate from Cua Cloud and deprecated packages
+description: Cua Cloud and Fleets ended on 18 October 2026, and cuabot, cua-computer, cua-computer-server and cua-agent are no longer maintained. What changed and what to use instead.
---
+import { Callout } from 'fumadocs-ui/components/callout';
+
+## Cua Cloud (Fleets) has ended
+
Cua Cloud, including Cua Fleets (pools, claims, warm replicas and the Terraform
-provider), ended on 18 October 2026. The Fleets pages that used to be here have
-been removed.
+provider), ended on 18 October 2026. The Fleets pages have been removed.
-## What still works
+### What still works
The same SDK calls, images and `cua` CLI commands run anywhere else:
| Where | How | Guide |
| --- | --- | --- |
-| This machine | `Sandbox.create(...)` (the default), `cua sb create` | [Set up local runtimes](/cua-sdk/guides/local-runtimes) |
-| Your own AWS, Google Cloud or Modal account | `on="aws"`, `on="gcp"`, `on="modal"`; `--on aws` in the CLI | [Use your own cloud](/cua-sdk/guides/your-cloud) |
+| This machine | `Sandbox.create(...)` (the default), `cua sb create` | [Choose where sandboxes run](/cua-sdk/guides/local-runtimes#this-machine) |
+| Your own AWS, Google Cloud or Modal account | `on="aws"`, `on="gcp"`, `on="modal"`; `--on aws` in the CLI | [Choose where sandboxes run](/cua-sdk/guides/local-runtimes#your-own-cloud) |
| A machine you run, shared with your team and agents | Cua Spaces | [Cua Spaces](/spaces) |
-## In your code
+### In your code
`on="cloud"`, `local=False`, `--on cloud` and `pool:` image references fail
with this message:
@@ -32,12 +35,87 @@ the `cua` CLI.
Replace `on="cloud"` with a local runtime or your own cloud. Sidecars,
services, secrets and images work the same way there:
-[Sidecars](/cua-sdk/guides/sidecars), [Services](/cua-sdk/guides/services),
-[Secrets](/cua-sdk/guides/secrets), [Images](/cua-sdk/guides/images).
+[Sidecars](/cua-sdk/guides/services#sidecars), [services](/cua-sdk/guides/services),
+[secrets](/cua-sdk/guides/services#secrets) and [images](/cua-sdk/guides/images).
Fleet pool names, claim TTLs and warm-replica settings have no replacement.
Your own cloud gives each sandbox a time limit and cleans up after it
-([Time limits and cleanup](/cua-sdk/guides/your-cloud#time-limits-and-cleanup)).
+([Time limits and cleanup](/cua-sdk/guides/local-runtimes#time-limits-and-cleanup)).
Questions: [GitHub issues](https://github.com/trycua/cua/issues) or
[Discord](https://discord.com/invite/mVnXXpdE85).
+
+## Deprecated packages
+
+<Callout type="warn" title="Deprecated">
+ Cua no longer maintains `cuabot`, `cua-computer`, `cua-computer-server` or
+ `cua-agent`. They will not receive updates or fixes. Existing releases stay on
+ npm and PyPI, so current installs keep installing, but you should move off them.
+</Callout>
+
+<Callout type="error" title="Do not run cuabot">
+ `cuabot` has known security issues and is no longer maintained. Do not run it.
+ If it is installed, [stop and remove it](#cuabot) now.
+</Callout>
+
+| Package | Registry | Last release | Use instead |
+| --- | --- | --- | --- |
+| `cuabot` | npm | 1.0.14 | [Cua Driver](/cua-driver) over MCP, or a sandbox from the [`cua` CLI](/cua-sdk/quickstart) or [Cua Spaces](/spaces) |
+| `cua-computer` | PyPI | 0.5.19 | The [`cua` SDK](/cua-sdk/quickstart) (`cua-sandbox`) for sandboxes, [Cua Driver](/cua-driver) for the machine you are on |
+| `cua-computer-server` | PyPI | 0.3.46 | Images that ship [cua-spacesd](/cua-sdk/guides/spacesd), or [Cua Driver](/cua-driver) on a host |
+| `cua-agent` | PyPI | 0.9.0 | A coding agent with the [Cua Driver MCP](/cua-driver/guides/connect-your-agent), or [`sandbox.agents()`](/cua-sdk/guides/run-a-coding-agent) |
+
+### cuabot
+
+`cuabot` ran coding agents in a Docker sandbox with a local server and a
+desktop you could watch. Stop it, uninstall it and remove what it created:
+
+```bash skip="destructive"
+cuabot --stop # repeat with --name <session> for each named session
+npm uninstall -g cuabot # or delete any local node_modules/cuabot
+docker rm -f cuabot-xpra
+docker images -q trycua/cuabot | xargs docker rmi
+rm -rf ~/.cuabot
+```
+
+Instead:
+
+- To let Claude Code, Codex, Cursor or another agent operate apps on your
+ machine, [connect it to Cua Driver](/cua-driver/guides/connect-your-agent).
+- To give an agent its own computer that you can watch,
+ [create a Space](/spaces/guides/add-a-space) or a sandbox with the
+ [`cua` CLI](/cua-sdk/quickstart), then
+ [run the agent in it](/cua-sdk/guides/run-a-coding-agent).
+
+### cua-computer
+
+`cua-computer` was the Python `Computer` class that started a VM or container
+and drove it through `cua-computer-server`. Use the `cua` SDK instead: it
+creates local sandboxes and sandboxes in your own cloud, and `Sandbox` exposes the screen, input,
+shell and files. Start with the [SDK quickstart](/cua-sdk/quickstart) and the
+[sandbox reference](/cua-sdk/reference/python/sandbox).
+
+To operate native apps on the machine you are on, use
+[Cua Driver](/cua-driver/quickstart).
+
+### cua-computer-server
+
+`cua-computer-server` was the HTTP and WebSocket server inside a guest that
+`cua-computer` talked to. The in-guest agent is now
+[cua-spacesd](/cua-sdk/guides/spacesd), which Cua Spaces and the current
+sandbox images ship. Nothing in the `cua` SDK talks to `cua-computer-server`
+any more. Images built before that change still carry it; see the
+[image catalog](/cua-sdk/reference/os-image-catalog) for which ones.
+
+To drive a desktop directly, install [Cua Driver](/cua-driver/quickstart) on it.
+
+### cua-agent
+
+`cua-agent` was the Python `ComputerAgent` loop with LiteLLM. Bring your own
+agent instead:
+
+- Connect Claude Code, Codex, Cursor, OpenClaw or another agent to the
+ [Cua Driver MCP server](/cua-driver/guides/connect-your-agent).
+- Run a coding agent inside a sandbox with
+ [`sandbox.agents()` or `cua agent run`](/cua-sdk/guides/run-a-coding-agent).
+- Score agents on tasks with [Cua Bench](/cua-bench).
diff --git a/docs/content/docs/cua-sdk/guides/desktop.mdx b/docs/content/docs/cua-sdk/guides/desktop.mdx
index 690de7f155..35953bae26 100644
--- a/docs/content/docs/cua-sdk/guides/desktop.mdx
+++ b/docs/content/docs/cua-sdk/guides/desktop.mdx
@@ -1,6 +1,6 @@
---
-title: Control the desktop
-description: Take screenshots, click and type, call typed Cua Driver tools, open a shell or a browser view, and attach to any cua-spacesd.
+title: Control the desktop and the browser
+description: Take screenshots, click and type, call typed Cua Driver tools, open a shell or a browser view, give an agent a browser, read Space thumbnails, and attach to any cua-spacesd.
---
import { Callout } from 'fumadocs-ui/components/callout';
@@ -193,6 +193,200 @@ Sharing stops when you close the page or click Stop.
Images without cua-spacesd that serve their own web display page open with
`cua sb view NAME --service <service>`.
+## Give an agent a browser
+
+A coding agent can browse the web with the `cua` MCP server and nothing else.
+The browser runs inside a sandbox, never on your machine: in a local container
+(gVisor when installed) or a VM. The agent drives it through the sandbox's own
+Cua Driver, and the `cua` MCP server reaches Cua Driver's typed browser tools
+with `call_tool`.
+
+### Set up your agent
+
+`cua agents setup` installs the Cua skills (the `cua-sandboxes` skill carries
+the browsing recipe) and adds the `cua` MCP server to every agent it finds.
+
+```bash test="cli-shape" id="browse-setup"
+cua agents setup --agents claude,codex,cursor -y
+```
+
+Restart the agent. The rest of this section is what the agent does with the
+`cua` MCP tools.
+
+### Pick an image
+
+`images_list` returns the image catalog that the
+[image catalog details](/cua-sdk/reference/os-image-catalog) page is generated
+from: each image's OS, container or VM form, runtimes, whether it ships
+cua-spacesd, and its browsers. `browser_tools: true` marks the images whose
+browser the Cua Driver browser tools drive.
+
+```python test="excerpt" id="browse-discover" source="tests/e2e/browse/e2e_browse.py#discover"
+cat = await agent.ok("images_list", {"browser": True})
+images = [i for i in cat["images"] if i["browser_tools"]]
+```
+
+The same list from a terminal:
+
+```bash test="cli-shape" id="browse-images"
+cua images ls --browser
+```
+
+### Create a sandbox with a browser
+
+`sandbox_create` with `browser: true` starts the canonical Linux image
+(`ghcr.io/trycua/linux:24.04`) on this machine, launches Chromium with a fresh
+throwaway profile, and binds the window for the browser tools. With `url` it
+also opens a first page. It returns the sandbox `id` and the `session`,
+`target_id` and `tab_id` that every browser call takes.
+
+```python test="excerpt" id="browse-create" source="tests/e2e/browse/e2e_browse.py#create"
+sb = await agent.ok("sandbox_create", create)
+space = sb["id"]
+ids = {
+ "session": sb["session"],
+ "target_id": sb["browser"]["target_id"],
+ "tab_id": sb["browser"]["tab_id"],
+}
+```
+
+From a terminal, create the same sandbox and watch it with `cua sb view`:
+
+```bash test="cli-shape" id="browse-create-cli"
+cua sb create --browser --open https://example.com --name web
+```
+
+### Read, click and type
+
+Every browser action is a `call_tool` on the sandbox with the ids above plus
+the tool's own arguments:
+
+| Tool | Arguments | Does |
+|---|---|---|
+| `get_browser_state` | `snapshot_format: "semantic_v2"`, `include_screenshot` | Reads the page: an outline and refs such as `p2:0`; optionally the tab as an image |
+| `browser_navigate` | `url` | Opens a URL |
+| `browser_click` | `ref`, `delivery_mode: "foreground"` | Clicks an element |
+| `browser_type` | `ref`, `text`, `replace` | Types; `replace: true` fills a field; text `"\n"` with `mode: "keystrokes"` presses Enter |
+| `browser_pointer` | `action`, `ref` | Hover, double-click, right-click, scroll, drag |
+
+A small helper keeps the calls short:
+
+```python test="excerpt" id="browse-helpers" source="tests/e2e/browse/e2e_browse.py#helpers"
+async def driver(tool: str, **args) -> dict:
+ return await agent.ok(
+ "call_tool", {"space": space, "tool": tool, "arguments": {**ids, **args}}
+ )
+
+async def read() -> dict:
+ return await driver("get_browser_state", snapshot_format="semantic_v2")
+
+async def click(ref: str) -> None:
+ # In a sandbox nobody else uses the browser window, so the
+ # trusted route may activate it (Linux Chromium needs that).
+ await driver("browser_click", ref=ref, delivery_mode="foreground")
+```
+
+Refs belong to the read that returned them and stay valid until the page
+changes. Read again after a navigation or a submit.
+
+The sandbox is a whole computer, so you can also serve your app in it
+(`space_write`, `space_bash`) and browse `http://127.0.0.1:<port>`. This fills
+and submits a form:
+
+```python test="excerpt" id="browse-fill" source="tests/e2e/browse/e2e_browse.py#fill"
+await driver("browser_navigate", url=f"http://127.0.0.1:{FORM_PORT}/")
+# One read; its refs stay valid until the page changes.
+page = await read()
+name_ref = find_ref(page, "textbox", "Name")
+agree_ref = find_ref(page, "checkbox", "I agree")
+submit_ref = find_ref(page, "button", "Submit")
+await driver("browser_type", ref=name_ref, text="Ada Lovelace", replace=True)
+await click(agree_ref)
+await click(submit_ref)
+```
+
+### Sign in with your own session
+
+To browse as you on a site where you are signed in, the agent can teleport
+that site's session from your browser (Firefox or Chrome) into the sandbox
+with `teleport_browser_session`. It names the exact sites. Nothing is selected
+by default, and there is no "all sessions" option. The first call moves
+nothing: it returns what would move and a consent requirement, which the agent
+shows you. Only your approval moves those sites' sessions into the sandbox.
+Delete the sandbox, or sign out there, to end them.
+
+### Clean up
+
+```python test="excerpt" id="browse-cleanup" source="tests/e2e/browse/e2e_browse.py#cleanup"
+await agent.call("sandbox_delete", {"name": space})
+```
+
+### What the browser tools cover
+
+Reading pages (outline, refs, text, a scoped `query`), navigation, clicks,
+typing and filling, Enter, hover, scroll, drag, uploads
+(`browser_set_input_files`), downloads (`browser_download`), page dialogs
+(`browser_dialog`) and tab screenshots. They drive Chromium-family browsers
+over the Chrome DevTools Protocol. Firefox ships in the image too: drive it
+with the desktop tools (`computer_screenshot`, `computer_click`). Waiting is a
+bounded loop of reads. There is no JavaScript `eval`, network interception or
+cookie editing tool.
+
+## Thumbnails
+
+For a small preview of a Space (a tile, a list row, a placeholder while a
+stream connects), use `Space.thumbnail` instead of `screenshot`. It returns a
+small JPEG of the primary display and when it was captured, from a cache that
+every client on the machine shares: the Spaces app, the CLI and your scripts.
+
+A cached image younger than `max_age_ms` comes back at once. Otherwise the SDK
+captures a fresh one through cua-spacesd and keeps it for the next caller. If
+that capture fails, you get the older image, and `captured_at_ms` says how old
+it is.
+
+<Tabs groupId="language" persist items={['Python', 'TypeScript', 'Swift']}>
+ <Tab value="Python">
+
+```python skip="no-runner"
+import cua
+
+space = await cua.connect().spaces().space("local:dev")
+thumb = await space.thumbnail(max_age_ms=120_000) # None: any age
+print(thumb.width, thumb.height, thumb.captured_at_ms)
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```ts skip="no-runner"
+import { connect } from '@trycua/cua';
+
+const space = await connect().spaces().space('local:dev');
+const thumb = await space.thumbnail(120_000n); // undefined: any age
+console.log(thumb.width, thumb.height, thumb.capturedAtMs);
+```
+
+ </Tab>
+ <Tab value="Swift">
+
+```swift skip="no-runner"
+import Cua
+
+let space = try await Cua.connect(address: nil, token: nil).spaces().space(space: "local:dev")
+let thumb = try await space.thumbnail(maxAgeMs: 120_000) // nil: any age
+print(thumb.width, thumb.height, thumb.capturedAtMs)
+```
+
+ </Tab>
+</Tabs>
+
+The cua daemon keeps the cache under `~/.cua/cache/thumbnails`: the latest
+image per Space, dropped when the Space is deleted, and capped at 32 MB (the
+oldest images go first). While any client has asked for a thumbnail in the last
+10 minutes, the daemon captures a new one for each running Space about every
+90 seconds. When nobody asks, it captures nothing and puts no load on the
+guests.
+
## Attach to or run spacesd
To use any machine that runs cua-spacesd, or to run it yourself, see
diff --git a/docs/content/docs/cua-sdk/guides/disk-usage.mdx b/docs/content/docs/cua-sdk/guides/disk-usage.mdx
deleted file mode 100644
index 27f33b6a66..0000000000
--- a/docs/content/docs/cua-sdk/guides/disk-usage.mdx
+++ /dev/null
@@ -1,79 +0,0 @@
----
-title: Disk usage and cleanup
-description: What local sandboxes keep on disk and how the SDK keeps it bounded.
----
-
-Images, VM disks and logs live under `~/.cua` (`CUA_HOME` moves them).
-
-```bash test="cli-shape" id="cua-cache-du"
-cua cache du # usage per category, budget, free space
-cua sb ls # SIZE column (--no-size skips it)
-```
-
-## Automatic cleanup
-
-- **Cache budget.** Pulled images, macOS base VMs and local builds share one
- budget: 30 GiB or 10% of free space, whichever is smaller. Least recently
- used entries go first, after every pull and build and when the daemon is
- idle.
-- **Never removed:** sandboxes (running or stopped), anything a sandbox uses,
- checkpoints, and Docker objects the SDK did not create or pull.
-- **Base images stay over budget** when a sandbox was created from them, when
- they are this release's macOS or Linux default, or when a create from them
- failed (so the retry does not download it again). `cua cache prune --all`
- removes every base no sandbox uses.
-- **Ephemeral sandboxes** are deleted with their handle. If the program
- crashes, the next `cua sb` command or the daemon deletes them 10 minutes
- later.
-- **Logs** are capped at 10 MiB per file (also the Lume installer's `/tmp`
- logs when cua installed Lume).
-- **Screenshots** from `cua do screenshot` without `--save` go to
- `~/.cua/screenshots`; the newest 20 are kept.
-
-## Free space now
-
-```bash test="cli-shape" id="cua-cache-prune"
-cua cache prune --dry-run # what would go
-cua cache prune # down to the budget
-cua cache prune --all # every unused cache entry
-cua sb rm my-box -f # a sandbox and all its disks
-```
-
-## Settings
-
-```bash test="cli-shape" id="cua-cache-config"
-cua cache config --budget 50G --min-free 10G
-```
-
-```json title="~/.cua/cache.json" test="config" id="cua-cache-json"
-{
- "budget": "50G",
- "min_free": "10G",
- "warn_free": "20G",
- "orphan_reap_minutes": 10,
- "auto_gc": true
-}
-```
-
-The environment wins: `CUA_CACHE_BUDGET` (`auto`, `off` or a size),
-`CUA_DISK_MIN_FREE` (default `5G`), `CUA_DISK_WARN_FREE` (`20G`),
-`CUA_ORPHAN_REAP_MINUTES` (`10`), `CUA_CACHE_AUTO_GC` (`0` turns it off).
-
-## Low disk
-
-A pull, build or VM create that would leave less than `CUA_DISK_MIN_FREE`
-fails before writing anything: `CuaError.InsufficientDisk` in the SDKs, exit
-code 7 in the CLI.
-
-```text output
-cua: insufficient disk: not enough disk space to pull ghcr.io/trycua/linux:24.04:
-it needs about 3.2 GiB and cua keeps 5.0 GiB free, but only 6.1 GiB is available
-on /Users/me/.cua/images (run `cua cache prune` to free space, or lower
-CUA_DISK_MIN_FREE)
-```
-
-## cua-bench results
-
-Kept until you remove them; cua-bench warns past 10 GiB
-(`CUA_BENCH_WARN_SIZE`). Keep fewer with `cb run ... --keep-runs 20` or
-`cb prune --runs --keep 20`.
diff --git a/docs/content/docs/cua-sdk/guides/images.mdx b/docs/content/docs/cua-sdk/guides/images.mdx
index 55f6e19e6e..eb98147808 100644
--- a/docs/content/docs/cua-sdk/guides/images.mdx
+++ b/docs/content/docs/cua-sdk/guides/images.mdx
@@ -1,6 +1,6 @@
---
title: Choose and build an image
-description: Pick a canonical or registry image, add packages and files, and pull private images, locally or in your own cloud.
+description: See every image Cua publishes, pick a canonical or registry image, add packages and files, and pull private images, locally or in your own cloud.
---
A sandbox runs one image reference. One resolver picks the variant each
@@ -24,15 +24,59 @@ Image.macos() # ghcr.io/trycua/macos:26 (Tahoe); Image.macos("15") for
| `Image.windows()` | QEMU VM from `windows:2022-disk` |
| `Image.macos()` | Lume VM (Apple silicon) |
-- Only `Image.linux()` ships cua-spacesd, so only it gets the computer
- interfaces. Reach the Windows and macOS images through services you declare.
+- The Linux, Windows and macOS 26 images ship cua-spacesd, so they get the
+ computer interfaces. macOS 15 runs the legacy guest agent: reach it through
+ services you declare.
- `CUA_IMAGE_LINUX`, `CUA_IMAGE_WINDOWS` and `CUA_IMAGE_MACOS` override the
defaults. The CLI takes the aliases `linux`, `windows`, `macos`,
`macos:tahoe` and `macos:sequoia`.
- Windows images do not include a Windows license. Confirm that your own
licenses cover your use, including hosting and virtualization rights.
-The full list is in the [image catalog details](/cua-sdk/reference/os-image-catalog).
+## Every published image
+
+Cua publishes these images on `ghcr.io/trycua`. The Linux, Windows, benchmark
+and macOS 26 images include [cua-spacesd](/spaces) and
+[cua-driver](/cua-driver), so they are ready for agentic workloads. Windows,
+macOS and tags ending in `-disk` are VMs; the rest are containers. For each
+image's runtimes and limits, see the
+[image catalog details](/cua-sdk/reference/os-image-catalog).
+
+{/* GENERATED:catalog-image-list:start */}
+### Linux
+
+- `ghcr.io/trycua/linux:24.04`
+- `ghcr.io/trycua/linux:24.04-disk` (VM)
+- `ghcr.io/trycua/linux:24.04-slim`
+- `ghcr.io/trycua/linux:24.04-slim-disk` (VM)
+- `ghcr.io/trycua/omarchy:edge`
+- `ghcr.io/trycua/omarchy:edge-disk` (VM)
+
+### Windows
+
+- `ghcr.io/trycua/windows:2022`
+
+### macOS
+
+- `ghcr.io/trycua/macos:26` (Tahoe)
+- `ghcr.io/trycua/macos:26-slim` (Tahoe 26 slim)
+- `ghcr.io/trycua/macos:15` (Sequoia)
+
+### Adapter benchmark images
+
+- `ghcr.io/trycua/bench-web:1.0` (run [MiniWoB++](/cua-bench/guides/adapter-benchmarks#miniwob), [WebVoyager](/cua-bench/guides/adapter-benchmarks#webvoyager), [Online-Mind2Web](/cua-bench/guides/adapter-benchmarks#online-mind2web), [WebGym](/cua-bench/guides/adapter-benchmarks#webgym))
+- `ghcr.io/trycua/bench-web:1.0-disk` (VM)
+- `ghcr.io/trycua/bench-osworld:verified` (run [OSWorld-Verified](/cua-bench/guides/adapter-benchmarks#osworld-verified))
+- `ghcr.io/trycua/bench-osworld:verified-disk` (VM)
+{/* GENERATED:catalog-image-list:end */}
+
+To start one, install the CLI. Then run `cua sb create <image> --name desk`
+and open its desktop with `cua sb view desk` (see
+[Any registry image](#any-registry-image)).
+
+```bash skip="host-install"
+curl -fsSL https://cua.ai/install.sh | sh
+```
## Any registry image
diff --git a/docs/content/docs/cua-sdk/guides/lifecycle.mdx b/docs/content/docs/cua-sdk/guides/lifecycle.mdx
index a69dc29594..f1eaa887e9 100644
--- a/docs/content/docs/cua-sdk/guides/lifecycle.mdx
+++ b/docs/content/docs/cua-sdk/guides/lifecycle.mdx
@@ -1,10 +1,11 @@
---
title: Manage sandbox lifecycle
-description: Create, keep, reconnect to, list, suspend and delete sandboxes, and run many at once.
+description: Create, keep, reconnect to, list, suspend and delete sandboxes, run many at once, and keep local disk use bounded.
---
Sandboxes run on this machine by default, so the examples pass no location.
-To use [your own cloud](/cua-sdk/guides/your-cloud) pass `on=` as in `Sandbox.create`.
+To use [your own cloud](/cua-sdk/guides/local-runtimes#your-own-cloud), pass
+`on="aws"` (or `"gcp"`, `"modal"`) to `Sandbox.create`.
## Ephemeral or kept
@@ -69,7 +70,7 @@ cua sb rm dev -f
```
Local sandboxes run until you delete them. In your own cloud, a sandbox
-deletes itself at its [time limit](/cua-sdk/guides/your-cloud#time-limits-and-cleanup).
+deletes itself at its [time limit](/cua-sdk/guides/local-runtimes#time-limits-and-cleanup).
## Run many at once
@@ -77,3 +78,80 @@ deletes itself at its [time limit](/cua-sdk/guides/your-cloud#time-limits-and-cl
Cap concurrency with an `asyncio.Semaphore` (every local sandbox uses host CPU,
memory and disk) and pass `return_exceptions=True` so one failure does not
cancel the rest.
+
+## Disk usage and cleanup
+
+Images, VM disks and logs live under `~/.cua` (`CUA_HOME` moves them).
+
+```bash test="cli-shape" id="cua-cache-du"
+cua cache du # usage per category, budget, free space
+cua sb ls # SIZE column (--no-size skips it)
+```
+
+### Automatic cleanup
+
+- **Cache budget.** Pulled images, macOS base VMs and local builds share one
+ budget: 30 GiB or 10% of free space, whichever is smaller. Least recently
+ used entries go first, after every pull and build and when the daemon is
+ idle.
+- **Never removed:** sandboxes (running or stopped), anything a sandbox uses,
+ checkpoints, and Docker objects the SDK did not create or pull.
+- **Base images stay over budget** when a sandbox was created from them, when
+ they are this release's macOS or Linux default, or when a create from them
+ failed (so the retry does not download it again). `cua cache prune --all`
+ removes every base no sandbox uses.
+- **Ephemeral sandboxes** are deleted with their handle. If the program
+ crashes, the next `cua sb` command or the daemon deletes them 10 minutes
+ later.
+- **Logs** are capped at 10 MiB per file (also the Lume installer's `/tmp`
+ logs when cua installed Lume).
+- **Screenshots** from `cua do screenshot` without `--save` go to
+ `~/.cua/screenshots`; the newest 20 are kept.
+
+### Free space now
+
+```bash test="cli-shape" id="cua-cache-prune"
+cua cache prune --dry-run # what would go
+cua cache prune # down to the budget
+cua cache prune --all # every unused cache entry
+cua sb rm my-box -f # a sandbox and all its disks
+```
+
+### Settings
+
+```bash test="cli-shape" id="cua-cache-config"
+cua cache config --budget 50G --min-free 10G
+```
+
+```json title="~/.cua/cache.json" test="config" id="cua-cache-json"
+{
+ "budget": "50G",
+ "min_free": "10G",
+ "warn_free": "20G",
+ "orphan_reap_minutes": 10,
+ "auto_gc": true
+}
+```
+
+The environment wins: `CUA_CACHE_BUDGET` (`auto`, `off` or a size),
+`CUA_DISK_MIN_FREE` (default `5G`), `CUA_DISK_WARN_FREE` (`20G`),
+`CUA_ORPHAN_REAP_MINUTES` (`10`), `CUA_CACHE_AUTO_GC` (`0` turns it off).
+
+### Low disk
+
+A pull, build or VM create that would leave less than `CUA_DISK_MIN_FREE`
+fails before writing anything: `CuaError.InsufficientDisk` in the SDKs, exit
+code 7 in the CLI.
+
+```text output
+cua: insufficient disk: not enough disk space to pull ghcr.io/trycua/linux:24.04:
+it needs about 3.2 GiB and cua keeps 5.0 GiB free, but only 6.1 GiB is available
+on /Users/me/.cua/images (run `cua cache prune` to free space, or lower
+CUA_DISK_MIN_FREE)
+```
+
+### cua-bench results
+
+Kept until you remove them; cua-bench warns past 10 GiB
+(`CUA_BENCH_WARN_SIZE`). Keep fewer with `cb run ... --keep-runs 20` or
+`cb prune --runs --keep 20`.
diff --git a/docs/content/docs/cua-sdk/guides/local-runtimes.mdx b/docs/content/docs/cua-sdk/guides/local-runtimes.mdx
index 4916c9f341..a7e3c86d3e 100644
--- a/docs/content/docs/cua-sdk/guides/local-runtimes.mdx
+++ b/docs/content/docs/cua-sdk/guides/local-runtimes.mdx
@@ -1,14 +1,27 @@
---
-title: Set up local runtimes
-description: Which runtime runs a local sandbox, how to check and set up the host, and how to pick a kind or runtime.
+title: Choose where sandboxes run
+description: Run sandboxes on this machine, in your own AWS, Google Cloud or Modal account, or on E2B, Daytona or Modal. Check the host, pick a runtime, and set the default.
---
import { Callout } from 'fumadocs-ui/components/callout';
-Local sandboxes run on this machine with no account. Local is the built-in
-default: omit `on=` (`local=` in cua-sandbox, `--on` in the CLI), or
-[change the default](#change-the-default).
-The SDK picks the kind and runtime from the image and starts it itself.
+A sandbox runs in one place. Pick it with `on=` in the SDK (`local=` in
+cua-sandbox) or `--on` in the CLI. Leave it out and the sandbox runs on this
+machine.
+
+| Where | `on` | What you set up |
+| --- | --- | --- |
+| [This machine](#this-machine) | `local` (the default) | A container engine, QEMU or Lume, with `cua runtime setup` |
+| [Your own cloud](#your-own-cloud) | `aws`, `gcp`, `modal` | `cua cloud connect` |
+| [Another provider](#other-sandbox-providers) | `e2b`, `daytona`, `modal` | The provider's API key, and a `cua` build with `--features contrib` |
+| A machine that runs cua-spacesd | `direct:<host:port>` | [Attach to or run cua-spacesd](/cua-sdk/guides/spacesd) |
+
+To change where sandboxes run by default, see [Change the default](#change-the-default).
+
+## This machine
+
+Local sandboxes run on this machine with no account. The SDK picks the kind
+and runtime from the image and starts it itself.
| Image | Runtime (`auto`) |
| --- | --- |
@@ -17,7 +30,7 @@ The SDK picks the kind and runtime from the image and starts it itself.
| macOS VM (`Image.macos()`) | `lume`, Apple silicon only (the SDK starts `lume serve`) |
| Linux arm64 VM on Apple silicon without QEMU | `lume` |
-## Check and set up the host
+### Check and set up the host
```bash test="cli-shape" id="cua-runtime-doctor"
cua runtime doctor # what this host can run (read-only)
@@ -34,7 +47,7 @@ cua runtime setup # install what is missing; or name qemu, lume, c
Apple silicon.
</Callout>
-## Pick a kind or runtime
+### Pick a kind or runtime
```bash test="cli-shape" id="cua-sb-create-linux"
cua sb create linux --name dev # a gVisor container
@@ -56,22 +69,325 @@ In code, pass `kind=` and `runtime=` (`Sandbox.create(image, kind="vm",
runtime="qemu")`); cua-sandbox still accepts a `Runtime` object
([runtime support](/cua-sdk/reference/runtime-support)).
-## What differs locally
+### What differs locally
-- The host's architecture; others run emulated and slowly.
+- The host's architecture. Others run emulated and slowly.
- Services and public URLs are served on loopback (public URLs by the cua
daemon, which the SDK starts).
-- [Sidecars](/cua-sdk/guides/sidecars) need `runtime="runc"` where gVisor would run.
-- Image layers build into your container engine before boot; VM images apply
+- [Sidecars](/cua-sdk/guides/services#sidecars) need `runtime="runc"` where gVisor would run.
+- Image layers build into your container engine before boot. VM images apply
them after boot through cua-spacesd.
-- A sandbox runs until you delete it; `keep_alive` raises.
+- A sandbox runs until you delete it. `keep_alive` raises.
- Images without cua-spacesd fall back to the runtime's agentless path (QMP,
VNC, SSH or ADB) where there is one.
+Images, VM disks and logs take disk space under `~/.cua`. See
+[Disk usage and cleanup](/cua-sdk/guides/lifecycle#disk-usage-and-cleanup).
+
+## Your own cloud
+
+Sandboxes and Spaces can run in a cloud account you own: `--on aws` (EC2),
+`--on gcp` (Compute Engine) or `--on modal` (Modal Sandboxes). The same images,
+SDK calls and `cua-bench` runs work there, and you pay the cloud directly.
+
+Each sandbox dials out to the cua.ai relay as a machine of your account, so
+nothing in your cloud listens on the internet. Your laptop, your agents and the
+Cua Spaces app reach it wherever they are. Streams, files and presence pass
+through relay.cua.ai, and only your devices and the accounts you share a Space
+with can reach the sandbox. The guest holds only its own machine token, never
+your account credentials. An account holds at most 32 machines, and each cloud
+sandbox uses one until you delete it.
+
+<Callout type="warn">
+ Everything here creates resources that your cloud account bills for. Cua
+ gives each one a time limit (8 hours by default) and cleans up after itself,
+ but set a budget in your cloud first.
+</Callout>
+
+### What you need
+
+- The cloud's own CLI, signed in. Cua uses its credentials where they are and
+ stores only the names:
+ - **AWS**: a profile in `~/.aws` (access keys, SSO or an assumed role).
+ - **Google Cloud**: `gcloud auth login` and a project with the Compute Engine
+ API enabled.
+ - **Modal**: a profile in `~/.modal.toml` (`modal token new`).
+- A cua.ai sign-in (`cua auth login`). Each cloud sandbox joins the relay as a
+ machine of your account.
+
+### Connect a cloud
+
+`cua cloud status` shows each cloud, whether its credentials were found on this
+machine, and what it can run at what hourly cost:
+
+```bash test="cli-shape" id="cua-cloud-status"
+cua cloud status
+```
+
+`cua cloud test` checks an account without creating anything. It checks the
+credentials, runs a dry run of a create, and reads the quota, the region and
+the machine types:
+
+```bash test="cli-shape" id="cua-cloud-test"
+cua cloud test aws --profile default --region us-west-2
+```
+
+`cua cloud connect` runs the same checks and connects only when they pass.
+`--default` also makes the cloud the default location, so `cua sb create` and
+`create_space` go there when you give no location:
+
+```bash test="cli-shape" id="cua-cloud-connect"
+cua cloud connect aws --region us-west-2 --default
+cua cloud connect gcp --project my-project --region us-central1
+cua cloud connect modal --environment sandboxes
+```
+
+`--ttl-hours` sets how long each sandbox there lives before it deletes itself
+(default 8; `0` keeps it until you delete it; Modal caps a sandbox at 24):
+
+```bash test="cli-shape" id="cua-cloud-connect-ttl"
+cua cloud connect aws --ttl-hours 2
+```
+
+The Cua Spaces app does the same from **New Space**, **Your cloud**,
+**Connect a cloud**.
+
+### Create sandboxes and Spaces
+
+A sandbox:
+
+```bash test="cli-shape" id="cua-sb-create-aws"
+cua sb create linux --on aws --name research
+cua sb exec aws:research -- uname -a
+cua sb delete aws:research
+```
+
+From Python, including `cua-bench` runs:
+
+```python skip="your-cloud" id="your-cloud-python"
+from cua_sandbox import Image, Sandbox
+
+async with Sandbox.ephemeral(Image.linux(), on="aws") as sb:
+ print(await sb.shell.run("uname -a"))
+ await sb.screenshot()
+```
+
+```bash test="cli-shape" id="cb-run-aws"
+cb run cua-bench-basic --on aws
+```
+
+A Space is a cloud sandbox shown as the relay machine it joined as,
+`relay:<machine>`. Stop and start keep its disk (on AWS and Google Cloud):
+
+```bash test="cli-shape" id="cua-spaces-create-aws"
+cua spaces create linux --on aws --name research
+cua spaces stop relay:cloud-0123456789abcdef
+cua spaces start relay:cloud-0123456789abcdef
+cua spaces delete relay:cloud-0123456789abcdef --force
+```
+
+Agents use the same `create_space` tool with `on="aws"`, and `cloud_status`,
+`cloud_test`, `cloud_connect` and `cloud_sweep` from the
+[Spaces contract](/spaces/reference/cloud).
+
+### What Cua creates
+
+| Cloud | Per sandbox | Shared |
+|---|---|---|
+| AWS | One EC2 instance and its disk. Docker runs the image on it. | One security group with no inbound rules, in the region's default VPC. |
+| Google Cloud | One Compute Engine instance and its disk. Docker runs the image on it. | A network with no inbound rules, so the project's default firewall rules never apply to it. |
+| Modal | One Modal sandbox running the image. | Nothing. |
+
+- Nothing else is created: no IAM users or keys, and no change to existing
+ networks, security groups or firewall rules.
+- The VM installs only Docker. The image carries its own cua-spacesd.
+- Every resource carries these tags (labels on Google Cloud):
+
+ | Tag | Value |
+ |---|---|
+ | `cua-managed` | `true` |
+ | `cua-owner` | This cua home's owner id |
+ | `cua-space` | The sandbox's name |
+ | `cua-machine` | Its relay machine |
+ | `cua-created-by` | The cua version |
+ | `cua-expires` | When it expires (Unix seconds) |
+
+- Cua records every resource in `~/.cua/cloud/state.json` before the cloud
+ call, with its cloud id once it has one.
+
+### Costs
+
+`cua cloud status` shows the estimated on-demand price of each image family
+per hour while it runs (compute and disk, not network). A stopped VM bills only
+its disk.
+
+| Cloud | `linux` | `linux-slim` |
+|---|---|---|
+| AWS | `t4g.medium` (arm64), about $0.04/hour | `t4g.small`, about $0.03/hour |
+| Google Cloud | `e2-medium`, about $0.04/hour | `e2-small`, about $0.03/hour |
+| Modal | 1 core (2 vCPU) and 4 GiB, about $0.24/hour | the same |
+
+- Windows and Omarchy are not offered yet. They run as VMs inside the cloud's
+ VM, which needs a nested-virtualization machine type. `cua cloud status`
+ says so next to them.
+- macOS is not offered. On AWS it would need an EC2 Mac dedicated host, which
+ has a 24-hour minimum.
+
+### Notes for each cloud
+
+- **AWS**:
+ - One region per connection (`--region`, else the profile's). Profiles, SSO
+ and assume-role profiles from `~/.aws` work as the AWS CLI's do.
+ - The instance allows only IMDSv2 with a hop limit of 1, so the sandbox's
+ containers cannot read the instance's metadata (or its user data). It has
+ no key pair and no instance profile.
+ - A new account's vCPU quota may be low. `cua cloud test aws` does not read
+ it yet, and a create past it fails with AWS's own message.
+- **Google Cloud**:
+ - One project and zone per connection (`--project`, `--region`, `--zone`).
+ - The instance has no service account, so nothing on it can call Google
+ APIs. Its containers reach the metadata server only for DNS.
+ - `cua cloud test gcp` says when the Compute Engine API is disabled.
+- **Modal**:
+ - One environment per connection (`--environment`) and a `~/.modal.toml`
+ profile (`--profile`).
+ - Sandboxes run under gVisor by default. `--runtime microvm` uses Modal's VM
+ runtime. Neither has `/dev/kvm`, so only Linux images run.
+ - A sandbox cannot be stopped and started, and lives at most 24 hours.
+ - Cua talks to Modal through `cua-modal-helper`, which uses Modal's official
+ Go SDK. Build it with `go build` in
+ `libs/cua/crates/cua-contrib/modal-helper`, and put it next to `cua`, on
+ `PATH`, or in `CUA_MODAL_HELPER`.
+
+### Time limits and cleanup
+
+Three things end a sandbox that nobody deleted:
+
+- **It shuts itself down.** A VM runs `shutdown` at its time limit and checks
+ it again after every reboot or start. Shutting down deletes it (AWS
+ terminates on shutdown; Google Cloud's run limit deletes it). Modal ends a
+ sandbox at its timeout.
+- **A failed create cleans up.** Whatever it made is deleted, and its relay
+ machine is removed.
+- **`cua cloud sweep`** lists expired sandboxes and anything Cua created whose
+ sandbox is gone. With `--delete` it deletes them. `--all` includes every Cua
+ resource in that cloud.
+
+```bash test="cli-shape" id="cua-cloud-sweep"
+cua cloud sweep
+cua cloud sweep aws --delete
+cua cloud sweep --all --delete
+```
+
+The sweeper touches only a resource that the cloud shows with
+`cua-managed=true` and this home's `cua-owner`, and that this home recorded or
+that carries its owner id. It never matches by name. Untagged resources and
+other owners' resources are never deleted, whatever they are called.
+
+`cua cloud disconnect` forgets a cloud and deletes nothing. It lists what Cua
+still records there.
+
+## Other sandbox providers
+
+The same images (the canonical `ghcr.io/trycua/linux`, or any registry image)
+also run on third-party sandbox platforms. The location is one more `--on`
+word: `--on e2b`, `--on daytona`, `--on modal`. Everything above the location
+works unchanged: services, `sb.spacesd()`, `cua doctor` and cua-bench.
+
+[Your own cloud](#your-own-cloud) needs no provider key, and its sandboxes join
+the cua.ai relay. Providers are opt-in. The default `cua` build knows the words
+and tells you how to get the provider. A build with `--features contrib`
+includes them. Modal works both ways: connect it as your own cloud and its
+sandboxes join the relay; with only a Modal key, the sandbox uses Modal's own
+tunnels.
+
+### Set up a provider
+
+```bash skip="host-install"
+cargo install --locked --path libs/cua/crates/cua-cli --features contrib
+cua auth provider set e2b # reads E2B_API_KEY from stdin, never echoed
+cua auth provider ls # where each key comes from, never the value
+```
+
+An environment variable wins over a stored key: `E2B_API_KEY`,
+`DAYTONA_API_KEY`, or `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET`.
+
+Modal documents no HTTP API, so `--on modal` goes through Modal's official Go
+SDK in a small helper, `cua-modal-helper`. Build it once and put it next to
+`cua` or on `PATH` (or point `CUA_MODAL_HELPER` at it):
+
+```bash skip="host-install"
+(cd libs/cua/crates/cua-contrib/modal-helper && go build -o ~/.local/bin/cua-modal-helper .)
+```
+
+### Create a sandbox on a provider
+
+```bash test="cli-shape" id="contrib-cli"
+cua sb create linux --on e2b --name demo
+cua doctor e2b:demo --strict
+cua sb delete e2b:demo
+```
+
+The ref is `<provider>:<name>` (`e2b:demo`, `daytona:demo`). `--claim-ttl` sets
+the platform's lifetime backstop (default one hour).
+
+```python test="contrib" id="contrib-python" prelude="contrib"
+from cua_sandbox import Image, Sandbox
+
+async with Sandbox.ephemeral(Image.linux(), on="daytona") as sb:
+ await sb.files.write_text("/tmp/hello.txt", "hello from daytona")
+ print(await sb.files.read_text("/tmp/hello.txt")) # hello from daytona
+```
+
+cua-bench takes the same word: `cb run task <task> --on e2b`.
+
+### What happens to the image
+
+The SDK resolves and pins the image first, then maps it onto the platform:
+
+| Provider | Image step | Cached by | Entrypoint |
+|---|---|---|---|
+| E2B | a template built `fromImage` | digest, start command, shape | runs once at build (E2B snapshots it); the SDK installs the cua-spacesd token |
+| Daytona | a snapshot from `imageName` | digest, entrypoint, shape | runs in every sandbox, with the token in its environment |
+| Modal | `FROM` the pinned image, `ENTRYPOINT []` | Modal's image cache | the image's `ENTRYPOINT` and `CMD` as the command, with the token in its environment |
+
+A moved tag gets a new template. Requests a provider cannot run fail before
+any API call, with a typed error: VM variants (`--vm`), images without an amd64
+build, Windows and macOS images, `network="none"`, sidecars, and (Daytona,
+Modal) private registries. Modal tunnels are fixed at create: declare every
+port with `--port`.
+
+### Ports and services
+
+Declared services and cua-spacesd (3211) are reachable through the provider's
+HTTPS URLs. `sb.service(name).url()` and `sb.tunnel.forward(port)` return them.
+Ports are public on the provider's proxy. cua-spacesd authenticates with its
+own token, so keep your other services authenticated too.
+
+### Support matrix
+
+Each provider's lane runs nightly: it creates `ghcr.io/trycua/linux:24.04`,
+runs `cua doctor <ref> --strict --json` inside it, and generates this table
+from the latest reports. A regression shows up here on the next run.
+
+{/* GENERATED:contrib-matrix:start */}
+
+| Provider | Kind | Verdict | display | input | streaming | audio | files | process | teleport | tunnels | mcp | auth | Measured |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| e2b | container | not measured | - | - | - | - | - | - | - | - | - | - | never |
+| daytona | container | not measured | - | - | - | - | - | - | - | - | - | - | never |
+| modal | container | not measured | - | - | - | - | - | - | - | - | - | - | never |
+
+{/* GENERATED:contrib-matrix:end */}
+
+`full`: the desktop works (display, input through cua-driver, streaming, files,
+auth). `container-only`: cua-spacesd answers but the desktop does not.
+`headless-only`: no cua-spacesd answered. `not measured`: no run yet.
+
## Change the default
Without `--on` (or `on=` / `local=`) a sandbox runs on this machine. To default
-to [your own cloud](/cua-sdk/guides/your-cloud) instead, set `default.on`:
+to [your own cloud](#your-own-cloud) instead, set `default.on`:
```bash test="cli-shape" id="cua-config-set-default-on"
cua config set default.on aws # written to ~/.cua/config.toml
@@ -88,10 +404,3 @@ The first match wins:
`default.kind` and `default.runtime` (`CUA_DEFAULT_KIND`,
`CUA_DEFAULT_RUNTIME`) work the same way, and `cua doctor` shows each default
with its source. Switch back with `cua config unset default.on`.
-
-## Disk usage and cleanup
-
-Images share a cache budget and are evicted least recently used first; a pull
-that would leave under 5 GiB free fails with `InsufficientDisk`. `cua cache du`
-shows what images and sandboxes take. See
-[Disk usage and cleanup](/cua-sdk/guides/disk-usage).
diff --git a/docs/content/docs/cua-sdk/guides/meta.json b/docs/content/docs/cua-sdk/guides/meta.json
index 23c560d819..ac66ad1f6f 100644
--- a/docs/content/docs/cua-sdk/guides/meta.json
+++ b/docs/content/docs/cua-sdk/guides/meta.json
@@ -3,24 +3,14 @@
"pages": [
"images",
"services",
- "secrets",
- "sidecars",
"lifecycle",
"desktop",
- "thumbnails",
"spacesd",
"local-runtimes",
- "disk-usage",
- "cua-cloud-ended",
- "your-cloud",
- "your-cloud-resources",
- "contrib-providers",
"test-in-ci",
"run-a-coding-agent",
- "coding-agent-options",
- "browse-the-web",
"agent-frameworks",
"omarchy",
- "migrate-from-deprecated-packages"
+ "cua-cloud-ended"
]
}
diff --git a/docs/content/docs/cua-sdk/guides/migrate-from-deprecated-packages.mdx b/docs/content/docs/cua-sdk/guides/migrate-from-deprecated-packages.mdx
deleted file mode 100644
index a32f112eca..0000000000
--- a/docs/content/docs/cua-sdk/guides/migrate-from-deprecated-packages.mdx
+++ /dev/null
@@ -1,79 +0,0 @@
----
-title: Migrate from deprecated packages
-description: cuabot, cua-computer, cua-computer-server and cua-agent are no longer maintained. What each one did and what to use instead.
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-<Callout type="warn" title="Deprecated">
- Cua no longer maintains `cuabot`, `cua-computer`, `cua-computer-server` or
- `cua-agent`. They will not receive updates or fixes. Existing releases stay on
- npm and PyPI, so current installs keep installing, but you should move off them.
-</Callout>
-
-<Callout type="error" title="Do not run cuabot">
- `cuabot` has known security issues and is no longer maintained. Do not run it.
- If it is installed, [stop and remove it](#cuabot) now.
-</Callout>
-
-| Package | Registry | Last release | Use instead |
-| --- | --- | --- | --- |
-| `cuabot` | npm | 1.0.14 | [Cua Driver](/cua-driver) over MCP, or a sandbox from the [`cua` CLI](/cua-sdk/quickstart) or [Cua Spaces](/spaces) |
-| `cua-computer` | PyPI | 0.5.19 | The [`cua` SDK](/cua-sdk/quickstart) (`cua-sandbox`) for sandboxes, [Cua Driver](/cua-driver) for the machine you are on |
-| `cua-computer-server` | PyPI | 0.3.46 | Images that ship [cua-spacesd](/cua-sdk/guides/spacesd), or [Cua Driver](/cua-driver) on a host |
-| `cua-agent` | PyPI | 0.9.0 | A coding agent with the [Cua Driver MCP](/cua-driver/guides/connect-your-agent), or [`sandbox.agents()`](/cua-sdk/guides/run-a-coding-agent) |
-
-## cuabot
-
-`cuabot` ran coding agents in a Docker sandbox with a local server and a
-desktop you could watch. Stop it, uninstall it and remove what it created:
-
-```bash skip="destructive"
-cuabot --stop # repeat with --name <session> for each named session
-npm uninstall -g cuabot # or delete any local node_modules/cuabot
-docker rm -f cuabot-xpra
-docker images -q trycua/cuabot | xargs docker rmi
-rm -rf ~/.cuabot
-```
-
-Instead:
-
-- To let Claude Code, Codex, Cursor or another agent operate apps on your
- machine, [connect it to Cua Driver](/cua-driver/guides/connect-your-agent).
-- To give an agent its own computer that you can watch,
- [create a Space](/spaces/guides/add-a-space) or a sandbox with the
- [`cua` CLI](/cua-sdk/quickstart), then
- [run the agent in it](/cua-sdk/guides/run-a-coding-agent).
-
-## cua-computer
-
-`cua-computer` was the Python `Computer` class that started a VM or container
-and drove it through `cua-computer-server`. Use the `cua` SDK instead: it
-creates local sandboxes and sandboxes in your own cloud, and `Sandbox` exposes the screen, input,
-shell and files. Start with the [SDK quickstart](/cua-sdk/quickstart) and the
-[sandbox reference](/cua-sdk/reference/python/sandbox).
-
-To operate native apps on the machine you are on, use
-[Cua Driver](/cua-driver/quickstart).
-
-## cua-computer-server
-
-`cua-computer-server` was the HTTP and WebSocket server inside a guest that
-`cua-computer` talked to. The in-guest agent is now
-[cua-spacesd](/cua-sdk/guides/spacesd), which Cua Spaces and the current
-sandbox images ship. Nothing in the `cua` SDK talks to `cua-computer-server`
-any more. Images built before that change still carry it; see the
-[image catalog](/cua-sdk/reference/os-image-catalog) for which ones.
-
-To drive a desktop directly, install [Cua Driver](/cua-driver/quickstart) on it.
-
-## cua-agent
-
-`cua-agent` was the Python `ComputerAgent` loop with LiteLLM. Bring your own
-agent instead:
-
-- Connect Claude Code, Codex, Cursor, OpenClaw or another agent to the
- [Cua Driver MCP server](/cua-driver/guides/connect-your-agent).
-- Run a coding agent inside a sandbox with
- [`sandbox.agents()` or `cua agent run`](/cua-sdk/guides/run-a-coding-agent).
-- Score agents on tasks with [Cua Bench](/cua-bench).
diff --git a/docs/content/docs/cua-sdk/guides/run-a-coding-agent.mdx b/docs/content/docs/cua-sdk/guides/run-a-coding-agent.mdx
index eb14943b40..2c9d5d8c0d 100644
--- a/docs/content/docs/cua-sdk/guides/run-a-coding-agent.mdx
+++ b/docs/content/docs/cua-sdk/guides/run-a-coding-agent.mdx
@@ -1,8 +1,9 @@
---
title: Run a coding agent in a sandbox
-description: Start Claude Code, Codex, Gemini CLI and other harnesses inside a sandbox, stream their events, follow up, interrupt, and collect results and files.
+description: Start Claude Code, Codex, Gemini CLI and other harnesses inside a sandbox, stream their events, follow up, interrupt, give them MCP servers or a custom endpoint, and collect results and files.
---
+
`sandbox.agents()` runs a coding-agent harness (Claude Code, Codex, Gemini CLI,
OpenCode, Goose, ...) inside the sandbox. The SDK installs the harness from
pinned, checksum-verified sources, drives it over the
@@ -152,11 +153,128 @@ run = await agents.get(runs[0].run_id)
print((await run.result()).text)
```
-## Options
+## Give the agent MCP servers
+
+Every run gets the sandbox's own MCP tools (cua-driver: screen, input,
+windows), unless you set `sandbox_mcp=False` or the harness cannot take them.
+Pi has no MCP client, Hermes and OpenClaw read MCP only from their own config,
+and Antigravity has it off by default (see [Harnesses](#harnesses)).
+
+Add more servers with `mcp_servers`. Each is a URL (streamable HTTP, reachable
+from inside the sandbox) or a command (stdio, run in the sandbox). Header
+values may be secrets, and the run treats them like keys.
+
+```python test="excerpt" id="mcp" source="examples/agents-in-sandboxes/tour.py#mcp"
+run = await agents.run(
+ "openai-codex",
+ "Use the docs server to look up our API style guide, then review api.py.",
+ cua.AgentRunOptions(
+ env_from_host=["OPENAI_API_KEY"],
+ mcp_servers=[
+ cua.AgentRunMcpServer(name="docs", url="https://mcp.example.com/mcp",
+ headers={"Authorization": "Bearer <token>"}),
+ cua.AgentRunMcpServer(name="fs", command="npx",
+ args=["-y", "@modelcontextprotocol/server-filesystem", "/srv"]),
+ ],
+ exit_when_idle=True,
+ ),
+)
+```
+
+```bash test="cli-shape" id="cli-mcp"
+cua agent run local:dev openai-codex "Review api.py" --env-from-host OPENAI_API_KEY \
+ --mcp docs=https://mcp.example.com/mcp --no-sandbox-mcp
+```
+
+## Use a custom endpoint or proxy
+
+`base_url` points the harness at a gateway, proxy or compatible server;
+`wire` picks its format (`anthropic`, `openai-responses`, `openai-chat`,
+`gemini`) when it differs from the harness's own.
+
+```python test="excerpt" id="endpoint" source="examples/agents-in-sandboxes/tour.py#endpoint"
+run = await agents.run(
+ "claude-code",
+ "Summarize the repository in five bullet points.",
+ cua.AgentRunOptions(
+ env={"ANTHROPIC_API_KEY": "<gateway key>"},
+ base_url="https://llm-gateway.internal.example.com",
+ model="claude-sonnet-4-5",
+ exit_when_idle=True,
+ ),
+)
+```
+
+```bash test="cli-shape" id="cli-endpoint"
+cua agent run local:dev claude-code "Summarize the repository" \
+ --env-from-host ANTHROPIC_API_KEY --base-url https://llm-gateway.internal.example.com \
+ --model <model-id>
+```
+
+## Harnesses
+
+```bash test="cli-shape" id="cli-harnesses"
+cua agent harnesses
+```
+
+```python test="docs" id="harness-ids"
+import json
+
+import cua
+
+print([h["id"] for h in json.loads(cua.agent_harnesses())])
+# ['claude-code', 'openai-codex', 'gemini-cli', 'google-antigravity', 'opencode', 'goose', 'pi', 'hermes', 'openclaw']
+```
-[Configure coding agents](/cua-sdk/guides/coding-agent-options) covers MCP
-servers for the agent, custom endpoints and proxies, the supported harnesses,
-credentials, and every event kind.
+| Harness | Key variables (any one) | Endpoint wire | Notes |
+| --- | --- | --- | --- |
+| `claude-code` | `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN` | `anthropic` | |
+| `openai-codex` | `OPENAI_API_KEY`, `CODEX_API_KEY` | `openai-responses` | |
+| `gemini-cli` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | `gemini` | Needs a paid API key |
+| `google-antigravity` | `GEMINI_API_KEY` | `gemini` | Headless ACP server, no terminal CLI; sandbox MCP off by default |
+| `opencode` | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY` | `openai-chat` | |
+| `goose` | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `OPENROUTER_API_KEY` | `openai-chat` | |
+| `pi` | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY` | `openai-chat` | Community ACP adapter; no MCP client |
+| `hermes` | `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | `openai-chat` | Needs git; ignores run MCP servers |
+| `openclaw` | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY` | `openai-chat` | Starts its own loopback Gateway; no per-run MCP servers |
+
+`cua agent harnesses` (or `cua.agent_harnesses()`) prints the full record:
+what each harness installs, its interactive CLI, and known limits.
+
+## Credentials
+
+- Keys reach a run only as explicit per-run env (`env`, `env_from_host`,
+ `--env-from-host`). They are written with mode 0600 in the run's directory,
+ redacted from its event log, and never passed in argv.
+- Nothing is copied from your machine's agent config (`~/.claude`, `~/.codex`,
+ and so on).
+- To use a signed-in session instead of a key, move it with
+ [teleport](/spaces/guides/teleport-an-app) (`claude-code` is a
+ built-in app), which shows what will move and asks for approval first.
+- See also [Secrets](/cua-sdk/guides/services#secrets).
+
+## Event kinds
+
+Each event has `seq`, `turn`, `kind`, optional `text` and tool fields, a
+one-line `line` rendering, and `json` (the raw record, ACP payload included).
+
+| Kind | Meaning |
+| --- | --- |
+| `install` | Installing the harness or its dependencies |
+| `initialized`, `authenticated`, `session`, `mode` | ACP setup |
+| `turn_started` | A prompt or follow-up began (`text` is the prompt) |
+| `message`, `thought` | Agent text and reasoning |
+| `user_message` | A user message the agent echoed |
+| `tool_call`, `tool_update` | A tool call and its progress (`tool_title`, `tool_kind`, `tool_status`) |
+| `plan` | The agent's plan entries |
+| `usage` | Token usage update |
+| `permission` | A permission request, auto-approved (the sandbox is the boundary) |
+| `commands`, `info`, `notice` | Available commands and informational updates |
+| `cancel_requested` | `interrupt()` was received |
+| `turn_ended` | The turn finished (`stop_reason`, usage) |
+| `error` | A harness or provider error |
+| `exited` | The run's process ended |
+| `other` | Anything else the harness sent |
## Related
@@ -164,4 +282,4 @@ credentials, and every event kind.
run a harness over a task file in any image and collect a JSON report.
- [cua-bench](/cua-bench/quickstart): `--agent harness` uses a
harness as a benchmark agent.
-- [Connect to an MCP server](/cua-sdk/guides/services) in a sandbox.
+- [Connect to an MCP server](/cua-sdk/guides/services#mcp-servers) in a sandbox.
diff --git a/docs/content/docs/cua-sdk/guides/secrets.mdx b/docs/content/docs/cua-sdk/guides/secrets.mdx
deleted file mode 100644
index afe2712a38..0000000000
--- a/docs/content/docs/cua-sdk/guides/secrets.mdx
+++ /dev/null
@@ -1,85 +0,0 @@
----
-title: Pass secrets into a sandbox
-description: Pass credentials from the host into a sandbox at runtime, and keep them out of images.
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-Read secrets on the host and hand them to one process in the sandbox at
-runtime. Never put them in an image spec. The examples take a connected Linux
-sandbox `sb` with an application at `/app/main.py`; they work locally and in
-[your own cloud](/cua-sdk/guides/your-cloud).
-
-| Value | Where it goes |
-| --- | --- |
-| API keys, tokens, passwords | The process environment at runtime (below) |
-| Key files | A temporary file that is removed when the process exits (below) |
-| Registry credentials | A [`RegistrySecret`](/cua-sdk/guides/images#private-registries), never logged or saved |
-| Non-sensitive settings | `Image.env()`, `env=` on `Sandbox.create`, `Container(env=...)` |
-
-## Environment variables
-
-Set `DATABASE_URL` and `GITHUB_TOKEN` on the host from your secret manager,
-then call `await run_with_secrets(sb)`:
-
-```python test="docs" id="run-with-secrets" session="secrets"
-import os
-import shlex
-from cua_sandbox import Sandbox
-
-
-async def run_with_secrets(sb: Sandbox):
- db_url = os.environ['DATABASE_URL']
- gh_token = os.environ['GITHUB_TOKEN']
- command = (
- f'DATABASE_URL={shlex.quote(db_url)} '
- f'GITHUB_TOKEN={shlex.quote(gh_token)} '
- 'python3 /app/main.py'
- )
- result = await sb.shell.run(command)
- if not result.success:
- raise RuntimeError('Application failed; inspect sanitized diagnostics')
-```
-
-Keep the assignments and the application in one `shell.run()` call: an
-`export` does not persist into the next call. `shlex.quote()` keeps spaces,
-quotes and newlines literal.
-
-## A temporary key file
-
-For an application that reads a key file, point `TASK_SSH_KEY_FILE` at the
-host file (mode `600`), then call `await run_with_key_file(sb)`:
-
-```python test="docs" id="run-with-key-file" session="key-file"
-import os
-from pathlib import Path
-import shlex
-from cua_sandbox import Sandbox
-
-
-async def run_with_key_file(sb: Sandbox):
- key_content = Path(os.environ['TASK_SSH_KEY_FILE']).read_bytes().decode('utf-8')
- script = f"""
-set -eu
-umask 077
-secret_dir=$(mktemp -d /tmp/cua-task-secret.XXXXXXXXXX)
-trap 'rm -f "$secret_dir/task-key"; rmdir "$secret_dir"' EXIT
-trap 'exit 1' HUP INT TERM
-printf '%s' {shlex.quote(key_content)} > "$secret_dir/task-key"
-chmod 600 "$secret_dir/task-key"
-TASK_SSH_KEY_FILE="$secret_dir/task-key" python3 /app/main.py
-"""
- result = await sb.shell.run(script)
- if not result.success:
- raise RuntimeError('Credential task failed; inspect sanitized diagnostics')
-```
-
-The file lives in a private directory and is removed when the application
-exits, including on failure. A killed shell or a lost connection can skip the
-cleanup: destroy the sandbox then.
-
-<Callout type="warn">
- These commands contain the secret values. Quoting does not redact logs,
- traces or process listings: do not print the command, do not enable
- `set -x`, use short-lived credentials, and revoke them when the task ends.
-</Callout>
diff --git a/docs/content/docs/cua-sdk/guides/services.mdx b/docs/content/docs/cua-sdk/guides/services.mdx
index 61f82d087c..3ec23cd952 100644
--- a/docs/content/docs/cua-sdk/guides/services.mdx
+++ b/docs/content/docs/cua-sdk/guides/services.mdx
@@ -1,11 +1,15 @@
---
-title: Run and share a service
-description: Run a server in a sandbox, call it, connect to an MCP server in it, forward a port, and share it with a public URL.
+title: Run services, sidecars and secrets
+description: Run a server in a sandbox, call it, connect to an MCP server in it, forward a port, share it with a public URL, add sidecar containers, and pass secrets.
---
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+Run a program in a sandbox, call it or share it, put helper containers next to
+it, and give it credentials without baking them into an image. This page covers
+services, [sidecars](#sidecars) and [secrets](#secrets).
+
A service is a named guest port. The image (or `command=`) runs the listener;
`services=` names it and `wait_for=` holds `create` until it answers. The
listener must bind a guest-reachable address (`0.0.0.0`, not only
@@ -14,7 +18,7 @@ listener must bind a guest-reachable address (`0.0.0.0`, not only
| Option | Meaning |
| --- | --- |
| `command=["python", "app.py"]` | argv that replaces the image's entrypoint |
-| `env={"LOG_LEVEL": "debug"}` | plain environment variables ([not secrets](/cua-sdk/guides/secrets)) |
+| `env={"LOG_LEVEL": "debug"}` | plain environment variables ([not secrets](#secrets)) |
| `services={"api": 8000}` | named guest ports |
| `wait_for=http("api", "/health")` or `tcp("api")` | readiness; a list waits for all. Fails at once if the command exits |
@@ -169,3 +173,171 @@ cua sb url web web --public --ttl 10m
it when sharing ends, and keep it out of logs and source control. It does
not extend the sandbox's lifetime.
</Callout>
+
+## Sidecars
+
+A sidecar is an extra container next to the sandbox, like a Docker Compose
+service. It is addressed by name on every runtime:
+
+- the sandbox reaches a sidecar at its `name` (`db:6379`);
+- a sidecar reaches the sandbox at `main`;
+- `services=` names a sidecar port so you can call it from your machine.
+
+```python test="container" id="sidecar-local" prelude="local-cleanup"
+from cua_sandbox import Container, Image, Sandbox, tcp
+
+sb = await Sandbox.create(
+ Image.from_registry("python:3.12-slim"),
+ command=["sleep", "infinity"],
+ sidecars=[Container("redis:7-alpine", ports=[6379], name="db")],
+ services={"db": 6379},
+ wait_for=tcp("db"),
+ runtime="runc",
+)
+```
+
+Local sidecars share the sandbox container's network namespace, so
+`localhost` works too. They need `runtime="runc"`: separate gVisor containers
+cannot share a network namespace, and the SDK refuses rather than switching
+runtimes silently. Local VM sandboxes refuse sidecars.
+
+### Reach the sandbox from a sidecar
+
+This relay fetches the sandbox's page from `http://main:8000` and serves it on
+its own port.
+
+```python test="container" id="sidecar-by-name" prelude="local-cleanup"
+from cua_sandbox import Container, Image, Sandbox, http
+
+relay = Container(
+ "busybox:1.36",
+ name="relay",
+ ports=[8081],
+ command=["sh", "-c", "mkdir -p /www; "
+ "until wget -qO /www/index.html http://main:8000/; do sleep 1; done; "
+ "exec httpd -f -p 8081 -h /www"],
+)
+sb = await Sandbox.create(
+ Image.from_registry("python:3.12-slim"),
+ command=["python", "-m", "http.server", "8000"],
+ sidecars=[relay],
+ services={"relay": 8081},
+ wait_for=http("relay", "/"),
+ runtime="runc",
+)
+print((await sb.service("relay").request("GET", "/")).status_code) # 200
+```
+
+### Sidecar options
+
+`Container(image, command=None, env=None, ports=None, name=None)`:
+
+- `name` is a DNS label and the hostname. It defaults from the image (`redis`
+ for `redis:7-alpine`) and cannot be `main`.
+- `command` replaces the sidecar image's entrypoint; `env` holds plain values.
+- A bare image string works too: `sidecars=["redis:7-alpine"]`.
+- At most 8 sidecars. With sidecars, the service names `main`, `sidecars` and
+ `sc` are reserved.
+- A private sidecar image on the sandbox image's registry uses the same
+ [registry secret](/cua-sdk/guides/images#private-registries).
+
+```bash test="cli-shape" id="cua-sb-create-sidecar"
+cua sb create python:3.12-slim --name app --runtime runc \
+ --sidecar redis:7-alpine,port=6379,name=db --service db=6379 --wait tcp:db \
+ -- sleep infinity
+```
+
+`--sidecar` takes `IMAGE[,port=PORT][,env=K=V][,name=NAME]` and repeats.
+
+```ts test="docs" id="sidecar-typescript"
+import { sidecar, SandboxCreateOptions } from '@trycua/cua';
+
+SandboxCreateOptions.create({
+ image: 'python:3.12-slim',
+ command: ['sleep', 'infinity'],
+ sidecars: [sidecar('redis:7-alpine', { ports: [6379], name: 'db' })],
+ services: new Map([['db', 6379]]),
+ runtime: 'runc',
+});
+```
+
+## Secrets
+
+Read secrets on the host and hand them to one process in the sandbox at
+runtime. Never put them in an image spec. The examples take a connected Linux
+sandbox `sb` with an application at `/app/main.py`; they work locally and in
+[your own cloud](/cua-sdk/guides/local-runtimes#your-own-cloud).
+
+| Value | Where it goes |
+| --- | --- |
+| API keys, tokens, passwords | The process environment at runtime (below) |
+| Key files | A temporary file that is removed when the process exits (below) |
+| Registry credentials | A [`RegistrySecret`](/cua-sdk/guides/images#private-registries), never logged or saved |
+| Non-sensitive settings | `Image.env()`, `env=` on `Sandbox.create`, `Container(env=...)` |
+
+### Environment variables
+
+Set `DATABASE_URL` and `GITHUB_TOKEN` on the host from your secret manager,
+then call `await run_with_secrets(sb)`:
+
+```python test="docs" id="run-with-secrets" session="secrets"
+import os
+import shlex
+from cua_sandbox import Sandbox
+
+
+async def run_with_secrets(sb: Sandbox):
+ db_url = os.environ['DATABASE_URL']
+ gh_token = os.environ['GITHUB_TOKEN']
+ command = (
+ f'DATABASE_URL={shlex.quote(db_url)} '
+ f'GITHUB_TOKEN={shlex.quote(gh_token)} '
+ 'python3 /app/main.py'
+ )
+ result = await sb.shell.run(command)
+ if not result.success:
+ raise RuntimeError('Application failed; inspect sanitized diagnostics')
+```
+
+Keep the assignments and the application in one `shell.run()` call: an
+`export` does not persist into the next call. `shlex.quote()` keeps spaces,
+quotes and newlines literal.
+
+### A temporary key file
+
+For an application that reads a key file, point `TASK_SSH_KEY_FILE` at the
+host file (mode `600`), then call `await run_with_key_file(sb)`:
+
+```python test="docs" id="run-with-key-file" session="key-file"
+import os
+from pathlib import Path
+import shlex
+from cua_sandbox import Sandbox
+
+
+async def run_with_key_file(sb: Sandbox):
+ key_content = Path(os.environ['TASK_SSH_KEY_FILE']).read_bytes().decode('utf-8')
+ script = f"""
+set -eu
+umask 077
+secret_dir=$(mktemp -d /tmp/cua-task-secret.XXXXXXXXXX)
+trap 'rm -f "$secret_dir/task-key"; rmdir "$secret_dir"' EXIT
+trap 'exit 1' HUP INT TERM
+printf '%s' {shlex.quote(key_content)} > "$secret_dir/task-key"
+chmod 600 "$secret_dir/task-key"
+TASK_SSH_KEY_FILE="$secret_dir/task-key" python3 /app/main.py
+"""
+ result = await sb.shell.run(script)
+ if not result.success:
+ raise RuntimeError('Credential task failed; inspect sanitized diagnostics')
+```
+
+The file lives in a private directory and is removed when the application
+exits, including on failure. A killed shell or a lost connection can skip the
+cleanup: destroy the sandbox then.
+
+<Callout type="warn">
+ These commands contain the secret values. Quoting does not redact logs,
+ traces or process listings: do not print the command, do not enable
+ `set -x`, use short-lived credentials, and revoke them when the task ends.
+</Callout>
diff --git a/docs/content/docs/cua-sdk/guides/sidecars.mdx b/docs/content/docs/cua-sdk/guides/sidecars.mdx
deleted file mode 100644
index 8e8a29c176..0000000000
--- a/docs/content/docs/cua-sdk/guides/sidecars.mdx
+++ /dev/null
@@ -1,91 +0,0 @@
----
-title: Add sidecar containers
-description: Run extra containers such as a database or cache next to a sandbox and reach them by name.
----
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-A sidecar is an extra container next to the sandbox, like a Docker Compose
-service. It is addressed by name on every runtime:
-
-- the sandbox reaches a sidecar at its `name` (`db:6379`);
-- a sidecar reaches the sandbox at `main`;
-- `services=` names a sidecar port so you can call it from your machine.
-
-```python test="container" id="local" prelude="local-cleanup"
-from cua_sandbox import Container, Image, Sandbox, tcp
-
-sb = await Sandbox.create(
- Image.from_registry("python:3.12-slim"),
- command=["sleep", "infinity"],
- sidecars=[Container("redis:7-alpine", ports=[6379], name="db")],
- services={"db": 6379},
- wait_for=tcp("db"),
- runtime="runc",
-)
-```
-
-Local sidecars share the sandbox container's network namespace, so
-`localhost` works too. They need `runtime="runc"`: separate gVisor containers
-cannot share a network namespace, and the SDK refuses rather than switching
-runtimes silently. Local VM sandboxes refuse sidecars.
-
-## Reach the sandbox from a sidecar
-
-This relay fetches the sandbox's page from `http://main:8000` and serves it on
-its own port.
-
-```python test="container" id="by-name" prelude="local-cleanup"
-from cua_sandbox import Container, Image, Sandbox, http
-
-relay = Container(
- "busybox:1.36",
- name="relay",
- ports=[8081],
- command=["sh", "-c", "mkdir -p /www; "
- "until wget -qO /www/index.html http://main:8000/; do sleep 1; done; "
- "exec httpd -f -p 8081 -h /www"],
-)
-sb = await Sandbox.create(
- Image.from_registry("python:3.12-slim"),
- command=["python", "-m", "http.server", "8000"],
- sidecars=[relay],
- services={"relay": 8081},
- wait_for=http("relay", "/"),
- runtime="runc",
-)
-print((await sb.service("relay").request("GET", "/")).status_code) # 200
-```
-
-## Options
-
-`Container(image, command=None, env=None, ports=None, name=None)`:
-
-- `name` is a DNS label and the hostname. It defaults from the image (`redis`
- for `redis:7-alpine`) and cannot be `main`.
-- `command` replaces the sidecar image's entrypoint; `env` holds plain values.
-- A bare image string works too: `sidecars=["redis:7-alpine"]`.
-- At most 8 sidecars. With sidecars, the service names `main`, `sidecars` and
- `sc` are reserved.
-- A private sidecar image on the sandbox image's registry uses the same
- [registry secret](/cua-sdk/guides/images#private-registries).
-
-```bash test="cli-shape" id="cua-sb-create"
-cua sb create python:3.12-slim --name app --runtime runc \
- --sidecar redis:7-alpine,port=6379,name=db --service db=6379 --wait tcp:db \
- -- sleep infinity
-```
-
-`--sidecar` takes `IMAGE[,port=PORT][,env=K=V][,name=NAME]` and repeats.
-
-```ts test="docs" id="typescript"
-import { sidecar, SandboxCreateOptions } from '@trycua/cua';
-
-SandboxCreateOptions.create({
- image: 'python:3.12-slim',
- command: ['sleep', 'infinity'],
- sidecars: [sidecar('redis:7-alpine', { ports: [6379], name: 'db' })],
- services: new Map([['db', 6379]]),
- runtime: 'runc',
-});
-```
diff --git a/docs/content/docs/cua-sdk/guides/spacesd.mdx b/docs/content/docs/cua-sdk/guides/spacesd.mdx
index 339a0734c2..ff9e4ae3b3 100644
--- a/docs/content/docs/cua-sdk/guides/spacesd.mdx
+++ b/docs/content/docs/cua-sdk/guides/spacesd.mdx
@@ -46,7 +46,7 @@ on a machine, see [Run spacesd yourself](#run-spacesd-yourself); its RPCs are in
## Run spacesd yourself
On a machine you own, `cua host setup` installs spacesd as a service
-([Unattended access](/spaces/guides/unattended-access)). To run the binary by
+([Unattended access](/spaces/guides/add-a-computer#add-a-computer-from-a-terminal)). To run the binary by
hand:
```bash skip="no-runner"
diff --git a/docs/content/docs/cua-sdk/guides/test-in-ci.mdx b/docs/content/docs/cua-sdk/guides/test-in-ci.mdx
index 76690d21ea..cbd128f4ca 100644
--- a/docs/content/docs/cua-sdk/guides/test-in-ci.mdx
+++ b/docs/content/docs/cua-sdk/guides/test-in-ci.mdx
@@ -12,7 +12,7 @@ is a plain `cua` command, so the same run works on your machine.
## GitHub Actions
-```yaml test="config" id="ci-basic"
+```yaml title=".github/workflows/e2e.yml" test="config" id="ci-basic"
jobs:
e2e:
runs-on: ubuntu-latest
@@ -30,15 +30,18 @@ jobs:
- `image`: a canonical image, a bench image or any registry reference.
- `on`: `local` (the default: Docker on the runner, or QEMU with KVM for VM
- images), `docker`, `qemu`, or a [contrib provider](/cua-sdk/guides/contrib-providers)
- such as `e2b`, `daytona` or `modal`. Cua Cloud (`cloud`) has ended: see
- [Cua Cloud (Fleets) has ended](/cua-sdk/guides/cua-cloud-ended). `claim-ttl`
- (default `60m`) is the backstop if cleanup never runs.
+ images), `docker`, `qemu`, or a
+ [provider](/cua-sdk/guides/local-runtimes#other-sandbox-providers) such as
+ `e2b`, `daytona` or `modal`. `claim-ttl` (default `60m`) is the backstop if
+ cleanup never runs.
+- If the runner has no Docker or KVM, use a runner that has Docker (GitHub-hosted
+ Linux runners do) or a provider such as `on: e2b`. Cua Cloud (`on: cloud`) has
+ ended: see [Cua Cloud (Fleets) has ended](/cua-sdk/guides/cua-cloud-ended).
- `run` runs on the runner with `CUA_SANDBOX` set to the sandbox ref.
`guest-run` runs inside the sandbox. `guest-setup` runs as root inside it
first, for example to install test dependencies.
-- `cua-version`: `source` (the default) builds the CLI from the action's ref.
- Pass `cua-bin` to use one you built.
+- `cua-version`: `source` (the default) builds the CLI from the action's ref,
+ which is why the example sets up Rust. Pass `cua-bin` to use one you built.
- Outputs: `ref`, `name`, `env-url`, `viewer-url`, `urls`, `overlays`,
`doctor-status`, `artifacts-dir`.
diff --git a/docs/content/docs/cua-sdk/guides/thumbnails.mdx b/docs/content/docs/cua-sdk/guides/thumbnails.mdx
deleted file mode 100644
index d62c8a50a2..0000000000
--- a/docs/content/docs/cua-sdk/guides/thumbnails.mdx
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: Space thumbnails
-description: Read a Space's latest small preview from the cache every client on the machine shares.
----
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-For a small preview of a Space (a tile, a list row, a placeholder while a
-stream connects), use `Space.thumbnail` rather than `screenshot`. It reads one
-cache that every client on the machine shares (the Spaces app, the CLI, your
-scripts): a small JPEG of the primary display and when it was captured. The
-cached image comes back at once when it is younger than `max_age_ms`; otherwise
-the SDK captures a fresh one through cua-spacesd and keeps it for the next
-caller. When that capture fails, the older image comes back, and
-`captured_at_ms` says how old it is.
-
-<Tabs groupId="language" persist items={['Python', 'TypeScript', 'Swift']}>
- <Tab value="Python">
-
-```python skip="no-runner"
-import cua
-
-space = await cua.connect().spaces().space("local:dev")
-thumb = await space.thumbnail(max_age_ms=120_000) # None: any age
-print(thumb.width, thumb.height, thumb.captured_at_ms)
-```
-
- </Tab>
- <Tab value="TypeScript">
-
-```ts skip="no-runner"
-import { connect } from '@trycua/cua';
-
-const space = await connect().spaces().space('local:dev');
-const thumb = await space.thumbnail(120_000n); // undefined: any age
-console.log(thumb.width, thumb.height, thumb.capturedAtMs);
-```
-
- </Tab>
- <Tab value="Swift">
-
-```swift skip="no-runner"
-import Cua
-
-let space = try await Cua.connect(address: nil, token: nil).spaces().space(space: "local:dev")
-let thumb = try await space.thumbnail(maxAgeMs: 120_000) // nil: any age
-print(thumb.width, thumb.height, thumb.capturedAtMs)
-```
-
- </Tab>
-</Tabs>
-
-The cua daemon owns the cache under `~/.cua/cache/thumbnails`. It keeps the
-latest image per Space across restarts, drops a Space's image when the Space is
-deleted or removed, and caps the cache at 32 MB (the oldest images go first).
-While any client has asked for a thumbnail in the last 10 minutes, the daemon
-also captures a new one for each running Space about every 90 seconds, so a
-preview is seldom more than a couple of minutes old. When nobody asks, it
-captures nothing and puts no load on the guests.
diff --git a/docs/content/docs/cua-sdk/guides/your-cloud-resources.mdx b/docs/content/docs/cua-sdk/guides/your-cloud-resources.mdx
deleted file mode 100644
index d81b1af07c..0000000000
--- a/docs/content/docs/cua-sdk/guides/your-cloud-resources.mdx
+++ /dev/null
@@ -1,75 +0,0 @@
----
-title: Your cloud resources and costs
-description: What Cua creates in your AWS, Google Cloud or Modal account, what it costs per hour, and the notes for each cloud.
----
-
-Details for [Use your own cloud](/cua-sdk/guides/your-cloud).
-
-## What Cua creates
-
-| Cloud | Per sandbox | Shared |
-|---|---|---|
-| AWS | One EC2 instance and its disk. Docker runs the image on it. | One security group with no inbound rules, in the region's default VPC. |
-| Google Cloud | One Compute Engine instance and its disk. Docker runs the image on it. | A network with no inbound rules, so the project's default firewall rules never apply to it. |
-| Modal | One Modal sandbox running the image. | Nothing. |
-
-- Nothing else is created: no IAM users or keys, no change to existing
- networks, security groups or firewall rules.
-- The VM installs only Docker. The image carries its own cua-spacesd.
-- Every resource carries these tags (labels on Google Cloud):
-
- | Tag | Value |
- |---|---|
- | `cua-managed` | `true` |
- | `cua-owner` | This cua home's owner id |
- | `cua-space` | The sandbox's name |
- | `cua-machine` | Its relay machine |
- | `cua-created-by` | The cua version |
- | `cua-expires` | When it expires (Unix seconds) |
-
-- Every resource is recorded in `~/.cua/cloud/state.json` before the cloud call,
- with its cloud id once it has one.
-
-## Costs
-
-`cua cloud status` shows the estimated on-demand price of each image family
-per hour while it runs (compute and disk, not network). A stopped VM bills only
-its disk.
-
-| Cloud | `linux` | `linux-slim` |
-|---|---|---|
-| AWS | `t4g.medium` (arm64), about $0.04/hour | `t4g.small`, about $0.03/hour |
-| Google Cloud | `e2-medium`, about $0.04/hour | `e2-small`, about $0.03/hour |
-| Modal | 1 core (2 vCPU) and 4 GiB, about $0.24/hour | the same |
-
-- Windows and Omarchy are not offered yet. They run as VMs inside the cloud's
- VM, which needs a nested-virtualization machine type; `cua cloud status`
- says so next to them.
-- macOS is not offered. On AWS it would need an EC2 Mac dedicated host, which
- has a 24-hour minimum.
-
-## Per-cloud notes
-
-- **AWS**:
- - One region per connection (`--region`, else the profile's). Profiles, SSO
- and assume-role profiles from `~/.aws` work as the AWS CLI's do.
- - The instance allows only IMDSv2 with a hop limit of 1, so the sandbox's
- containers cannot read the instance's metadata (or its user data). It has
- no key pair and no instance profile.
- - A new account's vCPU quota may be low. `cua cloud test aws` does not read
- it yet; a create past it fails with AWS's own message.
-- **Google Cloud**:
- - One project and zone per connection (`--project`, `--region`, `--zone`).
- - The instance has no service account, so nothing on it can call Google
- APIs. Its containers reach the metadata server only for DNS.
- - `cua cloud test gcp` says when the Compute Engine API is disabled.
-- **Modal**:
- - One environment per connection (`--environment`) and a `~/.modal.toml`
- profile (`--profile`).
- - Sandboxes run under gVisor by default; `--runtime microvm` uses Modal's VM
- runtime. Neither has `/dev/kvm`, so only Linux images run.
- - A sandbox cannot be stopped and started, and lives at most 24 hours.
- - Cua talks to Modal through `cua-modal-helper`, which uses Modal's official
- Go SDK. Build it with `go build` in
- `libs/cua/crates/cua-contrib/modal-helper` and put it next to `cua`, on
- `PATH`, or in `CUA_MODAL_HELPER`.
diff --git a/docs/content/docs/cua-sdk/guides/your-cloud.mdx b/docs/content/docs/cua-sdk/guides/your-cloud.mdx
deleted file mode 100644
index 2acc0a0d2f..0000000000
--- a/docs/content/docs/cua-sdk/guides/your-cloud.mdx
+++ /dev/null
@@ -1,154 +0,0 @@
----
-title: Use your own cloud
-description: Run sandboxes and Spaces in your own AWS, Google Cloud or Modal account with --on aws, --on gcp or --on modal, with Cua's tags, time limits and cleanup on everything it creates.
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-Sandboxes and Spaces can run in a cloud account you own: `--on aws` (EC2),
-`--on gcp` (Compute Engine) or `--on modal` (Modal Sandboxes). The same images,
-the same SDK calls and the same `cua-bench` runs work there; you pay the cloud
-directly.
-
-Each sandbox dials out to the cua.ai relay as a machine of your account, so
-nothing in your cloud listens on the internet, and your laptop, your agents and
-the Cua Spaces app reach it wherever they are.
-
-<Callout type="warn">
- Everything here creates resources that your cloud account bills for. Cua
- gives each one a time limit (8 hours by default) and cleans up after itself,
- but set a budget in your cloud first.
-</Callout>
-
-## What you need
-
-- The cloud's own CLI, signed in. Cua uses its credentials where they are and
- stores only the names:
- - **AWS**: a profile in `~/.aws` (access keys, SSO or an assumed role).
- - **Google Cloud**: `gcloud auth login` and a project with the Compute Engine
- API enabled.
- - **Modal**: a profile in `~/.modal.toml` (`modal token new`).
-- A cua.ai sign-in (`cua auth login`). Each cloud sandbox joins the relay as a
- machine of your account.
-
-## Connect a cloud
-
-`cua cloud status` shows each cloud, whether its credentials were found on this
-machine, and what it can run at what hourly cost:
-
-```bash test="cli-shape" id="cua-cloud-status"
-cua cloud status
-```
-
-`cua cloud test` checks an account without creating anything. It checks the
-credentials, runs a dry run of a create, and reads the quota, the region and the
-machine types:
-
-```bash test="cli-shape" id="cua-cloud-test"
-cua cloud test aws --profile default --region us-west-2
-```
-
-`cua cloud connect` runs the same checks and connects only when they pass.
-`--default` also makes it the default location, so `cua sb create` and
-`create_space` go there when no location is given:
-
-```bash test="cli-shape" id="cua-cloud-connect"
-cua cloud connect aws --region us-west-2 --default
-cua cloud connect gcp --project my-project --region us-central1
-cua cloud connect modal --environment sandboxes
-```
-
-`--ttl-hours` sets how long each sandbox there lives before it deletes itself
-(default 8; `0` keeps it until you delete it; Modal caps a sandbox at 24):
-
-```bash test="cli-shape" id="cua-cloud-connect-ttl"
-cua cloud connect aws --ttl-hours 2
-```
-
-The Cua Spaces app does the same from **New Space**, **Your cloud**,
-**Connect a cloud**.
-
-## Create sandboxes and Spaces
-
-A sandbox:
-
-```bash test="cli-shape" id="cua-sb-create-aws"
-cua sb create linux --on aws --name research
-cua sb exec aws:research -- uname -a
-cua sb delete aws:research
-```
-
-From Python, including `cua-bench`'s runs:
-
-```python skip="your-cloud" id="your-cloud-python"
-from cua_sandbox import Image, Sandbox
-
-async with Sandbox.ephemeral(Image.linux(), on="aws") as sb:
- print(await sb.shell.run("uname -a"))
- await sb.screenshot()
-```
-
-```bash test="cli-shape" id="cb-run-aws"
-cb run cua-bench-basic --on aws
-```
-
-A Space is a cloud sandbox shown as the relay machine it joined as,
-`relay:<machine>`. Stop and start keep its disk (on AWS and Google Cloud):
-
-```bash test="cli-shape" id="cua-spaces-create-aws"
-cua spaces create linux --on aws --name research
-cua spaces stop relay:cloud-0123456789abcdef
-cua spaces start relay:cloud-0123456789abcdef
-cua spaces delete relay:cloud-0123456789abcdef --force
-```
-
-Agents use the same `create_space` tool with `on="aws"`, and `cloud_status`,
-`cloud_test`, `cloud_connect` and `cloud_sweep` from the
-[Spaces contract](/spaces/reference/cloud).
-
-## What Cua creates
-
-One VM (or Modal sandbox) per sandbox, tagged `cua-managed=true` with your
-owner id and an expiry, and recorded in `~/.cua/cloud/state.json`. Nothing
-else: no IAM users or keys, no change to existing networks. What each cloud
-creates, the prices and the per-cloud notes:
-[Your cloud resources and costs](/cua-sdk/guides/your-cloud-resources).
-
-## Time limits and cleanup
-
-Three things end a sandbox that nobody deleted:
-
-- **It shuts itself down.** A VM runs `shutdown` at its time limit and checks
- it again after every reboot or start. Shutting down deletes it (AWS
- terminates on shutdown; Google Cloud's run limit deletes it). Modal ends a
- sandbox at its timeout.
-- **A failed create cleans up.** Whatever it made is deleted, and its relay
- machine is removed.
-- **`cua cloud sweep`** lists expired sandboxes and anything Cua created whose
- sandbox is gone. With `--delete` it deletes them; `--all` includes every Cua
- resource in that cloud:
-
- ```bash test="cli-shape" id="cua-cloud-sweep"
- cua cloud sweep
- cua cloud sweep aws --delete
- cua cloud sweep --all --delete
- ```
-
-The sweeper touches only a resource that the cloud shows with
-`cua-managed=true` and this home's `cua-owner`, and that this home recorded or
-that carries its owner id. It never matches by name. Untagged resources and
-other owners' resources are never deleted, whatever they are called.
-
-`cua cloud disconnect` forgets a cloud and deletes nothing. It lists what Cua
-still records there.
-
-## The relay
-
-Each sandbox is one machine of your cua.ai account on the relay:
-
-- Streams, files and presence pass through relay.cua.ai. There is no direct
- path from your cloud to your laptop.
-- An account holds at most 32 machines. Each cloud sandbox uses one, and its
- delete removes it.
-- Only your devices and the accounts you share a Space with can reach it. The
- guest holds only its own machine token, never your account credentials.
diff --git a/docs/content/docs/cua-sdk/index.mdx b/docs/content/docs/cua-sdk/index.mdx
index b741ae963f..f1c8741508 100644
--- a/docs/content/docs/cua-sdk/index.mdx
+++ b/docs/content/docs/cua-sdk/index.mdx
@@ -55,14 +55,14 @@ await sb.delete_();
</Tabs>
Setup: `cua runtime doctor` shows what this host has and `cua runtime setup`
-installs what is missing ([Local runtimes](/cua-sdk/guides/local-runtimes)).
+installs what is missing ([Choose where sandboxes run](/cua-sdk/guides/local-runtimes)).
Containers run the host's architecture (others run emulated); macOS runs in
Lume VMs on Apple silicon.
## Reach another machine
Any machine that runs [cua-spacesd](/cua-sdk/guides/spacesd), such as a spare
-Mac, a server on your LAN or [Tailscale](/spaces/guides/host-spaces-on-your-spare-mac),
+Mac, a server on your LAN or [Tailscale](/spaces/guides/add-a-computer#use-a-spare-mac-to-host-spaces),
or a container you started, connects directly by address and env token.
Nothing is created or deleted:
diff --git a/docs/content/docs/cua-sdk/quickstart.mdx b/docs/content/docs/cua-sdk/quickstart.mdx
index 301d1ce9bc..3ae48143be 100644
--- a/docs/content/docs/cua-sdk/quickstart.mdx
+++ b/docs/content/docs/cua-sdk/quickstart.mdx
@@ -93,7 +93,7 @@ The first start of an image pulls it, which can take a few minutes.
`Sandbox.ephemeral` deletes the sandbox when the block exits. A CLI sandbox
stays until you remove it: `cua sb rm web -f`. `cua cache du` shows what images and sandboxes
-take on disk ([Disk usage](/cua-sdk/guides/disk-usage)).
+take on disk ([Disk usage](/cua-sdk/guides/lifecycle#disk-usage-and-cleanup)).
## Images
@@ -137,6 +137,6 @@ Each has a container tag and a `-disk` VM tag, and runs locally with `cb run`.
## Next
-- [Control the desktop](/cua-sdk/guides/desktop)
-- [Run a service](/cua-sdk/guides/services)
+- [Control the desktop and the browser](/cua-sdk/guides/desktop)
+- [Run services, sidecars and secrets](/cua-sdk/guides/services)
- [Reach another machine](/cua-sdk#reach-another-machine)
diff --git a/docs/content/docs/cua-sdk/reference/runtime-support.mdx b/docs/content/docs/cua-sdk/reference/runtime-support.mdx
index 80a3848b5f..6301745ec8 100644
--- a/docs/content/docs/cua-sdk/reference/runtime-support.mdx
+++ b/docs/content/docs/cua-sdk/reference/runtime-support.mdx
@@ -107,7 +107,7 @@ Declaring a service does not install or start it. For an example layout, see the
| Direct `Sandbox.connect(url=...)` | spacesd | spacesd tunnel | No declared services |
| Legacy adapters (Android ADB, OSWorld, Tart, Hyper-V) | Adapter-specific | ADB forwards ports and Android sockets | Adapter-specific |
-For sandboxes in your own cloud, see [Use your own cloud](/cua-sdk/guides/your-cloud)
+For sandboxes in your own cloud, see [Choose where sandboxes run](/cua-sdk/guides/local-runtimes#your-own-cloud)
and [Sandbox interfaces](/cua-sdk/reference/python/interfaces).
## Evidence and limits
diff --git a/docs/content/docs/cua-sdk/reference/spaces/app-core/onboarding-previews.mdx b/docs/content/docs/cua-sdk/reference/spaces/app-core/onboarding-previews.mdx
index faa23a4001..9955324c02 100644
--- a/docs/content/docs/cua-sdk/reference/spaces/app-core/onboarding-previews.mdx
+++ b/docs/content/docs/cua-sdk/reference/spaces/app-core/onboarding-previews.mdx
@@ -7,7 +7,7 @@ description: "The animated miniatures on the onboarding cards: the background co
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:cua-sdk
Source: cua-bindgen docs --namespace cua_spaces_ffi (UniFFI metadata of libcua_spaces_ffi)
- Version: 0.4.1
+ Version: 0.5.0
*/}
import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/docs/content/docs/docs-for-agents.mdx b/docs/content/docs/docs-for-agents.mdx
index b755e5b201..6a336ed524 100644
--- a/docs/content/docs/docs-for-agents.mdx
+++ b/docs/content/docs/docs-for-agents.mdx
@@ -3,6 +3,17 @@ title: Docs for agents
description: Give a coding agent Cua's docs and source as Markdown or over MCP.
---
+## How the docs are organized
+
+| Part | Folder | What it covers |
+| --- | --- | --- |
+| Cua Spaces | `/docs/spaces` | The app: quickstart, task guides, how it works |
+| Cua Driver | `/docs/cua-driver` | Quickstart, guides, every command and tool |
+| Reference | `/docs/cua-cli`, `/docs/cua-sdk` | The `cua` command and the SDK |
+| More tools | `/docs/lume`, `/docs/cua-bench` | Lume virtual machines and Cua Bench |
+
+Old page URLs redirect to the page that replaced them.
+
## Markdown
Every page has a Markdown twin: append `.md` to its URL, or send `Accept: text/markdown`.
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
index 48ef78bf75..f20cbcea46 100644
--- a/docs/content/docs/index.mdx
+++ b/docs/content/docs/index.mdx
@@ -1,10 +1,10 @@
---
-title: Cua documentation
-description: Computers for you and your agents. Cua Spaces, Cua Driver, Lume and the developer tools, on your own machines.
+title: Cua Docs
+description: 'Give your agents their own computers with Cua Spaces. Watch them work, step in when you want, and share with your team.'
landing:
- hero: Cua Developers
- path: 'New to Cua? Open Cua Spaces for the five-minute quickstart. These walkthroughs cover the other products, from setup to a result you can check.'
- products: [spaces, cua-driver, lume, cua-sdk]
+ hero: Cua Docs
+ path: 'Start with the Cua Spaces quickstart. It takes about five minutes.'
+ products: [spaces, cua-driver]
examples:
- title: Cua Bots
description: Persistent bots on Cua Spaces, each with its own computer, memory, routines and rules. A Mac and iPhone app in SwiftUI.
@@ -17,7 +17,7 @@ landing:
- title: Source on GitHub
href: https://github.com/trycua/cua/tree/main/samples/cua-bots-macos
- title: 'Background computer-use with **Cua Driver**'
- description: 'An MCP tool for your agent. In this example, it builds and QAs a WPF app on Windows while you keep working.'
+ description: 'Your agent builds and tests a Windows app in the background while you keep working.'
href: /cua-driver/guides/recipes
cta: Cua Driver recipes
video: https://trycua.github.io/assets/videos/cua-driver/windows-wpf-agent-qa.mp4
@@ -32,51 +32,38 @@ import { Card, Cards } from 'fumadocs-ui/components/card';
<Cards>
<Card title="Cua Spaces" href="/spaces">
- Computers for you and your agents. Install the app, connect an agent and watch it work.
+ Computers for you and your agents. Install the app, connect an agent and watch it work. Start with the five-minute [quickstart](/spaces/quickstart).
</Card>
<Card title="Cua Driver" href="/cua-driver">
- Let an agent drive native apps on macOS, Windows and Linux in the background.
- </Card>
- <Card title="Lume" href="/lume">
- macOS and Linux VMs on Apple silicon.
+ Let an agent use the apps on your computer in the background, on macOS, Windows and Linux. Start with the [quickstart](/cua-driver/quickstart).
</Card>
</Cards>
-## Developers
-
-<Cards>
- <Card title="Cua SDK" href="/cua-sdk">
- Create and drive computers from your own code. Python, TypeScript, Swift and Rust.
- </Card>
- <Card title="Cua CLI" href="/cua-cli">
- `cua`: sandboxes, auth, the daemon and MCP from the terminal.
- </Card>
- <Card title="Cua Bench" href="/cua-bench">
- Run and score computer-use benchmarks on your machine.
- </Card>
-</Cards>
-
-## Start with Cua Spaces
+## Cua Spaces
- [Quickstart](/spaces/quickstart): install the app, connect your agent and run a first task in about five minutes.
- [Connect your agent](/spaces/guides/connect-your-agent): add Spaces to Claude Code, Codex, Cursor and other agents.
-- [Add a machine](/spaces/guides/add-a-machine): connect another Mac, Linux or Windows computer you own.
-- [Plans](/spaces/guides/plans): what Free, Pro and Teams include.
+- [Add a computer](/spaces/guides/add-a-computer): connect another Mac, Linux or Windows computer you own.
+- [Teams](/spaces/guides/teams): share computers with your team, and what each plan includes.
+- [How Spaces works](/spaces/concepts/how-spaces-works): what runs where, in plain words.
+
+## Cua Driver
-## More walkthroughs
+- [Quickstart](/cua-driver/quickstart): install Cua Driver and have your agent use a calculator.
+- [Connect your agent](/cua-driver/guides/connect-your-agent): add Cua Driver to Claude Code, Codex and other agents.
+- [Tool reference](/cua-driver/reference): every command and every tool.
-- [Sandbox images](/start-here/sandbox-images): the desktop and benchmark images, and one line to start each.
-- [Drive your first app with Cua Driver](/start-here/drive-your-first-app): let your agent operate a native app on the machine you already have.
-- [Create a local macOS sandbox with the Cua CLI](/start-here/create-a-local-macos-sandbox): a macOS Tahoe sandbox on Apple silicon with `cua sb create macos`.
-- [Run a sandbox in GitHub Actions](/start-here/run-in-github-actions): a Linux sandbox per CI job, with logs and a screenshot as artifacts.
-- [Build your first Cua Bench task](/start-here/your-first-cua-bench-task): create a task, score it with its oracle, then hand it to an agent.
+## More tools
+
+- [Cua CLI](/cua-cli): the `cua` command for Spaces, sandboxes, sign-in and MCP.
+- [Cua SDK](/cua-sdk): create and drive computers from your own code, in Python, TypeScript, Swift and Rust.
+- [Lume](/lume): macOS and Linux virtual machines on Apple silicon.
+- [Cua Bench](/cua-bench): run and score computer-use tests on your computer.
+- [Docs for agents](/docs-for-agents): give a coding agent these docs as Markdown or over MCP.
## Examples
-- [Cua Bots](/spaces/examples/cua-bots): persistent bots on Cua Spaces, each with its own computer, in a Mac and iPhone app. The same kind of app in TypeScript, Rust (Tauri) and Swift is in [Examples in other languages](/spaces/examples/other-languages).
-- [Background computer-use with Cua Driver](/cua-driver/guides/recipes): an MCP tool for your agent. In this example, it builds and QAs a WPF app on Windows ([video](https://x.com/trycua/status/2059688966085853245)).
+- [Cua Bots](/spaces/examples/cua-bots): bots that each have their own computer, in a Mac and iPhone app. The same kind of app in TypeScript, Rust and Swift is in [Use Spaces from code](/spaces/guides/create-a-space-with-the-sdk).
+- [Background computer use with Cua Driver](/cua-driver/guides/recipes): your agent builds and tests a Windows app while you keep working ([video](https://x.com/trycua/status/2059688966085853245)).
![Cua Bots: a bot finished its research, with the result card, a notification and its profile](/img/cua-bots/cua-bots-mac-research-ready.png)
-
-Coding agents can read these docs as Markdown or query them over MCP: see [Docs for agents](/docs-for-agents).
-Service status: [status.cua.ai](https://status.cua.ai).
diff --git a/docs/content/docs/lume/concepts/how-lume-works.mdx b/docs/content/docs/lume/concepts/how-lume-works.mdx
index b3c61e51d4..59b005b393 100644
--- a/docs/content/docs/lume/concepts/how-lume-works.mdx
+++ b/docs/content/docs/lume/concepts/how-lume-works.mdx
@@ -3,6 +3,9 @@ title: How Lume works
description: 'Offline unattended setup, SIP through paired Recovery, macOS disk growth with rollback, and what Lume telemetry collects.'
---
+This page explains what Lume does behind a few commands, and what its
+telemetry collects.
+
## Unattended setup
`lume create --unattended tahoe` (or `sequoia`) never clicks through Setup
diff --git a/docs/content/docs/lume/guides/api-and-mcp.mdx b/docs/content/docs/lume/guides/api-and-mcp.mdx
deleted file mode 100644
index 23494db7a1..0000000000
--- a/docs/content/docs/lume/guides/api-and-mcp.mdx
+++ /dev/null
@@ -1,52 +0,0 @@
----
-title: Drive Lume from scripts and agents
-description: 'Drive Lume from scripts through its local HTTP API, or from an AI client through its MCP server.'
----
-
-Both interfaces control the same VM store as the CLI. Use the API for scripts
-and services, MCP for AI clients.
-
-## HTTP API
-
-The installer runs `lume serve` at login on port 7777 (install with
-`--no-background-service` to manage it yourself):
-
-```bash test="cli-shape" id="lume-serve"
-lume serve # localhost:7777
-lume serve --port 7778
-```
-
-```bash skip="no-runner"
-curl http://localhost:7777/lume/vms
-```
-
-It listens on `localhost` only. Keep it there unless you have a network
-boundary and an authentication plan. Endpoints:
-[HTTP API reference](/lume/reference/http-api).
-
-## MCP server
-
-`lume serve --mcp` speaks MCP over stdio, so the client starts it. Use the path
-from `which lume`:
-
-```json test="config" id="json-config" schema="mcp-client-config"
-{
- "mcpServers": {
- "lume": {
- "command": "/Users/your-name/.local/bin/lume",
- "args": ["serve", "--mcp"]
- }
- }
-}
-```
-
-Restart the client. It can list, create, run, stop, clone and resize VMs and
-run SSH commands in unattended guests ([MCP tools](/lume/reference/mcp-tools)).
-Test the server with:
-
-```bash skip="third-party-cli"
-npx @modelcontextprotocol/inspector lume serve --mcp
-```
-
-The MCP server can create, delete and SSH into VMs. Configure it only for
-clients you trust, and give agents a dedicated VM.
diff --git a/docs/content/docs/lume/guides/gpu-passthrough.mdx b/docs/content/docs/lume/guides/gpu-passthrough.mdx
index fa765480df..de0068cb6e 100644
--- a/docs/content/docs/lume/guides/gpu-passthrough.mdx
+++ b/docs/content/docs/lume/guides/gpu-passthrough.mdx
@@ -5,11 +5,12 @@ description: 'Unlock a tested Metal capability profile for one workload inside a
import { Callout } from 'fumadocs-ui/components/callout';
-A stock macOS guest reports conservative Metal capabilities, so some apps skip
-GPU paths the paravirtualized device can run. A small MIT shim, injected into
-one process, raises two answers: `supportsFamily:` up to a configured Apple
-family, and the maximum threadgroup memory. It does not pass a physical GPU
-through, patch the host, or touch the guest kernel. Background and benchmarks:
+A macOS VM reports fewer Metal features than its virtual GPU can run, so some
+apps skip the GPU. A small MIT-licensed shim, loaded into one process, changes
+two of those answers: the Apple GPU family that `supportsFamily:` reports (up to
+a family you choose), and the maximum threadgroup memory. It does not pass a
+physical GPU to the VM, patch the host or touch the guest kernel. For background
+and benchmarks, read the
[technical writeup](https://cua.ai/blog/gpu-passthrough-macos-vms).
<Callout type="warn">
diff --git a/docs/content/docs/lume/guides/linux-guests.mdx b/docs/content/docs/lume/guides/linux-guests.mdx
index e833ca1aed..574530a57e 100644
--- a/docs/content/docs/lume/guides/linux-guests.mdx
+++ b/docs/content/docs/lume/guides/linux-guests.mdx
@@ -5,6 +5,9 @@ description: 'Run Omarchy on an ARM64 Arch Linux guest with optional Rosetta, an
import { Callout } from 'fumadocs-ui/components/callout';
+This page covers two setups: an Omarchy Linux desktop on an ARM64 guest, and an
+isolated macOS VM that runs an OpenClaw gateway.
+
## Omarchy on ARM64
Official Omarchy 4.0.1 source (commit
diff --git a/docs/content/docs/lume/guides/manage-vms.mdx b/docs/content/docs/lume/guides/manage-vms.mdx
index ed7cf42b02..3ea6f3fd04 100644
--- a/docs/content/docs/lume/guides/manage-vms.mdx
+++ b/docs/content/docs/lume/guides/manage-vms.mdx
@@ -1,8 +1,11 @@
---
title: Manage VMs
-description: 'Run, attach to, share folders with, store, clone, resize and remove Lume VMs, change SIP, and update Lume.'
+description: 'Run, attach to, share folders with, store, clone, resize and remove Lume VMs, change SIP, update Lume, and drive Lume from scripts or an AI client.'
---
+These are the everyday Lume commands. The examples use a VM named
+`macos-tahoe`; use your own VM's name.
+
## Inspect
```bash test="cli-shape,lume" id="lume-ls"
@@ -85,15 +88,17 @@ lume run --no-display macos-tahoe
lume ssh macos-tahoe 'diskutil info / | grep "Container Total Space"'
```
-Increase only, on a stopped VM with the standard layout, no FileVault, and a
-host macOS at least as new as the guest. `--no-backup` removes automatic
-rollback. Linux guests: Lume grows the image; grow the partition and
-filesystem in the guest. [How it works](/lume/concepts/how-lume-works#disk-growth).
+You can only make a disk bigger. The VM must be stopped, use the standard disk
+layout and have FileVault off, and the host macOS must be at least as new as the
+guest. `--no-backup` skips the rollback copy. For a Linux guest, Lume grows the
+disk image, and you then grow the partition and filesystem inside the guest.
+See [how disk growth works](/lume/concepts/how-lume-works#disk-growth).
-## Change SIP
+## Turn SIP on or off
-The VM must be macOS, stopped, with a working admin account and Remote Login
-(true for unattended VMs). Install the Recovery VNC driver once:
+System Integrity Protection (SIP) is macOS's protection for system files. The
+VM must be macOS and stopped, with a working admin account and Remote Login
+(unattended VMs already have both). Install the Recovery VNC driver once:
```bash skip="host-install"
python3 -m pip install --user vncdotool
@@ -106,11 +111,11 @@ printf '%s\n' "$LUME_ADMIN_PASSWORD" | \
lume sip off macos-tahoe --admin-user admin --admin-password-stdin --yes
```
-A successful run ends with `System Integrity Protection status: disabled.` (or
-`enabled.`) from a normal boot and leaves the VM stopped. Recovery input accepts
-admin passwords of lowercase letters, digits and hyphens. For many SIP-disabled
-VMs, change a seed once and `lume clone` it.
-[How it works](/lume/concepts/how-lume-works#sip).
+A successful run prints `System Integrity Protection status: disabled.` (or
+`enabled.`) from a normal boot and leaves the VM stopped. The admin password can
+use only lowercase letters, digits and hyphens, because Lume types it into
+Recovery. To get many VMs with SIP off, change one seed VM and `lume clone` it.
+See [how SIP changes work](/lume/concepts/how-lume-works#sip).
## Update Lume
@@ -128,6 +133,56 @@ curl -fsSL https://cua.ai/lume/install.sh | \
Stable is the default. A pinned nightly does not change the saved channel.
+## Drive Lume from scripts and AI clients
+
+The HTTP API and the MCP server control the same VMs as the `lume` command. Use
+the API from scripts and services, and MCP from AI clients.
+
+### Use the HTTP API
+
+The installer starts `lume serve` at login on port 7777. Install with
+`--no-background-service` to start it yourself:
+
+```bash test="cli-shape" id="lume-serve"
+lume serve # localhost:7777
+lume serve --port 7778
+```
+
+```bash skip="no-runner"
+curl http://localhost:7777/lume/vms
+```
+
+The API listens on `localhost` only. Keep it there unless you have a network
+boundary and a plan for authentication. Every endpoint is in the
+[HTTP API reference](/lume/reference/http-api).
+
+### Connect an MCP client
+
+`lume serve --mcp` speaks MCP over stdio, so the AI client starts it. Use the
+path that `which lume` prints:
+
+```json test="config" id="json-config" schema="mcp-client-config"
+{
+ "mcpServers": {
+ "lume": {
+ "command": "/Users/your-name/.local/bin/lume",
+ "args": ["serve", "--mcp"]
+ }
+ }
+}
+```
+
+Restart the client. It can then list, create, run, stop, clone and resize VMs,
+and run SSH commands in unattended guests (see the
+[MCP tools](/lume/reference/mcp-tools)). To test the server on its own:
+
+```bash skip="third-party-cli"
+npx @modelcontextprotocol/inspector lume serve --mcp
+```
+
+The MCP server can create and delete VMs and run commands in them. Configure it
+only for clients you trust, and give an agent its own VM.
+
## Troubleshooting
| Symptom | Fix |
diff --git a/docs/content/docs/lume/guides/meta.json b/docs/content/docs/lume/guides/meta.json
index 751f3b86ba..625665767e 100644
--- a/docs/content/docs/lume/guides/meta.json
+++ b/docs/content/docs/lume/guides/meta.json
@@ -3,7 +3,6 @@
"pages": [
"manage-vms",
"gpu-passthrough",
- "api-and-mcp",
"linux-guests"
]
}
diff --git a/docs/content/docs/lume/index.mdx b/docs/content/docs/lume/index.mdx
index 8760e5470d..ffcaced06b 100644
--- a/docs/content/docs/lume/index.mdx
+++ b/docs/content/docs/lume/index.mdx
@@ -1,12 +1,14 @@
---
title: Lume
description: 'Create and run macOS and Linux VMs on Apple silicon from the CLI, a local HTTP API or MCP.'
+landing:
+ summary: 'macOS and Linux virtual machines on Apple silicon.'
---
-Lume is a VM manager for Apple silicon Macs, built on Apple's
-Virtualization.framework. It creates vanilla macOS VMs straight from Apple
-restore images with SSH and autologin ready, runs Linux guests, and exposes the
-same VM store through the `lume` CLI, a local HTTP API and an MCP server.
+Lume runs macOS and Linux virtual machines (VMs) on an Apple silicon Mac, using
+Apple's Virtualization.framework. It builds a vanilla macOS VM straight from
+Apple's restore image, with SSH and autologin ready. You control the same VMs
+from the `lume` command, a local HTTP API or an MCP server for AI clients.
```bash test="cli-shape" id="lume-overview"
lume create macos-tahoe --ipsw latest --unattended tahoe
@@ -14,10 +16,11 @@ lume run macos-tahoe
lume ssh macos-tahoe 'sw_vers'
```
-The [cua SDK](/cua-sdk) installs and drives Lume itself for local macOS
-sandboxes; use Lume directly when you want the VMs yourself.
+The [cua SDK](/cua-sdk) installs and drives Lume for you when you ask for a
+local macOS sandbox. Use Lume directly when you want to manage the VMs
+yourself.
-| Requirement | |
+| Requirement | Detail |
|---|---|
| Host | Apple silicon, macOS 13 or later |
| Memory | 8 GB free (16 GB for an 8 GB guest) |
@@ -26,9 +29,8 @@ sandboxes; use Lume directly when you want the VMs yourself.
## Next
-- [Quickstart](/lume/quickstart): install, create a Tahoe VM, SSH in.
-- [Manage VMs](/lume/guides/manage-vms): run, attach, share folders, storage, clone, resize, SIP, updates.
-- [GPU passthrough](/lume/guides/gpu-passthrough): unlock Metal capabilities for one workload.
-- [API and MCP](/lume/guides/api-and-mcp): drive Lume from scripts or an AI client.
+- [Quickstart](/lume/quickstart): install Lume, create a Tahoe VM, SSH in.
+- [Manage VMs](/lume/guides/manage-vms): run, share folders, clone, resize, turn SIP off, update, and use the HTTP API or MCP.
+- [GPU passthrough](/lume/guides/gpu-passthrough): unlock more Metal features for one workload.
- [Linux guests](/lume/guides/linux-guests): Omarchy on ARM64, and an OpenClaw gateway.
-- [How Lume works](/lume/concepts/how-lume-works): unattended setup, SIP, disk growth, telemetry.
+- [How Lume works](/lume/concepts/how-lume-works): unattended setup, SIP, disk growth and telemetry.
diff --git a/docs/content/docs/lume/quickstart.mdx b/docs/content/docs/lume/quickstart.mdx
index 60a3737ea7..9872d0d34d 100644
--- a/docs/content/docs/lume/quickstart.mdx
+++ b/docs/content/docs/lume/quickstart.mdx
@@ -22,10 +22,11 @@ lume --version
lume create macos-tahoe --ipsw latest --unattended tahoe
```
-`--ipsw latest` downloads the newest supported restore image (or pass a local
-`.ipsw`; `lume ipsw` prints the URL). The `tahoe` preset prepares the guest
-offline: user `lume` with password `lume`, SSH, autologin, no sleep or screen
-lock. Creation boots once, checks SSH and leaves the VM stopped.
+`--ipsw latest` downloads the newest restore image Lume supports. To use a file
+you already have, pass its `.ipsw` path; `lume ipsw` prints the download URL.
+The `tahoe` preset sets up the guest without clicking through Setup Assistant:
+user `lume` with password `lume`, SSH on, autologin, and no sleep or screen
+lock. Lume boots the VM once, checks that SSH answers, and leaves it stopped.
```bash test="cli-shape" id="lume-run-macos-tahoe"
lume run macos-tahoe
@@ -39,7 +40,7 @@ The VM's desktop opens in Lume's viewer. From another terminal:
lume ssh macos-tahoe 'sw_vers; id -un'
```
-prints the guest's macOS version and `lume`. Change the password before using
+prints the guest's macOS version and `lume`. Change the password before you use
the VM for anything sensitive.
![lume ls listing local macOS VMs](/img/lume/lume-ls.png)
@@ -54,5 +55,5 @@ lume delete macos-tahoe
## Next
- [Manage VMs](/lume/guides/manage-vms)
-- [Drive Lume from scripts and agents](/lume/guides/api-and-mcp)
+- [Drive Lume from scripts and AI clients](/lume/guides/manage-vms#drive-lume-from-scripts-and-ai-clients)
- [CLI reference](/lume/reference/cli)
diff --git a/docs/content/docs/lume/reference/mcp-tools.mdx b/docs/content/docs/lume/reference/mcp-tools.mdx
index 4d787e7393..375f7d0106 100644
--- a/docs/content/docs/lume/reference/mcp-tools.mdx
+++ b/docs/content/docs/lume/reference/mcp-tools.mdx
@@ -10,7 +10,7 @@ description: "Every tool Lume's MCP server exposes, with its parameters."
Version: 0.6.1
*/}
-`lume serve --mcp` serves these tools over stdio. See [API and MCP](/lume/guides/api-and-mcp) for client setup.
+`lume serve --mcp` serves these tools over stdio. See [Connect an MCP client](/lume/guides/manage-vms#connect-an-mcp-client) for client setup.
## VM tools
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index c9a057182e..43dfce3867 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -3,12 +3,12 @@
"root": true,
"pages": [
"index",
- "start-here",
"spaces",
"cua-driver",
- "lume",
- "cua-sdk",
+ "---More tools---",
"cua-cli",
+ "cua-sdk",
+ "lume",
"cua-bench"
]
}
diff --git a/docs/content/docs/redirects.json b/docs/content/docs/redirects.json
index 8888563645..587a4cd6d1 100644
--- a/docs/content/docs/redirects.json
+++ b/docs/content/docs/redirects.json
@@ -1,12 +1,16 @@
{
"$comment": "Old docs slug -> current slug. Read by the docs.cua.ai renderer and next.config. When a page is merged or removed, point its entry (and entries targeting it) at the page that preserves its intent.",
"redirects": {
+ "driver": "cua-driver",
+ "cli": "cua-cli",
+ "sdk": "cua-sdk",
+ "bench": "cua-bench",
"cloud-fleets": "cua-sdk/guides/cua-cloud-ended",
"concepts": "",
"concepts/architecture": "cua-sdk/concepts/how-sandboxes-work",
"concepts/browser-targeting-and-background-delivery": "cua-driver/guides/browsers",
"concepts/capture-and-delivery-modalities": "cua-driver/concepts/how-cua-driver-works",
- "concepts/choose-a-cua-driver-integration": "cua-driver",
+ "concepts/choose-a-cua-driver-integration": "cua-driver/concepts/how-cua-driver-works#choose-an-integration",
"concepts/cua-bench-task-lifecycle": "cua-bench",
"concepts/how-cua-driver-is-validated": "cua-driver/concepts/how-cua-driver-works",
"concepts/how-fleet-images-work": "cua-sdk/guides/images",
@@ -15,7 +19,7 @@
"concepts/how-permission-policies-work": "cua-driver/guides/permissions",
"concepts/how-sandboxes-work": "cua-sdk/concepts/how-sandboxes-work",
"concepts/how-sip-works-in-lume-vms": "lume/concepts/how-lume-works",
- "concepts/how-the-perception-extension-works": "cua-driver/concepts/perception-extension",
+ "concepts/how-the-perception-extension-works": "cua-driver/concepts/how-cua-driver-works#the-optional-perception-extension",
"concepts/linux-desktops-and-computer-use": "cua-driver/concepts/platform-support",
"concepts/pools-claims-and-guest-services": "cua-sdk/guides/cua-cloud-ended",
"concepts/sandbox-lifecycle": "cua-sdk/guides/lifecycle",
@@ -44,7 +48,7 @@
"cua-driver/concepts/browser-targeting-and-background-delivery": "cua-driver/guides/browsers",
"cua-driver/concepts/capture-and-delivery-modalities": "cua-driver/concepts/how-cua-driver-works",
"cua-driver/concepts/choose-an-integration": "cua-driver",
- "cua-driver/concepts/computer-history": "cua-driver/guides/trajectories",
+ "cua-driver/concepts/computer-history": "cua-driver/guides/operate#record-a-trajectory",
"cua-driver/concepts/contracts": "cua-driver/concepts/how-cua-driver-works",
"cua-driver/concepts/development": "cua-driver",
"cua-driver/concepts/embedding": "cua-driver/guides/use-the-sdk",
@@ -76,7 +80,7 @@
"cua-driver/guides/recipes/fill-a-form-from-a-local-file": "cua-driver/guides/recipes",
"cua-driver/guides/recipes/prepare-an-exhibition-panel": "cua-driver/guides/recipes",
"cua-driver/guides/recipes/redact-and-annotate-a-pdf": "cua-driver/guides/recipes",
- "cua-driver/guides/record-and-render-a-trajectory": "cua-driver/guides/trajectories",
+ "cua-driver/guides/record-and-render-a-trajectory": "cua-driver/guides/operate#record-a-trajectory",
"cua-driver/guides/restrict-tool-access": "cua-driver/guides/permissions",
"cua-driver/guides/run-in-macos-lume-vm": "cua-driver/guides/vms-and-remote",
"cua-driver/guides/run-tests-in-macos-lume-vm": "cua-driver/guides/vms-and-remote",
@@ -85,7 +89,7 @@
"cua-driver/guides/update": "cua-driver/guides/operate",
"cua-driver/guides/use-claude-agent-sdk": "cua-driver/guides/connect-your-agent",
"cua-driver/guides/use-codex-sdk": "cua-driver/guides/connect-your-agent",
- "cua-driver/guides/use-computer-history": "cua-driver/guides/trajectories",
+ "cua-driver/guides/use-computer-history": "cua-driver/guides/operate#record-a-trajectory",
"cua-driver/guides/use-cua-with": "cua-driver/guides/connect-your-agent",
"cua-driver/guides/use-cua-with/anthropic": "cua-driver/guides/connect-your-agent",
"cua-driver/guides/use-cua-with/antigravity-cli": "cua-driver/guides/connect-your-agent",
@@ -150,7 +154,7 @@
"cua-sdk/reference/api/spaces": "cua-sdk/reference/spaces",
"cua-sdk/reference/api/teleport": "cua-sdk/reference/spaces/teleport",
"cua-sdk/reference/api/types": "cua-sdk/reference/types",
- "cua-sdk/reference/disk-usage": "cua-sdk/guides/disk-usage",
+ "cua-sdk/reference/disk-usage": "cua-sdk/guides/lifecycle#disk-usage-and-cleanup",
"cua-sdk/reference/rust/cua-sdk-guest": "cua-sdk/reference/rust/cua-sdk",
"cua-sdk/reference/rust/cua-sdk-sandboxes": "cua-sdk/reference/rust/cua-sdk",
"cua-sdk/reference/rust/cua-sdk-spaces": "cua-sdk/reference/rust/cua-sdk",
@@ -167,11 +171,11 @@
"cua-sdk/reference/sandbox/pool": "cua-sdk/guides/cua-cloud-ended",
"cua-sdk/reference/sandbox/runtime-support": "cua-sdk/reference/runtime-support",
"cua-sdk/reference/sandbox/typescript": "cua-sdk/reference/typescript",
- "cua/reference/agent-sdk": "cua-sdk/guides/migrate-from-deprecated-packages",
- "cua/reference/computer-sdk": "cua-sdk/guides/migrate-from-deprecated-packages",
- "cuabot": "cua-sdk/guides/migrate-from-deprecated-packages",
- "cuabot/cuabot": "cua-sdk/guides/migrate-from-deprecated-packages",
- "cuabot/install": "cua-sdk/guides/migrate-from-deprecated-packages",
+ "cua/reference/agent-sdk": "cua-sdk/guides/cua-cloud-ended#deprecated-packages",
+ "cua/reference/computer-sdk": "cua-sdk/guides/cua-cloud-ended#deprecated-packages",
+ "cuabot": "cua-sdk/guides/cua-cloud-ended#deprecated-packages",
+ "cuabot/cuabot": "cua-sdk/guides/cua-cloud-ended#deprecated-packages",
+ "cuabot/install": "cua-sdk/guides/cua-cloud-ended#deprecated-packages",
"fleets/concepts": "cua-sdk/guides/cua-cloud-ended",
"fleets/concepts/how-fleet-images-work": "cua-sdk/guides/images",
"fleets/concepts/pools-claims-and-guest-services": "cua-sdk/guides/cua-cloud-ended",
@@ -185,9 +189,9 @@
"fleets": "cua-sdk/guides/cua-cloud-ended",
"fleets/guides": "cua-sdk/guides/cua-cloud-ended",
"fleets/guides/capacity-and-claims": "cua-sdk/guides/cua-cloud-ended",
- "fleets/guides/claim-secrets": "cua-sdk/guides/secrets",
+ "fleets/guides/claim-secrets": "cua-sdk/guides/services",
"fleets/guides/images": "cua-sdk/guides/images",
- "fleets/guides/sidecars": "cua-sdk/guides/sidecars",
+ "fleets/guides/sidecars": "cua-sdk/guides/services",
"fleets/guides/terraform": "cua-sdk/guides/cua-cloud-ended",
"fleets/guides/troubleshoot": "cua-sdk/guides/cua-cloud-ended",
"fleets/guides/warm-pools": "cua-sdk/guides/cua-cloud-ended",
@@ -206,7 +210,7 @@
"fleets/reference/terraform": "cua-sdk/guides/cua-cloud-ended",
"how-to-guides": "",
"how-to-guides/agent-context/connect-your-agent-to-cua-docs": "docs-for-agents",
- "how-to-guides/cua-bench/convert-benchmark-images": "cua-bench/guides/convert-benchmark-images",
+ "how-to-guides/cua-bench/convert-benchmark-images": "cua-bench/guides/benchmarks#build-a-benchmark-image",
"how-to-guides/cua-bench/run-a-task": "cua-bench/quickstart",
"how-to-guides/driver/connect-your-agent": "cua-driver/guides/connect-your-agent",
"how-to-guides/driver/drive-a-web-page": "cua-driver/guides/browsers",
@@ -217,7 +221,7 @@
"how-to-guides/driver/keep-running": "cua-driver/guides/operate",
"how-to-guides/driver/parse-visual-regions": "cua-driver/guides/visual-regions",
"how-to-guides/driver/personalize-cursor": "cua-driver/guides/operate",
- "how-to-guides/driver/record-and-render-a-trajectory": "cua-driver/guides/trajectories",
+ "how-to-guides/driver/record-and-render-a-trajectory": "cua-driver/guides/operate#record-a-trajectory",
"how-to-guides/driver/restrict-tool-access": "cua-driver/guides/permissions",
"how-to-guides/driver/run-in-macos-lume-vm": "cua-driver/guides/vms-and-remote",
"how-to-guides/driver/run-tests-in-macos-lume-vm": "cua-driver/guides/vms-and-remote",
@@ -226,7 +230,7 @@
"how-to-guides/driver/update": "cua-driver/guides/operate",
"how-to-guides/driver/use-claude-agent-sdk": "cua-driver/guides/connect-your-agent",
"how-to-guides/driver/use-codex-sdk": "cua-driver/guides/connect-your-agent",
- "how-to-guides/driver/use-computer-history": "cua-driver/guides/trajectories",
+ "how-to-guides/driver/use-computer-history": "cua-driver/guides/operate#record-a-trajectory",
"how-to-guides/driver/use-jev-use-with-native-apps": "cua-driver/guides/visual-regions",
"how-to-guides/driver/use-jev-use-with-visual-regions": "cua-driver/guides/visual-regions",
"how-to-guides/driver/use-sdk-in-process": "cua-driver/guides/use-the-sdk",
@@ -241,8 +245,8 @@
"how-to-guides/lume/manage-vms": "lume/guides/manage-vms",
"how-to-guides/lume/run-omarchy-arm64": "lume/guides/linux-guests",
"how-to-guides/lume/run-openclaw": "lume/guides/linux-guests",
- "how-to-guides/lume/serve-api": "lume/guides/api-and-mcp",
- "how-to-guides/lume/use-mcp-server": "lume/guides/api-and-mcp",
+ "how-to-guides/lume/serve-api": "lume/guides/manage-vms#drive-lume-from-scripts-and-ai-clients",
+ "how-to-guides/lume/use-mcp-server": "lume/guides/manage-vms#drive-lume-from-scripts-and-ai-clients",
"how-to-guides/recipes/automate-a-legacy-windows-app-behind-a-vpn": "cua-driver/guides/recipes",
"how-to-guides/recipes/build-a-report-in-a-native-app": "cua-driver/guides/recipes",
"how-to-guides/recipes/build-and-inspect-a-map": "cua-driver/guides/recipes",
@@ -275,19 +279,19 @@
"how-to-guides/sandbox/run-openclaw-on-cloud-fleet": "cua-sdk/guides/agent-frameworks",
"how-to-guides/sandbox/run-osworld-on-cloud-fleet": "cua-bench/guides/benchmarks",
"how-to-guides/sandbox/scale-out": "cua-sdk/guides/lifecycle",
- "how-to-guides/sandbox/secrets": "cua-sdk/guides/secrets",
+ "how-to-guides/sandbox/secrets": "cua-sdk/guides/services#secrets",
"how-to-guides/sandbox/services": "cua-sdk/guides/services",
"how-to-guides/sandbox/set-up-fleet-credentials": "cua-sdk/guides/cua-cloud-ended",
"how-to-guides/sandbox/share-service-with-signed-url": "cua-sdk/guides/services",
- "how-to-guides/sandbox/sidecars": "cua-sdk/guides/sidecars",
+ "how-to-guides/sandbox/sidecars": "cua-sdk/guides/services#sidecars",
"how-to-guides/sandbox/troubleshoot-fleet-pools": "cua-sdk/guides/cua-cloud-ended",
"how-to-guides/sandbox/tunneling": "cua-sdk/guides/services",
"how-to-guides/spaces/add-a-space": "spaces/guides/add-a-space",
"how-to-guides/spaces/install-cua": "spaces/quickstart",
- "how-to-guides/spaces/set-up-unattended-access": "spaces/guides/unattended-access",
+ "how-to-guides/spaces/set-up-unattended-access": "spaces/guides/add-a-computer#add-a-computer-from-a-terminal",
"how-to-guides/spaces/stream-a-desktop": "spaces/guides/stream-a-desktop",
"how-to-guides/spaces/teleport-an-app": "spaces/guides/teleport-an-app",
- "how-to-guides/spaces/use-spaces-from-an-agent": "spaces/guides/use-from-an-agent",
+ "how-to-guides/spaces/use-spaces-from-an-agent": "spaces/guides/connect-your-agent#what-your-agent-can-do",
"local-sandboxes": "cua-sdk/guides/local-runtimes",
"lume/concepts/how-lume-expands-macos-disks": "lume/concepts/how-lume-works",
"lume/concepts/how-lume-unattended-setup-works": "lume/concepts/how-lume-works",
@@ -300,8 +304,8 @@
"lume/guides/install-lume": "lume/quickstart",
"lume/guides/run-omarchy-arm64": "lume/guides/linux-guests",
"lume/guides/run-openclaw": "lume/guides/linux-guests",
- "lume/guides/serve-api": "lume/guides/api-and-mcp",
- "lume/guides/use-mcp-server": "lume/guides/api-and-mcp",
+ "lume/guides/serve-api": "lume/guides/manage-vms#drive-lume-from-scripts-and-ai-clients",
+ "lume/guides/use-mcp-server": "lume/guides/manage-vms#drive-lume-from-scripts-and-ai-clients",
"reference": "",
"reference/cua-bench/cli-reference": "cua-bench/reference/cli",
"reference/cua-bench/task-definition": "cua-bench/reference/task-definition",
@@ -314,7 +318,7 @@
"reference/cua-driver/browser-profile-attachment": "cua-driver/guides/browsers",
"reference/cua-driver/browser-semantic-snapshots": "cua-driver/guides/browsers",
"reference/cua-driver/cli-reference": "cua-driver/reference/cli",
- "reference/cua-driver/computer-history": "cua-driver/guides/trajectories",
+ "reference/cua-driver/computer-history": "cua-driver/guides/operate#record-a-trajectory",
"reference/cua-driver/contracts": "cua-driver/concepts/how-cua-driver-works",
"reference/cua-driver/development": "cua-driver",
"reference/cua-driver/embedding": "cua-driver/guides/use-the-sdk",
@@ -357,7 +361,7 @@
"reference/cua-sdk/api/spaces": "cua-sdk/reference/spaces",
"reference/cua-sdk/api/teleport": "cua-sdk/reference/spaces/teleport",
"reference/cua-sdk/api/types": "cua-sdk/reference/types",
- "reference/cua-sdk/disk-usage": "cua-sdk/guides/disk-usage",
+ "reference/cua-sdk/disk-usage": "cua-sdk/guides/lifecycle#disk-usage-and-cleanup",
"reference/cua-sdk/python": "cua-sdk/reference/python",
"reference/cua-sdk/rust": "cua-sdk/reference/rust",
"reference/cua-sdk/rust/cua-fleet": "cua-sdk/guides/cua-cloud-ended",
@@ -395,22 +399,22 @@
"reference/sandbox-sdk/runtime-support": "cua-sdk/reference/runtime-support",
"reference/sandbox-sdk/typescript": "cua-sdk/reference/typescript",
"sandboxes": "cua-sdk",
- "spaces/guides/set-up-unattended-access": "spaces/guides/unattended-access",
- "spaces/guides/use-spaces-from-an-agent": "spaces/guides/use-from-an-agent",
+ "spaces/guides/set-up-unattended-access": "spaces/guides/add-a-computer#add-a-computer-from-a-terminal",
+ "spaces/guides/use-spaces-from-an-agent": "spaces/guides/connect-your-agent#what-your-agent-can-do",
"tutorials": "",
- "start-here": "",
- "tutorials/building-openkoalabots-with-cua-spaces": "spaces/examples/other-languages",
- "spaces/guides/build-openkoalabots": "spaces/examples/other-languages",
- "start-here/build-openkoalabots": "spaces/examples/other-languages",
- "spaces/examples/openkoalabots": "spaces/examples/other-languages",
- "tutorials/create-your-first-lume-vm": "start-here/create-a-local-macos-sandbox",
- "start-here/create-your-first-lume-vm": "start-here/create-a-local-macos-sandbox",
- "tutorials/drive-your-first-app": "start-here/drive-your-first-app",
+ "start-here": "spaces/quickstart",
+ "tutorials/building-openkoalabots-with-cua-spaces": "spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages",
+ "spaces/guides/build-openkoalabots": "spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages",
+ "start-here/build-openkoalabots": "spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages",
+ "spaces/examples/openkoalabots": "spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages",
+ "tutorials/create-your-first-lume-vm": "cua-cli/quickstart#macos-sandbox",
+ "start-here/create-your-first-lume-vm": "cua-cli/quickstart#macos-sandbox",
+ "tutorials/drive-your-first-app": "cua-driver/quickstart",
"tutorials/your-first-cloud-fleet": "spaces/guides/create-a-space-with-the-sdk",
"start-here/your-first-cloud-fleet": "spaces/guides/create-a-space-with-the-sdk",
- "start-here/host-spaces-on-your-spare-mac": "spaces/guides/host-spaces-on-your-spare-mac",
+ "start-here/host-spaces-on-your-spare-mac": "spaces/guides/add-a-computer#use-a-spare-mac-to-host-spaces",
"start-here/create-a-space-with-the-sdk": "spaces/guides/create-a-space-with-the-sdk",
- "tutorials/your-first-cua-bench-task": "start-here/your-first-cua-bench-task",
+ "tutorials/your-first-cua-bench-task": "cua-bench/quickstart#create-your-own-task",
"use-cua-with": "cua-driver/guides/connect-your-agent",
"use-cua-with/anthropic": "cua-driver/guides/connect-your-agent",
"use-cua-with/antigravity-cli": "cua-driver/guides/connect-your-agent",
@@ -439,9 +443,45 @@
"cua-sdk/reference/spaces/drive-app-core": "cua-sdk/reference/spaces/volume-app-core",
"use-cua-with/iflytek": "cua-driver/guides/connect-your-agent",
"spaces/teams": "spaces/guides/teams",
- "spaces/teams/machines": "spaces/guides/teams/machines",
- "spaces/teams/faq": "spaces/guides/teams/faq",
+ "spaces/teams/machines": "spaces/guides/teams#team-computers",
+ "spaces/teams/faq": "spaces/guides/teams#questions",
"cua-cli/reference/cli/fleet": "cua-sdk/guides/cua-cloud-ended",
- "cua-sdk/guides/cloud": "cua-sdk/guides/cua-cloud-ended"
+ "cua-sdk/guides/cloud": "cua-sdk/guides/cua-cloud-ended",
+ "start-here/drive-your-first-app": "cua-driver/quickstart",
+ "start-here/sandbox-images": "cua-sdk/guides/images#every-published-image",
+ "start-here/run-in-github-actions": "cua-sdk/guides/test-in-ci",
+ "start-here/create-a-local-macos-sandbox": "cua-cli/quickstart#macos-sandbox",
+ "start-here/your-first-cua-bench-task": "cua-bench/quickstart#create-your-own-task",
+ "cua-driver/guides/gemini": "cua-driver/guides/connect-your-agent#gemini",
+ "cua-driver/guides/trajectories": "cua-driver/guides/operate#record-a-trajectory",
+ "cua-driver/guides/test-in-a-sandbox": "cua-driver/guides/vms-and-remote#test-a-driver-build-in-a-sandbox",
+ "cua-driver/guides/cursor-motion": "cua-driver/guides/recipes#design-a-cursor-motion",
+ "cua-driver/concepts/perception-extension": "cua-driver/concepts/how-cua-driver-works#the-optional-perception-extension",
+ "cua-sdk/guides/migrate-from-deprecated-packages": "cua-sdk/guides/cua-cloud-ended#deprecated-packages",
+ "cua-sdk/guides/sidecars": "cua-sdk/guides/services#sidecars",
+ "cua-sdk/guides/your-cloud": "cua-sdk/guides/local-runtimes#your-own-cloud",
+ "cua-sdk/guides/secrets": "cua-sdk/guides/services#secrets",
+ "cua-sdk/guides/coding-agent-options": "cua-sdk/guides/run-a-coding-agent#give-the-agent-mcp-servers",
+ "cua-sdk/guides/browse-the-web": "cua-sdk/guides/desktop#give-an-agent-a-browser",
+ "cua-sdk/guides/thumbnails": "cua-sdk/guides/desktop#thumbnails",
+ "cua-sdk/guides/disk-usage": "cua-sdk/guides/lifecycle#disk-usage-and-cleanup",
+ "cua-sdk/guides/your-cloud-resources": "cua-sdk/guides/local-runtimes#what-cua-creates",
+ "cua-sdk/guides/contrib-providers": "cua-sdk/guides/local-runtimes#other-sandbox-providers",
+ "lume/guides/api-and-mcp": "lume/guides/manage-vms#drive-lume-from-scripts-and-ai-clients",
+ "cua-bench/guides/convert-benchmark-images": "cua-bench/guides/benchmarks#build-a-benchmark-image",
+ "spaces/guides/add-a-machine": "spaces/guides/add-a-computer",
+ "spaces/guides/unattended-access": "spaces/guides/add-a-computer#add-a-computer-from-a-terminal",
+ "spaces/guides/host-spaces-on-your-spare-mac": "spaces/guides/add-a-computer#use-a-spare-mac-to-host-spaces",
+ "spaces/guides/updates": "spaces/guides/install#updates",
+ "spaces/guides/use-from-an-agent": "spaces/guides/connect-your-agent#what-your-agent-can-do",
+ "spaces/guides/agent-keys": "spaces/guides/connect-your-agent#agent-keys",
+ "spaces/guides/plans": "spaces/guides/teams#plans",
+ "spaces/guides/teams/machines": "spaces/guides/teams#team-computers",
+ "spaces/guides/teams/faq": "spaces/guides/teams#questions",
+ "spaces/guides/send-files": "spaces/guides/cua-volume#send-a-file-into-a-space",
+ "spaces/guides/site-login": "spaces/guides/keyvault#let-an-agent-sign-in-to-a-site",
+ "spaces/guides/troubleshoot-create": "spaces/guides/troubleshoot",
+ "spaces/guides/mesh": "spaces/guides/relay-security#end-to-end-encrypted-connections-beta",
+ "spaces/examples/other-languages": "spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages"
}
}
diff --git a/docs/content/docs/spaces/concepts/how-spaces-works.mdx b/docs/content/docs/spaces/concepts/how-spaces-works.mdx
index 88fe50f660..4794479f33 100644
--- a/docs/content/docs/spaces/concepts/how-spaces-works.mdx
+++ b/docs/content/docs/spaces/concepts/how-spaces-works.mdx
@@ -8,7 +8,7 @@ the people and agents who use those Spaces.
## Computers and Spaces
-A **computer** (the app calls it a machine) is a Mac, Windows or Linux computer
+A **computer** is a Mac, Windows or Linux computer
you own or rent. A **Space** is one desktop on a computer, set up for a task. A
Space is a container or a VM, or the computer's own desktop.
@@ -21,8 +21,8 @@ that lets your devices reach your computers.
| Location | What it is |
|---|---|
| This computer | A container or VM on the Mac, Windows or Linux PC you are using. |
-| Another of your machines | A computer you [added](/spaces/guides/add-a-machine) that provides Spaces, such as a spare Mac mini. |
-| Your own cloud | A VM in your own AWS, Google Cloud or Modal account. See [Use your own cloud](/cua-sdk/guides/your-cloud). |
+| Another of your computers | A computer you [added](/spaces/guides/add-a-computer) that provides Spaces, such as a [spare Mac mini](/spaces/guides/add-a-computer#use-a-spare-mac-to-host-spaces). |
+| Your own cloud | A VM in your own AWS, Google Cloud or Modal account. See [Choose where sandboxes run](/cua-sdk/guides/local-runtimes#your-own-cloud). |
Cua Cloud, the hosted option, has ended. See
[Cua Cloud (Fleets) has ended](/cua-sdk/guides/cua-cloud-ended).
@@ -35,11 +35,11 @@ Every Space runs `cua-spacesd`. It streams the screen, takes input through
- **Directly.** On the same network, or over Tailscale, your device connects to
the Space with its address and a token. No account is needed, and the traffic
doesn't use the relay.
-- **Through the relay.** A machine set up with `cua host setup` joins the cua.ai
+- **Through the relay.** A computer set up with `cua host setup` joins the cua.ai
relay with an outbound connection, so you don't open ports. Your enrolled
devices, and people you share a Space with, reach it through the relay. Relay
- use counts toward your [plan's](/spaces/guides/plans) live sessions and relay
- hours.
+ use counts toward your [plan's](/spaces/guides/teams#plans) live sessions and
+ remote hours.
For what the relay can and can't see, see
[What the relay can see](/spaces/guides/relay-security).
@@ -48,18 +48,18 @@ For what the relay can and can't see, see
| Kind | Id | Comes from |
|------|----|------------|
-| Local | `local:<name>` | `spaces.create(options)`: a new Space, on this machine by default |
-| Direct | `direct:<host:port>` | `spaces.add(url, token)`: an existing machine |
-| Relay | `relay:<machine-id>` | Your machines set up with `cua host setup`, listed automatically |
+| Local | `local:<name>` | `spaces.create(options)`: a new Space, on this computer by default |
+| Direct | `direct:<host:port>` | `spaces.add(url, token)`: an existing computer |
+| Relay | `relay:<machine-id>` | Your computers set up with `cua host setup`, listed automatically |
The app, the `cua` CLI, the SDKs and `cua daemon` share one registry
-(`~/.cua/spaces.json`). Relay machines come from your account's directory and
+(`~/.cua/spaces.json`). Relay computers come from your account's directory and
are never written to `spaces.json`.
## Who can do what
You own your computers and the Spaces on them. You can
[share a Space](/spaces/guides/share-a-space) with another account as a viewer or
-an editor, and with [Teams](/spaces/guides/teams) a machine can belong to the
+an editor, and with [Teams](/spaces/guides/teams) a computer can belong to the
team instead of one person. Your agents act through the `cua` MCP server, and you
choose what each one may do. See [Connect your agent](/spaces/guides/connect-your-agent).
diff --git a/docs/content/docs/spaces/examples/cua-bots.mdx b/docs/content/docs/spaces/examples/cua-bots.mdx
index 1fcd235fc1..c0dfb8a892 100644
--- a/docs/content/docs/spaces/examples/cua-bots.mdx
+++ b/docs/content/docs/spaces/examples/cua-bots.mdx
@@ -22,7 +22,7 @@ Cua Bots is an example app for persistent bots. You create a bot, give it a name
## Features
-- Create a bot in three steps: name it, design its face (color, eyes, ears), and choose where its computer runs (this Mac or the cloud) and which agent drives it (Hermes, OpenClaw, Codex or Claude Code). It introduces itself when its computer is up.
+- Create a bot in three steps: name it, design its face (color, eyes, ears), and choose which of your computers it runs on (This Mac or a computer you [added](/spaces/guides/add-a-computer)) and which agent drives it (Hermes, OpenClaw, Codex or Claude Code). It introduces itself when its computer is up.
- Its face changes with what it's doing: thinking, working, waiting for you, done or paused.
- "Ada's computer": the bot's own Space, live beside the chat, framed in its color, with picture in picture. The bot has control until you take over; its face rides next to its pointer.
- Memory in the Cua Volume layout at `agents/<name>/`: it outlives the bot's computer. Finished files land in `outputs/`, files you hand it in `inbox/`.
@@ -59,8 +59,8 @@ These are real runs against a local Space. The bot's agent is the real harness (
| In the app | Cua underneath |
|---|---|
-| A bot's computer | A Space per bot (`bot-<name>`), created with `Spaces.create` (`on: local` or `cloud`, `reuse`) |
-| The bot | A `cua agents` harness run in its Space (`Space.agentStart`), with its Volume home as the working directory |
+| A bot's computer | A Space per bot (`bot-<name>`), created with `Spaces.create` on your own computers (`on: local` for This Mac, `on: host:<computer>` for a computer you added; `reuse`) |
+| The bot | A `cua agents` harness run in its Space (`Space.agentStart`, the same call as [`startThread`](/spaces/guides/connect-your-agent#run-an-agent-inside-a-space)), with its Volume home as the working directory |
| Memory, outputs, inbox | The Cua Volume layout, `agents/<name>/`, kept in a folder on the Mac and copied into the Space before a turn and back after it |
| Watching and taking over | `LiveStreamSession` and `StreamPiPController`; the pointer from `SpacesdClient.cursorPosition()` |
| Routines | The SDK's routine clock, `RoutineStore` |
@@ -83,7 +83,7 @@ swift build && .build/debug/CuaBots
Give the app a model key for the agents you pick (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`). The iPhone app is in `samples/cua-bots-ios`; its README covers the Xcode build and pairing.
-The app registers the Cua Spaces extensions at launch (`cuaSpacesRegister()`), so the runtime it embeds has persistent agents, the Keyvault and teleport. Because it links those Cua Spaces pieces, both samples are source-available under the FSL-1.1-MIT, like Cua Spaces; see [LICENSING.md](https://github.com/trycua/cua/blob/main/LICENSING.md). For examples in TypeScript and Rust (Tauri), see [Examples in other languages](/spaces/examples/other-languages).
+The app registers the Cua Spaces extensions at launch (`cuaSpacesRegister()`), so the runtime it embeds has persistent agents, the Keyvault and teleport. Because it links those Cua Spaces pieces, both samples are source-available under the FSL-1.1-MIT, like Cua Spaces; see [LICENSING.md](https://github.com/trycua/cua/blob/main/LICENSING.md). For examples in TypeScript and Rust (Tauri), see [Use Spaces from code](/spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages).
## Limits
diff --git a/docs/content/docs/spaces/examples/infinite-canvas.mdx b/docs/content/docs/spaces/examples/infinite-canvas.mdx
index d7fb607745..ce9b89bcd4 100644
--- a/docs/content/docs/spaces/examples/infinite-canvas.mdx
+++ b/docs/content/docs/spaces/examples/infinite-canvas.mdx
@@ -72,5 +72,5 @@ swift build -c release --product canvas-bench && .build/release/canvas-bench --t
| Part | Guide |
|------|-------|
| Window streams and presence | [Stream a desktop](/spaces/guides/stream-a-desktop) |
-| Agent threads | [Use from an agent](/spaces/guides/use-from-an-agent#run-an-agent-inside-a-space) |
+| Agent threads | [Run an agent inside a Space](/spaces/guides/connect-your-agent#run-an-agent-inside-a-space) |
| Adding Spaces by address | [Create a Space](/spaces/guides/add-a-space) |
diff --git a/docs/content/docs/spaces/examples/meta.json b/docs/content/docs/spaces/examples/meta.json
index 761e9fb4ce..cf1fc9ef96 100644
--- a/docs/content/docs/spaces/examples/meta.json
+++ b/docs/content/docs/spaces/examples/meta.json
@@ -2,7 +2,6 @@
"title": "Examples",
"pages": [
"cua-bots",
- "infinite-canvas",
- "other-languages"
+ "infinite-canvas"
]
}
diff --git a/docs/content/docs/spaces/examples/other-languages.mdx b/docs/content/docs/spaces/examples/other-languages.mdx
deleted file mode 100644
index 8f05f7fabb..0000000000
--- a/docs/content/docs/spaces/examples/other-languages.mdx
+++ /dev/null
@@ -1,67 +0,0 @@
----
-title: 'Examples in other languages'
-description: 'Agent-app examples on Cua Spaces in TypeScript, Rust (Tauri) and Swift: named bots, each working on a Space you watch live.'
-keywords:
- - Cua Spaces example
- - TypeScript agent app
- - Tauri agent app
----
-
-import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
-
-[Cua Bots](/spaces/examples/cua-bots) is the featured example, in SwiftUI. The OpenKoalaBots samples build a smaller agent app three times, in TypeScript, Rust (Tauri) and Swift, so you can start from the language you ship in. Each one runs named bots as long-lived agent threads on a shared Space, streams the Space's desktop next to the thread, sends files into it and runs routines.
-
-![The Tauri sample: a bot's thread next to the live Space](/img/openkoalabots/openkoalabots-tauri-thread.png)
-
-## Source
-
-| Language | Sample | Built on |
-|---|---|---|
-| TypeScript | [`samples/openkoalabot-example-ts`](https://github.com/trycua/cua/tree/main/samples/openkoalabot-example-ts) | A Node server and web UI on `@trycua/cua` |
-| Rust (Tauri) | [`samples/openkoalabot-example-tauri`](https://github.com/trycua/cua/tree/main/samples/openkoalabot-example-tauri) | A Tauri 2 app on the `cua-spaces` crate |
-| Swift | [`samples/openkoalabot-example-swift`](https://github.com/trycua/cua/tree/main/samples/openkoalabot-example-swift) | A SwiftUI app on `Cua` and `CuaSpaces` |
-
-All three pass one headless test, [`samples/openkoalabot-example-scenario`](https://github.com/trycua/cua/tree/main/samples/openkoalabot-example-scenario).
-
-## Run one
-
-From a clone of [trycua/cua](https://github.com/trycua/cua). The samples build the cua SDK from source, so you need Rust.
-
-<Tabs items={['TypeScript', 'Rust + Tauri', 'Swift']}>
- <Tab value="TypeScript">
- ```bash skip="no-runner"
- (cd libs/cua && cargo build --release -p cua-sdk)
- (cd libs/cua/typescript && npm ci && npm run stage:uniffi && npm run build && npm run build:browser)
- cd samples/openkoalabot-example-ts
- npm ci && npm run build && npm run build:web
- npm run serve # open the URL it prints
- ```
- </Tab>
- <Tab value="Rust + Tauri">
- ```bash skip="no-runner"
- cd samples/openkoalabot-example-tauri
- pnpm install --frozen-lockfile
- pnpm tauri build --debug --no-bundle
- src-tauri/target/debug/openkoalabot-example-tauri
- ```
- </Tab>
- <Tab value="Swift">
- ```bash skip="no-runner"
- (cd libs/cua && cargo build --release -p cua-sdk && node scripts/stage-uniffi-library.mjs --only=swift)
- cd samples/openkoalabot-example-swift
- swift build && .build/debug/OpenKoalaBotExample
- ```
- </Tab>
-</Tabs>
-
-Each app needs a Space: create one with **New Space**, or add one by address.
-
-## Where each part is explained
-
-| Part | Guide |
-|------|-------|
-| Create, add and delete a Space | [Create a Space](/spaces/guides/add-a-space) |
-| Live desktop and presence | [Stream a desktop](/spaces/guides/stream-a-desktop) |
-| File attachments | [Send files](/spaces/guides/send-files) |
-| Session teleport | [Teleport an app](/spaces/guides/teleport-an-app) |
-| Bots as agent threads | [Use from an agent](/spaces/guides/use-from-an-agent#run-an-agent-inside-a-space) |
diff --git a/docs/content/docs/spaces/guides/add-a-computer.mdx b/docs/content/docs/spaces/guides/add-a-computer.mdx
new file mode 100644
index 0000000000..8c87885edf
--- /dev/null
+++ b/docs/content/docs/spaces/guides/add-a-computer.mdx
@@ -0,0 +1,407 @@
+---
+title: Add a computer
+description: 'Connect another Mac, Windows or Linux computer you own to Cua Spaces, so your agents and your other devices can use it. Also how to turn a spare Mac into a place that runs Spaces.'
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+A computer you add runs Spaces for you. Once it is added, it shows up in
+**Computers** on all your devices, your agents can create Spaces on it, and you
+can open its desktop from anywhere, even when nobody is sitting at it. Cua
+doesn't rent computers: add a Mac on your desk, a spare box in the office, or a
+VM in your own cloud account.
+
+{/* VIDEO: Add a second computer to Cua Spaces with a link and open it from your Mac (about 45 seconds) */}
+
+## Add a computer from the app
+
+You need Cua Spaces on the computer you are adding, or its install command.
+
+1. In Cua Spaces, open **Computers** and press **Add a computer**. You can also
+ find it in the Getting Started checklist and the command palette.
+2. If you belong to a team, choose who the computer is for next to **Add it for**:
+ **Just me** or the team. See [Team computers](/spaces/guides/teams#team-computers).
+3. On the other computer, do one of these:
+ - Open the link.
+ - Scan the QR code with its camera.
+ - Run the install command in its terminal. Choose **macOS / Linux** or
+ **Windows (preview)** in the dialog to get the right command.
+4. If Cua Spaces is already on that computer, open **Computers** there, press
+ **Join with a code** and paste the code. The app asks before it joins.
+5. Watch the dialog. It says "Waiting for the computer..." and then "Added", and
+ the computer appears in your list.
+
+The link and code work once and expire after a short time. The dialog shows how
+long is left. Press **Revoke link** to cancel one you no longer need, or **Make
+a new link** if it expired.
+
+<Callout type="warn">
+ Only use a code you made yourself. Joining adds the computer to the account
+ that made the code, and that account can then reach it.
+</Callout>
+
+## Add a computer from a terminal
+
+If you can't use the link, set the computer up yourself:
+
+1. Install Cua Spaces on it. See [Install](/spaces/guides/install).
+2. Sign in with the same account you use here. A computer joins the account it
+ is set up with.
+3. Open **This computer**, choose how to use it, and press **Set up for access**.
+
+Or run this in a terminal on that computer:
+
+```bash test="cli-shape" id="cua-host-setup-add"
+cua host setup # signs in to cua.ai for this command if needed
+```
+
+`cua host setup` installs cua-spacesd as a background service. By default it
+joins the cua.ai relay with an outbound connection, as your account: no port
+forwarding and no token to copy. Your other devices, once
+[enrolled](#reach-it-from-your-other-devices), then see the computer as
+`relay:<machine-id>` in `cua spaces ls` and in the app.
+
+The computer keeps only its own token. If it is not signed in, setup
+signs you in for that one command and stores no session, so a dedicated host
+holds no account credentials. The token lets the computer serve itself and stop
+sharing. It can't list or reach your other computers, change who the computer is
+shared with, or enroll devices. Running `setup` again updates the configuration
+and rotates the token.
+
+| Option | Effect |
+|--------|--------|
+| `--remote` | When sign-in is needed, print a device code to approve in a browser on another computer (for example over SSH). The account session is not saved. Cannot be combined with `--direct`. |
+| `--direct ip:port` | Serve on your LAN (or a forwarded port) with a local env token instead of the relay. No account needed. |
+| `--relay URL` | Use a different relay (`CUA_RELAY_URL`). The default is `https://relay.cua.ai`. |
+| `--name NAME` | Display name (default: host name). |
+| `--allow ACCOUNT` | Also allow this account (id or email). Repeatable. |
+| `--runner KIND` | `auto`, `systemd`, `launchd`, `windows-task` or `process`. |
+| `--profile spare` | A spare computer: do not share its desktop, create Spaces for your devices (`--no-desktop --provide-spaces`). See [Use a spare Mac to host Spaces](#use-a-spare-mac-to-host-spaces). |
+| `--no-desktop` / `--provide-spaces` | Each of the two settings on its own. `cua host config` changes them later. |
+
+## What each system needs
+
+| System | Service setup installs | Before the computer is reachable |
+|---|---|---|
+| macOS | LaunchAgent `com.trycua.spacesd.host` in your GUI session | Grant cua-spacesd **Screen Recording** and **Accessibility** in System Settings, and [Cua Driver](/cua-driver/quickstart) its own permissions. Setup can't do it for you. |
+| Windows | Scheduled task `Cua\SpacesdHost` at logon, in your interactive session | Stay signed in and unlocked. After a restart, sign in once. |
+| Linux | systemd unit `cua-spacesd-host.service` (user unit; system unit as root) | Nothing more. |
+
+On Windows the host runs in your signed-in session, so your devices reach the
+desktop only while it is signed in, unlocked and on screen:
+
+- **After a restart**, sign in once (or turn on automatic sign-in). The host
+ starts at sign-in.
+- **Locked:** Windows doesn't let apps see or use its lock screen. For
+ unattended access, turn off automatic locking in **Settings > Accounts >
+ Sign-in options** and the screen saver's "On resume, display logon screen".
+- **Remote Desktop:** closing a Remote Desktop window leaves the session
+ disconnected, and Windows stops drawing it. To leave a remote PC (a cloud VM)
+ reachable, end Remote Desktop from an administrator prompt with
+ `tscon %sessionname% /dest:console` instead.
+
+A viewer or agent that connects in one of these states sees which one it is.
+
+## Reach it from your other devices
+
+A device reaches your computers through the cua.ai relay only after it is
+enrolled once with a second factor, so a stolen account session alone is not
+enough. A computer that only hosts is never enrolled as a client.
+
+- **Sign in.** Signing in on your own computer enrolls it: run
+ `cua devices enroll` right after `cua auth login`. A device that enrolled
+ before enrolls again on its own when you sign in again.
+- **Approve.** A brand-new device on an account that already has an enrolled
+ device needs approval from one of them (or a sign-in whose token itself
+ proves a second factor with your identity provider). `cua devices enroll`
+ shows a one-time code. Approve it on an enrolled device with
+ `cua devices approve <code>`, or in the app, which asks for Touch ID.
+
+Every enrolled device is notified when a new one joins, in the app's
+notification feed and in `cua devices audit`, so a device you don't recognize
+doesn't slip in unnoticed. Enrollment lasts 30 days. After that, a fresh
+sign-in or one approval re-verifies the device. Until then, unattended agents on
+an enrolled device keep working without prompts.
+
+```bash test="cli-shape" id="cua-devices"
+cua devices enroll
+cua devices approve K7QX-M2RP
+cua devices approve dev_0123456789abcdef01234567
+cua devices ls
+cua devices audit # who opened which machine, from which device, and when
+cua devices revoke dev_0123456789abcdef01234567
+```
+
+In the app, **Settings > Devices** shows this device's enrollment, your devices
+with Rename and Revoke, and Recent Access (which device opened which computer,
+and when). When another device asks to join, the app shows an approval sheet:
+Approve asks for Touch ID or your login password first, and Deny revokes that
+device.
+
+## Share it with other accounts
+
+`--allow` at setup, or later from an enrolled device, shares the computer with
+another account (id or verified email). Sharing asks for confirmation.
+Unsharing cuts that account's open connections.
+
+```bash test="cli-shape" id="cua-host-share"
+cua host share [email protected]
+cua host unshare [email protected]
+```
+
+<Callout type="warn">
+ Everyone on the allowlist gets full control of this desktop. Keep the list
+ short and run `cua host stop` when you do not need it. To let someone only
+ watch, [share a Space as a viewer](/spaces/guides/share-a-space).
+</Callout>
+
+## Check, pause or remove
+
+On the computer, run:
+
+```bash test="cli-shape" id="cua-host-status"
+cua host status # setup, service, who is connected; missing permissions
+cua host stop # disconnect everyone and refuse new connections
+cua host start # share again
+cua host remove # unregister, uninstall the service, delete ~/.cua/host
+```
+
+`cua host stop` turns sharing off locally first, so it holds even when the relay
+is unreachable. In direct mode, `cua host status` prints the URL and the path of
+the env token. Add the computer elsewhere with
+[`spaces.add(url, token)`](/spaces/guides/add-a-space#add-an-existing-computer-by-address).
+
+Uninstalling the app turns sharing off too. On Linux, `sudo apt remove cua-spaces`
+(and `purge`) removes the computer, and the Spaces it provides, from the relay,
+deletes the `cua-spacesd-host.service` user unit and stops the daemon. Your
+Spaces and data under `~/.cua` stay on the computer (the Spaces are turned off).
+
+An owner or admin can remove a team computer at
+[app.cua.ai/machines](https://app.cua.ai/machines). Removing a computer doesn't
+delete anything on it.
+
+## Use a spare Mac to host Spaces
+
+A spare Mac mini in a closet can run Spaces for your laptop and your agents.
+Your laptop, or a coding agent on it, asks for Spaces through the cua.ai relay or
+[directly over Tailscale](#over-tailscale-without-the-relay). The mini runs them
+with its own runtimes, Lume for macOS VMs and Docker for Linux. Its own desktop,
+shell and files stay private. To share a computer's own desktop instead, use the
+steps above.
+
+### Set up the spare Mac
+
+On the spare Mac:
+
+```bash test="cli-shape" id="cua-host-setup-spare"
+cua host setup --profile spare --name "Mac mini (spare)"
+```
+
+`--profile spare` is shorthand for `--no-desktop --provide-spaces`. Setup joins
+the relay the way the steps above do. It signs you in for that one command and
+keeps no account session, only the computer's own token.
+
+The computer has two settings, and each works on its own:
+
+| Setting | What it does | `desktop` profile (default) | `spare` profile |
+|---|---|---|---|
+| Share this desktop | The computer itself is a Space: its screen, input, shell and files. | on | off |
+| Provide Spaces | Your enrolled devices can create, list and delete Spaces on it. | off | on |
+
+With **Share this desktop** off, a relayed caller reaches only the Spaces
+service. Change either setting at any time:
+
+```bash test="cli-shape" id="cua-host-config"
+cua host config # show both settings and the Spaces it runs
+cua host config --desktop on --provide-spaces on # share the desktop too
+cua host config --max-spaces 6 # at most 6 Spaces at once (default 4)
+```
+
+The app's **This computer** page has the same two switches, the Spaces the
+computer provides, and every remote create and delete.
+
+### Over ssh or Tailscale
+
+A spare Mac mini you only reach over ssh (on your [Tailscale](https://tailscale.com)
+or your LAN) works the same way. Tailscale is only the ssh transport here:
+hosting Spaces still goes through the cua.ai relay.
+
+```bash skip="no-runner"
+ssh mini.your-tailnet.ts.net
+
+# on the mini, non-interactively:
+curl -fsSL https://cua.ai/install.sh | sh -s -- -y --select spaces,host --no-onboarding
+```
+
+`-y` accepts the install without the checklist, `--select spaces,host` picks the
+Cua Spaces app and hosting, and `--no-onboarding` skips the automatic
+`cua auth login` (there is no browser to sign in with yet). Then set up the host
+with a device code:
+
+```bash test="cli-shape" id="cua-host-setup-spare-ssh"
+cua host setup --remote --profile spare --name "Mac mini (spare)"
+```
+
+If the mini has no saved account session, this prints a URL and a short code
+that you approve in a browser on another device. The sign-in is held only for
+setup. An existing account session is reused.
+
+<Callout type="warn">
+ The mini needs an active GUI login session. `cua-spacesd` runs as a
+ LaunchAgent in the logged-in session, so it starts only after someone is
+ logged in, not at the login window. For a headless mini, turn on auto-login
+ (System Settings, Users & Groups, Login Options) so it signs in on its own
+ after every reboot or power loss. The first run also needs a one-time grant of
+ **Screen Recording** and **Accessibility** to `cua-spacesd` in System Settings,
+ Privacy & Security. Setup can't grant these for you.
+</Callout>
+
+### Create Spaces on it from your laptop
+
+Your laptop must be [enrolled](#reach-it-from-your-other-devices) for your
+account. Then ask your coding agent, through the cua MCP server:
+
+> spin up 2 macos spaces on my spare mac mini
+
+The agent calls `create_space` with `on="host:spare mac mini"`, `image="macos"`
+and `count=2`. From the CLI:
+
+```bash test="cli-shape" id="cua-spaces-create-host"
+cua spaces create macos:26 --on "spare mac mini" --count 2
+cua spaces create linux --on host:0123abcd4567ef89
+```
+
+The SDK takes the same `on`: `spaces.create(on="host:spare mac mini", image="macos")`.
+
+The computer is matched by its ID, its exact name, or the words of its name, so
+"spare mac mini" finds `Mac mini (spare)` or `office-mac-mini`. When two
+computers fit equally well, the call fails with `ambiguous_host` and lists them
+with their IDs, so the agent can ask you which one you meant.
+
+Each new Space joins the relay as a computer of its own and comes back as
+`relay:<machine>`. Open it, stream it and run commands in it like any other
+Space.
+
+List and delete work as for any Space:
+
+```bash test="cli-shape" id="cua-spaces-host-ls"
+cua spaces ls
+cua spaces delete relay:space-0123456789abcdef
+```
+
+`cua spaces ls` (and the app's sidebar) groups the Spaces a computer provides
+under that computer. In `list_spaces` each one carries `host` (the computer's ID)
+and `host_name`. Deleting asks the computer to delete the VM or container, and
+the Space leaves the relay.
+
+### Limits
+
+| Limit | Default | Why |
+|---|---|---|
+| macOS VMs on one Mac | 2 | Apple's macOS license allows two macOS VMs per Mac, and Apple Virtualization (which Lume runs on) enforces it. |
+| Spaces at once | 4 | Set with `cua host config --max-spaces N` (0: no limit). |
+
+A request past a limit fails with `limit_exceeded` and says which limit and what
+to do. macOS Spaces need a Mac host: a Linux or Windows host refuses them with
+`host_capability_missing`.
+
+macOS Spaces run as Lume VMs. They need an Apple silicon Mac on macOS 13 or later
+with [Lume](/lume) installed, about 50 GB of free disk and 8 GB of free memory
+per macOS Space. The first one downloads the image, so it takes longer than the
+next ones. The host's cua-spacesd starts the cua daemon when a request comes in.
+
+### Who can create Spaces on it
+
+- You, from any device enrolled for your account.
+- Accounts you share the computer with as editors (`cua host share` or
+ `cua spaces share relay:<machine> <who> --role editor`). They see and delete
+ only the Spaces they created. You see and delete all of them.
+- Nobody else. The relay refuses a device that is not enrolled, and the computer
+ refuses an account shared as a viewer.
+
+Every remote create, delete and refusal is a line in the computer's hash-chained
+audit log (`~/.cua/host/spaces-audit.jsonl`). `cua host status` and the app show
+it, and warn when the log does not verify.
+
+Agents follow [per-agent computer access](/spaces/guides/persistent-agents): a
+persistent agent uses a Space on your spare Mac only after you allow it, and a
+grant on the computer does not reach the Spaces it provides.
+
+```bash test="cli-shape" id="cua-agent-allow-host-space"
+cua agent allow-computer ada relay:space-0123456789abcdef
+```
+
+### Over Tailscale without the relay
+
+A spare Mac your laptop reaches by its [Tailscale](https://tailscale.com) (or
+LAN) address can host Spaces without the cua.ai relay: no sign-in on either
+computer and no enrolled devices. Set it up on its Tailscale address:
+
+```bash test="cli-shape" id="cua-host-setup-direct-spare"
+cua host setup --direct 100.101.102.103:3211 --profile spare --name "Mac mini (spare)"
+```
+
+Use the Mac's own address from `tailscale ip -4`. With `--direct 0.0.0.0:3211` it
+listens on every interface, and setup picks its Tailscale address (else its LAN
+address) for the next step. Setup prints the exact command to run on your laptop,
+with the Mac's token:
+
+```bash test="cli-shape" id="cua-spaces-add-direct-host"
+cua spaces add 100.101.102.103:3211 --host --name "Mac mini (spare)" --token <token>
+```
+
+The laptop keeps the token in its Spaces credential store
+(`~/.cua/spaces-credentials.json`, 0600) and lists the Mac in
+`~/.cua/direct-hosts.json`. Then create Spaces on it as on any host:
+
+```bash test="cli-shape" id="cua-spaces-create-direct-host"
+cua spaces create macos:26 --on "spare mac mini" --count 2
+```
+
+`on="host:<name>"` looks at your computers on the relay first, then at the hosts
+you added with `--host`, with the same matching rules. Each new Space runs on the
+Mac with the same limits (four Spaces, two macOS VMs). It is not put on the
+relay: the Mac forwards a port on its own address to the Space's cua-spacesd, and
+your laptop adds it as `direct:100.101.102.103:<port>`. `cua spaces ls` lists it
+under the Mac, `list_spaces` marks it `"via": "direct"`, and `cua spaces delete`,
+`stop` and `start` ask the Mac to do it. When a Space starts again, or the Mac
+restarts, the Mac opens the same port again.
+
+<Callout type="warn">
+ The direct listener is plain HTTP, and the Mac's token is its owner: it creates
+ and deletes Spaces there and reaches the Mac's own shell and files, even with
+ **Share this desktop** off. Treat it like an SSH key and use it only over
+ Tailscale or a LAN you trust. By default the Mac takes host calls, and
+ connections to the Spaces it forwards, only from loopback, Tailscale
+ (`100.64.0.0/10`, `fd7a:115c:a1e0::/48`) and private LAN addresses
+ (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`), and setup
+ refuses a public `--direct` address. `--allow-any-address` turns both off, with
+ a warning. To rotate the token, delete `~/.cua/host/env-token` on the Mac, run
+ the same `cua host setup` again, and add the Mac on your laptop again with the
+ new command.
+</Callout>
+
+### Spare Mac errors
+
+| Error | Meaning | Fix |
+|---|---|---|
+| `ambiguous_host` | Several of your computers fit the name. | Pick one of the listed IDs: `on="host:<id>"`. |
+| `not_found` | No computer fits the name. | Check `cua spaces ls`, or set the computer up with `--provide-spaces`. |
+| `host_capability_missing` | The computer is offline, does not provide Spaces, or cannot run that OS. | Run `cua host config --provide-spaces on` on it, or pick another computer. |
+| `limit_exceeded` | Two macOS VMs already run, or the computer is at its Space limit. | Delete one with `cua spaces delete`, or raise `--max-spaces`. |
+| `permission_denied` | The computer is shared with you to watch only. | Ask its owner to share it as an editor. |
+
+## If it doesn't work
+
+| What you see | What to do |
+|---|---|
+| "That code didn't work" | A code works once and expires. Make a new link in **Add a computer**. |
+| "This device isn't enrolled yet, so it can't make a link." | Enroll this device in **Settings, Devices**, or use `cua host setup` on the other computer. |
+| The computer never appears | On that computer, run `cua host status`. It shows the service state and any missing permission. |
+| The computer shows **Offline** | It is off, asleep or disconnected. Wake it or reconnect it, then run `cua host status` on it. |
+
+## Next
+
+- [Connect your agent](/spaces/guides/connect-your-agent): let an agent use the new computer.
+- [Create a Space](/spaces/guides/add-a-space): run a Space on it.
+- [Plans and Teams](/spaces/guides/teams): share computers with your team.
diff --git a/docs/content/docs/spaces/guides/add-a-machine.mdx b/docs/content/docs/spaces/guides/add-a-machine.mdx
deleted file mode 100644
index 6e272de601..0000000000
--- a/docs/content/docs/spaces/guides/add-a-machine.mdx
+++ /dev/null
@@ -1,106 +0,0 @@
----
-title: Add a machine
-description: 'Connect another Mac, Windows or Linux computer you own to Cua Spaces with a link, a code or one command, so your agents and your other devices can use it.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-A machine is a computer you own that runs Spaces for you. Once it is added, it
-shows up in **Machines** on all your devices, your agents can create Spaces on
-it, and you can open its desktop from anywhere. Cua doesn't rent machines: add a
-Mac on your desk, a spare box in the office, or a VM in your own cloud account.
-
-{/* VIDEO: Add a second computer to Cua Spaces with a link and open it from your Mac (about 45 seconds) */}
-
-## Add a machine from the app
-
-You need Cua Spaces on the computer you are adding, or its install command.
-
-1. In Cua Spaces, open **Machines** and press **Add a machine**. You can also
- find it in the Getting Started checklist and the command palette.
-2. If you belong to a team, choose who the machine is for next to **Add it for**:
- **Just me** or the team. See [Team machines](/spaces/guides/teams/machines).
-3. On the other computer, do one of these:
- - Open the link.
- - Scan the QR code with its camera.
- - Run the install command in its terminal. Choose **macOS / Linux** or
- **Windows (preview)** in the dialog to get the right command.
-4. If Cua Spaces is already on that computer, open **Machines** there, press
- **Join with a code** and paste the code. The app asks before it joins.
-5. Watch the dialog. It says "Waiting for the computer..." and then "Added", and
- the machine appears in your list.
-
-The link and code work once and expire after a short time. The dialog shows how
-long is left. Press **Revoke link** to cancel one you no longer need, or **Make
-a new link** if it expired.
-
-<Callout type="warn">
- Only use a code you made yourself. Joining adds the computer to the account
- that made the code, and that account can then reach it.
-</Callout>
-
-## Add a machine by hand
-
-If you can't use the link, set the computer up yourself:
-
-1. Install Cua Spaces on it. See [Install](/spaces/guides/install).
-2. Sign in with the same account you use here. A machine joins the account it is
- set up with.
-3. Open **This machine**, choose how to use it, and press **Set up for access**.
-
-Or run this in a terminal on that computer:
-
-```bash test="cli-shape" id="cua-host-setup-add"
-cua host setup
-```
-
-It signs you in to cua.ai for that one command if needed, and installs a
-background service that joins the relay. See
-[Set up unattended access](/spaces/guides/unattended-access) for the options. To
-use a spare machine only to run Spaces, see
-[Host Spaces on a spare Mac](/spaces/guides/host-spaces-on-your-spare-mac).
-
-## What each system needs
-
-| System | Before the machine is reachable |
-|---|---|
-| macOS | Grant cua-spacesd **Screen Recording** and **Accessibility** in System Settings. Setup can't do it for you. |
-| Windows | Stay signed in and unlocked. After a restart, sign in once. |
-| Linux | Setup installs the `cua-spacesd-host` systemd service. |
-
-## Reach it from your other devices
-
-A device reaches your machines through the cua.ai relay only after it is enrolled
-once with a second factor, so a stolen account session alone is not enough.
-Signing in on your own computer enrolls it. A brand-new device on an account that
-already has an enrolled device needs an approval from one of them. Open
-**Settings, Devices** to enroll or approve. The full steps are in
-[Set up unattended access](/spaces/guides/unattended-access#reach-it-from-your-devices).
-
-## Stop sharing or remove a machine
-
-On the machine, run:
-
-```bash test="cli-shape" id="cua-host-stop-remove"
-cua host stop # disconnect everyone and refuse new connections
-cua host remove # unregister, uninstall the service, delete ~/.cua/host
-```
-
-An owner or admin can remove a team machine at
-[app.cua.ai/machines](https://app.cua.ai/machines). Removing a machine doesn't
-delete anything on it.
-
-## If it doesn't work
-
-| What you see | What to do |
-|---|---|
-| "That code didn't work" | A code works once and expires. Make a new link in **Add a machine**. |
-| "This device isn't enrolled yet, so it can't make a link." | Enroll this device in **Settings, Devices**, or use `cua host setup` on the other computer. |
-| The machine never appears | On that computer, run `cua host status`. It shows the service state and any missing permission. |
-| The machine shows **Offline** | The computer is off, asleep or disconnected. Wake it or reconnect it, then run `cua host status` on it. |
-
-## Next
-
-- [Connect your agent](/spaces/guides/connect-your-agent): let an agent use the new machine.
-- [Create a Space](/spaces/guides/add-a-space): run a Space on it.
-- [Teams](/spaces/guides/teams): share machines with your team.
diff --git a/docs/content/docs/spaces/guides/add-a-space.mdx b/docs/content/docs/spaces/guides/add-a-space.mdx
index 5f43772801..daf1670861 100644
--- a/docs/content/docs/spaces/guides/add-a-space.mdx
+++ b/docs/content/docs/spaces/guides/add-a-space.mdx
@@ -1,6 +1,6 @@
---
title: Create a Space
-description: 'Create a Space on a computer you own from the app, the CLI or code: any image, progress, cancel, GPUs, adding an existing machine by address, then list, delete or remove it.'
+description: 'Create a Space on a computer you own from the app, the CLI or code: any image, progress, cancel, GPUs, adding an existing computer by address, then list, delete or remove it.'
---
import { Callout } from 'fumadocs-ui/components/callout';
@@ -9,7 +9,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
A Space is one desktop on one of your computers. Ids are the sandbox refs
`cua sb ls` prints (`local:<name>`, `aws:<name>`, `direct:<host:port>`,
`relay:<machine-id>`); a bare name works when it matches one Space. To connect a
-whole computer first, see [Add a machine](/spaces/guides/add-a-machine).
+whole computer first, see [Add a computer](/spaces/guides/add-a-computer).
## Create a Space in the app
@@ -19,11 +19,11 @@ whole computer first, see [Add a machine](/spaces/guides/add-a-machine).
3. Press **Create Space**. The Space appears in your list with a progress bar and
is ready when the bar finishes.
-If the create fails, see [Troubleshoot a failed create](/spaces/guides/troubleshoot-create).
+If the create fails, see [Troubleshoot](/spaces/guides/troubleshoot).
-## Add an existing machine by address
+## Add an existing computer by address
-Choose **Connect by address** in New Space, or register a machine from code.
+Choose **Connect by address** in New Space, or register a computer from code.
This example starts the canonical Linux image with a token:
```bash skip="no-runner"
@@ -123,7 +123,7 @@ result = await space.call_tool("add", '{"a": 2, "b": 3}', "mcp", None)
| Lifecycle, declared services, tunnels, public URLs, `list_tools` / `call_tool` with `service` | `bash`, files, streaming, presence, teleport, agent runs, the `driver` tool registry |
Spacesd features on an image without it fail with `CapabilityMissing`. The
-canonical images and machines set up with `cua host setup` run cua-spacesd.
+canonical images and computers set up with `cua host setup` run cua-spacesd.
<Callout type="info">
In the cloud, `command` and `env` work on container and VM images alike.
@@ -182,7 +182,7 @@ Sandboxes: `await sandboxes.cancel_create(name)` returns what was removed, or
| Removed | Kept |
|---|---|
-| The VM or container and its disks, the cloud claim, the relay machine, the registry entry, the create's journal | Anything that existed before the create |
+| The VM or container and its disks, the cloud claim, the relay computer, the registry entry, the create's journal | Anything that existed before the create |
| Partial downloads | Finished image layers in the engine's cache (Docker's; Lume's when its cache is on), so the next create resumes |
A Lume without `POST /lume/pull/cancel` cannot stop a pull: the create still
@@ -222,7 +222,7 @@ if cua set it. Metal apps in the guest may still need the per-workload shim:
cua spaces ls
```
-Lists registered Spaces and, when you are signed in, your machines on the
+Lists registered Spaces and, when you are signed in, your computers on the
relay (`relay:<machine-id>`, no `add` needed). Register or forget one from a
shell:
@@ -234,15 +234,14 @@ cua spaces rm studio
A [Tailscale](https://tailscale.com) address works here too (its IP or
MagicDNS name as the host:port): `cua spaces add` reaches it like any other
address and the Space registers as `direct:<addr>`. That only attaches one
-already-running Space; hosting Spaces for `on="host:<name>"` still goes
-through the cua.ai relay, set up with
-[`cua host setup`](/spaces/guides/host-spaces-on-your-spare-mac).
+already-running Space. To host Spaces for `on="host:<name>"`, set the computer up
+with [`cua host setup`](/spaces/guides/add-a-computer#use-a-spare-mac-to-host-spaces).
- `spaces.delete(id)` deletes a
-Space's sandbox and forgets it (a Space added by address is only forgotten);
-`spaces.remove(id)` forgets a Space without touching it.
+`spaces.delete(id)` deletes a Space's sandbox and forgets it (a Space added by
+address is only forgotten). `spaces.remove(id)` forgets a Space without touching
+it.
In TypeScript the methods are `create`, `delete_`, `add` and `remove`, with
options from `@trycua/cua/spaces`. Agents use the MCP tools `create_space`,
`delete_space`, `add_space` and `remove_space`
-([Use from an agent](/spaces/guides/use-from-an-agent)).
+([What your agent can do](/spaces/guides/connect-your-agent#what-your-agent-can-do)).
diff --git a/docs/content/docs/spaces/guides/agent-keys.mdx b/docs/content/docs/spaces/guides/agent-keys.mdx
deleted file mode 100644
index 8b60d3e5c0..0000000000
--- a/docs/content/docs/spaces/guides/agent-keys.mdx
+++ /dev/null
@@ -1,78 +0,0 @@
----
-title: Agent keys
-description: 'Give the coding agents in your Spaces a provider key (Anthropic, OpenAI or any other) once, in Cua Spaces → Settings → Agents. The key stays in the Keychain on your Mac and only reaches the agents that use it.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-Claude Code, Codex and the other harnesses need a provider key to run. Add it
-once in **Cua Spaces → Settings → Agents**, and every agent you start in a
-Space gets the key it needs.
-
-- **Anthropic** (`ANTHROPIC_API_KEY`): Claude Code and other agents that use Claude.
-- **OpenAI** (`OPENAI_API_KEY`): Codex and other agents that use OpenAI models.
-- **Another key**: save it under the variable its agent reads, like
- `GEMINI_API_KEY` or `OPENROUTER_API_KEY`.
-
-Each row shows only `•••• ` and the key's last four characters, and when you
-added it. Replace and Remove are on the same row. A key is never shown again
-after you save it.
-
-The same works from the `cua` CLI. The key is read from stdin, so it never
-lands in your shell history:
-
-```bash test="cli-shape" id="agent-keys-cli"
-cua agent keys
-pbpaste | cua agent keys set anthropic
-cua agent keys set other --env GEMINI_API_KEY < gemini.key
-cua agent keys rm OPENAI_API_KEY
-```
-
-## Which agents get a key
-
-When an agent starts (`agent_start`, a persistent agent's turn, a routine),
-the Cua daemon adds the saved keys that agent's harness reads, and no others:
-a Claude Code run gets `ANTHROPIC_API_KEY`, a Codex run gets
-`OPENAI_API_KEY`, and a Gemini CLI run gets neither. A key you pass yourself
-(`env`, or `env_from_host` from the daemon's environment) wins over a saved
-one.
-
-- **Other keys** reach a run only when its harness reads that variable, or
- when the caller names it in `env_from_host`.
-- **A custom endpoint** (`base_url`) gets no saved key unless it is named in
- `env_from_host`, so a key is never sent to a proxy you didn't mean it for.
-- **In the Space** the key is written 0600 into the run's own directory and
- redacted from the run's event log, like any key a run gets.
-
-`agent_capabilities` counts saved keys: a harness whose key is saved reports
-`auth: ok`. A run with no key fails before anything is installed, and the
-error says to add the key in Settings → Agents or to set it for the Cua
-daemon.
-
-## Where the keys are kept
-
-The Cua daemon keeps the keys in one item of your login Keychain (service
-`run.cua.ai`, next to your Cua sign-in). The item trusts the Cua apps of this
-Mac, so the app, the daemon and the `cua` CLI read it without a prompt, and
-agents started at night by a routine still get their key.
-
-The keys are not kept in the [Keyvault](/spaces/guides/keyvault). The Keyvault
-holds app sessions and passwords that you approve one use at a time and can
-lock; a provider key has to reach an agent the moment it starts, unattended,
-with no vault to set up first. The Keychain item is the same store that
-already keeps your Cua session.
-
-<Callout type="info">
- Agents never see this list. `agent_keys.list`, `agent_keys.set` and
- `agent_keys.remove` are methods of the daemon for the Cua app, not MCP
- tools: no agent can read, add or remove a key. Their answers carry only the
- provider, the variable, the last four characters and when the key was
- added. Keys never go to logs or usage data.
-</Callout>
-
-A build of cua that keeps its session in a file (an unsigned development
-build, or Linux today) can't save agent keys: they are never written to a
-plain file. Set the key in the Cua daemon's environment there instead
-(`export ANTHROPIC_API_KEY=…`, then `cua daemon stop` and `cua daemon start`)
-and name it in `env_from_host`. Windows uses the Credential Manager the same
-way as the macOS Keychain.
diff --git a/docs/content/docs/spaces/guides/connect-your-agent.mdx b/docs/content/docs/spaces/guides/connect-your-agent.mdx
index eef94b5cc3..c81448839e 100644
--- a/docs/content/docs/spaces/guides/connect-your-agent.mdx
+++ b/docs/content/docs/spaces/guides/connect-your-agent.mdx
@@ -1,9 +1,10 @@
---
title: Connect your agent
-description: 'Give Claude Code, Codex, Cursor and other AI agents the Cua Spaces tools from the app or the terminal, and check that they work.'
+description: 'Give Claude Code, Codex, Cursor and other AI agents the Cua Spaces tools from the app or the terminal, see what they can do, run agents inside a Space, and give them a provider key.'
---
import { Callout } from 'fumadocs-ui/components/callout';
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
Connecting an agent gives it the `cua` skills and the `cua` MCP server. After
that, it can create Spaces, run commands in them, send files, show you the
@@ -13,9 +14,10 @@ desktop and share a Space whenever you ask.
## Connect from the app
-On first run, the **AI agents** screen lists the supported agents it found on
-this computer. Tick the ones you use and press **Set up**. When it says "Your AI
-agents are set up", press **Continue**.
+On first run, the first screen offers **Connect Claude Code**, then Codex,
+Hermes, OpenClaw and **Other**. Press the one you use. The app adds Cua to that
+agent's settings and checks that the agent can use it. If the agent was already
+open, close it and open it again.
To connect an agent later, or to remove one, open **Settings, AI agents**:
@@ -55,8 +57,13 @@ this computer shares the same Spaces, sandboxes and streams.
3. If your agent asks permission to use a `cua` tool, allow it. Agents ask in
their own window or terminal.
-Then try a real task. These are the prompts the app offers on its last first-run
-screen:
+Then try the request the app offers at the end of its first run. It works
+right away, on this computer:
+
+> List my computers and tell me what's on this Mac
+
+On Windows the request ends "on this PC", and on Linux "on this computer". When
+that works, try a bigger task:
| Ask your agent | What it does |
|---|---|
@@ -64,8 +71,27 @@ screen:
| "Use my Space's browser to finish the checkout test and show me" | Moves your signed-in browser session into the Space, then drives the Space's browser (`teleport_browser_session`). |
| "Share this Space with a teammate as a viewer" | Shares the Space with read-only access (`share_space`). Cua Spaces asks you to confirm first. |
-Open the Space in Cua Spaces to watch it work. For every tool an agent gets, see
-[Use Spaces from an agent](/spaces/guides/use-from-an-agent).
+Open the Space in Cua Spaces to watch it work. [What your agent can do](#what-your-agent-can-do)
+lists the tools it gets.
+
+## What your agent can do
+
+The cua MCP server gives an agent 33 Spaces tools plus sandbox and computer
+tools. For the computer the agent runs on, use [Cua Driver](/cua-driver/quickstart)
+instead. The main ones:
+
+```text output
+list_spaces / create_space {reuse} -> pick, reuse or create a Space
+space_bash {space, command} -> run commands inside it
+send_file {space, path} -> drop a host file into ~/Downloads (sha256-verified)
+stream_endpoint -> a ticketed media URL
+list_tools / call_tool -> cua-driver tools in the Space, or any declared service
+delete_space {space} -> delete it and stop metering
+```
+
+`space` is an id or a name. A tool whose feature the Space lacks returns
+`capability_missing`. For every tool and its parameters, see the
+[Spaces reference](/spaces/reference).
## Limit what an agent can do
@@ -83,6 +109,170 @@ See [permissions](/cua-cli/guides/mcp-server#permissions) for the full list.
anything.
</Callout>
+## Run an agent inside a Space
+
+An agent can also start other agents inside a Space, as long-lived threads.
+
+| Tool | Does |
+|------|------|
+| `agent_capabilities` | Ready harnesses (`claude-code`, `openai-codex`). |
+| `agent_start {space, agent, prompt, show}` | Start a detached run. `show` tails it in a terminal on the Space desktop. |
+| `agent_message {space, run_id, text, force}` | Next turn. Refused mid-turn unless `force`. |
+| `agent_status`, `agent_list`, `agent_stop` | State, output tail, stop. |
+
+Runs live in the guest (`~/.spaces-agents/<run_id>/`) and survive the client
+going away. The daemon copies your agent's credential file (for example
+`~/.claude/.credentials.json`) into the Space at start.
+`CUA_SPACES_AGENT_CREDENTIALS_HOME=none` copies nothing.
+
+In TypeScript a run is a thread:
+
+```ts skip="third-party-cli"
+import { embedded } from "@trycua/cua"
+import { startThread } from "@trycua/cua/spaces"
+
+const bot = await startThread(embedded().spaces(), {
+ agent: "claude-code",
+ prompt: "Open the repo in the Space and run the tests",
+ placement: { type: "dedicated", on: "local", deleteOnClose: true },
+})
+await bot.send("Now fix the failing test")
+console.log(await bot.status())
+await bot.close() // stops the run and deletes the Space
+```
+
+`placement` `shared` (`{ type: "shared", space, acknowledgeNoIsolation: true }`)
+reuses a Space you name. `adoptThread(spaces, spaceId, runId)` reattaches.
+
+The lower-level calls are one run per thread and one message per turn. A message
+sent mid-turn is refused (or queued) unless forced, so show the reason. The
+TypeScript and Rust tabs are from the
+[examples in other languages](/spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages),
+and the Swift tab is from [Cua Bots](/spaces/examples/cua-bots).
+
+<Tabs items={['TypeScript', 'Rust', 'Swift']}>
+ <Tab value="TypeScript">
+ ```ts test="excerpt" id="ts-agent-start" source="samples/openkoalabot-example-ts/src/core/app.ts#ts-agent-start"
+ const report = await space.agentStart(bot.agent, prompt, false, options)
+ const t = new BotThread(bot, report.runId, space)
+ ```
+
+ ```ts test="excerpt" id="ts-agent-message" source="samples/openkoalabot-example-ts/src/core/app.ts#ts-agent-message"
+ const r = await this.space.agentMessage(this.runId, message, false)
+ if (!r.ok) {
+ this.fold.note(this.turns.length, `Refused: ${r.reason}`)
+ return { accepted: false, reason: r.reason }
+ }
+ ```
+ </Tab>
+ <Tab value="Rust">
+ ```rust test="excerpt" id="rs-agent" source="samples/openkoalabot-example-tauri/src-tauri/core/src/thread.rs#rs-agent"
+ let r = self
+ .agents
+ .start(&self.agent, text, self.options.clone())
+ .await
+ .map_err(agents_err)?;
+ ```
+
+ ```rust test="excerpt" id="rs-agent-message" source="samples/openkoalabot-example-tauri/src-tauri/core/src/thread.rs#rs-agent-message"
+ let r = self
+ .agents
+ .send(run, text, vec![])
+ .await
+ .map_err(agents_err)?;
+ if !r.accepts_message {
+ self.system(format!("queued while {}: {}", r.phase, r.reason));
+ }
+ ```
+ </Tab>
+ <Tab value="Swift">
+ ```swift test="excerpt" id="sw-agent-start" source="samples/cua-bots-macos/Sources/CuaBotsCua/CuaEngine.swift#sw-agent-start"
+ let options = SpaceAgentOptions(
+ envFromHost: endpoint?.keyVariables ?? Self.defaultKeyVariables(bot.harness),
+ repo: nil, branch: nil, cwd: home, model: endpoint?.model, baseUrl: endpoint?.baseURL,
+ exitWhenIdle: false)
+ let report = try await space.agentStart(agent: bot.harness.rawValue, prompt: prompt, show: false,
+ options: options)
+ ```
+
+ ```swift test="excerpt" id="sw-agent-message" source="samples/cua-bots-macos/Sources/CuaBotsCua/CuaEngine.swift#sw-agent-message"
+ let report = try await space(bot).agentMessage(runId: run, text: text, force: false)
+ if !report.ok { throw EngineError.refused(report.reason) }
+ ```
+ </Tab>
+</Tabs>
+
+## Agent keys
+
+Claude Code, Codex and the other harnesses need a provider key to run. Add it
+once in **Cua Spaces, Settings, Agents**, and every agent you start in a Space
+gets the key it needs.
+
+- **Anthropic** (`ANTHROPIC_API_KEY`): Claude Code and other agents that use Claude.
+- **OpenAI** (`OPENAI_API_KEY`): Codex and other agents that use OpenAI models.
+- **Another key**: save it under the variable its agent reads, like
+ `GEMINI_API_KEY` or `OPENROUTER_API_KEY`.
+
+Each row shows only `•••• ` and the key's last four characters, and when you
+added it. Replace and Remove are on the same row. A key is never shown again
+after you save it.
+
+The same works from the `cua` CLI. The key is read from stdin, so it never lands
+in your shell history:
+
+```bash test="cli-shape" id="agent-keys-cli"
+cua agent keys
+pbpaste | cua agent keys set anthropic
+cua agent keys set other --env GEMINI_API_KEY < gemini.key
+cua agent keys rm OPENAI_API_KEY
+```
+
+### Which agents get a key
+
+When an agent starts (`agent_start`, a persistent agent's turn, a routine), the
+Cua daemon adds the saved keys that agent's harness reads, and no others: a
+Claude Code run gets `ANTHROPIC_API_KEY`, a Codex run gets `OPENAI_API_KEY`, and
+a Gemini CLI run gets neither. A key you pass yourself (`env`, or `env_from_host`
+from the daemon's environment) wins over a saved one.
+
+- **Other keys** reach a run only when its harness reads that variable, or when
+ the caller names it in `env_from_host`.
+- **A custom endpoint** (`base_url`) gets no saved key unless it is named in
+ `env_from_host`, so a key is never sent to a proxy you didn't mean it for.
+- **In the Space** the key is written 0600 into the run's own directory and
+ redacted from the run's event log, like any key a run gets.
+
+`agent_capabilities` counts saved keys: a harness whose key is saved reports
+`auth: ok`. A run with no key fails before anything is installed, and the error
+says to add the key in Settings, Agents or to set it for the Cua daemon.
+
+### Where the keys are kept
+
+The Cua daemon keeps the keys in one item of your login Keychain (service
+`run.cua.ai`, next to your Cua sign-in). The item trusts the Cua apps of this
+Mac, so the app, the daemon and the `cua` CLI read it without a prompt, and
+agents started at night by a routine still get their key.
+
+The keys are not kept in the [Keyvault](/spaces/guides/keyvault). The Keyvault
+holds app sessions and passwords that you approve one use at a time and can lock.
+A provider key has to reach an agent the moment it starts, unattended, with no
+vault to set up first.
+
+<Callout type="info">
+ Agents never see this list. `agent_keys.list`, `agent_keys.set` and
+ `agent_keys.remove` are methods of the daemon for the Cua app, not MCP tools:
+ no agent can read, add or remove a key. Their answers carry only the provider,
+ the variable, the last four characters and when the key was added. Keys never
+ go to logs or usage data.
+</Callout>
+
+A build of cua that keeps its session in a file (an unsigned development build,
+or Linux today) can't save agent keys: they are never written to a plain file.
+Set the key in the Cua daemon's environment there instead
+(`export ANTHROPIC_API_KEY=...`, then `cua daemon stop` and `cua daemon start`)
+and name it in `env_from_host`. Windows uses the Credential Manager the same way
+as the macOS Keychain.
+
## If it doesn't work
| What you see | What to do |
@@ -90,10 +280,10 @@ See [permissions](/cua-cli/guides/mcp-server#permissions) for the full list.
| The agent has no `cua` tools | Run `cua agents status`. Then start a new session in the agent. In Hermes, run `/reload-mcp`. |
| "The Cua daemon isn't running. Start Cua, or run `cua daemon start`." | Open Cua Spaces, or run `cua daemon start`. |
| Your agent is not in the app's list | Run `cua agents detect` to see every supported agent, or add the server by hand as shown above. |
-| The agent can't reach a Space on another computer | Sign in on this computer, and make sure the device is enrolled. See [Add a machine](/spaces/guides/add-a-machine#reach-it-from-your-other-devices). |
+| The agent can't reach a Space on another computer | Sign in on this computer, and make sure the device is enrolled. See [Add a computer](/spaces/guides/add-a-computer#reach-it-from-your-other-devices). |
## Next
-- [Add a machine](/spaces/guides/add-a-machine): give your agent another computer.
-- [Use Spaces from an agent](/spaces/guides/use-from-an-agent): the tools, and agents that run inside a Space.
-- [Agent keys](/spaces/guides/agent-keys): give the agents that run inside a Space their provider key.
+- [Create a Space](/spaces/guides/add-a-space): run an agent's work in a new desktop.
+- [Add a computer](/spaces/guides/add-a-computer): give your agent another computer.
+- [Persistent agents](/spaces/guides/persistent-agents): agents with a name, a memory and routines.
diff --git a/docs/content/docs/spaces/guides/create-a-space-with-the-sdk.mdx b/docs/content/docs/spaces/guides/create-a-space-with-the-sdk.mdx
index 1a22730514..0f486a21d2 100644
--- a/docs/content/docs/spaces/guides/create-a-space-with-the-sdk.mdx
+++ b/docs/content/docs/spaces/guides/create-a-space-with-the-sdk.mdx
@@ -1,14 +1,18 @@
---
-title: Create a Space with the Cua SDK
-description: Create a Linux Space on your own machine from Python or TypeScript, run a command in it, take a screenshot, ask Cua Driver for its windows, watch it, and delete it.
+title: Use Spaces from code
+description: Create a Linux Space on your own computer from Python or TypeScript, run a command in it, take a screenshot, ask Cua Driver for its windows, watch it, and delete it. Then start from a full agent app in TypeScript, Rust or Swift.
+keywords:
+ - Cua Spaces example
+ - TypeScript agent app
+ - Tauri agent app
---
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
This walkthrough is for developers. A Space is a desktop your agents can use and
-you can watch. You create one on your own machine from code, run a command in it,
+you can watch. You create one on your own computer from code, run a command in it,
take a screenshot, ask Cua Driver which windows it sees, watch the desktop,
-and delete the Space. Nothing leaves your machine.
+and delete the Space. Nothing leaves your computer.
Requirements: Docker (or Podman or Colima) and about 4 GB of free memory.
@@ -38,7 +42,7 @@ npm install @trycua/cua
## 2. Create a Space and use it
-The program passes no location, so the Space runs on this machine: the
+The program passes no location, so the Space runs on this computer: the
canonical Linux desktop (`ghcr.io/trycua/linux:24.04`) in a container.
<Tabs groupId="sdk-lang" persist items={['Python', 'TypeScript']}>
@@ -143,11 +147,70 @@ cua spaces delete local:space-1a2b3c
`cua spaces ls` shows what is left.
+## Examples in other languages
+
+[Cua Bots](/spaces/examples/cua-bots) is the featured example, in SwiftUI. The OpenKoalaBots samples build a smaller agent app three times, in TypeScript, Rust (Tauri) and Swift, so you can start from the language you ship in. Each one runs named bots as long-lived agent threads on a shared Space, streams the Space's desktop next to the thread, sends files into it and runs routines.
+
+![The Tauri sample: a bot's thread next to the live Space](/img/openkoalabots/openkoalabots-tauri-thread.png)
+
+### Source
+
+| Language | Sample | Built on |
+|---|---|---|
+| TypeScript | [`samples/openkoalabot-example-ts`](https://github.com/trycua/cua/tree/main/samples/openkoalabot-example-ts) | A Node server and web UI on `@trycua/cua` |
+| Rust (Tauri) | [`samples/openkoalabot-example-tauri`](https://github.com/trycua/cua/tree/main/samples/openkoalabot-example-tauri) | A Tauri 2 app on the `cua-spaces` crate |
+| Swift | [`samples/openkoalabot-example-swift`](https://github.com/trycua/cua/tree/main/samples/openkoalabot-example-swift) | A SwiftUI app on `Cua` and `CuaSpaces` |
+
+All three pass one headless test, [`samples/openkoalabot-example-scenario`](https://github.com/trycua/cua/tree/main/samples/openkoalabot-example-scenario).
+
+### Run one
+
+From a clone of [trycua/cua](https://github.com/trycua/cua). The samples build the cua SDK from source, so you need Rust.
+
+<Tabs items={['TypeScript', 'Rust + Tauri', 'Swift']}>
+ <Tab value="TypeScript">
+ ```bash skip="no-runner"
+ (cd libs/cua && cargo build --release -p cua-sdk)
+ (cd libs/cua/typescript && npm ci && npm run stage:uniffi && npm run build && npm run build:browser)
+ cd samples/openkoalabot-example-ts
+ npm ci && npm run build && npm run build:web
+ npm run serve # open the URL it prints
+ ```
+ </Tab>
+ <Tab value="Rust + Tauri">
+ ```bash skip="no-runner"
+ cd samples/openkoalabot-example-tauri
+ pnpm install --frozen-lockfile
+ pnpm tauri build --debug --no-bundle
+ src-tauri/target/debug/openkoalabot-example-tauri
+ ```
+ </Tab>
+ <Tab value="Swift">
+ ```bash skip="no-runner"
+ (cd libs/cua && cargo build --release -p cua-sdk && node scripts/stage-uniffi-library.mjs --only=swift)
+ cd samples/openkoalabot-example-swift
+ swift build && .build/debug/OpenKoalaBotExample
+ ```
+ </Tab>
+</Tabs>
+
+Each app needs a Space: create one with **New Space**, or add one by address.
+
+### Where each part is explained
+
+| Part | Guide |
+|------|-------|
+| Create, add and delete a Space | [Create a Space](/spaces/guides/add-a-space) |
+| Live desktop and presence | [Stream a desktop](/spaces/guides/stream-a-desktop) |
+| File attachments | [Send a file into a Space](/spaces/guides/cua-volume#send-a-file-into-a-space) |
+| Session teleport | [Teleport an app](/spaces/guides/teleport-an-app) |
+| Bots as agent threads | [Run an agent inside a Space](/spaces/guides/connect-your-agent#run-an-agent-inside-a-space) |
+
## Next
-- [Reach another machine](/cua-sdk#reach-another-machine): connect the SDK to
- any machine that runs cua-spacesd, by address and token.
-- [Host Spaces on a spare Mac](/spaces/guides/host-spaces-on-your-spare-mac):
- let your laptop create Spaces on another machine, over the relay, ssh or
+- [Reach another computer](/cua-sdk#reach-another-machine): connect the SDK to
+ any computer that runs cua-spacesd, by address and token.
+- [Add a computer](/spaces/guides/add-a-computer#use-a-spare-mac-to-host-spaces):
+ let your laptop create Spaces on another computer, over the relay, ssh or
Tailscale.
- [Create a Space](/spaces/guides/add-a-space): any image, progress, GPUs.
diff --git a/docs/content/docs/spaces/guides/cua-volume.mdx b/docs/content/docs/spaces/guides/cua-volume.mdx
index 97537b5613..922a8a54ac 100644
--- a/docs/content/docs/spaces/guides/cua-volume.mdx
+++ b/docs/content/docs/spaces/guides/cua-volume.mdx
@@ -1,13 +1,15 @@
---
title: Cua Volume
-description: 'One versioned drive per account, shared by every Space and agent: agent memory and outputs that outlive any Space, with default access rules, grants you approve, and an audit log.'
+description: 'One versioned drive per account, shared by every Space and agent: agent memory and outputs that outlive any Space, with default access rules, grants you approve, and an audit log. Also how to send a one-off file into a Space.'
---
import { Callout } from 'fumadocs-ui/components/callout';
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
Cua Volume keeps what outlives a Space: a persistent agent's memory, its
outputs, and files the user shares with every Space. A Space's own disk goes
-away when the Space is deleted; the drive does not.
+away when the Space is deleted; the drive does not. To copy a one-off file into
+one Space instead, see [Send a file into a Space](#send-a-file-into-a-space).
## Layout
@@ -24,7 +26,7 @@ still reach the old content.
| Principal | `public/` | `agents/<self>/` | `agents/<other>/` | `spaces/<this>/` | `spaces/<other>/` |
|-----------|-----------|------------------|-------------------|------------------|-------------------|
-| You (app, CLI, agents on your machine) | rw | rw | rw | rw | rw |
+| You (app, CLI, agents on your computer) | rw | rw | rw | rw | rw |
| Agent A in Space S | r | rw | none | rw | none |
| Space S, no agent | r | none | none | rw | none |
@@ -103,12 +105,6 @@ that it does not verify.
## Show it in Finder
-<Callout type="info">
-Cua Volume is becoming **Cua Volume**. The mounted volume already carries the
-new name; the `cua volume` commands and `drive_*` tools keep their names for
-now.
-</Callout>
-
The drive can appear as a volume named **Cua Volume**, so any app opens its
files in place. It is off until you turn it on in Cua (Settings > Storage)
or from a terminal:
@@ -178,7 +174,7 @@ the full set of numbers, including 1 GB rows and sync latency.
Every Space mounts the same volume, so a program in the guest reads and
writes it like any folder. The guest sees only that Space's view (the
Space's row in the table above, or its agent's), and it never holds keys:
-your machine serves the view over the Space's own connection and applies the
+your computer serves the view over the Space's own connection and applies the
access rules, the audit log and the secret scanner there.
| Guest | How it mounts | Where |
@@ -201,7 +197,7 @@ not need to reconnect the Space:
so no dead mount is left behind.
- When it starts, the daemon unmounts anything a previous daemon left at the
mount path (a crash, a force-quit) before it does anything else.
-- Your machine notices the connection closed, or that the new daemon reports
+- Your computer notices the connection closed, or that the new daemon reports
the volume detached, and mounts the volume again, then restarts the hotspot
if one was on. It retries with a growing wait (2 s, then 4 s, up to a
minute) while the daemon is still coming up, and keeps a persistent agent's
@@ -210,11 +206,65 @@ not need to reconnect the Space:
is `soft`, interruptible and times out in seconds, and the system marks it
dead and unmounts it (`deadtimeout`).
+## Send a file into a Space
+
+To copy a one-off file or folder into one Space, without keeping it on the
+volume, use `send_file`. It puts the file in the Space user's `~/Downloads` (or a
+subfolder). Every file is verified by SHA-256 before it is published, and a
+transfer that does not land is an error.
+
+- For a folder, `.gitignore`, `.ignore` and a root `.dockerignore` are honored
+ (`respect_ignore_files`).
+- Nothing already in the Space is replaced by default. A file of the same name is
+ kept and the new copy lands as `name (1).ext` (`conflict: "rename"`). Pass
+ `conflict: "skip"` to keep only the existing file, or `conflict: "overwrite"`
+ to replace it.
+
+From [the examples in other languages](/spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages):
+
+<Tabs items={['TypeScript', 'Rust', 'Swift']}>
+ <Tab value="TypeScript">
+ ```ts test="excerpt" id="ts-send-file" source="samples/openkoalabot-example-ts/src/core/app.ts#ts-send-file"
+ const report = await this.space.sendFile(localPath, {
+ targetDirectory: subdir,
+ respectIgnoreFiles: true,
+ conflict: "rename",
+ })
+ if (!report.verified) throw new Error(`send_file of ${localPath} was not verified`)
+ ```
+ </Tab>
+ <Tab value="Rust">
+ ```rust test="excerpt" id="rs-send-file" source="samples/openkoalabot-example-tauri/src-tauri/core/src/files.rs#rs-send-file"
+ let report: SendFileReport = space
+ .send_file(
+ path,
+ SendFileOptions {
+ subdir: subdir.to_string(),
+ ..Default::default()
+ },
+ )
+ .await?;
+ ```
+ </Tab>
+ <Tab value="Swift">
+ ```swift test="excerpt" id="sw-send-file" source="samples/openkoalabot-example-swift/Sources/OpenKoalaBotExample/Scenario/ScenarioRunner.swift#sw-send-file"
+ let report = try await handle().sendFile(
+ localPath: file.path,
+ options: SpaceSendFileOptions(targetDirectory: step["subdir"] as? String,
+ respectIgnoreFiles: true, conflict: "overwrite"))
+ ```
+ </Tab>
+</Tabs>
+
+Python: `await space.send_file(path, cua.SpaceSendFileOptions(target_directory="inbox"))`.
+Agents use the MCP tool `send_file` ([what your agent can do](/spaces/guides/connect-your-agent#what-your-agent-can-do)).
+The options are in the [`send_file` reference](/spaces/reference/commands-and-files#send_file).
+
## Sync across devices
-Two machines using the same bucket see each other's changes within
+Two computers using the same bucket see each other's changes within
seconds. Each change is also written to a small change log in the bucket
-itself (`.cua-feed/`), and every machine checks it with a single listing
+itself (`.cua-feed/`), and every computer checks it with a single listing
request, twice a second while things change, backing off to every 5 seconds
when idle. No Cua service is involved; it works with your own S3, R2 or
MinIO bucket.
@@ -226,7 +276,7 @@ at p95 for a 1 KiB file, and shows in the other's mounted volume 2 ms to
0.34 s). While nothing changes, the check backs off, so the first change
after a quiet period can take up to 5 seconds.
-When two machines change the same file, the write that reaches the bucket
+When two computers change the same file, the write that reaches the bucket
last becomes the current version, and the other one is kept next to it as
`name (conflict from <machine> <date>).ext`. Both stay in the file's
history. Nothing is dropped silently.
@@ -237,7 +287,7 @@ cua volume status --json
<Callout type="info">
Keep the change log small with a bucket lifecycle rule that expires
-noncurrent versions under `.cua-feed/` after a day. Each machine already
+noncurrent versions under `.cua-feed/` after a day. Each computer already
deletes feed entries older than a day.
</Callout>
@@ -274,8 +324,8 @@ page. Nothing shows while the files stay on this Mac with no other device.
**Volume page.** Status, not a file browser: Finder is. Open in Finder
shows the volume, mounting it first when it is not mounted. Devices lists every
-machine on the bucket, this one with its pending uploads and last sync.
-Conflicts lists files two machines wrote at once: Open shows the other
+computer on the bucket, this one with its pending uploads and last sync.
+Conflicts lists files two computers wrote at once: Open shows the other
copy in Finder, Resolve clears the entry and keeps both files.
![The Volume page with two devices and a conflict](/img/spaces/spaces-volume-page.png)
@@ -284,7 +334,7 @@ copy in Finder, Resolve clears the entry and keeps both files.
| Backend | Where | Set up |
|---------|-------|--------|
-| `fs` (default) | `~/.cua/volume/data` on this machine | Nothing |
+| `fs` (default) | `~/.cua/volume/data` on this computer | Nothing |
| `s3` | Any S3-compatible bucket with versioning on (AWS S3, R2, MinIO) | `cua volume config set` and `cua volume config set-keys` |
```bash test="cli-shape" id="cua-volume-config"
diff --git a/docs/content/docs/spaces/guides/host-spaces-on-your-spare-mac.mdx b/docs/content/docs/spaces/guides/host-spaces-on-your-spare-mac.mdx
deleted file mode 100644
index 541e86c5b2..0000000000
--- a/docs/content/docs/spaces/guides/host-spaces-on-your-spare-mac.mdx
+++ /dev/null
@@ -1,234 +0,0 @@
----
-title: Host Spaces on a spare Mac
-description: 'Turn a spare Mac mini (or any machine) into a place your laptop and your agents create Spaces on, over the relay, ssh or Tailscale, without sharing its own desktop.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-A spare Mac mini in a closet can run Spaces for your laptop and your agents.
-Your laptop, or a coding agent on it, asks for Spaces through the cua.ai relay or
-[directly over Tailscale](#over-tailscale-without-the-relay). The Mac mini runs
-them with its own runtimes: Lume for macOS VMs and Docker for Linux. Its own
-desktop, shell and files stay private. You can set it up
-[over ssh](#over-ssh-or-tailscale). To share a computer's own desktop instead,
-see [Add a machine](/spaces/guides/add-a-machine).
-
-## Set up the spare Mac
-
-On the spare Mac:
-
-```bash test="cli-shape" id="cua-host-setup-spare"
-cua host setup --profile spare --name "Mac mini (spare)"
-```
-
-`--profile spare` is shorthand for `--no-desktop --provide-spaces`. Setup
-joins the relay the way [unattended access](/spaces/guides/unattended-access)
-does. It signs you in for that one command and keeps no account session, only
-the machine's own token.
-
-The machine has two settings, and each works on its own:
-
-| Setting | What it does | `desktop` profile (default) | `spare` profile |
-|---|---|---|---|
-| Share this desktop | The machine itself is a Space: its screen, input, shell and files. | on | off |
-| Provide Spaces | Your enrolled devices can create, list and delete Spaces on it. | off | on |
-
-With **Share this desktop** off, the host's cua-spacesd runs without its
-desktop services, and a relayed caller reaches only the Spaces service. Change
-either setting at any time:
-
-```bash test="cli-shape" id="cua-host-config"
-cua host config # show both settings and the Spaces it runs
-cua host config --desktop on --provide-spaces on # share the desktop too
-cua host config --max-spaces 6 # at most 6 Spaces at once (default 4)
-```
-
-The app's **This machine** page has the same two switches, the Spaces the
-machine provides, and every remote create and delete.
-
-## Over ssh or Tailscale
-
-A spare Mac mini you only reach over ssh (on your [Tailscale](https://tailscale.com)
-or your LAN) works the same way. Tailscale is only the ssh transport here;
-hosting Spaces still goes through the cua.ai relay, not through Tailscale.
-
-```bash skip="no-runner"
-ssh mini.your-tailnet.ts.net
-
-# on the mini, non-interactively:
-curl -fsSL https://cua.ai/install.sh | sh -s -- -y --select spaces,host --no-onboarding
-```
-
-`-y` accepts the install without the interactive checklist, `--select
-spaces,host` picks the Cua Spaces app and hosting, and `--no-onboarding`
-skips the automatic `cua auth login` (there is no browser or tty to sign in
-with yet). Then set up the host with a device code:
-
-```bash test="cli-shape" id="cua-host-setup-spare-ssh"
-cua host setup --remote --profile spare --name "Mac mini (spare)"
-```
-
-If the mini has no saved account session, this prints a URL and a short code
-that you can approve in a browser on another device. The sign-in is held only
-for setup: the mini keeps its machine token, without saving an account session
-or enrolling it as a controller. An existing account session is reused.
-
-<Callout type="warn">
- The mini needs an active GUI login session: `cua-spacesd` runs as a
- LaunchAgent in the logged-in (Aqua) session, so it starts only after
- someone is logged in, not at the login window. For a headless mini, turn
- on auto-login (System Settings > Users & Groups > Login Options) so it
- signs in on its own after every reboot or power loss. The first run also needs a one-time
- grant of **Screen Recording** and **Accessibility** to `cua-spacesd` in
- System Settings > Privacy & Security; nothing in setup grants these for
- you.
-</Callout>
-
-From your laptop, create Spaces on it the same way as any other host (see
-below): `create_space(on="host:<name>", count=2)`, or
-`cua spaces create macos:26 --on "<name>" --count 2`.
-
-## Create Spaces from your laptop
-
-Your laptop must be [enrolled](/spaces/guides/unattended-access#reach-it-from-your-devices)
-for your account. Then ask your coding agent, through the cua MCP server:
-
-> spin up 2 macos spaces on my spare mac mini
-
-The agent calls `create_space` with `on="host:spare mac mini"`,
-`image="macos"` and `count=2`. From the CLI:
-
-```bash test="cli-shape" id="cua-spaces-create-host"
-cua spaces create macos:26 --on "spare mac mini" --count 2
-cua spaces create linux --on host:0123abcd4567ef89
-```
-
-The SDK takes the same `on`: `spaces.create(on="host:spare mac mini", image="macos")`.
-
-The machine is matched by its ID, its exact name, or the words of its name,
-so "spare mac mini" finds `Mac mini (spare)` or `office-mac-mini`. When two
-machines fit equally well (two Mac minis), the call fails with
-`ambiguous_host` and lists them with their IDs, so the agent can ask you
-which one you meant.
-
-Each new Space joins the relay as a machine of its own and comes back as
-`relay:<machine>`. Open it, stream it and run commands in it like any other
-Space.
-
-## List and delete
-
-```bash test="cli-shape" id="cua-spaces-host-ls"
-cua spaces ls
-cua spaces delete relay:space-0123456789abcdef
-```
-
-`cua spaces ls` (and the app's sidebar) groups the Spaces a machine provides
-under that machine. In `list_spaces` each one carries `host` (the machine ID)
-and `host_name`. Deleting asks the machine to delete the VM or container,
-and the Space leaves the relay.
-
-## Limits
-
-| Limit | Default | Why |
-|---|---|---|
-| macOS VMs on one Mac | 2 | Apple's macOS license allows two macOS VMs per Mac, and Apple Virtualization (which Lume runs on) enforces it. |
-| Spaces at once | 4 | Set with `cua host config --max-spaces N` (0: no limit). |
-
-A request past a limit fails with `limit_exceeded` and says which limit and
-what to do. macOS Spaces need a Mac host: a Linux or Windows host refuses
-them with `host_capability_missing`.
-
-## Who can create Spaces on it
-
-- You, from any device enrolled for your account.
-- Accounts you share the machine with as editors (`cua host share` or
- `cua spaces share relay:<machine> <who> --role editor`). They see and
- delete only the Spaces they created; you see and delete all of them.
-- Nobody else. A device that is not enrolled is refused by the relay, and an
- account shared as a viewer is refused by the machine.
-
-Every remote create, delete and refusal is a line in the machine's
-hash-chained audit log (`~/.cua/host/spaces-audit.jsonl`). `cua host status`
-and the app show it, and warn when the log does not verify.
-
-Agents follow [per-agent computer access](/spaces/guides/persistent-agents):
-a persistent agent uses a Space on your spare Mac only after you allow it, and
-a grant on the machine does not reach the Spaces it provides.
-
-```bash test="cli-shape" id="cua-agent-allow-host-space"
-cua agent allow-computer ada relay:space-0123456789abcdef
-```
-
-## Over Tailscale without the relay
-
-A spare Mac your laptop reaches by its [Tailscale](https://tailscale.com) (or
-LAN) address can host Spaces without the cua.ai relay: no sign-in on either
-machine and no enrolled devices. Set it up on its Tailscale address:
-
-```bash test="cli-shape" id="cua-host-setup-direct-spare"
-cua host setup --direct 100.101.102.103:3211 --profile spare --name "Mac mini (spare)"
-```
-
-Use the Mac's own address from `tailscale ip -4`. With `--direct
-0.0.0.0:3211` it listens on every interface and setup picks its Tailscale
-address (else its LAN address) for the next step. Setup prints the exact
-command to run on your laptop, with the Mac's token:
-
-```bash test="cli-shape" id="cua-spaces-add-direct-host"
-cua spaces add 100.101.102.103:3211 --host --name "Mac mini (spare)" --token <token>
-```
-
-The laptop keeps the token in its Spaces credential store
-(`~/.cua/spaces-credentials.json`, 0600) and lists the Mac in
-`~/.cua/direct-hosts.json`. Then create Spaces on it as on any host:
-
-```bash test="cli-shape" id="cua-spaces-create-direct-host"
-cua spaces create macos:26 --on "spare mac mini" --count 2
-```
-
-`on="host:<name>"` looks at your machines on the relay first, then at the
-hosts you added with `--host`, with the same matching: an ID or exact name
-wins, otherwise the words of the name, and two equally good matches fail with
-`ambiguous_host`.
-
-Each new Space runs on the Mac with the same limits (four Spaces, two macOS
-VMs). It is not put on the relay: the Mac forwards a port on its own address
-to the Space's cua-spacesd, and your laptop adds it as
-`direct:100.101.102.103:<port>` with the Space's own token. `cua spaces ls`
-lists it under the Mac, `list_spaces` marks it `"via": "direct"`, and
-`cua spaces delete`, `stop` and `start` ask the Mac to do it. When a Space
-starts again, or the Mac restarts, the Mac opens the same port again.
-
-<Callout type="warn">
- The direct listener is plain HTTP, and the Mac's token is its owner: it
- creates and deletes Spaces there and reaches the Mac's own shell and files,
- even with **Share this desktop** off. Treat it like an SSH key and use it
- only over Tailscale or a LAN you trust. By default the Mac takes host calls,
- and connections to the Spaces it forwards, only from loopback, Tailscale
- (`100.64.0.0/10`, `fd7a:115c:a1e0::/48`) and private LAN addresses
- (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`), and setup
- refuses a public `--direct` address. `--allow-any-address` turns both off,
- with a warning. To rotate the token, delete `~/.cua/host/env-token` on the
- Mac, run the same `cua host setup` again, and add the Mac on your laptop
- again with the new command.
-</Callout>
-
-## macOS Spaces with Lume
-
-The spare Mac runs macOS Spaces as Lume VMs:
-
-- Apple silicon and macOS 13 or later, with [Lume](/lume) installed.
-- About 50 GB free disk and 8 GB free memory per macOS Space. The first one
- downloads the image, so it takes longer than the next ones.
-- The cua daemon on the spare Mac creates the VMs. The host's cua-spacesd
- starts it when a request comes in, with the `cua` CLI that ran setup.
-
-## Troubleshooting
-
-| Error | Meaning | Fix |
-|---|---|---|
-| `ambiguous_host` | Several of your machines fit the name. | Pick one of the listed IDs: `on="host:<id>"`. |
-| `not_found` | No machine fits the name. | Check `cua spaces ls`, or set the machine up with `--provide-spaces`. |
-| `host_capability_missing` | The machine is offline, does not provide Spaces, or cannot run that OS. | Run `cua host config --provide-spaces on` on it, or pick another machine. |
-| `limit_exceeded` | Two macOS VMs already run, or the machine is at its Space limit. | Delete one with `cua spaces delete`, or raise `--max-spaces`. |
-| `permission_denied` | The machine is shared with you to watch only. | Ask its owner to share it as an editor. |
diff --git a/docs/content/docs/spaces/guides/install.mdx b/docs/content/docs/spaces/guides/install.mdx
index bf931c0582..8bb55bde93 100644
--- a/docs/content/docs/spaces/guides/install.mdx
+++ b/docs/content/docs/spaces/guides/install.mdx
@@ -1,6 +1,6 @@
---
title: Install
-description: 'Install the Cua Spaces app and the cua CLI on macOS, Windows or Linux, and what the first-run screens ask.'
+description: 'Install the Cua Spaces app and the cua CLI on macOS, Windows or Linux, what the first-run screens ask, and how the app keeps itself up to date.'
---
import { Callout } from 'fumadocs-ui/components/callout';
@@ -57,18 +57,17 @@ At a console the installer shows a checklist first. Add `--cli-only`
## First run
-The first time you open the app, it walks you through a few screens. You can
-skip most of them and change every choice later in **Settings**.
+The first time you open the app, it walks you through a short setup. The
+[Quickstart](/spaces/quickstart) shows each step.
-| Screen | What it does |
+| Step | What it does |
|---|---|
-| Welcome | Starts the setup. |
-| Command line | Installs the `cua` command and adds it to your PATH. It shows only when the command is missing or out of date. |
-| Where should Cua Spaces show up? | Chooses how the app appears, for example the notch and menu bar, or the menu bar only. |
-| Sign in | Signs you in to reach your computers from other devices. You can skip it. |
-| AI agents | Gives your coding agents the `cua` skills and MCP server. See [Connect your agent](/spaces/guides/connect-your-agent). |
-| This machine | Chooses between reaching other machines, and setting this one up for [unattended access](/spaces/guides/unattended-access). |
-| You're all set | Offers a first Space and three prompts to try with your agent. |
+| A shared Space for every agent | Connects your agent: Claude Code, Codex, Hermes, OpenClaw or another one. See [Connect your agent](/spaces/guides/connect-your-agent). |
+| Checking your setup | Signs you in to Cua and asks for the two settings your agent needs: to control this computer and to see its screen. Then this computer is your first Space. |
+| Try your first request | A request to copy into your agent. It works right away. |
+| Give your agent its own Space | Optional: a fresh Linux or macOS computer inside this one, away from your files. |
+
+If you stop before every step is done, Home keeps a **Finish setting up** list.
Cua Spaces launches at login by default, so the Spaces this computer provides
and your persistent agents come back after a restart. Turn it off in **Settings,
@@ -79,7 +78,7 @@ General**.
The supported package is the **.deb** on Ubuntu 24.04. It is sandboxed and
installs the confirmation prompt the Keyvault needs. `sudo apt remove cua-spaces`
turns off what the app set up (see
-[Unattended access](/spaces/guides/unattended-access#check-pause-remove)).
+[Check, pause or remove](/spaces/guides/add-a-computer#check-pause-or-remove)).
The **AppImage** is a portable build, not a supported one. It cannot use the
browser sandbox (it starts with `--no-sandbox`), and without the system's
@@ -91,8 +90,52 @@ For Linux Spaces created on this computer, the `cua` CLI uses Docker (gVisor
access to `/dev/kvm` to run same-architecture guests quickly. Run
`cua runtime doctor` to see what this computer has.
+## Updates
+
+Cua Spaces checks for new versions and downloads them in the background on
+macOS, Windows and Linux. The settings are in **Settings, About**, which also
+shows your version.
+
+The app checks when it starts and again every few hours. When a new version is
+ready, **Update ready** appears at the bottom of the sidebar, with **Restart to
+update** and a **What's new** link to the release notes. Nothing restarts until
+you click. If an agent is still working, the app asks first.
+
+In **Settings, About**:
+
+- **Check for and download updates automatically** turns the background checks on
+ or off. With it off, press **Check Now** to check by hand.
+- **Install a downloaded update when Cua Spaces quits** installs a downloaded
+ update when you quit the app. It needs automatic checks.
+- **Last check** says when the app last looked.
+
+On macOS, every update is the same notarized disk image as the download on the
+release page, and the app installs it only when its signature matches the key
+built into the app. Windows and Linux update through their own updater.
+
+### Stable or Beta
+
+**Update to:** picks the channel.
+
+- **Stable**: tested releases.
+- **Beta**: releases and prereleases, with new features sooner and rough edges.
+
+Going back to Stable from a newer beta keeps the version you have until a newer
+stable release is out.
+
+### After an update
+
+The first time the new version opens, it refreshes what Cua installed into your
+AI agents, the way `cua agents update` does: the Cua skill folders and the Cua
+MCP entries in Claude Code, Cursor and the other agents you set up. A skill
+folder you edited is left as you left it. It also restarts the Cua daemon when
+the app started it, so the daemon runs the new version too.
+
+This happens without any window. If something fails, the app shows one notice
+with what to run.
+
## Next
- [Quickstart](/spaces/quickstart): connect an agent and run a first task.
-- [Plans](/spaces/guides/plans): what Free, Pro and Teams include.
-- [Updates](/spaces/guides/updates): how the app keeps itself current.
+- [Plans and Teams](/spaces/guides/teams): what Free, Pro and Teams include.
+- [Troubleshoot](/spaces/guides/troubleshoot): when a Space won't create, update first, then retry.
diff --git a/docs/content/docs/spaces/guides/keyvault.mdx b/docs/content/docs/spaces/guides/keyvault.mdx
index dba9e4d94f..47a286ae0f 100644
--- a/docs/content/docs/spaces/guides/keyvault.mdx
+++ b/docs/content/docs/spaces/guides/keyvault.mdx
@@ -1,6 +1,6 @@
---
title: Keyvault
-description: 'The Cua Keyvault is a password manager for what teleport moves: cookies, localStorage values, passwords and files, grouped by the app they came from. Every item is locked until you allow unattended access. Search, select several, lock, unlock or delete them, approve requests and turn it off from the Keyvault page.'
+description: 'The Cua Keyvault is a password manager for what teleport moves: cookies, localStorage values, passwords and files, grouped by the app they came from. Every item is locked until you allow unattended access. Approve requests, lock or delete items, let an agent sign in to a site with a saved password, and turn it off from the Keyvault page.'
---
import { Callout } from 'fumadocs-ui/components/callout';
@@ -87,23 +87,100 @@ reading the app again, so macOS does not ask for Keychain access.
## Saved passwords
-Import your browser's saved passwords, one item per login:
+Import your browser's saved passwords, one item per login. The daemon asks for
+Touch ID or your login password first:
```bash test="cli-shape" id="kv-import-passwords"
cua keyvault import-passwords --browser chrome
+cua keyvault import-passwords --browser chrome --site github.com # one site only
```
-They stay sealed in the vault and are never delivered to a Space as files.
-An agent uses one only through [site login](/spaces/guides/site-login): you
+They stay sealed in the vault and are never delivered to a Space as files. An
+agent uses one only to [sign in to a site](#let-an-agent-sign-in-to-a-site): you
approve the sign-in, and the Keyvault types it into the page on the saved
-login's own origin. Chrome on macOS and Linux is supported.
+login's own origin. Chrome on macOS and Linux is supported. Windows (DPAPI) is
+not supported yet.
Passwords go into a Space's browser only when you tick **Also send saved
passwords** in the teleport review (it is off unless you do, and never
remembered). Each one is re-encrypted for the browser in the Space with that
browser's own key and written beside the logins it already has, so the browser
must have been opened once there. An agent can never have a password delivered,
-only used through site login.
+only used to sign in.
+
+## Let an agent sign in to a site
+
+Ask an agent "log me into github.com on a new Space" and it can sign in without
+you typing the password and without the agent ever reading it. The agent asks,
+you approve in Cua, and the Keyvault types the login into the page through the
+Space's Cua Driver.
+
+Before you start, [set up the Keyvault](#set-up-and-unlock), import your saved
+passwords as above, and [connect your agent](/spaces/guides/connect-your-agent).
+
+### What happens
+
+1. The agent creates a Space and opens the site's sign-in page in its browser.
+2. It calls `request_site_login` with the Space and the page URL. The Keyvault
+ files a request and the tool answers `pending` with a `request_id`.
+3. Cua shows the request: which agent, which site, which Space. Approving it
+ asks for Touch ID or your login password. One approval covers one sign-in.
+4. The agent calls `request_site_login` again with the `request_id`. The
+ Keyvault checks the page is on the saved login's exact origin, types the
+ username and password with Cua Driver, submits the form and answers `filled`
+ with a masked username (`a***@example.com`).
+
+If you decline, the tool answers with a `login_refused` error and nothing is
+typed. If the page is on another origin (a look-alike domain, a redirect), the
+Keyvault refuses before typing anything.
+
+### The tool
+
+| Argument | Meaning |
+|----------|---------|
+| `space` | The Space to sign in. |
+| `url` | The site's sign-in page (`http` or `https`). |
+| `agent` | The agent asking; shown to you in the approval. |
+| `session`, `target_id`, `tab_id` | The browser tab to sign in, from the agent's own `get_browser_state` on the same Space. Without them the Keyvault opens its own browser in the Space on `url` and returns its tab. |
+| `username` | Which saved account, when the site has several. |
+| `request_id` | From the first call; present on the retry. |
+| `wait_secs` | How long the retry waits for your answer (default 20, at most 120). |
+
+From the SDK the same call is `space.request_site_login(url, options)`
+(`requestSiteLogin` in Swift, TypeScript and Kotlin). See the
+[Keyvault tool reference](/spaces/reference/keyvault) for the full result shape.
+
+Requests also show up in the CLI, for a computer without the app open:
+
+```bash test="cli-shape" id="approve-login"
+cua keyvault requests
+cua keyvault approve 5f2c9a0e
+cua keyvault deny 5f2c9a0e
+```
+
+### What the agent sees
+
+Only what happened: `pending`, `filled` with the site, the origin, a masked
+username and the tab it signed in, or `login_refused`. The password is never in a
+tool result, an error, an event, a log line or the audit log.
+
+<Callout type="warn">
+Once a page is signed in, its session lives in the Space's browser. An agent
+working in that Space can use the session like you could. Delete the Space when
+the work is done.
+</Callout>
+
+### Unattended sign-in and limits
+
+By default every sign-in asks. To let one agent sign in to one site on its own
+(for a routine), turn on **Unattended** for that site's saved password in the
+Keyvault page and add an unattended rule for the agent and the Space. Both steps
+ask for Touch ID, and the rule expires.
+
+- The Keyvault fills a standard form: a password field, the username field
+ before it and a submit button after it. Multi-step sign-ins (username page,
+ then password page) need one `request_site_login` per page.
+- Two-factor prompts are yours to answer: open the Space's viewer and take over.
## What is an item and what stays a file
@@ -140,18 +217,16 @@ dropped: it stays a file or is listed as unavailable.
## Saved sessions (cookies)
The Keyvault holds a browser's cookies one item each, decrypted from Chrome's
-Safe Storage-encrypted store and kept sealed like any other item. Unlike a
-saved password, a delivered session's
-cookies are meant to be used: when an agent's grant or unattended rule
-delivers one into a Space, the Space's own Chrome gets its own freshly
-created (or existing) Safe Storage key, and the cookies are re-encrypted
-under THAT key before they land in its `Cookies` database -- the source
-Mac's key is never copied anywhere. This capture path is reached today by
-the `teleport_app` and `teleport_browser_session` MCP tools (an agent's
-request, with your approval); the plain **Teleport an app** picker still
-moves a session directly, without the Keyvault, and a first-party
-`cua keyvault import-session` command for a human to use directly is tracked
-as follow-up work.
+Safe Storage-encrypted store and kept sealed like any other item. Unlike a saved
+password, a delivered session's cookies are meant to be used. When an agent's
+grant or unattended rule delivers one into a Space, the Space's own Chrome gets
+its own freshly created (or existing) Safe Storage key, and the cookies are
+re-encrypted under that key before they land in its `Cookies` database. The
+source Mac's key is never copied anywhere.
+
+Today an agent reaches this through the `teleport_app` and
+`teleport_browser_session` MCP tools, with your approval. The plain **Teleport an
+app** picker still moves a session directly, without the Keyvault.
## Audit
@@ -204,25 +279,6 @@ cua keyvault lock
Scripts can pass the passphrase on stdin with `--passphrase-stdin`. See the
[`cua keyvault` reference](/cua-cli/reference/cli/keyvault).
-## Development builds
-
-A debug `cua daemon` can trust a development build of the app instead of
-Cua's signature. It never touches the login keychain, so its vault is
-passphrase-only:
-
-```bash skip="no-runner"
-# The app build (and, for the CLI, a debug cua) by cdhash
-export CUA_KEYVAULT_TEST_REQUIREMENT="$(apps/cua-spaces-macos/scripts/dev-keyvault.sh \
- "<path>/Cua Spaces.app" libs/cua/target/debug/cua)"
-cua daemon start --foreground
-```
-
-Launch the app built with a debug `libcua_sdk.dylib` (`CUA_SDK_DYLIB` in
-`apps/cua-spaces-macos/scripts/build-app.sh`) and
-`CUA_KEYVAULT_ALLOW_UNVERIFIED_DAEMON=1`, which lets a debug client talk to
-the unsigned daemon. Set the same variable for a debug `cua keyvault`.
-Release builds ignore both variables.
-
See [Teleport an app](/spaces/guides/teleport-an-app) for what moves, and the
[teleport reference](/spaces/reference/teleport) for the `teleport_app` consent
flow.
diff --git a/docs/content/docs/spaces/guides/mesh.mdx b/docs/content/docs/spaces/guides/mesh.mdx
deleted file mode 100644
index 07d6afbff9..0000000000
--- a/docs/content/docs/spaces/guides/mesh.mdx
+++ /dev/null
@@ -1,103 +0,0 @@
----
-title: End-to-end encrypted connections (beta)
-description: 'An opt-in beta: your devices reach your machines over a WireGuard®-based mesh inside Cua, end to end encrypted, with the relay forwarding only ciphertext.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-<Callout type="info">
- **Beta, off by default.** Nothing changes unless you turn the mesh on with
- `CUA_MESH` (below). It is meant for the Beta channel of the Cua Spaces app
- and will be on by default there in a later beta; stable releases keep the
- relay's HTTPS path.
-</Callout>
-
-With the mesh on, a device that opens a Space on one of your machines
-(`relay:<machine>`) connects to it over a WireGuard®-based mesh that runs
-inside Cua itself, instead of through the relay's HTTPS path. The relay
-coordinates the mesh but never holds a session key: shell, files, input,
-screen and Keyvault deliveries cross it only as ciphertext.
-
-- **End to end.** Each device and machine makes its own key pair on first
- use; the private half never leaves it. Traffic between two of them is
- encrypted with WireGuard between those two keys.
-- **Direct when possible.** Two ends on the same network connect directly.
- Otherwise packets go through the relay, still encrypted between the two
- ends: the relay forwards them without being able to read or change them.
-- **Inside Cua only.** There is no network interface, no VPN profile, no
- system extension and nothing that needs administrator rights. Mesh
- addresses (`fd5c:a000::/32`) exist only inside Cua, so the mesh never
- conflicts with Tailscale or another VPN you already run, and it carries
- Spaces traffic only.
-
-## Turn it on
-
-Both ends opt in: the device you connect from and the machine you host.
-
-| `CUA_MESH` | Behavior |
-|---|---|
-| unset or `off` (default) | The relay's HTTPS path only, as before. |
-| `prefer` | The mesh when both ends and the relay support it; the relay's HTTPS path otherwise, with a log line saying why. |
-| `require` | The mesh or nothing: a relay that could read the session is never used. |
-
-- **On the device:** set `CUA_MESH` where `cua` runs (your shell, or the
- environment of the cua daemon; restart the daemon with `cua daemon stop`
- after changing it).
-- **On a hosted machine:** run `cua host setup` with `CUA_MESH=prefer` set.
- The setting is kept for the host's service until you run setup again
- without it.
-
-`cua spaces ls` lists the same machines either way. With `prefer`, a machine
-or relay that does not speak the mesh yet is used over HTTPS, so mixing
-updated and older machines works.
-
-## Who can connect
-
-The relay applies the rules you already manage:
-
-- A device enrolled for your account reaches the machines your account owns
- and those shared with it, while their sharing is on.
-- The machine sees each device with the same identity as before (account,
- verified email, owner, editor or viewer), and its own host policy still
- decides what that caller may do.
-- Stopping sharing, removing someone from a share list, or revoking a device
- takes it off the mesh within seconds and cuts its open connections. The
- next call says why.
-
-## Your plan allowance
-
-A desktop view, terminal or agent session over the mesh counts toward your
-plan's live sessions, the same as one over the relay's HTTPS path, and one
-machine reached both ways at once counts once. Remote hours count only the
-time a session's traffic goes through the relay: a direct connection uses
-none. `cua usage` and the app's Settings show both.
-
-## When the network changes
-
-Connections belong to the two ends, not to a network path. When a laptop
-moves from Wi-Fi to Ethernet or its public address changes, traffic moves to
-the relay for a moment and back to a direct path as soon as one answers. A
-relay restart does not interrupt direct connections; a connection that was
-going through the relay resumes when the relay is back.
-
-## What still goes through the relay's HTTPS path
-
-- The **browser viewer** and **web or Cloudflare-hosted agents** that cannot
- run Cua: they reach `https://<relay>/m/<machine>/…` as before. See
- [what the relay can see](/spaces/guides/relay-security).
-- Machines and devices without the mesh turned on, or on a version of Cua
- from before it.
-- Relays that do not coordinate a mesh, such as a self-hosted `cua-relay`:
- `prefer` uses their HTTPS path quietly.
-
-## Firewalls
-
-Direct paths use UDP. Each end picks a UDP port on its own; outbound UDP is
-all it needs. On networks that block UDP, the mesh still works through the
-relay, over HTTPS to the same relay address as the rest of Cua.
-
-<Callout type="info">
- WireGuard is a registered trademark of Jason A. Donenfeld. Cua's mesh uses
- the WireGuard protocol through Cloudflare's BSD-licensed boringtun; it is
- not affiliated with or endorsed by the WireGuard project.
-</Callout>
diff --git a/docs/content/docs/spaces/guides/meta.json b/docs/content/docs/spaces/guides/meta.json
index 5ac7cfe989..07a7665f44 100644
--- a/docs/content/docs/spaces/guides/meta.json
+++ b/docs/content/docs/spaces/guides/meta.json
@@ -4,32 +4,22 @@
"---Get started---",
"install",
"connect-your-agent",
- "add-a-machine",
- "---Share, Pro and Teams---",
- "share-a-space",
- "plans",
+ "add-a-space",
+ "add-a-computer",
+ "---Teams and sharing---",
"teams",
- "---Computers---",
- "unattended-access",
- "host-spaces-on-your-spare-mac",
+ "share-a-space",
"---Work in a Space---",
- "add-a-space",
- "create-a-space-with-the-sdk",
"stream-a-desktop",
- "send-files",
"teleport-an-app",
- "site-login",
+ "keyvault",
"cua-volume",
- "---Agents---",
- "use-from-an-agent",
"persistent-agents",
- "agent-keys",
- "keyvault",
+ "create-a-space-with-the-sdk",
"---Keep it working---",
- "updates",
- "troubleshoot-create",
+ "troubleshoot",
+ "uninstall",
"---Advanced---",
- "relay-security",
- "mesh"
+ "relay-security"
]
}
diff --git a/docs/content/docs/spaces/guides/persistent-agents.mdx b/docs/content/docs/spaces/guides/persistent-agents.mdx
index 9ccebd6696..4d3626bde7 100644
--- a/docs/content/docs/spaces/guides/persistent-agents.mdx
+++ b/docs/content/docs/spaces/guides/persistent-agents.mdx
@@ -8,7 +8,7 @@ import { Callout } from 'fumadocs-ui/components/callout';
A persistent agent is a harness with a name, a Space to work in, and a home in
the [Cua Volume](/spaces/guides/cua-volume) at `agents/<name>/`. The harness keeps
its memory in that home, so the agent remembers across runs, across a Space
-being deleted and created again, and across machines.
+being deleted and created again, and across computers.
```bash test="cli-shape" id="persistent-create"
cua agent create ada --harness hermes --in local:dev --env-from-host OPENAI_API_KEY
@@ -72,7 +72,7 @@ cua agent resume ada
| Space | Pause | Resume |
|-------|-------|--------|
| Local | Suspends the Space. | Resumes it. |
-| Your own machine or an added address | Only the agent pauses. | Only the agent resumes. |
+| Your own computer or an added address | Only the agent pauses. | Only the agent resumes. |
## What the agent gets
@@ -85,11 +85,11 @@ over the Space's own connection (no token enters the Space).
| `volume_ls`, `volume_read`, `volume_write` | The drive, as `agent:<name>`: its home, `public/` (read) and its Space's folder. |
| `volume_request_access` | Asks you for more; you approve in the app. |
| `computer_list`, `computer_list_tools`, `computer_call` | Your computers you allowed this agent to use. |
-| `request_site_login` | [Sign in to a site](/spaces/guides/site-login) with a password from your Keyvault, after you approve. The agent never sees it. |
+| `request_site_login` | [Sign in to a site](/spaces/guides/keyvault#let-an-agent-sign-in-to-a-site) with a password from your Keyvault, after you approve. The agent never sees it. |
## Access to your computers
-`cua host setup` makes a machine a Space for your whole account. A persistent
+`cua host setup` makes a computer a Space for your whole account. A persistent
agent reaches it only if you allow that agent by name. Allowing asks for Touch
ID or your passphrase; revoking takes effect on the agent's next call; every
grant, use and refusal is audited.
diff --git a/docs/content/docs/spaces/guides/plans.mdx b/docs/content/docs/spaces/guides/plans.mdx
deleted file mode 100644
index c89d96759b..0000000000
--- a/docs/content/docs/spaces/guides/plans.mdx
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Plans
-description: 'Cua Spaces Free, Pro and Teams: what each includes, how to see your usage, how to upgrade, and what happens at a limit.'
----
-
-Cua Spaces is bring-your-own compute: you connect your own machines, and Cua
-does not rent them out. The plans cover the app, sharing and the hosted relay
-that lets your devices reach your machines. Current prices are on
-[cua.ai/pricing](https://cua.ai/pricing), which is the source of truth.
-
-| Plan | Price | Live sessions | Remote hours |
-| --- | --- | --- | --- |
-| Free | $0 | 2 | 20 a month |
-| Pro | $18 a month or $180 a year, one person | 5 | 200 a month |
-| Teams | $30 per seat a month or $300 per seat a year, 1 to 100 seats | 5 per seat | 200 per seat a month, pooled across the team |
-
-Every plan includes Spaces on every computer you connect, Teleport and sharing a
-Space with named people. Pro adds more live sessions and remote hours. Teams adds
-team-owned machines, roles and device approval. SSO and audit export are not
-included yet.
-
-## What counts toward the limits
-
-**Remote hours** are the time you spend using your computers from somewhere
-else. Using a computer from itself is free.
-
-In detail, a **live session** is one person or agent holding a stream open to a
-machine through the relay, such as a desktop view, a terminal or an agent's
-process stream. Each hour with at least one live session counts as one remote
-hour, per calendar month (UTC).
-
-Spaces you reach directly, for example on your own network, don't use the relay
-and don't count.
-
-## See your usage
-
-Open **Settings** in Cua Spaces. The usage row shows your live sessions and
-remote hours this month, for example 1 of 2 live sessions and 6.5 of 20 remote
-hours, and the plan card shows your plan. To read the same numbers in a
-terminal, run `cua usage`.
-
-When you have used 80% of your remote hours, the app shows a notice with an
-**Upgrade** button. Nothing stops at the limit: your Spaces keep working.
-
-## Upgrade to Pro
-
-1. Press **Upgrade** or **Get Pro** in the app, or open
- [cua.ai/pricing](https://cua.ai/pricing) and choose **Get Pro**.
-2. Sign in or create a Cua account.
-3. Pay with Stripe Checkout.
-
-Pro has no trial, and Free stays available. On a yearly plan, you can cancel
-within 14 days of the first yearly charge for a full refund. Monthly plans have
-no refund for partial months. Change or cancel a plan at any time on the
-[billing page](https://app.cua.ai/billing).
-
-## Start a team
-
-Teams starts at 1 seat, so you can begin with just yourself. Each seat adds to
-one pool the whole team shares: 2 seats give 10 live sessions and 400 remote hours
-a month. To buy Teams, invite people and manage seats, see
-[Teams](/spaces/guides/teams).
-
-## Next
-
-- [Teams](/spaces/guides/teams)
-- [Teams FAQ](/spaces/guides/teams/faq)
-- [Share a Space](/spaces/guides/share-a-space)
diff --git a/docs/content/docs/spaces/guides/relay-security.mdx b/docs/content/docs/spaces/guides/relay-security.mdx
index 4aad3f9cf4..a9540c83f8 100644
--- a/docs/content/docs/spaces/guides/relay-security.mdx
+++ b/docs/content/docs/spaces/guides/relay-security.mdx
@@ -1,6 +1,6 @@
---
title: What the relay can see
-description: 'A plain accounting of what relay.cua.ai can and cannot see, and what we have done and are still doing about it.'
+description: 'A plain accounting of what relay.cua.ai can and cannot see, what we have done and are still doing about it, and the opt-in end-to-end encrypted connections (beta) that keep the relay from reading a session.'
---
import { Callout } from 'fumadocs-ui/components/callout';
@@ -25,22 +25,18 @@ bug in this page: tell us.
(`libs/cua-spacesd/crates/cua-relay/README.md` in the cua repository)
for the exact claims and how they are enforced in code.
- A compromised relay process, relay host, or a memory dump of either, is
- equivalent to a compromised session for every machine currently routed
- through it: it can mint assertions the machines still trust, and read
+ equivalent to a compromised session for every computer currently routed
+ through it: it can mint assertions the computers still trust, and read
whatever crosses it meanwhile.
## The mesh (beta, opt-in)
-With [end-to-end encrypted connections](/spaces/guides/mesh) turned on
-(`CUA_MESH=prefer` or `require` on both the device and the machine), a
-`relay:` Space no longer goes through the HTTPS path below: the device and
-the machine talk WireGuard to each other, directly when they can, and the
-relay forwards only ciphertext it cannot read or change. It still decides
-who may connect, from the same accounts, devices and share lists. The mesh
-is off by default; everything on this page describes the HTTPS path, which
-stays in use for everything else (the browser viewer, web-hosted agents,
-machines and devices without the mesh, and `prefer` when the mesh is not
-available). With `CUA_MESH=require`, a device never falls back to it.
+[End-to-end encrypted connections](#end-to-end-encrypted-connections-beta) are
+off by default. When you turn them on, a `relay:` Space no longer goes through
+the HTTPS path, and the relay forwards only ciphertext it cannot read or change.
+Everything in the next sections describes the HTTPS path, which stays in use for
+everything else: the browser viewer, web-hosted agents, computers and devices
+without the mesh, and `prefer` when the mesh is not available.
## What crosses the relay
@@ -55,7 +51,7 @@ available). With `CUA_MESH=require`, a device never falls back to it.
## Sealed delivery: where it stands
-We seal teleport secrets end to end to the destination machine's own key, so
+We seal teleport secrets end to end to the destination computer's own key, so
the relay forwards only ciphertext for a sealed delivery. The construction:
an ephemeral X25519 key per delivery, HKDF-SHA256, XChaCha20Poly1305, bound
to the Space id, a purpose string and a timestamp, with replay rejection
@@ -71,7 +67,7 @@ every subsequent teleport delivery to it.
the teleport `ImportSession` path (which the Keyvault broker's combined
prompt also uses for cookies and session data) refuses to send over a
`relay:` Space from such an image unless you explicitly acknowledge the
- risk for that one delivery -- republishing the guest image is what makes
+ risk for that one delivery. Republishing the guest image is what makes
the refusal go away, by making the delivery sealed instead. The
**Keyvault site-login password path** (typed directly into a page via
`browser_type`) is **gated the same way, but not yet sealed**: a saved
@@ -89,29 +85,128 @@ path, so there is nothing to seal against.
## Other hardening already shipped
- **Device enrollment with MFA for new devices.** Re-signing in enrolls only
- your own machine (a re-key, or your account's first device). A brand-new
+ your own computer (a re-key, or your account's first device). A brand-new
device on an account that already has an enrolled device needs an approval
from an enrolled device, or a sign-in whose token itself proves a second
- factor -- a verified email alone is not enough.
-- **New machines are flagged.** A machine registered without an enrolled
+ factor. A verified email alone is not enough.
+- **New computers are flagged.** A computer registered without an enrolled
device's signature or MFA is marked unconfirmed until an enrolled device
vouches for it.
-- **A separate origin for machine content.** Machines no longer render as
+- **A separate origin for computer content.** Computers no longer render as
HTML, register a Service Worker, or set cookies on the relay's own
origin outside the one known viewer path; a fully separate registrable
- domain for machine content is designed and partly implemented in code,
+ domain for computer content is designed and partly implemented in code,
pending a DNS/TLS rollout.
- **Bounded relay memory.** A per-machine cap on buffered bytes and streams,
- plus a relay-wide budget with backpressure, so one machine (or one
+ plus a relay-wide budget with backpressure, so one computer (or one
account's worth of them) with slow-reading clients cannot take down every
- other machine's connection.
+ other computer's connection.
- **A tamper-evident, exportable audit log**, hash-chained like the
Keyvault's own, with `GET /v1/audit?format=jsonl` for export to your own
SIEM or backup.
- **The migration grace period (a stolen session alone reaching every
- machine) is off by default**, and time-boxed to an announced rollout
+ computer) is off by default**, and time-boxed to an announced rollout
window when it does run.
+## End-to-end encrypted connections (beta)
+
+<Callout type="info">
+ **Beta, off by default.** Nothing changes unless you turn the mesh on with
+ `CUA_MESH` (below). It is meant for the Beta channel of the Cua Spaces app
+ and will be on by default there in a later beta; stable releases keep the
+ relay's HTTPS path.
+</Callout>
+
+With the mesh on, a device that opens a Space on one of your computers
+(`relay:<machine>`) connects to it over a WireGuard®-based mesh that runs
+inside Cua itself, instead of through the relay's HTTPS path. The relay
+coordinates the mesh but never holds a session key: shell, files, input,
+screen and Keyvault deliveries cross it only as ciphertext.
+
+- **End to end.** Each device and computer makes its own key pair on first
+ use; the private half never leaves it. Traffic between two of them is
+ encrypted with WireGuard between those two keys.
+- **Direct when possible.** Two ends on the same network connect directly.
+ Otherwise packets go through the relay, still encrypted between the two
+ ends: the relay forwards them without being able to read or change them.
+- **Inside Cua only.** There is no network interface, no VPN profile, no
+ system extension and nothing that needs administrator rights. Mesh
+ addresses (`fd5c:a000::/32`) exist only inside Cua, so the mesh never
+ conflicts with Tailscale or another VPN you already run, and it carries
+ Spaces traffic only.
+
+### Turn it on
+
+Both ends opt in: the device you connect from and the computer you host.
+
+| `CUA_MESH` | Behavior |
+|---|---|
+| unset or `off` (default) | The relay's HTTPS path only, as before. |
+| `prefer` | The mesh when both ends and the relay support it; the relay's HTTPS path otherwise, with a log line saying why. |
+| `require` | The mesh or nothing: a relay that could read the session is never used. |
+
+- **On the device:** set `CUA_MESH` where `cua` runs (your shell, or the
+ environment of the cua daemon; restart the daemon with `cua daemon stop`
+ after changing it).
+- **On a hosted computer:** run `cua host setup` with `CUA_MESH=prefer` set.
+ The setting is kept for the host's service until you run setup again
+ without it.
+
+`cua spaces ls` lists the same computers either way. With `prefer`, a computer
+or relay that does not speak the mesh yet is used over HTTPS, so mixing
+updated and older computers works.
+
+### Who can connect
+
+The relay applies the rules you already manage:
+
+- A device enrolled for your account reaches the computers your account owns
+ and those shared with it, while their sharing is on.
+- The computer sees each device with the same identity as before (account,
+ verified email, owner, editor or viewer), and its own host policy still
+ decides what that caller may do.
+- Stopping sharing, removing someone from a share list, or revoking a device
+ takes it off the mesh within seconds and cuts its open connections. The
+ next call says why.
+
+### Your plan allowance
+
+A desktop view, terminal or agent session over the mesh counts toward your
+plan's live sessions, the same as one over the relay's HTTPS path, and one
+computer reached both ways at once counts once. Remote hours count only the
+time a session's traffic goes through the relay: a direct connection uses
+none. `cua usage` and the app's Settings show both.
+
+### When the network changes
+
+Connections belong to the two ends, not to a network path. When a laptop
+moves from Wi-Fi to Ethernet or its public address changes, traffic moves to
+the relay for a moment and back to a direct path as soon as one answers. A
+relay restart does not interrupt direct connections; a connection that was
+going through the relay resumes when the relay is back.
+
+### What still goes through the relay's HTTPS path
+
+- The **browser viewer** and **web or Cloudflare-hosted agents** that cannot
+ run Cua: they reach `https://<relay>/m/<machine>/…` as before. See
+ [what the relay can see](#the-short-version).
+- Computers and devices without the mesh turned on, or on a version of Cua
+ from before it.
+- Relays that do not coordinate a mesh, such as a self-hosted `cua-relay`:
+ `prefer` uses their HTTPS path quietly.
+
+### Firewalls
+
+Direct paths use UDP. Each end picks a UDP port on its own; outbound UDP is
+all it needs. On networks that block UDP, the mesh still works through the
+relay, over HTTPS to the same relay address as the rest of Cua.
+
+<Callout type="info">
+ WireGuard is a registered trademark of Jason A. Donenfeld. Cua's mesh uses
+ the WireGuard protocol through Cloudflare's BSD-licensed boringtun; it is
+ not affiliated with or endorsed by the WireGuard project.
+</Callout>
+
## Reporting a concern
See [`SECURITY.md`](https://github.com/trycua/cua/blob/main/SECURITY.md) for
@@ -120,10 +215,10 @@ harbor for good-faith security research.
## Related
-- [Set up unattended access](/spaces/guides/unattended-access) -- device
- enrollment in full.
-- [Share a Space](/spaces/guides/share-a-space) -- the allowlist and audit
- trail for sharing.
-- [Keyvault](/spaces/guides/keyvault) and [Teleport an
- app](/spaces/guides/teleport-an-app) -- what these deliver and how consent
- works.
+- [Add a computer](/spaces/guides/add-a-computer#reach-it-from-your-other-devices):
+ device enrollment in full.
+- [Share a Space](/spaces/guides/share-a-space): the allowlist and audit trail
+ for sharing.
+- [Keyvault](/spaces/guides/keyvault) and
+ [Teleport an app](/spaces/guides/teleport-an-app): what these deliver and how
+ consent works.
diff --git a/docs/content/docs/spaces/guides/send-files.mdx b/docs/content/docs/spaces/guides/send-files.mdx
deleted file mode 100644
index a7ffcd97a3..0000000000
--- a/docs/content/docs/spaces/guides/send-files.mdx
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Send files
-description: 'Send a host file or folder into a Space: it lands in ~/Downloads, verified by SHA-256.'
----
-
-import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
-
-`send_file` copies a host file or folder into the Space user's `~/Downloads`
-(or a subfolder). Every file is verified by SHA-256 before it is published; a
-transfer that does not land is an error. For a folder, `.gitignore`, `.ignore`
-and a root `.dockerignore` are honored (`respect_ignore_files`). Nothing
-already in the Space is replaced by default: a file of the same name is kept
-and the new copy lands as `name (1).ext` (`conflict: "rename"`). Pass
-`conflict: "skip"` to keep only the existing file, or `conflict: "overwrite"`
-to replace it.
-
-From [the examples in other languages](/spaces/examples/other-languages):
-
-<Tabs items={['TypeScript', 'Rust', 'Swift']}>
- <Tab value="TypeScript">
- ```ts test="excerpt" id="ts-send-file" source="samples/openkoalabot-example-ts/src/core/app.ts#ts-send-file"
- const report = await this.space.sendFile(localPath, {
- targetDirectory: subdir,
- respectIgnoreFiles: true,
- conflict: "rename",
- })
- if (!report.verified) throw new Error(`send_file of ${localPath} was not verified`)
- ```
- </Tab>
- <Tab value="Rust">
- ```rust test="excerpt" id="rs-send-file" source="samples/openkoalabot-example-tauri/src-tauri/core/src/files.rs#rs-send-file"
- let report: SendFileReport = space
- .send_file(
- path,
- SendFileOptions {
- subdir: subdir.to_string(),
- ..Default::default()
- },
- )
- .await?;
- ```
- </Tab>
- <Tab value="Swift">
- ```swift test="excerpt" id="sw-send-file" source="samples/openkoalabot-example-swift/Sources/OpenKoalaBotExample/Scenario/ScenarioRunner.swift#sw-send-file"
- let report = try await handle().sendFile(
- localPath: file.path,
- options: SpaceSendFileOptions(targetDirectory: step["subdir"] as? String,
- respectIgnoreFiles: true, conflict: "overwrite"))
- ```
- </Tab>
-</Tabs>
-
-Python: `await space.send_file(path, cua.SpaceSendFileOptions(target_directory="inbox"))`. Agents use
-the MCP tool `send_file` ([Use from an agent](/spaces/guides/use-from-an-agent));
-options are in the [`send_file` reference](/spaces/reference/commands-and-files#send_file).
diff --git a/docs/content/docs/spaces/guides/share-a-space.mdx b/docs/content/docs/spaces/guides/share-a-space.mdx
index b85867bafc..669f9b5134 100644
--- a/docs/content/docs/spaces/guides/share-a-space.mdx
+++ b/docs/content/docs/spaces/guides/share-a-space.mdx
@@ -14,7 +14,8 @@ address or account ID, and choose **Viewer** or **Editor**. The same list shows
who has access and who is connected. Cua Spaces asks you to confirm with Touch
ID or your login password first.
-To share a whole machine with your team, see [Teams](/spaces/guides/teams).
+You can share with one person at a time, or with a whole team at once. See
+[People and teams](#people-and-teams).
From a terminal:
@@ -26,6 +27,17 @@ cua spaces unshare local:studio [email protected] # at once
cua spaces unshare local:studio --all # nobody; leaves the relay
```
+## People and teams
+
+- **One person.** Type their email or account ID. They can be anyone with a
+ cua.ai account. They do not have to be on your team, or on any team. You
+ choose **Viewer** or **Editor** for each person.
+- **A whole team.** Every member of the team, and their agents, can use the
+ Space, as an editor. Only an owner or admin of a team on the
+ [Teams plan](/spaces/guides/teams) can do this, and only for a Space they
+ own. See
+ [Share a Space with the team](/spaces/guides/teams#share-a-space-with-the-team).
+
## What each role can do
| | Viewer | Editor |
@@ -38,18 +50,25 @@ cua spaces unshare local:studio --all # nobody; leaves t
The Space's own cua-spacesd enforces the role, not the caller. A refused call
fails with `PermissionDenied` (`view-only share: <who> cannot call <method>`).
+A team always gets the Editor role. There is no view-only share for a whole
+team. To let someone only watch, share with them as a person, as a viewer.
+
## How it works
-Sharing uses the relay and allowlist that [unattended access](/spaces/guides/unattended-access)
-uses:
+Sharing uses the same relay and allowlist as an
+[added computer](/spaces/guides/add-a-computer#add-a-computer-from-a-terminal):
- A host (`relay:<id>` from `cua host setup`) is shared directly.
- Any other Space is published on the relay on its first share. The owner's
- account registers a machine for it, and the Space's own driver dials out
+ account registers a computer for it, and the Space's own driver dials out
over WSS, so no inbound port opens.
-- The relay keeps two lists per machine: `allow` (editors) and `viewers`.
-- Invitees need a verified email or account ID and an [enrolled device](/spaces/guides/unattended-access#reach-it-from-your-devices).
+- The relay keeps two lists per computer: `allow` (editors) and `viewers`.
+- Invitees need a verified email or account ID and an [enrolled device](/spaces/guides/add-a-computer#reach-it-from-your-other-devices).
- Removing someone, or changing their role, cuts their open streams at once.
+- A team share works differently. The Space goes on the team's list of
+ computers, and each time someone opens it, the relay checks with the Cua
+ account service that they are still in the team and that their device is
+ approved.
```rust test="excerpt" id="rs-share-space" source="libs/cua/crates/cua-spaces/tests/share_space_e2e.rs#rs-share-space"
let shares = ada
@@ -105,12 +124,13 @@ tools are `relay_register_space` and `relay_unregister_space`.
| Space | Shareable | Why |
|---|---|---|
| Host (`relay:<id>`) | yes | Already on the relay. |
-| Local container or VM | yes, while this machine runs it | Its driver dials the relay. Suspending it disconnects everyone. |
+| Local container or VM | yes, while this computer runs it | Its driver dials the relay. Suspending it disconnects everyone. |
| In your own cloud (AWS, Google Cloud, Modal) | yes | Its driver dials the relay from the cloud. |
| Added by address (`direct:`) | yes, if its driver supports `relay_attach` | Older drivers report `capability_missing`. |
| A Space shared with you | no | Only the owner can share (`permission_denied`). |
-- The relay shares with accounts, not teams: share with each member.
+- You can share with a person or with a whole team. A team always gets the
+ Editor role.
- Presence cursors travel on the relay stream, not QUIC datagrams, so remote
cursors update a little less often than on your own network.
- A Space that is released (for example a paused persistent agent in your
diff --git a/docs/content/docs/spaces/guides/site-login.mdx b/docs/content/docs/spaces/guides/site-login.mdx
deleted file mode 100644
index 55e079865c..0000000000
--- a/docs/content/docs/spaces/guides/site-login.mdx
+++ /dev/null
@@ -1,102 +0,0 @@
----
-title: Log in to a site
-description: 'Let an agent sign in to a website in a Space with a password you saved in the Cua Keyvault. You approve each sign-in; the agent never sees the password.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-Ask an agent "log me into github.com on a new Space" and it can sign in
-without you typing the password and without the agent ever reading it. The
-password stays in the [Keyvault](/spaces/guides/keyvault): the agent asks,
-you approve in Cua, and the Keyvault types the login into the page through
-the Space's Cua Driver.
-
-## Before you start
-
-1. Set up the Keyvault (**Keyvault** in the Cua sidebar, or
- `cua keyvault init`).
-2. Import your saved passwords from Chrome. The daemon asks for Touch ID or
- your login password, and the passwords are stored sealed, one item per
- site:
-
- ```bash test="cli-shape" id="import-passwords"
- cua keyvault import-passwords --browser chrome
- cua keyvault import-passwords --browser chrome --site github.com
- ```
-
-3. Give your agent the Cua tools: `cua agents` installs them into Claude
- Code, Codex, Hermes and OpenClaw.
-
-## What happens
-
-1. The agent creates a Space and opens the site's sign-in page in its
- browser.
-2. It calls `request_site_login` with the Space and the page URL. The
- Keyvault files a request and the tool answers `pending` with a
- `request_id`.
-3. Cua shows the request: which agent, which site, which Space. Approving it
- asks for Touch ID or your login password. One approval covers one
- sign-in.
-4. The agent calls `request_site_login` again with the `request_id`. The
- Keyvault checks the page is on the saved login's exact origin, types the
- username and password with Cua Driver, submits the form and answers
- `filled` with a masked username (`a***@example.com`).
-
-If you decline, the tool answers with a `login_refused` error and nothing is
-typed. If the page is on another origin (a look-alike domain, a redirect),
-the Keyvault refuses before typing anything.
-
-## The tool
-
-| Argument | Meaning |
-|----------|---------|
-| `space` | The Space to sign in. |
-| `url` | The site's sign-in page (`http` or `https`). |
-| `agent` | The agent asking; shown to you in the approval. |
-| `session`, `target_id`, `tab_id` | The browser tab to sign in, from the agent's own `get_browser_state` on the same Space. Without them the Keyvault opens its own browser in the Space on `url` and returns its tab. |
-| `username` | Which saved account, when the site has several. |
-| `request_id` | From the first call; present on the retry. |
-| `wait_secs` | How long the retry waits for your answer (default 20, at most 120). |
-
-From the SDK the same call is `space.request_site_login(url, options)`
-(`requestSiteLogin` in Swift, TypeScript and Kotlin). See the
-[Keyvault tool reference](/spaces/reference/keyvault) for the full result shape.
-
-## Approve from a terminal
-
-Requests also show up in the CLI, for a machine without the app open:
-
-```bash test="cli-shape" id="approve-login"
-cua keyvault requests
-cua keyvault approve 5f2c9a0e
-cua keyvault deny 5f2c9a0e
-```
-
-## What the agent sees
-
-Only what happened: `pending`, `filled` with the site, the origin, a masked
-username and the tab it signed in, or `login_refused`. The password is never
-in a tool result, an error, an event, a log line or the audit log.
-
-<Callout type="warn">
-Once a page is signed in, its session lives in the Space's browser. An agent
-working in that Space can use the session like you could. Delete the Space
-when the work is done.
-</Callout>
-
-## Unattended sign-in
-
-By default every sign-in asks. To let one agent sign in to one site on its
-own (for a routine), turn on **Unattended** for that site's saved password in
-the Keyvault page and add an unattended rule for the agent and the Space.
-Both steps ask for Touch ID, and the rule expires.
-
-## Limits
-
-- Saved passwords import from Chrome on macOS and Linux. Windows (DPAPI) is
- not supported yet.
-- The Keyvault fills a standard form: a password field, the username field
- before it and a submit button after it. Multi-step sign-ins (username page,
- then password page) need one `request_site_login` per page.
-- Two-factor prompts are yours to answer: open the Space's viewer and take
- over.
diff --git a/docs/content/docs/spaces/guides/stream-a-desktop.mdx b/docs/content/docs/spaces/guides/stream-a-desktop.mdx
index 3e25004841..0171816952 100644
--- a/docs/content/docs/spaces/guides/stream-a-desktop.mdx
+++ b/docs/content/docs/spaces/guides/stream-a-desktop.mdx
@@ -32,7 +32,7 @@ RCDP messages and framing) is open source, so any client can attach to a
ticket.
The same calls in TypeScript, Rust and Swift, from
-[the examples in other languages](/spaces/examples/other-languages). The first frame is a keyframe.
+[the examples in other languages](/spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages). The first frame is a keyframe.
<Tabs items={['TypeScript', 'Rust', 'Swift']}>
<Tab value="TypeScript">
diff --git a/docs/content/docs/spaces/guides/teams.mdx b/docs/content/docs/spaces/guides/teams.mdx
new file mode 100644
index 0000000000..8e637e64e4
--- /dev/null
+++ b/docs/content/docs/spaces/guides/teams.mdx
@@ -0,0 +1,260 @@
+---
+title: Plans and Teams
+description: 'Cua Spaces Free, Pro and Teams: what each plan includes and how to see your usage. How to buy Teams, invite people, pair team computers, approve devices and manage seats.'
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Cua Spaces is bring-your-own compute: you connect your own computers, and Cua
+does not rent them out. The plans cover the app, sharing and the hosted relay
+that lets your devices reach your computers. Current prices are on
+[cua.ai/pricing](https://cua.ai/pricing), which is the source of truth.
+
+## Plans
+
+| Plan | Price | Live sessions | Remote hours |
+| --- | --- | --- | --- |
+| Free | $0 | 2 | 20 a month |
+| Pro | $18 a month or $180 a year, one person | 5 | 200 a month |
+| Teams | $30 per seat a month or $300 per seat a year, 1 to 100 seats | 5 per seat | 200 per seat a month, pooled across the team |
+
+Every plan includes Spaces on every computer you connect, Teleport and sharing a
+Space with named people. Pro adds more live sessions and remote hours. Teams
+adds team-owned computers, roles and device approval. SSO and audit export are
+not included yet.
+
+## What counts toward the limits
+
+**Remote hours** are the time you spend using your computers from somewhere
+else. Using a computer from itself is free.
+
+A **live session** is one person or agent holding a stream open to a computer
+through the relay, such as a desktop view, a terminal or an agent's process
+stream. Each hour with at least one live session counts as one remote hour, per
+calendar month (UTC).
+
+Spaces you reach directly, for example on your own network, don't use the relay
+and don't count.
+
+## See your usage
+
+Open **Settings** in Cua Spaces. The usage row shows your live sessions and
+remote hours this month, for example 1 of 2 live sessions and 6.5 of 20 remote
+hours, and the plan card shows your plan. To read the same numbers in a
+terminal, run `cua usage`.
+
+When you have used 80% of your remote hours, the app shows a notice with an
+**Upgrade** button. Nothing stops at the limit: your Spaces keep working.
+
+## Upgrade to Pro
+
+1. Press **Upgrade** or **Get Pro** in the app, or open
+ [cua.ai/pricing](https://cua.ai/pricing) and choose **Get Pro**.
+2. Sign in or create a Cua account.
+3. Pay with Stripe Checkout.
+
+Pro has no trial, and Free stays available. Change or cancel a plan at any time
+on the [billing page](https://app.cua.ai/billing). See [Cancel](#cancel) for
+refunds.
+
+## Buy Teams
+
+Teams turns the computers your team already has into shared desktops for people
+and their agents. Computers belong to the team instead of one person's account,
+an owner and admins decide who can do what, and a new device must be approved
+before it can reach a team computer.
+
+{/* VIDEO: Create a team, invite a teammate and share a machine with them (about 60 seconds) */}
+
+Teams starts at 1 seat, so you can begin with just yourself and add seats as
+people join. Two seats give 10 live sessions and 400 remote hours a month for the
+whole team.
+
+1. Open [app.cua.ai/buy/teams](https://app.cua.ai/buy/teams) and sign in or
+ create a Cua account.
+2. Name your team and choose the number of seats and monthly or yearly billing.
+3. Pay with Stripe Checkout. Teams is for business use: Stripe asks for your
+ company name and address, and you can add your company's VAT or GST ID.
+
+There is no trial. The person who buys is the team's owner.
+
+## Create your team and invite people
+
+Naming the team in checkout creates it, and you join it as its **owner**. After
+payment the Team page at [app.cua.ai/team](https://app.cua.ai/team) shows
+"Invite your team".
+
+Teams are invitation only. Enter an email address and choose a role. The person
+gets an email, signs in with that address and joins. Invitees do not pay and do
+not see checkout.
+
+- Members plus pending invitations cannot exceed the seats you pay for, and you
+ take one seat yourself. On a 1-seat team, the Team page shows **Add seats**
+ before your first invite. It opens Stripe, where you raise the quantity (see
+ [Seats and billing](#seats-and-billing)).
+- Until the first payment completes, a new team can invite up to 5 people.
+- Revoke a pending invitation from the same page.
+
+Cua Spaces shows your teams in **Settings, Teams**: each team with its members,
+their roles and pending invitations marked "(Invited)". Press **Manage team** to
+invite people and change roles in the account app, or **Billing and plans** to
+change seats and billing.
+
+## Roles
+
+A team has one owner, and any number of admins and members.
+
+| | Owner | Admin | Member |
+|---|---|---|---|
+| Open team computers (from an approved device) | yes | yes | yes |
+| Request approval for a new device | not needed | yes | yes |
+| Leave the team | no | yes | yes |
+| Invite people | yes | yes | no |
+| Remove members | yes, admins too | members only | no |
+| Add and remove team computers | yes | yes | no |
+| Approve or deny devices | yes | yes | no |
+| Make a member an admin, or an admin a member | yes | no | no |
+| Cancel the subscription, delete the team | yes | no | no |
+
+The owner's role cannot change and the owner cannot leave: to close a team,
+cancel the subscription first, then delete the team. The owner's own devices need
+no approval. Admins cannot remove other admins or the owner.
+
+Owners and admins remove a member in the Members list on the Team page. Removal
+takes effect at once, and the person's device approvals for the team are deleted.
+A member leaves with **Leave team** on the same page.
+
+## Team computers
+
+A **team computer** belongs to the team. Every member, and their agents, sees it
+in the Cua Spaces app and can open it, from a device an admin has approved. A
+**personal computer** stays on your own account, as described in
+[Add a computer](/spaces/guides/add-a-computer), and only you and the accounts
+you [share it with](/spaces/guides/share-a-space) can reach it.
+
+| | Personal computer | Team computer |
+|---|---|---|
+| Belongs to | One account | The team |
+| Who sees it | You, and accounts you share it with | Every member |
+| Who can open it | You, and people you share it with | Every member, as an editor, from an approved device |
+| Who adds or removes it | You | Owners and admins |
+
+Team members have full use of a team computer: there are no view-only team
+members. To let someone only watch, share a Space with them as a viewer instead.
+
+### Pair a computer to the team
+
+Pairing needs Cua Spaces 0.8.0 or later. An owner or admin does this.
+
+1. In the Cua Spaces app, open **Computers**, press **Add a computer** and choose
+ your team next to **Add it for**. The app shows a link, a QR code and a
+ one-time pairing code that looks like `K7QM-4XPB-2RHD`. For the personal
+ version of these steps, see [Add a computer](/spaces/guides/add-a-computer).
+2. On the computer you are adding, open the link, or run the install command the
+ app shows. With the `cua` CLI installed, the code alone is enough:
+
+```bash test="cli-shape" id="cua-host-setup-pair-team"
+cua host setup --pair K7QM-4XPB-2RHD
+```
+
+If the computer already has the Cua Spaces app, you don't need the command.
+Opening the link in a browser offers to open the app, and the app shows **Join
+with a code** with the code filled in. You can also open **Computers** in the app,
+choose **Join with a code**, and paste the code or the link. The app asks before
+it joins.
+
+The computer joins the team that made the code, with no sign-in on that computer.
+A code works once and expires after 30 minutes. Revoke an unused one from the
+same dialog.
+
+The computer then appears under **Computers** at
+[app.cua.ai/machines](https://app.cua.ai/machines), where an owner or admin can
+remove it from the team. Removing a computer does not delete anything on it.
+
+Mac, Windows and Linux computers can all be team computers, and all join with
+`cua host setup`. See [Install](/spaces/guides/install) to get the `cua` CLI.
+Members open team computers from the Cua Spaces app (macOS 26 or later) or the
+Windows and Linux apps on the [download page](https://cua.ai/download).
+
+### Approve a device
+
+A member's device can open team computers only once an owner or admin approves
+it.
+
+1. The member signs in on a new device and asks for approval.
+2. The request shows under **Device approvals** at
+ [app.cua.ai/machines](https://app.cua.ai/machines) while it waits. The member
+ sees that it is waiting for an admin.
+3. An owner or admin chooses **Approve** or **Deny**. A denied device cannot open
+ team computers.
+
+Members see their own devices. Owners and admins see everyone's. Removing a
+member deletes their approvals.
+
+### Who can open a team computer
+
+A person can open a team computer when all of these hold. The relay checks them
+with the Cua account service and caches the answer for up to a minute.
+
+- They are a member of the team. Their role is read from the team itself, so a
+ removed member loses access at once.
+- The computer is on the team's list.
+- Their device is approved (the owner's devices always are).
+
+### Share a Space with the team
+
+To make a Space you already have a team computer, share it with the team. Every
+member of the team, and their agents, then sees it and can open it as an editor
+(full control), from a device an admin has approved.
+
+- **In the app:** press **Share** on the Space. If you own or manage a team on
+ the Teams plan, the Share window shows a **Share with** button for each of
+ your teams.
+- **In a terminal:** run `cua spaces share <space> team:<team id>`, or
+ `cua team add-machine <team> <space>`. `cua team ls` shows the team ID.
+- Only an owner or admin of the team can do this, and only for a Space they
+ own. A team can hold as many shared computers as its seats allow.
+- A team always gets the Editor role. There is no view-only share for a whole
+ team. To let someone only watch, share with them as a person, as a viewer.
+- To stop, remove the team in the Share window, or run
+ `cua spaces unshare <space> team:<team id>`.
+
+You can also share a Space with one person who is not on your team. See
+[Share a Space](/spaces/guides/share-a-space).
+
+## Seats and billing
+
+Seats, the monthly or yearly period, the card and invoices are managed in the
+Stripe billing portal: [app.cua.ai/billing](https://app.cua.ai/billing), then
+**Manage billing**. Only the owner buys and changes the plan.
+
+- **Add seats:** you pay a prorated amount for the rest of the current period,
+ added to your next invoice. The maximum is 100 seats.
+- **Remove seats:** you get a prorated credit on future invoices. Credits are not
+ refunded in cash. You cannot go below 1 seat.
+- **Switch between monthly and yearly:** in the same portal. Stripe prorates the
+ change.
+
+See the [Plan Terms](https://cua.ai/spaces-terms) for the details.
+
+## Cancel
+
+Cancel Pro or Teams in the billing portal at any time. The plan stays active
+until the end of the period you paid for, then you move to Free (a team moves to
+Free as a whole). Your Spaces and everything in them stay on your computers.
+
+Monthly plans have no refund for partial months. On a yearly plan, cancelling
+within 14 days of the first yearly charge refunds it in full, and after that
+there is no refund for the unused part of the year. The
+[Plan Terms](https://cua.ai/spaces-terms) have the full text.
+
+## Questions
+
+### Is SSO included?
+
+Not yet. SSO and audit export are coming next, with no dates yet. They are not
+included in Teams today.
+
+### Who do I contact?
+
diff --git a/docs/content/docs/spaces/guides/teams/faq.mdx b/docs/content/docs/spaces/guides/teams/faq.mdx
deleted file mode 100644
index 583c995be3..0000000000
--- a/docs/content/docs/spaces/guides/teams/faq.mdx
+++ /dev/null
@@ -1,58 +0,0 @@
----
-title: Teams FAQ
-description: 'Answers about Cua Teams: SSO and audit export, data and bring-your-own compute, billing, refunds and support.'
----
-
-## Is SSO included?
-
-Not yet. SSO and audit export are coming next, with no dates yet. They are not
-included in Teams today.
-
-## Does Cua host or rent the machines?
-
-No. Spaces run on computers you own or rent yourself: your Mac, other machines
-you connect, or VMs in your own cloud account. Your cloud provider bills you for
-those VMs. Cua provides the app, the sharing and the relay that lets your
-devices reach your machines.
-
-## Can a Mac be a team machine?
-
-Yes. Macs, Linux and Windows machines can all be team machines, so you can share
-your own Mac with your team. See [team machines](/spaces/guides/teams/machines).
-
-## What happens to our data if we cancel?
-
-Your Spaces and everything in them stay on your machines. The team moves to Free
-at the end of the period you paid for.
-
-## Is there a trial?
-
-No. Free stays available, and you can [buy Teams](/spaces/guides/teams#buy-teams) when
-you are ready.
-
-## What is the refund policy?
-
-Monthly plans have no refund for partial months. On a yearly plan, cancel within
-14 days of the first yearly charge for a full refund; after that there is no
-refund for the unused part of the year. The
-[Plan Terms](https://cua.ai/spaces-terms) have the full text.
-
-## How are seat changes charged?
-
-Stripe prorates them. Added seats are charged pro rata for the rest of the
-period on your next invoice. Removed seats earn a prorated credit on future
-invoices, not a cash refund. The minimum is 1 seat, the maximum 100.
-
-## What if we use more than the pool?
-
-Nothing is cut off. The Cua Spaces app shows a notice with an Upgrade button.
-See [Teams](/spaces/guides/teams) for what a live session and a remote hour are.
-
-## Which Spaces count against the pool?
-
-Only those that use the relay. Spaces on your own network or reached directly do not go through the relay and
-do not count.
-
-## Who do I contact?
-
diff --git a/docs/content/docs/spaces/guides/teams/index.mdx b/docs/content/docs/spaces/guides/teams/index.mdx
deleted file mode 100644
index 9d2151bc3c..0000000000
--- a/docs/content/docs/spaces/guides/teams/index.mdx
+++ /dev/null
@@ -1,122 +0,0 @@
----
-title: Teams
-description: 'Cua Teams: machines that belong to the team, roles, device approval and a shared relay allowance. Buy it, create a team, invite people, manage seats and cancel.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-Teams turns the computers your team already has into shared desktops for
-people and their agents. With Teams, machines belong to the team instead of one
-person's account, an owner and admins decide who can do what, and a new device
-must be approved before it can reach a team machine. You bring the computers;
-Cua does not rent them ([FAQ](/spaces/guides/teams/faq)).
-
-| | |
-|---|---|
-| Price | $30 per seat a month, or $300 per seat a year (two months free) |
-| Seats | 1 to 100 |
-| Includes | Everything in Pro, plus team machines, roles and device approval |
-| Usage | Each seat adds 5 live sessions and 200 remote hours a month to one pool the whole team shares |
-
-You can start with 1 seat, just you, and add seats as people join. Two seats
-give 10 live sessions and 400 remote hours a month for the team.
-
-**Remote hours** are the time your team spends using its computers from
-somewhere else; using a computer from itself is free. A **live session** is one
-person or agent holding a stream open to a machine through the relay, such as a
-desktop view, a terminal or an agent's process stream. Each hour with at least
-one live session counts as one remote hour, per calendar month (UTC). Spaces on your own network or reached directly do not go
-through the relay and do not count. If the team goes over, nothing is cut off:
-the Cua Spaces app shows a notice with an Upgrade button.
-
-Prices and usage are on [cua.ai/pricing](https://cua.ai/pricing).
-
-{/* VIDEO: Create a team, invite a teammate and share a machine with them (about 60 seconds) */}
-
-## Buy Teams
-
-1. Open [app.cua.ai/buy/teams](https://app.cua.ai/buy/teams) and sign in or
- create a Cua account.
-2. Name your team and choose the number of seats and monthly or yearly billing.
-3. Pay with Stripe Checkout. Teams is for business use: Stripe asks for your
- company name and address, and you can add your company's VAT or GST ID.
-
-There is no trial. The person who buys is the team's owner.
-
-## Create your team and invite people
-
-Naming the team in checkout creates it, and you join it as its **owner**. After
-payment the Team page at [app.cua.ai/team](https://app.cua.ai/team) shows
-"Invite your team".
-
-Teams are invitation only. Enter an email address and choose a role. The person
-gets an email, signs in with that address and joins. Invitees do not pay and do
-not see checkout.
-
-- Members plus pending invitations cannot exceed the seats you pay for, and
- you take one seat yourself. On a 1-seat team, the Team page shows **Add
- seats** before your first invite; it opens Stripe, where you raise the
- quantity (see [Seats and billing](#seats-and-billing)).
-- Until the first payment completes, a new team can invite up to 5 people.
-- Revoke a pending invitation from the same page.
-
-## Teams in the app
-
-Cua Spaces shows your teams in **Settings, Teams**: each team with its members,
-their roles and pending invitations marked "(Invited)". The app only shows teams.
-Press **Manage team** to invite people and change roles in the account app, or
-**Billing and plans** to change seats and billing.
-
-## Roles
-
-A team has one owner, and any number of admins and members.
-
-| | Owner | Admin | Member |
-|---|---|---|---|
-| Open team machines (from an approved device) | yes | yes | yes |
-| Request approval for a new device | not needed | yes | yes |
-| Leave the team | no | yes | yes |
-| Invite people | yes | yes | no |
-| Remove members | yes, admins too | members only | no |
-| Add and remove team machines | yes | yes | no |
-| Approve or deny devices | yes | yes | no |
-| Make a member an admin, or an admin a member | yes | no | no |
-| Cancel the subscription, delete the team | yes | no | no |
-
-The owner's role cannot change and the owner cannot leave: to close a team,
-cancel the subscription first, then delete the team. The owner's own devices
-need no approval. Admins cannot remove other admins or the owner.
-
-## Remove a member or leave
-
-Owners and admins remove a member in the Members list on the Team page.
-Removal takes effect at once, and the person's device approvals for the team are
-deleted. A member leaves with **Leave team** on the same page.
-
-## Seats and billing
-
-Seats, the monthly or yearly period, the card and invoices are managed in the
-Stripe billing portal: [app.cua.ai/billing](https://app.cua.ai/billing), then
-**Manage billing**. Only the owner buys and changes the plan.
-
-- **Add seats:** you pay a prorated amount for the rest of the current period,
- added to your next invoice.
-- **Remove seats:** you get a prorated credit on future invoices. Credits are
- not refunded in cash. You cannot go below 1 seat.
-- **Switch between monthly and yearly:** in the same portal. Stripe prorates the
- change.
-
-See the [Plan Terms](https://cua.ai/spaces-terms) for the details.
-
-## Cancel
-
-Cancel in the billing portal at any time. The plan stays active until the end of
-the period you paid for, then the team moves to Free. Monthly plans have no
-refund for partial months. On a yearly plan, cancelling within 14 days of the
-first yearly charge refunds it in full. Your Spaces and everything in them stay
-on your machines.
-
-<Callout type="info">
- Next: [pair machines to the team and approve devices](/spaces/guides/teams/machines),
- or read the [Teams FAQ](/spaces/guides/teams/faq).
-</Callout>
diff --git a/docs/content/docs/spaces/guides/teams/machines.mdx b/docs/content/docs/spaces/guides/teams/machines.mdx
deleted file mode 100644
index 2955324089..0000000000
--- a/docs/content/docs/spaces/guides/teams/machines.mdx
+++ /dev/null
@@ -1,94 +0,0 @@
----
-title: Team machines
-description: 'Pair a machine to your team, approve devices, and decide who can open what: team machines versus your own machines, on Mac, Windows and Linux.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-A **team machine** belongs to the team. Every member, and their agents, sees it
-in the Cua Spaces app and can open it, from a device an admin has approved. A
-**personal machine** stays on your own account, as in
-[unattended access](/spaces/guides/unattended-access), and only you and the
-accounts you [share it with](/spaces/guides/share-a-space) can reach it.
-
-| | Personal machine | Team machine |
-|---|---|---|
-| Belongs to | One account | The team |
-| Who sees it | You, and accounts you share it with | Every member |
-| Who can open it | You, and people you share it with | Every member, as an editor, from an approved device |
-| Who adds or removes it | You | Owners and admins |
-
-Team members have full use of a team machine: there are no view-only team
-members. To let someone only watch, share a Space with them as a viewer instead.
-
-## Pair a machine to the team
-
-Pairing needs Cua Spaces 0.8.0 or later. An owner or admin does this.
-
-1. In the Cua Spaces app, open **Machines**, press **Add a machine** and choose
- your team next to **Add it for**. The app shows a link, a QR code and a
- one-time pairing code that looks like `K7QM-4XPB-2RHD`. For the personal
- version of these steps, see [Add a machine](/spaces/guides/add-a-machine).
-2. On the computer you are adding, open the link, or run the install command the
- app shows. With the `cua` CLI installed, the code alone is enough:
-
-```bash test="cli-shape" id="cua-host-setup-pair-team"
-cua host setup --pair K7QM-4XPB-2RHD
-```
-
-If the computer already has the Cua Spaces app, you don't need the command.
-Opening the link in a browser offers to open the app, and the app shows **Join
-with a code** with the code filled in. You can also open **Machines** in the
-app, choose **Join with a code**, and paste the code or the link. The app asks
-before it joins.
-
-The machine joins the team that made the code, with no sign-in on that
-computer. A code works once and expires after 30 minutes. Revoke an unused one
-from the same dialog.
-
-The machine then appears under **Machines** at
-[app.cua.ai/machines](https://app.cua.ai/machines), where an owner or admin can
-remove it from the team. Removing a machine does not delete anything on it.
-
-## Mac, Windows and Linux
-
-| | Open team machines | Be a team machine |
-|---|---|---|
-| Mac | Cua Spaces app (macOS 26 or later) | Yes |
-| Windows | Windows and Linux apps: see the [download page](https://cua.ai/download) | Yes |
-| Linux | Windows and Linux apps: see the [download page](https://cua.ai/download) | Yes |
-
-Mac, Windows and Linux machines all join with `cua host setup`, as in
-[unattended access](/spaces/guides/unattended-access). See
-[Install](/spaces/guides/install) to get the `cua` CLI.
-
-## Device approval
-
-With Teams, a member's device can open team machines only once an owner or admin
-approves it.
-
-1. The member signs in on a new device and asks for approval.
-2. The request shows under **Device approvals** at
- [app.cua.ai/machines](https://app.cua.ai/machines) while it waits. The member
- sees that it is waiting for an admin.
-3. An owner or admin chooses **Approve** or **Deny**. A denied device cannot
- open team machines.
-
-Members see their own devices; owners and admins see everyone's. The owner's own
-devices need no approval. Removing a member deletes their approvals.
-
-## Who can open a team machine
-
-A person can open a team machine when all of these hold. The relay checks them
-with the Cua account service, and caches the answer for up to a minute.
-
-- They are a member of the team (their role is read from the team itself, so a
- removed member loses access at once).
-- The machine is on the team's list.
-- Their device is approved (the owner's devices always are).
-
-## Share a Space with the team
-
-To make an existing Space a team machine, share it with the team. Every member
-then sees it and opens it as an editor from an approved device. Macs, Linux and
-Windows machines can all be team machines.
diff --git a/docs/content/docs/spaces/guides/teams/meta.json b/docs/content/docs/spaces/guides/teams/meta.json
deleted file mode 100644
index c0dd7957a2..0000000000
--- a/docs/content/docs/spaces/guides/teams/meta.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
- "title": "Teams",
- "pages": [
- "index",
- "machines",
- "faq"
- ]
-}
diff --git a/docs/content/docs/spaces/guides/teleport-an-app.mdx b/docs/content/docs/spaces/guides/teleport-an-app.mdx
index e8ef994e8d..9ee14d2b93 100644
--- a/docs/content/docs/spaces/guides/teleport-an-app.mdx
+++ b/docs/content/docs/spaces/guides/teleport-an-app.mdx
@@ -1,12 +1,12 @@
---
title: Teleport an app
-description: 'Bring an app from this machine into a Space: install it there, open your files in it, or move its signed-in state, with a consent screen for everything that leaves.'
+description: 'Bring an app from this computer into a Space: install it there, open your files in it, or move its signed-in state, with a consent screen for everything that leaves.'
---
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-**Teleport an app** lists every app installed on this machine and says what
+**Teleport an app** lists every app installed on this computer and says what
teleport can do with each one in a Space:
| Level | What happens in the Space | Moves |
@@ -33,9 +33,9 @@ the entry's `sensitive_groups` and `TeleportPlanOptions.sensitive_groups`.
Chrome (and Chromium) encrypts cookies and saved passwords at rest with a
per-machine **Safe Storage** key held in this Mac's login Keychain, so they
-cannot simply be copied to another machine. When **Keep me signed in** is
+cannot simply be copied to another computer. When **Keep me signed in** is
checked, teleport decrypts the cookies here (the OS asks you to allow that
-Keychain read) and carries the decrypted values, not the source machine's
+Keychain read) and carries the decrypted values, not the source computer's
key; the Space re-encrypts them under its own Safe Storage key before Chrome
ever reads them. The source's key never leaves this Mac.
@@ -50,7 +50,7 @@ there -- unless a master password is set, which is refused rather than
guessed at.) To actually sign in with a saved Chrome password, use the
[Keyvault](/spaces/guides/keyvault) (`cua keyvault import-passwords`)
instead: it decrypts on import and signs in through [site
-login](/spaces/guides/site-login), without ever exposing the password to an
+login](/spaces/guides/keyvault#let-an-agent-sign-in-to-a-site), without ever exposing the password to an
agent. **Keep me signed in** (cookies) does not have this limitation on
either browser.
</Callout>
@@ -223,7 +223,7 @@ runs teleport; an SDK runtime without Cua Spaces raises
</Tab>
</Tabs>
-The Rust tab is from [the examples in other languages](/spaces/examples/other-languages); the Swift tab is from [Cua Bots](/spaces/examples/cua-bots), which teleports a saved sign-in the user picked.
+The Rust tab is from [the examples in other languages](/spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages); the Swift tab is from [Cua Bots](/spaces/examples/cua-bots), which teleports a saved sign-in the user picked.
Returning nothing raises `TeleportRefused`. Sensitive items need
`acknowledge_sensitive=True`. MCP tools: `teleport_manifest`, `teleport_app`.
diff --git a/docs/content/docs/spaces/guides/troubleshoot-create.mdx b/docs/content/docs/spaces/guides/troubleshoot.mdx
similarity index 74%
rename from docs/content/docs/spaces/guides/troubleshoot-create.mdx
rename to docs/content/docs/spaces/guides/troubleshoot.mdx
index fd7d698e32..201d638e9f 100644
--- a/docs/content/docs/spaces/guides/troubleshoot-create.mdx
+++ b/docs/content/docs/spaces/guides/troubleshoot.mdx
@@ -1,21 +1,26 @@
---
-title: Troubleshoot a failed create
-description: 'Fix a Space that does not create: the common causes (disk, container engine, virtualization, the two-VM limit, Local Network), how to retry, and how to ask for help.'
+title: Troubleshoot
+description: 'Fix a Space that does not create (disk, container engine, virtualization, the two-VM limit, Local Network), find help for agents and computers that will not connect, and ask for help.'
---
import { Callout } from 'fumadocs-ui/components/callout';
+Most problems are a Space that won't create, or an agent or computer that won't
+connect. This page covers a failed create in detail and points to the fix for the
+rest.
+
+## A Space won't create
+
When a Space can't be created, Cua Spaces shows **Couldn't create this Space**
-with the reason, a **Try again** button and a **Remove from list** button. This
-page explains the usual reasons and what to do about each.
+with the reason, a **Try again** button and a **Remove from list** button.
{/* VIDEO: Fix a Space that fails to create: read the reason, retry, and send a report (about 45 seconds) */}
-## Try these first
+### Try these first
1. Press **Try again**. A retry reuses the image that already downloaded, so it
is usually much faster than the first attempt.
-2. Update Cua Spaces to the latest version. See [Updates](/spaces/guides/updates).
+2. Update Cua Spaces to the latest version. See [Updates](/spaces/guides/install#updates) in Install.
3. Run the checks in a terminal:
```bash test="cli-shape" id="cua-doctor-host"
@@ -23,7 +28,7 @@ cua runtime doctor # which container engines and VM runtimes this computer h
cua doctor # host checks in one report
```
-## Find your reason
+### Find your reason
Match the reason the app shows to the rows below. The word in parentheses is the
fixed name Cua uses for the cause. See [Create failure kinds](/cua-sdk/concepts/telemetry-error-kinds)
@@ -40,14 +45,14 @@ for the full list.
| macOS blocked the connection to the new VM (`local_network`) | Open **System Settings, Privacy & Security, Local Network**, turn on Cua Spaces, then try again. |
| "The Cua daemon isn't running. Start Cua, or run `cua daemon start`." | Open Cua Spaces, or run `cua daemon start`. |
-## Creating on another machine
+### Creating on another computer
-To create a Space on one of your other machines, that machine must be online,
+To create a Space on one of your other computers, that computer must be online,
provide Spaces, and be set up for your account. If the create fails with a name
such as `ambiguous_host` or `host_capability_missing`, see the
-[troubleshooting table](/spaces/guides/host-spaces-on-your-spare-mac#troubleshooting).
+[spare Mac errors](/spaces/guides/add-a-computer#spare-mac-errors).
-## Stop a create that is stuck
+### Stop a create that is stuck
Press **Cancel** in the toolbar of a Space that is being created. Cua Spaces
removes the partial Space and keeps the finished image layers, so the next
@@ -73,6 +78,16 @@ system, and the Cua Spaces version from **Settings, About**.
Remove anything you don't want to share before you send.
</Callout>
+## Other problems
+
+| What you see | Where to look |
+|---|---|
+| The agent has no `cua` tools, or can't reach a Space | [If it doesn't work](/spaces/guides/connect-your-agent#if-it-doesnt-work) in Connect your agent |
+| A computer never appears, or shows **Offline** | [If it doesn't work](/spaces/guides/add-a-computer#if-it-doesnt-work) in Add a computer |
+| An error name such as `capability_missing` or `permission_denied` | [Errors](/spaces/reference/errors) in the Spaces reference |
+| You want Cua Spaces gone, or a clean reinstall | [Uninstall Cua Spaces](/spaces/guides/uninstall), then [Install](/spaces/guides/install) |
+| Something else | Email [email protected] as described above |
+
## Next
- [Create a Space](/spaces/guides/add-a-space): images, progress, GPUs.
diff --git a/docs/content/docs/spaces/guides/unattended-access.mdx b/docs/content/docs/spaces/guides/unattended-access.mdx
deleted file mode 100644
index 99fdaaebbe..0000000000
--- a/docs/content/docs/spaces/guides/unattended-access.mdx
+++ /dev/null
@@ -1,167 +0,0 @@
----
-title: Set up unattended access
-description: 'Make this machine a Space you reach from your other devices: cua host setup installs cua-spacesd as a service that joins the cua.ai relay, or serves on ip:port.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-Unattended access makes a computer reachable from your other devices without
-anyone sitting at it, so your agents can use it any time. For the quick path with
-a link or a code, see [Add a machine](/spaces/guides/add-a-machine). This page
-has every option and the details.
-
-`cua host setup` installs cua-spacesd as a service. By default it joins the
-cua.ai relay over outbound WSS as your account: no port forwarding, no token to
-copy. Your other devices, once [enrolled](#reach-it-from-your-devices), then see
-this machine as `relay:<machine-id>` in `cua spaces ls` and the app. The app's
-**Set up for access** button runs the same setup.
-
-```bash test="cli-shape" id="cua-auth-login"
-cua host setup # signs in to cua.ai for this command if needed
-```
-
-The host keeps only its own machine token. When the machine is not signed in,
-setup signs you in for that one command and stores no session, so a dedicated
-host holds no account credentials. The machine token lets the host serve itself
-and stop sharing; it cannot list or reach your other machines, change who the
-machine is shared with, or enroll devices.
-
-| Option | Effect |
-|--------|--------|
-| `--remote` | When sign-in is needed, print a device code to approve in a browser on another machine (for example over SSH). The account session is not saved. Cannot be combined with `--direct`. |
-| `--direct ip:port` | Serve on your LAN (or a forwarded port) with a local env token instead of the relay. No account needed. |
-| `--relay URL` | Use a different relay (`CUA_RELAY_URL`). The default is `https://relay.cua.ai`. |
-| `--name NAME` | Display name (default: host name). |
-| `--allow ACCOUNT` | Also allow this account (id or email). Repeatable. |
-| `--runner KIND` | `auto`, `systemd`, `launchd`, `windows-task` or `process`. |
-| `--profile spare` | A spare machine: do not share its desktop, create Spaces for your devices (`--no-desktop --provide-spaces`). See [Host Spaces on a spare Mac](/spaces/guides/host-spaces-on-your-spare-mac). |
-| `--no-desktop` / `--provide-spaces` | Each of the two settings on its own. `cua host config` changes them later. |
-
-Running `setup` again updates the configuration and rotates the machine token.
-The host checks the relay's signed identity assertion against the owner and the
-allowlist; the env token never leaves the machine.
-
-| OS | Service |
-|----|---------|
-| macOS | LaunchAgent `com.trycua.spacesd.host` in your GUI session. Grant cua-spacesd **Screen Recording** and **Accessibility**, and [Cua Driver](/cua-driver/quickstart) its own permissions. |
-| Linux | systemd unit `cua-spacesd-host.service` (user unit; system unit as root). |
-| Windows | Scheduled task `Cua\SpacesdHost` at logon, in your interactive session. |
-
-On Windows the host runs in your signed-in session, so your devices reach the
-desktop only while it is signed in, unlocked and on screen:
-
-- **After a restart**, sign in once (or turn on automatic sign-in). The host
- starts at sign-in.
-- **Locked:** Windows doesn't let apps see or use its lock screen. For
- unattended access, turn off automatic locking in **Settings > Accounts >
- Sign-in options** and the screen saver's "On resume, display logon screen".
-- **Remote Desktop:** closing a Remote Desktop window leaves the session
- disconnected, and Windows stops drawing it. To leave a remote PC (a cloud VM)
- reachable, end Remote Desktop from an administrator prompt with
- `tscon %sessionname% /dest:console` instead.
-
-A viewer or agent that connects in one of these states sees which one it is.
-
-## Check, pause, remove
-
-```bash test="cli-shape" id="cua-host-status"
-cua host status # setup, service, who is connected; missing permissions
-cua host stop # disconnect everyone and refuse new connections
-cua host start # share again
-cua host remove # unregister, uninstall the service, delete ~/.cua/host
-```
-
-Uninstalling the app turns this off too. On Linux, `sudo apt remove cua-spaces`
-(and `purge`) removes the machine, and the Spaces it provides, from the relay,
-deletes the `cua-spacesd-host.service` user unit and stops the daemon. Your
-Spaces and data under `~/.cua` stay on the machine (the Spaces are turned off).
-
-`cua host stop` turns sharing off locally first, so it holds even when the
-relay is unreachable. In direct mode `cua host status` prints the URL and the
-env token's path; add the machine elsewhere with
-[`spaces.add(url, token)`](/spaces/guides/add-a-space#add-an-existing-machine-by-address).
-
-<Callout type="warn">
- Everyone on the allowlist gets full control of this desktop. Keep the list
- short and run `cua host stop` when you do not need it. To let someone only
- watch, [share it as a viewer](/spaces/guides/share-a-space).
-</Callout>
-
-## Share with other accounts
-
-`--allow` at setup, or later from an enrolled device, shares the machine with
-another account (id or verified email). Sharing asks for confirmation;
-unsharing cuts that account's open connections.
-
-```bash test="cli-shape" id="cua-host-share"
-cua host share [email protected]
-cua host unshare [email protected]
-```
-
-## Reach it from your devices
-
-A device that lists or opens your machines through the relay is enrolled once
-with a second factor. A stolen account session alone is not enough. Hosting
-never enrolls a machine as a client.
-
-- **Sign in:** `cua devices enroll` right after `cua auth login` enrolls the
- device at once. A device that enrolled before re-enrolls on its own when you
- sign in again (in the CLI or the app), so an expired or replaced key never
- needs another device.
-- **Approve:** on a long-lived session, `cua devices enroll` shows a one-time
- code instead. Approve it on an enrolled device with
- `cua devices approve <code>` or by its id (`cua devices approve dev_...`),
- or in the app, which asks for Touch ID.
-
-Each device reports a hash of its machine's identity. When a new key of the
-same machine enrolls (another build of the app, a lost key), it replaces the
-old record, so one machine is one device. Builds of cua that store the key
-differently (the OS keychain for signed builds, a `0600` file otherwise) share
-one key: the signed build moves the file's key into the keychain.
-
-```bash test="cli-shape" id="cua-devices"
-cua devices enroll
-cua devices approve K7QX-M2RP
-cua devices approve dev_0123456789abcdef01234567
-cua devices ls
-cua devices audit # who opened which machine, from which device, and when
-cua devices revoke dev_0123456789abcdef01234567
-```
-
-The device key stays in the OS keychain (or a `0600` file where there is none).
-Enrollment lasts 30 days. After that, a fresh sign-in or one approval
-re-verifies the device. Until then, unattended agents on an enrolled device
-keep working without prompts.
-
-**Re-signing in is enough only for your own machine**: the same machine
-enrolling again with a new key (another build, a lost key), or your account's
-first device. A brand-new device on an account that already has an enrolled
-device needs either an approval from an enrolled device, or a sign-in whose
-token itself proves a second factor (MFA) with your identity provider --
-a verified email alone no longer enrolls it silently. Either way, every
-enrolled device is notified (the app's notification feed and
-`cua devices audit`), so a device you do not recognize does not slip in
-unnoticed.
-
-Relays can run a **migration grace period** right after enrollment is turned
-on, during which a signed-in session alone is let through (flagged and
-audited) while apps catch up. It is off by default and, on `relay.cua.ai`,
-only ever runs for a short, announced window right after a rollout; check
-`cua devices ls` (it reports `enforce_after`) or `cua host status` if you are
-unsure whether it is currently open.
-
-In the Cua Spaces app, **Settings > Devices** shows the same: this device's
-enrollment (enrolled until a date, or when a grace period ends), your devices
-with Rename and Revoke, and Recent Access (which device opened which machine,
-and when). **Enroll** offers a fresh sign-in or a one-time code to approve
-elsewhere. When another device asks to join and needs an approval, the app
-shows a notification and an approval sheet; Approve asks for Touch ID or your
-login password first, and Deny revokes that device. A device enrolled by a
-sign-in that proved MFA shows up already enrolled, with no approval step, the
-same as your own machine re-signing in.
-
-A machine registered without an enrolled device's signature or a sign-in that
-proved MFA is recorded as unconfirmed on the relay (`GET /v1/machines`'
-`confirmed` field) and can be confirmed from an enrolled device
-(`POST /v1/machines/{id}/confirm`); surfacing this as a "New machine" badge
-in the apps is tracked separately.
diff --git a/docs/content/docs/spaces/guides/uninstall.mdx b/docs/content/docs/spaces/guides/uninstall.mdx
index cb7059f73f..bfd189b12f 100644
--- a/docs/content/docs/spaces/guides/uninstall.mdx
+++ b/docs/content/docs/spaces/guides/uninstall.mdx
@@ -36,7 +36,7 @@ curl -fsSL https://cua.ai/uninstall.sh | sh -s -- --dry-run
- The `cua` CLI, and the line the installer added to your shell profile (the user
PATH on Windows).
- The host service, after `cua host remove`, so this computer no longer shows up
- as a machine in your account.
+ as a computer in your account.
- The Cua skills and MCP entries in your AI agents, the way `cua agents remove`
does. Entries from other tools stay.
- Launch at login.
diff --git a/docs/content/docs/spaces/guides/updates.mdx b/docs/content/docs/spaces/guides/updates.mdx
deleted file mode 100644
index 35d1ebfce1..0000000000
--- a/docs/content/docs/spaces/guides/updates.mdx
+++ /dev/null
@@ -1,53 +0,0 @@
----
-title: Updates
-description: 'How the Cua Spaces app updates itself on macOS, Windows and Linux, how to pick the Stable or Beta channel, and what it refreshes after an update.'
----
-
-Cua Spaces checks for new versions and downloads them in the background on
-macOS, Windows and Linux. Everything is in **Settings, About**, which also shows
-your version.
-
-## How updates work
-
-The app checks when it starts and again every few hours. When a new version is
-ready, a line appears at the bottom of the sidebar: **Update ready**, with
-**Restart to update** and a **What's new** link to the release notes. Nothing
-restarts until you click. If an agent is still working, the app asks first.
-
-In **Settings, About**:
-
-- **Check for and download updates automatically** turns the background checks on
- or off. With it off, press **Check Now** to check by hand.
-- **Install a downloaded update when Cua Spaces quits** installs a downloaded
- update when you quit the app. It needs automatic checks.
-- **Last check** says when the app last looked.
-
-On macOS, every update is the same notarized disk image as the download on the
-release page, and the app installs it only when its signature matches the key
-built into the app. Windows and Linux update through their own updater.
-
-## Channels
-
-**Update to:** picks what you get:
-
-- **Stable**: tested releases.
-- **Beta**: releases and prereleases, with new features sooner and rough edges.
-
-Going back to Stable from a newer beta keeps the version you have until a newer
-stable release is out.
-
-## After an update
-
-The first time the new version opens, it refreshes what Cua installed into your
-AI agents, the way `cua agents update` does: the Cua skill folders and the Cua
-MCP entries in Claude Code, Cursor and the other agents you set up. A skill
-folder you edited is left as you left it. It also restarts the Cua daemon when
-the app started it, so the daemon runs the new version too.
-
-This happens without any window. If something fails, the app shows one notice
-with what to run.
-
-## Next
-
-- [Install](/spaces/guides/install): download a version by hand.
-- [Troubleshoot a failed create](/spaces/guides/troubleshoot-create): update first, then retry.
diff --git a/docs/content/docs/spaces/guides/use-from-an-agent.mdx b/docs/content/docs/spaces/guides/use-from-an-agent.mdx
deleted file mode 100644
index 01dfb99f6a..0000000000
--- a/docs/content/docs/spaces/guides/use-from-an-agent.mdx
+++ /dev/null
@@ -1,124 +0,0 @@
----
-title: Use Spaces from an agent
-description: 'The Spaces tools an AI coding agent gets through cua daemon mcp, and how to run agents inside a Space as long-lived threads.'
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
-
-The cua MCP server gives an agent 33 Spaces tools plus sandbox and computer
-tools. For the machine the agent runs on, use
-[Cua Driver](/cua-driver/quickstart) instead.
-
-## Tools your agent gets
-
-To connect an agent, see [Connect your agent](/spaces/guides/connect-your-agent).
-Narrow what it can do with `--permissions spaces:readonly`
-([permissions](/cua-cli/guides/mcp-server#permissions)).
-
-```text output
-list_spaces / create_space {reuse} -> pick, reuse or create a Space
-space_bash {space, command} -> run commands inside it
-send_file {space, path} -> drop a host file into ~/Downloads (sha256-verified)
-stream_endpoint -> a ticketed media URL
-list_tools / call_tool -> cua-driver tools in the Space, or any declared service
-delete_space {space} -> delete it and stop metering
-```
-
-`space` is an id or a name. A tool whose feature the Space lacks returns
-`capability_missing`.
-
-## Run an agent inside a Space
-
-| Tool | Does |
-|------|------|
-| `agent_capabilities` | Ready harnesses (`claude-code`, `openai-codex`). |
-| `agent_start {space, agent, prompt, show}` | Start a detached run; `show` tails it in a terminal on the Space desktop. |
-| `agent_message {space, run_id, text, force}` | Next turn; refused mid-turn unless `force`. |
-| `agent_status`, `agent_list`, `agent_stop` | State, output tail, stop. |
-
-Runs live in the guest (`~/.spaces-agents/<run_id>/`) and survive the client
-going away. The daemon copies your agent's credential file (for example
-`~/.claude/.credentials.json`) into the Space at start;
-`CUA_SPACES_AGENT_CREDENTIALS_HOME=none` copies nothing.
-
-In TypeScript a run is a thread:
-
-```ts skip="third-party-cli"
-import { embedded } from "@trycua/cua"
-import { startThread } from "@trycua/cua/spaces"
-
-const bot = await startThread(embedded().spaces(), {
- agent: "claude-code",
- prompt: "Open the repo in the Space and run the tests",
- placement: { type: "dedicated", on: "local", deleteOnClose: true },
-})
-await bot.send("Now fix the failing test")
-console.log(await bot.status())
-await bot.close() // stops the run and deletes the Space
-```
-
-`placement` `shared` (`{ type: "shared", space, acknowledgeNoIsolation: true }`)
-reuses a Space you name; `adoptThread(spaces, spaceId, runId)` reattaches.
-
-The lower-level calls, one run per thread and one message per turn. The
-TypeScript and Rust tabs are from [the examples in other languages](/spaces/examples/other-languages), the Swift tab from
-[Cua Bots](/spaces/examples/cua-bots). A message sent mid-turn is
-refused (or queued) unless forced; show the reason.
-
-<Tabs items={['TypeScript', 'Rust', 'Swift']}>
- <Tab value="TypeScript">
- ```ts test="excerpt" id="ts-agent-start" source="samples/openkoalabot-example-ts/src/core/app.ts#ts-agent-start"
- const report = await space.agentStart(bot.agent, prompt, false, options)
- const t = new BotThread(bot, report.runId, space)
- ```
-
- ```ts test="excerpt" id="ts-agent-message" source="samples/openkoalabot-example-ts/src/core/app.ts#ts-agent-message"
- const r = await this.space.agentMessage(this.runId, message, false)
- if (!r.ok) {
- this.fold.note(this.turns.length, `Refused: ${r.reason}`)
- return { accepted: false, reason: r.reason }
- }
- ```
- </Tab>
- <Tab value="Rust">
- ```rust test="excerpt" id="rs-agent" source="samples/openkoalabot-example-tauri/src-tauri/core/src/thread.rs#rs-agent"
- let r = self
- .agents
- .start(&self.agent, text, self.options.clone())
- .await
- .map_err(agents_err)?;
- ```
-
- ```rust test="excerpt" id="rs-agent-message" source="samples/openkoalabot-example-tauri/src-tauri/core/src/thread.rs#rs-agent-message"
- let r = self
- .agents
- .send(run, text, vec![])
- .await
- .map_err(agents_err)?;
- if !r.accepts_message {
- self.system(format!("queued while {}: {}", r.phase, r.reason));
- }
- ```
- </Tab>
- <Tab value="Swift">
- ```swift test="excerpt" id="sw-agent-start" source="samples/cua-bots-macos/Sources/CuaBotsCua/CuaEngine.swift#sw-agent-start"
- let options = SpaceAgentOptions(
- envFromHost: endpoint?.keyVariables ?? Self.defaultKeyVariables(bot.harness),
- repo: nil, branch: nil, cwd: home, model: endpoint?.model, baseUrl: endpoint?.baseURL,
- exitWhenIdle: false)
- let report = try await space.agentStart(agent: bot.harness.rawValue, prompt: prompt, show: false,
- options: options)
- ```
-
- ```swift test="excerpt" id="sw-agent-message" source="samples/cua-bots-macos/Sources/CuaBotsCua/CuaEngine.swift#sw-agent-message"
- let report = try await space(bot).agentMessage(runId: run, text: text, force: false)
- if !report.ok { throw EngineError.refused(report.reason) }
- ```
- </Tab>
-</Tabs>
-
-<Callout type="warn">
- `space_bash`, `send_file`, `teleport_app` and `hotspot_start` act with your
- authority. Grant `spaces:readonly` to agents that only need to look.
-</Callout>
diff --git a/docs/content/docs/spaces/index.mdx b/docs/content/docs/spaces/index.mdx
index d4c8c1e9d3..81a37750c9 100644
--- a/docs/content/docs/spaces/index.mdx
+++ b/docs/content/docs/spaces/index.mdx
@@ -12,7 +12,9 @@ spare Linux box, a VM in your own cloud account. Cua does not rent them.
A **Space** is one desktop on one of those computers, set up for a task. Your
agent runs commands in it and uses its apps and browser. You see the same
-screen, take over when you want, and give a teammate access.
+screen and take over when you want. You can share a Space with anyone who has
+a cua.ai account, to watch it or to work in it. On the Teams plan you can also
+share it with your whole team.
## Get started
@@ -20,7 +22,7 @@ screen, take over when you want, and give a teammate access.
run a first task. About five minutes.
2. [Connect your agent](/spaces/guides/connect-your-agent): add Spaces to
Claude Code, Codex, Cursor and other agents.
-3. [Add a machine](/spaces/guides/add-a-machine): connect another Mac, Linux
+3. [Add a computer](/spaces/guides/add-a-computer): connect another Mac, Linux
or Windows computer you own.
## What do you want to do?
@@ -29,12 +31,10 @@ screen, take over when you want, and give a teammate access.
|---|---|
| Install on Mac, Windows or Linux | [Install](/spaces/guides/install) |
| Let my agent use Spaces | [Connect your agent](/spaces/guides/connect-your-agent) |
-| Use another computer I own | [Add a machine](/spaces/guides/add-a-machine) |
-| Reach my computers from my other devices | [Set up unattended access](/spaces/guides/unattended-access) |
-| Let a teammate watch or work in a Space | [Share a Space](/spaces/guides/share-a-space) |
-| Compare Free, Pro and Teams | [Plans](/spaces/guides/plans) |
-| Set up a team with shared machines | [Teams](/spaces/guides/teams) |
-| Fix a Space that won't create | [Troubleshoot a failed create](/spaces/guides/troubleshoot-create) |
+| Use another computer I own, or reach my computers from my other devices | [Add a computer](/spaces/guides/add-a-computer) |
+| Let someone else watch or work in a Space | [Share a Space](/spaces/guides/share-a-space) |
+| Compare Free, Pro and Teams, or set up a team | [Plans and Teams](/spaces/guides/teams) |
+| Fix a Space that won't create | [Troubleshoot](/spaces/guides/troubleshoot) |
| Move a signed-in app into a Space | [Teleport an app](/spaces/guides/teleport-an-app) |
| Understand how it fits together | [How Spaces works](/spaces/concepts/how-spaces-works) |
@@ -43,10 +43,10 @@ screen, take over when you want, and give a teammate access.
The `cua` CLI, the MCP server and the SDKs (Python, TypeScript, Swift and
Rust) use the same Spaces as the app.
-- [Use Spaces from an agent](/spaces/guides/use-from-an-agent): the Spaces
- tools your agent gets over MCP.
-- [Create a Space with the Cua SDK](/spaces/guides/create-a-space-with-the-sdk):
- create, use and delete a Space from code.
+- [What your agent can do](/spaces/guides/connect-your-agent#what-your-agent-can-do):
+ the Spaces tools your agent gets over MCP.
+- [Use Spaces from code](/spaces/guides/create-a-space-with-the-sdk): create, use
+ and delete a Space from code.
- [Reference](/spaces/reference): every Spaces tool, its parameters and its
errors.
- [Examples](/spaces/examples/cua-bots): apps built on the Spaces SDK.
diff --git a/docs/content/docs/spaces/quickstart.mdx b/docs/content/docs/spaces/quickstart.mdx
index 2590848606..cca8a7f8bf 100644
--- a/docs/content/docs/spaces/quickstart.mdx
+++ b/docs/content/docs/spaces/quickstart.mdx
@@ -1,13 +1,13 @@
---
title: Quickstart
-description: 'Install Cua Spaces, connect your AI agent, and ask it to work on a computer you can watch. About five minutes.'
+description: 'Install Cua Spaces, connect your AI agent, make this Mac your first Space and send your first request. About five minutes.'
---
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-In about five minutes you install Cua Spaces, connect your AI coding agent, and
-ask it to run a task in a Space while you watch.
+In about five minutes you install Cua Spaces, connect your AI coding agent, make
+this computer your first Space and ask your agent to use it while you watch.
{/* VIDEO: Install Cua Spaces, connect an agent and watch it work in a Space (about 60 seconds) */}
@@ -16,13 +16,11 @@ ask it to run a task in a Space while you watch.
- A Mac (macOS 26 or later), a Windows PC (preview) or a Linux PC (Ubuntu 24.04).
- An AI coding agent, such as Claude Code, Codex or Cursor. See the
[supported agents](/cua-cli/guides/mcp-server#supported-agents).
-- Enough room for a first Space. A Linux Space needs a container engine such as
- Docker running on this computer. A macOS Space needs an Apple silicon Mac and
- about 50 GB of free disk, and its first image is a large download, so a Linux
- Space is the faster way to see it work.
+- A free Cua account. The app asks you to sign in during setup.
-You don't need an account to start. Sign in later to reach your computers from
-other devices.
+Your computer is your first Space, so there is nothing big to download. An extra
+Space is optional: a Linux Space needs a container engine such as Docker, and a
+macOS Space needs an Apple silicon Mac and about 50 GB of free disk.
## 1. Install Cua Spaces
@@ -45,44 +43,59 @@ has the details for each system.
## 2. Connect your agent
-Open Cua Spaces. The app walks you through a few first-run screens.
+Open Cua Spaces. The first screen says "A shared Space for every agent."
-1. On **Sign in**, sign in or skip.
-2. On **AI agents**, tick the agents you use and press **Set up**. When you see
- "Your AI agents are set up", press **Continue**. The app gave each agent the
- `cua` skills and MCP server.
-3. On **This machine**, keep **Access other machines** and continue. Pick the
- other option only for a computer you want to reach from elsewhere.
+Press **Connect Claude Code**. If you use another agent, pick it instead:
+Codex, Hermes, OpenClaw or **Other**. The app adds Cua to that agent's settings.
-If your agent was already running, start a new session so it loads the new
-tools. To connect an agent later, see [Connect your agent](/spaces/guides/connect-your-agent).
+If your agent was already open, close it and open it again so it loads the new
+tools. To connect more agents later, see [Connect your agent](/spaces/guides/connect-your-agent).
-## 3. Create your first Space
+## 3. Make this computer your first Space
-On the last screen, choose **Create** next to a system. Cua Spaces shows the
-download progress, and the Space appears in your list when it is ready. You can
-also create one later with **New Space**.
+The app checks your setup and shows what's left. These steps use the Mac
+wording; on Windows and Linux the app says "this PC" or "this computer". Press the button on each row:
-## 4. Ask your agent to use it
+1. **Sign in**, then finish signing in to Cua in your browser. The app then
+ adds this Mac to your account by itself.
+2. **Let Cua control this Mac**, so your agent can click and type.
+3. **Let Cua see this screen**, so your agent can see what's on it.
-The last screen has a **Try asking your agent** list. Press a prompt to copy it,
-then paste it into your agent:
+Each of the last two opens System Settings. Turn Cua on there; macOS asks you
+only once. When every row is done, the app says "Your agent can use this Mac."
+This Mac is now your first Space.
-- "Open a Linux Space and run my test suite in it"
-- "Use my Space's browser to finish the checkout test and show me"
-- "Share this Space with a teammate as a viewer"
+## 4. Try your first request
-Open the Space from Cua Spaces to watch the agent work. You can take over at any
-time by using the desktop yourself.
+Under **Try this in Claude Code**, press **Copy** and paste the request into
+your agent:
+
+> List my computers and tell me what's on this Mac
+
+It works right away, on this Mac. Open Cua Spaces to watch your agent work, and
+use the desktop yourself whenever you want to take over.
+
+## 5. Add a Linux Space (optional)
+
+**Give your agent its own Space** offers a fresh computer inside this Mac, away
+from your files and your mouse. Choose **Linux** for the quickest one (a Mac can
+also make a macOS Space), or choose **No extra Space for now**. The card shows
+how long it takes and how much it downloads.
+
+Press **Done** whenever you like. The new Space keeps getting made after the
+window closes, shows its progress in the sidebar, and you get a notice when it's
+ready.
<Callout type="info">
- A Space that fails to create shows the reason and a **Try again** button. See
- [Troubleshoot a failed create](/spaces/guides/troubleshoot-create).
+ If a step is still open, the button says **Finish later**. Home then keeps a
+ **Finish setting up** list with the same steps. A Space that fails to create
+ shows the reason and a **Try again** button. See
+ [Troubleshoot](/spaces/guides/troubleshoot).
</Callout>
## Next
-- [Add a machine](/spaces/guides/add-a-machine): use another computer you own.
+- [Add a computer](/spaces/guides/add-a-computer): use another computer you own.
- [Share a Space](/spaces/guides/share-a-space): let a teammate watch or work in it.
-- [Plans](/spaces/guides/plans): what Free, Pro and Teams include.
-- Using code instead? [Create a Space with the Cua SDK](/spaces/guides/create-a-space-with-the-sdk).
+- [Plans and Teams](/spaces/guides/teams): what Free, Pro and Teams include.
+- Using code instead? [Use Spaces from code](/spaces/guides/create-a-space-with-the-sdk).
diff --git a/docs/content/docs/spaces/reference/sharing.mdx b/docs/content/docs/spaces/reference/sharing.mdx
index 1f134807c3..7b8d5fde30 100644
--- a/docs/content/docs/spaces/reference/sharing.mdx
+++ b/docs/content/docs/spaces/reference/sharing.mdx
@@ -22,7 +22,7 @@ description: "Let other cua.ai accounts watch or edit a Space, through the relay
Let another cua.ai account watch or edit a Space.
-Shares the Space through the cua.ai relay with one account, by verified email or account id; the same allowlist and device enrollment `cua host share` uses. A viewer joins presence with their own named cursor and watches a view-only stream: the Space's driver refuses their input, shell, files and MCP. An editor gets full use, and their input is a human session. Sharing again changes the role. A host (`relay:<id>`) is shared directly; any other Space (local, cloud, or added by address) is attached to the relay on its first share: its own driver dials out, so it needs no inbound port. Invitees open `invitee_space`.
+Shares the Space through the cua.ai relay with one account, by verified email or account id, or with a whole team as `team:<id>` (always as an editor; Teams plan); the same allowlist and device enrollment `cua host share` uses. A viewer joins presence with their own named cursor and watches a view-only stream: the Space's driver refuses their input, shell, files and MCP. An editor gets full use, and their input is a human session. Sharing again changes the role. A host (`relay:<id>`) is shared directly; any other Space (local, cloud, or added by address) is attached to the relay on its first share: its own driver dials out, so it needs no inbound port. Invitees open `invitee_space`.
| | |
| --- | --- |
@@ -40,7 +40,7 @@ Shares the Space through the cua.ai relay with one account, by verified email or
| --- | --- | --- | --- |
| `role` | `string` | `viewer` | `viewer` (presence with their own cursor and a view-only stream) or `editor` (full use; their input is a human session). Default `viewer`. |
| `space` | `string` | required | Space id or name. |
-| `who` | `string` | required | Who: an email address (verified by cua.ai) or an account id. Teams are not accepted: share with each member. |
+| `who` | `string` | required | Who: an email address (verified by cua.ai) or an account id, or `team:<id>` for a whole team. A team always gets `editor` and needs the Teams plan; the sharer is a team owner or admin who owns the Space. |
### Result
diff --git a/docs/content/docs/start-here/create-a-local-macos-sandbox.mdx b/docs/content/docs/start-here/create-a-local-macos-sandbox.mdx
deleted file mode 100644
index 6e0effeeea..0000000000
--- a/docs/content/docs/start-here/create-a-local-macos-sandbox.mdx
+++ /dev/null
@@ -1,101 +0,0 @@
----
-title: Create a local macOS sandbox with the Cua CLI
-description: Create a macOS Tahoe sandbox on an Apple silicon Mac with `cua sb create macos`, run a command, take a screenshot, open its desktop, and remove it.
----
-
-Requirements: Apple silicon, macOS 14 or later, about 40 GB free disk and 8 GB free memory.
-
-## Install
-
-```bash skip="host-install"
-curl -fsSL https://cua.ai/install.sh | sh
-```
-
-```bash test="cli-shape" id="macos-runtime-setup"
-cua runtime doctor
-cua runtime setup lume # installs Lume if it is missing
-```
-
-## Create
-
-```bash test="cli-shape" id="macos-sb-create"
-cua sb create macos --name mac
-```
-
-```text output
-ID STATUS LOCATION KIND RUNTIME EXPIRES
-local:mac ready local vm lume -
-```
-
-`macos` is `ghcr.io/trycua/macos:26` (Tahoe); `macos:sequoia` is `:15`. The
-first create pulls the image (23 GB, about 8 min); later creates clone it and
-are ready in about 25 s. The Tahoe image starts cua-spacesd at login, with its
-screen and accessibility permissions already granted.
-
-## Run a command
-
-```bash test="cli-shape" id="macos-sb-exec"
-cua sb exec mac -- sw_vers
-```
-
-```text output
-ProductName: macOS
-ProductVersion: 26.5.2
-BuildVersion: 25F84
-```
-
-`exec` runs through cua-spacesd, with stdout, stderr and the exit code kept
-apart. The Sequoia image (`macos:sequoia`) has no cua-spacesd; there `exec`
-runs over SSH (`lume ssh`).
-
-## Screenshot and view
-
-```bash test="cli-shape" id="macos-sb-screenshot"
-cua sb screenshot mac -o desktop.png
-```
-
-```text output
-wrote desktop.png (1024x768)
-```
-
-![The desktop of a local macOS Tahoe sandbox](/img/cua-cli/macos-sandbox-desktop.png)
-
-```bash test="cli-shape" id="macos-sb-view"
-cua sb view mac
-```
-
-```text output
-Viewer for mac: http://192.168.64.63:3211/viewer/#ticket=****&files=%2FUsers%2Flume
-```
-
-`view` opens cua-spacesd's HTML5 viewer in the browser with a short-lived
-ticket (`--no-open` prints the URL instead). On Sequoia, which has no
-cua-spacesd, screenshots come over the VM's VNC endpoint and `view` opens the
-display with `lume attach`.
-
-## Remove
-
-```bash test="cli-shape" id="macos-sb-rm"
-cua sb rm mac
-```
-
-The pulled image stays as a stopped base VM for the next create; `cua cache ls`
-lists it.
-
-## From the SDK
-
-```python skip="macos-vm"
-from cua_sandbox import Image, Sandbox
-
-async with Sandbox.ephemeral(Image.macos()) as sb:
- print((await sb.shell.run("sw_vers")).stdout)
- png = await sb.screen.screenshot()
-```
-
-`sb.shell` and `sb.screen` go through cua-spacesd, the same path as the CLI.
-
-## Next
-
-- [Local runtimes](/cua-sdk/guides/local-runtimes)
-- [Sandbox images](/start-here/sandbox-images)
-- [Lume quickstart](/lume/quickstart): a vanilla macOS VM from Apple's restore image, with Lume alone.
diff --git a/docs/content/docs/start-here/drive-your-first-app.mdx b/docs/content/docs/start-here/drive-your-first-app.mdx
deleted file mode 100644
index 7918806a64..0000000000
--- a/docs/content/docs/start-here/drive-your-first-app.mdx
+++ /dev/null
@@ -1,351 +0,0 @@
----
-title: Drive your first app with Cua Driver
-description: Install Cua Driver, connect your agent, and verify a result in a desktop app on macOS, Windows, or Linux.
----
-
-import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
-import { Callout } from 'fumadocs-ui/components/callout';
-
-By the end of this walkthrough, your agent will open Calculator, compute 6 × 7,
-and report 42 through **Cua Driver**. You will install the driver, connect
-your agent, and run a prompt that matches its integration on macOS, Windows, or
-Linux. Have an agent installed and a desktop calculator available before you
-begin. On Linux, use your distribution's calculator, such as GNOME Calculator.
-
-New to agents that operate applications? [How Cua Driver works](/cua-driver/concepts/how-cua-driver-works)
-explains the model behind the workflow.
-
-This walkthrough connects an existing agent to Cua Driver. To embed Cua Driver
-in your own program instead, see [Use the SDK](/cua-driver/guides/use-the-sdk).
-To try it without touching your own desktop, run it
-[in a sandbox](/cua-driver/guides/test-in-a-sandbox).
-
-<VideoDemo
- src="https://github.com/user-attachments/assets/11b248e5-d505-4349-aaae-ad9f95a1162f"
- poster="https://github.com/user-attachments/assets/0fb62243-56ec-4d51-8771-35640a5e6031"
- title="Drive a legacy postal app with Cua Driver"
- sourceUrl="https://x.com/trycua/status/2059693301276565841"
- className="my-8"
->
- Cua Driver fills shipment details and prints receipts in a Windows desktop app with no API. You
- will start with a smaller Calculator task below.
-</VideoDemo>
-
-## 1. Install Cua Driver
-
-Use the same one-line installer on every platform; it picks the right path for the host and needs no administrator access.
-
-<Tabs items={['macOS', 'Windows', 'Linux']}>
- <Tab value="macOS">
- Requires macOS 14 (Sonoma) or later.
-
- ```bash skip="host-install"
- /bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
- ```
-
- Start the daemon through the app bundle so macOS attributes permission prompts to CuaDriver.app. This is what makes the TCC grant stick to the driver:
-
- ```bash skip="host-macos-permissions"
- open -n -g -a CuaDriver --args serve
- ```
-
- Then grant Accessibility and Screen Recording:
-
- ```bash test="cli-shape" id="cua-driver-permissions-grant"
- cua-driver permissions grant
- ```
-
- macOS prompts once for each permission. Neither prompt grants anything on its own: both offer **Open System Settings**, not **Allow**:
-
- ![The macOS Accessibility Access prompt for CuaDriver, offering Open System Settings or Deny](https://github.com/user-attachments/assets/b7a5a0c0-f297-4249-81f9-ca42c6b6f8ba)
-
- ![The macOS Screen Recording prompt for CuaDriver, offering Open System Settings or Deny](https://github.com/user-attachments/assets/69efc964-a375-495e-8a27-400c9dd08e17)
-
- Clicking **Open System Settings** adds CuaDriver to that permission's list for you, switched off. Toggling it on is what actually grants access:
-
- ![CuaDriver listed under Accessibility in System Settings with its toggle switched off](https://github.com/user-attachments/assets/d149fe5a-28cb-460c-8868-4eda80d540a4)
-
- ![CuaDriver listed under Screen & System Audio Recording in System Settings with its toggle switched off](https://github.com/user-attachments/assets/469308b5-84d7-4fd6-a580-e62925120337)
-
- <Callout type="warn">
- Do this for both **Accessibility** and **Screen & System Audio Recording**; choosing **Deny** leaves the driver unable to see or drive your desktop. macOS may offer to quit and reopen CuaDriver when you flip a toggle. Accept, because the driver only picks up a changed grant after a full relaunch. If the daemon does not come back, start it again with `open -n -g -a CuaDriver --args serve`.
- </Callout>
-
- macOS does not always raise both prompts in one pass. Check what actually landed:
-
- ```bash test="cli-shape" id="cua-driver-permissions-status"
- cua-driver permissions status
- ```
-
- If one is still missing, run the pair again to prompt for it:
-
- ```bash test="cli-shape" id="cua-driver-permissions-grant-2"
- open -n -g -a CuaDriver --args serve
- cua-driver permissions grant
- ```
- </Tab>
- <Tab value="Windows">
- Requires Windows 10/11 with an interactive desktop session and PowerShell.
-
- ```powershell test="cli-shape" id="cua-driver-autostart-kick"
- irm https://cua.ai/driver/install.ps1 | iex
- cua-driver autostart kick
- ```
-
- The installer attempts to register Cua Driver to start automatically at sign-in. `kick` starts that task immediately. If registration was skipped or failed, run `cua-driver serve` in a terminal in the interactive desktop session and leave it open. Use a second terminal for the checks below. Over SSH, see [Windows over SSH](/cua-driver/guides/vms-and-remote#windows-over-ssh).
-
- </Tab>
- <Tab value="Linux">
- Requires an x86_64 Linux desktop session with X11 or XWayland, plus AT-SPI 2.
- On a minimal Debian or Ubuntu image, first run
- `sudo apt install libxi6 at-spi2-core`. Run this walkthrough inside the
- desktop session, where the driver can reach its display and accessibility
- bus.
-
- ```bash skip="host-install"
- /bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
- ```
-
- Start the daemon from a terminal in the same desktop session:
-
- ```bash test="cli-shape" id="cua-driver-serve"
- cua-driver serve
- ```
-
- Leave that terminal open. Run the verification commands below in a second
- terminal in the same desktop session.
-
- </Tab>
-</Tabs>
-
-<Callout type="info">
- The daemon you just started runs in the default `standard` permission mode, which is the right choice for this walkthrough. Once you move past Calculator, read [Permissions](/cua-driver/guides/permissions) to decide whether a real workload should be `bounded` instead. Stale macOS grants? See [Troubleshoot](/cua-driver/guides/troubleshoot#reset-stale-macos-permissions).
-</Callout>
-
-## 2. Verify it is working
-
-First confirm that the daemon is reachable:
-
-```bash test="cli-shape" id="cua-driver-status"
-cua-driver status
-```
-
-Expect `Cua Driver daemon is running`. If it is not running, repeat your
-platform's startup step above. Then check the environment:
-
-```bash test="cli-shape" id="cua-driver-doctor"
-cua-driver doctor
-```
-
-Then list the running GUI apps the driver can reach:
-
-```bash test="cli-shape" id="cua-driver-call"
-cua-driver call list_apps
-```
-
-Read the `doctor` report, including warnings: a zero exit code does not prove
-desktop readiness. On macOS, also confirm both grants with
-`cua-driver permissions status`. Continue when the required permissions and
-desktop services are available, and `list_apps` includes a GUI app you recognize. An
-empty list is not a successful desktop check: open Calculator in that session
-and retry. Resolve permission or display errors before connecting the agent.
-
-## 3. Connect your agent
-
-Choose one integration for your agent. A skill teaches the agent to use the
-Cua Driver CLI; MCP registration exposes Cua Driver as a tool server.
-`mcp-config` prints the registration command, which you must run, and installs
-the skill for that agent (add `--no-skills` to skip it). Use the output from your
-machine, not the illustrative paths below.
-
-<Tabs items={['Claude Code', 'Codex', 'Prime Agent', 'OpenClaw', 'Hermes']}>
- <Tab value="Claude Code">
- Install the Cua Driver skill for Claude Code:
-
- ```bash test="cli-shape" id="cua-driver-skills-install"
- cua-driver skills install
- cua-driver skills status
- ```
-
- Confirm that the status includes a Claude Code skill link, then start a
- fresh Claude Code session. If the link is missing, follow
- [Install the agent skill](/cua-driver/guides/connect-your-agent#install-the-agent-skill).
-
- Prefer plain MCP instead of the skill? Print the Claude Code registration command:
-
- ```bash test="cli-shape" id="cua-driver-mcp-config-claude"
- cua-driver mcp-config --client claude
- ```
-
- It prints a command you run to register the server (paths will be specific to your install):
-
- ```bash output
- claude mcp add-json --scope user cua-computer-use '{"args":["mcp"],"command":"/Users/you/.local/bin/cua-driver"}'
- ```
- </Tab>
- <Tab value="Codex">
- Print the Codex registration command:
-
- ```bash test="cli-shape" id="cua-driver-mcp-config-codex"
- cua-driver mcp-config --client codex
- ```
-
- It prints a command you run to register the server. The emitted command uses the absolute installed binary path:
-
- ```bash output
- codex mcp add cua-driver -- /Users/you/.local/bin/cua-driver mcp
- ```
-
- Run `codex mcp list` to confirm the `cua-driver` registration. Start a fresh
- Codex session and use `/mcp` to check that the server is active. See the
- [official Codex MCP instructions](https://learn.chatgpt.com/docs/extend/mcp).
- </Tab>
- <Tab value="Prime Agent">
- Install the Cua Driver skill pack. Prime Agent discovers it from its native
- skill directory and calls Cua Driver from the persistent IPython environment;
- no MCP registration is required.
-
- ```bash test="cli-shape" id="cua-driver-skills-install-2"
- cua-driver skills install
- cua-driver skills status
- ```
-
- Run `/reload` in Prime Agent or start a new session after installation so
- the skill appears. Use `/skill:cua-driver` to load it explicitly.
- </Tab>
- <Tab value="OpenClaw">
- Print the OpenClaw registration command:
-
- ```bash test="cli-shape" id="cua-driver-mcp-config-openclaw"
- cua-driver mcp-config --client openclaw
- ```
-
- It prints a command you run to register the server, using the absolute installed binary path:
-
- ```bash output
- openclaw mcp set cua-driver '{"command":"/Users/you/.local/bin/cua-driver","args":["mcp"]}'
- ```
-
- <Callout type="warn">
- On macOS, a server spawned this way by the gateway does not inherit OpenClaw.app's own Accessibility and Screen Recording grants. To embed Cua Driver in the host app instead, so the host owns the grants, see [Expose MCP from a desktop app](/cua-driver/guides/use-the-sdk#expose-mcp-from-a-desktop-app).
- </Callout>
- </Tab>
- <Tab value="Hermes">
- Hermes includes a built-in `computer_use` toolset. Enable it for the CLI
- instead of adding a second raw MCP server, then start a chat with it:
-
- ```bash skip="third-party-cli"
- hermes tools enable computer_use --platform cli
- hermes -t computer_use chat
- ```
-
- If it cannot reach Cua Driver, repair it with `hermes computer-use install`
- and check with `hermes computer-use doctor`.
- </Tab>
-</Tabs>
-
-Using Cursor, Antigravity, OpenCode, Pi, a local model or another harness? See [Connect your agent](/cua-driver/guides/connect-your-agent).
-
-## 4. Ask your agent
-
-Use the prompt that matches the setup you chose. Ask the agent to read the
-calculator's displayed result after acting, so it verifies the GUI instead of
-answering the arithmetic from memory.
-
-<Tabs items={['Claude Code', 'Codex', 'Prime Agent', 'OpenClaw', 'Hermes']}>
- <Tab value="Claude Code">
- ```text output
- Using the Cua Driver skill, open the installed calculator app,
- compute 6 × 7, and read the displayed result back from a fresh snapshot.
- ```
-
- If you chose MCP registration instead, replace “Cua Driver skill” with
- “cua-computer-use MCP server.”
- </Tab>
- <Tab value="Codex">
- ```text output
- Using the cua-driver MCP server, open the installed calculator app,
- compute 6 × 7, and read the displayed result back from a fresh snapshot.
- ```
- </Tab>
- <Tab value="Prime Agent">
- ```text output
- Using the Cua Driver skill, open the installed calculator app,
- compute 6 × 7, and read the displayed result back from a fresh snapshot.
- ```
- </Tab>
- <Tab value="OpenClaw">
- ```text output
- Using the cua-driver MCP server, open the installed calculator app,
- compute 6 × 7, and read the displayed result back from a fresh snapshot.
- ```
- </Tab>
- <Tab value="Hermes">
- ```text output
- Using the computer_use toolset, open the installed calculator app,
- compute 6 × 7, and read the displayed result back from a fresh snapshot.
- ```
- </Tab>
-</Tabs>
-
-The app name, controls, and action sequence vary by platform and calculator.
-The agent must discover them from fresh state; element indices from another
-run are not reusable. If no calculator is installed, install one through your
-platform's normal app or package manager, then repeat the prompt.
-
-To understand how the driver observes and acts, see [How Cua Driver works](/cua-driver/concepts/how-cua-driver-works).
-
-## 5. Confirm what happened
-
-Confirm that the calculator displays **42** and that the agent's final
-observation reports that value. A correct answer alone does not prove that the
-agent operated the app.
-
-Cua Driver uses best-effort background delivery. Observe whether your active
-app, keyboard focus, and real pointer stay unchanged during the interaction;
-do not infer this from the answer. The visible agent cursor is a separate
-overlay. macOS and Windows accessibility actions can operate supported
-controls in the background, but some apps require explicit foreground
-delivery. Linux AT-SPI actions and X11 routes can also work in the background;
-native Wayland depends on compositor support and has raw-keyboard limits.
-Launching an app can itself raise a window. See
-[Platform mechanisms](/cua-driver/concepts/how-cua-driver-works#platform-mechanisms)
-for these differences and [Known limits](/cua-driver/guides/troubleshoot#known-limits)
-for apps that need the foreground.
-
-## Clean up
-
-Stop the daemon when you are done:
-
-```bash test="cli-shape" id="cua-driver-stop"
-cua-driver stop
-```
-
-## What you did
-
-You installed Cua Driver, checked its daemon and desktop access, connected your
-agent, and verified a result computed inside a desktop app.
-
-## Try a real workflow
-
-Use a bounded task to connect app actions with a saved result. These macOS
-examples include edited recordings, fictional starter files, and output checks:
-
-- [Build and inspect a map](/cua-driver/guides/recipes#build-and-inspect-a-map):
- load spatial data, prepare a print layout, and inspect the exported PDF.
-- [Redact and annotate a PDF](/cua-driver/guides/recipes#redact-and-annotate-a-pdf):
- prepare a review copy in Preview and check the saved redactions.
-- [Prepare an exhibition panel](/cua-driver/guides/recipes#prepare-an-exhibition-panel):
- crop an archive image and edit a panel across GIMP and Inkscape.
-
-These runs include foreground desktop input. Use a separate desktop, a
-[sandbox](/cua-driver/guides/test-in-a-sandbox) or a
-[VM](/cua-driver/guides/vms-and-remote) when you need to keep working during
-the task.
-
-## Next steps
-
-- [Connect your agent](/cua-driver/guides/connect-your-agent): every supported harness, agent SDKs and local models.
-- [Use the SDK](/cua-driver/guides/use-the-sdk): drive apps from Python or TypeScript and verify each action.
-- [Keep Cua Driver running and updated](/cua-driver/guides/operate): autostart, permission modes and updates.
-- [How Cua Driver works](/cua-driver/concepts/how-cua-driver-works): how it avoids focus and cursor disruption when the target app supports it.
diff --git a/docs/content/docs/start-here/meta.json b/docs/content/docs/start-here/meta.json
deleted file mode 100644
index 2bbc2f5773..0000000000
--- a/docs/content/docs/start-here/meta.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
- "title": "Start here",
- "icon": "GraduationCap",
- "pages": [
- "sandbox-images",
- "drive-your-first-app",
- "create-a-local-macos-sandbox",
- "run-in-github-actions",
- "your-first-cua-bench-task"
- ]
-}
diff --git a/docs/content/docs/start-here/run-in-github-actions.mdx b/docs/content/docs/start-here/run-in-github-actions.mdx
deleted file mode 100644
index f66e1bef21..0000000000
--- a/docs/content/docs/start-here/run-in-github-actions.mdx
+++ /dev/null
@@ -1,40 +0,0 @@
----
-title: Run a sandbox in GitHub Actions
-description: Start a Linux sandbox in a GitHub Actions job with the cua-sandbox action, run a command in it, keep a screenshot, and delete it.
----
-
-The `cua-sandbox` action creates the sandbox, runs your steps, uploads logs,
-the doctor report and `screenshot.png` as an artifact, and always deletes the
-sandbox, even on cancel.
-
-```yaml title=".github/workflows/e2e.yml" test="config" id="gha-linux-sandbox"
-jobs:
- e2e:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
- - uses: dtolnay/[email protected]
- - uses: trycua/cua/.github/actions/cua-sandbox@main
- with:
- image: linux
- run: |
- cua sb exec "$CUA_SANDBOX" uname -a
- cua sb screenshot "$CUA_SANDBOX" -o "$CUA_SANDBOX_ARTIFACTS/desktop.png"
-```
-
-- `run` runs on the runner; `guest-run` runs inside the sandbox.
-- `cua-version` defaults to `source` (builds the CLI from the action's ref, hence the Rust step).
-- No Docker or KVM on the runner: use a runner that has Docker (GitHub-hosted Linux runners do), or a [contrib provider](/cua-sdk/guides/contrib-providers) such as `on: e2b`. Cua Cloud (`on: cloud`) has ended.
-
-## The same steps locally
-
-```bash test="cli-shape" id="gha-local-steps"
-cua sb create linux --name ci --wait desktop
-cua sb exec ci uname -a
-cua sb screenshot ci -o desktop.png
-cua sb rm ci --force
-```
-
-## Next
-
-- [Test in CI with Cua sandboxes](/cua-sdk/guides/test-in-ci): every input and output, injecting the build under test, and `cua doctor` expectations.
diff --git a/docs/content/docs/start-here/sandbox-images.mdx b/docs/content/docs/start-here/sandbox-images.mdx
deleted file mode 100644
index 42f493129a..0000000000
--- a/docs/content/docs/start-here/sandbox-images.mdx
+++ /dev/null
@@ -1,45 +0,0 @@
----
-title: Sandbox images
-description: The desktop and benchmark images Cua publishes.
----
-
-Cua publishes these images on `ghcr.io/trycua`. The Linux, Windows, benchmark and macOS 26 images include [cua-spacesd](/spaces) and [cua-driver](/cua-driver), making them ready for agentic workloads; macOS 15 runs the legacy guest agent for now. Windows, macOS and tags ending in `-disk` are VMs; the rest are containers. [Image catalog details](/cua-sdk/reference/os-image-catalog).
-
-{/* GENERATED:catalog-image-list:start */}
-### Linux
-
-- `ghcr.io/trycua/linux:24.04`
-- `ghcr.io/trycua/linux:24.04-disk` (VM)
-- `ghcr.io/trycua/linux:24.04-slim`
-- `ghcr.io/trycua/linux:24.04-slim-disk` (VM)
-- `ghcr.io/trycua/omarchy:edge`
-- `ghcr.io/trycua/omarchy:edge-disk` (VM)
-
-### Windows
-
-- `ghcr.io/trycua/windows:2022`
-
-### macOS
-
-- `ghcr.io/trycua/macos:26` (Tahoe)
-- `ghcr.io/trycua/macos:26-slim` (Tahoe 26 slim)
-- `ghcr.io/trycua/macos:15` (Sequoia)
-
-### Adapter benchmark images
-
-- `ghcr.io/trycua/bench-web:1.0` (run [MiniWoB++](/cua-bench/guides/adapter-benchmarks#miniwob), [WebVoyager](/cua-bench/guides/adapter-benchmarks#webvoyager), [Online-Mind2Web](/cua-bench/guides/adapter-benchmarks#online-mind2web), [WebGym](/cua-bench/guides/adapter-benchmarks#webgym))
-- `ghcr.io/trycua/bench-web:1.0-disk` (VM)
-- `ghcr.io/trycua/bench-osworld:verified` (run [OSWorld-Verified](/cua-bench/guides/adapter-benchmarks#osworld-verified))
-- `ghcr.io/trycua/bench-osworld:verified-disk` (VM)
-{/* GENERATED:catalog-image-list:end */}
-
-## Run one
-
-```bash skip="host-install"
-curl -fsSL https://cua.ai/install.sh | sh
-```
-
-```bash test="cli-shape" id="cua-sb-create-desk"
-cua sb create linux --name desk
-cua sb view desk
-```
diff --git a/docs/content/docs/start-here/your-first-cua-bench-task.mdx b/docs/content/docs/start-here/your-first-cua-bench-task.mdx
deleted file mode 100644
index a33aa34613..0000000000
--- a/docs/content/docs/start-here/your-first-cua-bench-task.mdx
+++ /dev/null
@@ -1,147 +0,0 @@
----
-title: 'Build your first Cua Bench task'
-description: 'Create a Cua Bench task, score it with its oracle in a local Linux sandbox, solve it yourself, then hand it to an agent.'
----
-
-In this walkthrough you create a small computer-use task, check it with its
-built-in oracle solution in a Linux sandbox on your machine, solve it yourself
-in the same sandbox, and then hand it to an agent. You need no API key until
-the agent step.
-
-## Before you start
-
-- Python 3.12 or 3.13 and [uv](https://docs.astral.sh/uv/).
-- A local runtime for the `ghcr.io/trycua/linux:24.04` sandbox (Docker, and
- gVisor when installed). Check it with the `cua` CLI:
-
-```bash test="cli-shape" id="cua-runtime-doctor"
-cua runtime doctor
-```
-
-## 1. Install Cua Bench
-
-```bash skip="host-install"
-uv tool install cua-bench
-```
-
-This puts the `cb` command on your `PATH`. `cb --help` lists its command
-groups, including `run`, `interact`, `task` and `trace`.
-
-## 2. Create a task
-
-Create a working directory and scaffold a task in it:
-
-```bash skip="no-runner"
-mkdir cua-bench-tutorial && cd cua-bench-tutorial
-cb task create first-task
-```
-
-Answer the prompts, for example:
-
-```text output
-Author name: Your name
-Author email: [email protected]
-License [MIT]:
-Task description: Write a word to a file
-Task difficulty (easy|medium|hard) [easy]:
-Task category (e.g., grounding, software-engineering) [grounding]:
-Tags (comma-separated): starter,linux
-```
-
-The scaffold is two files:
-
-```text output
-first-task/
-├── main.py
-└── pyproject.toml
-```
-
-`main.py` defines the whole task lifecycle. The starter defines two variants,
-each asking for one word in `/tmp/answer.txt`, and four functions:
-
-```python skip="pseudo"
[email protected]_config(split="train")
-def load(): ... # the variants and the machine they run on (native Linux)
-
[email protected]_task(split="train")
-async def start(task_cfg, session): ... # remove any old answer
-
[email protected]_task(split="train")
-async def solve(task_cfg, session): ... # the oracle: write the right word
-
[email protected]_task(split="train")
-async def evaluate(task_cfg, session): ... # 1.0 if the file holds the word
-```
-
-## 3. Inspect the task
-
-```bash skip="no-runner"
-cb task info first-task
-```
-
-![cb task info: a native Linux task with 2 variants and setup, solve and evaluate](/img/cua-bench/cb-task-info.png)
-
-The provider is `native`: a real OS in a container or VM. The check marks
-confirm that Cua Bench found the setup, solve and evaluate functions.
-
-## 4. Run the oracle
-
-```bash skip="no-runner"
-cb run first-task --variant-id 0 --oracle
-```
-
-`cb run` starts a Linux sandbox, runs the setup, the oracle solution and the
-evaluator, and releases the sandbox. It reports `reward=1`. A failing oracle
-means the task is broken, not the agent.
-
-## 5. Solve it yourself
-
-Open the same variant without the oracle:
-
-```bash skip="no-runner"
-cb interact first-task --variant-id 0
-```
-
-`cb interact` sets the task up, prints the sandbox's `Display:` link and opens
-the viewer in your browser. Open a terminal in the sandbox desktop and write
-the answer:
-
-![The task sandbox mid-task: a terminal writing hello to /tmp/answer.txt](/img/cua-bench/cb-interact-desktop.png)
-
-Return to your terminal and press Enter. Cua Bench evaluates the sandbox and
-releases it:
-
-![cb interact: setup complete, evaluation result 1.0, sandbox released](/img/cua-bench/cb-interact.png)
-
-The evaluator that scored the oracle also scored your attempt.
-
-## 6. Hand it to an agent
-
-```bash test="cli-shape" id="first-task-agent"
-cb run first-task --agent cua-agent --model anthropic/claude-sonnet-4-20250514
-```
-
-`--on local` (the default) runs tasks in sandboxes on this machine; `--kind`,
-`--runtime`, `--image`, `--cpu` and `--memory` shape them.
-
-## Clean up
-
-```bash skip="destructive"
-cd .. && rm -rf cua-bench-tutorial
-```
-
-Run results stay in `~/.local/share/cua-bench/runs`. Keep fewer with
-`cb prune --runs --keep N`.
-
-## What you built
-
-You created a task with variants, a setup function, an oracle solution and an
-evaluator, and used the same evaluator to score the oracle, your own attempt
-and an agent.
-
-## Next steps
-
-- [Write a task](/cua-bench/guides/write-a-task): richer setup, checks and HTML task windows.
-- [Run a benchmark](/cua-bench/guides/benchmarks): OSWorld-Verified, MiniWoB++, WebVoyager and more.
-- [Sandbox images](/start-here/sandbox-images): the benchmark images and how to start them.
-- [CLI reference](/cua-bench/reference/cli)
diff --git a/docs/public/media/workflow-demos/highlights-poster.jpg b/docs/public/media/workflow-demos/highlights-poster.jpg
index 09b899c37f..1bbea08510 100644
Binary files a/docs/public/media/workflow-demos/highlights-poster.jpg and b/docs/public/media/workflow-demos/highlights-poster.jpg differ
diff --git a/docs/public/scripts/openai-agents/run_openai_agents.py b/docs/public/scripts/openai-agents/run_openai_agents.py
index 6ce18c7da7..35378abc92 100644
--- a/docs/public/scripts/openai-agents/run_openai_agents.py
+++ b/docs/public/scripts/openai-agents/run_openai_agents.py
@@ -10,7 +10,8 @@
The sandbox runs on this machine by default. Set CUA_ON to "aws", "gcp" or
"modal" to run it in your own cloud account instead (connect it first with
-`cua cloud connect`; see https://cua.ai/docs/cua-sdk/guides/your-cloud).
+`cua cloud connect`; see
+https://cua.ai/docs/cua-sdk/guides/local-runtimes#your-own-cloud).
The application API key remains on the controller. Only the restricted
environment key is copied into the sandbox, and its temporary file is
diff --git a/docs/scripts/product-structure.test.ts b/docs/scripts/product-structure.test.ts
index 28624d8b38..0f5c265e36 100644
--- a/docs/scripts/product-structure.test.ts
+++ b/docs/scripts/product-structure.test.ts
@@ -11,16 +11,27 @@ const docs = path.resolve(__dirname, '..');
const repo = path.resolve(docs, '..');
const content = path.join(docs, 'content/docs');
-// In sidebar order: Cua Spaces first, then the products it builds on, then the
-// developer tools (SDK, CLI, Bench).
+// In sidebar order: Cua Spaces (the product), Cua Driver, then one More tools
+// group (the CLI, the SDK, Lume and Cua Bench).
const PRODUCTS: Array<[string, string]> = [
['spaces', 'Cua Spaces'],
['cua-driver', 'Cua Driver'],
- ['lume', 'Lume'],
- ['cua-sdk', 'Cua SDK'],
['cua-cli', 'Cua CLI'],
+ ['cua-sdk', 'Cua SDK'],
+ ['lume', 'Lume'],
['cua-bench', 'Cua Bench'],
];
+// The root meta.json: the products in order, with the More tools separator.
+const ROOT_ORDER = [
+ 'index',
+ 'spaces',
+ 'cua-driver',
+ '---More tools---',
+ 'cua-cli',
+ 'cua-sdk',
+ 'lume',
+ 'cua-bench',
+];
// Sections in their only allowed order; `examples` and `concepts` are optional.
const SECTIONS = ['index', 'quickstart', 'guides', 'examples', 'concepts', 'reference'];
const OPTIONAL = new Set(['examples', 'concepts']);
@@ -30,9 +41,6 @@ const SECTION_TITLES: Record<string, string> = {
concepts: 'Concepts',
reference: 'Reference',
};
-// The one non-product section: end-to-end walkthroughs for the Cua Driver, Lume,
-// SDK and Bench products, listed first. Spaces walkthroughs live in Spaces.
-const START_HERE: [string, string] = ['start-here', 'Start here'];
// The docs home is the designed landing; its frontmatter feeds it.
// Each example: a title, a page, alt text and its media (an image, or a
// video with its poster); the description is optional.
@@ -68,12 +76,12 @@ function slugs(): Set<string> {
);
}
-test('the root lists Start here, then the products in order', () => {
- assert.deepEqual(meta('').pages, [
- 'index',
- START_HERE[0],
- ...PRODUCTS.map(([dir]) => dir),
- ]);
+test('the root lists the products in order, with the CLI, SDK, Lume and Bench under More tools', () => {
+ assert.deepEqual(meta('').pages, ROOT_ORDER);
+ assert.deepEqual(
+ ROOT_ORDER.filter((page) => page !== 'index' && !page.startsWith('---')),
+ PRODUCTS.map(([dir]) => dir)
+ );
const stray = readdirSync(content).filter(
(name) =>
name.endsWith('.mdx') && !ROOT_PAGES.has(name)
@@ -82,30 +90,7 @@ test('the root lists Start here, then the products in order', () => {
const dirs = readdirSync(content).filter((name) =>
statSync(path.join(content, name)).isDirectory()
);
- assert.deepEqual(
- dirs.sort(),
- [START_HERE[0], ...PRODUCTS.map(([dir]) => dir)].sort()
- );
-});
-
-test('Start here is a flat list of walkthroughs', () => {
- const [dir, title] = START_HERE;
- const m = meta(dir);
- assert.equal(m.title, title);
- assert.notEqual(m.root, true, `${dir} lives in the main sidebar, not its own tab`);
- const pages = m.pages ?? [];
- // Its Overview is the docs home (index.mdx), so it has no index of its own.
- assert.ok(!pages.includes('index'), `${dir} has no index: its Overview is the docs home`);
- assert.equal(pages[0], 'sandbox-images', `${dir}/meta.json opens with Sandbox images`);
- const files = readdirSync(path.join(content, dir)).filter((name) => name !== 'meta.json');
- for (const name of files) {
- assert.ok(name.endsWith('.mdx'), `${dir}/${name}: Start here has no subfolders`);
- }
- assert.deepEqual(
- files.map((name) => name.replace(/\.mdx$/, '')).sort(),
- [...pages].sort(),
- `${dir}/meta.json lists exactly its pages`
- );
+ assert.deepEqual(dirs.sort(), PRODUCTS.map(([dir]) => dir).sort());
});
test('the docs home features its examples with real pages and media', () => {
diff --git a/docs/scripts/sandbox-navigation.test.ts b/docs/scripts/sandbox-navigation.test.ts
index ce0ace8dc2..2000597190 100644
--- a/docs/scripts/sandbox-navigation.test.ts
+++ b/docs/scripts/sandbox-navigation.test.ts
@@ -29,25 +29,15 @@ test('the Cua SDK has its task guides and one concept page', async () => {
assert.deepEqual(guides.pages, [
'images',
'services',
- 'secrets',
- 'sidecars',
'lifecycle',
'desktop',
- 'thumbnails',
'spacesd',
'local-runtimes',
- 'disk-usage',
- 'cua-cloud-ended',
- 'your-cloud',
- 'your-cloud-resources',
- 'contrib-providers',
'test-in-ci',
'run-a-coding-agent',
- 'coding-agent-options',
- 'browse-the-web',
'agent-frameworks',
'omarchy',
- 'migrate-from-deprecated-packages',
+ 'cua-cloud-ended',
]);
assert.deepEqual((await metadata('cua-sdk/concepts')).pages, [
'how-sandboxes-work',
@@ -110,8 +100,8 @@ test('removed Sandbox and Fleet pages redirect to the page that replaced them',
'fleets/concepts/pools-claims-and-guest-services': 'cua-sdk/guides/cua-cloud-ended',
'fleets/guides/claim-a-sandbox': 'cua-sdk/guides/cua-cloud-ended',
'fleets/guides/images': 'cua-sdk/guides/images',
- 'fleets/guides/sidecars': 'cua-sdk/guides/sidecars',
- 'fleets/guides/claim-secrets': 'cua-sdk/guides/secrets',
+ 'fleets/guides/sidecars': 'cua-sdk/guides/services',
+ 'fleets/guides/claim-secrets': 'cua-sdk/guides/services',
};
for (const [from, to] of Object.entries(expected)) {
assert.equal(redirects[from], to, from);
diff --git a/docs/scripts/tests/test_sandbox_secret_example.py b/docs/scripts/tests/test_sandbox_secret_example.py
index e0f20b9b26..dc372cfdd1 100644
--- a/docs/scripts/tests/test_sandbox_secret_example.py
+++ b/docs/scripts/tests/test_sandbox_secret_example.py
@@ -23,13 +23,15 @@ from unittest.mock import patch
from cua_sandbox.interfaces.shell import Shell
-PAGE = Path(__file__).resolve().parents[2] / "content/docs/cua-sdk/guides/secrets.mdx"
+PAGE = Path(__file__).resolve().parents[2] / "content/docs/cua-sdk/guides/services.mdx"
SANDBOX_PROJECT = (
Path(__file__).resolve().parents[3] / "libs/python/cua-sandbox/pyproject.toml"
)
with SANDBOX_PROJECT.open("rb") as stream:
SANDBOX_VERSION = tomllib.load(stream)["project"]["version"]
-BLOCKS = re.findall(r"```python[^\n]*\n(.*?)\n```", PAGE.read_text(), re.DOTALL)
+# The secrets examples are the "Secrets" section of the services page.
+SECRETS = re.search(r"^## Secrets\n(.*?)(?=^## |\Z)", PAGE.read_text(), re.DOTALL | re.MULTILINE).group(1)
+BLOCKS = re.findall(r"```python[^\n]*\n(.*?)\n```", SECRETS, re.DOTALL)
SYNTHETIC = "synthetic space 'quote' \"double\" $HOME $(exit 91) `exit 92`\nEOF\nlast\n"
diff --git a/docs/scripts/tests/test_unified_sandbox_docs.py b/docs/scripts/tests/test_unified_sandbox_docs.py
index 6e0c6e0894..6b1cf5e7b6 100644
--- a/docs/scripts/tests/test_unified_sandbox_docs.py
+++ b/docs/scripts/tests/test_unified_sandbox_docs.py
@@ -13,12 +13,12 @@ UNIFIED = (
"cua-sdk/index",
"cua-sdk/quickstart",
"cua-sdk/guides/services",
- "cua-sdk/guides/sidecars",
"cua-sdk/guides/images",
"cua-sdk/guides/lifecycle",
)
-# Hand-written Cua SDK pages stay short.
-MAX_WORDS = 1000
+# Hand-written Cua SDK pages stay short. A guide that folds in related tasks
+# (services with sidecars and secrets, where sandboxes run) gets more room.
+MAX_WORDS = 3000
def page(slug: str) -> str:
diff --git a/libs/cua/crates/cua-contrib/matrix/contrib_matrix.py b/libs/cua/crates/cua-contrib/matrix/contrib_matrix.py
index aee11c0aeb..f85451b86d 100644
--- a/libs/cua/crates/cua-contrib/matrix/contrib_matrix.py
+++ b/libs/cua/crates/cua-contrib/matrix/contrib_matrix.py
@@ -42,7 +42,7 @@ from pathlib import Path
HERE = Path(__file__).resolve().parent
LEDGER = HERE / "ledger"
REPO = HERE.parents[4]
-PAGE = REPO / "docs" / "content" / "docs" / "cua-sdk" / "guides" / "contrib-providers.mdx"
+PAGE = REPO / "docs" / "content" / "docs" / "cua-sdk" / "guides" / "local-runtimes.mdx"
REGION = "contrib-matrix"
#: Providers this cua implements, in display order, with the kinds each
diff --git a/libs/cua/crates/cua-spaces-contract/src/inputs.rs b/libs/cua/crates/cua-spaces-contract/src/inputs.rs
index 486df7ee28..0cf395228b 100644
--- a/libs/cua/crates/cua-spaces-contract/src/inputs.rs
+++ b/libs/cua/crates/cua-spaces-contract/src/inputs.rs
@@ -1042,8 +1042,9 @@ pub struct NoArgs {}
pub struct ShareSpace {
/// Space id or name.
pub space: SpaceArg,
- /// Who: an email address (verified by cua.ai) or an account id. Teams
- /// are not accepted: share with each member.
+ /// Who: an email address (verified by cua.ai) or an account id, or
+ /// `team:<id>` for a whole team. A team always gets `editor` and needs
+ /// the Teams plan; the sharer is a team owner or admin who owns the Space.
pub who: String,
/// `viewer` (presence with their own cursor and a view-only stream) or
/// `editor` (full use; their input is a human session). Default
diff --git a/libs/cua/crates/cua-spaces-contract/src/lib.rs b/libs/cua/crates/cua-spaces-contract/src/lib.rs
index f4975d6d5e..ef3818dd3f 100644
--- a/libs/cua/crates/cua-spaces-contract/src/lib.rs
+++ b/libs/cua/crates/cua-spaces-contract/src/lib.rs
@@ -625,7 +625,7 @@ const DRIVE_INSTRUCTIONS: &str = "Cua Volume is one versioned drive per account,
const SHARES_RESULT: &str = "JSON: `space`, `machine` (the relay machine it is shared as; empty when not shared), `invitee_space` (what the people it is shared with open: `relay:<machine>`), `url`, `online` and `shares` (each `who`, `role`: viewer or editor, and `connected`).";
-const SHARE_INSTRUCTIONS: &str = "Shares the Space through the cua.ai relay with one account, by verified email or account id; the same allowlist and device enrollment `cua host share` uses. A viewer joins presence with their own named cursor and watches a view-only stream: the Space's driver refuses their input, shell, files and MCP. An editor gets full use, and their input is a human session. Sharing again changes the role. A host (`relay:<id>`) is shared directly; any other Space (local, cloud, or added by address) is attached to the relay on its first share: its own driver dials out, so it needs no inbound port. Invitees open `invitee_space`.";
+const SHARE_INSTRUCTIONS: &str = "Shares the Space through the cua.ai relay with one account, by verified email or account id, or with a whole team as `team:<id>` (always as an editor; Teams plan); the same allowlist and device enrollment `cua host share` uses. A viewer joins presence with their own named cursor and watches a view-only stream: the Space's driver refuses their input, shell, files and MCP. An editor gets full use, and their input is a human session. Sharing again changes the role. A host (`relay:<id>`) is shared directly; any other Space (local, cloud, or added by address) is attached to the relay on its first share: its own driver dials out, so it needs no inbound port. Invitees open `invitee_space`.";
/// The Spaces tools, in manifest order.
pub fn tools() -> Vec<Tool> {
diff --git a/libs/cua/spaces-contract/manifest.json b/libs/cua/spaces-contract/manifest.json
index a54347e7c5..f5f20997c8 100644
--- a/libs/cua/spaces-contract/manifest.json
+++ b/libs/cua/spaces-contract/manifest.json
@@ -4644,7 +4644,7 @@
"name": "share_space",
"category": "sharing",
"description": "Let another cua.ai account watch or edit a Space.",
- "instructions": "Shares the Space through the cua.ai relay with one account, by verified email or account id; the same allowlist and device enrollment `cua host share` uses. A viewer joins presence with their own named cursor and watches a view-only stream: the Space's driver refuses their input, shell, files and MCP. An editor gets full use, and their input is a human session. Sharing again changes the role. A host (`relay:<id>`) is shared directly; any other Space (local, cloud, or added by address) is attached to the relay on its first share: its own driver dials out, so it needs no inbound port. Invitees open `invitee_space`.",
+ "instructions": "Shares the Space through the cua.ai relay with one account, by verified email or account id, or with a whole team as `team:<id>` (always as an editor; Teams plan); the same allowlist and device enrollment `cua host share` uses. A viewer joins presence with their own named cursor and watches a view-only stream: the Space's driver refuses their input, shell, files and MCP. An editor gets full use, and their input is a human session. Sharing again changes the role. A host (`relay:<id>`) is shared directly; any other Space (local, cloud, or added by address) is attached to the relay on its first share: its own driver dials out, so it needs no inbound port. Invitees open `invitee_space`.",
"platforms": [
"macos",
"windows",
@@ -4692,7 +4692,7 @@
"type": "string"
},
"who": {
- "description": "Who: an email address (verified by cua.ai) or an account id. Teams\nare not accepted: share with each member.",
+ "description": "Who: an email address (verified by cua.ai) or an account id, or\n`team:<id>` for a whole team. A team always gets `editor` and needs\nthe Teams plan; the sharer is a team owner or admin who owns the Space.",
"type": "string"
}
},
diff --git a/libs/cuabot/README.md b/libs/cuabot/README.md
index 8cf4e53b29..af07d19284 100644
--- a/libs/cuabot/README.md
+++ b/libs/cuabot/README.md
@@ -13,7 +13,7 @@
> rm -rf ~/.cuabot
> ```
>
-> There will be no fixes or new releases. To give a coding agent a computer, use [Cua Driver](https://cua.ai/docs/cua-driver/guides/connect-your-agent) over MCP, or a sandbox from the [`cua` CLI](https://cua.ai/docs/cua-sdk/quickstart) or [Cua Spaces](https://cua.ai/docs/spaces/quickstart). See [Migrate from deprecated packages](https://cua.ai/docs/cua-sdk/guides/migrate-from-deprecated-packages).
+> There will be no fixes or new releases. To give a coding agent a computer, use [Cua Driver](https://cua.ai/docs/cua-driver/guides/connect-your-agent) over MCP, or a sandbox from the [`cua` CLI](https://cua.ai/docs/cua-sdk/quickstart) or [Cua Spaces](https://cua.ai/docs/spaces/quickstart). See [Migrate from deprecated packages](https://cua.ai/docs/cua-sdk/guides/cua-cloud-ended#deprecated-packages).
Co-op computer-use for any agent.
diff --git a/libs/python/agent/README.md b/libs/python/agent/README.md
index 6ec5f19159..1b96dcff18 100644
--- a/libs/python/agent/README.md
+++ b/libs/python/agent/README.md
@@ -1,7 +1,7 @@
# Cua Agent
> [!WARNING]
-> **Deprecated:** `cua-agent` is no longer maintained by Cua and will not receive updates or fixes. For desktop control, connect your coding agent to [Cua Driver](https://cua.ai/docs/cua-driver/guides/connect-your-agent) over MCP. For sandboxes, use the [`cua` SDK and CLI](https://cua.ai/docs/cua-sdk/quickstart) (`pip install cua`) and [run a coding agent in a sandbox](https://cua.ai/docs/cua-sdk/guides/run-a-coding-agent). See [Migrate from deprecated packages](https://cua.ai/docs/cua-sdk/guides/migrate-from-deprecated-packages). Existing releases stay on PyPI, so current installs keep working.
+> **Deprecated:** `cua-agent` is no longer maintained by Cua and will not receive updates or fixes. For desktop control, connect your coding agent to [Cua Driver](https://cua.ai/docs/cua-driver/guides/connect-your-agent) over MCP. For sandboxes, use the [`cua` SDK and CLI](https://cua.ai/docs/cua-sdk/quickstart) (`pip install cua`) and [run a coding agent in a sandbox](https://cua.ai/docs/cua-sdk/guides/run-a-coding-agent). See [Migrate from deprecated packages](https://cua.ai/docs/cua-sdk/guides/cua-cloud-ended#deprecated-packages). Existing releases stay on PyPI, so current installs keep working.
Computer-Use framework with liteLLM integration for running agentic workflows on macOS, Windows, and Linux sandboxes.
diff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.md
index 07472d90db..983251e59c 100644
--- a/libs/python/cua-sandbox/README.md
+++ b/libs/python/cua-sandbox/README.md
@@ -171,7 +171,7 @@ Sidecars are addressed by name: the sandbox reaches `db:6379` and a
sidecar reaches the sandbox at `main`. With sidecars, the service names `main`,
`sidecars` and `sc` are reserved. Local sidecars need `runtime="runc"`, and
local VM sandboxes refuse sidecars. See
-[Sidecars](https://cua.ai/docs/cua-sdk/guides/sidecars).
+[Sidecars](https://cua.ai/docs/cua-sdk/guides/services#sidecars).
## Ephemeral sandbox
diff --git a/scripts/docs-generators/config.json b/scripts/docs-generators/config.json
index a244e594e4..5503e65262 100644
--- a/scripts/docs-generators/config.json
+++ b/scripts/docs-generators/config.json
@@ -168,7 +168,7 @@
"libs/images/sandbox-images.json",
"libs/images/bench/*/lock.json",
"docs/content/docs/cua-sdk/quickstart.mdx",
- "docs/content/docs/start-here/sandbox-images.mdx",
+ "docs/content/docs/cua-sdk/guides/images.mdx",
"scripts/docs-generators/sandbox.test.ts",
"scripts/docs-generators/headers/cua-sdk/runtime-support.md",
"scripts/docs-generators/headers/cua-sdk/os-image-catalog.md",
diff --git a/scripts/docs-generators/headers/cua-sdk/runtime-support.md b/scripts/docs-generators/headers/cua-sdk/runtime-support.md
index 5ded71ed9f..807d778c8b 100644
--- a/scripts/docs-generators/headers/cua-sdk/runtime-support.md
+++ b/scripts/docs-generators/headers/cua-sdk/runtime-support.md
@@ -87,7 +87,7 @@ Declaring a service does not install or start it. For an example layout, see the
| Direct `Sandbox.connect(url=...)` | spacesd | spacesd tunnel | No declared services |
| Legacy adapters (Android ADB, OSWorld, Tart, Hyper-V) | Adapter-specific | ADB forwards ports and Android sockets | Adapter-specific |
-For sandboxes in your own cloud, see [Use your own cloud](/cua-sdk/guides/your-cloud)
+For sandboxes in your own cloud, see [Choose where sandboxes run](/cua-sdk/guides/local-runtimes#your-own-cloud)
and [Sandbox interfaces](/cua-sdk/reference/python/interfaces).
## Evidence and limits
diff --git a/scripts/docs-generators/headers/lume/mcp-tools.md b/scripts/docs-generators/headers/lume/mcp-tools.md
index a5e4e04bdf..cb378bc55f 100644
--- a/scripts/docs-generators/headers/lume/mcp-tools.md
+++ b/scripts/docs-generators/headers/lume/mcp-tools.md
@@ -1 +1 @@
-`lume serve --mcp` serves these tools over stdio. See [API and MCP](/lume/guides/api-and-mcp) for client setup.
+`lume serve --mcp` serves these tools over stdio. See [Connect an MCP client](/lume/guides/manage-vms#connect-an-mcp-client) for client setup.
diff --git a/tests/e2e/cua-sdk/python/test_browse.py b/tests/e2e/cua-sdk/python/test_browse.py
index e41ee2b01e..136490c32d 100644
--- a/tests/e2e/cua-sdk/python/test_browse.py
+++ b/tests/e2e/cua-sdk/python/test_browse.py
@@ -1,4 +1,4 @@
-"""Browse the web from an agent with Cua (guide: cua-sdk/guides/browse-the-web).
+"""Browse the web from an agent with Cua (guide: cua-sdk/guides/desktop#give-an-agent-a-browser).
A fresh-agent session driven ONLY through the host `cua mcp` server with the
official MCP Python SDK (tests/e2e/browse/e2e_browse.py), no LLM:
@@ -30,7 +30,7 @@ sys.path.insert(0, str(BROWSE))
mcp = pytest.importorskip("mcp", reason="the MCP Python SDK is not installed (pip install mcp)")
import e2e_browse # noqa: E402
-GUIDE = "cua-sdk/guides/browse-the-web.mdx"
+GUIDE = "cua-sdk/guides/desktop.mdx"
def _cua() -> str:
diff --git a/tests/e2e/cua-sdk/scenarios.json b/tests/e2e/cua-sdk/scenarios.json
index e8ee77178b..3802a40f00 100644
--- a/tests/e2e/cua-sdk/scenarios.json
+++ b/tests/e2e/cua-sdk/scenarios.json
@@ -334,7 +334,7 @@
},
{
"id": "browse-the-web",
- "guide": "cua-sdk/guides/browse-the-web.mdx",
+ "guide": "cua-sdk/guides/desktop.mdx#give-an-agent-a-browser",
"langs": [
"py"
],