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: simplify navigation and restore Cua-Bench learning path (#2508)
Francesco Bonaccie98623e2400a
diff --git a/docs/content/docs/concepts/cua-bench-task-lifecycle.mdx b/docs/content/docs/concepts/cua-bench-task-lifecycle.mdxnew file mode 100644index 0000000000..5e6311f118--- /dev/null+++ b/docs/content/docs/concepts/cua-bench-task-lifecycle.mdx@@ -0,0 +1,73 @@+---+title: 'The Cua-Bench task lifecycle'+description: 'Understand how task variants, setup, solutions, and evaluators form a repeatable experiment.'+---++A Cua-Bench task is a repeatable experiment, not only a natural-language+instruction. It combines the state an agent starts from, the interface it can+operate, and the evidence used to score the result.++## One definition, many variants++The task configuration returns one or more variants. Every variant has its own+prompt and may carry different metadata, provider settings, operating-system+theme, or initial state.++Variants let a benchmark change inputs without duplicating its setup and+evaluation code. An agent can therefore face the same underlying skill across+different labels, layouts, or operating systems.++## Four lifecycle functions++A task module describes four distinct phases:++1. **Configuration** returns the task variants available for a dataset split.+2. **Setup** prepares the selected variant and opens the applications or+ interface the agent will use.+3. **Solve** provides an optional oracle: a known procedure that exercises the+ task and checks whether the environment can produce a successful result.+4. **Evaluate** inspects final state and returns one or more rewards.++Configuration is shared while setup, solving, and evaluation operate on one+selected variant and its session.++## Why the oracle and evaluator are separate++The oracle describes one way to reach the goal. The evaluator defines what+counts as reaching it. Keeping them separate prevents a benchmark from scoring+an agent by whether it copied one prescribed sequence of clicks.++The same evaluator can score an oracle, a human attempt, or an agent+trajectory. An oracle reward below the expected score usually indicates a task+or environment problem rather than an agent-quality result.++## Providers and sessions++The provider in a variant's computer configuration determines where the task+runs:++- a **simulated** provider renders a lightweight desktop through Playwright;+- a **native** provider supplies a real operating-system environment through+ the configured container or virtual-machine platform.++Setup, solve, and evaluate functions receive a session interface. The task uses+that interface to open windows, execute input actions, capture screenshots, or+read state needed for evaluation. This keeps the lifecycle consistent while+the underlying environment changes.++## From one task to a benchmark++A dataset groups task definitions. The runner expands their variants, assigns+them to environments, records their results, and aggregates rewards. Traces+preserve the observations and actions from individual sessions so failures can+be inspected after the run.++The benchmark score is therefore the end of a chain:++```text+dataset → task → variant → environment session → trajectory → evaluator → reward+```++The [task definition reference](/reference/cua-bench/task-definition) describes+the exact Python contract. To see the lifecycle operate end to end, build+[your first Cua-Bench task](/tutorials/your-first-cua-bench-task).diff --git a/docs/content/docs/concepts/how-cua-driver-is-validated.mdx b/docs/content/docs/concepts/how-cua-driver-is-validated.mdxindex 9030a34ba6..c3c8e54024 100644--- a/docs/content/docs/concepts/how-cua-driver-is-validated.mdx+++ b/docs/content/docs/concepts/how-cua-driver-is-validated.mdx@@ -1,6 +1,6 @@----title: 'How Cua Driver Is Validated'-description: 'Why Cua Driver uses source-built desktop harnesses, independent application oracles, and retained evidence to validate behavior between releases.'+title: 'How we continuously validate Cua Driver'+description: 'How source-built desktop harnesses, independent application oracles, and retained evidence validate Cua Driver between releases.'---Desktop automation crosses boundaries that ordinary unit tests cannot observe.diff --git a/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx b/docs/content/docs/concepts/how-lume-unattended-setup-works.mdxindex 29507d286a..f66537bd37 100644--- a/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx+++ b/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx@@ -1,6 +1,6 @@----title: How Lume prepares vanilla macOS VMs-description: Understand the offline setup flow behind Lume's unattended macOS VMs.+title: How Lume creates local macOS sandboxes+description: How Lume turns Apple restore images into unattended local macOS sandboxes.---Lume creates vanilla macOS VMs from Apple restore images. The unattended setupdiff --git a/docs/content/docs/concepts/how-sandboxes-work.mdx b/docs/content/docs/concepts/how-sandboxes-work.mdxindex f4ba2461ec..82eb6f7fa2 100644--- a/docs/content/docs/concepts/how-sandboxes-work.mdx+++ b/docs/content/docs/concepts/how-sandboxes-work.mdx@@ -57,10 +57,8 @@ Snapshots are useful when setup is expensive. Packages can be installed once, moEach *fork* starts from the same snapshot but gets its own writable disk. Changes in one fork do not affect the snapshot or sibling forks. On copy-on-write storage, forks can be near-instant because unchanged blocks are shared until a sandbox writes to them.-## Cloud and local execution+## Local execution-The same lifecycle concepts apply in local mode and cloud mode. The sandbox still starts from an `Image`, exposes a code half and a GUI half, can be ephemeral or persistent, and can be snapshotted or deleted.+Local mode runs on the developer's hardware. Linux containers use Docker Desktop, macOS VMs use Lume, and VM backends can use QEMU or Hyper-V. Local execution depends on the machine's available CPU, memory, disk, and virtualization support. Select it with `local=True`.-Local mode runs on the developer's hardware. Linux containers use Docker Desktop, macOS VMs use Lume, and VM backends can use QEMU. Local execution depends on the machine's available CPU, memory, disk, and virtualization support. Local mode is selected with `local=True`.--Cloud mode runs managed VMs on Cua infrastructure with the same API surface. Provisioning, placement, and capacity are handled by the service. Cloud mode uses a Cua API key through `CUA_API_KEY`.+The sandbox still starts from an `Image`, exposes a code half and a GUI half, and can be ephemeral or persistent. Start with [Your first local sandbox](/tutorials/your-first-local-sandbox).diff --git a/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdx b/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdxindex 28615c19e3..81ff6c82f8 100644--- a/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdx+++ b/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdx@@ -76,5 +76,5 @@ files.## Related pages- [Change SIP on a macOS VM](/how-to-guides/lume/change-sip)-- [How Lume prepares vanilla macOS VMs](/concepts/how-lume-unattended-setup-works)+- [How Lume creates local macOS sandboxes](/concepts/how-lume-unattended-setup-works)- [Lume limits](/reference/lume/limits#sip-automation)diff --git a/docs/content/docs/concepts/index.mdx b/docs/content/docs/concepts/index.mdxindex 37cd8a7fe9..6e7b9dba98 100644--- a/docs/content/docs/concepts/index.mdx+++ b/docs/content/docs/concepts/index.mdx@@ -3,6 +3,6 @@ title: "Concepts"description: "Understand the design ideas behind Cua and how its main pieces fit together."----Use these pages when you want the model behind Cua rather than a step-by-step guide or API table. They explain what computer use means in Cua, how Cua Driver keeps the desktop usable while it acts, and how Cua Sandbox gives an agent a disposable computer.+Use these pages when you want the model behind Cua rather than a step-by-step guide or API table. They explain what computer use means in Cua, how Cua Driver keeps the desktop usable while it acts, and how Cua Sandbox gives an agent a disposable local computer.-Start with [What is computer use?](/concepts/what-is-computer-use) for the basic model. Read [Best-effort background](/concepts/the-no-foreground-contract) to understand Cua Driver's default behavior on a shared machine, then [Capture and delivery modalities](/concepts/capture-and-delivery-modalities) for the action axes. [How Cua Driver is validated](/concepts/how-cua-driver-is-validated) explains why desktop support requires application-owned E2E evidence in addition to unit tests. Read [How sandboxes work](/concepts/how-sandboxes-work) when you need the model for disposable computers. Read [How Lume prepares vanilla macOS VMs](/concepts/how-lume-unattended-setup-works) for the local VM setup model, and [How SIP works in Lume VMs](/concepts/how-sip-works-in-lume-vms) for signed boot-policy changes.+Start with [What is computer use?](/concepts/what-is-computer-use) for the basic model. Read [Best-effort background](/concepts/the-no-foreground-contract) to understand Cua Driver's default behavior on a shared machine, then [Capture and delivery modalities](/concepts/capture-and-delivery-modalities) for the action axes. [How we continuously validate Cua Driver](/concepts/how-cua-driver-is-validated) explains why desktop support requires application-owned E2E evidence in addition to unit tests. Read [How sandboxes work](/concepts/how-sandboxes-work) when you need the model for disposable computers. Read [How Lume creates local macOS sandboxes](/concepts/how-lume-unattended-setup-works) for the local VM setup model, and [How SIP works in Lume VMs](/concepts/how-sip-works-in-lume-vms) for signed boot-policy changes. For evaluation, start with [What is Cua-Bench?](/concepts/what-is-cua-bench), then read [The Cua-Bench task lifecycle](/concepts/cua-bench-task-lifecycle).diff --git a/docs/content/docs/concepts/meta.json b/docs/content/docs/concepts/meta.jsonindex 3f8d28bbdb..030f917219 100644--- a/docs/content/docs/concepts/meta.json+++ b/docs/content/docs/concepts/meta.json@@ -4,15 +4,21 @@"pages": ["index","what-is-computer-use",+ "---Cua Driver---","sdk-mcp-and-hosting","the-no-foreground-contract","capture-and-delivery-modalities","browser-targeting-and-background-delivery","how-permission-policies-work","how-cua-driver-is-validated",+ "---Cua Sandbox---","how-sandboxes-work",+ "---Lume---","how-lume-unattended-setup-works","how-sip-works-in-lume-vms",- "how-lume-expands-macos-disks"+ "how-lume-expands-macos-disks",+ "---Cua-Bench---",+ "what-is-cua-bench",+ "cua-bench-task-lifecycle"]}diff --git a/docs/content/docs/concepts/what-is-computer-use.mdx b/docs/content/docs/concepts/what-is-computer-use.mdxindex ae0fa113d3..5aaa8a7869 100644--- a/docs/content/docs/concepts/what-is-computer-use.mdx+++ b/docs/content/docs/concepts/what-is-computer-use.mdx@@ -37,7 +37,7 @@ You bring the agent, which already handles coding and tool-use on its own. Cua g**Cua Driver** drives the GUI of a real machine you already have, whether that machine runs macOS, Windows, or Linux. It is the right shape when the agent needs to work with local applications, signed-in accounts, existing files, or machine state that already lives on that computer.-**Cua Sandbox** is a fresh isolated cloud computer where the agent can run code and drive the GUI together. It is a full computer with all three action surfaces available inside the same environment rather than a remote desktop, which matters when the task needs both programmatic work and visible interaction without touching your local machine. The agent brings the model and its reasoning; Cua provides the computer where that reasoning can turn into action.+**Cua Sandbox** is a fresh isolated computer running on local Docker or VM infrastructure where the agent can run code and drive the GUI together. It is a full computer with all three action surfaces available inside the same environment rather than a remote desktop, which matters when the task needs both programmatic work and visible interaction without changing the host desktop. The agent brings the model and its reasoning; Cua provides the computer where that reasoning can turn into action.## Safety and isolation@@ -47,6 +47,6 @@ Cua Driver exposes [permission policies](/concepts/how-permission-policies-work)## Start building-- [Drive your first application](/tutorials/drive-your-first-app) on an existing macOS, Windows, or Linux computer.-- [Start your first cloud sandbox](/tutorials/your-first-cloud-sandbox) for an isolated Linux computer.+- [Drive your first app with Cua Driver](/tutorials/drive-your-first-app) on an existing macOS, Windows, or Linux computer.+- [Start your first local sandbox](/tutorials/your-first-local-sandbox) for an isolated Linux computer.- [Install Cua Driver](/how-to-guides/driver/install) and connect it to an agent you already use.diff --git a/docs/content/docs/cuabench/index.mdx b/docs/content/docs/concepts/what-is-cua-bench.mdxsimilarity index 100%rename from docs/content/docs/cuabench/index.mdxrename to docs/content/docs/concepts/what-is-cua-bench.mdxdiff --git a/docs/content/docs/cuabench/meta.json b/docs/content/docs/how-to-guides/cua-bench/meta.jsonsimilarity index 51%rename from docs/content/docs/cuabench/meta.jsonrename to docs/content/docs/how-to-guides/cua-bench/meta.jsonindex 2aa0c8d7cd..8bf52bf367 100644--- a/docs/content/docs/cuabench/meta.json+++ b/docs/content/docs/how-to-guides/cua-bench/meta.json@@ -1,4 +1,4 @@{"title": "Cua-Bench",- "pages": ["index"]+ "pages": ["run-a-task"]}diff --git a/docs/content/docs/how-to-guides/cua-bench/run-a-task.mdx b/docs/content/docs/how-to-guides/cua-bench/run-a-task.mdxnew file mode 100644index 0000000000..b6717b8861--- /dev/null+++ b/docs/content/docs/how-to-guides/cua-bench/run-a-task.mdx@@ -0,0 +1,81 @@+---+title: 'Run and validate a Cua-Bench task'+description: 'Inspect a task, verify its oracle, and exercise a variant manually.'+---++Use this guide to validate an existing task before running it with an agent or+including it in a dataset.++## Before you start++- Install Cua-Bench and any dependencies required by the task's provider.+- Have a local task directory containing `main.py`.++## Inspect the task++Load the task before starting an environment:++```bash+cb task info <task-path>+```++Confirm:++- the provider and operating-system types are the ones you expect;+- the selected variant exists;+- setup and evaluation show check marks;+- solve shows a check mark when the task is supposed to include an oracle.++## Verify the oracle and evaluator++Run the selected variant with its oracle and close it after evaluation:++```bash+cb interact <task-path> \+ --variant-id 0 \+ --oracle \+ --no-wait+```++Check the reported evaluation result against the reward the task considers+successful. A failed oracle is a task or environment validation failure; do not+use that result as an agent score.++## Exercise the task manually++```bash+cb interact <task-path> --variant-id 0+```++Complete the task in its visible environment. Return to the terminal and press+Enter to evaluate and close it.++## Check additional variants++Repeat the oracle check for each variant:++```bash+cb interact <task-path> --variant-id <variant> --oracle --no-wait+```++Changing only `--variant-id` exercises the same lifecycle functions with the+selected variant's prompt, metadata, and computer configuration.++## Troubleshooting++### Playwright reports that the browser executable is missing++For a simulated task, install Chromium in the same environment as Cua-Bench:++```bash+uv tool run --from 'cua-bench[browser]' playwright install chromium+```++### A lifecycle function is missing++Confirm that the task's `main.py` decorates each function with the same split.+Refer to the [task definition reference](/reference/cua-bench/task-definition)+for the supported decorators and signatures.++If you have not created a task before, follow+[Build your first Cua-Bench task](/tutorials/your-first-cua-bench-task).diff --git a/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx b/docs/content/docs/how-to-guides/driver/connect-your-agent.mdxindex 05aaa8bd6e..bb9b14a28b 100644--- a/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx+++ b/docs/content/docs/how-to-guides/driver/connect-your-agent.mdx@@ -8,7 +8,7 @@ import { Callout } from 'fumadocs-ui/components/callout';`cua-driver mcp` runs Cua Driver as a stdio MCP server. Register it when you want an MCP-capable [computer-use agent](/concepts/what-is-computer-use) to drive the **host desktop**: installed apps, signed-in browser sessions, local files opened in apps, and the current OS user session.<Callout type="info">- This connects an agent to Cua Driver on the current machine. To create disposable cloud desktops, use [Cua Sandbox](/tutorials/your-first-cloud-sandbox) instead.+ This connects an agent to Cua Driver on the current machine. To create a disposable local desktop, use [Cua Sandbox](/tutorials/your-first-local-sandbox) instead.</Callout>## Before you startdiff --git a/docs/content/docs/how-to-guides/driver/meta.json b/docs/content/docs/how-to-guides/driver/meta.jsonindex 7f82667d2b..74ef9eba77 100644--- a/docs/content/docs/how-to-guides/driver/meta.json+++ b/docs/content/docs/how-to-guides/driver/meta.json@@ -3,6 +3,7 @@"pages": ["install","use-sdk-in-process",+ "verify-a-desktop-action","use-claude-agent-sdk","use-codex-sdk","expose-mcp-from-desktop-app",diff --git a/docs/content/docs/how-to-guides/driver/record-and-render-a-trajectory.mdx b/docs/content/docs/how-to-guides/driver/record-and-render-a-trajectory.mdxindex 0f498bbc3e..b10b88bd19 100644--- a/docs/content/docs/how-to-guides/driver/record-and-render-a-trajectory.mdx+++ b/docs/content/docs/how-to-guides/driver/record-and-render-a-trajectory.mdx@@ -3,7 +3,6 @@ title: Record and render a Cua Driver trajectorydescription: Capture an agent's Cua Driver actions and turn the trajectory into a zoom-on-click MP4.----import { Callout } from 'fumadocs-ui/components/callout';import { Steps, Step } from 'fumadocs-ui/components/steps';Record an agent-driven task when you need both the action evidence and a short product demo. Cua Driver saves each action with before-and-after state, screenshots, and arguments. With video enabled, it also captures the display so you can render the trajectory with zoom effects around each action.@@ -18,12 +17,6 @@ Record an agent-driven task when you need both the action evidence and a short pfocused product demo.</VideoDemo>-<Callout type="info">- This guide records an agent's Cua Driver actions. To record a task you perform by hand over VNC- and turn it into a reusable skill, see [Record a demonstration as a- skill](/how-to-guides/skills/record-a-demonstration).-</Callout>-## Before you start- [Install Cua Driver](/how-to-guides/driver/install) and [connect your agent](/how-to-guides/driver/connect-your-agent).@@ -56,10 +49,6 @@ sudo apt install ffmpegThe recording directory will contain one `turn-NNNNN` folder for each action and a display capture named `recording.mp4`.- <Callout type="warn">- `cua-driver recording start` records per-action evidence but does not enable display video. Use the MCP tool with `record_video: true` when you plan to render an MP4.- </Callout>-</Step><Step>diff --git a/docs/content/docs/tutorials/verify-a-desktop-action-with-cua-driver.mdx b/docs/content/docs/how-to-guides/driver/verify-a-desktop-action.mdxsimilarity index 85%rename from docs/content/docs/tutorials/verify-a-desktop-action-with-cua-driver.mdxrename to docs/content/docs/how-to-guides/driver/verify-a-desktop-action.mdxindex b0575fbf1d..b9e995eccd 100644--- a/docs/content/docs/tutorials/verify-a-desktop-action-with-cua-driver.mdx+++ b/docs/content/docs/how-to-guides/driver/verify-a-desktop-action.mdx@@ -1,13 +1,13 @@----title: 'Verify a desktop action with Cua Driver'-description: 'Build a deterministic perceive, act, and verify loop in Python or TypeScript.'+title: 'Verify a desktop action'+description: 'Check a Python or TypeScript desktop action against an independent postcondition.'---import { Tabs, Tab } from 'fumadocs-ui/components/tabs';-In this tutorial, you will capture the desktop, enter a unique value in a local-browser fixture, and prove that the page received it. The proof comes from a-loopback state endpoint, not from trusting the action response.+Use this guide to capture the desktop, enter a unique value in a local browser+fixture, and prove that the page received it. A loopback state endpoint provides+the proof independently from the action response.## Get the examplediff --git a/docs/content/docs/how-to-guides/index.mdx b/docs/content/docs/how-to-guides/index.mdxindex b81b8e7f84..59af927eca 100644--- a/docs/content/docs/how-to-guides/index.mdx+++ b/docs/content/docs/how-to-guides/index.mdx@@ -5,4 +5,4 @@ description: 'Follow recipes for specific Cua goals.'How-to guides are recipes for **a specific goal**. They assume you already know the basics, so do a tutorial first if not. Unlike tutorials, they are *not a lesson*; they get you to a result and stop.-They are grouped by surface: Cua Driver for operating apps on a real machine, sandbox for cloud desktops, Lume for local Apple Silicon VMs, plus recipes, skills, and agent context.+They are grouped by product: Cua Driver for operating apps on a physical machine, Sandbox for isolated local desktops, Lume for local Apple silicon VMs, and Cua-Bench for verifiable computer-use tasks. Recipes and agent context cover workflows that span those products.diff --git a/docs/content/docs/how-to-guides/lume/install-lume.mdx b/docs/content/docs/how-to-guides/lume/install-lume.mdxindex 400baecb53..25040b9d91 100644--- a/docs/content/docs/how-to-guides/lume/install-lume.mdx+++ b/docs/content/docs/how-to-guides/lume/install-lume.mdx@@ -3,7 +3,7 @@ title: Install and run Lumedescription: Install Lume, Cua's local Apple Silicon VM manager for macOS and Linux guests.----Lume is Cua's local VM manager for Apple Silicon Macs. Use it when you want to create, run, or serve macOS and Linux VMs on your own machine. It can provide local VM substrate for Cua workflows, but the primary product choice is still [Cua Driver](/tutorials/drive-your-first-app) for an existing machine or [Cua Sandbox](/tutorials/your-first-cloud-sandbox) for a fresh isolated desktop.+Lume is Cua's local VM manager for Apple Silicon Macs. Use it when you want to create, run, or serve macOS and Linux VMs on your own machine. It can provide local VM substrate for Cua workflows, but the primary product choice is still [Cua Driver](/tutorials/drive-your-first-app) for an existing machine or [Cua Sandbox](/tutorials/your-first-local-sandbox) for a fresh isolated desktop.## Requirementsdiff --git a/docs/content/docs/how-to-guides/meta.json b/docs/content/docs/how-to-guides/meta.jsonindex a82e2f23e8..fc104ae3e5 100644--- a/docs/content/docs/how-to-guides/meta.json+++ b/docs/content/docs/how-to-guides/meta.json@@ -6,8 +6,8 @@"driver","sandbox","lume",+ "cua-bench","recipes",- "skills","agent-context"]}diff --git a/docs/content/docs/how-to-guides/recipes/automate-a-legacy-windows-app-behind-a-vpn.mdx b/docs/content/docs/how-to-guides/recipes/automate-a-legacy-windows-app-behind-a-vpn.mdxindex 37370e6247..b72c99656c 100644--- a/docs/content/docs/how-to-guides/recipes/automate-a-legacy-windows-app-behind-a-vpn.mdx+++ b/docs/content/docs/how-to-guides/recipes/automate-a-legacy-windows-app-behind-a-vpn.mdx@@ -79,6 +79,6 @@ When a desktop app has **no API** and only runs **behind the corporate VPN**, dr## Scale this out-When the same workflow must run across many employees, regions, or tenants at once, move it onto **Cua Sandbox** cloud Windows desktops and fan out the jobs. Start with [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out) and [Your first cloud sandbox](/tutorials/your-first-cloud-sandbox).+When the same workflow must run concurrently, use local Cua Sandbox Windows VMs and cap concurrency to the resources available on the host. Start with [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out) and [Your first local sandbox](/tutorials/your-first-local-sandbox).-The driving logic stays the same. The host changes from your VPN-connected Windows box to a fleet of cloud desktops with the VPN configuration baked into the image. See [Choose and build a sandbox image](/how-to-guides/sandbox/images).+The driving logic stays the same. Each local Windows VM needs the VPN configuration and application included in its starting image. See [Choose and build a sandbox image](/how-to-guides/sandbox/images).diff --git a/docs/content/docs/how-to-guides/recipes/build-a-report-in-a-native-app.mdx b/docs/content/docs/how-to-guides/recipes/build-a-report-in-a-native-app.mdxindex c16832a178..31053ee848 100644--- a/docs/content/docs/how-to-guides/recipes/build-a-report-in-a-native-app.mdx+++ b/docs/content/docs/how-to-guides/recipes/build-a-report-in-a-native-app.mdx@@ -9,7 +9,7 @@ import { Steps, Step } from 'fumadocs-ui/components/steps';Numbers is a **macOS-only** app with **no clean automation API** for building a spreadsheet, charting it, and exporting a polished PDF. With Cua Driver, the agent drives the *real Numbers app on a real Mac*, the same way a person would, through the GUI.<Callout type="warn">- This recipe is macOS-only. Numbers, Keynote, and Pages do not exist on Linux or Windows, so you need a real Mac now, or a cloud macOS desktop later.+ This recipe is macOS-only. Numbers, Keynote, and Pages do not exist on Linux or Windows, so use a real Mac or a local macOS VM.</Callout><Callout type="info">@@ -70,8 +70,8 @@ Numbers is a **macOS-only** app with **no clean automation API** for building a## Scale this out-One Mac builds one Numbers report at a time. To generate many reports at once, for example one per ticker, client, or reporting period, move the same workflow onto **Cua Sandbox** cloud macOS desktops and fan them out.+One Mac builds one Numbers report at a time. To generate several reports concurrently, run the workflow in local macOS sandboxes backed by Lume and limit concurrency to the CPU and memory available on the host.-Use [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out) to run the jobs concurrently, [Choose and build a sandbox image](/how-to-guides/sandbox/images) to bake Numbers and any helper tools into the macOS image, and [Your first cloud sandbox](/tutorials/your-first-cloud-sandbox) for the basic SDK lifecycle.+Use [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out) to run the jobs concurrently, [Choose and build a sandbox image](/how-to-guides/sandbox/images) to prepare Numbers and any helper tools, and [Local macOS sandboxes with Lume](/tutorials/create-your-first-lume-vm) for the VM foundation.-A cloud macOS desktop is the only way to scale Numbers automation, since Numbers cannot run on Linux containers.+Numbers cannot run in Linux containers, so each concurrent worker needs its own local macOS VM.diff --git a/docs/content/docs/how-to-guides/recipes/export-contacts-overnight.mdx b/docs/content/docs/how-to-guides/recipes/export-contacts-overnight.mdxindex 80aa407b52..cf8542d46c 100644--- a/docs/content/docs/how-to-guides/recipes/export-contacts-overnight.mdx+++ b/docs/content/docs/how-to-guides/recipes/export-contacts-overnight.mdx@@ -65,6 +65,6 @@ Kick off the task before you leave. In the morning, open `~/contacts.csv` and sp## Scale this out-One logged-in browser profile handles one account at a time. To process many accounts, events, or platforms in parallel overnight, move each authenticated session into its own **Cua Sandbox** cloud desktop. Log in once per sandbox, persist the session in the image, then fan the jobs out.+One logged-in browser profile handles one account at a time. To process several accounts, events, or platforms in parallel overnight, use one local Cua Sandbox per authenticated session and cap concurrency to the resources available on the host.-Use [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out) to run many desktops at once, [Images](/how-to-guides/sandbox/images) to bake the logged-in session into an image, and [Your first cloud sandbox](/tutorials/your-first-cloud-sandbox) for the basic SDK lifecycle.+Use [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out) to run several local desktops, [Images](/how-to-guides/sandbox/images) to prepare their starting state, and [Your first local sandbox](/tutorials/your-first-local-sandbox) for the basic SDK lifecycle.diff --git a/docs/content/docs/how-to-guides/recipes/fill-a-form-from-a-local-file.mdx b/docs/content/docs/how-to-guides/recipes/fill-a-form-from-a-local-file.mdxindex a6c2c8f16e..77a1381ca2 100644--- a/docs/content/docs/how-to-guides/recipes/fill-a-form-from-a-local-file.mdx+++ b/docs/content/docs/how-to-guides/recipes/fill-a-form-from-a-local-file.mdx@@ -55,6 +55,6 @@ Use this recipe when the data already lives on your machine, for example in a PD## Scale this out-One desktop fills one form at a time. To submit many forms in parallel, for example one per CSV row or one per applicant, move the same workflow onto **Cua Sandbox** cloud desktops. Drop each source file into its own sandbox, start one agent job per sandbox, and fan the jobs out.+One desktop fills one form at a time. To submit several forms in parallel, for example one per CSV row or one per applicant, run one local Cua Sandbox per job and cap concurrency to the resources available on the host.-Use [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out) to run many jobs concurrently. Use [Choose and build a sandbox image](/how-to-guides/sandbox/images) to stage the source files in an image or mount them into each sandbox. Use [Your first cloud sandbox](/tutorials/your-first-cloud-sandbox) for the basic SDK lifecycle.+Use [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out) to run the jobs concurrently. Use [Choose and build a sandbox image](/how-to-guides/sandbox/images) to stage the source files in an image or mount them into each sandbox. Use [Your first local sandbox](/tutorials/your-first-local-sandbox) for the basic SDK lifecycle.diff --git a/docs/content/docs/how-to-guides/sandbox/interactive-shell.mdx b/docs/content/docs/how-to-guides/sandbox/interactive-shell.mdxindex 3be4ec9c1a..f4b0e6d8d6 100644--- a/docs/content/docs/how-to-guides/sandbox/interactive-shell.mdx+++ b/docs/content/docs/how-to-guides/sandbox/interactive-shell.mdx@@ -35,7 +35,7 @@ Create a sandbox, open a PTY session with `sb.terminal.create`, send input as te```pythonfrom cua import Sandbox, Image-async with Sandbox.ephemeral(Image.linux()) as sb:+async with Sandbox.ephemeral(Image.linux(), local=True) as sb:session = await sb.terminal.create(cols=80, rows=24)pid = session['pid']diff --git a/docs/content/docs/how-to-guides/sandbox/lifecycle.mdx b/docs/content/docs/how-to-guides/sandbox/lifecycle.mdxindex 5fccab22df..20973a8cc3 100644--- a/docs/content/docs/how-to-guides/sandbox/lifecycle.mdx+++ b/docs/content/docs/how-to-guides/sandbox/lifecycle.mdx@@ -16,7 +16,7 @@ import asynciofrom cua import Sandbox, Imageasync def main():- async with Sandbox.ephemeral(Image.linux()) as sb:+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:result = await sb.shell.run('echo hello')print(result.stdout) # 'hello\n'# sandbox deleted here@@ -31,7 +31,7 @@ asyncio.run(main())Use `Sandbox.create` when the sandbox **must outlive the script**. Call `await sb.disconnect()` to drop the connection while the sandbox keeps running.```python-sb = await Sandbox.create(Image.linux(), name='my-dev-sandbox')+sb = await Sandbox.create(Image.linux(), name='my-dev-sandbox', local=True)await sb.shell.run('apt-get install -y vim')await sb.disconnect() # sandbox keeps running```@@ -39,7 +39,7 @@ await sb.disconnect() # sandbox keeps runningDelete the sandbox when you are done with it.```python-async with Sandbox.connect('my-dev-sandbox') as sb:+async with Sandbox.connect('my-dev-sandbox', local=True) as sb:await sb.destroy()```@@ -60,7 +60,7 @@ Use `Sandbox.connect` to attach to an already-running sandbox.Reconnect by name.```python-async with Sandbox.connect('my-dev-sandbox') as sb:+async with Sandbox.connect('my-dev-sandbox', local=True) as sb:result = await sb.shell.run('vim --version')print(result.stdout)```@@ -68,7 +68,7 @@ async with Sandbox.connect('my-dev-sandbox') as sb:`Sandbox.connect` supports both `await` and `async with`. Its context manager calls `disconnect()` automatically, so the sandbox keeps running after the connection closes.```python-async with Sandbox.connect('my-sandbox') as sb:+async with Sandbox.connect('my-sandbox', local=True) as sb:await sb.shell.run('echo reconnected')# connection dropped, sandbox keeps running```@@ -78,26 +78,20 @@ async with Sandbox.connect('my-sandbox') as sb:List available sandboxes, then filter to local runtimes when needed.```python-sandboxes = await Sandbox.list()+sandboxes = await Sandbox.list(local=True)for info in sandboxes:print(info.name, info.os_type, info.status)--# list only local sandboxes-sandboxes = await Sandbox.list(local=True)```-## Cloud vs local--Use cloud by default. Set `CUA_API_KEY` in the environment before creating cloud sandboxes.--```python-# cloud (default)-async with Sandbox.ephemeral(Image.linux()) as sb: ...-```+## Choose a local runtime-Pass `local=True` for local runtimes such as Docker, Lume, or QEMU.+Pass `local=True` to use a runtime on your own machine. Cua selects a compatible local runtime from the image type: Docker for Linux containers, QEMU for Linux VMs, Lume for macOS VMs, and QEMU or Hyper-V for Windows VMs.```python-# local Docker-async with Sandbox.ephemeral(Image.linux(), local=True) as sb: ...+# local Docker desktop container+async with Sandbox.ephemeral(+ Image.linux(kind='container'),+ local=True,+) as sb:+ ...```diff --git a/docs/content/docs/how-to-guides/sandbox/meta.json b/docs/content/docs/how-to-guides/sandbox/meta.jsonindex 323fc062b9..37fe58712f 100644--- a/docs/content/docs/how-to-guides/sandbox/meta.json+++ b/docs/content/docs/how-to-guides/sandbox/meta.json@@ -1 +1 @@-{ "title": "Sandbox", "pages": ["lifecycle", "snapshots", "secrets", "scale-out", "tunneling", "images", "interactive-shell"] }+{ "title": "Sandbox", "pages": ["lifecycle", "secrets", "scale-out", "tunneling", "images", "interactive-shell"] }diff --git a/docs/content/docs/how-to-guides/sandbox/scale-out.mdx b/docs/content/docs/how-to-guides/sandbox/scale-out.mdxindex c9e604d01c..a49f4745b7 100644--- a/docs/content/docs/how-to-guides/sandbox/scale-out.mdx+++ b/docs/content/docs/how-to-guides/sandbox/scale-out.mdx@@ -8,7 +8,7 @@ import { Callout } from 'fumadocs-ui/components/callout';Because `Sandbox.ephemeral` and `Sandbox.create` are async, you can **run many sandboxes at the same time** using `asyncio`.<Callout type="info">- Cloud sandboxes are billed per second of runtime. Running many sandboxes in parallel incurs charges proportional to wall-clock time times number of sandboxes. Use local=True during development to avoid costs.+ Every local sandbox consumes host CPU, memory, and disk. Start with low concurrency and increase it only after observing host resource use.</Callout>## Run a fixed set concurrently@@ -20,7 +20,7 @@ import asynciofrom cua import Sandbox, Imageasync def run_task(task: str) -> str:- async with Sandbox.ephemeral(Image.linux()) as sb:+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:result = await sb.shell.run(f"echo '{task}'")return result.stdout.strip()@@ -44,7 +44,7 @@ MAX_CONCURRENT = 5async def process_item(sem: asyncio.Semaphore, item: str) -> dict:async with sem:- async with Sandbox.ephemeral(Image.linux()) as sb:+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:result = await sb.shell.run(f"python /app/process.py '{item}'")return {'item': item, 'output': result.stdout, 'ok': result.success}@@ -70,7 +70,7 @@ async def worker(queue: asyncio.Queue, worker_id: int):task = await queue.get()if task is None:break- async with Sandbox.ephemeral(Image.linux()) as sb:+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:result = await sb.shell.run(task)print(f'[worker-{worker_id}] {result.stdout.strip()}')queue.task_done()diff --git a/docs/content/docs/how-to-guides/sandbox/secrets.mdx b/docs/content/docs/how-to-guides/sandbox/secrets.mdxindex 0cb7aa629e..a61dbc7ad6 100644--- a/docs/content/docs/how-to-guides/sandbox/secrets.mdx+++ b/docs/content/docs/how-to-guides/sandbox/secrets.mdx@@ -7,15 +7,6 @@ import { Callout } from 'fumadocs-ui/components/callout';Pass secrets from the host environment into a sandbox **at runtime**, and keep image metadata for non-sensitive configuration.-## Set the Cua API key--The Cua API key is read from CUA_API_KEY environment variable. You can also pass it explicitly:--```python-async with Sandbox.ephemeral(Image.linux(), api_key=my_key) as sb:- ...-```-## Inject secrets at runtimeRead secrets from the host environment, then inject them into the sandbox with `sb.shell.run`.@@ -29,7 +20,7 @@ async def main():db_url = os.environ['DATABASE_URL']gh_token = os.environ['GITHUB_TOKEN']- async with Sandbox.ephemeral(Image.linux()) as sb:+ async with Sandbox.ephemeral(Image.linux(), local=True) as sb:await sb.shell.run(f"export DATABASE_URL='{db_url}'")await sb.shell.run(f"export GITHUB_TOKEN='{gh_token}'")await sb.shell.run('python /app/main.py')@@ -73,7 +64,7 @@ img = (Copy SSH keys, certificates, and other secret files into the sandbox at runtime, then set file permissions.```python-async with Sandbox.ephemeral(Image.linux()) as sb:+async with Sandbox.ephemeral(Image.linux(), local=True) as sb:with open(os.path.expanduser('~/.ssh/id_rsa')) as f:key_content = f.read()await sb.shell.run('mkdir -p /root/.ssh && chmod 700 /root/.ssh')diff --git a/docs/content/docs/how-to-guides/sandbox/snapshots.mdx b/docs/content/docs/how-to-guides/sandbox/snapshots.mdxdeleted file mode 100644index 30f4f0c7fd..0000000000--- a/docs/content/docs/how-to-guides/sandbox/snapshots.mdx+++ /dev/null@@ -1,87 +0,0 @@-----title: 'Take and restore snapshots'-description: Capture a sandbox disk state and fork fresh sandboxes from that point.------import { Callout } from 'fumadocs-ui/components/callout';--A *snapshot* captures the **full disk state** of a running sandbox and returns a new Image that you can pass to Sandbox.ephemeral() or Sandbox.create() to start a fresh sandbox from that point.--## Snapshot and restore--<Callout type="info">- Snapshots are currently supported on Cua Cloud sandboxes. Local sandboxes (Docker, Lume, QEMU) have limited snapshot support.-</Callout>--Call `snapshot()` on a running sandbox after you make the changes you want to keep.--```python-import asyncio-from cua import Sandbox, Image--async def main():- async with Sandbox.ephemeral(Image.linux('ubuntu', '24.04')) as sb:- await sb.shell.run('apt-get update -qq && apt-get install -y -qq cowsay')- cowsay_image = await sb.snapshot(name='with-cowsay')-- # boot from snapshot — cowsay already installed- async with Sandbox.ephemeral(cowsay_image) as sb2:- result = await sb2.shell.run('/usr/games/cowsay hello from snapshot!')- print(result.stdout)--asyncio.run(main())-```--Signature:--```python-await sb.snapshot(name='my-snapshot', stateful=False)-```--Parameters:--- name: str | None: optional human-readable label-- stateful: bool (default False): capture memory state in addition to disk (VMs only)--Returns: an Image--## Pre-bake an environment once, fork many times--Snapshot after slow setup, then **reuse that image for repeated runs**.--```python-async with Sandbox.ephemeral(Image.linux()) as sb:- await sb.shell.run('apt-get update && apt-get install -y python3-pip ffmpeg')- await sb.shell.run('pip install torch transformers')- ml_image = await sb.snapshot(name='ml-ready')--for lr in [0.001, 0.01, 0.1]:- async with Sandbox.ephemeral(ml_image) as sb:- await sb.shell.run(f'python train.py --lr {lr}')-```--## Isolate state between runs--Each fork gets **its own copy of disk**, changes in one fork never affect another.--```python-async with Sandbox.ephemeral(Image.linux()) as sb:- await sb.shell.run('echo original > /tmp/data.txt')- base = await sb.snapshot(name='base')--async with Sandbox.ephemeral(base) as a:- await a.shell.run('echo fork-a >> /tmp/data.txt')--async with Sandbox.ephemeral(base) as b:- result = await b.shell.run('cat /tmp/data.txt')- print(result.stdout) # 'original\n' — no trace of fork-a-```--## Performance--| Operation | Typical time |-|-----------|-------------|-| Create + install packages | 30-120 s |-| Fork from snapshot | 1-5 s |--On backends that use copy-on-write storage, forking is nearly instant regardless of disk image size. On dir storage backends, the fork performs a full copy.diff --git a/docs/content/docs/how-to-guides/sandbox/tunneling.mdx b/docs/content/docs/how-to-guides/sandbox/tunneling.mdxindex c8c0d7e832..4f9ff62878 100644--- a/docs/content/docs/how-to-guides/sandbox/tunneling.mdx+++ b/docs/content/docs/how-to-guides/sandbox/tunneling.mdx@@ -14,7 +14,7 @@ Start the service inside the sandbox, then forward its port.```pythonfrom cua import Sandbox, Image-async with Sandbox.ephemeral(Image.linux()) as sb:+async with Sandbox.ephemeral(Image.linux(), local=True) as sb:await sb.shell.run('python3 -m http.server 8080 &')async with sb.tunnel.forward(8080) as t:@@ -69,7 +69,7 @@ Start Chrome with remote debugging enabled, then read the DevTools target list t```pythonfrom cua import Sandbox, Image-async with Sandbox.ephemeral(Image.linux()) as sb:+async with Sandbox.ephemeral(Image.linux(), local=True) as sb:await sb.shell.run('google-chrome --remote-debugging-port=9222 --headless &')async with sb.tunnel.forward(9222) as t:diff --git a/docs/content/docs/how-to-guides/skills/meta.json b/docs/content/docs/how-to-guides/skills/meta.jsondeleted file mode 100644index f115067ce5..0000000000--- a/docs/content/docs/how-to-guides/skills/meta.json+++ /dev/null@@ -1 +0,0 @@-{ "title": "Skills & demonstrations", "pages": ["record-a-demonstration"] }diff --git a/docs/content/docs/how-to-guides/skills/record-a-demonstration.mdx b/docs/content/docs/how-to-guides/skills/record-a-demonstration.mdxdeleted file mode 100644index edf72dbdec..0000000000--- a/docs/content/docs/how-to-guides/skills/record-a-demonstration.mdx+++ /dev/null@@ -1,135 +0,0 @@-----title: 'Record a demonstration as a skill'-description: 'Demonstrate a task once over VNC and turn it into a reusable cua skill you can read, replay, and apply with new inputs.'-----import { Callout } from 'fumadocs-ui/components/callout';--Use `cua skills record` to demonstrate a task once in a VNC session and save it as a **reusable skill**. The result is `~/.cua/skills/<name>/SKILL.md` plus the recorded trajectory assets, which you can inspect, replay as a video, and pass to `ComputerAgent` for similar tasks with new inputs. This is *record-and-replay* in the sense of show-once-get-a-reusable-skill. It does not replay the original input verbatim.--<Callout type='info'>-This records a human demonstration into a reusable skill. The Cua Driver agent-trajectory recorder is separate.-</Callout>--## Prerequisites--- Start a sandbox that exposes VNC. Use a running Cua Cloud sandbox by name, or use any VNC URL, such as a local Docker sandbox at `http://localhost:8006/vnc.html`.-- Install `ffmpeg`. The recorder fails fast if it is missing.--```bash-# macOS-brew install ffmpeg--# Linux-sudo apt install ffmpeg-```--- Set an LLM API key for captioning. The default provider is `anthropic`, which reads `ANTHROPIC_API_KEY` and uses `claude-haiku-4-5` by default.--```bash-export ANTHROPIC_API_KEY=...-```--Use `--provider openai` to read `OPENAI_API_KEY` and use `gpt-4o-mini` by default. You can also pass `--api-key` directly.--## Steps--1. Start recording.-- Use exactly one target flag: `--sandbox` or `--vnc-url`. Pass `--name` and `--description` to avoid the prompts after recording.--```bash-cua skills record \- --sandbox my-sandbox \- --name flight-booking \- --description "Book a flight through the browser"-```--```bash-cua skills record \- --vnc-url http://localhost:8006/vnc.html \- --name flight-booking \- --description "Book a flight through the browser"-```-- The full command shape is:--```text-cua skills record [--sandbox NAME | --vnc-url URL] [--name NAME] [--description DESC] [--provider anthropic|openai] [--model NAME] [--api-key KEY]-```-- Short flags are `-s` for `--sandbox`, `-u` for `--vnc-url`, `-n` for `--name`, `-d` for `--description`, `-p` for `--provider`, `-m` for `--model`, and `-k` for `--api-key`.--2. Perform the task by hand in the VNC window.-- The CLI starts a local recording server, opens the VNC viewer in your browser with recording already enabled, and prints:--```text-Recording will start automatically when you connect.-```-- Complete the task manually in the VNC window. The recording has a 30 minute timeout.--3. Stop recording.-- Click `Stop Recording` in the VNC panel. If you omitted `--name` or `--description`, enter them when prompted. Skill names can contain only letters, numbers, hyphens, and underscores.--4. Inspect the skill.-- After you stop recording, the CLI extracts frames at each input event, captions each step with the VLM, and writes the skill to `~/.cua/skills/<name>/`.--```bash-cua skills read flight-booking-cua skills replay flight-booking-```-- `cua skills read` prints `SKILL.md` as markdown by default. Use `--format json` when you need trajectory data and `skill_prompt`.--```bash-cua skills read flight-booking --format json-```-- `cua skills replay` opens the recorded `.mp4` in your browser. It does not replay the original inputs.-- The skill directory contains:--```text-~/.cua/skills/flight-booking/- SKILL.md- trajectory/- *.mp4- events.json- trajectory.json- step_N_full.jpg-```-- `SKILL.md` contains YAML frontmatter with `name` and `description`, a `Steps` section, and an `Agent Prompt` section.--5. Apply the skill to a new task.-- Read `SKILL.md`, prefix it as context to a `ComputerAgent` run, then provide the real task with different inputs. The agent follows the demonstrated workflow pattern and adapts the parameters.--```python-from pathlib import Path-from cua import ComputerAgent--skill_prompt = (Path.home() / '.cua/skills/flight-booking/SKILL.md').read_text()-agent = ComputerAgent(loop='anthropic')-messages = [- {'role': 'user', 'content': skill_prompt},- {'role': 'user', 'content': 'Book a flight from Boston to Chicago for next Friday'},-]-async for result in agent.run(messages):- print(result)-```--## Manage your skills--```bash-cua skills list-cua skills ls-cua skills read flight-booking-cua skills delete flight-booking-cua skills clean-```--`cua skills clean` deletes all skills after confirmation.diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdxindex 362b07cb4f..d7d82a600e 100644--- a/docs/content/docs/index.mdx+++ b/docs/content/docs/index.mdx@@ -1,9 +1,9 @@---title: 'Cua documentation'-description: 'Open-source computer-use automation for real machines and disposable cloud desktops.'+description: 'Open-source computer-use automation for real machines and local isolated desktops.'----Cua is an open-source MIT-licensed platform ([github.com/trycua/cua](https://github.com/trycua/cua)) for **computer-use automation**: letting AI agents operate computers by clicking, typing, and reading the screen and accessibility tree. What we refer to as **Computer-Use 2.0** treats the GUI as one tool surface in an agent loop, alongside code, shell, files, and APIs. Use Cua Driver to drive a machine you already have, Cua Sandbox to start an isolated cloud desktop, or Cua-Bench to evaluate computer-use agents.+Cua is an open-source MIT-licensed platform ([github.com/trycua/cua](https://github.com/trycua/cua)) for **computer-use automation**: letting AI agents operate computers by clicking, typing, and reading the screen and accessibility tree. What we refer to as **Computer-Use 2.0** treats the GUI as one tool surface in an agent loop, alongside code, shell, files, and APIs. Use Cua Driver to drive a machine you already have, Cua Sandbox to start an isolated local desktop, or Cua-Bench to evaluate computer-use agents.import { Card, Cards } from 'fumadocs-ui/components/card';@@ -13,11 +13,11 @@ import { Card, Cards } from 'fumadocs-ui/components/card';already have without bringing them to the foreground or moving the real mouse. It speaks MCPover stdio and is also a plain CLI.</Card>- <Card title="Spin up a cloud desktop — Cua Sandbox" href="/tutorials/your-first-cloud-sandbox">- Start disposable full Linux, Windows, or macOS VMs with a GUI for an agent to drive when you- want a fresh, isolated computer in the cloud instead of your own machine.+ <Card title="Start a local desktop — Cua Sandbox" href="/tutorials/your-first-local-sandbox">+ Start a disposable Linux desktop with Docker, or use a local VM runtime when you need a fresh,+ isolated computer on your own hardware.</Card>- <Card title="Evaluate agents with Cua-Bench" href="/cuabench">+ <Card title="Evaluate agents with Cua-Bench" href="/concepts/what-is-cua-bench">Define verifiable computer-use tasks, run agents across local or hosted environments, and scorethe resulting trajectories.</Card>@@ -53,10 +53,8 @@ Tutorials: learn by doing. Start with [Tutorials](/tutorials).Concepts: understand how and why Cua works. Start with [Concepts](/concepts).-Cua-Bench: define tasks and evaluate agents. Start with [Cua-Bench](/cuabench).-How-to guides: recipes for a goal. Start with [How-to guides](/how-to-guides).Reference: precise technical description. Start with [Reference](/reference).-For real local apps and signed-in state, start with **Cua Driver**. For fresh isolated desktops, start with **Cua Sandbox**. Lume is the local Apple Silicon VM substrate behind part of the stack.+For existing apps and signed-in state, start with **Cua Driver**. For fresh isolated local desktops, start with **Cua Sandbox**. Lume is the local Apple Silicon VM substrate behind part of the stack.diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.jsonindex 5047f68d39..7e852b9f51 100644--- a/docs/content/docs/meta.json+++ b/docs/content/docs/meta.json@@ -1,5 +1,13 @@{"title": "Documentation","root": true,- "pages": ["index", "---Learn---", "tutorials", "concepts", "cuabench", "---Do---", "how-to-guides", "reference"]+ "pages": [+ "index",+ "---Learn---",+ "tutorials",+ "concepts",+ "---Do---",+ "how-to-guides",+ "reference"+ ]}diff --git a/docs/content/docs/reference/cua-bench/cli-reference.mdx b/docs/content/docs/reference/cua-bench/cli-reference.mdxnew file mode 100644index 0000000000..0f215d5681--- /dev/null+++ b/docs/content/docs/reference/cua-bench/cli-reference.mdx@@ -0,0 +1,50 @@+---+title: 'CLI reference'+description: 'Cua-Bench command groups for tasks, datasets, benchmark runs, environments, agents, and traces.'+---++The Cua-Bench CLI is available as `cb` from the `libs/cua-bench` environment.+Run `cb --help` or `cb <command> --help` for the complete options supported by+your installed version.++## Task and dataset commands++| Command | Purpose |+|---------|---------|+| `cb task info <path>` | Inspect a task's provider, variants, and lifecycle functions. |+| `cb task list [path]` | List available task directories. |+| `cb task create` | Scaffold a task interactively. |+| `cb task generate` | Generate a task scaffold from a prompt. |+| `cb dataset list` | List known datasets. |+| `cb dataset build <path>` | Build a dataset artifact. |++## Run commands++| Command | Purpose |+|---------|---------|+| `cb interact <task-path>` | Run one task interactively with its UI visible. |+| `cb run task <task-path>` | Run one task, optionally with an agent or oracle. |+| `cb run dataset <dataset>` | Run tasks from a dataset in parallel. |+| `cb run list` | List runs and their status. |+| `cb run info <run-id>` | Show details for a run. |+| `cb run watch <run-id>` | Follow a run in the terminal. |+| `cb run logs <run-id>` | Print run or session logs. |+| `cb run stop <run-id>` | Stop a running benchmark. |++Common run options include `--agent`, `--model`, `--oracle`,+`--max-steps`, `--image`, `--platform`, and `--output-dir`. Use the command's+`--help` output for defaults and compatibility constraints.++## Environment and artifact commands++| Command group | Purpose |+|---------------|---------|+| `cb image` | List, inspect, create, delete, clone, or open a shell in environment images. |+| `cb platform` | Inspect the available execution platforms. |+| `cb agent` | Initialize, build, and push agent images. |+| `cb trace` | View a trace or open agent trajectories from completed runs. |+| `cb status` | Inspect running Cua-Bench resources. |+| `cb prune` | Review and remove unused run or environment resources. |++See the [task definition reference](/reference/cua-bench/task-definition) for+the Python task contract.diff --git a/docs/content/docs/reference/cua-bench/meta.json b/docs/content/docs/reference/cua-bench/meta.jsonnew file mode 100644index 0000000000..daf73ac8d2--- /dev/null+++ b/docs/content/docs/reference/cua-bench/meta.json@@ -0,0 +1,7 @@+{+ "title": "Cua-Bench",+ "pages": [+ "cli-reference",+ "task-definition"+ ]+}diff --git a/docs/content/docs/reference/cua-bench/task-definition.mdx b/docs/content/docs/reference/cua-bench/task-definition.mdxnew file mode 100644index 0000000000..b3a15d27ef--- /dev/null+++ b/docs/content/docs/reference/cua-bench/task-definition.mdx@@ -0,0 +1,178 @@+---+title: 'Task definition reference'+description: 'Python types, decorators, and lifecycle signatures for Cua-Bench task modules.'+---++A Cua-Bench task directory contains a `main.py` module. The module exports+decorated lifecycle functions that Cua-Bench discovers for a dataset split.++## `Task`++```python+Task(+ description: str,+ task_id: str | None = None,+ metadata: dict | None = None,+ computer: dict | None = None,+)+```++| Field | Required | Description |+|-------|----------|-------------|+| `description` | Yes | Natural-language objective presented to the agent. |+| `task_id` | No | Stable identifier supplied by the task author or dataset. |+| `metadata` | No | Variant-specific values consumed by lifecycle functions. |+| `computer` | No | Provider and setup configuration for the environment. |++A computer configuration has this shape:++```python+{+ "provider": "simulated",+ "setup_config": {+ "os_type": "macos",+ "width": 512,+ "height": 512,+ },+}+```++Provider-specific settings may add more keys to `setup_config`.++## Lifecycle decorators++Every decorator accepts a split as a positional string or as `split="..."`.+The default split is `train`.++| Decorator | Function result |+|-----------|-----------------|+| `@tasks_config` | A list of `Task` variants. |+| `@setup_task` | No required return value. |+| `@solve_task` | No required return value. The function is optional. |+| `@evaluate_task` | The task's evaluation result, commonly `list[float]`. |++The parameterized forms are equivalent:++```python[email protected]_config("train")+def load():+ ...+[email protected]_config(split="train")+def load():+ ...+```++### Configuration++```python[email protected]_config(split="train")+def load() -> list[cb.Task]:+ ...+```++Configuration runs when the task module is loaded. Each returned `Task` is a+selectable variant, indexed from zero by the CLI.++### Setup++```python[email protected]_task(split="train")+async def setup(+ task_cfg: cb.Task,+ session: cb.DesktopSession,+) -> None:+ ...+```++Setup receives the selected variant and its started session. Session operations+are asynchronous and must be awaited.++### Oracle++```python[email protected]_task(split="train")+async def solve(+ task_cfg: cb.Task,+ session: cb.DesktopSession,+) -> None:+ ...+```++The oracle is invoked when a run requests the solution. It operates on the+state prepared by setup.++### Evaluation++```python[email protected]_task(split="train")+async def evaluate(+ task_cfg: cb.Task,+ session: cb.DesktopSession,+) -> list[float]:+ ...+```++Evaluation inspects the current session state. A task may return multiple+reward components; their meaning is defined by that task or dataset.++## Common session operations++`DesktopSession` is the shared interface supplied to lifecycle functions.+Common asynchronous operations include:++| Operation | Result |+|-----------|--------|+| `launch_window(...)` | Opens HTML, a folder, or a URL and returns a window identifier. |+| `execute_javascript(pid, script)` | Evaluates JavaScript in a task window. |+| `click_element(pid, selector)` | Clicks an element identified by a CSS selector. |+| `execute_action(action)` | Delivers a Cua-Bench input action. |+| `screenshot()` | Returns the current screenshot as bytes. |++Support for an operation can depend on the selected provider.++## Minimal module++```python+from pathlib import Path++import cua_bench as cb++pid = None++[email protected]_config(split="train")+def load():+ return [+ cb.Task(+ description='Click the "Submit" button.',+ computer={+ "provider": "simulated",+ "setup_config": {"os_type": "macos"},+ },+ )+ ]++[email protected]_task(split="train")+async def setup(task_cfg: cb.Task, session: cb.DesktopSession):+ global pid+ pid = await session.launch_window(+ html=(Path(__file__).parent / "gui/index.html").read_text(),+ title="Task",+ )++[email protected]_task(split="train")+async def solve(task_cfg: cb.Task, session: cb.DesktopSession):+ await session.click_element(pid, "#submit")++[email protected]_task(split="train")+async def evaluate(task_cfg: cb.Task, session: cb.DesktopSession):+ clicked = await session.execute_javascript(pid, "window.__clicked")+ return [1.0] if clicked is True else [0.0]+```++The [CLI reference](/reference/cua-bench/cli-reference) describes the commands+that inspect and execute task modules.diff --git a/docs/content/docs/reference/index.mdx b/docs/content/docs/reference/index.mdxindex d3273edf55..36cc1ec2c3 100644--- a/docs/content/docs/reference/index.mdx+++ b/docs/content/docs/reference/index.mdx@@ -1,13 +1,14 @@---title: 'Reference'-description: 'Index of reference material for Cua Driver, Lume, and the Sandbox SDK.'+description: 'Index of reference material for Cua Driver, Lume, the Sandbox SDK, and Cua-Bench.'----Reference documents the full technical specification for Cua's subsystems. It covers `cua-driver`, Lume, the Sandbox SDK, and the Docs & Code MCP server. The pages define commands, APIs, exposed tools, types, and stated limits.+Reference documents the full technical specification for Cua's subsystems. It covers `cua-driver`, Lume, the Sandbox SDK, Cua-Bench, and the Docs & Code MCP server. The pages define commands, APIs, exposed tools, types, and stated limits.| Section | What it documents ||---------|-------------------|| [`cua-driver`](/reference/cua-driver/cli-reference) | CLI commands, the generated MCP tool reference for the stdio MCP server, and known behavioral limits for best-effort background automation. || [Lume](/reference/lume/cli-reference) | CLI commands, local HTTP API, and host limits for creating, running, and managing macOS and Linux VMs on Apple Silicon Macs. || [Sandbox SDK](/reference/sandbox-sdk) | Python API reference for building images, creating sandboxes, and driving their interfaces. |+| [Cua-Bench](/reference/cua-bench/cli-reference) | CLI command groups and the Python task-definition contract. || [Docs & Code MCP](/reference/docs-code-mcp) | Hosted read-only search over Cua docs and versioned source code. |diff --git a/docs/content/docs/reference/meta.json b/docs/content/docs/reference/meta.jsonindex 7317a8232d..cab3d5a508 100644--- a/docs/content/docs/reference/meta.json+++ b/docs/content/docs/reference/meta.json@@ -6,6 +6,7 @@"cua-driver","lume","sandbox-sdk",+ "cua-bench","docs-code-mcp"]}diff --git a/docs/content/docs/tutorials/create-your-first-lume-vm.mdx b/docs/content/docs/tutorials/create-your-first-lume-vm.mdxindex dcc9ba6300..c2d9c81bcd 100644--- a/docs/content/docs/tutorials/create-your-first-lume-vm.mdx+++ b/docs/content/docs/tutorials/create-your-first-lume-vm.mdx@@ -1,5 +1,5 @@----title: Create your first local macOS VM with Lume+title: Local macOS sandboxes with Lumedescription: Install Lume and create a vanilla macOS Tahoe VM from an Apple restore image.---diff --git a/docs/content/docs/tutorials/drive-your-first-app.mdx b/docs/content/docs/tutorials/drive-your-first-app.mdxindex 96c2147f4c..baf78f9989 100644--- a/docs/content/docs/tutorials/drive-your-first-app.mdx+++ b/docs/content/docs/tutorials/drive-your-first-app.mdx@@ -1,12 +1,15 @@----title: Drive your first app+title: Drive your first app with Cua Driverdescription: Install Cua Driver, connect your agent, and ask it in plain English to drive a desktop app in the background on macOS, Windows, or Linux.---import { Tabs, Tab } from 'fumadocs-ui/components/tabs';import { Callout } from 'fumadocs-ui/components/callout';-You do not type **Cua Driver** CLI commands by hand. Cua Driver is a backend that an agent harness (Claude Code, Codex, Hermes, and others) drives for you. In this tutorial you install Cua Driver, connect your agent, and ask it in plain English to open a calculator and read a result back. Works the same on macOS, Windows, and Linux.+By the end of this tutorial, your agent will open Calculator, compute 6 × 7,+and report 42 through **Cua Driver**. You will install the driver, connect+Claude Code, Codex, or Hermes, and run the same prompt on macOS, Windows, or+Linux.New to agents that operate applications? Start with [What is computer use?](/concepts/what-is-computer-use) for the model behind the workflow, then return here to build one.@@ -198,5 +201,7 @@ You installed Cua Driver, verified it could see your desktop, connected your age## Next steps- [Connect your agent](/how-to-guides/driver/connect-your-agent): register Cua Driver with Cursor, Antigravity, OpenCode, OpenClaw, Pi, and more.+- [Use Cua Driver in process](/how-to-guides/driver/use-sdk-in-process): embed the typed SDK in a Python or TypeScript application.+- [Verify a desktop action](/how-to-guides/driver/verify-a-desktop-action): check an action against an independent postcondition.- [Best-effort background](/concepts/the-no-foreground-contract): how Cua Driver avoids focus and cursor disruption when the target app supports it.- [How-to guides](/how-to-guides): keep the driver running, update it, and more.diff --git a/docs/content/docs/tutorials/index.mdx b/docs/content/docs/tutorials/index.mdxindex 51bcfd0718..957ec1c025 100644--- a/docs/content/docs/tutorials/index.mdx+++ b/docs/content/docs/tutorials/index.mdx@@ -5,9 +5,11 @@ description: 'Learn Cua by following end-to-end builds.'Tutorials teach Cua by building something end to end. Start here if you are new to Cua. Each tutorial is *one happy path* you can follow from start to finish.-- [Drive your first app](/tutorials/drive-your-first-app) - operate a native app in the background with Cua Driver.-- [Verify a desktop action with Cua Driver](/tutorials/verify-a-desktop-action-with-cua-driver) - build a deterministic Python or TypeScript perceive, act, and verify loop.-- [Your first cloud sandbox](/tutorials/your-first-cloud-sandbox) - spin up a disposable cloud computer.-- [Create your first local macOS VM](/tutorials/create-your-first-lume-vm) - install Lume and boot a vanilla Tahoe guest.+- [Drive your first app with Cua Driver](/tutorials/drive-your-first-app) - operate a native app in the background.+- [Your first local sandbox](/tutorials/your-first-local-sandbox) - start a disposable Linux desktop with Docker.+- [Local macOS sandboxes with Lume](/tutorials/create-your-first-lume-vm) - install Lume and boot a vanilla Tahoe guest.+- [Build your first Cua-Bench task](/tutorials/your-first-cua-bench-task) - create and verify a simulated computer-use task.++Building a Python or TypeScript application? [Use Cua Driver in process](/how-to-guides/driver/use-sdk-in-process) after completing the first tutorial.Once you are comfortable, [How-to guides](/how-to-guides) cover specific goals and [Reference](/reference) has the exact APIs.diff --git a/docs/content/docs/tutorials/meta.json b/docs/content/docs/tutorials/meta.jsonindex 6e7b311be0..a25721b241 100644--- a/docs/content/docs/tutorials/meta.json+++ b/docs/content/docs/tutorials/meta.json@@ -4,10 +4,8 @@"pages": ["index","drive-your-first-app",- "your-first-cua-driver-python-app",- "your-first-cua-driver-typescript-app",- "verify-a-desktop-action-with-cua-driver",- "your-first-cloud-sandbox",- "create-your-first-lume-vm"+ "your-first-local-sandbox",+ "create-your-first-lume-vm",+ "your-first-cua-bench-task"]}diff --git a/docs/content/docs/tutorials/your-first-cloud-sandbox.mdx b/docs/content/docs/tutorials/your-first-cloud-sandbox.mdxdeleted file mode 100644index b9226b50a3..0000000000--- a/docs/content/docs/tutorials/your-first-cloud-sandbox.mdx+++ /dev/null@@ -1,89 +0,0 @@-----title: Your first cloud sandbox-description: Create a cloud Linux sandbox with the Python SDK, run one command, and save a screenshot.------import { Callout } from 'fumadocs-ui/components/callout';--In this tutorial, you create an *ephemeral* cloud Linux sandbox, run `uname -a` inside it, touch the sandbox clipboard, and save a screenshot from the sandbox to your current directory.--<Callout type="info">- Prerequisites: Python 3.12 or 3.13. A free account at cua.ai for cloud sandboxes.-</Callout>--## Sign in and create an API key--Sign in at cua.ai.--Open **Dashboard > API Keys > New API Key**.--Copy the API key immediately. You will use it in your terminal in the next step.--## Install the SDK--Open a terminal and install the Python SDK:--```bash-pip install cua-```--## Set your API key--Set `CUA_API_KEY` in the same terminal:--```bash-export CUA_API_KEY=sk_cua-...-```--Replace `sk_cua-...` with the API key you copied from the dashboard.--## Create the script--Create a file named `first_sandbox.py`:--```python-import asyncio-from cua import Sandbox, Image--async def main():- async with Sandbox.ephemeral(Image.linux()) as sb:- result = await sb.shell.run("uname -a")- print(result.stdout)-- await sb.clipboard.set("Hello from the sandbox clipboard")- value = await sb.clipboard.get()- print(value)-- screenshot = await sb.screenshot()- with open("screenshot.png", "wb") as f:- f.write(screenshot)- print("Screenshot saved to screenshot.png")--asyncio.run(main())-```--## Run it--Run the script from the same directory:--```bash-python first_sandbox.py-```--You should see a Linux kernel string and the clipboard value printed in your terminal.--You should also see a new file named `screenshot.png` in the current directory.--## What just happened--`Sandbox.ephemeral(Image.linux())` created a cloud Linux container. The script ran `uname -a` inside that container, printed the command output, changed and read the sandbox desktop clipboard, took a screenshot, and wrote it to `screenshot.png`.--When the `async with` block exited, **the sandbox destroyed itself**. No cleanup is needed.--## Next steps--- [Manage sandbox lifecycle](/how-to-guides/sandbox/lifecycle)-- [Create and restore snapshots](/how-to-guides/sandbox/snapshots)-- [Pass secrets to sandboxes](/how-to-guides/sandbox/secrets)-- [Run parallel sandboxes](/how-to-guides/sandbox/scale-out)-- [Sandbox SDK API reference](/reference/sandbox-sdk)diff --git a/docs/content/docs/tutorials/your-first-cua-bench-task.mdx b/docs/content/docs/tutorials/your-first-cua-bench-task.mdxnew file mode 100644index 0000000000..d0ceba77bc--- /dev/null+++ b/docs/content/docs/tutorials/your-first-cua-bench-task.mdx@@ -0,0 +1,120 @@+---+title: 'Build your first Cua-Bench task'+description: 'Create, inspect, solve, and evaluate a simulated computer-use task.'+---++In this tutorial, you will create a small computer-use task and verify it with+its oracle solution. The task runs in a simulated desktop, so it does not need+Docker, a VM, or an API key.++## Before you start++Install:++- Python 3.12 or 3.13;+- [uv](https://docs.astral.sh/uv/).++## Install Cua-Bench++Install the CLI and the browser support used by simulated tasks:++```bash+uv tool install 'cua-bench[browser]'+uv tool run --from 'cua-bench[browser]' playwright install chromium+```++Confirm that the CLI is available:++```bash+cb --help+```++You should see command groups including `run`, `interact`, `task`, `trace`, and+`dataset`.++## Create a task++Create a working directory, enter it, and start the task scaffolder:++```bash+mkdir cua-bench-tutorial+cd cua-bench-tutorial+cb task create first-task+```++Use these values when prompted:++```text+Author name: Your name+Author email: [email protected]+License [MIT]:+Task description: Click the Submit button+Task difficulty (easy|medium|hard) [easy]:+Task category (e.g., grounding, software-engineering) [grounding]:+Tags (comma-separated): button,simulated+```++The scaffold contains the task definition and a small HTML interface:++```text+first-task/+├── main.py+├── pyproject.toml+└── gui/+ └── index.html+```++## Inspect the task++Ask Cua-Bench to load the definition:++```bash+cb task info first-task+```++The output reports a simulated provider, one macOS-themed variant, and check+marks for the setup, solve, and evaluate functions. This confirms that the CLI+can discover the complete task lifecycle.++## Run the oracle++Run the task with its reference solution:++```bash+cb interact first-task --variant-id 0 --oracle --no-wait+```++A desktop window opens while Cua-Bench sets up the interface, clicks the+button, and evaluates the final state. The final lines should include:++```text+✓ Solution complete+✓ Evaluation result: [1.0]+✓ Task completed successfully!+```++The reward of `1.0` means the evaluator observed the state produced by the+oracle.++## Try the task yourself++Run the same variant without the oracle:++```bash+cb interact first-task --variant-id 0+```++Click **Submit** in the task window. Return to the terminal and press Enter to+evaluate and close the task.++## What you built++You created a task with a prompt, simulated desktop, setup function, oracle+solution, and evaluator. You then used the same evaluator to verify both a+reference solution and a manual attempt.++## Next steps++- Understand [the Cua-Bench task lifecycle](/concepts/cua-bench-task-lifecycle).+- Learn how to [run and validate an existing task](/how-to-guides/cua-bench/run-a-task).+- Consult the [task definition reference](/reference/cua-bench/task-definition).diff --git a/docs/content/docs/tutorials/your-first-cua-driver-python-app.mdx b/docs/content/docs/tutorials/your-first-cua-driver-python-app.mdxdeleted file mode 100644index 1c6c44e03a..0000000000--- a/docs/content/docs/tutorials/your-first-cua-driver-python-app.mdx+++ /dev/null@@ -1,82 +0,0 @@-----title: 'Your first Cua Driver Python app'-description: 'Import Cua Driver as a same-process Python SDK and inspect the desktop.'------In this tutorial, you will import Cua Driver into a Python application, start a-session, and read the desktop size. The driver runs in your Python process; you-do not need to start a daemon.--## Before you begin--You need Python 3.10 or newer and a supported interactive macOS, Windows, or-Linux desktop. On macOS, the Python host needs Accessibility and Screen-Recording permission for the actions it performs.--Create a virtual environment and install the published package:--```bash-python3 -m venv .venv-source .venv/bin/activate-python -m pip install cua-driver-```--## Create the application--Save this as `first_driver.py`:--```python-import asyncio--from cua_driver import (- CaptureScope,- CuaDriver,- EndSessionInput,- GetScreenSizeInput,- StartSessionInput,-)---async def main() -> None:- driver = CuaDriver.create()- session = "first-sdk-app"-- await driver.start_session(- StartSessionInput(- session=session,- capture_scope=CaptureScope.DESKTOP,- )- )- try:- metadata = await driver.metadata()- screen = await driver.get_screen_size(- GetScreenSizeInput(session=session)- )- print(f"cua-driver {metadata.driver_version}")- print(screen.text)- finally:- await driver.end_session(EndSessionInput(session=session))- await driver.shutdown()---asyncio.run(main())-```--Run it:--```bash-python first_driver.py-```--The program prints the loaded driver version and the desktop dimensions. It-also demonstrates the lifecycle every SDK application should own: create the-runtime, start and end its sessions, then await `shutdown()`.--## Next steps--- [Use the SDK in process](/how-to-guides/driver/use-sdk-in-process) to capture- the desktop and select a capture scope.-- [Python and TypeScript SDK reference](/reference/cua-driver/sdk-reference)- lists the typed methods, records, and errors.-- [SDK, MCP, and process hosting](/concepts/sdk-mcp-and-hosting) explains when a- daemon is useful.diff --git a/docs/content/docs/tutorials/your-first-cua-driver-typescript-app.mdx b/docs/content/docs/tutorials/your-first-cua-driver-typescript-app.mdxdeleted file mode 100644index 46fad5c9f8..0000000000--- a/docs/content/docs/tutorials/your-first-cua-driver-typescript-app.mdx+++ /dev/null@@ -1,75 +0,0 @@-----title: 'Your first Cua Driver TypeScript app'-description: 'Import Cua Driver as a same-process TypeScript SDK and inspect the desktop.'------In this tutorial, you will import Cua Driver into a Node application, start a-session, and read the desktop size. The driver runs in the Node process; you do-not need to start a daemon.--## Before you begin--You need Node.js and a supported interactive macOS, Windows, or Linux desktop.-On macOS, the Node host needs Accessibility and Screen Recording permission for-the actions it performs.--Create a project and install the published package:--```bash-npm init -y-npm install @trycua/cua-driver-```--## Create the application--Save this as `first-driver.mjs`:--```js-import {- CaptureScope,- CuaDriver,- EndSessionInput,- GetScreenSizeInput,- StartSessionInput,-} from '@trycua/cua-driver';--const driver = CuaDriver.create(undefined);-const session = 'first-sdk-app';--await driver.startSession(- StartSessionInput.new({- session,- captureScope: CaptureScope.Desktop,- })-);-try {- const metadata = await driver.metadata();- const screen = await driver.getScreenSize(GetScreenSizeInput.new({ session }));- console.log(`cua-driver ${metadata.driverVersion}`);- console.log(screen.text);-} finally {- await driver.endSession(EndSessionInput.new({ session }));- await driver.shutdown();- driver.uniffiDestroy();-}-```--Run it:--```bash-node first-driver.mjs-```--The program prints the loaded driver version and the desktop dimensions. It-also demonstrates the lifecycle every Node application should own: create the-runtime, start and end its sessions, await `shutdown()`, then release the-generated binding handle with `uniffiDestroy()`.--## Next steps--- [Use the SDK in process](/how-to-guides/driver/use-sdk-in-process) to capture- the desktop and select a capture scope.-- [Python and TypeScript SDK reference](/reference/cua-driver/sdk-reference)- lists the typed methods, records, and errors.-- [SDK, MCP, and process hosting](/concepts/sdk-mcp-and-hosting) explains when a- daemon is useful.diff --git a/docs/content/docs/tutorials/your-first-local-sandbox.mdx b/docs/content/docs/tutorials/your-first-local-sandbox.mdxnew file mode 100644index 0000000000..e765a1eba9--- /dev/null+++ b/docs/content/docs/tutorials/your-first-local-sandbox.mdx@@ -0,0 +1,73 @@+---+title: Your first local sandbox+description: Create a local Linux sandbox with Docker, run one command, and save a screenshot.+---++import { Callout } from 'fumadocs-ui/components/callout';++In this tutorial, you create an *ephemeral* Linux sandbox on your machine, run `uname -a` inside it, touch the sandbox clipboard, and save a screenshot from the sandbox to your current directory.++<Callout type="info">+ Prerequisites: Python 3.12 or 3.13 and Docker Desktop or Docker Engine.+</Callout>++## Install the SDK++Open a terminal and install the Python SDK:++```bash+pip install cua+```++## Create the script++Create a file named `first_sandbox.py`:++```python+import asyncio+from cua import Sandbox, Image++async def main():+ async with Sandbox.ephemeral(+ Image.linux(kind="container"),+ local=True,+ ) as sb:+ result = await sb.shell.run("uname -a")+ print(result.stdout)++ await sb.clipboard.set("Hello from the sandbox clipboard")+ value = await sb.clipboard.get()+ print(value)++ screenshot = await sb.screenshot()+ with open("screenshot.png", "wb") as f:+ f.write(screenshot)+ print("Screenshot saved to screenshot.png")++asyncio.run(main())+```++## Run it++Run the script from the same directory:++```bash+python first_sandbox.py+```++You should see a Linux kernel string and the clipboard value printed in your terminal.++You should also see a new file named `screenshot.png` in the current directory.++## What just happened++`Sandbox.ephemeral(..., local=True)` created a Linux desktop container through Docker on your machine. The script ran `uname -a` inside that container, printed the command output, changed and read the sandbox desktop clipboard, took a screenshot, and wrote it to `screenshot.png`.++When the `async with` block exited, **the sandbox destroyed itself**. No cleanup is needed.++## Next steps++- [Manage sandbox lifecycle](/how-to-guides/sandbox/lifecycle)+- [Choose and build a sandbox image](/how-to-guides/sandbox/images)+- [Open an interactive sandbox shell](/how-to-guides/sandbox/interactive-shell)+- [Sandbox SDK API reference](/reference/sandbox-sdk)diff --git a/docs/next.config.mjs b/docs/next.config.mjsindex 3841080473..fb70a9fa84 100644--- a/docs/next.config.mjs+++ b/docs/next.config.mjs@@ -1,13 +1,24 @@import { createMDX } from 'fumadocs-mdx/next';+import { networkInterfaces } from 'node:os';const withMDX = createMDX();+const localDevOrigins = [+ 'localhost',+ '127.0.0.1',+ ...Object.values(networkInterfaces())+ .flat()+ .filter((address) => address && !address.internal)+ .map((address) => address.address),+];+/** @type {import('next').NextConfig} */const config = {reactStrictMode: true,trailingSlash: false,basePath: '/docs',assetPrefix: '/docs',+ allowedDevOrigins: [...new Set(localDevOrigins)],async redirects() {return [{@@ -16,6 +27,41 @@ const config = {basePath: false,permanent: false,},+ {+ source: '/cuabench',+ destination: '/concepts/what-is-cua-bench',+ permanent: true,+ },+ {+ source: '/tutorials/your-first-cua-driver-python-app',+ destination: '/how-to-guides/driver/use-sdk-in-process',+ permanent: true,+ },+ {+ source: '/tutorials/your-first-cua-driver-typescript-app',+ destination: '/how-to-guides/driver/use-sdk-in-process',+ permanent: true,+ },+ {+ source: '/tutorials/verify-a-desktop-action-with-cua-driver',+ destination: '/how-to-guides/driver/verify-a-desktop-action',+ permanent: true,+ },+ {+ source: '/tutorials/your-first-cloud-sandbox',+ destination: '/tutorials/your-first-local-sandbox',+ permanent: true,+ },+ {+ source: '/how-to-guides/sandbox/snapshots',+ destination: '/how-to-guides/sandbox/images',+ permanent: true,+ },+ {+ source: '/how-to-guides/skills/record-a-demonstration',+ destination: '/how-to-guides',+ permanent: true,+ },];},images: {