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: add Claude Code in sandbox guide (#1290)
Sarina Li3e720b17d8a8
diff --git a/docs/content/docs/cua/examples/claude-code/cloud-sandbox.mdx b/docs/content/docs/cua/examples/claude-code/cloud-sandbox.mdxnew file mode 100644index 0000000000..c0d58ff626--- /dev/null+++ b/docs/content/docs/cua/examples/claude-code/cloud-sandbox.mdx@@ -0,0 +1,77 @@+---+title: Cloud Sandbox+description: Run Claude Code in a Cua cloud sandbox+---++A complete script that hands off a coding task to Claude Code running inside a Cua cloud sandbox.++## Prerequisites++```bash+pip install cua-sandbox+export CUA_API_KEY="your-cua-key"+export ANTHROPIC_API_KEY="your-anthropic-key"+```++## Script++```python+"""Run Claude Code inside a Cua cloud sandbox."""++import asyncio+import os++from cua_sandbox import Image, Sandbox++image = Image.linux("ubuntu", "24.04")+++async def run(sb, cmd, **kwargs):+ """Run a command and print its output."""+ print(f"$ {cmd}")+ result = await sb.shell.run(cmd, **kwargs)+ if result.stdout:+ print(result.stdout.strip())+ if result.stderr:+ print(result.stderr.strip())+ return result+++async def main():+ api_key = os.environ["ANTHROPIC_API_KEY"]++ async with Sandbox.ephemeral(image) as sb:+ # Install Node.js 20 + Claude Code (skip if already present)+ check = await sb.shell.run("which claude", timeout=10)+ if check.returncode != 0:+ sudo = "sudo " if (await sb.shell.run("whoami")).stdout.strip() != "root" else ""+ await run(sb, f"{sudo}apt-get update && {sudo}apt-get install -y curl git", timeout=120)+ await run(sb, f"curl -fsSL https://deb.nodesource.com/setup_20.x | {sudo}bash -", timeout=60)+ await run(sb, f"{sudo}apt-get install -y nodejs", timeout=60)+ await run(sb, f"{sudo}npm install -g @anthropic-ai/claude-code", timeout=120)++ # Run Claude Code+ result = await run(+ sb,+ f"ANTHROPIC_API_KEY='{api_key}' claude "+ f"--dangerously-skip-permissions "+ f"-p 'Create a hello world index.html file' "+ f"--output-format stream-json --verbose",+ timeout=300,+ )++ # Verify the result+ await run(sb, "cat index.html", timeout=10)+++if __name__ == "__main__":+ asyncio.run(main())+```++## Run it++```bash+python test_claude_code_cloud.py+```++See the [Claude Code guide](/cua/guide/agents-in-sandbox/claude-code) for more patterns like working on repositories, resuming sessions, and custom system prompts.diff --git a/docs/content/docs/cua/examples/claude-code/meta.json b/docs/content/docs/cua/examples/claude-code/meta.jsonindex f3100520a7..2e95cad97b 100644--- a/docs/content/docs/cua/examples/claude-code/meta.json+++ b/docs/content/docs/cua/examples/claude-code/meta.json@@ -2,5 +2,5 @@"title": "Claude Code","description": "Claude Code integration examples","icon": "Terminal",- "pages": ["human-demonstrations"]+ "pages": ["cloud-sandbox", "human-demonstrations"]}diff --git a/docs/content/docs/cua/guide/agents-in-sandbox/claude-code.mdx b/docs/content/docs/cua/guide/agents-in-sandbox/claude-code.mdxnew file mode 100644index 0000000000..cce555baa2--- /dev/null+++ b/docs/content/docs/cua/guide/agents-in-sandbox/claude-code.mdx@@ -0,0 +1,153 @@+---+title: Claude Code+description: Run Claude Code inside a Cua cloud sandbox+icon: claude-code+---++import { Callout } from 'fumadocs-ui/components/callout';+import { Step, Steps } from 'fumadocs-ui/components/steps';++Hand off coding tasks to [Claude Code](https://docs.anthropic.com/en/docs/claude-code) running in an isolated Cua cloud sandbox with full filesystem, terminal, and git access.++## Setup++<Steps>++<Step>++### Install the SDK++```bash+pip install cua-sandbox+```++</Step>++<Step>++### Set your keys++```bash+export CUA_API_KEY="your-cua-key"+export ANTHROPIC_API_KEY="your-anthropic-key"+```++</Step>++</Steps>++## Run Claude Code in a cloud sandbox++This spins up an ephemeral cloud VM via the Cua API. You'll need a `CUA_API_KEY` — get one from [cua.ai/dashboard](https://cua.ai/dashboard) if you don't have one yet.++```python+import asyncio, os+from cua_sandbox import Sandbox, Image++async def main():+ api_key = os.environ["ANTHROPIC_API_KEY"]++ # CUA_API_KEY is read from your environment automatically+ async with Sandbox.ephemeral(Image.linux("ubuntu", "24.04")) as sb:+ # Install Node.js + Claude Code+ await sb.shell.run("sudo apt-get update && sudo apt-get install -y curl", timeout=60)+ await sb.shell.run("curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -", timeout=60)+ await sb.shell.run("sudo apt-get install -y nodejs", timeout=60)+ await sb.shell.run("sudo npm install -g @anthropic-ai/claude-code", timeout=120)++ # Hand off a task+ result = await sb.shell.run(+ f"ANTHROPIC_API_KEY='{api_key}' claude -p 'Create a hello world index.html' "+ f"--dangerously-skip-permissions --output-format stream-json --verbose",+ timeout=300,+ )+ print(result.stdout)++asyncio.run(main())+```++<Callout type="info">+ `--dangerously-skip-permissions` is required for headless execution. `-p` passes the task as a prompt.+</Callout>++## Connect to an existing sandbox++Skip provisioning by connecting to a sandbox that's already running.++```python+sb = await Sandbox.connect("my-sandbox")+async with sb:+ result = await sb.shell.run(+ f"ANTHROPIC_API_KEY='{api_key}' claude -p 'List all TODO comments' "+ f"--dangerously-skip-permissions",+ timeout=300,+ )+ print(result.stdout)+```++## Work on a repository++Clone a repo, run a task, and inspect the diff.++```python+await sb.shell.run("git clone https://github.com/user/repo.git /tmp/repo", timeout=60)++result = await sb.shell.run(+ f"cd /tmp/repo && ANTHROPIC_API_KEY='{api_key}' claude -p 'Fix the failing tests' "+ f"--dangerously-skip-permissions --output-format stream-json --verbose",+ timeout=300,+)+print(result.stdout)++diff = await sb.shell.run("cd /tmp/repo && git diff", timeout=30)+print(diff.stdout)+```++## Structured output++`--output-format stream-json --verbose` emits one JSON object per line.++| Event type | Description |+|------------|-------------|+| `system` | Session init — tools, model, config |+| `assistant` | Claude's responses and tool calls |+| `result` | Final summary — cost, duration, tokens |++```python+import json++for line in result.stdout.strip().splitlines():+ event = json.loads(line)+ if event["type"] == "result":+ print(f"Cost: ${event['total_cost_usd']:.4f}")+ print(f"Result: {event['result']}")+```++## Resume a session++Extract the `session_id` from the init event and pass it back.++```python+init = json.loads(result.stdout.strip().splitlines()[0])+session_id = init["session_id"]++followup = await sb.shell.run(+ f"ANTHROPIC_API_KEY='{api_key}' claude -p 'Now add CSS styling' "+ f"--dangerously-skip-permissions --output-format stream-json --verbose "+ f"--session-id {session_id}",+ timeout=300,+)+```++## Custom system prompt++Write a `CLAUDE.md` into the repo before running Claude Code.++```python+await sb.shell.run(+ "echo '# Rules\n- Use TypeScript\n- Write tests for all changes' > /tmp/repo/CLAUDE.md",+ timeout=10,+)+```++Claude Code automatically reads `CLAUDE.md` from the working directory.diff --git a/docs/content/docs/cua/guide/agents-in-sandbox/meta.json b/docs/content/docs/cua/guide/agents-in-sandbox/meta.jsonnew file mode 100644index 0000000000..17af893e65--- /dev/null+++ b/docs/content/docs/cua/guide/agents-in-sandbox/meta.json@@ -0,0 +1,7 @@+{+ "title": "Agents in Sandbox",+ "description": "Run coding agents inside Cua sandboxes",+ "icon": "Bot",+ "defaultOpen": true,+ "pages": ["claude-code"]+}diff --git a/docs/content/docs/cua/guide/fundamentals/meta.json b/docs/content/docs/cua/guide/fundamentals/meta.jsonindex ebdcd7451f..4bf64fa359 100644--- a/docs/content/docs/cua/guide/fundamentals/meta.json+++ b/docs/content/docs/cua/guide/fundamentals/meta.json@@ -2,6 +2,6 @@"title": "Agent","description": "Core concepts for building agents with Cua","icon": "Lightbulb",- "defaultOpen": true,+ "defaultOpen": false,"pages": ["agent-loops", "vlms", "cua-vlm-router", "browser-tool", "callbacks"]}diff --git a/docs/content/docs/cua/guide/meta.json b/docs/content/docs/cua/guide/meta.jsonindex ad96f7cce1..d9c32772de 100644--- a/docs/content/docs/cua/guide/meta.json+++ b/docs/content/docs/cua/guide/meta.json@@ -2,5 +2,5 @@"title": "Guide","description": "Learn how to build with Cua","icon": "Book",- "pages": ["get-started", "sandbox", "fundamentals", "advanced", "integrations"]+ "pages": ["get-started", "sandbox", "agents-in-sandbox", "fundamentals", "advanced", "integrations"]}diff --git a/docs/src/lib/source.ts b/docs/src/lib/source.tsindex edc67ce558..f060dfb1b8 100644--- a/docs/src/lib/source.ts+++ b/docs/src/lib/source.ts@@ -32,6 +32,19 @@ const brandIcons: Record<string, () => React.ReactElement> = {d: 'M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z',})),+ 'claude-code': () =>+ createElement(+ 'svg',+ {+ viewBox: '0 0 24 24',+ fill: '#D97757',+ className: 'w-4 h-4',+ },+ createElement('path', {+ d: 'M4.709 15.955l4.72-2.647.08-.23-.08-.128H9.2l-.79-.048-2.698-.073-2.339-.097-2.266-.122-.571-.121L0 11.784l.055-.352.48-.321.686.06 1.52.103 2.278.158 1.652.097 2.449.255h.389l.055-.157-.134-.098-.103-.097-2.358-1.596-2.552-1.688-1.336-.972-.724-.491-.364-.462-.158-1.008.656-.722.881.06.225.061.893.686 1.908 1.476 2.491 1.833.365.304.145-.103.019-.073-.164-.274-1.355-2.446-1.446-2.49-.644-1.032-.17-.619a2.97 2.97 0 01-.104-.729L6.283.134 6.696 0l.996.134.42.364.62 1.414 1.002 2.229 1.555 3.03.456.898.243.832.091.255h.158V9.01l.128-1.706.237-2.095.23-2.695.08-.76.376-.91.747-.492.584.28.48.685-.067.444-.286 1.851-.559 2.903-.364 1.942h.212l.243-.242.985-1.306 1.652-2.064.73-.82.85-.904.547-.431h1.033l.76 1.129-.34 1.166-1.064 1.347-.881 1.142-1.264 1.7-.79 1.36.073.11.188-.02 2.856-.606 1.543-.28 1.841-.315.833.388.091.395-.328.807-1.969.486-2.309.462-3.439.813-.042.03.049.061 1.549.146.662.036h1.622l3.02.225.79.522.474.638-.079.485-1.215.62-1.64-.389-3.829-.91-1.312-.329h-.182v.11l1.093 1.068 2.006 1.81 2.509 2.33.127.578-.322.455-.34-.049-2.205-1.657-.851-.747-1.926-1.62h-.128v.17l.444.649 2.345 3.521.122 1.08-.17.353-.608.213-.668-.122-1.374-1.925-1.415-2.167-1.143-1.943-.14.08-.674 7.254-.316.37-.729.28-.607-.461-.322-.747.322-1.476.389-1.924.315-1.53.286-1.9.17-.632-.012-.042-.14.018-1.434 1.967-2.18 2.945-1.726 1.845-.414.164-.717-.37.067-.662.401-.589 2.388-3.036 1.44-1.882.93-1.086-.006-.158h-.055L4.132 18.56l-1.13.146-.487-.456.061-.746.231-.243 1.908-1.312-.006.006z',+ fillRule: 'nonzero',+ })+ ),};// Icon resolver