Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
docs: lead with local; show direct connect instead of cloud (#4430)
ddupont4aa1164479b9
diff --git a/docs/content/docs/cua-bench/guides/adapter-benchmarks.mdx b/docs/content/docs/cua-bench/guides/adapter-benchmarks.mdxindex 3fa99ba8c6..39df7f59b8 100644--- a/docs/content/docs/cua-bench/guides/adapter-benchmarks.mdx+++ b/docs/content/docs/cua-bench/guides/adapter-benchmarks.mdx@@ -9,7 +9,7 @@ adapters in `libs/cua-bench/tasks/` against converted benchmark images.Every adapter runs with one command: `cb run dataset <tasks> --agent <agent> --model <model>`.Converted images come in two variants, a container (`<ver>`) and a VM disk-(`<ver>-disk`): `--kind container|vm` picks one, `--on cloud` runs it in the Cua cloud.+(`<ver>-disk`): `--kind container|vm` picks one.Both run cua-spacesd, and every result records `image_ref`, `image_variant`,`image_digest` and `arch`.@@ -54,7 +54,7 @@ cua-spacesd added.```bash skip="placeholder"pip install "cua-bench[osworld]"cb run dataset libs/cua-bench/tasks/osworld --agent <agent> --model <model> --kind vm-cb run dataset libs/cua-bench/tasks/osworld --agent <agent> --model <model> --kind container --on cloud+cb run dataset libs/cua-bench/tasks/osworld --agent <agent> --model <model> --kind container```OSWorld's `SetupController` and evaluators run on your machine against the@@ -134,7 +134,7 @@ CUA_BENCH_OM2W_LEVEL=easy cb run dataset libs/cua-bench/tasks/online_mind2web \MIT, data CDLA-Permissive-2.0. Needs guest network and `OPENAI_API_KEY`; scored by an LLM judge. Select with `--max-variants`.```bash skip="placeholder"-cb run dataset libs/cua-bench/tasks/webgym --agent <agent> --model <model> --kind vm --on cloud+cb run dataset libs/cua-bench/tasks/webgym --agent <agent> --model <model> --kind vm````--oracle` runs scripted solutions where a set has them; `--noop` scores andiff --git a/docs/content/docs/cua-bench/guides/benchmarks.mdx b/docs/content/docs/cua-bench/guides/benchmarks.mdxindex 4dbe468f2c..ecd7911aaa 100644--- a/docs/content/docs/cua-bench/guides/benchmarks.mdx+++ b/docs/content/docs/cua-bench/guides/benchmarks.mdx@@ -58,12 +58,7 @@ cb run cua-bench-basic --agent cua-agent --model anthropic/claude-sonnet-4-20250| `--dry-run` | Prints each variant's image, kind and backend; starts nothing. |`--on local` (the default) runs sandboxes on this machine (Docker, gVisor when-installed; check with `cua runtime doctor`). `--on cloud` runs the same-taskset in the Cua cloud after `cb login`:--```bash test="cli-shape" id="bench-registry-cloud"-cb run cua-bench-basic --agent cua-agent --model anthropic/claude-sonnet-4-20250514 -j 16 --on cloud-```+installed; check with `cua runtime doctor`).Agents: `cua-agent` (any model the [Cua agent](/cua-sdk) supports) or your ownwith `--agent-import-path module:Class`. `--model` needs that provider's APIdiff --git a/docs/content/docs/cua-bench/index.mdx b/docs/content/docs/cua-bench/index.mdxindex 850c44a1c8..3b289ed6ef 100644--- a/docs/content/docs/cua-bench/index.mdx+++ b/docs/content/docs/cua-bench/index.mdx@@ -43,7 +43,7 @@ A task module (`main.py`) has four functions:| `@solve_task` | Optional oracle: one known way to succeed. A failing oracle means a broken task, not a bad agent. || `@evaluate_task` | Inspects the final state and returns rewards. It scores an oracle, a human or an agent the same way. |-Tasks run in a real sandbox from the [cua SDK](/cua-sdk): on this machine (`cb run --on local`, the default) or in the Cua cloud (`--on cloud`).+Tasks run in a real sandbox from the [cua SDK](/cua-sdk) on this machine (`cb run --on local`, the default).## Nextdiff --git a/docs/content/docs/cua-bench/quickstart.mdx b/docs/content/docs/cua-bench/quickstart.mdxindex 034cae9bc0..4d56098144 100644--- a/docs/content/docs/cua-bench/quickstart.mdx+++ b/docs/content/docs/cua-bench/quickstart.mdx@@ -48,11 +48,9 @@ Each variant's `result.json`, `run.log` and `trajectory.json` land in```bash test="cli-shape" id="bench-quickstart-agent"cb run cua-bench-basic --agent cua-agent --model anthropic/claude-sonnet-4-20250514 -j 4-cb run cua-bench-basic --agent cua-agent --model anthropic/claude-sonnet-4-20250514 -j 16 --on cloud```-The first runs every task on this machine (`--on local` is the default); the-second runs them in the Cua cloud after `cb login`.+It runs every task on this machine (`--on local` is the default).## Try a task yourselfdiff --git a/docs/content/docs/cua-cli/quickstart.mdx b/docs/content/docs/cua-cli/quickstart.mdxindex ffec66a25c..d02f6ba0e7 100644--- a/docs/content/docs/cua-cli/quickstart.mdx+++ b/docs/content/docs/cua-cli/quickstart.mdx@@ -49,22 +49,11 @@ cua do type "echo hello"cua do key enter```-## The same in the cloud--```bash test="cli-shape" id="cua-quickstart-cloud"-cua auth login-cua sb create linux --on cloud --name dev-cloud-cua sb exec dev-cloud "uname -a"-```--`cua sb ls` lists both, local and cloud.-## Clean up```bash test="cli-shape" id="cua-quickstart-rm"cua sb rm devcua sb rm desk-cua sb rm dev-cloud # releases the cloud sandbox```## Nextdiff --git a/docs/content/docs/cua-sdk/guides/agent-frameworks.mdx b/docs/content/docs/cua-sdk/guides/agent-frameworks.mdxindex 5aa2307a9f..cab8ca137f 100644--- a/docs/content/docs/cua-sdk/guides/agent-frameworks.mdx+++ b/docs/content/docs/cua-sdk/guides/agent-frameworks.mdx@@ -33,15 +33,15 @@ sandbox. Deleting an OpenAI session alone does not release the sandbox.Codex-in-ChatGPT's Computer Use plugin runs only on macOS and Windows, with aneligible, signed-in ChatGPT account. To let it take over a VM instead of yourdesktop, create a Windows sandbox (`Image.from_registry(WINDOWS_IMAGE,-os_type="windows", kind="vm")`, `local=False`) from a disk that runs cua-spacesd,+os_type="windows", kind="vm")`) from a disk that runs cua-spacesd,open it with `cua sb view`, install the ChatGPT desktop app and Codex CLI, andrun `codex plugin add computer-use@openai-bundled`. Sign-in and approvals stayinteractive.## Cursor Cloud Agents-A Cursor self-hosted Team Pool worker runs in a cloud Linux desktop for as-long as your controller holds `Sandbox.ephemeral(Image.linux(), local=False)`.+A Cursor self-hosted Team Pool worker runs in a Linux desktop for as long as+your controller holds `Sandbox.ephemeral(Image.linux())`.The controller installs the Cursor CLI, writes `CURSOR_API_KEY` to amode-`600` file with `sb.files.write_text`, and starts`agent worker --pool <pool> start` in the background. It needs Cursor@@ -56,8 +56,7 @@ OpenClaw's bundled `cua-computer` provider runs Cua Driver in-process, so its`DISPLAY=:1`:```bash test="cli-shape" id="cua-sb-create-openclaw"-cua sb create linux --on cloud \- --name openclaw --cpu 4 --memory 8GB --claim-ttl 2h+cua sb create linux --name openclaw --cpu 4 --memory 8GBcua sb rm openclaw -f```@@ -180,7 +179,7 @@ Build on an x86_64 host with KVM (the cloud runs amd64), push, and run it:cua image build minecraft.json \--base vm:ghcr.io/trycua/linux:24.04-disk \--push ghcr.io/<you>/minecraft-workspace:1-cua sb create ghcr.io/<you>/minecraft-workspace@sha256:<digest> --on cloud --name mc --cpu 4 --memory 8GB+cua sb create ghcr.io/<you>/minecraft-workspace@sha256:<digest> --name mc --cpu 4 --memory 8GBcua sb view mccua sb rm mc -f```diff --git a/docs/content/docs/cua-sdk/guides/browse-the-web.mdx b/docs/content/docs/cua-sdk/guides/browse-the-web.mdxindex 04eb8cf5c1..52f11b66b3 100644--- a/docs/content/docs/cua-sdk/guides/browse-the-web.mdx+++ b/docs/content/docs/cua-sdk/guides/browse-the-web.mdx@@ -44,7 +44,7 @@ cua images ls --browser`sandbox_create` with `browser: true` starts the canonical Linux image(`ghcr.io/trycua/linux:24.04`), launches Chromium with a fresh throwawayprofile inside it, binds the window for the browser tools and, with `url`,-opens a first page. Pass `on: "cloud"` to run it on Cua Fleet. It returns the+opens a first page. It runs on this machine by default. It returns thesandbox `id` and the `session`, `target_id` and `tab_id` every browser calltakes.diff --git a/docs/content/docs/cua-sdk/guides/cloud.mdx b/docs/content/docs/cua-sdk/guides/cloud.mdxindex 52e1ced776..397f1708ad 100644--- a/docs/content/docs/cua-sdk/guides/cloud.mdx+++ b/docs/content/docs/cua-sdk/guides/cloud.mdx@@ -55,7 +55,7 @@ cua sb exec demo -- uname -acua sb rm demo -f```-In code, pass `local=False`, as in the [quickstart](/cua-sdk/quickstart), and+In code, pass `local=False` to the [quickstart](/cua-sdk/quickstart) calls, and`kind=` / `runtime=` as locally (cloud runtimes: `gvisor` for containers,`kubevirt` for VMs). `CloudOptions` tunes the managed capacity:diff --git a/docs/content/docs/cua-sdk/guides/desktop.mdx b/docs/content/docs/cua-sdk/guides/desktop.mdxindex 7d9e09cdbe..4eade03d4b 100644--- a/docs/content/docs/cua-sdk/guides/desktop.mdx+++ b/docs/content/docs/cua-sdk/guides/desktop.mdx@@ -24,11 +24,11 @@ the interfaces below raise `SpacesdNotAvailable`.<Tabs groupId="language" persist items={['Python', 'TypeScript', 'CLI']}><Tab value="Python">-```python test="docs,fleet" id="desktop-python" prelude="fakefleet"+```python test="container" id="desktop-python"from pathlib import Pathfrom cua_sandbox import Image, Sandbox-async with Sandbox.ephemeral(Image.linux(), local=False) as sb:+async with Sandbox.ephemeral(Image.linux()) as sb:width, height = await sb.get_dimensions()await sb.mouse.click(width // 2, height // 2)await sb.keyboard.type("hello")@@ -39,13 +39,12 @@ async with Sandbox.ephemeral(Image.linux(), local=False) as sb:</Tab><Tab value="TypeScript">-```ts test="docs,fleet" id="desktop-typescript" prelude="fakefleet"+```ts test="container" id="desktop-typescript"import { writeFile } from 'node:fs/promises';import { embedded, SandboxCreateOptions } from '@trycua/cua';-const sb = await embedded({ fleetFromSession: true }).sandboxes().create(+const sb = await embedded().sandboxes().create(SandboxCreateOptions.create({- on: 'cloud',image: 'ghcr.io/trycua/linux:24.04',}));@@ -65,7 +64,7 @@ try {<Tab value="CLI">```bash test="cli-shape" id="cua-sb-create-linux"-cua sb create linux --on cloud --name desk+cua sb create linux --name deskcua sb screenshot desk -o desk.pngcua sb view desk # opens the desktop in the browser viewercua sb rm -f desk@@ -80,10 +79,10 @@ cua sb rm -f deskpip install --extra-index-url https://wheels.cua.ai/simple 'cua-sandbox[driver]==0.8.0'```-```python test="fleet" id="typed-driver" prelude="image-desktop"+```python test="container" id="typed-driver" prelude="image-desktop"from cua_driver import GetScreenSizeInput-async with Sandbox.ephemeral(image, local=False) as sb:+async with Sandbox.ephemeral(image) as sb:async with sb.driver.connect() as driver:result = await driver.get_screen_size(GetScreenSizeInput(session=None))print(result.text)@@ -112,7 +111,7 @@ cua sb exec dev ls -la /tmp # one command, no PTY```python test="container" id="terminal"from cua_sandbox import Sandbox, Image-async with Sandbox.ephemeral(Image.linux(), local=True) as sb:+async with Sandbox.ephemeral(Image.linux()) as sb:session = await sb.terminal.create(cols=80, rows=24) # command='python3' for a programpid = session['pid']await sb.terminal.send_input(pid, 'echo hello\n')@@ -137,10 +136,10 @@ cua sb create linux --name desk2 --view # open it when the sandbox is readycua viewer # one local page for every sandbox (Cua Spaces)```-```python test="docs,fleet" id="desktop-viewer-url" prelude="fakefleet"+```python test="container" id="desktop-viewer-url"from cua_sandbox import Image, Sandbox-async with Sandbox.ephemeral(Image.linux(), local=False) as sb:+async with Sandbox.ephemeral(Image.linux()) as sb:print(await sb.viewer_url())```diff --git a/docs/content/docs/cua-sdk/guides/images.mdx b/docs/content/docs/cua-sdk/guides/images.mdxindex 22de331bc3..5f9638f0bb 100644--- a/docs/content/docs/cua-sdk/guides/images.mdx+++ b/docs/content/docs/cua-sdk/guides/images.mdx@@ -51,7 +51,7 @@ windows = Image.from_registry("registry.example/win:1", os_type="windows", kind=content.```bash test="cli-shape" id="cua-sb-create-linux"-cua sb create linux --name desk # add --on cloud for the cloud+cua sb create linux --name deskcua sb create python:3.12-slim --name app -- python -m http.server 8000```@@ -95,7 +95,7 @@ prod = base.pip_install('gunicorn').run('useradd -m appuser')```python test="container" id="start-dev" session="dev" prelude="images-dev"from cua_sandbox import Sandbox-async with Sandbox.ephemeral(dev, local=True) as sb: # local=False builds it in the cloud+async with Sandbox.ephemeral(dev) as sb:print((await sb.shell.run('python -c "import rich"')).returncode)```@@ -117,9 +117,9 @@ Image.from_file('https://example.com/windows.vhdx', os_type='windows')## Private registries-Pass a `RegistrySecret`. Locally the SDK uses it for the pull; in the cloud it-becomes the sandbox's pull secret, which also covers sidecar images on the same-registry. Credentials are never logged or saved in `~/.cua`.+Pass a `RegistrySecret`. The SDK uses it for the pull (in the cloud it becomes+the sandbox's pull secret, which also covers sidecar images on the same+registry). Credentials are never logged or saved in `~/.cua`.```python skip="pseudo"from cua_sandbox import Image, RegistrySecret, Sandbox@@ -128,7 +128,7 @@ image = Image.from_registry("ghcr.io/acme/agent:1.4",secret=RegistrySecret.from_env(), # CUA_REGISTRY_USERNAME / CUA_REGISTRY_PASSWORD)-sb = await Sandbox.create(image, local=True) # or local=False+sb = await Sandbox.create(image)```| Secret | Credentials |@@ -144,14 +144,13 @@ Without a secret, local pulls also use `CUA_REGISTRY_*`, `GITHUB_TOKEN` forcua sb create ghcr.io/acme/agent:1.4 \--registry-secret env:CUA_REGISTRY_USERNAME:CUA_REGISTRY_PASSWORDcua sb create 123456789012.dkr.ecr.us-east-1.amazonaws.com/agent:1.4 \- --registry-secret aws-ecr:us-east-1 --on cloud+ --registry-secret aws-ecr:us-east-1``````ts test="docs" id="typescript"import { registrySecret, SandboxCreateOptions } from '@trycua/cua';SandboxCreateOptions.create({- on: 'cloud',image: 'ghcr.io/acme/agent:1.4',registrySecret: registrySecret.fromEnv('CUA_REGISTRY_USERNAME', 'CUA_REGISTRY_PASSWORD'),});diff --git a/docs/content/docs/cua-sdk/guides/lifecycle.mdx b/docs/content/docs/cua-sdk/guides/lifecycle.mdxindex e9d39cf2de..a8121b96c5 100644--- a/docs/content/docs/cua-sdk/guides/lifecycle.mdx+++ b/docs/content/docs/cua-sdk/guides/lifecycle.mdx@@ -3,8 +3,8 @@ title: Manage sandbox lifecycledescription: Create, keep, reconnect to, list, suspend and delete sandboxes, keep cloud sandboxes alive, and run many at once.----Every lifecycle call takes the same `local=` switch as `Sandbox.create`. The-examples use `local=True`; pass `local=False` for the cloud.+Sandboxes run on this machine by default, so the examples pass no location.+Every lifecycle call takes the same `local=` switch as `Sandbox.create`.## Ephemeral or kept@@ -12,11 +12,11 @@ examples use `local=True`; pass `local=False` for the cloud.from cua_sandbox import Image, Sandbox# Deleted when the block exits.-async with Sandbox.ephemeral(Image.linux(), local=True) as sb:+async with Sandbox.ephemeral(Image.linux()) as sb:...# Kept until you delete it.-sb = await Sandbox.create(Image.linux(), name="dev", local=True)+sb = await Sandbox.create(Image.linux(), name="dev")await sb.disconnect() # the sandbox keeps running```@@ -48,12 +48,12 @@ works when it is unique; otherwise the call raises `AmbiguousSandbox`.## Reconnect, list, delete```python test="container" id="reconnect-list-delete" session="local" prelude="local-cleanup"-sb = await Sandbox.connect("dev", local=True)-for s in await Sandbox.list(): # local and cloud; local=True filters+sb = await Sandbox.connect("dev")+for s in await Sandbox.list():print(s.name, s.status, s.location)-await Sandbox.suspend("dev", local=True)-sb = await Sandbox.resume("dev", local=True)-await Sandbox.delete("dev", local=True)+await Sandbox.suspend("dev")+sb = await Sandbox.resume("dev")+await Sandbox.delete("dev")````await sb.destroy()` deletes the sandbox you hold. Suspend, resume and restart@@ -62,7 +62,7 @@ are local only: in the cloud `suspend` and `restart` raise `Unsupported`, andin `~/.cua/sandboxes`, so either can reconnect to the other's sandboxes.```bash test="cli-shape" id="cua-sb-create-linux"-cua sb create linux --name dev # --on cloud for the cloud+cua sb create linux --name devcua sb ls # local and cloud; --local or --cloud filterscua sb info devcua sb suspend dev && cua sb resume devdiff --git a/docs/content/docs/cua-sdk/guides/services.mdx b/docs/content/docs/cua-sdk/guides/services.mdxindex d26af055f8..09bc5b0bc4 100644--- a/docs/content/docs/cua-sdk/guides/services.mdx+++ b/docs/content/docs/cua-sdk/guides/services.mdx@@ -20,9 +20,6 @@ listener must bind a guest-reachable address (`0.0.0.0`, not only## Start a server-<Tabs groupId="where" persist items={['Local', 'Cloud']}>- <Tab value="Local">-```python test="container" id="start-local" session="local" prelude="local-cleanup"from cua_sandbox import Image, Sandbox, http@@ -32,33 +29,13 @@ sb = await Sandbox.create(env={"PYTHONUNBUFFERED": "1"},services={"api": 8000},wait_for=http("api", "/"),- local=True,-)-```-- </Tab>- <Tab value="Cloud">--```python test="docs" id="start-cloud" session="cloud" prelude="fakefleet"-from cua_sandbox import Image, Sandbox, http--sb = await Sandbox.create(- Image.from_registry("python:3.12-slim"),- command=["python", "-m", "http.server", "8000"],- env={"PYTHONUNBUFFERED": "1"},- services={"api": 8000},- wait_for=http("api", "/"),- local=False,)```- </Tab>-</Tabs>-```bash test="cli-shape" id="cua-sb-create"cua sb create python:3.12-slim --name api \--service api=8000 --wait http:api/ --env PYTHONUNBUFFERED=1 \- -- python -m http.server 8000 # add --on cloud for the cloud+ -- python -m http.server 8000cua sb url api api```@@ -81,7 +58,6 @@ import { embedded, http, SandboxCreateOptions } from '@trycua/cua';const sb = await embedded().sandboxes().create(SandboxCreateOptions.create({- on: 'local', // or 'cloud'image: 'python:3.12-slim',command: ['python', '-m', 'http.server', '8000'],env: new Map([['PYTHONUNBUFFERED', '1']]),@@ -114,9 +90,6 @@ server.run("streamable-http", host="0.0.0.0", port=8765)COMMAND = ["sh", "-c", "pip install -q 'mcp>=2' && exec python -c " + shlex.quote(SERVER)]```-<Tabs groupId="where" persist items={['Local', 'Cloud']}>- <Tab value="Local">-```python test="container" id="mcp-local" session="mcp" prelude="local-cleanup"from cua_sandbox import Image, Sandbox, tcp@@ -125,28 +98,9 @@ sb = await Sandbox.create(command=COMMAND,services={"mcp": 8765},wait_for=tcp("mcp"),- local=True,)```- </Tab>- <Tab value="Cloud">--```python test="docs" id="mcp-cloud" session="mcp" prelude="fakefleet"-from cua_sandbox import Image, Sandbox, tcp--sb = await Sandbox.create(- Image.from_registry("python:3.12-slim"),- command=COMMAND,- services={"mcp": 8765},- wait_for=tcp("mcp"),- local=False,-)-```-- </Tab>-</Tabs>-`sb.mcp(service)` opens an official `mcp` client (`pip install "cua-sandbox[mcp]"`).`sb.mcp_config(service)` returns the URL and headers for any other client;fetch a fresh one per connection.diff --git a/docs/content/docs/cua-sdk/guides/sidecars.mdx b/docs/content/docs/cua-sdk/guides/sidecars.mdxindex fcbff8707a..8e8a29c176 100644--- a/docs/content/docs/cua-sdk/guides/sidecars.mdx+++ b/docs/content/docs/cua-sdk/guides/sidecars.mdx@@ -1,6 +1,6 @@---title: Add sidecar containers-description: Run extra containers such as a database or cache next to a sandbox and reach them by name, locally and in the cloud.+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';@@ -12,9 +12,6 @@ service. It is addressed by name on every runtime:- a sidecar reaches the sandbox at `main`;- `services=` names a sidecar port so you can call it from your machine.-<Tabs groupId="where" persist items={['Local', 'Cloud']}>- <Tab value="Local">-```python test="container" id="local" prelude="local-cleanup"from cua_sandbox import Container, Image, Sandbox, tcp@@ -25,7 +22,6 @@ sb = await Sandbox.create(services={"db": 6379},wait_for=tcp("db"),runtime="runc",- local=True,)```@@ -34,32 +30,10 @@ Local sidecars share the sandbox container's network namespace, socannot share a network namespace, and the SDK refuses rather than switchingruntimes silently. Local VM sandboxes refuse sidecars.- </Tab>- <Tab value="Cloud">--```python test="docs,fleet" id="cloud" prelude="fakefleet"-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"),- local=False,-)-```--The cloud ignores `runtime="runc"` and runs sidecars on both runtimes; see-[Fleet sidecars](/fleets/guides/sidecars).-- </Tab>-</Tabs>-## Reach the sandbox from a sidecarThis relay fetches the sandbox's page from `http://main:8000` and serves it on-its own port. With `local=False` the same code runs in the cloud.+its own port.```python test="container" id="by-name" prelude="local-cleanup"from cua_sandbox import Container, Image, Sandbox, http@@ -79,7 +53,6 @@ sb = await Sandbox.create(services={"relay": 8081},wait_for=http("relay", "/"),runtime="runc",- local=True,)print((await sb.service("relay").request("GET", "/")).status_code) # 200```@@ -109,7 +82,6 @@ cua sb create python:3.12-slim --name app --runtime runc \import { sidecar, SandboxCreateOptions } from '@trycua/cua';SandboxCreateOptions.create({- on: 'local',image: 'python:3.12-slim',command: ['sleep', 'infinity'],sidecars: [sidecar('redis:7-alpine', { ports: [6379], name: 'db' })],diff --git a/docs/content/docs/cua-sdk/guides/test-in-ci.mdx b/docs/content/docs/cua-sdk/guides/test-in-ci.mdxindex 1d9c3968e7..58eaed130b 100644--- a/docs/content/docs/cua-sdk/guides/test-in-ci.mdx+++ b/docs/content/docs/cua-sdk/guides/test-in-ci.mdx@@ -102,7 +102,6 @@ sb = await Sandbox.create(Image.from_registry("python:3.12-slim"),command=["sleep", "infinity"],runtime="runc",- local=True,overlay={"tool": (tool, "/usr/local/bin/tool")},)[result] = await sb.overlay({"tool": (tool, "/usr/local/bin/tool")})diff --git a/docs/content/docs/cua-sdk/index.mdx b/docs/content/docs/cua-sdk/index.mdxindex a3cdd42637..87bab58a0c 100644--- a/docs/content/docs/cua-sdk/index.mdx+++ b/docs/content/docs/cua-sdk/index.mdx@@ -1,6 +1,6 @@---title: Cua SDK-description: Build agentic applications and workflows on isolated Linux, Windows and macOS desktops, on your machine or in the cloud.+description: Build agentic applications and workflows on isolated Linux, Windows and macOS desktops on your machine, or on any machine that runs cua-spacesd.landing:summary: 'Isolated Linux, Windows and macOS desktops for your app, with your agents inside.'cta: Explore Cua SDK@@ -9,17 +9,17 @@ landing:import { Tab, Tabs } from 'fumadocs-ui/components/tabs';Build agentic apps and workflows on real desktops. Cua SDK gives your-application isolated Linux, Windows and macOS machines, locally or in the-cloud, runs the agents you already use inside them, and streams everything back-so your users can watch, take over or teleport work in and out.+application isolated Linux, Windows and macOS machines on your own computer,+runs the agents you already use inside them, and streams everything back so+your users can watch, take over or teleport work in and out.[Cua Driver](/cua-driver) is how the agents drive each desktop.-The same code runs on your machine (`local=True`, the default) or in the cloud-(`local=False`). Any OCI image works; commands, services, readiness probes,-public URLs and port forwards behave the same on both.+Sandboxes run on this machine by default: leave out `local=` (or `on`) and the+SDK uses Docker or Podman (gVisor when installed), QEMU, or Lume on Apple+silicon. Any OCI image works.-<Tabs groupId="where" persist items={['Local', 'Cloud']}>- <Tab value="Local">+<Tabs groupId="sdk-lang" persist items={['Python', 'TypeScript']}>+ <Tab value="Python">```python test="container" id="local-ephemeral" session="local"from cua_sandbox import Image, Sandbox, http@@ -29,42 +29,70 @@ async with Sandbox.ephemeral(command=["python", "-m", "http.server", "8000"],services={"web": 8000},wait_for=http("web", "/"),- local=True,) as sb:print((await sb.service("web").request("GET", "/")).status_code) # 200```</Tab>- <Tab value="Cloud">+ <Tab value="TypeScript">++```ts test="container" id="local-ephemeral-ts"+import { embedded, http, SandboxCreateOptions } from '@trycua/cua';++const sb = await embedded().sandboxes().create(+ SandboxCreateOptions.create({+ image: 'python:3.12-slim',+ command: ['python', '-m', 'http.server', '8000'],+ services: new Map([['web', 8000]]),+ waitFor: [http('web', '/')],+ })+);+console.log((await sb.service('web').request('GET', '/', undefined, undefined, undefined)).status); // 200+await sb.delete_();+```-```python test="docs" id="cloud-ephemeral" session="cloud" prelude="fakefleet"-from cua_sandbox import Image, Sandbox, http+ </Tab>+</Tabs>-async with Sandbox.ephemeral(- Image.from_registry("python:3.12-slim"),- command=["python", "-m", "http.server", "8000"],- services={"web": 8000},- wait_for=http("web", "/"),- local=False, # needs cloud credentials: `cua auth login`-) as sb:- print((await sb.service("web").request("GET", "/")).status_code) # 200+Setup: `cua runtime doctor` shows what this host has and `cua runtime setup`+installs what is missing ([Local runtimes](/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](/start-here/host-spaces-on-your-spare-mac),+or a container you started, connects directly by address and env token.+Nothing is created or deleted:++<Tabs groupId="sdk-lang" persist items={['Python', 'TypeScript']}>+ <Tab value="Python">++```python test="docs" id="direct-connect" session="direct-connect" prelude="space-url"+from cua_sandbox import Sandbox++async with Sandbox.connect(url="http://10.0.0.5:3211", token="TOKEN") as sb:+ print((await sb.shell.run("uname -a")).stdout)```</Tab>-</Tabs>+ <Tab value="TypeScript">++```ts test="docs" id="direct-connect-ts" prelude="space-url"+import { embedded } from '@trycua/cua';-## Local and cloud+const sb = await embedded().sandboxes().connectUrl("http://10.0.0.5:3211", "TOKEN", undefined);+const guest = await sb.spacesd(undefined);+console.log(new TextDecoder().decode((await guest.sh('uname -a', undefined)).stdout));+```-| | Local (`local=True`) | Cloud (`local=False`) |-| --- | --- | --- |-| Runs on | Docker or Podman (gVisor when installed), QEMU, or Lume on this machine | Cua cloud at [run.cua.ai](https://run.cua.ai): gVisor containers, KubeVirt VMs |-| Setup | `cua runtime doctor`, `cua runtime setup` | `cua auth login` |-| Architecture | The host's (other architectures run emulated) | amd64 |-| macOS | Lume VMs on Apple silicon | Not available |-| Details | [Local runtimes](/cua-sdk/guides/local-runtimes) | [Cloud sandboxes](/cua-sdk/guides/cloud) |+ </Tab>+</Tabs>-For named pools, fixed warm capacity or Terraform, see-[Cua Fleets](/fleets).+The CLI does the same with `cua sb create --on direct:10.0.0.5:3211 --token+"$CUA_ENV_TOKEN"`. To share machines across a team, join the+[Teams waitlist](https://cua.ai/teams).## Packages@@ -79,8 +107,8 @@ For named pools, fixed warm capacity or Terraform, see## How it fits togetherThe SDK is one Rust core with generated bindings, running in your process or-in `cua daemon`. It starts local runtimes itself and reaches the cloud through-the Fleet gateway. Nothing needs to run inside the image; images that ship+in `cua daemon`. It starts local runtimes itself and connects to other+machines directly. Nothing needs to run inside the image; images that ship[cua-spacesd](/cua-sdk/reference/protocol) (such as `Image.linux()`) also get thecomputer interfaces: `sb.shell`, `sb.files`, `sb.screen`, `sb.mouse`,`sb.keyboard`. See [How sandboxes work](/cua-sdk/concepts/how-sandboxes-work).diff --git a/docs/content/docs/cua-sdk/quickstart.mdx b/docs/content/docs/cua-sdk/quickstart.mdxindex c7e3637eee..0268c66ece 100644--- a/docs/content/docs/cua-sdk/quickstart.mdx+++ b/docs/content/docs/cua-sdk/quickstart.mdx@@ -1,12 +1,12 @@---title: Quickstart-description: Your first sandbox. Run a web server in a sandbox on your machine, call it, then run the same code in the cloud.+description: Your first sandbox. Run a web server in a sandbox on your machine and call it.---import { Tab, Tabs } from 'fumadocs-ui/components/tabs';-Run a web server in a sandbox on your machine and call it. The cloud variant-changes one line: `local=False`.+Run a web server in a sandbox on your machine and call it. Sandboxes run+locally by default, so the code passes no location.## Prerequisites@@ -16,7 +16,7 @@ changes one line: `local=False`.pip install cua-sandbox```-- Locally, a container engine (Docker, Podman or Colima). Check the host and+- A container engine (Docker, Podman or Colima). Check the host andinstall what is missing:```bash test="cli-shape" id="cua-runtime-doctor"@@ -24,13 +24,10 @@ cua runtime doctorcua runtime setup```-- For the cloud, sign in once with `cua auth login`- ([credentials](/cua-sdk/guides/cloud#credentials)).-## Run-<Tabs groupId="quickstart-run" persist items={['Local', 'Cloud', 'CLI', 'TypeScript']}>- <Tab value="Local">+<Tabs groupId="quickstart-run" persist items={['Python', 'CLI', 'TypeScript']}>+ <Tab value="Python">```python title="quickstart.py" test="container" id="local-server" session="local"import asyncio@@ -44,31 +41,6 @@ async def main():command=["python", "-m", "http.server", "8000"],services={"web": 8000},wait_for=http("web", "/"),- local=True,- ) as sb:- print((await sb.service("web").request("GET", "/")).status_code)- print(await sb.service("web").url())---asyncio.run(main())-```-- </Tab>- <Tab value="Cloud">--```python title="quickstart.py" test="docs,fleet" id="cloud-server" session="cloud" prelude="fakefleet"-import asyncio--from cua_sandbox import Image, Sandbox, http---async def main():- async with Sandbox.ephemeral(- Image.from_registry("python:3.12-slim"),- command=["python", "-m", "http.server", "8000"],- services={"web": 8000},- wait_for=http("web", "/"),- local=False,) as sb:print((await sb.service("web").request("GET", "/")).status_code)print(await sb.service("web").url())@@ -83,7 +55,7 @@ asyncio.run(main())```bash test="cli-shape" id="cua-sb-create"cua sb create python:3.12-slim --name web \--service web=8000 --wait http:web/ \- -- python -m http.server 8000 # add --on cloud for the cloud+ -- python -m http.server 8000cua sb url web web```@@ -95,7 +67,6 @@ import { embedded, http, SandboxCreateOptions } from '@trycua/cua';const sb = await embedded().sandboxes().create(SandboxCreateOptions.create({- on: 'local', // 'cloud' for the cloudimage: 'python:3.12-slim',command: ['python', '-m', 'http.server', '8000'],services: new Map([['web', 8000]]),@@ -116,8 +87,7 @@ await sb.delete_();http://127.0.0.1:53817```-In the cloud the URL is a short-lived signed `https://` URL, and the first-start of an image can take a few minutes.+The first start of an image pulls it, which can take a few minutes.## Clean up@@ -153,8 +123,7 @@ Tahoe and `Image.macos("15")` Sequoia, both local only on Apple silicon.## Adapter benchmark images-Each has a container tag and a `-disk` VM tag, and runs locally or in the-cloud with `cb run`.+Each has a container tag and a `-disk` VM tag, and runs locally with `cb run`.{/* GENERATED:catalog-benchmarks:start */}| Benchmark | What | Tasks | Image |@@ -170,4 +139,4 @@ cloud with `cb run`.- [Control the desktop](/cua-sdk/guides/desktop)- [Run a service](/cua-sdk/guides/services)-- [Run sandboxes in the cloud](/cua-sdk/guides/cloud)+- [Reach another machine](/cua-sdk#reach-another-machine)diff --git a/docs/content/docs/cua-sdk/reference/python/configuration.mdx b/docs/content/docs/cua-sdk/reference/python/configuration.mdxindex 144c5a72aa..cec603eed9 100644--- a/docs/content/docs/cua-sdk/reference/python/configuration.mdx+++ b/docs/content/docs/cua-sdk/reference/python/configuration.mdx@@ -7,7 +7,7 @@ description: "configure, login, whoami, transports and the errors cua-sandbox raAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: pnpm --dir docs docs:generate:pythonSource: griffe over libs/python/cua-sandbox/cua_sandbox (cua_sandbox.configuration)- Version: cua-sandbox 0.8.0+ Version: cua-sandbox 0.9.0*/}Process-wide settings, sign-in helpers, transports and the typed errors of `cua-sandbox`.diff --git a/docs/content/docs/cua-sdk/reference/python/image.mdx b/docs/content/docs/cua-sdk/reference/python/image.mdxindex a06045d2fc..58f303088b 100644--- a/docs/content/docs/cua-sdk/reference/python/image.mdx+++ b/docs/content/docs/cua-sdk/reference/python/image.mdx@@ -7,7 +7,7 @@ description: "The Image builder, sidecar containers and registry credentials ofAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: pnpm --dir docs docs:generate:pythonSource: griffe over libs/python/cua-sandbox/cua_sandbox (cua_sandbox.image)- Version: cua-sandbox 0.8.0+ Version: cua-sandbox 0.9.0*/}`Image` is an immutable, chainable description of what a sandbox boots. Builder methods return a new `Image`.diff --git a/docs/content/docs/cua-sdk/reference/python/index.mdx b/docs/content/docs/cua-sdk/reference/python/index.mdxindex 4469c75df7..5793533b7d 100644--- a/docs/content/docs/cua-sdk/reference/python/index.mdx+++ b/docs/content/docs/cua-sdk/reference/python/index.mdx@@ -7,14 +7,14 @@ description: "cua_sandbox and the cua package helpers: packages, configuration,AUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: pnpm --dir docs docs:generate:pythonSource: griffe over libs/cua/python/src/cua (cua._native excluded) and libs/python/cua-sandbox- Version: cua 0.2.0, cua-sandbox 0.8.0+ Version: cua 0.2.0, cua-sandbox 0.9.0*/}The high-level Python API: `cua_sandbox` (`Sandbox`, `Image`, the computer interfaces, `Pool`) and the helpers the `cua` package adds. It is a thin layer over the [Cua SDK objects](/cua-sdk/reference): the cloud, the local runtimes and cua-spacesd all go through `cua`, whose generated binding (`cua._native`) those pages document.| Package | Install | Import || --- | --- | --- |-| `cua-sandbox` 0.8.0 (Python 3.11 to 3.13) | `pip install cua-sandbox` | `from cua_sandbox import Sandbox, Image` |+| `cua-sandbox` 0.9.0 (Python 3.11 to 3.13) | `pip install cua-sandbox` | `from cua_sandbox import Sandbox, Image` || `cua` 0.2.0 with the extra | `pip install "cua[sandbox]"` | `from cua import Sandbox, Image` (the same classes) || MCP client support | `pip install "cua-sandbox[mcp]"` | `sb.mcp()` || Typed Cua Driver access | `pip install "cua-sandbox[driver]"` | `sb.driver` |diff --git a/docs/content/docs/cua-sdk/reference/python/interfaces.mdx b/docs/content/docs/cua-sdk/reference/python/interfaces.mdxindex c57d07d85a..17e50abd64 100644--- a/docs/content/docs/cua-sdk/reference/python/interfaces.mdx+++ b/docs/content/docs/cua-sdk/reference/python/interfaces.mdx@@ -7,7 +7,7 @@ description: "Shell, mouse, keyboard, screen, clipboard, window, terminal, filesAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: pnpm --dir docs docs:generate:pythonSource: griffe over libs/python/cua-sandbox/cua_sandbox (cua_sandbox.interfaces)- Version: cua-sandbox 0.8.0+ Version: cua-sandbox 0.9.0*/}Every sandbox exposes these interfaces as attributes (`sb.shell`, `sb.mouse`, ...). Input goes through cua-driver inside the guest.diff --git a/docs/content/docs/cua-sdk/reference/python/pool.mdx b/docs/content/docs/cua-sdk/reference/python/pool.mdxindex 74d5f78ebf..566bb3aeeb 100644--- a/docs/content/docs/cua-sdk/reference/python/pool.mdx+++ b/docs/content/docs/cua-sdk/reference/python/pool.mdx@@ -7,7 +7,7 @@ description: "Pools, templates, sandbox specs and pool errors of cua-sandbox."AUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: pnpm --dir docs docs:generate:pythonSource: griffe over libs/python/cua-sandbox/cua_sandbox (cua_sandbox.pool)- Version: cua-sandbox 0.8.0+ Version: cua-sandbox 0.9.0*/}`Pool` keeps warm cloud capacity for a `SandboxSpec`. `Sandbox.create` uses shared capacity; a named pool is for dedicated capacity.diff --git a/docs/content/docs/cua-sdk/reference/python/runtimes.mdx b/docs/content/docs/cua-sdk/reference/python/runtimes.mdxindex 065a8d7c54..38e3d938db 100644--- a/docs/content/docs/cua-sdk/reference/python/runtimes.mdx+++ b/docs/content/docs/cua-sdk/reference/python/runtimes.mdx@@ -7,7 +7,7 @@ description: "Local runtimes (Docker, QEMU, Lume, Hyper-V, Tart, Android emulatoAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: pnpm --dir docs docs:generate:pythonSource: griffe over libs/python/cua-sandbox/cua_sandbox (cua_sandbox.runtimes)- Version: cua-sandbox 0.8.0+ Version: cua-sandbox 0.9.0*/}Local sandboxes run on a runtime the SDK picks for the image. Pass one explicitly to `Sandbox.create(..., runtime=...)` to override it.diff --git a/docs/content/docs/cua-sdk/reference/python/sandbox.mdx b/docs/content/docs/cua-sdk/reference/python/sandbox.mdxindex 1c8287e136..4b71eaedd2 100644--- a/docs/content/docs/cua-sdk/reference/python/sandbox.mdx+++ b/docs/content/docs/cua-sdk/reference/python/sandbox.mdx@@ -7,7 +7,7 @@ description: "Sandbox, SandboxInfo, the sandbox() helper and the creation optionAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: pnpm --dir docs docs:generate:pythonSource: griffe over libs/python/cua-sandbox/cua_sandbox (cua_sandbox.sandbox)- Version: cua-sandbox 0.8.0+ Version: cua-sandbox 0.9.0*/}The `Sandbox` class is the entry point of `cua-sandbox`: create, connect to, or reattach a sandbox, then use its interfaces.@@ -446,10 +446,10 @@ by the interfaces when the image has it).{/* Examples: scripts/docs-generators/examples/cua-sdk/python/Sandbox.create.py */}-```python test="docs" id="sandbox-create-py" session="sandbox-create-py" prelude="fakefleet"+```python test="container" id="sandbox-create-py" session="sandbox-create-py"import asyncio-from cua_sandbox import CloudOptions, Image, Sandbox, http+from cua_sandbox import Image, Sandbox, httpasync def main():sb = await Sandbox.create(@@ -457,8 +457,6 @@ async def main():command=["python", "-m", "http.server", "8000"],services={"web": 8000},wait_for=http("web", "/"),- local=False, # the cloud; omit it to run locally- cloud=CloudOptions(warm=False), # optional; implies the cloudcpu=2, memory="4GB",)print(sb.id)diff --git a/docs/content/docs/cua-sdk/reference/python/services.mdx b/docs/content/docs/cua-sdk/reference/python/services.mdxindex 2bcce983e2..558c3b09a2 100644--- a/docs/content/docs/cua-sdk/reference/python/services.mdx+++ b/docs/content/docs/cua-sdk/reference/python/services.mdx@@ -7,7 +7,7 @@ description: "Named services, signed and public URLs, tunnels and MCP endpointsAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: pnpm --dir docs docs:generate:pythonSource: griffe over libs/python/cua-sandbox/cua_sandbox (cua_sandbox.services)- Version: cua-sandbox 0.8.0+ Version: cua-sandbox 0.9.0*/}Reach ports inside a sandbox: named services, tunnels, shareable URLs and MCP servers.diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdxindex b346bd6fa9..d3bd800b8e 100644--- a/docs/content/docs/index.mdx+++ b/docs/content/docs/index.mdx@@ -1,10 +1,10 @@---title: Cua documentation-description: Open-source computer-use infrastructure. Sandboxes on your machine or in the cloud, and agents that drive real desktops.+description: Computer-use infrastructure on your own machines. Sandboxes, Spaces, and agents that drive real desktops.landing:hero: Cua Developerspath: 'One walkthrough per product, from setup to a result you can check.'- products: [cua-sdk, cua-driver, fleets, cua-bench]+ products: [cua-sdk, cua-driver, spaces, cua-bench]examples:- title: Cua Botsdescription: Persistent bots on Cua Spaces, each with its own computer, memory, routines and rules. A Mac and iPhone app in SwiftUI.@@ -32,19 +32,16 @@ import { Card, Cards } from 'fumadocs-ui/components/card';<Cards><Card title="Cua SDK" href="/cua-sdk">- Isolated Linux, Windows and macOS desktops for your app, locally or in the cloud, with your agents running inside.+ Isolated Linux, Windows and macOS desktops for your app, on your machine, with your agents running inside.</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="Cua Fleets" href="/fleets">- Dedicated cloud capacity: pools, templates, warm pools, Terraform.- </Card><Card title="Cua Spaces" href="/spaces">The desktop app for your sandboxes and machines: stream, share files, teleport apps.</Card><Card title="Cua Bench" href="/cua-bench">- Run and score computer-use benchmarks locally or in the cloud.+ Run and score computer-use benchmarks on your machine.</Card><Card title="Lume" href="/lume">macOS and Linux VMs on Apple silicon.@@ -57,7 +54,8 @@ import { Card, Cards } from 'fumadocs-ui/components/card';## Start here- [Sandbox images](/start-here/sandbox-images): the desktop and benchmark images, and one line to start each.-- [Your first cloud sandbox](/start-here/your-first-cloud-fleet): start a Linux desktop in the Cua cloud, verify a file inside it, and release it.+- [Create a Space with the Cua SDK](/start-here/create-a-space-with-the-sdk): create a Linux Space on your machine from Python or TypeScript, use it, watch it and delete it.+- [Host Spaces on your spare Mac](/start-here/host-spaces-on-your-spare-mac): let your laptop create Spaces on another machine, over the relay, ssh or Tailscale.- [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.diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.jsonindex 9f1e8fb73f..2c9ebbde18 100644--- a/docs/content/docs/meta.json+++ b/docs/content/docs/meta.json@@ -6,8 +6,8 @@"start-here","cua-sdk","cua-driver",- "fleets","spaces",+ "fleets","cua-bench","lume","cua-cli"diff --git a/docs/content/docs/redirects.json b/docs/content/docs/redirects.jsonindex d54990e7c5..aef823f19e 100644--- a/docs/content/docs/redirects.json+++ b/docs/content/docs/redirects.json@@ -379,7 +379,9 @@"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",- "tutorials/your-first-cloud-fleet": "start-here/your-first-cloud-fleet",+ "tutorials/your-first-cloud-fleet": "start-here/create-a-space-with-the-sdk",+ "start-here/your-first-cloud-fleet": "start-here/create-a-space-with-the-sdk",+ "spaces/guides/host-spaces-on-your-spare-mac": "start-here/host-spaces-on-your-spare-mac","tutorials/your-first-cua-bench-task": "start-here/your-first-cua-bench-task","use-cua-with": "cua-driver/guides/connect-your-agent","use-cua-with/anthropic": "cua-driver/guides/connect-your-agent",diff --git a/docs/content/docs/spaces/guides/add-a-space.mdx b/docs/content/docs/spaces/guides/add-a-space.mdxindex 074a7dedc0..4ba381a56b 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: Add a Space-description: 'Create a Space locally or in the cloud, or from any image, follow or cancel the create, add a GPU, add an existing machine, then list, delete or remove it.'+description: 'Create a Space on your machine, from any image, follow or cancel the create, add a GPU, add an existing machine, then list, delete or remove it.'---import { Callout } from 'fumadocs-ui/components/callout';@@ -13,7 +13,7 @@ prints (`local:<name>`, `cloud:<name>`, `direct:<host:port>`,## Create a Space```python skip="pseudo"-created = await spaces.create(cua.SpaceCreateOptions(on="local", cpus=2, memory_mb=4096))+created = await spaces.create(cua.SpaceCreateOptions(cpus=2, memory_mb=4096))space = await spaces.space(created.space.id)```@@ -23,18 +23,6 @@ without `on`, the Space runs where `cua config get default.on` says (localunless you changed it; the Spaces app sets it in Settings, Default location).`cua runtime doctor` shows what this host has.-## In the cloud--Needs `cua auth login`, or `CUA_CLIENT_ID` and `CUA_CLIENT_SECRET`. Cloud-Spaces are metered until deleted.--```python skip="placeholder"-created = await spaces.create(cua.SpaceCreateOptions(on="cloud"))-space = await spaces.space(created.space.id)-# ...-await spaces.delete(created.space.id)-```-`reuse=True` returns a registered, reachable Space in the same location first(`created.reused` says so). With `wait=False`, `created.pending_id` names aSpace that is not ready yet.@@ -173,7 +161,7 @@ MagicDNS name as the host:port): `cua spaces add` reaches it like any otheraddress and the Space registers as `direct:<addr>`. That only attaches onealready-running Space; hosting Spaces for `on="host:<name>"` still goesthrough the cua.ai relay, set up with-[`cua host setup`](/spaces/guides/host-spaces-on-your-spare-mac).+[`cua host setup`](/start-here/host-spaces-on-your-spare-mac).`spaces.delete(id)` deletes aSpace's sandbox and forgets it (a Space added by address is only forgotten);diff --git a/docs/content/docs/spaces/guides/cua-volume.mdx b/docs/content/docs/spaces/guides/cua-volume.mdxindex 99b670705c..1693caa73c 100644--- a/docs/content/docs/spaces/guides/cua-volume.mdx+++ b/docs/content/docs/spaces/guides/cua-volume.mdx@@ -267,7 +267,6 @@ copy in Finder, Resolve clears the entry and keeps both files.|---------|-------|--------|| `fs` (default) | `~/.cua/volume/data` on this machine | Nothing || `s3` | Any S3-compatible bucket with versioning on (AWS S3, R2, MinIO) | `cua volume config set` and `cua volume config set-keys` |-| `cloud` | The Cua cloud's bucket, short-lived keys scoped to your folders | Off by default; the Cua cloud must enable Cua Volume for your account |```bash test="cli-shape" id="cua-volume-config"cua volume config show@@ -281,12 +280,6 @@ daemon after changing the backend from the terminal. Settings > Storage inCua tests the bucket first (reachable, keys allowed to write, versioning on)and switches the running drive without a restart.-<Callout type="info">-The `cloud` backend is off until the Cua cloud turns on Cua Volume: the-server answers `drive_disabled` until then. When on, keys last 15 to 60-minutes and reach only the folders your session may use.-</Callout>-## Limits| Limit | Value |diff --git a/docs/content/docs/spaces/guides/meta.json b/docs/content/docs/spaces/guides/meta.jsonindex 135d8c7c86..b49a4c5bdb 100644--- a/docs/content/docs/spaces/guides/meta.json+++ b/docs/content/docs/spaces/guides/meta.json@@ -4,7 +4,6 @@"add-a-space","unattended-access","share-a-space",- "host-spaces-on-your-spare-mac","stream-a-desktop","send-files","teleport-an-app",diff --git a/docs/content/docs/spaces/guides/persistent-agents.mdx b/docs/content/docs/spaces/guides/persistent-agents.mdxindex 211f92aad9..9ccebd6696 100644--- a/docs/content/docs/spaces/guides/persistent-agents.mdx+++ b/docs/content/docs/spaces/guides/persistent-agents.mdx@@ -72,7 +72,6 @@ cua agent resume ada| Space | Pause | Resume ||-------|-------|--------|| Local | Suspends the Space. | Resumes it. |-| Cloud | Saves the home, then releases the Space (Cua Cloud cannot suspend a Space). | Creates the Space again from the same image and restores the home. Apps that were open do not come back. || Your own machine or an added address | Only the agent pauses. | Only the agent resumes. |## What the agent getsdiff --git a/docs/content/docs/spaces/guides/unattended-access.mdx b/docs/content/docs/spaces/guides/unattended-access.mdxindex 2bbc6a9a47..72109c9613 100644--- a/docs/content/docs/spaces/guides/unattended-access.mdx+++ b/docs/content/docs/spaces/guides/unattended-access.mdx@@ -28,7 +28,7 @@ machine is shared with, or enroll devices.| `--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 your spare Mac](/spaces/guides/host-spaces-on-your-spare-mac). |+| `--profile spare` | A spare machine: do not share its desktop, create Spaces for your devices (`--no-desktop --provide-spaces`). See [Host Spaces on your spare Mac](/start-here/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.diff --git a/docs/content/docs/spaces/index.mdx b/docs/content/docs/spaces/index.mdxindex 35f07527c7..afda4ef50f 100644--- a/docs/content/docs/spaces/index.mdx+++ b/docs/content/docs/spaces/index.mdx@@ -1,12 +1,17 @@---title: Cua Spacesdescription: 'The Cua Spaces app and SDK: register any sandbox or machine once, then stream it, run agents in it and teleport apps into it.'+landing:+ summary: 'Desktops for you and your agents on your own Mac and your team''s machines: watch, stream, teleport apps.'+ cta: Explore Cua Spaces----A Space is a desktop your agents can use and you can watch: a local container-or VM, a cloud sandbox, or your own machine. Each runs cua-spacesd, which-streams the screen, takes input through Cua Driver, and receives teleported-apps and files.+A Space is a desktop your agents can use and you can watch: a container or VM+on your own Mac, or one of your team's machines (your own cloud is coming+soon). Each runs cua-spacesd, which streams the screen, takes input through+Cua Driver, and receives teleported apps and files. Cua Spaces is+source-available under the FSL-1.1-MIT. For teams, join the+[waitlist](https://cua.ai/teams).The **Cua Spaces app** puts your Spaces in the menu bar and notch, so you canwatch them, open them and teleport apps in with a drag.@@ -19,9 +24,8 @@ run agents in them from Python, TypeScript, Swift or Rust.| 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 |-| Cloud | `cloud:<name>` | `spaces.create(on="cloud")` |-| Local | `local:<name>` | `spaces.create(on="local")` || Relay | `relay:<machine-id>` | Your machines set up with `cua host setup`, listed automatically |The app, the `cua` CLI, the SDKs and `cua daemon` share one registry (`~/.cua/spaces.json`).diff --git a/docs/content/docs/start-here/create-a-space-with-the-sdk.mdx b/docs/content/docs/start-here/create-a-space-with-the-sdk.mdxnew file mode 100644index 0000000000..86a129d248--- /dev/null+++ b/docs/content/docs/start-here/create-a-space-with-the-sdk.mdx@@ -0,0 +1,153 @@+---+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.+---++import { Tab, Tabs } from 'fumadocs-ui/components/tabs';++A Space is a desktop your agents can use and you can watch. In this+walkthrough you create one on your own machine 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.++Requirements: Docker (or Podman or Colima) and about 4 GB of free memory.++## 1. Install++```bash skip="host-install"+curl -fsSL https://cua.ai/install.sh | sh # the cua CLI+cua runtime doctor # checks the container engine+```++<Tabs groupId="sdk-lang" persist items={['Python', 'TypeScript']}>+ <Tab value="Python">++```bash skip="host-install"+pip install cua+```++ </Tab>+ <Tab value="TypeScript">++```bash skip="host-install"+npm install @trycua/cua+```++ </Tab>+</Tabs>++## 2. Create a Space and use it++The program passes no location, so the Space runs on this machine: the+canonical Linux desktop (`ghcr.io/trycua/linux:24.04`) in a container.++<Tabs groupId="sdk-lang" persist items={['Python', 'TypeScript']}>+ <Tab value="Python">++```python title="first_space.py" test="container" id="first-space"+import asyncio++import cua+++async def main():+ spaces = cua.embedded().spaces()+ created = await spaces.create(cua.SpaceCreateOptions())+ space = await spaces.space(created.space.id)+ print("space:", created.space.id)++ # Run a command.+ out = await space.bash("uname -sm", None)+ print(out.stdout.strip())++ # Take a screenshot.+ shot = await space.screenshot(None)+ with open("space.png", "wb") as f:+ f.write(shot.image)+ print("screenshot: space.png")++ # Ask Cua Driver in the Space which windows are open.+ windows = await space.call_tool("list_windows", None, None, None)+ print("driver:", "error" if windows.is_error else "ok")++ # Delete the Space. Comment this out to keep it and watch it (step 3).+ await spaces.delete(created.space.id)+++asyncio.run(main())+```++ </Tab>+ <Tab value="TypeScript">++```ts title="first-space.ts" test="container" id="first-space-ts"+import { writeFile } from 'node:fs/promises';+import { embedded, SpaceCreateOptions } from '@trycua/cua';++const spaces = embedded().spaces();+const created = await spaces.create(SpaceCreateOptions.create({}));+const id = created.space!.id;+const space = await spaces.space(id);+console.log('space:', id);++// Run a command.+console.log((await space.bash('uname -sm', undefined)).stdout.trim());++// Take a screenshot.+const shot = await space.screenshot(undefined);+await writeFile('space.png', Buffer.from(shot.image));+console.log('screenshot: space.png');++// Ask Cua Driver in the Space which windows are open.+const windows = await space.callTool('list_windows', undefined, undefined, undefined);+console.log('driver:', windows.isError ? 'error' : 'ok');++// Delete the Space. Comment this out to keep it and watch it (step 3).+await spaces.delete_(id);+```++ </Tab>+</Tabs>++Run it with `python first_space.py` or `npx tsx first-space.ts`. The first+run pulls the image, which can take a few minutes.++```text output+space: local:space-1a2b3c+Linux x86_64+screenshot: space.png+driver: ok+```++`space.png` holds the desktop. On Apple silicon `uname` prints `aarch64`.++## 3. Watch it++Keep the Space (comment out the delete line), run the program again, then open+its desktop in your browser with the id it printed:++```bash test="cli-shape" id="first-space-view"+cua sb view local:space-1a2b3c+```++The [Cua Spaces app](/spaces) lists the same Space, since the app, the CLI and+the SDK share one registry.++## 4. Clean up++The program deletes its Space. One you kept goes with:++```bash test="cli-shape" id="first-space-delete"+cua spaces delete local:space-1a2b3c+```++`cua spaces ls` shows what is left.++## 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 your spare Mac](/start-here/host-spaces-on-your-spare-mac):+ let your laptop create Spaces on another machine, over the relay, ssh or+ Tailscale.+- [Add a Space](/spaces/guides/add-a-space): any image, progress, GPUs.diff --git a/docs/content/docs/spaces/guides/host-spaces-on-your-spare-mac.mdx b/docs/content/docs/start-here/host-spaces-on-your-spare-mac.mdxsimilarity index 94%rename from docs/content/docs/spaces/guides/host-spaces-on-your-spare-mac.mdxrename to docs/content/docs/start-here/host-spaces-on-your-spare-mac.mdxindex 07246c4455..83a990513e 100644--- a/docs/content/docs/spaces/guides/host-spaces-on-your-spare-mac.mdx+++ b/docs/content/docs/start-here/host-spaces-on-your-spare-mac.mdx@@ -1,15 +1,17 @@---title: Host Spaces on your spare Mac-description: 'Turn a spare Mac mini (or any machine) into a place your laptop and your agents create Spaces on, without sharing its own desktop.'+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';-Spaces run on your Mac, on your machines, or in the cloud (Cua cloud, or [your own AWS, Google Cloud or Modal account](/cua-sdk/guides/your-cloud)). A spare Mac mini-in a closet can run Spaces for your laptop: your laptop, or a coding agent on-it, asks for them through the cua.ai relay, and the Mac mini runs them with-its own runtimes (Lume for macOS VMs, Docker for Linux). Its own desktop,-shell and files stay private.+Spaces run on your own Mac and on your other machines (your own cloud is+coming soon). In this walkthrough a spare Mac mini in a closet runs Spaces for+your laptop: your laptop, or a coding agent on it, asks for them through the+cua.ai relay or [directly over Tailscale](#over-tailscale-without-the-relay),+and the Mac mini runs them with its own runtimes (Lume for macOS VMs, Docker+for Linux). You can set the Mac up [over ssh](#over-ssh-or-tailscale). Its own+desktop, shell and files stay private.## Set up the spare Macdiff --git a/docs/content/docs/start-here/meta.json b/docs/content/docs/start-here/meta.jsonindex 045c5fcbc2..b3c0fd3fb4 100644--- a/docs/content/docs/start-here/meta.json+++ b/docs/content/docs/start-here/meta.json@@ -3,7 +3,8 @@"icon": "GraduationCap","pages": ["sandbox-images",- "your-first-cloud-fleet",+ "create-a-space-with-the-sdk",+ "host-spaces-on-your-spare-mac","drive-your-first-app","create-a-local-macos-sandbox","run-in-github-actions",diff --git a/docs/content/docs/start-here/sandbox-images.mdx b/docs/content/docs/start-here/sandbox-images.mdxindex 8a1a988154..42f493129a 100644--- a/docs/content/docs/start-here/sandbox-images.mdx+++ b/docs/content/docs/start-here/sandbox-images.mdx@@ -43,5 +43,3 @@ curl -fsSL https://cua.ai/install.sh | shcua sb create linux --name deskcua sb view desk```--Add `--on cloud` to run it in the cloud.diff --git a/docs/content/docs/start-here/your-first-cloud-fleet.mdx b/docs/content/docs/start-here/your-first-cloud-fleet.mdxdeleted file mode 100644index 3721e5c1d3..0000000000--- a/docs/content/docs/start-here/your-first-cloud-fleet.mdx+++ /dev/null@@ -1,172 +0,0 @@-----title: Your first cloud sandbox-description: Start a Linux desktop sandbox in the Cua cloud, hash a file inside it, verify the result on your machine, and release it.------import { Callout } from 'fumadocs-ui/components/callout';-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';--In this walkthrough you start a Linux desktop sandbox in the Cua cloud, write a-file into it, hash the file in the guest, check the hash on your computer,-look at the desktop, and release the sandbox. You do it first with the `cua`-CLI, then as a script.--Sandboxes run on your machine by default; `--on cloud` (or `local=False` in-Python) sends the same calls to the cloud. To stay local, start with the-[Cua SDK quickstart](/cua-sdk/quickstart).--The walkthrough uses the canonical Linux image, `ghcr.io/trycua/linux:24.04`,-which ships cua-spacesd on port `3211`. The CLI and SDK send shell, file and-screenshot calls to it through the cloud gateway.--<Callout type="info">- Cloud usage is billed while a sandbox runs. Releasing it ends the charge; the capacity behind it- is managed for you and removed when idle.-</Callout>--## 1. Sign in--Install the `cua` CLI, then sign in:--```bash test="cli-shape" id="cua-auth-login"-curl -fsSL https://cua.ai/install.sh | sh-cua auth login-cua auth whoami-```--`whoami` verifies the session against the cloud. On a machine without a-browser, use `cua auth login --remote`.--## 2. Start a sandbox with the CLI--```bash test="cli-shape" id="cua-sb-create"-cua sb create ghcr.io/trycua/linux:24.04 --on cloud --name first-fleet-```--Canonical images keep warm capacity, so this usually takes seconds; the first-start of another image can take a few minutes. Without a running `cua daemon`,-the sandbox expires 15 minutes after the command unless you run-`cua sb keep-alive first-fleet`, which is plenty for this walkthrough.--Write a file, hash it in the guest, and hash the same bytes locally:--```bash test="cli-shape" id="cua-sb-cp"-printf 'pear\napple\npear\nbanana\n' > fruit.txt-cua sb cp fruit.txt first-fleet:/tmp/fruit.txt-cua sb exec first-fleet sha256sum /tmp/fruit.txt-shasum -a 256 fruit.txt-```--Both commands print-`d9359aad71bda9a11a4fd2e8d72044d6f0f77519c6b6fb30d251806febcfb4d0`. Your-computer computed the second value, so the check does not rely on the guest to-verify itself.--Take a screenshot, or open the live desktop in your browser with the viewer:--```bash test="cli-shape" id="cua-sb-screenshot-first-fleet"-cua sb screenshot first-fleet -o first-fleet.png-cua sb view first-fleet-```----Release the sandbox:--```bash test="cli-shape" id="cua-sb-rm-first-fleet"-cua sb rm -f first-fleet-```--## 3. Do the same from a script--Scripts read cloud credentials from the environment. Create an API key and-export it (the secret is printed once):--```bash test="cli-shape" id="cua-auth-keys-create"-cua auth keys create first-fleet-```--```bash skip="placeholder"-export CUA_CLIENT_ID="<client-id>"-export CUA_CLIENT_SECRET="<client-secret>"-```--The TypeScript example can also use your `cua auth login` session when no key-is set.--<Tabs groupId="language" persist items={['Python', 'TypeScript']}>- <Tab value="Python">--You need Python `>=3.11,<3.14` and [`uv`](https://docs.astral.sh/uv/). Download-the example and run it:--```bash skip="third-party-cli"-curl -fsSLO https://cua.ai/docs-assets/scripts/first-cloud-fleet/first_cloud_fleet.py-uv run first_cloud_fleet.py-```--The script header pins `cua-sandbox==0.8.0` and runs `Image.linux()`-(`ghcr.io/trycua/linux:24.04`) unless `CUA_FLEET_IMAGE` names another image.-`local=False` sends it to the cloud; without it the sandbox runs on your-machine. Its core is:--```python skip="pseudo"-async with Sandbox.ephemeral(image, local=False, cpu=4, memory_mb=4096) as sandbox:- await sandbox.files.write_text(SOURCE_PATH, SOURCE_TEXT)- result = await sandbox.shell.run(f"sha256sum {SOURCE_PATH}")- ...- SCREENSHOT.write_bytes(await sandbox.screenshot())-```-- </Tab>- <Tab value="TypeScript">--You need Node.js 20 or newer:--```bash skip="host-install"-mkdir first-cloud-fleet && cd first-cloud-fleet-npm init -y && npm pkg set type=module-npm install @trycua/[email protected] && npm install --save-dev tsx-```--```bash skip="third-party-cli"-curl -fsSLo first-cloud-fleet.ts \- https://cua.ai/docs-assets/scripts/first-cloud-fleet/first-cloud-fleet.ts.txt-npx tsx first-cloud-fleet.ts-```--It uses the same default image and `CUA_FLEET_IMAGE` override, talks to-cua-spacesd in the guest for the upload, the hash and the screenshot, and-deletes the sandbox in a `finally` block.-- </Tab>-</Tabs>--A successful run prints:--```text output-Claimed ...-Verified SHA-256: d9359aad71bda9a11a4fd2e8d72044d6f0f77519c6b6fb30d251806febcfb4d0-Screenshot: .../first-cloud-fleet.png-Claim released-```--Both scripts release the sandbox even when a step fails. If a process is-killed first, the sandbox expires on its own after its TTL (15 minutes by-default). Idle managed pools are deleted after 30 minutes, or now with-`cua fleet pools gc`; see-[Clean up leftovers](/fleets/guides/troubleshoot#clean-up-leftovers).--## What you built--You ran a cloud sandbox from a registry image with no capacity setup. The CLI-and the SDK reached cua-spacesd in the guest, and releasing the sandbox ended-the charge.--## Next steps--- [Fleets quickstart](/fleets/quickstart): apply a pool of your own and claim from it.-- [Run sandboxes in the cloud](/cua-sdk/guides/cloud): credentials, regions and options.-- [Run a service](/cua-sdk/guides/services) in a sandbox and reach it from your machine.-- [Manage sandbox lifecycle](/cua-sdk/guides/lifecycle): named sandboxes, reconnecting, keep-alive.-- [Control the desktop](/cua-sdk/guides/desktop): screenshots, input and the viewer.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.mdxindex fd34132df7..a33aa34613 100644--- a/docs/content/docs/start-here/your-first-cua-bench-task.mdx+++ b/docs/content/docs/start-here/your-first-cua-bench-task.mdx@@ -117,9 +117,8 @@ The evaluator that scored the oracle also scored your attempt.## 6. Hand it to an agent-```bash skip="placeholder"+```bash test="cli-shape" id="first-task-agent"cb run first-task --agent cua-agent --model anthropic/claude-sonnet-4-20250514-cb run first-task --agent cua-agent --model <model> --on cloud # after cua auth login````--on local` (the default) runs tasks in sandboxes on this machine; `--kind`,diff --git a/docs/next.config.mjs b/docs/next.config.mjsindex 3a2b1c3997..efeed00e50 100644--- a/docs/next.config.mjs+++ b/docs/next.config.mjs@@ -88,12 +88,12 @@ const config = {},{source: '/tutorials/your-first-cloud-sandbox',- destination: '/tutorials/your-first-cloud-fleet',+ destination: '/start-here/create-a-space-with-the-sdk',permanent: true,},{source: '/tutorials/your-first-local-sandbox',- destination: '/tutorials/your-first-cloud-fleet',+ destination: '/start-here/create-a-space-with-the-sdk',permanent: true,},{diff --git a/docs/scripts/product-structure.test.ts b/docs/scripts/product-structure.test.tsindex dbd0f331f2..db56b1dcbf 100644--- a/docs/scripts/product-structure.test.ts+++ b/docs/scripts/product-structure.test.ts@@ -14,8 +14,8 @@ const content = path.join(docs, 'content/docs');const PRODUCTS: Array<[string, string]> = [['cua-sdk', 'Cua SDK'],['cua-driver', 'Cua Driver'],- ['fleets', 'Cua Fleets'],['spaces', 'Cua Spaces'],+ ['fleets', 'Cua Fleets'],['cua-bench', 'Cua Bench'],['lume', 'Lume'],['cua-cli', 'Cua CLI'],diff --git a/docs/scripts/sandbox-navigation.test.ts b/docs/scripts/sandbox-navigation.test.tsindex cd07646391..27074c824b 100644--- a/docs/scripts/sandbox-navigation.test.ts+++ b/docs/scripts/sandbox-navigation.test.ts@@ -49,10 +49,10 @@ test('the Cua SDK has its task guides and one concept page', async () => {}});-test('the quickstart runs locally first and lists the images and benchmark images', async () => {+test('the quickstart runs locally and lists the images and benchmark images', async () => {const body = await readFile(path.join(content, 'cua-sdk/quickstart.mdx'), 'utf8');- const local = body.indexOf('<Tab value="Local">');- assert.ok(local > 0 && local < body.indexOf('<Tab value="Cloud">'), 'local before cloud');+ assert.ok(body.includes('<Tab value="Python">'), 'the quickstart leads with Python');+ assert.ok(!body.includes('local=False') && !body.includes('<Tab value="Cloud">'), 'local only');for (const ref of ['ghcr.io/trycua/linux:24.04','ghcr.io/trycua/linux:24.04-disk',diff --git a/docs/scripts/tests/test_unified_sandbox_docs.py b/docs/scripts/tests/test_unified_sandbox_docs.pyindex 306189fe06..f9ce2113b8 100644--- a/docs/scripts/tests/test_unified_sandbox_docs.py+++ b/docs/scripts/tests/test_unified_sandbox_docs.py@@ -1,4 +1,4 @@-"""One Cua SDK tree: every task page shows local and cloud with one API."""+"""One Cua SDK tree: task pages lead with local, which needs no `local=`."""from pathlib import Pathimport json@@ -7,8 +7,8 @@ import unittestDOCS = Path(__file__).resolve().parents[2] / "content" / "docs"-# Task pages whose code is the same local and cloud: each shows both sides,-# as Local/Cloud tabs or a snippet with a one-line `local=` comment.+# Task pages: local is the default, so their examples pass no `local=` and+# show no cloud variant (the cloud has its own guide).UNIFIED = ("cua-sdk/index","cua-sdk/quickstart",@@ -26,13 +26,13 @@ def page(slug: str) -> str:class UnifiedSandboxDocsTests(unittest.TestCase):- def test_task_pages_show_local_and_cloud(self):+ def test_task_pages_lead_with_local(self):for slug in UNIFIED:with self.subTest(slug=slug):text = page(slug)- tabs = "'Local', 'Cloud'" in text- both = "local=True" in text and ("local=False" in text or "local=True #" in text)- self.assertTrue(tabs or both, f"{slug} shows only one side")+ self.assertNotIn("'Local', 'Cloud'", text, f"{slug} has a cloud tab")+ self.assertNotIn("local=False", text, f"{slug} shows a cloud example")+ self.assertNotRegex(text, r"local=True[,)]", f"{slug} passes the default")def test_pages_stay_short(self):for folder in ("cua-sdk", "fleets"):diff --git a/scripts/docs-generators/examples/cua-sdk/python/Sandbox.create.py b/scripts/docs-generators/examples/cua-sdk/python/Sandbox.create.pyindex 861b296acf..8e9b36ae23 100644--- a/scripts/docs-generators/examples/cua-sdk/python/Sandbox.create.py+++ b/scripts/docs-generators/examples/cua-sdk/python/Sandbox.create.py@@ -1,7 +1,7 @@-# docs: test="docs" prelude="fakefleet"+# docs: test="container"import asyncio-from cua_sandbox import CloudOptions, Image, Sandbox, http+from cua_sandbox import Image, Sandbox, httpasync def main():@@ -10,8 +10,6 @@ async def main():command=["python", "-m", "http.server", "8000"],services={"web": 8000},wait_for=http("web", "/"),- local=False, # the cloud; omit it to run locally- cloud=CloudOptions(warm=False), # optional; implies the cloudcpu=2, memory="4GB",)print(sb.id)