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: 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.mdx
new file mode 100644
index 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.json
index 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.mdx
new file mode 100644
index 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.json
new file mode 100644
index 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.json
index 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.json
index 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.ts
index 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