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: 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.mdx
index 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 an
diff --git a/docs/content/docs/cua-bench/guides/benchmarks.mdx b/docs/content/docs/cua-bench/guides/benchmarks.mdx
index 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 own
with `--agent-import-path module:Class`. `--model` needs that provider's API
diff --git a/docs/content/docs/cua-bench/index.mdx b/docs/content/docs/cua-bench/index.mdx
index 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).
## Next
diff --git a/docs/content/docs/cua-bench/quickstart.mdx b/docs/content/docs/cua-bench/quickstart.mdx
index 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 yourself
diff --git a/docs/content/docs/cua-cli/quickstart.mdx b/docs/content/docs/cua-cli/quickstart.mdx
index 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 dev
cua sb rm desk
-cua sb rm dev-cloud # releases the cloud sandbox
```
## Next
diff --git a/docs/content/docs/cua-sdk/guides/agent-frameworks.mdx b/docs/content/docs/cua-sdk/guides/agent-frameworks.mdx
index 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 an
eligible, signed-in ChatGPT account. To let it take over a VM instead of your
desktop, 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, and
run `codex plugin add computer-use@openai-bundled`. Sign-in and approvals stay
interactive.
## 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 a
mode-`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 8GB
cua 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 8GB
cua sb view mc
cua 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.mdx
index 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 throwaway
profile 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 the
sandbox `id` and the `session`, `target_id` and `tab_id` every browser call
takes.
diff --git a/docs/content/docs/cua-sdk/guides/cloud.mdx b/docs/content/docs/cua-sdk/guides/cloud.mdx
index 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 -a
cua 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.mdx
index 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 Path
from 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 desk
cua sb screenshot desk -o desk.png
cua sb view desk # opens the desktop in the browser viewer
cua sb rm -f desk
@@ -80,10 +79,10 @@ cua sb rm -f desk
pip 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 program
pid = 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 ready
cua 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.mdx
index 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 desk
cua 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` for
cua sb create ghcr.io/acme/agent:1.4 \
--registry-secret env:CUA_REGISTRY_USERNAME:CUA_REGISTRY_PASSWORD
cua 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.mdx
index 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 lifecycle
description: 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`, and
in `~/.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 dev
cua sb ls # local and cloud; --local or --cloud filters
cua sb info dev
cua sb suspend dev && cua sb resume dev
diff --git a/docs/content/docs/cua-sdk/guides/services.mdx b/docs/content/docs/cua-sdk/guides/services.mdx
index 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 8000
cua 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.mdx
index 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, so
cannot share a network namespace, and the SDK refuses rather than switching
runtimes 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 sidecar
This 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.mdx
index 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.mdx
index 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 together
The 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 the
computer 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.mdx
index 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 and
install what is missing:
```bash test="cli-shape" id="cua-runtime-doctor"
@@ -24,13 +24,10 @@ cua runtime doctor
cua 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 8000
cua 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 cloud
image: '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.mdx
index 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 ra
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:python
Source: 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.mdx
index 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 of
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:python
Source: 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.mdx
index 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 DIRECTLY
Generated by: pnpm --dir docs docs:generate:python
Source: 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.mdx
index 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, files
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:python
Source: 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.mdx
index 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 DIRECTLY
Generated by: pnpm --dir docs docs:generate:python
Source: 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.mdx
index 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 emulato
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:python
Source: 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.mdx
index 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 option
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:python
Source: 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, http
async 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 cloud
cpu=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.mdx
index 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 endpoints
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
Generated by: pnpm --dir docs docs:generate:python
Source: 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.mdx
index 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 Developers
path: '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 Bots
description: 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.json
index 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.json
index 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.mdx
index 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 (local
unless 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 a
Space that is not ready yet.
@@ -173,7 +161,7 @@ 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).
+[`cua host setup`](/start-here/host-spaces-on-your-spare-mac).
`spaces.delete(id)` deletes a
Space'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.mdx
index 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 in
Cua 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.json
index 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.mdx
index 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 gets
diff --git a/docs/content/docs/spaces/guides/unattended-access.mdx b/docs/content/docs/spaces/guides/unattended-access.mdx
index 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.mdx
index 35f07527c7..afda4ef50f 100644
--- a/docs/content/docs/spaces/index.mdx
+++ b/docs/content/docs/spaces/index.mdx
@@ -1,12 +1,17 @@
---
title: Cua Spaces
description: '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 can
watch 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.mdx
new file mode 100644
index 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.mdx
similarity index 94%
rename from docs/content/docs/spaces/guides/host-spaces-on-your-spare-mac.mdx
rename to docs/content/docs/start-here/host-spaces-on-your-spare-mac.mdx
index 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 Mac
diff --git a/docs/content/docs/start-here/meta.json b/docs/content/docs/start-here/meta.json
index 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.mdx
index 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 | sh
cua sb create linux --name desk
cua 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.mdx
deleted file mode 100644
index 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
-```
-
-![The viewer showing a sandbox's XFCE desktop with a terminal open](/img/cua-sdk/viewer-terminal.png)
-
-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.mdx
index 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.mjs
index 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.ts
index 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.ts
index 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.py
index 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 Path
import json
@@ -7,8 +7,8 @@ import unittest
DOCS = 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.py
index 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, http
async 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 cloud
cpu=2, memory="4GB",
)
print(sb.id)