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: restructure documentation with Fumadocs for improved navigation

f-trycuac946c64eaaa5
diff --git a/docs/content/docs/example-usecases/gemini-complex-ui-navigation.mdx b/docs/content/docs/examples/ai-models/gemini-complex-ui-navigation.mdx
similarity index 100%
rename from docs/content/docs/example-usecases/gemini-complex-ui-navigation.mdx
rename to docs/content/docs/examples/ai-models/gemini-complex-ui-navigation.mdx
diff --git a/docs/content/docs/examples/ai-models/meta.json b/docs/content/docs/examples/ai-models/meta.json
new file mode 100644
index 0000000000..3c2b81bc77
--- /dev/null
+++ b/docs/content/docs/examples/ai-models/meta.json
@@ -0,0 +1,8 @@
+{
+ "title": "AI Models",
+ "description": "Examples using different AI models",
+ "icon": "Brain",
+ "pages": [
+ "gemini-complex-ui-navigation"
+ ]
+}
diff --git a/docs/content/docs/example-usecases/form-filling.mdx b/docs/content/docs/examples/automation/form-filling.mdx
similarity index 100%
rename from docs/content/docs/example-usecases/form-filling.mdx
rename to docs/content/docs/examples/automation/form-filling.mdx
diff --git a/docs/content/docs/examples/automation/meta.json b/docs/content/docs/examples/automation/meta.json
new file mode 100644
index 0000000000..92ac666640
--- /dev/null
+++ b/docs/content/docs/examples/automation/meta.json
@@ -0,0 +1,10 @@
+{
+ "title": "Automation",
+ "description": "Automate repetitive tasks with Cua",
+ "icon": "Workflow",
+ "defaultOpen": true,
+ "pages": [
+ "form-filling",
+ "post-event-contact-export"
+ ]
+}
diff --git a/docs/content/docs/example-usecases/post-event-contact-export.mdx b/docs/content/docs/examples/automation/post-event-contact-export.mdx
similarity index 100%
rename from docs/content/docs/example-usecases/post-event-contact-export.mdx
rename to docs/content/docs/examples/automation/post-event-contact-export.mdx
diff --git a/docs/content/docs/examples/index.mdx b/docs/content/docs/examples/index.mdx
new file mode 100644
index 0000000000..7aa893a01e
--- /dev/null
+++ b/docs/content/docs/examples/index.mdx
@@ -0,0 +1,44 @@
+---
+title: Examples
+description: Real-world examples of building with Cua
+---
+
+import { Card, Cards } from 'fumadocs-ui/components/card';
+import { Workflow, Laptop, Brain } from 'lucide-react';
+
+# Examples
+
+Explore real-world examples of building computer-use agents with Cua. These examples demonstrate various use cases across different platforms and AI models.
+
+<Cards>
+ <Card
+ icon={<Workflow className="w-6 h-6" />}
+ href="/examples/automation/form-filling"
+ title="Automation"
+ description="Automate repetitive tasks like form filling and data export"
+ />
+ <Card
+ icon={<Laptop className="w-6 h-6" />}
+ href="/examples/platform-specific/windows-app-behind-vpn"
+ title="Platform-Specific"
+ description="Platform-specific examples and integrations"
+ />
+ <Card
+ icon={<Brain className="w-6 h-6" />}
+ href="/examples/ai-models/gemini-complex-ui-navigation"
+ title="AI Models"
+ description="Examples using different AI models for GUI grounding"
+ />
+</Cards>
+
+## Featured Examples
+
+### Automation
+- **[PDF to Form Automation](/examples/automation/form-filling)** - Extract data from PDFs and automatically fill web forms
+- **[Post-Event Contact Export](/examples/automation/post-event-contact-export)** - Automate contact data extraction after events
+
+### Platform-Specific
+- **[Windows App behind VPN](/examples/platform-specific/windows-app-behind-vpn)** - Control Windows applications through VPN connections
+
+### AI Models
+- **[GUI Grounding with Gemini 3](/examples/ai-models/gemini-complex-ui-navigation)** - Use Gemini for complex UI navigation tasks
diff --git a/docs/content/docs/examples/meta.json b/docs/content/docs/examples/meta.json
new file mode 100644
index 0000000000..ecafd7bba1
--- /dev/null
+++ b/docs/content/docs/examples/meta.json
@@ -0,0 +1,12 @@
+{
+ "title": "Examples",
+ "description": "Real-world examples of building with Cua",
+ "root": true,
+ "icon": "Blocks",
+ "pages": [
+ "index",
+ "automation",
+ "platform-specific",
+ "ai-models"
+ ]
+}
diff --git a/docs/content/docs/examples/platform-specific/meta.json b/docs/content/docs/examples/platform-specific/meta.json
new file mode 100644
index 0000000000..f72d91ded9
--- /dev/null
+++ b/docs/content/docs/examples/platform-specific/meta.json
@@ -0,0 +1,8 @@
+{
+ "title": "Platform-Specific",
+ "description": "Platform-specific examples and integrations",
+ "icon": "Laptop",
+ "pages": [
+ "windows-app-behind-vpn"
+ ]
+}
diff --git a/docs/content/docs/example-usecases/windows-app-behind-vpn.mdx b/docs/content/docs/examples/platform-specific/windows-app-behind-vpn.mdx
similarity index 100%
rename from docs/content/docs/example-usecases/windows-app-behind-vpn.mdx
rename to docs/content/docs/examples/platform-specific/windows-app-behind-vpn.mdx
diff --git a/docs/content/docs/guide/agents/callbacks.mdx b/docs/content/docs/guide/agents/callbacks.mdx
new file mode 100644
index 0000000000..0f6a5c7bde
--- /dev/null
+++ b/docs/content/docs/guide/agents/callbacks.mdx
@@ -0,0 +1,272 @@
+---
+title: Callbacks
+description: Hooks into the agent lifecycle for logging, cost management, and data handling
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+
+Callbacks provide hooks into the agent's lifecycle, allowing for custom functionality at various stages of an agent's run. They enable extensibility for tasks such as logging, cost management, and data handling.
+
+## Quick Start
+
+```python
+from cua import ComputerAgent
+from cua.agent.callbacks import (
+ ImageRetentionCallback,
+ TrajectorySaverCallback,
+ BudgetManagerCallback,
+ LoggingCallback
+)
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ callbacks=[
+ ImageRetentionCallback(only_n_most_recent_images=3),
+ TrajectorySaverCallback(trajectory_dir="trajectories"),
+ BudgetManagerCallback(max_budget=10.0, raise_error=True),
+ LoggingCallback(level=logging.INFO)
+ ]
+)
+```
+
+## Built-in Callbacks
+
+<Tabs items={['Cost Optimization', 'Trajectories', 'Logging']}>
+<Tab value="Cost Optimization">
+
+### Budget Manager
+
+Control spending with budget limits:
+
+```python
+from cua.agent.callbacks import BudgetManagerCallback
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ callbacks=[
+ BudgetManagerCallback(
+ max_budget=5.0, # $5 limit
+ reset_after_each_run=False,
+ raise_error=True
+ )
+ ]
+)
+```
+
+**Shorthand:**
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ max_trajectory_budget=5.0 # $5 limit
+)
+```
+
+**Options:**
+- `max_budget`: Dollar limit for trajectory
+- `reset_after_each_run`: Reset budget per run (default: True)
+- `raise_error`: Raise exception vs. graceful stop (default: False)
+
+### Image Retention
+
+Reduce token usage by limiting images in context:
+
+```python
+from cua.agent.callbacks import ImageRetentionCallback
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ callbacks=[
+ ImageRetentionCallback(only_n_most_recent_images=3)
+ ]
+)
+```
+
+**Shorthand:**
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ only_n_most_recent_images=3 # Auto-adds ImageRetentionCallback
+)
+```
+
+### Combined Cost Optimization
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ max_trajectory_budget=5.0, # Budget limit
+ only_n_most_recent_images=3, # Image retention
+ trajectory_dir="trajectories" # Track spending
+)
+```
+
+</Tab>
+<Tab value="Trajectories">
+
+### TrajectorySaverCallback
+
+Records complete agent conversations including messages, actions, and screenshots for debugging and analysis.
+
+```python
+from cua.agent.callbacks import TrajectorySaverCallback
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ callbacks=[
+ TrajectorySaverCallback(
+ trajectory_dir="my_trajectories",
+ save_screenshots=True
+ )
+ ]
+)
+```
+
+**Shorthand:**
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ trajectory_dir="trajectories", # Auto-save trajectories
+ tools=[computer]
+)
+```
+
+### View Trajectories Online
+
+View trajectories in the browser at **[cua.ai/trajectory-viewer](https://cua.ai/trajectory-viewer)**
+
+The viewer provides:
+- Interactive conversation replay
+- Screenshot galleries
+- No data collection
+
+### Trajectory Structure
+
+Each trajectory contains:
+- **metadata.json**: Run info, timestamps, usage stats (`total_tokens`, `response_cost`)
+- **turn_000/**: Turn-by-turn conversation history (api calls, responses, computer calls, screenshots)
+
+</Tab>
+<Tab value="Logging">
+
+### LoggingCallback
+
+Built-in logging for agent monitoring:
+
+```python
+from cua.agent.callbacks import LoggingCallback
+import logging
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ callbacks=[
+ LoggingCallback(
+ logger=logging.getLogger("cua"),
+ level=logging.INFO
+ )
+ ]
+)
+```
+
+**Shorthand:**
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ verbosity=logging.INFO # Auto-adds LoggingCallback
+)
+```
+
+### Custom Logger
+
+Create custom loggers by extending AsyncCallbackHandler:
+
+```python
+from cua.agent.callbacks.base import AsyncCallbackHandler
+import logging
+
+class CustomLogger(AsyncCallbackHandler):
+ def __init__(self, logger_name="agent"):
+ self.logger = logging.getLogger(logger_name)
+ self.logger.setLevel(logging.INFO)
+
+ handler = logging.StreamHandler()
+ formatter = logging.Formatter(
+ '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+ )
+ handler.setFormatter(formatter)
+ self.logger.addHandler(handler)
+
+ async def on_run_start(self, kwargs, old_items):
+ self.logger.info(f"Agent run started with model: {kwargs.get('model')}")
+
+ async def on_computer_call_start(self, item):
+ action = item.get('action', {})
+ self.logger.info(f"Computer action: {action.get('type')}")
+
+ async def on_usage(self, usage):
+ cost = usage.get('response_cost', 0)
+ self.logger.info(f"API call cost: ${cost:.4f}")
+
+ async def on_run_end(self, kwargs, old_items, new_items):
+ self.logger.info("Agent run completed")
+
+# Use custom logger
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ callbacks=[CustomLogger("my_agent")]
+)
+```
+
+</Tab>
+</Tabs>
+
+## Callback Lifecycle
+
+Callbacks are called in a specific order during agent execution:
+
+| Order | Method | Description |
+|-------|--------|-------------|
+| 1 | `on_run_start(kwargs, old_items)` | Called once when agent run begins |
+| 2 | `on_run_continue(kwargs, old_items, new_items)` | Called before each iteration. Return `False` to stop |
+| 3 | `on_llm_start(messages)` | Preprocess messages before LLM call |
+| 4 | `on_api_start(kwargs)` | Called before each LLM API call |
+| 5 | `on_api_end(kwargs, result)` | Called after each LLM API call |
+| 6 | `on_usage(usage)` | Called when usage info is received |
+| 7 | `on_llm_end(messages)` | Postprocess messages after LLM call |
+| 8 | `on_responses(kwargs, responses)` | Called when responses are received |
+| 9 | Response hooks | `on_text`, `on_computer_call_start/end`, `on_function_call_start/end`, `on_screenshot` |
+| 10 | `on_run_end(kwargs, old_items, new_items)` | Called when agent run completes |
+
+## Custom Callbacks
+
+Create custom callbacks by subclassing `AsyncCallbackHandler`:
+
+```python
+from cua.agent.callbacks.base import AsyncCallbackHandler
+
+class CustomCallback(AsyncCallbackHandler):
+ async def on_llm_start(self, messages):
+ """Preprocess messages before LLM call"""
+ # Add custom preprocessing logic
+ return messages
+
+ async def on_llm_end(self, messages):
+ """Postprocess messages after LLM call"""
+ # Add custom postprocessing logic
+ return messages
+
+ async def on_usage(self, usage):
+ """Track usage information"""
+ print(f"Tokens used: {usage.total_tokens}")
+```
diff --git a/docs/content/docs/agent-sdk/chat-history.mdx b/docs/content/docs/guide/agents/chat-history.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/chat-history.mdx
rename to docs/content/docs/guide/agents/chat-history.mdx
diff --git a/docs/content/docs/agent-sdk/custom-tools.mdx b/docs/content/docs/guide/agents/custom-tools.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/custom-tools.mdx
rename to docs/content/docs/guide/agents/custom-tools.mdx
diff --git a/docs/content/docs/agent-sdk/customizing-computeragent.mdx b/docs/content/docs/guide/agents/customizing-computeragent.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/customizing-computeragent.mdx
rename to docs/content/docs/guide/agents/customizing-computeragent.mdx
diff --git a/docs/content/docs/agent-sdk/message-format.mdx b/docs/content/docs/guide/agents/message-format.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/message-format.mdx
rename to docs/content/docs/guide/agents/message-format.mdx
diff --git a/docs/content/docs/guide/agents/meta.json b/docs/content/docs/guide/agents/meta.json
new file mode 100644
index 0000000000..29ce8297c1
--- /dev/null
+++ b/docs/content/docs/guide/agents/meta.json
@@ -0,0 +1,17 @@
+{
+ "title": "Agents",
+ "description": "Building and configuring computer-use agents",
+ "icon": "Bot",
+ "pages": [
+ "supported-agents",
+ "callbacks",
+ "custom-tools",
+ "chat-history",
+ "customizing-computeragent",
+ "prompt-caching",
+ "message-format",
+ "usage-tracking",
+ "telemetry",
+ "migration-guide"
+ ]
+}
diff --git a/docs/content/docs/agent-sdk/migration-guide.mdx b/docs/content/docs/guide/agents/migration-guide.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/migration-guide.mdx
rename to docs/content/docs/guide/agents/migration-guide.mdx
diff --git a/docs/content/docs/agent-sdk/prompt-caching.mdx b/docs/content/docs/guide/agents/prompt-caching.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/prompt-caching.mdx
rename to docs/content/docs/guide/agents/prompt-caching.mdx
diff --git a/docs/content/docs/guide/agents/supported-agents.mdx b/docs/content/docs/guide/agents/supported-agents.mdx
new file mode 100644
index 0000000000..c43d4bd18a
--- /dev/null
+++ b/docs/content/docs/guide/agents/supported-agents.mdx
@@ -0,0 +1,219 @@
+---
+title: Supported Agents
+description: Computer-use agents, grounding models, composed agents, and human-in-the-loop
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+The Agent SDK supports multiple types of agents for different use cases. All agent loops are compatible with any LLM provider supported by LiteLLM.
+
+<Tabs items={['All-in-one CUAs', 'Grounding Models', 'Composed Agents', 'Human-in-the-Loop']}>
+<Tab value="All-in-one CUAs">
+
+## Computer-Use Agents
+
+These models support complete computer-use agent functionality through `ComputerAgent.run()`. They can understand natural language instructions and autonomously perform sequences of actions.
+
+### Anthropic Claude
+
+Claude models with computer-use capabilities:
+
+| Model | ID |
+|-------|-----|
+| Claude 4.5 | `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` |
+| Claude 4.1 | `claude-opus-4-1-20250805` |
+| Claude 4 | `claude-opus-4-20250514`, `claude-sonnet-4-20250514` |
+| Claude 3.7 | `claude-3-7-sonnet-20250219` |
+
+```python
+agent = ComputerAgent("claude-sonnet-4-5-20250929", tools=[computer])
+async for _ in agent.run("Open Firefox and navigate to github.com"):
+ pass
+```
+
+### Google Gemini
+
+- Gemini 2.5 CUA: `gemini-2.5-computer-use-preview-10-2025`
+
+```python
+agent = ComputerAgent("gemini-2.5-computer-use-preview-10-2025", tools=[computer])
+async for _ in agent.run("Open Firefox and navigate to github.com"):
+ pass
+```
+
+### OpenAI
+
+- Computer-use-preview: `computer-use-preview`
+
+```python
+agent = ComputerAgent("openai/computer-use-preview", tools=[computer])
+async for _ in agent.run("Take a screenshot and describe what you see"):
+ pass
+```
+
+### Other Models
+
+| Model | ID |
+|-------|-----|
+| GLM-4.5V | `openrouter/z-ai/glm-4.5v` |
+| InternVL 3.5 | `huggingface-local/OpenGVLab/InternVL3_5-{1B,2B,4B,8B,...}` |
+| Qwen3 VL | `cua/qwen/qwen3-vl-235b` (via Cua VLM Router) |
+| UI-TARS 1.5 | `huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B` |
+
+</Tab>
+<Tab value="Grounding Models">
+
+## Grounding Models
+
+These models specialize in UI element grounding and click prediction. They can identify precise coordinates for UI elements based on natural language descriptions.
+
+Use `ComputerAgent.predict_click()` to get coordinates for specific UI elements.
+
+<Callout type="info">
+All models that support `ComputerAgent.run()` also support `ComputerAgent.predict_click()`.
+</Callout>
+
+### Specialized Grounding Models
+
+| Model | ID |
+|-------|-----|
+| OpenCUA | `huggingface-local/xlangai/OpenCUA-{7B,32B}` |
+| GTA1 | `huggingface-local/HelloKKMe/GTA1-{7B,32B,72B}` |
+| Holo 1.5 | `huggingface-local/Hcompany/Holo1.5-{3B,7B,72B}` |
+| InternVL 3.5 | `huggingface-local/OpenGVLab/InternVL3_5-{1B,2B,4B,8B,...}` |
+| OmniParser | `omniparser` (requires LLM combination) |
+| Moondream3 | `moondream3` |
+
+### Usage
+
+```python
+agent = ComputerAgent("claude-sonnet-4-5-20250929", tools=[computer])
+
+# Predict coordinates for specific elements
+login_coords = agent.predict_click("find the login button")
+search_coords = agent.predict_click("locate the search text field")
+
+print(f"Login button: {login_coords}")
+print(f"Search field: {search_coords}")
+```
+
+```python
+# GTA1 for click prediction only
+agent = ComputerAgent("huggingface-local/HelloKKMe/GTA1-7B", tools=[computer])
+coords = agent.predict_click("find the submit button")
+print(f"Click coordinates: {coords}") # (450, 320)
+
+# Note: GTA1 cannot perform autonomous task planning
+# Use composed agents for full capabilities
+```
+
+</Tab>
+<Tab value="Composed Agents">
+
+## Composed Agents
+
+Combine specialized grounding models with powerful LLMs for task planning using the format `"grounding_model+planning_model"`.
+
+### How It Works
+
+1. **Planning Phase**: The LLM analyzes the task and decides what actions to take
+2. **Grounding Phase**: The grounding model converts element descriptions to precise coordinates
+3. **Execution**: Actions are performed using the predicted coordinates
+
+### Examples
+
+**GTA1 + Claude 4.5 Sonnet**
+
+```python
+agent = ComputerAgent(
+ "huggingface-local/HelloKKMe/GTA1-7B+anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+)
+
+async for _ in agent.run("Open Firefox, navigate to github.com, and search for 'computer-use'"):
+ pass
+```
+
+**GTA1 + GPT-5**
+
+```python
+agent = ComputerAgent(
+ "huggingface-local/HelloKKMe/GTA1-7B+openai/gpt-5",
+ tools=[computer]
+)
+
+async for _ in agent.run("Take a screenshot and click on the most prominent button"):
+ pass
+```
+
+**Moondream3 + GPT-4o**
+
+```python
+agent = ComputerAgent(
+ "moondream3+openai/gpt-4o",
+ tools=[computer]
+)
+
+async for _ in agent.run("Close the settings window, then open Downloads"):
+ pass
+```
+
+### Benefits
+
+- **Specialized Grounding**: Use models optimized for click prediction accuracy
+- **Flexible Planning**: Choose any LLM for task reasoning
+- **Cost Optimization**: Use smaller grounding models with larger planning models
+
+</Tab>
+<Tab value="Human-in-the-Loop">
+
+## Human-in-the-Loop
+
+Use humans as agents for evaluation, demonstrations, and interactive control.
+
+### Getting Started
+
+Start the human agent tool:
+
+```bash
+python -m agent.human_tool
+```
+
+The UI will show pending completions. Select a completion to take control of the agent.
+
+### Usage
+
+**Direct Human Agent**
+
+```python
+agent = ComputerAgent(
+ "human/human",
+ tools=[computer]
+)
+
+async for _ in agent.run("Take a screenshot and click on the most prominent button"):
+ pass
+```
+
+**Composed with Grounding Model**
+
+```python
+agent = ComputerAgent(
+ "huggingface-local/HelloKKMe/GTA1-7B+human/human",
+ tools=[computer]
+)
+
+async for _ in agent.run("Navigate to settings and enable dark mode"):
+ pass
+```
+
+### Use Cases
+
+- **Evaluation**: Have humans evaluate agent performance and provide ground truth
+- **Demonstrations**: Create training data by having humans demonstrate tasks
+- **Interactive Control**: Take manual control when automated agents need guidance
+- **Testing**: Validate agent, tool, and environment behavior manually
+
+</Tab>
+</Tabs>
diff --git a/docs/content/docs/agent-sdk/telemetry.mdx b/docs/content/docs/guide/agents/telemetry.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/telemetry.mdx
rename to docs/content/docs/guide/agents/telemetry.mdx
diff --git a/docs/content/docs/agent-sdk/usage-tracking.mdx b/docs/content/docs/guide/agents/usage-tracking.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/usage-tracking.mdx
rename to docs/content/docs/guide/agents/usage-tracking.mdx
diff --git a/docs/content/docs/computer-sdk/cloud-vm-management.mdx b/docs/content/docs/guide/computers/cloud-vm-management.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/cloud-vm-management.mdx
rename to docs/content/docs/guide/computers/cloud-vm-management.mdx
diff --git a/docs/content/docs/computer-sdk/commands.mdx b/docs/content/docs/guide/computers/commands.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/commands.mdx
rename to docs/content/docs/guide/computers/commands.mdx
diff --git a/docs/content/docs/computer-sdk/computer-ui.mdx b/docs/content/docs/guide/computers/computer-ui.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/computer-ui.mdx
rename to docs/content/docs/guide/computers/computer-ui.mdx
diff --git a/docs/content/docs/computer-sdk/custom-computer-handlers.mdx b/docs/content/docs/guide/computers/custom-computer-handlers.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/custom-computer-handlers.mdx
rename to docs/content/docs/guide/computers/custom-computer-handlers.mdx
diff --git a/docs/content/docs/guide/computers/meta.json b/docs/content/docs/guide/computers/meta.json
new file mode 100644
index 0000000000..676afafba5
--- /dev/null
+++ b/docs/content/docs/guide/computers/meta.json
@@ -0,0 +1,13 @@
+{
+ "title": "Computers",
+ "description": "Working with sandboxed computers and VMs",
+ "icon": "Monitor",
+ "pages": [
+ "commands",
+ "sandboxed-python",
+ "computer-ui",
+ "tracing-api",
+ "custom-computer-handlers",
+ "cloud-vm-management"
+ ]
+}
diff --git a/docs/content/docs/computer-sdk/sandboxed-python.mdx b/docs/content/docs/guide/computers/sandboxed-python.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/sandboxed-python.mdx
rename to docs/content/docs/guide/computers/sandboxed-python.mdx
diff --git a/docs/content/docs/computer-sdk/tracing-api.mdx b/docs/content/docs/guide/computers/tracing-api.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/tracing-api.mdx
rename to docs/content/docs/guide/computers/tracing-api.mdx
diff --git a/docs/content/docs/guide/fundamentals/agent-loops.mdx b/docs/content/docs/guide/fundamentals/agent-loops.mdx
new file mode 100644
index 0000000000..df00a82d81
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/agent-loops.mdx
@@ -0,0 +1,143 @@
+---
+title: Agent Loops
+description: Supported computer-using agent loops and models
+---
+
+<Callout>
+ A corresponding <a href="https://github.com/trycua/cua/blob/main/notebooks/agent_nb.ipynb" target="_blank">Jupyter Notebook</a> is available for this documentation.
+</Callout>
+
+An **agent loop** runs iteratively until a task is complete:
+
+1. **Observe** → Take a screenshot
+2. **Reason** → VLM decides the next action
+3. **Act** → Execute (click, type, scroll)
+4. **Repeat** → Until done
+
+To run an agent loop simply do:
+
+```python
+from agent import ComputerAgent
+import asyncio
+from computer import Computer
+
+
+async def take_screenshot():
+ async with Computer(
+ os_type="linux",
+ provider_type="cloud",
+ name="your-sandbox-name",
+ api_key="your-api-key"
+ ) as computer:
+
+ agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ max_trajectory_budget=5.0
+ )
+
+ messages = [{"role": "user", "content": "Take a screenshot and tell me what you see"}]
+
+ async for result in agent.run(messages):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+
+
+if __name__ == "__main__":
+ asyncio.run(take_screenshot())
+```
+
+For a list of supported models and configurations, see the [Supported Agents](./supported-agents/computer-use-agents) page.
+
+## Configuration
+
+Before running an agent, set the appropriate API key as an environment variable:
+
+```bash
+# For cloud sandboxes and Cua VLM Router
+export CUA_API_KEY="your-cua-api-key"
+
+# For direct provider access (BYOK - Bring Your Own Key)
+export ANTHROPIC_API_KEY="your-anthropic-key"
+export OPENAI_API_KEY="your-openai-key"
+```
+
+Use `CUA_API_KEY` when using Cua's cloud infrastructure or VLM Router. Use provider-specific keys when connecting directly to Anthropic or OpenAI.
+
+## Sending Tasks
+
+You can send tasks to the agent as a simple string or as a message list for multi-turn conversations:
+
+```python
+# Single task
+async for result in agent.run("Open Firefox and go to google.com"):
+ process(result)
+
+# Multi-turn conversation (continues from previous context)
+messages = [
+ {"role": "user", "content": "Take a screenshot"},
+ {"role": "assistant", "content": "Done. I can see a desktop with Firefox open."},
+ {"role": "user", "content": "Now click the search bar"}
+]
+async for result in agent.run(messages):
+ process(result)
+```
+
+Multi-turn conversations are useful when you need the agent to build on previous actions or when implementing human-in-the-loop workflows.
+
+## Processing Results
+
+Each iteration yields a result containing the agent's outputs and token usage:
+
+```python
+async for result in agent.run(messages):
+ for item in result["output"]:
+ match item["type"]:
+ case "message":
+ # Agent's text response
+ print(item["content"][0]["text"])
+ case "computer_call":
+ # Action the agent is taking (screenshot, click, type)
+ print(f"Action: {item['action']['type']}")
+ case "computer_call_output":
+ # Result of the action (e.g., screenshot image)
+ print(f"Output received for {item['call_id']}")
+
+ # Track costs
+ print(f"Cost so far: ${result['usage']['response_cost']:.4f}")
+```
+
+### Streaming Responses
+
+For real-time feedback, enable streaming to receive partial results as they're generated:
+
+```python
+async for result in agent.run(messages, stream=True):
+ for item in result["output"]:
+ if item["type"] == "message":
+ # Print text as it arrives
+ print(item["content"][0]["text"], end="", flush=True)
+```
+
+## Handling Errors
+
+The agent respects the `max_trajectory_budget` you set. When the budget is exceeded, the agent raises an exception:
+
+```python
+from agent.exceptions import BudgetExceededException
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ max_trajectory_budget=5.0 # Max $5 per run
+)
+
+try:
+ async for result in agent.run(messages):
+ process(result)
+except BudgetExceededException:
+ print("Task exceeded budget limit")
+```
+
+This prevents runaway costs when agents get stuck in loops or take longer than expected.
diff --git a/docs/content/docs/guide/fundamentals/browser-tool.mdx b/docs/content/docs/guide/fundamentals/browser-tool.mdx
new file mode 100644
index 0000000000..0e2df037f8
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/browser-tool.mdx
@@ -0,0 +1,196 @@
+---
+title: Browser Tool
+description: Specialized browser automation for web-focused models
+---
+
+The **Browser Tool** provides a specialized interface for browser automation. While full computer-use models control the entire desktop, some models like Gemini 2.5 Computer-Use and Microsoft Fara are optimized specifically for web interactions. The Browser Tool gives these models browser-specific actions that are more efficient than simulating desktop clicks.
+
+## When to Use Browser Tool
+
+Use the Browser Tool when:
+
+- You're automating web-based workflows (forms, data extraction, navigation)
+- You're using a browser-optimized model (Gemini 2.5, Fara)
+- You want browser-specific actions like direct URL navigation or web search
+
+Use the standard Computer tool when:
+
+- You need to control desktop applications
+- You're using a full computer-use model (Claude, OpenAI, UI-TARS, Qwen)
+- Your workflow spans multiple applications
+
+## Basic Usage
+
+The Browser Tool uses Playwright under the hood to control the browser:
+
+```python
+from computer import Computer
+from agent import ComputerAgent
+from agent.tools import BrowserTool
+
+# Create a computer instance
+computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
+await computer.run()
+
+# Create a browser tool from the computer interface
+browser = BrowserTool(interface=computer)
+
+# Use with a browser-optimized model
+agent = ComputerAgent(
+ model="gemini-2.5-computer-use-preview-10-2025",
+ tools=[browser]
+)
+
+async for result in agent.run("Go to github.com and search for 'cua'"):
+ print(result)
+```
+
+The agent sees the browser viewport and can issue browser-specific commands.
+
+## Browser-Specific Actions
+
+The Browser Tool provides actions that aren't available with standard computer-use:
+
+### Direct URL Navigation
+
+Instead of clicking the address bar and typing, go directly to a URL:
+
+```python
+# Agent can use visit_url action
+await agent.run("Navigate to https://docs.cua.ai")
+```
+
+The model issues a `visit_url` action that immediately loads the page—no keyboard or mouse simulation needed.
+
+### Web Search
+
+Perform searches without navigating to a search engine first:
+
+```python
+# Agent can use web_search action
+await agent.run("Search for 'python async tutorial'")
+```
+
+The `web_search` action opens a search directly, saving multiple interaction steps.
+
+### Browser History
+
+Navigate back without finding and clicking the back button:
+
+```python
+# Agent can use history_back action
+await agent.run("Go back to the previous page")
+```
+
+## Using Browser Tool Directly
+
+You can also call Browser Tool actions programmatically without an agent:
+
+```python
+from agent.tools import BrowserTool
+
+browser = BrowserTool(interface=computer)
+
+# Navigate to a URL
+await browser.visit_url("https://example.com")
+
+# Take a screenshot
+screenshot = await browser.screenshot()
+
+# Click at coordinates
+await browser.click(x=500, y=300)
+
+# Type text
+await browser.type("Hello from Browser Tool")
+
+# Scroll the page (positive = up, negative = down)
+await browser.scroll(delta_x=0, delta_y=500)
+
+# Perform a web search
+await browser.web_search("Python documentation")
+
+# Go back in history
+await browser.history_back()
+```
+
+This is useful for scripted automation where you don't need AI reasoning.
+
+## Coordinate Handling
+
+Browser-optimized models often work with resized images for efficiency. The Browser Tool automatically handles coordinate translation:
+
+1. **Model sees** - A resized screenshot optimized for the VLM
+2. **Model outputs** - Coordinates in the resized image space
+3. **Browser Tool translates** - Converts to actual viewport coordinates
+4. **Playwright executes** - Click/type at the correct screen position
+
+You don't need to handle this manually—coordinates from the model are automatically mapped to the correct viewport position.
+
+## Memory System
+
+The Browser Tool includes a memory feature for multi-step tasks:
+
+```python
+# Agent can memorize facts during execution
+await agent.run("Find the pricing for the Pro plan and remember it, then go to the FAQ page")
+```
+
+The `pause_and_memorize_fact` action lets the agent store information for later reference within the same session.
+
+## Example: Form Automation
+
+Here's a complete example automating a web form:
+
+```python
+from computer import Computer
+from agent import ComputerAgent
+from agent.tools import BrowserTool
+
+computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
+await computer.run()
+
+browser = BrowserTool(interface=computer)
+
+agent = ComputerAgent(
+ model="gemini-2.5-computer-use-preview-10-2025",
+ tools=[browser]
+)
+
+# Multi-step form automation
+instructions = """
+1. Go to https://example.com/contact
+2. Fill in the name field with "John Doe"
+3. Fill in the email field with "[email protected]"
+4. Select "Sales Inquiry" from the dropdown
+5. Type a message asking about enterprise pricing
+6. Click the Submit button
+"""
+
+async for result in agent.run(instructions):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+```
+
+## Supported Models
+
+These models are designed for browser automation and work best with the Browser Tool:
+
+- **Gemini 2.5 Computer-Use** (`gemini-2.5-computer-use-preview-10-2025`)
+- **Microsoft Fara** (`azure_ml/Fara-7B`)
+
+Full computer-use models (Claude, OpenAI, UI-TARS, Qwen) can also use the Browser Tool, but they're designed for broader desktop control and may not take full advantage of browser-specific actions.
+
+## Browser Tool vs Computer Tool
+
+| Feature | Browser Tool | Computer Tool |
+|---------|-------------|---------------|
+| Direct URL navigation | ✅ | ❌ (requires typing) |
+| Web search action | ✅ | ❌ (requires browser UI) |
+| History navigation | ✅ | ❌ (requires clicking) |
+| Desktop applications | ❌ | ✅ |
+| System dialogs | ❌ | ✅ |
+| Multi-application workflows | ❌ | ✅ |
+| Playwright integration | ✅ Native | ❌ |
+
+Choose Browser Tool for web-focused tasks where efficiency matters. Choose Computer Tool for workflows that span multiple applications or require desktop access.
diff --git a/docs/content/docs/guide/fundamentals/callbacks.mdx b/docs/content/docs/guide/fundamentals/callbacks.mdx
new file mode 100644
index 0000000000..21aef0777d
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/callbacks.mdx
@@ -0,0 +1,260 @@
+---
+title: Callbacks
+description: Hook into agent lifecycle events for logging, cost tracking, and more
+---
+
+**Callbacks** let you hook into the agent's execution lifecycle. Use them to log events, track costs, save trajectories, limit context size, or add custom behavior at any point during agent execution.
+
+## Using Callbacks
+
+Pass callbacks when creating your agent:
+
+```python
+from agent import ComputerAgent
+from agent.callbacks import LoggingCallback, BudgetManagerCallback
+import logging
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ callbacks=[
+ LoggingCallback(level=logging.INFO),
+ BudgetManagerCallback(max_budget=5.0)
+ ]
+)
+```
+
+Many callbacks also have shorthand parameters on `ComputerAgent`:
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ verbosity=logging.INFO, # Adds LoggingCallback
+ max_trajectory_budget=5.0, # Adds BudgetManagerCallback
+ only_n_most_recent_images=3, # Adds ImageRetentionCallback
+ trajectory_dir="trajectories", # Adds TrajectorySaverCallback
+ instructions="Be concise" # Adds PromptInstructionsCallback
+)
+```
+
+## Built-in Callbacks
+
+### LoggingCallback
+
+Logs agent lifecycle events with configurable verbosity:
+
+```python
+from agent.callbacks import LoggingCallback
+import logging
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[LoggingCallback(level=logging.DEBUG)]
+)
+
+# Or use shorthand
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ verbosity=logging.INFO
+)
+```
+
+Logs include API calls, computer actions, text responses, and usage statistics. Image URLs are automatically sanitized in logs.
+
+### BudgetManagerCallback
+
+Tracks costs and stops execution when a budget limit is reached:
+
+```python
+from agent.callbacks import BudgetManagerCallback
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[BudgetManagerCallback(
+ max_budget=10.0, # Dollar limit
+ reset_after_each_run=True, # Reset per run (default)
+ raise_error=False # Graceful stop vs exception
+ )]
+)
+
+# Or use shorthand
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ max_trajectory_budget=5.0
+)
+```
+
+When `raise_error=True`, the agent raises `BudgetExceededError` instead of stopping gracefully.
+
+### ImageRetentionCallback
+
+Limits how many screenshots are kept in the message history to prevent context overflow:
+
+```python
+from agent.callbacks import ImageRetentionCallback
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[ImageRetentionCallback(only_n_most_recent_images=3)]
+)
+
+# Or use shorthand
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ only_n_most_recent_images=3
+)
+```
+
+Older screenshots are removed along with their associated computer call items.
+
+### TrajectorySaverCallback
+
+Saves complete agent conversations for debugging and analysis:
+
+```python
+from agent.callbacks import TrajectorySaverCallback
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[TrajectorySaverCallback(
+ trajectory_dir="trajectories",
+ reset_on_run=True, # New trajectory per run
+ screenshot_dir="screenshots" # Optional separate screenshot dir
+ )]
+)
+
+# Or use shorthand
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ trajectory_dir="trajectories"
+)
+```
+
+See [Trajectories](/docs/guide/fundamentals/trajectories) for details on the saved format.
+
+### PromptInstructionsCallback
+
+Prepends custom instructions to every LLM call:
+
+```python
+from agent.callbacks import PromptInstructionsCallback
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[PromptInstructionsCallback("Always confirm before clicking buttons")]
+)
+
+# Or use shorthand
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ instructions="Always confirm before clicking buttons"
+)
+```
+
+This is a simple way to guide agent behavior without modifying agent loops.
+
+## Lifecycle Hooks
+
+Callbacks can implement these hooks (all are optional):
+
+```python
+from agent.callbacks.base import AsyncCallbackHandler
+
+class MyCallback(AsyncCallbackHandler):
+ async def on_run_start(self, kwargs, old_items):
+ """Called when agent.run() begins"""
+ pass
+
+ async def on_run_continue(self, kwargs, old_items, new_items) -> bool:
+ """Called before each iteration. Return False to stop."""
+ return True
+
+ async def on_llm_start(self, messages):
+ """Preprocess messages before LLM call. Return modified messages."""
+ return messages
+
+ async def on_llm_end(self, messages):
+ """Postprocess messages after LLM call. Return modified messages."""
+ return messages
+
+ async def on_usage(self, usage):
+ """Called with token usage info after each LLM call"""
+ print(f"Tokens: {usage.total_tokens}, Cost: ${usage.response_cost:.4f}")
+
+ async def on_computer_call_start(self, item):
+ """Called before a computer action (click, type, etc.)"""
+ pass
+
+ async def on_computer_call_end(self, item, result):
+ """Called after a computer action completes"""
+ pass
+
+ async def on_screenshot(self, screenshot, name):
+ """Called when a screenshot is taken"""
+ pass
+
+ async def on_run_end(self, kwargs, old_items, new_items):
+ """Called when agent.run() completes"""
+ pass
+```
+
+## Creating Custom Callbacks
+
+Build your own callback by extending `AsyncCallbackHandler`:
+
+```python
+from agent.callbacks.base import AsyncCallbackHandler
+
+class ActionCounterCallback(AsyncCallbackHandler):
+ def __init__(self):
+ self.action_count = 0
+
+ async def on_computer_call_end(self, item, result):
+ self.action_count += 1
+ print(f"Actions taken: {self.action_count}")
+
+ async def on_run_end(self, kwargs, old_items, new_items):
+ print(f"Total actions in run: {self.action_count}")
+ self.action_count = 0 # Reset for next run
+
+# Use it
+counter = ActionCounterCallback()
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[counter]
+)
+
+await agent.run("Open Firefox and search for Cua")
+print(f"Final count: {counter.action_count}")
+```
+
+## Callback Execution Order
+
+Callbacks execute in this order during a run:
+
+1. `on_run_start` - Once at the beginning
+2. For each iteration:
+ - `on_run_continue` - Check if should continue
+ - `on_llm_start` - Before LLM call
+ - `on_api_start` - Before API request
+ - `on_api_end` - After API response
+ - `on_usage` - With usage stats
+ - `on_llm_end` - After LLM processing
+ - `on_responses` - With model responses
+ - `on_text` / `on_computer_call_start` / `on_computer_call_end` - Per response item
+ - `on_screenshot` - When screenshots are taken
+3. `on_run_end` - Once at the end
+
+Multiple callbacks are called in the order they appear in the `callbacks` list.
diff --git a/docs/content/docs/guide/fundamentals/computers.mdx b/docs/content/docs/guide/fundamentals/computers.mdx
new file mode 100644
index 0000000000..6cca15b914
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/computers.mdx
@@ -0,0 +1,102 @@
+---
+title: Computer Types
+description: Comparing sandbox providers and their capabilities
+---
+
+{/* prettier-ignore */}
+<Callout>A corresponding <a href="https://github.com/trycua/cua/blob/main/notebooks/computer_nb.ipynb" target="_blank">Jupyter Notebook</a> and <a href="https://github.com/trycua/cua/tree/main/examples/computer-example-ts" target="_blank">NodeJS project</a> are available for this documentation.</Callout>
+
+Cua supports multiple sandbox providers, each with different trade-offs. Choose based on your requirements for OS support, isolation, and deployment environment.
+
+## Provider Comparison
+
+| Provider | OS | Host Requirements | Isolation | Persistence | Best For |
+|----------|-----|-------------------|-----------|-------------|----------|
+| **Cloud** | Linux, Windows, macOS | Any | Full VM | Configurable | Production, teams, CI/CD |
+| **Docker** | Linux | Docker installed | Container | Volume mounts | Local dev, testing |
+| **Lume** | macOS | macOS host | Full VM | Snapshot-based | macOS automation |
+| **Windows Sandbox** | Windows | Win 10 Pro/11 | Sandbox | Ephemeral only | Windows automation |
+| **QEMU Docker** | Linux, Windows, Android | Docker + KVM | Full VM | Disk images | Multi-OS testing |
+| **Host** | Any | None | None | N/A | Debugging (not recommended) |
+
+## Provider Details
+
+### Cloud (`provider_type="cloud"`)
+
+Managed VMs hosted by Cua. No local setup required.
+
+- **OS options**: Linux (Ubuntu), Windows, macOS
+- **`provider_type`**: `"cloud"`
+- **Required params**: `name`, `api_key` (or `CUA_API_KEY` env var)
+- **Persistence**: Sandbox state persists between sessions unless explicitly reset
+
+### Docker (`provider_type="docker"`)
+
+Linux desktops running in Docker containers.
+
+- **OS options**: Linux only (XFCE or Ubuntu/KASM)
+- **`provider_type`**: `"docker"`
+- **Required params**: `image`
+- **Images**: `trycua/cua-xfce:latest` (lightweight), `trycua/cua-ubuntu:latest` (full desktop)
+- **Persistence**: Ephemeral by default, use volume mounts for persistence
+
+### Lume (`provider_type="lume"`)
+
+Native macOS VMs using Apple's Virtualization framework.
+
+- **OS options**: macOS only
+- **`provider_type`**: `"lume"`
+- **Required params**: `name` (image name)
+- **Host requirement**: macOS with Lume CLI installed
+- **Persistence**: Snapshot-based, can restore to clean state
+
+### Windows Sandbox (`provider_type="winsandbox"`)
+
+Built-in Windows isolation feature.
+
+- **OS options**: Windows only
+- **`provider_type`**: `"winsandbox"`
+- **Host requirement**: Windows 10 Pro/Enterprise or Windows 11
+- **Persistence**: Always ephemeral (resets on close)
+- **Additional dep**: `pywinsandbox`
+
+### QEMU Docker (`provider_type="qemu"`)
+
+Full VMs running inside Docker via QEMU emulation.
+
+- **OS options**: Linux, Windows, Android
+- **`provider_type`**: `"qemu"`
+- **Required params**: `image` (golden image path)
+- **Host requirement**: Docker with KVM support
+- **Persistence**: Disk image based
+
+### Host Desktop (`use_host_computer_server=True`)
+
+Direct control of your machine. **Use with caution.**
+
+- **OS options**: Whatever your host runs
+- **No isolation**: Agent actions affect your real system
+- **Use case**: Debugging only, never in production
+
+## Quick Reference
+
+```python
+from computer import Computer
+
+# Cloud (recommended for production)
+computer = Computer(os_type="linux", provider_type="cloud", name="my-sandbox", api_key="...")
+
+# Docker (recommended for local dev)
+computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
+
+# Lume (macOS only)
+computer = Computer(os_type="macos", provider_type="lume", name="macos-sequoia-cua:latest")
+
+# Windows Sandbox (Windows host only)
+computer = Computer(os_type="windows", provider_type="winsandbox", ephemeral=True)
+
+# Host (debugging only)
+computer = Computer(use_host_computer_server=True)
+```
+
+For setup instructions, see [Set Up a Sandbox](/docs/guide/get-started/set-up-sandbox).
diff --git a/docs/content/docs/guide/fundamentals/custom-tools.mdx b/docs/content/docs/guide/fundamentals/custom-tools.mdx
new file mode 100644
index 0000000000..4491fad2d8
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/custom-tools.mdx
@@ -0,0 +1,254 @@
+---
+title: Custom Tools
+description: Extend agent capabilities with your own tools
+---
+
+**Custom tools** let you extend what your agent can do beyond the built-in Computer and Browser tools. Define functions that the agent can call to perform specific tasks like calculations, API calls, file operations, or any custom logic.
+
+## Simple Function Tools
+
+The easiest way to add a tool is to pass a function with a docstring:
+
+```python
+from agent import ComputerAgent
+
+def calculate(a: int, b: int) -> int:
+ """Calculate the sum of two integers"""
+ return a + b
+
+def get_weather(city: str) -> str:
+ """Get current weather for a city"""
+ # Your API call here
+ return f"Weather in {city}: Sunny, 72°F"
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer, calculate, get_weather]
+)
+
+await agent.run("What's 42 + 58? Also check the weather in San Francisco.")
+```
+
+The agent can now call `calculate` and `get_weather` alongside computer actions. Cua automatically extracts the function signature and docstring to create the tool schema.
+
+## Sandboxed Tools
+
+For tools that should run inside the sandbox rather than on your host machine, use the `@sandboxed` decorator:
+
+```python
+from computer.helpers import sandboxed
+
+@sandboxed()
+def read_file(path: str) -> str:
+ """Read contents of a file in the sandbox"""
+ with open(path, 'r') as f:
+ return f.read()
+
+@sandboxed()
+def save_note(filename: str, content: str) -> str:
+ """Save a note to a file in the sandbox"""
+ with open(filename, 'w') as f:
+ f.write(content)
+ return f"Saved to {filename}"
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer, read_file, save_note]
+)
+
+await agent.run("Read the file at /tmp/data.txt and summarize it")
+```
+
+Sandboxed tools execute inside the sandbox's virtual environment, which is safer and can access files on the sandbox's filesystem.
+
+See [Sandboxed Python](/docs/guide/fundamentals/sandboxed-python) for more details.
+
+## Using the BaseTool Class
+
+For more control over tool schema and behavior, extend `BaseTool`:
+
+```python
+from agent.tools import BaseTool, register_tool
+from typing import Union
+
+@register_tool("database_query")
+class DatabaseQueryTool(BaseTool):
+ def __init__(self, connection_string: str):
+ self.connection_string = connection_string
+
+ @property
+ def description(self) -> str:
+ return "Execute a read-only SQL query against the database"
+
+ @property
+ def parameters(self) -> dict:
+ return {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "SQL SELECT query to execute"
+ }
+ },
+ "required": ["query"]
+ }
+
+ def call(self, params: Union[str, dict], **kwargs) -> Union[str, dict]:
+ if isinstance(params, str):
+ params = {"query": params}
+
+ query = params["query"]
+ # Execute query and return results
+ return {"rows": [...], "count": 10}
+
+# Use it
+db_tool = DatabaseQueryTool("postgresql://...")
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer, db_tool]
+)
+```
+
+The `@register_tool` decorator registers your tool class with a name that the agent uses to invoke it.
+
+## Tool Schema
+
+Tools need a schema so the model knows how to call them. For function tools, Cua generates the schema automatically from type hints and docstrings.
+
+For `BaseTool` classes, you define the schema in the `parameters` property:
+
+```python
+@property
+def parameters(self) -> dict:
+ return {
+ "type": "object",
+ "properties": {
+ "param_name": {
+ "type": "string",
+ "description": "What this parameter does"
+ },
+ "optional_param": {
+ "type": "integer",
+ "description": "An optional number"
+ }
+ },
+ "required": ["param_name"] # Only required params
+ }
+```
+
+This follows the JSON Schema format used by OpenAI and other providers.
+
+## Async Tools
+
+Both sync and async functions work as tools:
+
+```python
+import asyncio
+import httpx
+
+async def fetch_url(url: str) -> str:
+ """Fetch content from a URL"""
+ async with httpx.AsyncClient() as client:
+ response = await client.get(url)
+ return response.text[:1000] # First 1000 chars
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer, fetch_url]
+)
+```
+
+Sync functions are automatically run in a thread pool to avoid blocking.
+
+## Combining Tools
+
+Pass multiple tools of different types:
+
+```python
+from agent import ComputerAgent
+from agent.tools import BrowserTool
+from computer.helpers import sandboxed
+
+# Built-in tool
+browser = BrowserTool(interface=computer)
+
+# Simple function
+def calculate(expression: str) -> float:
+ """Evaluate a math expression"""
+ return eval(expression) # Use with caution
+
+# Sandboxed function
+@sandboxed()
+def process_data(data: list) -> dict:
+ """Process data inside the sandbox"""
+ import pandas as pd
+ df = pd.DataFrame(data)
+ return df.describe().to_dict()
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer, browser, calculate, process_data]
+)
+```
+
+The agent decides which tool to use based on the task.
+
+## Error Handling
+
+Tools can raise exceptions, which are passed back to the model:
+
+```python
+from agent.tools import ToolError
+
+def divide(a: float, b: float) -> float:
+ """Divide a by b"""
+ if b == 0:
+ raise ToolError("Cannot divide by zero")
+ return a / b
+```
+
+The model sees the error message and can adjust its approach.
+
+## Example: File Management Tools
+
+Here's a complete example with file management tools:
+
+```python
+from agent import ComputerAgent
+from computer.helpers import sandboxed
+
+@sandboxed()
+def list_files(directory: str = ".") -> list:
+ """List files in a directory"""
+ import os
+ return os.listdir(directory)
+
+@sandboxed()
+def read_file(path: str) -> str:
+ """Read a file's contents"""
+ with open(path, 'r') as f:
+ return f.read()
+
+@sandboxed()
+def write_file(path: str, content: str) -> str:
+ """Write content to a file"""
+ with open(path, 'w') as f:
+ f.write(content)
+ return f"Written {len(content)} bytes to {path}"
+
+@sandboxed()
+def append_file(path: str, content: str) -> str:
+ """Append content to a file"""
+ with open(path, 'a') as f:
+ f.write(content)
+ return f"Appended {len(content)} bytes to {path}"
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer, list_files, read_file, write_file, append_file]
+)
+
+await agent.run("Create a file called notes.txt with today's date, then read it back")
+```
+
+The agent can now manage files directly without needing to use the UI.
diff --git a/docs/content/docs/guide/fundamentals/meta.json b/docs/content/docs/guide/fundamentals/meta.json
new file mode 100644
index 0000000000..066ae3a14b
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/meta.json
@@ -0,0 +1,17 @@
+{
+ "title": "Fundamentals",
+ "description": "Core concepts for building with Cua",
+ "icon": "Lightbulb",
+ "defaultOpen": true,
+ "pages": [
+ "agent-loops",
+ "computers",
+ "vlms",
+ "browser-tool",
+ "sandboxed-python",
+ "custom-tools",
+ "callbacks",
+ "trajectories",
+ "tracing"
+ ]
+}
diff --git a/docs/content/docs/guide/fundamentals/sandboxed-python.mdx b/docs/content/docs/guide/fundamentals/sandboxed-python.mdx
new file mode 100644
index 0000000000..4599af62cf
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/sandboxed-python.mdx
@@ -0,0 +1,225 @@
+---
+title: Sandboxed Python
+description: Execute Python functions securely in isolated virtual environments
+---
+
+**Sandboxed Python** lets you run Python code inside your sandbox rather than on your host machine. This bridges the gap between UI automation (clicking buttons, filling forms) and data processing (API calls, file manipulation, computation).
+
+## Why Run Code in the Sandbox?
+
+When your agent scrapes data from a UI, you often need to process it—call an API, transform the data, or save it somewhere. Running this code on your host has drawbacks:
+
+- **Security risk** - Untrusted code could affect your system
+- **Dependency conflicts** - Packages might clash with your local environment
+- **Reproducibility** - Different hosts have different setups
+
+Sandboxed Python executes your functions inside the sandbox's isolated environment, using virtual environments you control.
+
+## Running a Function in the Sandbox
+
+Here's the basic pattern:
+
+```python
+from computer import Computer
+
+computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
+await computer.run()
+
+# First, install any packages you need
+await computer.venv_install("my_env", ["requests", "pandas"])
+
+# Define a function to run remotely
+def fetch_data(url):
+ import requests
+ import pandas as pd
+
+ response = requests.get(url)
+ data = response.json()
+ df = pd.DataFrame(data)
+ return {"rows": len(df), "columns": list(df.columns)}
+
+# Execute it in the sandbox
+result = await computer.venv_exec("my_env", fetch_data, "https://api.example.com/data")
+print(result) # {"rows": 100, "columns": ["id", "name", "value"]}
+```
+
+The function runs inside the sandbox, not on your host. Cua automatically extracts the function's source code, serializes the arguments, sends everything to the sandbox, executes it, and returns the result.
+
+## Setting Up Virtual Environments
+
+Before running code, create a virtual environment and install packages:
+
+```python
+# Create "data_env" and install packages
+await computer.venv_install("data_env", ["numpy", "scipy", "matplotlib"])
+
+# Add more packages later
+await computer.venv_install("data_env", ["seaborn", "scikit-learn"])
+```
+
+Virtual environments are stored in `~/.venvs/{name}` on Linux/macOS or `%USERPROFILE%\.venvs\{name}` on Windows sandboxes. They persist across function calls.
+
+You can also run arbitrary shell commands with the environment activated:
+
+```python
+# Check installed packages
+result = await computer.venv_cmd("data_env", "pip list")
+print(result.output)
+
+# Run a script
+result = await computer.venv_cmd("data_env", "python /path/to/script.py")
+```
+
+## Using the `@sandboxed` Decorator
+
+For cleaner code, use the decorator to mark functions for remote execution:
+
+```python
+from computer import Computer
+from computer.helpers import sandboxed
+
+computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
+await computer.run()
+
+await computer.venv_install("api_env", ["requests"])
+
+@sandboxed("api_env")
+def call_api(endpoint, payload):
+ import requests
+ response = requests.post(endpoint, json=payload)
+ response.raise_for_status()
+ return response.json()
+
+# Call it like a normal async function
+result = await call_api("https://api.example.com/submit", {"name": "test"})
+```
+
+The decorator transforms the function so that calling it executes remotely. You can configure retry behavior and specify which computer instance to use:
+
+```python
+@sandboxed(venv_name="my_env", computer=computer, max_retries=5)
+def unreliable_operation():
+ # Will retry up to 5 times on failure
+ ...
+```
+
+## How It Works Under the Hood
+
+When you call a sandboxed function, Cua:
+
+1. **Extracts source code** - Uses Python's AST to analyze your function
+2. **Detects dependencies** - Automatically includes imports, helper functions, and closure variables
+3. **Serializes arguments** - JSON-encodes and base64-wraps data for safe transport
+4. **Executes remotely** - Runs the code in the sandbox's virtual environment
+5. **Returns results** - Deserializes the output back to Python objects
+
+This means your function can call other local functions, and they'll be included automatically:
+
+```python
+def helper(x):
+ return x * 2
+
+@sandboxed("my_env")
+def process(value):
+ return helper(value) + 10 # helper() is included automatically
+
+result = await process(5) # Returns 20
+```
+
+## Handling Errors
+
+Exceptions raised in the sandbox propagate back with full tracebacks:
+
+```python
+@sandboxed("my_env")
+def might_fail(x):
+ if x < 0:
+ raise ValueError(f"Expected positive number, got {x}")
+ return x ** 2
+
+try:
+ result = await might_fail(-5)
+except ValueError as e:
+ print(f"Error from sandbox: {e}")
+ # Traceback shows the exact line in your function
+```
+
+The traceback includes both the remote stack (where the error occurred in the sandbox) and local context (where you called the function).
+
+## Running Long Tasks in the Background
+
+For tasks that take a while, run them in the background to avoid blocking:
+
+```python
+def long_running_analysis(data_path):
+ import pandas as pd
+ import time
+
+ df = pd.read_csv(data_path)
+ # ... expensive computation ...
+ time.sleep(60)
+ return {"processed": len(df)}
+
+# Start without waiting
+pid = await computer.venv_exec_background(
+ "data_env",
+ long_running_analysis,
+ "/tmp/large_dataset.csv",
+ requirements=["pandas"] # Auto-installs if missing
+)
+
+print(f"Background task running with PID: {pid}")
+
+# Continue with other work while it runs
+```
+
+## Example: Browser Automation with Playwright
+
+Combine UI automation with Playwright running inside the sandbox:
+
+```python
+await computer.venv_install("browser_env", ["playwright"])
+await computer.venv_cmd("browser_env", "playwright install chromium")
+
+@sandboxed("browser_env")
+def scrape_page(url):
+ from playwright.sync_api import sync_playwright
+
+ with sync_playwright() as p:
+ browser = p.chromium.launch()
+ page = browser.new_page()
+ page.goto(url)
+
+ title = page.title()
+ links = [a.get_attribute("href") for a in page.query_selector_all("a")]
+
+ browser.close()
+
+ return {"title": title, "link_count": len(links)}
+
+result = await scrape_page("https://example.com")
+```
+
+## Example: Processing Agent-Scraped Data
+
+After your agent extracts data from a UI, process it in the sandbox:
+
+```python
+# Agent scrapes a table from the UI
+table_data = await agent.run("Extract the sales data table from the spreadsheet")
+
+@sandboxed("data_env")
+def analyze_sales(data):
+ import pandas as pd
+
+ df = pd.DataFrame(data)
+ return {
+ "total_revenue": df["revenue"].sum(),
+ "top_product": df.loc[df["revenue"].idxmax(), "product"],
+ "monthly_avg": df.groupby("month")["revenue"].mean().to_dict()
+ }
+
+analysis = await analyze_sales(table_data)
+```
+
+This pattern keeps your host clean while giving agents full computational capabilities inside isolated environments.
diff --git a/docs/content/docs/guide/fundamentals/tracing.mdx b/docs/content/docs/guide/fundamentals/tracing.mdx
new file mode 100644
index 0000000000..cc34baa7d9
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/tracing.mdx
@@ -0,0 +1,271 @@
+---
+title: Tracing API
+description: Record computer interactions for debugging, training, and analysis
+---
+
+The **Tracing API** records everything that happens on a Computer—screenshots, API calls, accessibility trees, and custom metadata. Unlike [Trajectories](/docs/guide/fundamentals/trajectories) which are specific to ComputerAgent, tracing works with any Computer usage: custom agents, scripts, human-in-the-loop workflows, or RPA.
+
+## Basic Usage
+
+Start and stop tracing around any computer operations:
+
+```python
+from computer import Computer
+
+computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
+await computer.run()
+
+# Start tracing
+await computer.tracing.start()
+
+# Perform operations (these get recorded)
+await computer.interface.left_click(100, 200)
+await computer.interface.type_text("Hello, World!")
+screenshot = await computer.interface.screenshot()
+
+# Stop and save trace
+trace_path = await computer.tracing.stop()
+print(f"Trace saved to: {trace_path}")
+```
+
+This creates a ZIP archive containing all recorded events, screenshots, and metadata.
+
+## What Gets Recorded
+
+By default, tracing captures:
+
+- **Screenshots** - Taken automatically after key actions (clicks, typing, key presses)
+- **API calls** - Every method called on `computer.interface` with arguments and results
+- **Timestamps** - Absolute and relative timing for each event
+- **Errors** - Any exceptions that occur during operations
+
+You can also enable:
+
+- **Accessibility trees** - Semantic structure of the UI (useful for debugging element detection)
+- **Custom metadata** - Your own key-value data added during the session
+
+## Configuration
+
+Control what gets recorded with start options:
+
+```python
+await computer.tracing.start({
+ "name": "my-workflow", # Custom trace name
+ "screenshots": True, # Capture screenshots (default: True)
+ "api_calls": True, # Log interface calls (default: True)
+ "accessibility_tree": False, # Record a11y trees (default: False)
+ "metadata": True, # Enable custom metadata (default: True)
+})
+```
+
+Control output format when stopping:
+
+```python
+# Save as ZIP archive (default)
+trace_path = await computer.tracing.stop({"format": "zip"})
+
+# Save as directory (easier to browse)
+trace_path = await computer.tracing.stop({"format": "dir"})
+
+# Custom output path
+trace_path = await computer.tracing.stop({"path": "/tmp/my-trace.zip"})
+```
+
+## Output Format
+
+Traces are saved with this structure:
+
+```
+trace_20250103_143052_abc123/
+├── trace_metadata.json # Overall trace info
+├── event_000001_trace_start.json
+├── event_000002_api_call.json
+├── event_000003_api_call.json
+├── 000001_initial_screenshot.png
+├── 000002_after_left_click.png
+├── 000003_after_type_text.png
+└── event_000004_trace_end.json
+```
+
+**trace_metadata.json:**
+```json
+{
+ "trace_id": "trace_20250103_143052_abc123",
+ "start_time": "2025-01-03T14:30:52Z",
+ "end_time": "2025-01-03T14:31:15Z",
+ "duration": 23.456,
+ "total_events": 12,
+ "screenshot_count": 5,
+ "config": {
+ "screenshots": true,
+ "api_calls": true
+ }
+}
+```
+
+**API call event:**
+```json
+{
+ "type": "api_call",
+ "timestamp": 1704295852.789,
+ "relative_time": 3.666,
+ "data": {
+ "method": "left_click",
+ "args": {"x": 100, "y": 200},
+ "result": null,
+ "error": null,
+ "screenshot": "000002_after_left_click.png",
+ "success": true
+ }
+}
+```
+
+## Adding Custom Metadata
+
+Add context during tracing for later analysis:
+
+```python
+await computer.tracing.start()
+
+# Add metadata at any point
+await computer.tracing.add_metadata("workflow", "login-flow")
+await computer.tracing.add_metadata("user_id", "test-user-123")
+await computer.tracing.add_metadata("step", "entering-credentials")
+
+await computer.interface.type_text("username")
+
+await computer.tracing.add_metadata("step", "clicking-submit")
+await computer.interface.left_click(500, 300)
+
+trace_path = await computer.tracing.stop()
+```
+
+Metadata appears in the trace alongside events, making it easy to correlate actions with your application context.
+
+## Tracing with ComputerAgent
+
+Tracing works alongside ComputerAgent—you get both agent-level information and detailed computer interaction logs:
+
+```python
+from computer import Computer
+from agent import ComputerAgent
+
+computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
+await computer.run()
+
+# Start tracing before agent runs
+await computer.tracing.start({"name": "agent-task"})
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ trajectory_dir="trajectories" # Can use both!
+)
+
+async for result in agent.run("Open Firefox and search for Cua"):
+ pass
+
+# Stop tracing after agent completes
+trace_path = await computer.tracing.stop()
+```
+
+Now you have:
+- **Trajectory** - Agent's reasoning, API calls to the model, action decisions
+- **Trace** - Low-level computer interactions, screenshots, timing
+
+## Tracing vs Trajectories
+
+| Feature | Tracing API | Trajectories |
+|---------|-------------|--------------|
+| Works with | Any Computer usage | ComputerAgent only |
+| Records | Computer interface calls | Agent reasoning + actions |
+| Screenshots | After each action | Per agent turn |
+| Accessibility data | Optional | No |
+| Custom metadata | Yes | No |
+| Output format | ZIP or directory | Directory with turns |
+| Real-time control | Start/stop anytime | Per agent run |
+
+**Use Tracing when:**
+- Building custom agents or scripts
+- Recording human demonstrations
+- Debugging computer interface issues
+- Need fine-grained timing data
+- Want accessibility tree snapshots
+
+**Use Trajectories when:**
+- Using ComputerAgent
+- Need agent reasoning and model responses
+- Want turn-by-turn organization
+- Using the trajectory viewer
+
+## Recording Human Demonstrations
+
+Tracing is ideal for capturing human-driven workflows as training data:
+
+```python
+computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
+await computer.run()
+
+await computer.tracing.start({
+ "name": "human-demo-login",
+ "accessibility_tree": True # Capture UI structure
+})
+
+# Human performs actions via VNC or other interface
+# Meanwhile, your script can add context:
+await computer.tracing.add_metadata("task", "login-to-dashboard")
+await computer.tracing.add_metadata("demonstrator", "expert-user-1")
+
+# Wait for human to finish...
+input("Press Enter when done with demonstration")
+
+trace_path = await computer.tracing.stop()
+print(f"Demo saved to: {trace_path}")
+```
+
+## Privacy Considerations
+
+Tracing is designed with privacy in mind:
+
+- **Clipboard** - Only the length is recorded, not the actual content
+- **Screenshots** - Can be disabled entirely with `screenshots: False`
+- **Passwords** - Text input is recorded, so consider disabling for sensitive workflows
+
+```python
+# Privacy-conscious tracing
+await computer.tracing.start({
+ "screenshots": False, # No visual data
+ "api_calls": True # Still log actions
+})
+```
+
+## Debugging with Traces
+
+When something goes wrong, traces show exactly what happened:
+
+1. **Open trace_metadata.json** to see the overview
+2. **Check event files** in order to find where things went wrong
+3. **Look at screenshots** to see what the screen looked like
+4. **Check error fields** in API call events for exceptions
+
+```python
+import json
+from pathlib import Path
+
+# Load a trace
+trace_dir = Path("trace_20250103_143052_abc123")
+
+with open(trace_dir / "trace_metadata.json") as f:
+ metadata = json.load(f)
+
+print(f"Duration: {metadata['duration']:.2f}s")
+print(f"Events: {metadata['total_events']}")
+print(f"Screenshots: {metadata['screenshot_count']}")
+
+# Find failed API calls
+for event_file in sorted(trace_dir.glob("event_*.json")):
+ with open(event_file) as f:
+ event = json.load(f)
+ if event.get("data", {}).get("error"):
+ print(f"Error in {event_file.name}: {event['data']['error']}")
+```
diff --git a/docs/content/docs/guide/fundamentals/trajectories.mdx b/docs/content/docs/guide/fundamentals/trajectories.mdx
new file mode 100644
index 0000000000..c523c0e4c8
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/trajectories.mdx
@@ -0,0 +1,199 @@
+---
+title: Trajectories
+description: Save and analyze agent execution for debugging and training
+---
+
+**Trajectories** record everything your agent does—every API call, response, screenshot, and action. Use them to debug issues, understand agent behavior, or create training data.
+
+## Saving Trajectories
+
+Enable trajectory saving with the `trajectory_dir` parameter:
+
+```python
+from agent import ComputerAgent
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ trajectory_dir="trajectories"
+)
+
+await agent.run("Open Firefox and search for Cua documentation")
+```
+
+This creates a directory structure with everything the agent did:
+
+```
+trajectories/
+└── 2025-01-03_claude_143022_a1b2/
+ ├── metadata.json
+ ├── turn_000/
+ │ ├── 0000_api_start.json
+ │ ├── 0001_api_result.json
+ │ ├── 0002_screenshot.png
+ │ ├── 0003_agent_response.json
+ │ ├── 0004_computer_call_result.json
+ │ └── 0005_screenshot_action.png
+ └── turn_001/
+ └── ...
+```
+
+## What Gets Saved
+
+Each trajectory includes:
+
+- **metadata.json** - Run info, timestamps, total token usage, and costs
+- **API calls** - The exact messages sent to the model
+- **Model responses** - What the model decided to do
+- **Screenshots** - Raw screenshots at each step
+- **Action screenshots** - Screenshots with crosshairs showing where actions occurred
+- **Computer call results** - Outcomes of clicks, typing, and other actions
+
+## Trajectory Structure
+
+The trajectory ID encodes useful information:
+
+```
+2025-01-03_claude_143022_a1b2
+│ │ │ └── Unique ID (first 4 chars of UUID)
+│ │ └── Time (HHMMSS)
+│ └── Model name
+└── Date (YYYY-MM-DD)
+```
+
+Each turn (iteration of the agent loop) gets its own directory with sequentially numbered artifacts.
+
+## Configuration Options
+
+Control trajectory behavior with a config dict:
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ trajectory_dir={
+ "trajectory_dir": "trajectories",
+ "reset_on_run": False, # Continue same trajectory across runs
+ "screenshot_dir": "screenshots" # Save screenshots separately
+ }
+)
+```
+
+**Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `trajectory_dir` | Required | Base directory for trajectories |
+| `reset_on_run` | `True` | Create new trajectory ID per run |
+| `screenshot_dir` | `None` | Optional separate directory for screenshots |
+
+Setting `reset_on_run=False` appends to the same trajectory across multiple `agent.run()` calls, useful for multi-step workflows.
+
+## Viewing Trajectories
+
+### Online Viewer
+
+Upload your trajectory folder to the [Cua Trajectory Viewer](https://cua.ai/trajectory-viewer) for interactive exploration:
+
+- Timeline slider to step through actions
+- Screenshot gallery with action annotations
+- API call and response inspection
+- Usage statistics
+
+The viewer runs entirely in your browser—no data is uploaded to any server.
+
+### Manual Inspection
+
+Open the JSON files directly to see exactly what happened:
+
+**metadata.json:**
+```json
+{
+ "trajectory_id": "2025-01-03_claude_143022_a1b2",
+ "created_at": "2025-01-03T14:30:22Z",
+ "status": "completed",
+ "total_usage": {
+ "total_tokens": 5000,
+ "response_cost": 0.50
+ },
+ "total_turns": 5
+}
+```
+
+**agent_response.json:**
+```json
+{
+ "type": "computer_call",
+ "action": {
+ "type": "click",
+ "coordinate": [500, 300]
+ },
+ "call_id": "call_abc123"
+}
+```
+
+## Action Crosshairs
+
+Screenshots are saved twice: once raw, once with crosshairs showing where the agent clicked. The `_action.png` suffix indicates an annotated screenshot:
+
+- `0002_screenshot.png` - Original screenshot
+- `0005_screenshot_action.png` - Screenshot with red crosshair at click location
+
+This makes it easy to see exactly where the agent intended to click, which is invaluable for debugging misclicks.
+
+## Using Trajectories for Debugging
+
+When an agent fails, trajectories help you understand why:
+
+1. **Open the trajectory folder** and find the turn where things went wrong
+2. **Check the screenshot** to see what the agent saw
+3. **Check the action screenshot** to see where it clicked
+4. **Read the API result** to see what the model decided
+5. **Compare to the computer_call_result** to see what actually happened
+
+Common issues trajectories help identify:
+
+- **Wrong element clicked** - Crosshair shows the agent clicked the wrong button
+- **Element not visible** - Screenshot shows the target was off-screen or hidden
+- **Timing issue** - Screenshot shows page wasn't fully loaded
+- **Misinterpretation** - Model response shows incorrect reasoning
+
+## Example: Saving and Analyzing
+
+```python
+from agent import ComputerAgent
+from pathlib import Path
+import json
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ trajectory_dir="trajectories"
+)
+
+await agent.run("Log into the admin panel and export user data")
+
+# Find the latest trajectory
+trajectories = sorted(Path("trajectories").iterdir())
+latest = trajectories[-1]
+
+# Load metadata
+with open(latest / "metadata.json") as f:
+ metadata = json.load(f)
+
+print(f"Trajectory: {metadata['trajectory_id']}")
+print(f"Status: {metadata['status']}")
+print(f"Turns: {metadata['total_turns']}")
+print(f"Cost: ${metadata['total_usage']['response_cost']:.4f}")
+```
+
+## Training Data
+
+Trajectories can be used as training data for fine-tuning computer-use models. The structured format includes:
+
+- Input screenshots
+- Model decisions
+- Action coordinates
+- Outcomes
+
+This is the same format used for collecting human demonstrations for training.
diff --git a/docs/content/docs/guide/fundamentals/vlms.mdx b/docs/content/docs/guide/fundamentals/vlms.mdx
new file mode 100644
index 0000000000..9b728a534a
--- /dev/null
+++ b/docs/content/docs/guide/fundamentals/vlms.mdx
@@ -0,0 +1,235 @@
+---
+title: Vision Language Models
+description: VLMs supported by the Cua Agent Framework
+---
+
+A **Vision Language Model (VLM)** is the AI that powers your computer-use agent. It sees screenshots, reasons about what's on screen, and decides what action to take next. Cua supports models from cloud providers, open-source projects, and local inference.
+
+## Using a Model
+
+Specify the model when creating your agent:
+
+```python
+from computer import Computer
+from agent import ComputerAgent
+
+computer = Computer(os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest")
+await computer.run()
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+)
+
+async for result in agent.run("Open Firefox and search for 'Cua'"):
+ print(result)
+```
+
+The model string tells Cua which provider and model to use. Cua automatically selects the right agent loop implementation for each model.
+
+## Cloud Providers
+
+Cloud-hosted models offer the best accuracy and require no local GPU. You'll need an API key from the provider (or use Cua VLM Router for unified access).
+
+### Anthropic Claude
+
+Claude models are optimized for computer-use with native tool support.
+
+```python
+# Claude Sonnet 4.5 - best balance of speed and accuracy
+agent = ComputerAgent(model="anthropic/claude-sonnet-4-5-20250929", tools=[computer])
+
+# Claude Haiku 4.5 - faster, lower cost
+agent = ComputerAgent(model="anthropic/claude-haiku-4-5-20250929", tools=[computer])
+```
+
+Set your API key:
+
+```bash
+export ANTHROPIC_API_KEY="your-key"
+```
+
+### OpenAI
+
+OpenAI's computer-use preview model:
+
+```python
+agent = ComputerAgent(model="openai/computer-use-preview", tools=[computer])
+```
+
+```bash
+export OPENAI_API_KEY="your-key"
+```
+
+### Google Gemini
+
+Gemini 2.5 Computer-Use is optimized for **browser automation** rather than full desktop control. Use it with the [Browser Tool](/docs/guide/fundamentals/browser-tool) for web-based tasks:
+
+```python
+from agent.tools import BrowserTool
+
+# Use with BrowserTool for web automation
+agent = ComputerAgent(model="gemini-2.5-computer-use-preview-10-2025", tools=[browser])
+```
+
+```bash
+export GOOGLE_API_KEY="your-key"
+```
+
+For full desktop computer-use, consider Anthropic Claude or OpenAI instead.
+
+### Microsoft Fara
+
+Fara is Microsoft's browser automation model, available via Azure ML. Like Gemini 2.5, it's designed for web tasks and works with the [Browser Tool](/docs/guide/fundamentals/browser-tool):
+
+```python
+from agent.tools import BrowserTool
+
+agent = ComputerAgent(
+ model="azure_ml/Fara-7B",
+ tools=[browser],
+ api_base="https://your-azure-endpoint.inference.ml.azure.com"
+)
+```
+
+## Local Models
+
+Run models on your own hardware for privacy, cost savings, or air-gapped environments. Local models require a GPU with sufficient VRAM (typically 16GB+ for 7B models).
+
+### Using HuggingFace Models
+
+```python
+# UI-TARS - ByteDance's full computer-use model
+agent = ComputerAgent(
+ model="huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B",
+ tools=[computer]
+)
+
+# Qwen 2.5 VL - Alibaba's full computer-use model
+agent = ComputerAgent(
+ model="huggingface-local/Qwen/Qwen2.5-VL-7B-Instruct",
+ tools=[computer]
+)
+```
+
+The first run downloads model weights from HuggingFace. Subsequent runs load from cache.
+
+### Using MLX (Apple Silicon)
+
+For M1/M2/M3 Macs, MLX provides optimized inference:
+
+```python
+agent = ComputerAgent(
+ model="mlx-vlm/Qwen/Qwen2.5-VL-7B-Instruct",
+ tools=[computer]
+)
+```
+
+MLX models run efficiently on Apple's unified memory architecture.
+
+## Composed Models
+
+Some models excel at **grounding** (finding UI elements) but can't reason about tasks. Others are great at **planning** but can't precisely locate elements. Composed models combine both:
+
+```python
+# Format: grounding_model+planning_model
+agent = ComputerAgent(
+ model="huggingface-local/HelloKKMe/GTA1-7B+anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+)
+```
+
+The `+` syntax tells Cua to use a two-stage approach:
+
+1. **Grounding stage** - The first model (GTA1) analyzes the screenshot and identifies UI element coordinates
+2. **Planning stage** - The second model (Claude) receives the element list and decides which to interact with
+
+This is useful when you want local grounding (privacy, cost) with cloud reasoning (accuracy):
+
+```python
+# Local grounding + cloud planning
+"moondream3+anthropic/claude-sonnet-4-5-20250929"
+"omniparser+openai/gpt-4o"
+"huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B+openai/gpt-4o"
+```
+
+## Cua VLM Router
+
+Instead of managing multiple API keys, use Cua VLM Router for unified access:
+
+```python
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer]
+)
+```
+
+```bash
+export CUA_API_KEY="your-cua-key"
+```
+
+The router provides:
+
+- Single API key for all supported providers
+- Automatic fallback between providers
+- Unified usage tracking and billing
+
+See [Cua VLM Router](/docs/guide/model-providers/cua-vlm-router) for details.
+
+## Model Capabilities
+
+Models fall into three categories based on what they can control:
+
+### Full Computer-Use
+
+These models can control any desktop application—clicking, typing, scrolling across the entire screen. They work with the standard `Computer` tool:
+
+- **Anthropic Claude** (all versions)
+- **OpenAI computer-use-preview**
+- **UI-TARS** (ByteDance)
+- **Qwen 2.5 VL** (Alibaba)
+
+```python
+# Full desktop control
+agent = ComputerAgent(model="anthropic/claude-sonnet-4-5-20250929", tools=[computer])
+```
+
+### Browser-Only
+
+These models are optimized for web automation. They work with the `BrowserTool` and provide browser-specific actions like URL navigation and web search:
+
+- **Gemini 2.5 Computer-Use** (Google)
+- **Fara** (Microsoft)
+
+```python
+# Browser automation only
+agent = ComputerAgent(model="gemini-2.5-computer-use-preview-10-2025", tools=[browser])
+```
+
+See [Browser Tool](/docs/guide/fundamentals/browser-tool) for details.
+
+### Grounding-Only
+
+These models can locate UI elements but can't reason about what action to take. They must be composed with a planning model:
+
+- **GTA1** (grounding)
+- **OmniParser** (Microsoft, UI element detection)
+- **Moondream3** (lightweight grounding)
+
+```python
+# Must be composed with a planning model
+"omniparser+openai/gpt-4o"
+"huggingface-local/HelloKKMe/GTA1-7B+anthropic/claude-sonnet-4-5-20250929"
+```
+
+## Choosing a Model
+
+**For full desktop automation:** Use Claude Sonnet 4.5 or OpenAI computer-use-preview. They handle complex UIs and multi-application workflows.
+
+**For web automation:** Use Gemini 2.5 or Fara with the Browser Tool. They have browser-specific optimizations like direct URL navigation.
+
+**For local development:** UI-TARS 1.5 7B or Qwen 2.5 VL run well on consumer GPUs without API keys.
+
+**For cost optimization:** Compose a local grounding model with a cloud planner. The grounding model handles visual processing locally, reducing API calls.
+
+**For air-gapped environments:** UI-TARS or Qwen run fully offline with no external API calls.
diff --git a/docs/content/docs/guide/get-started/meta.json b/docs/content/docs/guide/get-started/meta.json
new file mode 100644
index 0000000000..a665a79ac2
--- /dev/null
+++ b/docs/content/docs/guide/get-started/meta.json
@@ -0,0 +1,7 @@
+{
+ "title": "Get Started",
+ "description": "Get started with Cua",
+ "defaultOpen": true,
+ "icon": "Rocket",
+ "pages": ["what-is-cua", "what-is-computer-use-agent", "what-is-desktop-sandbox", "set-up-sandbox", "using-computer-sdk", "using-agent-sdk", "using-cloud-cli"]
+}
diff --git a/docs/content/docs/guide/get-started/set-up-sandbox.mdx b/docs/content/docs/guide/get-started/set-up-sandbox.mdx
new file mode 100644
index 0000000000..8530c0b0cf
--- /dev/null
+++ b/docs/content/docs/guide/get-started/set-up-sandbox.mdx
@@ -0,0 +1,200 @@
+---
+title: Set Up a Sandbox
+description: Create an isolated environment for your computer-use agents
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Choose how you want to run your Cua sandbox. This will be the isolated environment where your automated tasks execute safely.
+
+<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'QEMU Docker', 'macOS Sandbox', 'Windows Sandbox']}>
+ <Tab value="Cloud Sandbox">
+
+ Create and manage cloud sandboxes that run Linux (Ubuntu), Windows, or macOS.
+
+ **First, create your API key:**
+
+ 1. Go to [cua.ai/signin](https://cua.ai/signin)
+ 2. Navigate to **Dashboard > API Keys > New API Key** to create your API key
+ 3. **Important:** Copy and save your API key immediately - you won't be able to see it again (you'll need to regenerate if lost)
+
+ **Then, create your sandbox using either option:**
+
+ **Option 1: Via Website**
+
+ 1. Navigate to **Dashboard > Sandboxes > Create Sandbox**
+ 2. Create a sandbox, choosing **Linux**, **Windows**, or **macOS**
+
+ ![Create Sandbox Instance](/img/sandbox-create.png)
+
+ 3. Note your sandbox name
+
+ **Option 2: Via CLI**
+
+ 1. Install the Cua CLI:
+ ```bash
+ # macOS/Linux
+ curl -LsSf https://cua.ai/cli/install.sh | sh
+
+ # Windows
+ powershell -ExecutionPolicy ByPass -c "irm https://cua.ai/cli/install.ps1 | iex"
+ ```
+
+ 2. Login and create a sandbox:
+ ```bash
+ cua auth login
+ cua sb create --os linux --size small --region north-america
+ ```
+
+ 3. Note your sandbox name and password from the output
+
+ Your Cloud Sandbox will be automatically configured and ready to use.
+
+ </Tab>
+ <Tab value="Linux on Docker">
+
+ Run Linux desktop locally on macOS, Windows, or Linux hosts.
+
+ 1. Install Docker Desktop or Docker Engine
+
+ 2. Pull a Cua Docker image:
+
+ ```bash
+ # XFCE (Lightweight) - recommended for most use cases
+ docker pull --platform=linux/amd64 trycua/cua-xfce:latest
+
+ # OR KASM (Full-Featured) - full Ubuntu desktop
+ docker pull --platform=linux/amd64 trycua/cua-ubuntu:latest
+ ```
+
+ </Tab>
+ <Tab value="QEMU Docker">
+
+ Run full Linux (Ubuntu Desktop), Windows 11, or Android 11 VMs inside Docker containers using QEMU virtualization.
+
+ <Callout type="warn">
+ Linux and Windows images require a **golden image preparation step** on first use. Android images start directly without preparation.
+ </Callout>
+
+ <Tabs items={['Linux', 'Windows', 'Android']}>
+ <Tab value="Linux">
+
+ **1. Install Docker Desktop or Docker Engine**
+
+ **2. Pull the QEMU Linux image:**
+
+ ```bash
+ docker pull trycua/cua-qemu-linux:latest
+ ```
+
+ **3. Download Ubuntu 22.04 LTS Server ISO:**
+
+ - Download the [Ubuntu 22.04 Server ISO](https://releases.ubuntu.com/22.04/ubuntu-22.04.5-live-server-amd64.iso) (~2GB)
+
+ **4. Create golden image:**
+
+ ```bash
+ docker run -it --rm \
+ --device=/dev/kvm \
+ --cap-add NET_ADMIN \
+ --mount type=bind,source=/path/to/ubuntu-22.04.5-live-server-amd64.iso,target=/custom.iso \
+ -v ~/cua-storage/linux:/storage \
+ -p 8006:8006 \
+ -p 5000:5000 \
+ -e RAM_SIZE=8G \
+ -e CPU_CORES=4 \
+ -e DISK_SIZE=64G \
+ trycua/cua-qemu-linux:latest
+ ```
+
+ The container will install Ubuntu Desktop from the ISO and shut down when complete. Monitor progress at [http://localhost:8006](http://localhost:8006).
+
+ </Tab>
+ <Tab value="Windows">
+
+ **1. Install Docker Desktop or Docker Engine**
+
+ **2. Pull the QEMU Windows image:**
+
+ ```bash
+ docker pull trycua/cua-qemu-windows:latest
+ ```
+
+ **3. Download Windows 11 Enterprise Evaluation ISO:**
+
+ - Visit [Microsoft Evaluation Center](https://info.microsoft.com/ww-landing-windows-11-enterprise.html)
+ - Accept the Terms of Service
+ - Download **Windows 11 Enterprise Evaluation (90-day trial, English, United States)** ISO (~6GB)
+
+ **4. Create golden image:**
+
+ ```bash
+ docker run -it --rm \
+ --device=/dev/kvm \
+ --cap-add NET_ADMIN \
+ --mount type=bind,source=/path/to/windows-11-enterprise-eval.iso,target=/custom.iso \
+ -v ~/cua-storage/windows:/storage \
+ -p 8006:8006 \
+ -p 5000:5000 \
+ -e RAM_SIZE=8G \
+ -e CPU_CORES=4 \
+ -e DISK_SIZE=64G \
+ trycua/cua-qemu-windows:latest
+ ```
+
+ The container will install Windows 11 from the ISO and shut down when complete. Monitor progress at [http://localhost:8006](http://localhost:8006).
+
+ </Tab>
+ <Tab value="Android">
+
+ **1. Install Docker Desktop or Docker Engine**
+
+ **2. Pull the QEMU Android image:**
+
+ ```bash
+ docker pull trycua/cua-qemu-android:latest
+ ```
+
+ No golden image preparation needed - the Android emulator starts directly when you run it!
+
+ </Tab>
+ </Tabs>
+
+ </Tab>
+ <Tab value="macOS Sandbox">
+
+ macOS hosts only - requires Lume CLI.
+
+ 1. Install the Lume CLI:
+
+ ```bash
+ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+ ```
+
+ 2. Start a local Cua sandbox:
+
+ ```bash
+ lume run macos-sequoia-cua:latest
+ ```
+
+ </Tab>
+ <Tab value="Windows Sandbox">
+
+ Windows hosts only - requires Windows 10 Pro/Enterprise or Windows 11.
+
+ 1. Enable [Windows Sandbox](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-install)
+ 2. Install the `pywinsandbox` dependency:
+
+ ```bash
+ pip install -U git+git://github.com/karkason/pywinsandbox.git
+ ```
+
+ 3. Windows Sandbox will be automatically configured when you run the CLI
+
+ </Tab>
+</Tabs>
+
+## Next Step
+
+Once your sandbox is set up, proceed to [Using the Computer SDK](/docs/guide/get-started/using-computer-sdk) to connect and start interacting with it.
diff --git a/docs/content/docs/guide/get-started/using-agent-sdk.mdx b/docs/content/docs/guide/get-started/using-agent-sdk.mdx
new file mode 100644
index 0000000000..89d782bd38
--- /dev/null
+++ b/docs/content/docs/guide/get-started/using-agent-sdk.mdx
@@ -0,0 +1,275 @@
+---
+title: Using the Agent SDK
+description: Add AI automation with vision-language models
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Now that you've verified your sandbox works with the Computer SDK, use an Agent to automate complex tasks. The agent interacts with the computer environment using a vision-language model to understand the UI and execute actions.
+
+Cua Agent Framework provides:
+- **100+ VLM options** through Cua VLM Router and direct provider access
+- **Built-in optimizations** for computer-use tasks
+- **Structured agent loops** for consistent behavior
+
+## Installation
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+ **Using uv (recommended):**
+ ```bash
+ uv pip install "cua-agent[all]"
+ ```
+
+ **Or with pip:**
+ ```bash
+ pip install "cua-agent[all]"
+ ```
+ </Tab>
+ <Tab value="TypeScript">
+ ```bash
+ npm install @trycua/computer ai
+ ```
+ </Tab>
+</Tabs>
+
+## Choose Your Model Provider
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+<Tabs items={['Cua VLM Router', 'BYOK (Bring Your Own Key)']}>
+ <Tab value="Cua VLM Router">
+
+Use Cua's inference API to access multiple model providers with a single API key (same key used for sandbox access). Cua VLM Router provides intelligent routing and cost optimization.
+
+```python
+import os
+import asyncio
+from computer import Computer
+from agent import ComputerAgent
+
+os.environ["CUA_API_KEY"] = "sk_cua-api01_..."
+
+computer = Computer(
+ os_type="linux", # or "windows" or "macos"
+ provider_type="cloud",
+ name="your-sandbox-name" # from CLI or website
+)
+
+async def main():
+ await computer.run() # Connect to the sandbox
+
+ try:
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5", # Cua-routed model
+ tools=[computer],
+ max_trajectory_budget=5.0
+ )
+
+ messages = [{"role": "user", "content": "Take a screenshot and tell me what you see"}]
+
+ async for result in agent.run(messages):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+ finally:
+ await computer.disconnect()
+
+asyncio.run(main())
+```
+
+**Available Cua models:**
+- `cua/anthropic/claude-sonnet-4.5` - Claude Sonnet 4.5 (recommended)
+- `cua/anthropic/claude-opus-4.5` - Claude Opus 4.5 (enhanced agentic capabilities)
+- `cua/anthropic/claude-haiku-4.5` - Claude Haiku 4.5 (faster, cost-effective)
+- `cua/google/gemini-3-pro-preview` - Gemini 3 Pro Preview (most powerful multimodal)
+- `cua/google/gemini-3-flash-preview` - Gemini 3 Flash Preview (fastest and cheapest)
+- `cua/qwen/qwen3-vl-235b` - Qwen3 VL 235B (large-scale vision-language tasks)
+
+**Available composed models:**
+- `huggingface-local/HelloKKMe/GTA1-7B+anthropic/claude-sonnet-4-5-20250929` - GTA1 grounding + Claude Sonnet 4.5 planning
+- `huggingface-local/HelloKKMe/GTA1-7B+openai/gpt-5` - GTA1 grounding + GPT-5 planning
+- `huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B+openai/gpt-4o` - UI-TARS grounding + GPT-4o planning
+- `moondream3+openai/gpt-4o` - Moondream3 grounding + GPT-4o planning
+
+**Benefits:**
+
+- Single API key for multiple providers
+- Cost tracking and optimization
+- No need to manage multiple provider keys
+
+</Tab>
+<Tab value="BYOK (Bring Your Own Key)">
+
+Use your own API keys from model providers like Anthropic, OpenAI, or others.
+
+```python
+import os
+import asyncio
+from computer import Computer
+from agent import ComputerAgent
+
+# Set your provider API key
+os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..." # For Anthropic
+# OR
+os.environ["OPENAI_API_KEY"] = "sk-..." # For OpenAI
+
+computer = Computer(
+ os_type="linux", # or "windows" or "macos"
+ provider_type="cloud",
+ name="your-sandbox-name" # from CLI or website
+)
+
+async def main():
+ await computer.run() # Launch & connect to the sandbox
+
+ try:
+ agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929", # Direct provider model
+ tools=[computer],
+ max_trajectory_budget=5.0
+ )
+
+ messages = [{"role": "user", "content": "Take a screenshot and tell me what you see"}]
+
+ async for result in agent.run(messages):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+ finally:
+ await computer.disconnect()
+
+asyncio.run(main())
+```
+
+**Supported providers:**
+- `anthropic/claude-*` - Anthropic Claude models
+- `openai/gpt-*` - OpenAI GPT models
+- `openai/o1-*` - OpenAI o1 models
+- `huggingface-local/*` - Local HuggingFace models
+- And many more via LiteLLM
+
+See [Supported Models](/docs/reference/agent-sdk/supported-model-providers/) for the complete list.
+
+</Tab>
+</Tabs>
+
+</Tab>
+<Tab value="TypeScript">
+
+For TypeScript, you can build agent loops using the [Vercel AI SDK](https://ai-sdk.dev/) with the Cua Computer Framework TypeScript library.
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import { Computer, OSType } from "@trycua/computer";
+
+const client = new Anthropic();
+let computer: Computer;
+
+const computerTool = {
+ type: "tool" as const,
+ name: "computer",
+ description: "Control the computer with actions like screenshot, click, type, etc.",
+ inputSchema: {
+ type: "object" as const,
+ properties: {
+ action: {
+ type: "string" as const,
+ description: "Action to perform (screenshot, click, type, key_press, etc.)",
+ },
+ coordinate: {
+ type: "array" as const,
+ items: { type: "number" as const },
+ description: "x, y coordinates for click actions",
+ },
+ text: {
+ type: "string" as const,
+ description: "Text to type",
+ },
+ },
+ required: ["action"],
+ },
+};
+
+async function runAgentLoop(goal: string) {
+ // Initialize computer
+ computer = new Computer({
+ osType: OSType.LINUX,
+ provider_type: "cloud",
+ name: "your-sandbox-name",
+ apiKey: process.env.CUA_API_KEY!,
+ });
+
+ await computer.run();
+
+ const messages: any[] = [];
+ messages.push({ role: "user", content: goal });
+
+ // Agent loop
+ for (let i = 0; i < 10; i++) {
+ const response = await client.messages.create({
+ model: "claude-opus-4-1-20250805",
+ max_tokens: 4096,
+ tools: [computerTool],
+ messages: messages,
+ });
+
+ if (response.stop_reason === "end_turn") {
+ console.log("Task completed!");
+ break;
+ }
+
+ messages.push({ role: "assistant", content: response.content });
+
+ // Process tool calls
+ const toolResults = [];
+ for (const block of response.content) {
+ if (block.type === "tool_use") {
+ let result: any;
+ switch (block.input.action) {
+ case "screenshot":
+ result = await computer.interface.screenshot();
+ break;
+ case "click":
+ result = await computer.interface.click(
+ block.input.coordinate[0],
+ block.input.coordinate[1]
+ );
+ break;
+ case "type":
+ result = await computer.interface.type(block.input.text);
+ break;
+ }
+ toolResults.push({
+ type: "tool_result",
+ tool_use_id: block.id,
+ content: JSON.stringify(result),
+ });
+ }
+ }
+
+ if (toolResults.length > 0) {
+ messages.push({ role: "user", content: toolResults });
+ }
+ }
+
+ await computer.disconnect();
+}
+
+runAgentLoop("Take a screenshot and tell me what you see");
+```
+
+For more details, see the [Vercel AI SDK Computer Use Cookbook](https://ai-sdk.dev/cookbook/guides/computer-use).
+
+</Tab>
+</Tabs>
+
+## Next Steps
+
+- Explore [Agent Loops](/docs/guide/agents/agent-loops) for advanced agent configuration
+- Check out [Custom Tools](/docs/guide/agents/custom-tools) to extend your agents
+- Review [Supported Model Providers](/docs/reference/agent-sdk/supported-model-providers/) for more LLM options
+- Try the [Form Filling](/docs/examples/automation/form-filling) example use case
+- Join our [Discord community](https://discord.com/invite/cua-ai) for help and discussion
diff --git a/docs/content/docs/guide/get-started/using-cloud-cli.mdx b/docs/content/docs/guide/get-started/using-cloud-cli.mdx
new file mode 100644
index 0000000000..4512044135
--- /dev/null
+++ b/docs/content/docs/guide/get-started/using-cloud-cli.mdx
@@ -0,0 +1,199 @@
+---
+title: Using the Cloud CLI
+description: Manage cloud sandboxes from your terminal
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+The Cua Cloud CLI lets you create, manage, and connect to cloud sandboxes directly from your terminal. This is the fastest way to get a sandbox running without writing any code.
+
+## Installation
+
+Install the CLI globally using npm or bun:
+
+<Tabs items={['npm', 'bun']}>
+<Tab value="npm">
+```bash
+npm install -g @trycua/cli
+```
+</Tab>
+<Tab value="bun">
+```bash
+bun install -g @trycua/cli
+```
+</Tab>
+</Tabs>
+
+Verify the installation:
+
+```bash
+cua --version
+```
+
+## Authentication
+
+Before managing sandboxes, authenticate with your Cua account:
+
+```bash
+# Browser-based login (opens OAuth flow)
+cua auth login
+
+# Or use an API key directly
+cua auth login --api-key sk_cua-api01_...
+```
+
+To write your API key to a `.env` file for use in projects:
+
+```bash
+cua auth env
+```
+
+This creates or updates `.env` with your `CUA_API_KEY`.
+
+## Creating a Sandbox
+
+Create a new cloud sandbox with the `create` command:
+
+```bash
+cua sandbox create --os linux --size small --region north-america
+```
+
+**Required options:**
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `--os` | `linux`, `windows`, `macos` | Operating system |
+| `--size` | `small`, `medium`, `large` | Compute tier |
+| `--region` | `north-america`, `europe`, `asia-pacific`, `south-america` | Geographic region |
+
+**Compute tiers:**
+
+| Size | vCPU | RAM | Best for |
+|------|------|-----|----------|
+| `small` | 1 | 4 GB | Simple tasks, testing |
+| `medium` | 2 | 8 GB | General automation |
+| `large` | 8 | 32 GB | Complex workflows, multiple apps |
+
+The command returns once your sandbox is ready. You'll see the sandbox name, which you'll use for all other commands.
+
+## Listing Sandboxes
+
+View all your sandboxes:
+
+```bash
+cua sandbox list
+```
+
+Output shows NAME, STATUS, and HOST for each sandbox. Status values:
+
+- `running` - Ready to use
+- `stopped` - Not running (no charges)
+- `pending` - Starting up
+- `suspended` - Memory state preserved
+- `terminated` - Deleted
+
+Shorthand aliases: `cua ls`, `cua ps`, `cua sb list`
+
+## Managing Sandbox Lifecycle
+
+Start, stop, and restart sandboxes:
+
+```bash
+# Start a stopped sandbox (hot-start in under 1 second)
+cua sandbox start my-sandbox
+
+# Stop a running sandbox (preserves data)
+cua sandbox stop my-sandbox
+
+# Restart a sandbox
+cua sandbox restart my-sandbox
+
+# Suspend (preserves memory state)
+cua sandbox suspend my-sandbox
+
+# Permanently delete
+cua sandbox delete my-sandbox
+```
+
+Stopping a sandbox preserves all files, installed software, and browser profiles. You only pay for compute time while the sandbox is running.
+
+## Connecting to a Sandbox
+
+Open the sandbox desktop in your browser:
+
+```bash
+cua sandbox vnc my-sandbox
+```
+
+This opens a NoVNC session with the password pre-filled. You can interact with the desktop directly in your browser.
+
+Shorthand: `cua open my-sandbox`
+
+## Getting Sandbox Details
+
+View detailed information about a sandbox:
+
+```bash
+cua sandbox get my-sandbox
+```
+
+Add flags for more details:
+
+```bash
+# Include password in output
+cua sandbox get my-sandbox --show-passwords
+
+# Include VNC URL
+cua sandbox get my-sandbox --show-vnc-url
+
+# JSON output for scripting
+cua sandbox get my-sandbox --json
+```
+
+## Command Reference
+
+The CLI supports both grouped and flat command styles:
+
+| Grouped Style | Flat Style | Description |
+|---------------|------------|-------------|
+| `cua auth login` | `cua login` | Authenticate |
+| `cua auth logout` | `cua logout` | Clear credentials |
+| `cua auth env` | `cua env` | Write API key to .env |
+| `cua sandbox list` | `cua list` | List sandboxes |
+| `cua sandbox create` | `cua create` | Create sandbox |
+| `cua sandbox get <name>` | `cua get <name>` | Get sandbox details |
+| `cua sandbox start <name>` | `cua start <name>` | Start sandbox |
+| `cua sandbox stop <name>` | `cua stop <name>` | Stop sandbox |
+| `cua sandbox restart <name>` | `cua restart <name>` | Restart sandbox |
+| `cua sandbox delete <name>` | `cua delete <name>` | Delete sandbox |
+| `cua sandbox vnc <name>` | `cua vnc <name>` | Open VNC in browser |
+
+## Example Workflow
+
+Here's a typical workflow for setting up and using a sandbox:
+
+```bash
+# 1. Login
+cua auth login
+
+# 2. Create a Linux sandbox
+cua sandbox create --os linux --size small --region north-america
+# Output: Created sandbox "curious-fox-123"
+
+# 3. Open the desktop in your browser
+cua open curious-fox-123
+
+# 4. Export your API key for SDK usage
+cua auth env
+
+# 5. Use the sandbox with Python SDK
+python my_agent.py
+
+# 6. Stop when done (preserves data, stops charges)
+cua stop curious-fox-123
+```
+
+## Next Step
+
+Once your sandbox is running, proceed to [Using the Computer SDK](/docs/guide/get-started/using-computer-sdk) to connect programmatically, or [Using the Agent SDK](/docs/guide/get-started/using-agent-sdk) to add AI automation.
diff --git a/docs/content/docs/guide/get-started/using-computer-sdk.mdx b/docs/content/docs/guide/get-started/using-computer-sdk.mdx
new file mode 100644
index 0000000000..0fe8c6d3c3
--- /dev/null
+++ b/docs/content/docs/guide/get-started/using-computer-sdk.mdx
@@ -0,0 +1,458 @@
+---
+title: Using the Computer SDK
+description: Connect to your sandbox and perform basic interactions
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn" title="Python Version Compatibility">
+ Cua packages require **Python 3.12 or 3.13**. Python 3.14 is not currently supported due to dependency compatibility issues (pydantic-core/PyO3 compatibility). If you encounter build errors on Python 3.14, please use Python 3.13 or earlier.
+</Callout>
+
+The Computer SDK lets you connect to your sandbox and perform basic interactions like taking screenshots, clicking, and typing. This is an important verification step before adding AI agents.
+
+## Installation
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+ **Using uv (recommended):**
+ ```bash
+ uv pip install cua-computer
+ ```
+
+ **Or with pip:**
+ ```bash
+ pip install cua-computer
+ ```
+ </Tab>
+ <Tab value="TypeScript">
+ ```bash
+ npm install @trycua/computer
+ ```
+ </Tab>
+</Tabs>
+
+## Connect to Your Sandbox
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ <Tabs items={['Cloud Sandbox', 'Linux on Docker', 'QEMU Docker', 'macOS Sandbox', 'Windows Sandbox', 'Your host desktop']}>
+ <Tab value="Cloud Sandbox">
+ Set your Cua API key (same key used for model inference) and connect to your sandbox:
+ ```python
+ import os
+ from computer import Computer
+ import asyncio
+
+ os.environ["CUA_API_KEY"] = "sk_cua-api01_..."
+
+ computer = Computer(
+ os_type="linux", # or "windows" or "macos"
+ provider_type="cloud",
+ name="your-sandbox-name" # from CLI or website
+ )
+
+ async def main():
+ await computer.run() # Connect to the sandbox
+
+ try:
+ # Take a screenshot of the computer's current display
+ screenshot = await computer.interface.screenshot()
+ # Simulate a left-click at coordinates (100, 100)
+ await computer.interface.left_click(100, 100)
+ # Type "Hello!" into the active application
+ await computer.interface.type_text("Hello!")
+ finally:
+ await computer.disconnect()
+
+ asyncio.run(main())
+ ```
+ </Tab>
+ <Tab value="Linux on Docker">
+ ```python
+ from computer import Computer
+ import asyncio
+
+ computer = Computer(
+ os_type="linux",
+ provider_type="docker",
+ image="trycua/cua-xfce:latest" # or "trycua/cua-ubuntu:latest"
+ )
+
+ async def main():
+ await computer.run() # Launch & connect to the sandbox
+
+ try:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello!")
+ finally:
+ await computer.disconnect()
+
+ asyncio.run(main())
+ ```
+ </Tab>
+ <Tab value="QEMU Docker">
+ <Tabs items={['Linux', 'Windows', 'Android']}>
+ <Tab value="Linux">
+ ```python
+ from computer import Computer
+ import asyncio
+
+ computer = Computer(
+ os_type="linux",
+ provider_type="docker",
+ image="trycua/cua-qemu-linux:latest",
+ storage="~/cua-storage/linux",
+ run_opts={
+ "devices": ["/dev/kvm"], # Optional but recommended
+ },
+ )
+
+ async def main():
+ await computer.run() # Boot from golden image
+
+ try:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello!")
+ finally:
+ await computer.disconnect()
+
+ asyncio.run(main())
+ ```
+ </Tab>
+ <Tab value="Windows">
+ ```python
+ from computer import Computer
+ import asyncio
+
+ computer = Computer(
+ os_type="windows",
+ provider_type="docker",
+ image="trycua/cua-qemu-windows:latest",
+ storage="~/cua-storage/windows",
+ run_opts={
+ "devices": ["/dev/kvm"], # Optional but recommended
+ },
+ )
+
+ async def main():
+ await computer.run() # Boot from golden image
+
+ try:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello!")
+ finally:
+ await computer.disconnect()
+
+ asyncio.run(main())
+ ```
+ </Tab>
+ <Tab value="Android">
+ ```python
+ from computer import Computer
+ import asyncio
+
+ computer = Computer(
+ os_type="android",
+ provider_type="docker",
+ image="trycua/cua-qemu-android:latest",
+ timeout=150, # Emulator needs more time to boot
+ run_opts={
+ "devices": ["/dev/kvm"], # Required for Android emulator
+ "env": {
+ "EMULATOR_DEVICE": "Samsung Galaxy S10",
+ },
+ },
+ )
+
+ async def main():
+ await computer.run() # Launch & connect to Android emulator
+
+ try:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello!")
+ finally:
+ await computer.disconnect()
+
+ asyncio.run(main())
+ ```
+ </Tab>
+ </Tabs>
+ </Tab>
+ <Tab value="macOS Sandbox">
+ ```python
+ from computer import Computer
+ import asyncio
+
+ computer = Computer(
+ os_type="macos",
+ provider_type="lume",
+ name="macos-sequoia-cua:latest"
+ )
+
+ async def main():
+ await computer.run() # Launch & connect to the sandbox
+
+ try:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello!")
+ finally:
+ await computer.disconnect()
+
+ asyncio.run(main())
+ ```
+ </Tab>
+ <Tab value="Windows Sandbox">
+ ```python
+ from computer import Computer
+ import asyncio
+
+ computer = Computer(
+ os_type="windows",
+ provider_type="windows_sandbox"
+ )
+
+ async def main():
+ await computer.run() # Launch & connect to the sandbox
+
+ try:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello!")
+ finally:
+ await computer.disconnect()
+
+ asyncio.run(main())
+ ```
+ </Tab>
+ <Tab value="Your host desktop">
+ Install and run `cua-computer-server`:
+ ```bash
+ pip install cua-computer-server
+ python -m computer_server
+ ```
+
+ Then, use the `Computer` object to connect:
+ ```python
+ from computer import Computer
+ import asyncio
+
+ computer = Computer(use_host_computer_server=True)
+
+ async def main():
+ await computer.run() # Connect to the host desktop
+
+ try:
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type_text("Hello!")
+ finally:
+ await computer.disconnect()
+
+ asyncio.run(main())
+ ```
+ </Tab>
+ </Tabs>
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ <Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS Sandbox', 'Windows Sandbox', 'Your host desktop']}>
+ <Tab value="Cloud Sandbox">
+ Set your Cua API key (same key used for model inference):
+ ```bash
+ export CUA_API_KEY="sk_cua-api01_..."
+ ```
+
+ Then connect to your sandbox:
+ ```typescript
+ import { Computer, OSType } from '@trycua/computer';
+
+ const computer = new Computer({
+ osType: OSType.LINUX, // or OSType.WINDOWS or OSType.MACOS
+ name: "your-sandbox-name" // from CLI or website
+ });
+ await computer.run(); // Connect to the sandbox
+ ```
+ </Tab>
+ <Tab value="Linux on Docker">
+ ```typescript
+ import { Computer, OSType, ProviderType } from '@trycua/computer';
+
+ const computer = new Computer({
+ osType: OSType.LINUX,
+ providerType: ProviderType.DOCKER,
+ image: "trycua/cua-xfce:latest" // or "trycua/cua-ubuntu:latest"
+ });
+ await computer.run(); // Launch & connect to the sandbox
+ ```
+ </Tab>
+ <Tab value="macOS Sandbox">
+ ```typescript
+ import { Computer, OSType, ProviderType } from '@trycua/computer';
+
+ const computer = new Computer({
+ osType: OSType.MACOS,
+ providerType: ProviderType.LUME,
+ name: "macos-sequoia-cua:latest"
+ });
+ await computer.run(); // Launch & connect to the sandbox
+ ```
+ </Tab>
+ <Tab value="Windows Sandbox">
+ ```typescript
+ import { Computer, OSType, ProviderType } from '@trycua/computer';
+
+ const computer = new Computer({
+ osType: OSType.WINDOWS,
+ providerType: ProviderType.WINDOWS_SANDBOX
+ });
+ await computer.run(); // Launch & connect to the sandbox
+ ```
+ </Tab>
+ <Tab value="Your host desktop">
+ First, install and run `cua-computer-server`:
+ ```bash
+ pip install cua-computer-server
+ python -m computer_server
+ ```
+
+ Then, use the `Computer` object to connect:
+ ```typescript
+ import { Computer } from '@trycua/computer';
+
+ const computer = new Computer({ useHostComputerServer: true });
+ await computer.run(); // Connect to the host desktop
+ ```
+ </Tab>
+ </Tabs>
+
+ Once connected, you can perform interactions:
+ ```typescript
+ try {
+ // Take a screenshot of the computer's current display
+ const screenshot = await computer.interface.screenshot();
+ // Simulate a left-click at coordinates (100, 100)
+ await computer.interface.leftClick(100, 100);
+ // Type "Hello!" into the active application
+ await computer.interface.typeText("Hello!");
+ } finally {
+ await computer.disconnect();
+ }
+ ```
+
+ </Tab>
+</Tabs>
+
+## Common Operations
+
+| Operation | Python | TypeScript |
+|-----------|--------|------------|
+| Screenshot | `await computer.interface.screenshot()` | `await computer.interface.screenshot()` |
+| Left click | `await computer.interface.left_click(x, y)` | `await computer.interface.leftClick(x, y)` |
+| Right click | `await computer.interface.right_click(x, y)` | `await computer.interface.rightClick(x, y)` |
+| Double click | `await computer.interface.double_click(x, y)` | `await computer.interface.doubleClick(x, y)` |
+| Type text | `await computer.interface.type_text("text")` | `await computer.interface.typeText("text")` |
+| Press key | `await computer.interface.key("Enter")` | `await computer.interface.key("Enter")` |
+| Scroll | `await computer.interface.scroll(x, y, clicks)` | `await computer.interface.scroll(x, y, clicks)` |
+
+## Lifecycle Methods
+
+- `computer.run()` - Connect to an already-running sandbox
+- `computer.start()` - Start and connect to the sandbox (if not running)
+- `computer.disconnect()` - Disconnect but keep sandbox running
+- `computer.stop()` - Fully stop the sandbox and disconnect
+
+## Managing Cloud Sandboxes
+
+For cloud sandboxes, you can programmatically manage VM lifecycle using the `CloudProvider`:
+
+<Tabs items={['Python', 'TypeScript']}>
+<Tab value="Python">
+
+```python
+import os
+import asyncio
+from computer.providers.cloud.provider import CloudProvider
+
+os.environ["CUA_API_KEY"] = "sk_cua-api01_..."
+
+async def main():
+ provider = CloudProvider()
+
+ # List all your sandboxes
+ sandboxes = await provider.list_vms()
+ for vm in sandboxes:
+ print(f"{vm['name']}: {vm['status']}")
+
+ # Start a sandbox
+ await provider.run_vm("my-sandbox")
+
+ # Check sandbox status
+ info = await provider.get_vm("my-sandbox")
+ print(f"Status: {info['status']}")
+
+ # Stop when done
+ await provider.stop_vm("my-sandbox")
+
+asyncio.run(main())
+```
+
+</Tab>
+<Tab value="TypeScript">
+
+```typescript
+import { CloudProvider } from "@trycua/computer";
+
+const provider = new CloudProvider({
+ apiKey: process.env.CUA_API_KEY!,
+});
+
+async function main() {
+ // List all your sandboxes
+ const sandboxes = await provider.listVMs();
+ for (const vm of sandboxes) {
+ console.log(`${vm.name}: ${vm.status}`);
+ }
+
+ // Start a sandbox
+ await provider.runVM("my-sandbox");
+
+ // Check sandbox status
+ const info = await provider.getVM("my-sandbox");
+ console.log(`Status: ${info.status}`);
+
+ // Stop when done
+ await provider.stopVM("my-sandbox");
+}
+
+main();
+```
+
+</Tab>
+</Tabs>
+
+Available operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `list_vms()` | List all sandboxes in your account |
+| `get_vm(name)` | Get status and details for a specific sandbox |
+| `run_vm(name)` | Start a sandbox (hot-start in under 1 second) |
+| `stop_vm(name)` | Stop a running sandbox |
+| `restart_vm(name)` | Restart a sandbox |
+
+This is useful for orchestrating multiple sandboxes, building CI/CD pipelines, or programmatically managing sandbox lifecycle.
+
+## Next Step
+
+Once you've verified your sandbox connection works, proceed to [Using the Agent SDK](/docs/guide/get-started/using-agent-sdk) to add AI automation.
+
+For more details on available commands, see the [Computer SDK Commands](/docs/reference/computer-sdk/commands) reference.
diff --git a/docs/content/docs/guide/get-started/what-is-computer-use-agent.mdx b/docs/content/docs/guide/get-started/what-is-computer-use-agent.mdx
new file mode 100644
index 0000000000..e4f8e3eaef
--- /dev/null
+++ b/docs/content/docs/guide/get-started/what-is-computer-use-agent.mdx
@@ -0,0 +1,114 @@
+---
+title: What is a Computer-Use Agent?
+description: Understanding AI agents that can see and interact with computer interfaces
+---
+
+A **computer-use agent** is an AI system that can perceive, understand, and interact with graphical user interfaces (GUIs) just like a human user would. Instead of using APIs or scripted automation, these agents "see" the screen and perform actions through simulated mouse and keyboard inputs.
+
+## How Computer-Use Agents Work
+
+Computer-use agents operate through a continuous loop:
+
+```
+┌─────────────────────────────────────────┐
+│ 1. OBSERVE │
+│ Take a screenshot of the screen │
+└──────────────────┬──────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────┐
+│ 2. UNDERSTAND │
+│ Vision-language model analyzes │
+│ the screenshot and current goal │
+└──────────────────┬──────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────┐
+│ 3. DECIDE │
+│ Determine the next action: │
+│ click, type, scroll, etc. │
+└──────────────────┬──────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────┐
+│ 4. ACT │
+│ Execute the action on the computer │
+└──────────────────┬──────────────────────┘
+ │
+ ▼
+ Loop back to 1
+```
+
+This cycle repeats until the agent completes its goal or determines it cannot proceed.
+
+## Key Components
+
+### Vision-Language Models (VLMs)
+
+At the core of computer-use agents are **vision-language models**—AI models that can process both images and text. These models:
+
+- Identify UI elements (buttons, text fields, menus)
+- Read text on screen
+- Understand spatial relationships
+- Reason about what actions to take
+
+Popular VLMs for computer use include Claude (Anthropic), GPT-4V (OpenAI), and Gemini (Google).
+
+### Grounding Models
+
+**Grounding models** specialize in precisely locating UI elements on screen. Given a description like "the Submit button," they return exact pixel coordinates. Examples include:
+
+- UI-TARS
+- GTA-1
+- Moondream
+
+### Planning Models
+
+**Planning models** handle high-level reasoning—deciding what to do next given the current state and goal. They're typically large language models that excel at:
+
+- Breaking down complex tasks into steps
+- Handling errors and unexpected situations
+- Maintaining context across multiple actions
+
+## Composed vs. End-to-End Agents
+
+### End-to-End Agents
+
+A single model handles both understanding and action selection:
+
+```
+Screenshot → [Single VLM] → Action
+```
+
+**Pros:** Simpler architecture, lower latency
+**Cons:** May sacrifice accuracy in either perception or planning
+
+### Composed Agents
+
+Separate models for grounding and planning:
+
+```
+Screenshot → [Grounding Model] → UI Elements → [Planning Model] → Action
+```
+
+**Pros:** Best-in-class performance for each capability
+**Cons:** Higher complexity, potentially higher cost
+
+Cua supports both approaches, letting you choose based on your requirements.
+
+## Challenges in Computer Use
+
+Building effective computer-use agents involves solving several challenges:
+
+- **Coordinate accuracy** - Clicking the right pixel matters
+- **Timing** - Waiting for pages to load, animations to complete
+- **Error recovery** - Handling popups, errors, and unexpected states
+- **Context management** - Remembering what's been done across many steps
+- **Safety** - Preventing unintended actions on real systems
+
+Cua addresses these challenges with sandboxed environments, optimized agent loops, and built-in safety mechanisms.
+
+## Next Steps
+
+- Learn about [Desktop Sandboxes](/docs/guide/get-started/what-is-desktop-sandbox) where agents run safely
+- [Set Up a Sandbox](/docs/guide/get-started/set-up-sandbox) to build your first agent
diff --git a/docs/content/docs/guide/get-started/what-is-cua.mdx b/docs/content/docs/guide/get-started/what-is-cua.mdx
new file mode 100644
index 0000000000..9104f08ac8
--- /dev/null
+++ b/docs/content/docs/guide/get-started/what-is-cua.mdx
@@ -0,0 +1,64 @@
+---
+title: What is Cua?
+description: Learn about Cua, the open-source platform for building computer-use agents
+---
+
+Cua is an **open-source platform** for building, deploying, and managing computer-use agents. It provides everything you need to create AI agents that can interact with desktop environments just like a human would—clicking, typing, navigating, and completing tasks autonomously.
+
+<div className="not-prose relative rounded-xl overflow-hidden my-8 w-full">
+ <img src="/docs/img/hero.png" alt="Cua" className="w-full h-auto rounded-xl" />
+</div>
+
+## The Cua Stack
+
+Cua consists of three main components:
+
+### 1. Desktop Sandboxes
+
+Isolated virtual environments where your agents can safely execute tasks. Cua supports:
+
+- **Cloud Sandboxes** - Managed Linux, Windows, and macOS environments hosted by Cua
+- **Local Sandboxes** - Docker containers, QEMU VMs, macOS VMs via Lume, or Windows Sandbox on your own machine
+
+### 2. Computer Framework
+
+A unified SDK for controlling desktop environments programmatically:
+
+- Take screenshots and observe the screen
+- Simulate mouse clicks, movements, and scrolling
+- Type text and press keyboard shortcuts
+- Works identically across all sandbox types
+
+### 3. Agent Framework
+
+Tools for building AI agents that understand and interact with GUIs:
+
+- **100+ vision-language model options** through Cua VLM Router or direct provider access
+- **Pre-built agent loops** optimized for computer-use tasks
+- **Composable architecture** for combining grounding and planning models
+- **Built-in telemetry** for monitoring agent performance
+
+## Why Cua?
+
+Traditional automation tools require you to write explicit scripts for every action. Cua agents can:
+
+- **Understand visual context** - See what's on screen and make decisions
+- **Adapt to changes** - Handle UI variations without breaking
+- **Complete complex tasks** - Chain multiple actions to achieve goals
+- **Work across applications** - Navigate between different programs seamlessly
+
+## Use Cases
+
+Cua is ideal for:
+
+- **Workflow automation** - Automate repetitive tasks across any application
+- **Testing** - Run end-to-end tests that interact with real UIs
+- **Data extraction** - Scrape information from applications that don't have APIs
+- **RPA (Robotic Process Automation)** - Enterprise automation with AI understanding
+- **Benchmarks** - Evaluate computer-use agents on standardized tasks (OSWorld, ScreenSpot, etc.)
+- **RL/Gym Environments** - Train reinforcement learning agents with desktop environments as Gym-compatible envs
+- **Research** - Build and evaluate computer-use AI agents
+
+## Getting Started
+
+Ready to build your first agent? Continue to [Set Up a Sandbox](/docs/guide/get-started/set-up-sandbox) to set up your environment and run your first automation.
diff --git a/docs/content/docs/guide/get-started/what-is-desktop-sandbox.mdx b/docs/content/docs/guide/get-started/what-is-desktop-sandbox.mdx
new file mode 100644
index 0000000000..b2279268b7
--- /dev/null
+++ b/docs/content/docs/guide/get-started/what-is-desktop-sandbox.mdx
@@ -0,0 +1,142 @@
+---
+title: What is a Desktop Sandbox?
+description: Understanding isolated environments for safe computer-use agent execution
+---
+
+A **desktop sandbox** is an isolated virtual environment that provides a complete desktop operating system where computer-use agents can safely execute tasks. Think of it as a disposable computer that your agent can control without risk to your real system.
+
+## Why Use Sandboxes?
+
+Running AI agents directly on your computer poses risks:
+
+- **Unintended actions** - Agents might click the wrong button or delete files
+- **Security concerns** - Malicious content could affect your system
+- **State pollution** - Each run might leave behind artifacts that affect future runs
+- **Reproducibility** - Hard to ensure consistent starting conditions
+
+Sandboxes solve these problems by providing:
+
+- **Isolation** - Actions in the sandbox don't affect your host system
+- **Reset capability** - Start fresh for each task
+- **Safety** - Experiment freely without consequences
+- **Consistency** - Identical environment every time
+
+## Sandbox Options in Cua
+
+Cua supports multiple sandbox types to fit different needs:
+
+### Cloud Sandboxes
+
+Managed virtual machines hosted by Cua's infrastructure.
+
+| Feature | Details |
+|---------|---------|
+| **OS Options** | Linux (Ubuntu), Windows, macOS |
+| **Setup** | Instant—create via CLI or dashboard |
+| **Best For** | Production workloads, teams, CI/CD |
+| **Access** | API key required |
+
+```bash
+# Create a cloud sandbox
+cua sb create --os linux --size small --region north-america
+```
+
+### Docker Sandboxes
+
+Linux desktops running in Docker containers on your machine.
+
+| Feature | Details |
+|---------|---------|
+| **OS Options** | Linux (XFCE, Ubuntu Desktop) |
+| **Setup** | Docker Desktop required |
+| **Best For** | Local development, testing |
+| **Access** | No API key needed |
+
+```bash
+# Pull and run a Docker sandbox
+docker pull trycua/cua-xfce:latest
+```
+
+### QEMU Docker Sandboxes
+
+Full virtual machines (Linux, Windows, Android) running inside Docker via QEMU emulation.
+
+| Feature | Details |
+|---------|---------|
+| **OS Options** | Linux, Windows 11, Android |
+| **Setup** | Requires golden image preparation |
+| **Best For** | Testing on specific OS versions |
+| **Access** | No API key needed |
+
+### macOS Sandboxes (Lume)
+
+Native macOS virtual machines using Apple's Virtualization framework.
+
+| Feature | Details |
+|---------|---------|
+| **OS Options** | macOS (various versions) |
+| **Setup** | macOS host required, install Lume CLI |
+| **Best For** | macOS-specific automation |
+| **Access** | No API key needed |
+
+```bash
+# Start a macOS sandbox
+lume run macos-sequoia-cua:latest
+```
+
+### Windows Sandbox
+
+Native Windows sandbox using Windows Sandbox feature.
+
+| Feature | Details |
+|---------|---------|
+| **OS Options** | Windows |
+| **Setup** | Windows 10 Pro/Enterprise or Windows 11 |
+| **Best For** | Windows-specific automation |
+| **Access** | No API key needed |
+
+## How Sandboxes Connect to Agents
+
+Your agent interacts with sandboxes through the Computer Framework:
+
+```
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+│ │ │ │ │ │
+│ Your Agent │────▶│ Computer │────▶│ Sandbox │
+│ (AI Logic) │ │ Framework │ │ (Desktop) │
+│ │◀────│ │◀────│ │
+└─────────────────┘ └─────────────────┘ └─────────────────┘
+ │
+ │ Unified API
+ │
+ ┌─────────┴─────────┐
+ │ │
+ Screenshots Actions
+ (what agent sees) (click, type, etc.)
+```
+
+The Computer Framework provides the same API regardless of which sandbox type you're using. This means you can:
+
+- Develop locally with Docker
+- Test on specific platforms with QEMU
+- Deploy to production with Cloud Sandboxes
+
+...all without changing your agent code.
+
+## Choosing the Right Sandbox
+
+| Use Case | Recommended Sandbox |
+|----------|-------------------|
+| Getting started / learning | Docker (Linux) |
+| Production deployment | Cloud Sandbox |
+| macOS automation | Lume (macOS) |
+| Windows automation | Cloud (Windows) or Windows Sandbox |
+| Android testing | QEMU Docker (Android) |
+| CI/CD pipelines | Cloud Sandbox |
+| Air-gapped environments | Docker or QEMU |
+
+## Next Steps
+
+- [Set Up a Sandbox](/docs/guide/get-started/set-up-sandbox) to create your first environment
+- Learn about [Computer Framework](/docs/guide/computers) for controlling sandboxes
+- Explore [Cloud VM Management](/docs/reference/computer-sdk/cloud-vm-management) for production deployments
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/guide/index.mdx
similarity index 100%
rename from docs/content/docs/index.mdx
rename to docs/content/docs/guide/index.mdx
diff --git a/docs/content/docs/agent-sdk/benchmarks/index.mdx b/docs/content/docs/guide/integrations/benchmarks/index.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/benchmarks/index.mdx
rename to docs/content/docs/guide/integrations/benchmarks/index.mdx
diff --git a/docs/content/docs/agent-sdk/benchmarks/interactive.mdx b/docs/content/docs/guide/integrations/benchmarks/interactive.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/benchmarks/interactive.mdx
rename to docs/content/docs/guide/integrations/benchmarks/interactive.mdx
diff --git a/docs/content/docs/agent-sdk/benchmarks/introduction.mdx b/docs/content/docs/guide/integrations/benchmarks/introduction.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/benchmarks/introduction.mdx
rename to docs/content/docs/guide/integrations/benchmarks/introduction.mdx
diff --git a/docs/content/docs/agent-sdk/benchmarks/meta.json b/docs/content/docs/guide/integrations/benchmarks/meta.json
similarity index 100%
rename from docs/content/docs/agent-sdk/benchmarks/meta.json
rename to docs/content/docs/guide/integrations/benchmarks/meta.json
diff --git a/docs/content/docs/agent-sdk/benchmarks/osworld-verified.mdx b/docs/content/docs/guide/integrations/benchmarks/osworld-verified.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/benchmarks/osworld-verified.mdx
rename to docs/content/docs/guide/integrations/benchmarks/osworld-verified.mdx
diff --git a/docs/content/docs/agent-sdk/benchmarks/screenspot-pro.mdx b/docs/content/docs/guide/integrations/benchmarks/screenspot-pro.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/benchmarks/screenspot-pro.mdx
rename to docs/content/docs/guide/integrations/benchmarks/screenspot-pro.mdx
diff --git a/docs/content/docs/agent-sdk/benchmarks/screenspot-v2.mdx b/docs/content/docs/guide/integrations/benchmarks/screenspot-v2.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/benchmarks/screenspot-v2.mdx
rename to docs/content/docs/guide/integrations/benchmarks/screenspot-v2.mdx
diff --git a/docs/content/docs/agent-sdk/integrations/hud.mdx b/docs/content/docs/guide/integrations/hud.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/integrations/hud.mdx
rename to docs/content/docs/guide/integrations/hud.mdx
diff --git a/docs/content/docs/agent-sdk/mcp-server/client-integrations.mdx b/docs/content/docs/guide/integrations/mcp-server/client-integrations.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/mcp-server/client-integrations.mdx
rename to docs/content/docs/guide/integrations/mcp-server/client-integrations.mdx
diff --git a/docs/content/docs/agent-sdk/mcp-server/configuration.mdx b/docs/content/docs/guide/integrations/mcp-server/configuration.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/mcp-server/configuration.mdx
rename to docs/content/docs/guide/integrations/mcp-server/configuration.mdx
diff --git a/docs/content/docs/agent-sdk/mcp-server/index.mdx b/docs/content/docs/guide/integrations/mcp-server/index.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/mcp-server/index.mdx
rename to docs/content/docs/guide/integrations/mcp-server/index.mdx
diff --git a/docs/content/docs/agent-sdk/mcp-server/installation.mdx b/docs/content/docs/guide/integrations/mcp-server/installation.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/mcp-server/installation.mdx
rename to docs/content/docs/guide/integrations/mcp-server/installation.mdx
diff --git a/docs/content/docs/agent-sdk/mcp-server/llm-integrations.mdx b/docs/content/docs/guide/integrations/mcp-server/llm-integrations.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/mcp-server/llm-integrations.mdx
rename to docs/content/docs/guide/integrations/mcp-server/llm-integrations.mdx
diff --git a/docs/content/docs/agent-sdk/mcp-server/meta.json b/docs/content/docs/guide/integrations/mcp-server/meta.json
similarity index 100%
rename from docs/content/docs/agent-sdk/mcp-server/meta.json
rename to docs/content/docs/guide/integrations/mcp-server/meta.json
diff --git a/docs/content/docs/agent-sdk/mcp-server/tools.mdx b/docs/content/docs/guide/integrations/mcp-server/tools.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/mcp-server/tools.mdx
rename to docs/content/docs/guide/integrations/mcp-server/tools.mdx
diff --git a/docs/content/docs/agent-sdk/mcp-server/usage.mdx b/docs/content/docs/guide/integrations/mcp-server/usage.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/mcp-server/usage.mdx
rename to docs/content/docs/guide/integrations/mcp-server/usage.mdx
diff --git a/docs/content/docs/guide/integrations/meta.json b/docs/content/docs/guide/integrations/meta.json
new file mode 100644
index 0000000000..080015651b
--- /dev/null
+++ b/docs/content/docs/guide/integrations/meta.json
@@ -0,0 +1,11 @@
+{
+ "title": "Integrations",
+ "description": "Third-party tools and integrations",
+ "icon": "Plug",
+ "pages": [
+ "mcp-server",
+ "observability",
+ "hud",
+ "benchmarks"
+ ]
+}
diff --git a/docs/content/docs/agent-sdk/integrations/observability.mdx b/docs/content/docs/guide/integrations/observability.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/integrations/observability.mdx
rename to docs/content/docs/guide/integrations/observability.mdx
diff --git a/docs/content/docs/guide/meta.json b/docs/content/docs/guide/meta.json
new file mode 100644
index 0000000000..fe7e181380
--- /dev/null
+++ b/docs/content/docs/guide/meta.json
@@ -0,0 +1,14 @@
+{
+ "title": "Guide",
+ "description": "Learn how to build with Cua",
+ "root": true,
+ "icon": "Book",
+ "pages": [
+ "get-started",
+ "fundamentals",
+ "model-providers",
+ "agents",
+ "computers",
+ "integrations"
+ ]
+}
diff --git a/docs/content/docs/agent-sdk/supported-model-providers/cua-vlm-router.mdx b/docs/content/docs/guide/model-providers/cua-vlm-router.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/supported-model-providers/cua-vlm-router.mdx
rename to docs/content/docs/guide/model-providers/cua-vlm-router.mdx
diff --git a/docs/content/docs/agent-sdk/supported-model-providers/index.mdx b/docs/content/docs/guide/model-providers/index.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/supported-model-providers/index.mdx
rename to docs/content/docs/guide/model-providers/index.mdx
diff --git a/docs/content/docs/agent-sdk/supported-model-providers/local-models.mdx b/docs/content/docs/guide/model-providers/local-models.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/supported-model-providers/local-models.mdx
rename to docs/content/docs/guide/model-providers/local-models.mdx
diff --git a/docs/content/docs/guide/model-providers/meta.json b/docs/content/docs/guide/model-providers/meta.json
new file mode 100644
index 0000000000..303c6bce13
--- /dev/null
+++ b/docs/content/docs/guide/model-providers/meta.json
@@ -0,0 +1,10 @@
+{
+ "title": "Model Providers",
+ "description": "Supported LLM providers and models",
+ "icon": "Cpu",
+ "pages": [
+ "index",
+ "cua-vlm-router",
+ "local-models"
+ ]
+}
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 14f80e9ed3..82030468cc 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -1,22 +1,9 @@
{
"title": "Home",
"description": "Documentation Home",
- "root": true,
- "defaultOpen": true,
"pages": [
- "[github][GitHub](https://github.com/trycua/cua)",
- "[discord][Discord](https://discord.com/invite/cua-ai)",
- "---[Rocket]Get Started---",
- "...get-started",
- "---[ChefHat]Examples Cookbook---",
- "...example-usecases",
- "---[Bot]Agent Playbook---",
- "...agent-sdk",
- "---[BookCopy]Computer Playbook---",
- "...computer-sdk",
- "---[Terminal]Cloud CLI Playbook---",
- "...cli-playbook",
- "---[Terminal]macOS VM CLI Playbook---",
- "...macos-vm-cli-playbook"
+ "guide",
+ "examples",
+ "reference"
]
}
diff --git a/docs/content/docs/reference/agent-sdk/index.mdx b/docs/content/docs/reference/agent-sdk/index.mdx
new file mode 100644
index 0000000000..ef0eb56370
--- /dev/null
+++ b/docs/content/docs/reference/agent-sdk/index.mdx
@@ -0,0 +1,584 @@
+---
+title: Agent SDK
+description: Python API reference for the Agent SDK
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+The **Agent SDK** (`cua-agent`) provides the Python interface for building computer-use agents. This reference covers the ComputerAgent class, callbacks, tools, and response types.
+
+## Installation
+
+```bash
+pip install cua-agent
+```
+
+## ComputerAgent
+
+The main class for creating agents that can autonomously operate computers.
+
+```python
+from agent import ComputerAgent
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+)
+
+async for result in agent.run("Open Firefox and search for Cua"):
+ print(result.text)
+```
+
+### Constructor Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model` | `str` | Required | Model identifier (see [VLMs](/docs/guide/fundamentals/vlms)) |
+| `tools` | `list` | Required | Tools the agent can use |
+| `api_key` | `str` | Provider env var | API key for the model provider |
+| `callbacks` | `list` | `[]` | List of callback handlers |
+| `instructions` | `str` | `None` | Custom instructions prepended to prompts |
+| `verbosity` | `int` | `None` | Logging level (e.g., `logging.INFO`) |
+| `max_trajectory_budget` | `float` | `None` | Maximum cost in dollars |
+| `only_n_most_recent_images` | `int` | `None` | Limit retained screenshots |
+| `trajectory_dir` | `str` \| `dict` | `None` | Directory for saving trajectories |
+
+### Methods
+
+#### `run(task, chat_history)`
+
+Execute a task autonomously. Returns an async generator of results.
+
+```python
+async for result in agent.run("Click the submit button"):
+ if result.text:
+ print(result.text)
+ if result.action:
+ print(f"Action: {result.action}")
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `task` | `str` | Required | Natural language task description |
+| `chat_history` | `list` | `[]` | Previous conversation messages |
+
+**Yields:** `AgentResult` objects containing model responses and actions.
+
+#### `run_to_completion(task, chat_history)`
+
+Execute a task and return only the final result.
+
+```python
+result = await agent.run_to_completion("Open the calculator app")
+print(result.text)
+```
+
+**Returns:** `AgentResult` - The final result after task completion.
+
+---
+
+## AgentResult
+
+Returned by `agent.run()` for each iteration of the agent loop.
+
+```python
+async for result in agent.run("Search for documentation"):
+ # Check what happened this iteration
+ if result.text:
+ print(f"Agent said: {result.text}")
+
+ if result.action:
+ print(f"Action type: {result.action.type}")
+
+ if result.usage:
+ print(f"Tokens used: {result.usage.total_tokens}")
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `text` | `str \| None` | Text response from the model |
+| `action` | `Action \| None` | Computer action taken |
+| `screenshot` | `PIL.Image \| None` | Screenshot after action |
+| `usage` | `Usage \| None` | Token and cost information |
+| `error` | `str \| None` | Error message if action failed |
+| `done` | `bool` | True if agent considers task complete |
+
+### Action Types
+
+The `action` property contains details about computer actions:
+
+```python
+result.action.type # "click", "type", "key", "scroll", etc.
+result.action.coordinate # [x, y] for click actions
+result.action.text # Text for type actions
+result.action.key # Key for key press actions
+```
+
+---
+
+## Usage Tracking
+
+The `Usage` object tracks token consumption and costs.
+
+```python
+async for result in agent.run("Complete this form"):
+ if result.usage:
+ print(f"Input tokens: {result.usage.input_tokens}")
+ print(f"Output tokens: {result.usage.output_tokens}")
+ print(f"Total tokens: {result.usage.total_tokens}")
+ print(f"Cost: ${result.usage.response_cost:.4f}")
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `input_tokens` | `int` | Tokens in the prompt |
+| `output_tokens` | `int` | Tokens in the response |
+| `total_tokens` | `int` | Total tokens used |
+| `response_cost` | `float` | Cost in dollars |
+| `cache_creation_input_tokens` | `int` | Tokens written to cache |
+| `cache_read_input_tokens` | `int` | Tokens read from cache |
+
+---
+
+## Callbacks
+
+Callbacks hook into the agent lifecycle for logging, cost tracking, and custom behavior.
+
+### Built-in Callbacks
+
+#### LoggingCallback
+
+Log agent events with configurable verbosity.
+
+```python
+from agent.callbacks import LoggingCallback
+import logging
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[LoggingCallback(level=logging.DEBUG)]
+)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `level` | `int` | `logging.INFO` | Logging level |
+
+#### BudgetManagerCallback
+
+Track costs and stop when budget is exceeded.
+
+```python
+from agent.callbacks import BudgetManagerCallback
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[BudgetManagerCallback(
+ max_budget=10.0,
+ reset_after_each_run=True,
+ raise_error=False
+ )]
+)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `max_budget` | `float` | Required | Maximum cost in dollars |
+| `reset_after_each_run` | `bool` | `True` | Reset budget per run |
+| `raise_error` | `bool` | `False` | Raise exception vs graceful stop |
+
+#### ImageRetentionCallback
+
+Limit screenshot history to prevent context overflow.
+
+```python
+from agent.callbacks import ImageRetentionCallback
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[ImageRetentionCallback(only_n_most_recent_images=3)]
+)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `only_n_most_recent_images` | `int` | Required | Max screenshots to retain |
+
+#### TrajectorySaverCallback
+
+Save complete agent conversations for debugging.
+
+```python
+from agent.callbacks import TrajectorySaverCallback
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[TrajectorySaverCallback(
+ trajectory_dir="trajectories",
+ reset_on_run=True,
+ screenshot_dir="screenshots"
+ )]
+)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `trajectory_dir` | `str` | Required | Base directory for trajectories |
+| `reset_on_run` | `bool` | `True` | Create new trajectory per run |
+| `screenshot_dir` | `str` | `None` | Separate directory for screenshots |
+
+#### PromptInstructionsCallback
+
+Prepend custom instructions to every LLM call.
+
+```python
+from agent.callbacks import PromptInstructionsCallback
+
+agent = ComputerAgent(
+ model="...",
+ tools=[computer],
+ callbacks=[PromptInstructionsCallback("Always confirm before clicking")]
+)
+```
+
+### Creating Custom Callbacks
+
+Extend `AsyncCallbackHandler` to create custom callbacks:
+
+```python
+from agent.callbacks.base import AsyncCallbackHandler
+
+class MyCallback(AsyncCallbackHandler):
+ async def on_run_start(self, kwargs, old_items):
+ """Called when agent.run() begins"""
+ print("Starting run...")
+
+ async def on_run_continue(self, kwargs, old_items, new_items) -> bool:
+ """Called before each iteration. Return False to stop."""
+ return True
+
+ async def on_llm_start(self, messages):
+ """Preprocess messages before LLM call."""
+ return messages
+
+ async def on_llm_end(self, messages):
+ """Postprocess messages after LLM call."""
+ return messages
+
+ async def on_usage(self, usage):
+ """Called with usage stats after each LLM call."""
+ print(f"Cost: ${usage.response_cost:.4f}")
+
+ async def on_computer_call_start(self, item):
+ """Called before a computer action."""
+ pass
+
+ async def on_computer_call_end(self, item, result):
+ """Called after a computer action."""
+ pass
+
+ async def on_screenshot(self, screenshot, name):
+ """Called when a screenshot is taken."""
+ pass
+
+ async def on_run_end(self, kwargs, old_items, new_items):
+ """Called when agent.run() completes."""
+ print("Run complete!")
+```
+
+### Callback Lifecycle Order
+
+1. `on_run_start` - Once at the beginning
+2. For each iteration:
+ - `on_run_continue` - Check if should continue
+ - `on_llm_start` - Before LLM call
+ - `on_api_start` - Before API request
+ - `on_api_end` - After API response
+ - `on_usage` - With usage stats
+ - `on_llm_end` - After LLM processing
+ - `on_responses` - With model responses
+ - `on_text` / `on_computer_call_start` / `on_computer_call_end` - Per response item
+ - `on_screenshot` - When screenshots are taken
+3. `on_run_end` - Once at the end
+
+---
+
+## Tools
+
+### Built-in Tools
+
+#### Computer
+
+The primary tool for full computer control.
+
+```python
+from computer import Computer
+
+computer = Computer(
+ os_type="linux",
+ provider_type="docker",
+ image="trycua/cua-xfce:latest"
+)
+await computer.run()
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+)
+```
+
+#### BrowserTool
+
+Specialized tool for web automation with browser-only models.
+
+```python
+from agent.tools import BrowserTool
+
+browser = BrowserTool(interface=computer)
+
+agent = ComputerAgent(
+ model="google/gemini-2.5-flash",
+ tools=[browser]
+)
+```
+
+See [Browser Tool](/docs/guide/fundamentals/browser-tool) for available actions.
+
+### Custom Function Tools
+
+Add Python functions as tools:
+
+```python
+def calculate(a: int, b: int) -> int:
+ """Calculate the sum of two integers"""
+ return a + b
+
+async def fetch_data(url: str) -> str:
+ """Fetch data from a URL"""
+ async with httpx.AsyncClient() as client:
+ response = await client.get(url)
+ return response.text
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer, calculate, fetch_data]
+)
+```
+
+### Sandboxed Tools
+
+Run tools inside the sandbox with the `@sandboxed` decorator:
+
+```python
+from computer.helpers import sandboxed
+
+@sandboxed()
+def read_sandbox_file(path: str) -> str:
+ """Read a file from inside the sandbox"""
+ with open(path, 'r') as f:
+ return f.read()
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer, read_sandbox_file]
+)
+```
+
+### BaseTool Class
+
+For full control over tool schema:
+
+```python
+from agent.tools import BaseTool, register_tool
+
+@register_tool("database_query")
+class DatabaseQueryTool(BaseTool):
+ def __init__(self, connection_string: str):
+ self.connection = connection_string
+
+ @property
+ def description(self) -> str:
+ return "Execute a read-only SQL query"
+
+ @property
+ def parameters(self) -> dict:
+ return {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "SQL SELECT query to execute"
+ }
+ },
+ "required": ["query"]
+ }
+
+ def call(self, params, **kwargs):
+ query = params["query"] if isinstance(params, dict) else params
+ # Execute and return results
+ return {"rows": [...]}
+```
+
+### ToolError
+
+Raise `ToolError` for recoverable errors:
+
+```python
+from agent.tools import ToolError
+
+def divide(a: float, b: float) -> float:
+ """Divide a by b"""
+ if b == 0:
+ raise ToolError("Cannot divide by zero")
+ return a / b
+```
+
+The model sees the error message and can adjust its approach.
+
+---
+
+## Model Providers
+
+### Model Format
+
+Models are specified as `provider/model-name`:
+
+```python
+# Anthropic
+agent = ComputerAgent(model="anthropic/claude-sonnet-4-5-20250929", ...)
+
+# OpenAI
+agent = ComputerAgent(model="openai/computer-use-preview", ...)
+
+# Google
+agent = ComputerAgent(model="google/gemini-2.5-flash", ...)
+
+# Local models via Ollama
+agent = ComputerAgent(model="ollama/ui-tars:latest", ...)
+```
+
+### Composed Models
+
+Use `+` to combine models for different capabilities:
+
+```python
+# UI-TARS for grounding, Claude for planning
+agent = ComputerAgent(
+ model="ollama/ui-tars:latest+anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+)
+
+# Qwen for grounding, GPT-4 for planning
+agent = ComputerAgent(
+ model="ollama/qwen2.5-vl:latest+openai/gpt-4o",
+ tools=[computer]
+)
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | API key for Anthropic models |
+| `OPENAI_API_KEY` | API key for OpenAI models |
+| `GOOGLE_API_KEY` | API key for Google models |
+| `OLLAMA_HOST` | Host for Ollama (default: `localhost:11434`) |
+
+---
+
+## Chat History
+
+Pass previous messages to maintain context:
+
+```python
+from agent.types import Message
+
+history = [
+ Message(role="user", content="Open the browser"),
+ Message(role="assistant", content="I've opened Firefox."),
+]
+
+async for result in agent.run(
+ "Now search for Python tutorials",
+ chat_history=history
+):
+ print(result.text)
+```
+
+### Message Format
+
+```python
+from agent.types import Message
+
+# User message
+user_msg = Message(role="user", content="Click the button")
+
+# Assistant message
+assistant_msg = Message(role="assistant", content="I clicked the submit button.")
+
+# System message (for instructions)
+system_msg = Message(role="system", content="Be concise in responses.")
+```
+
+---
+
+## Error Handling
+
+Handle errors during agent execution:
+
+```python
+from agent import ComputerAgent
+from agent.errors import AgentError, BudgetExceededError
+
+try:
+ async for result in agent.run("Complete the form"):
+ if result.error:
+ print(f"Action failed: {result.error}")
+ print(result.text)
+except BudgetExceededError:
+ print("Budget limit reached")
+except AgentError as e:
+ print(f"Agent error: {e}")
+```
+
+### Error Types
+
+| Error | Description |
+|-------|-------------|
+| `AgentError` | Base class for agent errors |
+| `BudgetExceededError` | Cost limit exceeded |
+| `ModelError` | Model API error |
+| `ToolError` | Tool execution error |
+
+---
+
+## Trajectory Configuration
+
+Configure trajectory saving with a dict:
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer],
+ trajectory_dir={
+ "trajectory_dir": "trajectories",
+ "reset_on_run": False, # Continue same trajectory across runs
+ "screenshot_dir": "screenshots" # Save screenshots separately
+ }
+)
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `trajectory_dir` | Required | Base directory |
+| `reset_on_run` | `True` | Create new ID per run |
+| `screenshot_dir` | `None` | Separate screenshot directory |
diff --git a/docs/content/docs/reference/agent-sdk/meta.json b/docs/content/docs/reference/agent-sdk/meta.json
new file mode 100644
index 0000000000..096a077dbc
--- /dev/null
+++ b/docs/content/docs/reference/agent-sdk/meta.json
@@ -0,0 +1,6 @@
+{
+ "title": "Agent SDK",
+ "description": "Python API for building computer-use agents",
+ "icon": "Bot",
+ "pages": ["index"]
+}
diff --git a/docs/content/docs/cli-playbook/commands.mdx b/docs/content/docs/reference/cli-playbook/commands.mdx
similarity index 100%
rename from docs/content/docs/cli-playbook/commands.mdx
rename to docs/content/docs/reference/cli-playbook/commands.mdx
diff --git a/docs/content/docs/cli-playbook/index.mdx b/docs/content/docs/reference/cli-playbook/index.mdx
similarity index 100%
rename from docs/content/docs/cli-playbook/index.mdx
rename to docs/content/docs/reference/cli-playbook/index.mdx
diff --git a/docs/content/docs/reference/cli-playbook/meta.json b/docs/content/docs/reference/cli-playbook/meta.json
new file mode 100644
index 0000000000..e463b566e4
--- /dev/null
+++ b/docs/content/docs/reference/cli-playbook/meta.json
@@ -0,0 +1,6 @@
+{
+ "title": "Cloud CLI",
+ "description": "Command-line interface for CUA Cloud",
+ "icon": "Cloud",
+ "pages": ["index", "commands"]
+}
diff --git a/docs/content/docs/reference/computer-sdk/index.mdx b/docs/content/docs/reference/computer-sdk/index.mdx
new file mode 100644
index 0000000000..807ef276d6
--- /dev/null
+++ b/docs/content/docs/reference/computer-sdk/index.mdx
@@ -0,0 +1,601 @@
+---
+title: Computer SDK
+description: Python API reference for the Computer SDK
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+
+The **Computer SDK** (`cua-computer`) provides the Python interface for creating and controlling sandboxed desktop environments. This reference covers the core classes, methods, and types you'll use when working with computers programmatically.
+
+## Installation
+
+```bash
+pip install cua-computer
+```
+
+## Core Classes
+
+### Computer
+
+The main class for creating and managing sandboxed desktop environments.
+
+```python
+from computer import Computer
+
+computer = Computer(
+ os_type="linux",
+ provider_type="docker",
+ image="trycua/cua-xfce:latest"
+)
+await computer.run()
+```
+
+#### Constructor Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `os_type` | `str` | Required | Operating system type: `"linux"`, `"macos"`, or `"windows"` |
+| `provider_type` | `str` | Required | Provider type: `"docker"`, `"lume"`, `"cloud"`, `"qemu"`, `"windows-sandbox"`, or `"host"` |
+| `image` | `str` | `None` | Container/VM image to use (provider-specific) |
+| `name` | `str` | `None` | Optional name for the computer instance |
+| `display` | `str` | `"1024x768"` | Display resolution |
+| `memory` | `str` | `"4GB"` | Memory allocation |
+| `cpu` | `int` | `2` | Number of CPU cores |
+
+#### Methods
+
+##### `run()`
+
+Start the computer and establish connection.
+
+```python
+await computer.run()
+```
+
+Returns once the computer is ready to accept commands.
+
+##### `stop()`
+
+Stop the computer and release resources.
+
+```python
+await computer.stop()
+```
+
+##### `screenshot()`
+
+Capture the current screen state.
+
+```python
+screenshot = await computer.screenshot()
+# Returns PIL.Image object
+```
+
+**Returns:** `PIL.Image.Image` - The current screen contents
+
+---
+
+### ComputerInterface
+
+The interface for interacting with the computer's display, keyboard, and mouse. Accessed via `computer.interface`.
+
+```python
+interface = computer.interface
+```
+
+#### Mouse Actions
+
+##### `left_click(x, y)`
+
+Perform a left mouse click at the specified coordinates.
+
+```python
+await computer.interface.left_click(500, 300)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `x` | `int` | X coordinate |
+| `y` | `int` | Y coordinate |
+
+##### `right_click(x, y)`
+
+Perform a right mouse click at the specified coordinates.
+
+```python
+await computer.interface.right_click(500, 300)
+```
+
+##### `double_click(x, y)`
+
+Perform a double-click at the specified coordinates.
+
+```python
+await computer.interface.double_click(500, 300)
+```
+
+##### `middle_click(x, y)`
+
+Perform a middle mouse click at the specified coordinates.
+
+```python
+await computer.interface.middle_click(500, 300)
+```
+
+##### `move(x, y)`
+
+Move the mouse cursor to the specified coordinates.
+
+```python
+await computer.interface.move(500, 300)
+```
+
+##### `drag(start_x, start_y, end_x, end_y)`
+
+Drag from start coordinates to end coordinates.
+
+```python
+await computer.interface.drag(100, 100, 500, 500)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `start_x` | `int` | Starting X coordinate |
+| `start_y` | `int` | Starting Y coordinate |
+| `end_x` | `int` | Ending X coordinate |
+| `end_y` | `int` | Ending Y coordinate |
+
+##### `scroll(x, y, scroll_x, scroll_y)`
+
+Scroll at the specified coordinates.
+
+```python
+# Scroll down
+await computer.interface.scroll(500, 300, 0, -3)
+
+# Scroll up
+await computer.interface.scroll(500, 300, 0, 3)
+
+# Scroll right
+await computer.interface.scroll(500, 300, 3, 0)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `x` | `int` | X coordinate where scroll occurs |
+| `y` | `int` | Y coordinate where scroll occurs |
+| `scroll_x` | `int` | Horizontal scroll amount (positive = right) |
+| `scroll_y` | `int` | Vertical scroll amount (positive = up) |
+
+#### Keyboard Actions
+
+##### `type_text(text)`
+
+Type text using the keyboard.
+
+```python
+await computer.interface.type_text("Hello, World!")
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | `str` | Text to type |
+
+##### `key(key)`
+
+Press a single key or key combination.
+
+```python
+# Single key
+await computer.interface.key("enter")
+
+# Key combination
+await computer.interface.key("ctrl+c")
+await computer.interface.key("cmd+v") # macOS
+await computer.interface.key("alt+tab")
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `str` | Key name or combination (e.g., `"enter"`, `"ctrl+c"`) |
+
+**Supported Keys:**
+
+- Letters: `a-z`
+- Numbers: `0-9`
+- Modifiers: `ctrl`, `alt`, `shift`, `cmd` (macOS), `win` (Windows)
+- Special: `enter`, `return`, `tab`, `escape`, `backspace`, `delete`, `space`
+- Navigation: `up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown`
+- Function: `f1`-`f12`
+
+#### Screen Methods
+
+##### `screenshot()`
+
+Capture the current screen.
+
+```python
+screenshot = await computer.interface.screenshot()
+```
+
+**Returns:** `PIL.Image.Image` - The current screen contents
+
+##### `get_screen_size()`
+
+Get the screen dimensions.
+
+```python
+width, height = await computer.interface.get_screen_size()
+```
+
+**Returns:** `tuple[int, int]` - Width and height in pixels
+
+##### `get_cursor_position()`
+
+Get the current cursor position.
+
+```python
+x, y = await computer.interface.get_cursor_position()
+```
+
+**Returns:** `tuple[int, int]` - X and Y coordinates
+
+#### Clipboard Methods
+
+##### `get_clipboard()`
+
+Get the current clipboard contents.
+
+```python
+text = await computer.interface.get_clipboard()
+```
+
+**Returns:** `str` - Clipboard text content
+
+##### `set_clipboard(text)`
+
+Set the clipboard contents.
+
+```python
+await computer.interface.set_clipboard("Text to copy")
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | `str` | Text to set in clipboard |
+
+#### Shell Methods
+
+##### `run_shell(command)`
+
+Execute a shell command in the computer.
+
+```python
+result = await computer.interface.run_shell("ls -la")
+print(result.stdout)
+print(result.stderr)
+print(result.exit_code)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `command` | `str` | Shell command to execute |
+
+**Returns:** `ShellResult` with properties:
+- `stdout` - Standard output
+- `stderr` - Standard error
+- `exit_code` - Exit code (0 = success)
+
+#### File Methods
+
+##### `file_read(path)`
+
+Read a file from the computer.
+
+```python
+content = await computer.interface.file_read("/home/user/file.txt")
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `str` | Absolute path to the file |
+
+**Returns:** `str` - File contents
+
+##### `file_write(path, content)`
+
+Write content to a file on the computer.
+
+```python
+await computer.interface.file_write("/home/user/file.txt", "Hello!")
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `str` | Absolute path to the file |
+| `content` | `str` | Content to write |
+
+##### `file_exists(path)`
+
+Check if a file exists.
+
+```python
+exists = await computer.interface.file_exists("/home/user/file.txt")
+```
+
+**Returns:** `bool` - True if file exists
+
+---
+
+### Tracing
+
+The tracing subsystem records computer interactions. Accessed via `computer.tracing`.
+
+```python
+tracing = computer.tracing
+```
+
+#### Methods
+
+##### `start(options)`
+
+Start recording interactions.
+
+```python
+await computer.tracing.start({
+ "name": "my-workflow",
+ "screenshots": True,
+ "api_calls": True,
+ "accessibility_tree": False,
+ "metadata": True
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `str` | Auto-generated | Custom trace name |
+| `screenshots` | `bool` | `True` | Capture screenshots |
+| `api_calls` | `bool` | `True` | Log interface calls |
+| `accessibility_tree` | `bool` | `False` | Record accessibility trees |
+| `metadata` | `bool` | `True` | Enable custom metadata |
+
+##### `stop(options)`
+
+Stop recording and save the trace.
+
+```python
+trace_path = await computer.tracing.stop({
+ "format": "zip", # or "dir"
+ "path": "/custom/path.zip" # optional
+})
+```
+
+**Returns:** `str` - Path to saved trace
+
+##### `add_metadata(key, value)`
+
+Add custom metadata to the trace.
+
+```python
+await computer.tracing.add_metadata("workflow", "login-flow")
+await computer.tracing.add_metadata("step", "entering-credentials")
+```
+
+---
+
+## Provider Types
+
+Different providers offer different capabilities and trade-offs.
+
+### Docker Provider
+
+```python
+computer = Computer(
+ os_type="linux",
+ provider_type="docker",
+ image="trycua/cua-xfce:latest"
+)
+```
+
+Best for Linux sandboxes with fast startup. Requires Docker to be installed.
+
+### Lume Provider
+
+```python
+computer = Computer(
+ os_type="macos",
+ provider_type="lume",
+ name="my-macos-vm"
+)
+```
+
+For macOS virtual machines on Apple Silicon. Requires [Lume](/docs/reference/macos-vm-cli-playbook/lume) to be installed.
+
+### Cloud Provider
+
+```python
+from computer import Computer
+from computer.providers import CloudProvider
+
+computer = Computer(
+ os_type="linux",
+ provider_type="cloud"
+)
+```
+
+For managed cloud sandboxes. See [CloudProvider](#cloudprovider) for configuration.
+
+### Windows Sandbox Provider
+
+```python
+computer = Computer(
+ os_type="windows",
+ provider_type="windows-sandbox"
+)
+```
+
+For Windows sandboxes on Windows hosts. Requires Windows Sandbox feature enabled.
+
+### QEMU Provider
+
+```python
+computer = Computer(
+ os_type="linux",
+ provider_type="qemu",
+ image="/path/to/disk.qcow2"
+)
+```
+
+For full VM emulation with QEMU. Supports any guest OS.
+
+### Host Provider
+
+```python
+computer = Computer(
+ os_type="macos", # or current host OS
+ provider_type="host"
+)
+```
+
+Directly controls the host machine. Use with caution.
+
+---
+
+## CloudProvider
+
+The `CloudProvider` class enables programmatic management of cloud sandboxes.
+
+```python
+from computer.providers import CloudProvider
+
+provider = CloudProvider(
+ api_key="your-api-key",
+ region="north-america"
+)
+```
+
+### Constructor Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | `CUA_API_KEY` env var | API key for authentication |
+| `region` | `str` | `"north-america"` | Region: `"north-america"`, `"europe"`, `"asia-pacific"` |
+
+### Methods
+
+##### `create_sandbox(options)`
+
+Create a new cloud sandbox.
+
+```python
+sandbox = await provider.create_sandbox({
+ "os": "linux",
+ "size": "medium",
+ "image": "trycua/cua-xfce:latest"
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `os` | `str` | `"linux"` | Operating system |
+| `size` | `str` | `"small"` | Size: `"small"`, `"medium"`, `"large"` |
+| `image` | `str` | Default image | Container image to use |
+
+##### `list_sandboxes()`
+
+List all sandboxes.
+
+```python
+sandboxes = await provider.list_sandboxes()
+for sandbox in sandboxes:
+ print(f"{sandbox.id}: {sandbox.status}")
+```
+
+##### `get_sandbox(sandbox_id)`
+
+Get details for a specific sandbox.
+
+```python
+sandbox = await provider.get_sandbox("sandbox-abc123")
+```
+
+##### `delete_sandbox(sandbox_id)`
+
+Delete a sandbox.
+
+```python
+await provider.delete_sandbox("sandbox-abc123")
+```
+
+---
+
+## Types
+
+### OSType
+
+```python
+from computer import OSType
+
+OSType.LINUX # "linux"
+OSType.MACOS # "macos"
+OSType.WINDOWS # "windows"
+```
+
+### ProviderType
+
+```python
+from computer import ProviderType
+
+ProviderType.DOCKER # "docker"
+ProviderType.LUME # "lume"
+ProviderType.CLOUD # "cloud"
+ProviderType.QEMU # "qemu"
+ProviderType.WINDOWS_SANDBOX # "windows-sandbox"
+ProviderType.HOST # "host"
+```
+
+### ShellResult
+
+Result from `run_shell()` calls.
+
+```python
+result = await computer.interface.run_shell("echo hello")
+result.stdout # "hello\n"
+result.stderr # ""
+result.exit_code # 0
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `stdout` | `str` | Standard output |
+| `stderr` | `str` | Standard error |
+| `exit_code` | `int` | Exit code (0 = success) |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CUA_API_KEY` | API key for cloud provider |
+| `CUA_REGION` | Default region for cloud provider |
+| `DOCKER_HOST` | Custom Docker host for Docker provider |
+| `LUME_HOST` | Custom Lume API host (default: `localhost:7777`) |
+
+---
+
+## Context Manager Usage
+
+The Computer class supports async context managers for automatic cleanup:
+
+```python
+from computer import Computer
+
+async with Computer(
+ os_type="linux",
+ provider_type="docker",
+ image="trycua/cua-xfce:latest"
+) as computer:
+ await computer.interface.type_text("Hello!")
+ # Computer automatically stopped on exit
+```
diff --git a/docs/content/docs/reference/computer-sdk/meta.json b/docs/content/docs/reference/computer-sdk/meta.json
new file mode 100644
index 0000000000..bf192152fe
--- /dev/null
+++ b/docs/content/docs/reference/computer-sdk/meta.json
@@ -0,0 +1,6 @@
+{
+ "title": "Computer SDK",
+ "description": "Python API for sandboxed desktop environments",
+ "icon": "Monitor",
+ "pages": ["index"]
+}
diff --git a/docs/content/docs/macos-vm-cli-playbook/lume/cli-reference.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lume/cli-reference.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lume/cli-reference.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lume/cli-reference.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lume/faq.md b/docs/content/docs/reference/macos-vm-cli-playbook/lume/faq.md
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lume/faq.md
rename to docs/content/docs/reference/macos-vm-cli-playbook/lume/faq.md
diff --git a/docs/content/docs/macos-vm-cli-playbook/lume/http-api.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lume/http-api.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lume/http-api.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lume/http-api.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lume/index.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lume/index.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lume/index.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lume/index.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lume/installation.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lume/installation.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lume/installation.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lume/installation.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lume/meta.json b/docs/content/docs/reference/macos-vm-cli-playbook/lume/meta.json
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lume/meta.json
rename to docs/content/docs/reference/macos-vm-cli-playbook/lume/meta.json
diff --git a/docs/content/docs/macos-vm-cli-playbook/lume/prebuilt-images.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lume/prebuilt-images.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lume/prebuilt-images.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lume/prebuilt-images.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lumier/building-lumier.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lumier/building-lumier.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lumier/building-lumier.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lumier/building-lumier.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lumier/docker-compose.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lumier/docker-compose.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lumier/docker-compose.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lumier/docker-compose.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lumier/docker.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lumier/docker.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lumier/docker.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lumier/docker.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lumier/index.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lumier/index.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lumier/index.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lumier/index.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lumier/installation.mdx b/docs/content/docs/reference/macos-vm-cli-playbook/lumier/installation.mdx
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lumier/installation.mdx
rename to docs/content/docs/reference/macos-vm-cli-playbook/lumier/installation.mdx
diff --git a/docs/content/docs/macos-vm-cli-playbook/lumier/meta.json b/docs/content/docs/reference/macos-vm-cli-playbook/lumier/meta.json
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/lumier/meta.json
rename to docs/content/docs/reference/macos-vm-cli-playbook/lumier/meta.json
diff --git a/docs/content/docs/reference/macos-vm-cli-playbook/meta.json b/docs/content/docs/reference/macos-vm-cli-playbook/meta.json
new file mode 100644
index 0000000000..7c98e4bd2f
--- /dev/null
+++ b/docs/content/docs/reference/macos-vm-cli-playbook/meta.json
@@ -0,0 +1,6 @@
+{
+ "title": "macOS VM CLI",
+ "description": "CLI tools for macOS virtualization",
+ "icon": "Terminal",
+ "pages": ["lume", "lumier"]
+}
diff --git a/docs/content/docs/reference/meta.json b/docs/content/docs/reference/meta.json
new file mode 100644
index 0000000000..6c2d7f2179
--- /dev/null
+++ b/docs/content/docs/reference/meta.json
@@ -0,0 +1,12 @@
+{
+ "title": "Reference",
+ "description": "SDK and CLI API reference",
+ "root": true,
+ "icon": "FileText",
+ "pages": [
+ "computer-sdk",
+ "agent-sdk",
+ "cli-playbook",
+ "macos-vm-cli-playbook"
+ ]
+}
diff --git a/docs/content/examples/example-usecases/form-filling.mdx b/docs/content/examples/example-usecases/form-filling.mdx
new file mode 100644
index 0000000000..d133aa026f
--- /dev/null
+++ b/docs/content/examples/example-usecases/form-filling.mdx
@@ -0,0 +1,500 @@
+---
+title: PDF to Form Automation
+description: Enhance and Automate Interactions Between Form Filling and Local File Systems
+---
+
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+## Overview
+
+Cua can be used to automate interactions between form filling and local file systems over any operating system. Cua let's you interact with all the elements of a web page and local file systems to integrate between the two.
+
+This preset usecase uses [Cua Computer Framework](/computer-sdk/computers) to interact with a web page and local file systems along with [Agent Loops](/agent-sdk/agent-loops) to run the agent in a loop with message history.
+
+---
+
+<Steps>
+
+<Step>
+
+### Set Up Your Environment
+
+First, install the required dependencies:
+
+Create a `requirements.txt` file:
+
+```text
+cua-agent
+cua-computer
+python-dotenv>=1.0.0
+```
+
+Install the dependencies using uv (recommended):
+
+```bash
+uv pip install -r requirements.txt
+```
+
+Or using pip:
+
+```bash
+pip install -r requirements.txt
+```
+
+Create a `.env` file with your API keys:
+
+```text
+ANTHROPIC_API_KEY=your-anthropic-api-key
+CUA_API_KEY=sk_cua-api01...
+```
+
+</Step>
+
+<Step>
+
+### Create Your Form Filling Script
+
+Create a Python file (e.g., `form_filling.py`) and select your environment:
+
+<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS Sandbox', 'Windows Sandbox']}>
+ <Tab value="Cloud Sandbox">
+
+```python
+import asyncio
+import logging
+import os
+import signal
+import traceback
+
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def handle_sigint(sig, frame):
+ print("\n\nExecution interrupted by user. Exiting gracefully...")
+ exit(0)
+
+async def fill_application():
+ try:
+ async with Computer(
+ os_type="linux",
+ provider_type=VMProviderType.CLOUD,
+ name="your-sandbox-name", # Replace with your sandbox name
+ api_key=os.environ["CUA_API_KEY"],
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=True,
+ max_trajectory_budget=5.0,
+ )
+
+ tasks = [
+ "Visit https://www.overleaf.com/latex/templates/jakes-resume/syzfjbzwjncs.pdf and download the pdf.",
+ "Visit https://form.jotform.com/252881246782264 and fill the form from the information in the pdf."
+ ]
+
+ history = []
+
+ for i, task in enumerate(tasks, 1):
+ print(f"\n[Task {i}/{len(tasks)}] {task}")
+
+ # Add user message to history
+ history.append({"role": "user", "content": task})
+
+ # Run agent with conversation history
+ async for result in agent.run(history, stream=False):
+ history += result.get("output", [])
+
+ # Print output for debugging
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for content_part in content:
+ if content_part.get("text"):
+ logger.info(f"Agent: {content_part.get('text')}")
+ elif item.get("type") == "computer_call":
+ action = item.get("action", {})
+ action_type = action.get("type", "")
+ logger.debug(f"Computer Action: {action_type}")
+
+ print(f"✅ Task {i}/{len(tasks)} completed")
+
+ print("\n🎉 All tasks completed successfully!")
+
+ except Exception as e:
+ logger.error(f"Error in fill_application: {e}")
+ traceback.print_exc()
+ raise
+
+def main():
+ try:
+ load_dotenv()
+
+ if "ANTHROPIC_API_KEY" not in os.environ:
+ raise RuntimeError(
+ "Please set the ANTHROPIC_API_KEY environment variable.\n"
+ "You can add it to a .env file in the project root."
+ )
+
+ if "CUA_API_KEY" not in os.environ:
+ raise RuntimeError(
+ "Please set the CUA_API_KEY environment variable.\n"
+ "You can add it to a .env file in the project root."
+ )
+
+ signal.signal(signal.SIGINT, handle_sigint)
+
+ asyncio.run(fill_application())
+
+ except Exception as e:
+ logger.error(f"Error running automation: {e}")
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ main()
+```
+
+ </Tab>
+ <Tab value="Linux on Docker">
+
+```python
+import asyncio
+import logging
+import os
+import signal
+import traceback
+
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def handle_sigint(sig, frame):
+ print("\n\nExecution interrupted by user. Exiting gracefully...")
+ exit(0)
+
+async def fill_application():
+ try:
+ async with Computer(
+ os_type="linux",
+ provider_type=VMProviderType.DOCKER,
+ image="trycua/cua-xfce:latest", # or "trycua/cua-ubuntu:latest"
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=True,
+ max_trajectory_budget=5.0,
+ )
+
+ tasks = [
+ "Visit https://www.overleaf.com/latex/templates/jakes-resume/syzfjbzwjncs.pdf and download the pdf.",
+ "Visit https://form.jotform.com/252881246782264 and fill the form from the information in the pdf."
+ ]
+
+ history = []
+
+ for i, task in enumerate(tasks, 1):
+ print(f"\n[Task {i}/{len(tasks)}] {task}")
+
+ # Add user message to history
+ history.append({"role": "user", "content": task})
+
+ # Run agent with conversation history
+ async for result in agent.run(history, stream=False):
+ history += result.get("output", [])
+
+ # Print output for debugging
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for content_part in content:
+ if content_part.get("text"):
+ logger.info(f"Agent: {content_part.get('text')}")
+ elif item.get("type") == "computer_call":
+ action = item.get("action", {})
+ action_type = action.get("type", "")
+ logger.debug(f"Computer Action: {action_type}")
+
+ print(f"✅ Task {i}/{len(tasks)} completed")
+
+ print("\n🎉 All tasks completed successfully!")
+
+ except Exception as e:
+ logger.error(f"Error in fill_application: {e}")
+ traceback.print_exc()
+ raise
+
+def main():
+ try:
+ load_dotenv()
+
+ if "ANTHROPIC_API_KEY" not in os.environ:
+ raise RuntimeError(
+ "Please set the ANTHROPIC_API_KEY environment variable.\n"
+ "You can add it to a .env file in the project root."
+ )
+
+ signal.signal(signal.SIGINT, handle_sigint)
+
+ asyncio.run(fill_application())
+
+ except Exception as e:
+ logger.error(f"Error running automation: {e}")
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ main()
+```
+
+ </Tab>
+ <Tab value="macOS Sandbox">
+
+```python
+import asyncio
+import logging
+import os
+import signal
+import traceback
+
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def handle_sigint(sig, frame):
+ print("\n\nExecution interrupted by user. Exiting gracefully...")
+ exit(0)
+
+async def fill_application():
+ try:
+ async with Computer(
+ os_type="macos",
+ provider_type=VMProviderType.LUME,
+ name="macos-sequoia-cua:latest",
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=True,
+ max_trajectory_budget=5.0,
+ )
+
+ tasks = [
+ "Visit https://www.overleaf.com/latex/templates/jakes-resume/syzfjbzwjncs.pdf and download the pdf.",
+ "Visit https://form.jotform.com/252881246782264 and fill the form from the information in the pdf."
+ ]
+
+ history = []
+
+ for i, task in enumerate(tasks, 1):
+ print(f"\n[Task {i}/{len(tasks)}] {task}")
+
+ # Add user message to history
+ history.append({"role": "user", "content": task})
+
+ # Run agent with conversation history
+ async for result in agent.run(history, stream=False):
+ history += result.get("output", [])
+
+ # Print output for debugging
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for content_part in content:
+ if content_part.get("text"):
+ logger.info(f"Agent: {content_part.get('text')}")
+ elif item.get("type") == "computer_call":
+ action = item.get("action", {})
+ action_type = action.get("type", "")
+ logger.debug(f"Computer Action: {action_type}")
+
+ print(f"✅ Task {i}/{len(tasks)} completed")
+
+ print("\n🎉 All tasks completed successfully!")
+
+ except Exception as e:
+ logger.error(f"Error in fill_application: {e}")
+ traceback.print_exc()
+ raise
+
+def main():
+ try:
+ load_dotenv()
+
+ if "ANTHROPIC_API_KEY" not in os.environ:
+ raise RuntimeError(
+ "Please set the ANTHROPIC_API_KEY environment variable.\n"
+ "You can add it to a .env file in the project root."
+ )
+
+ signal.signal(signal.SIGINT, handle_sigint)
+
+ asyncio.run(fill_application())
+
+ except Exception as e:
+ logger.error(f"Error running automation: {e}")
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ main()
+```
+
+ </Tab>
+ <Tab value="Windows Sandbox">
+
+```python
+import asyncio
+import logging
+import os
+import signal
+import traceback
+
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def handle_sigint(sig, frame):
+ print("\n\nExecution interrupted by user. Exiting gracefully...")
+ exit(0)
+
+async def fill_application():
+ try:
+ async with Computer(
+ os_type="windows",
+ provider_type=VMProviderType.WINDOWS_SANDBOX,
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=True,
+ max_trajectory_budget=5.0,
+ )
+
+ tasks = [
+ "Visit https://www.overleaf.com/latex/templates/jakes-resume/syzfjbzwjncs.pdf and download the pdf.",
+ "Visit https://form.jotform.com/252881246782264 and fill the form from the information in the pdf."
+ ]
+
+ history = []
+
+ for i, task in enumerate(tasks, 1):
+ print(f"\n[Task {i}/{len(tasks)}] {task}")
+
+ # Add user message to history
+ history.append({"role": "user", "content": task})
+
+ # Run agent with conversation history
+ async for result in agent.run(history, stream=False):
+ history += result.get("output", [])
+
+ # Print output for debugging
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for content_part in content:
+ if content_part.get("text"):
+ logger.info(f"Agent: {content_part.get('text')}")
+ elif item.get("type") == "computer_call":
+ action = item.get("action", {})
+ action_type = action.get("type", "")
+ logger.debug(f"Computer Action: {action_type}")
+
+ print(f"✅ Task {i}/{len(tasks)} completed")
+
+ print("\n🎉 All tasks completed successfully!")
+
+ except Exception as e:
+ logger.error(f"Error in fill_application: {e}")
+ traceback.print_exc()
+ raise
+
+def main():
+ try:
+ load_dotenv()
+
+ if "ANTHROPIC_API_KEY" not in os.environ:
+ raise RuntimeError(
+ "Please set the ANTHROPIC_API_KEY environment variable.\n"
+ "You can add it to a .env file in the project root."
+ )
+
+ signal.signal(signal.SIGINT, handle_sigint)
+
+ asyncio.run(fill_application())
+
+ except Exception as e:
+ logger.error(f"Error running automation: {e}")
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ main()
+```
+
+ </Tab>
+</Tabs>
+
+</Step>
+
+<Step>
+
+### Run Your Script
+
+Execute your form filling automation:
+
+```bash
+python form_filling.py
+```
+
+The agent will:
+
+1. Download the PDF resume from Overleaf
+2. Extract information from the PDF
+3. Fill out the JotForm with the extracted information
+
+Monitor the output to see the agent's progress through each task.
+
+</Step>
+
+</Steps>
+
+---
+
+## Next Steps
+
+- Learn more about [Cua Computer Framework](/computer-sdk/computers) and [Computer Commands](/computer-sdk/commands)
+- Read about [Agent Loops](/agent-sdk/agent-loops), [Tools](/agent-sdk/custom-tools), and [Supported Model Providers](/agent-sdk/supported-model-providers/)
+- Experiment with different [Models and Providers](/agent-sdk/supported-model-providers/)
+- Join our [Discord community](https://discord.com/invite/mVnXXpdE85) for help
diff --git a/docs/content/examples/example-usecases/gemini-complex-ui-navigation.mdx b/docs/content/examples/example-usecases/gemini-complex-ui-navigation.mdx
new file mode 100644
index 0000000000..4a3d1d0fbc
--- /dev/null
+++ b/docs/content/examples/example-usecases/gemini-complex-ui-navigation.mdx
@@ -0,0 +1,640 @@
+---
+title: GUI Grounding with Gemini 3
+description: Using Google's Gemini 3 with OmniParser for Advanced GUI Grounding Tasks
+---
+
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+## Overview
+
+This example demonstrates how to use Google's Gemini 3 models with OmniParser for complex GUI grounding tasks. Gemini 3 Pro achieves exceptional performance on the [ScreenSpot-Pro benchmark](https://github.com/likaixin2000/ScreenSpot-Pro-GUI-Grounding) with a **72.7% accuracy** (compared to Claude Sonnet 4.5's 36.2%), making it ideal for precise UI element location and complex navigation tasks.
+
+<img
+ src="/docs/img/grounding-with-gemini3.gif"
+ alt="Demo of Gemini 3 with OmniParser performing complex GUI navigation tasks"
+ width="800px"
+/>
+
+<Callout type="info" title="Why Gemini 3 for UI Navigation?">
+ According to [Google's Gemini 3 announcement](https://blog.google/products/gemini/gemini-3/),
+ Gemini 3 Pro achieves: - **72.7%** on ScreenSpot-Pro (vs. Gemini 2.5 Pro's 11.4%) -
+ Industry-leading performance on complex UI navigation tasks - Advanced multimodal understanding
+ for high-resolution screens
+</Callout>
+
+### What You'll Build
+
+This guide shows how to:
+
+- Set up Vertex AI with proper authentication
+- Use OmniParser with Gemini 3 for GUI element detection
+- Leverage Gemini 3-specific features like `thinking_level` and `media_resolution`
+- Create agents that can perform complex multi-step UI interactions
+
+---
+
+<Steps>
+
+<Step>
+
+### Set Up Google Cloud and Vertex AI
+
+Before using Gemini 3 models, you need to enable Vertex AI in Google Cloud Console.
+
+#### 1. Create a Google Cloud Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Click **Select a project** → **New Project**
+3. Enter a project name and click **Create**
+4. Note your **Project ID** (you'll need this later)
+
+#### 2. Enable Vertex AI API
+
+1. Navigate to [Vertex AI API](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com)
+2. Select your project
+3. Click **Enable**
+
+#### 3. Enable Billing
+
+1. Go to [Billing](https://console.cloud.google.com/billing)
+2. Link a billing account to your project
+3. Vertex AI offers a [free tier](https://cloud.google.com/vertex-ai/pricing) for testing
+
+#### 4. Create a Service Account
+
+1. Go to [IAM & Admin > Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
+2. Click **Create Service Account**
+3. Enter a name (e.g., "cua-gemini-agent")
+4. Click **Create and Continue**
+5. Grant the **Vertex AI User** role
+6. Click **Done**
+
+#### 5. Create and Download Service Account Key
+
+1. Click on your newly created service account
+2. Go to **Keys** tab
+3. Click **Add Key** → **Create new key**
+4. Select **JSON** format
+5. Click **Create** (the key file will download automatically)
+6. **Important**: Store this key file securely! It contains credentials for accessing your Google Cloud resources
+
+<Callout type="warn">
+ Never commit your service account JSON key to version control! Add it to `.gitignore` immediately.
+</Callout>
+
+</Step>
+
+<Step>
+
+### Install Dependencies
+
+Install the required packages for OmniParser and Gemini 3:
+
+Create a `requirements.txt` file:
+
+```text
+cua-agent
+cua-computer
+cua-som # OmniParser for GUI element detection
+litellm>=1.0.0
+python-dotenv>=1.0.0
+google-cloud-aiplatform>=1.70.0
+```
+
+Install the dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+</Step>
+
+<Step>
+
+### Configure Environment Variables
+
+Create a `.env` file in your project root:
+
+```text
+# Google Cloud / Vertex AI credentials
+GOOGLE_CLOUD_PROJECT=your-project-id
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/your-service-account-key.json
+
+# Cua credentials (for cloud sandboxes)
+CUA_API_KEY=sk_cua-api01...
+CUA_SANDBOX_NAME=your-sandbox-name
+```
+
+Replace the values:
+
+- `your-project-id`: Your Google Cloud Project ID from Step 1
+- `/path/to/your-service-account-key.json`: Path to the JSON key file you downloaded
+- `sk_cua-api01...`: Your Cua API key from the [Cua dashboard](https://cua.dev)
+- `your-sandbox-name`: Your sandbox name (if using cloud sandboxes)
+
+</Step>
+
+<Step>
+
+### Create Your Complex UI Navigation Script
+
+Create a Python file (e.g., `gemini_ui_navigation.py`):
+
+<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS Sandbox']}>
+ <Tab value="Cloud Sandbox">
+
+```python
+import asyncio
+import logging
+import os
+import signal
+import traceback
+
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def handle_sigint(sig, frame):
+ print("\n\nExecution interrupted by user. Exiting gracefully...")
+ exit(0)
+
+async def complex_ui_navigation():
+ """
+ Demonstrate Gemini 3's exceptional UI grounding capabilities
+ with complex, multi-step navigation tasks.
+ """
+ try:
+ async with Computer(
+ os_type="linux",
+ provider_type=VMProviderType.CLOUD,
+ name=os.environ["CUA_SANDBOX_NAME"],
+ api_key=os.environ["CUA_API_KEY"],
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ # Use OmniParser with Gemini 3 Pro for optimal GUI grounding
+ model="omniparser+vertex_ai/gemini-3-pro-preview",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=False,
+ max_trajectory_budget=5.0,
+ # Gemini 3-specific parameters
+ thinking_level="high", # Enables deeper reasoning (vs "low")
+ media_resolution="high", # High-resolution image processing (vs "low" or "medium")
+ )
+
+ # Complex GUI grounding tasks inspired by ScreenSpot-Pro benchmark
+ # These test precise element location in professional UIs
+ tasks = [
+ # Task 1: GitHub repository navigation
+ {
+ "instruction": (
+ "Go to github.com/trycua/cua. "
+ "Find and click on the 'Issues' tab. "
+ "Then locate and click on the search box within the issues page "
+ "(not the global GitHub search). "
+ "Type 'omniparser' and press Enter."
+ ),
+ "description": "Tests precise UI element distinction in a complex interface",
+ },
+
+ # Task 2: Search for and install Visual Studio Code
+ {
+ "instruction": (
+ "Open your system's app store (e.g., Microsoft Store). "
+ "Search for 'Visual Studio Code'. "
+ "In the search results, select 'Visual Studio Code'. "
+ "Click on 'Install' or 'Get' to begin the installation. "
+ "If prompted, accept any permissions or confirm the installation. "
+ "Wait for Visual Studio Code to finish installing."
+ ),
+ "description": "Tests the ability to search for an application and complete its installation through a step-by-step app store workflow.",
+ },
+ ]
+
+ history = []
+
+ for i, task_info in enumerate(tasks, 1):
+ task = task_info["instruction"]
+ print(f"\n{'='*60}")
+ print(f"[Task {i}/{len(tasks)}] {task_info['description']}")
+ print(f"{'='*60}")
+ print(f"\nInstruction: {task}\n")
+
+ # Add user message to history
+ history.append({"role": "user", "content": task})
+
+ # Run agent with conversation history
+ async for result in agent.run(history, stream=False):
+ history += result.get("output", [])
+
+ # Print output for debugging
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for content_part in content:
+ if content_part.get("text"):
+ logger.info(f"Agent: {content_part.get('text')}")
+ elif item.get("type") == "computer_call":
+ action = item.get("action", {})
+ action_type = action.get("type", "")
+ logger.debug(f"Computer Action: {action_type}")
+
+ print(f"\n✅ Task {i}/{len(tasks)} completed")
+
+ print("\n🎉 All complex UI navigation tasks completed successfully!")
+
+ except Exception as e:
+ logger.error(f"Error in complex_ui_navigation: {e}")
+ traceback.print_exc()
+ raise
+
+def main():
+ try:
+ load_dotenv()
+
+ # Validate required environment variables
+ required_vars = [
+ "GOOGLE_CLOUD_PROJECT",
+ "GOOGLE_APPLICATION_CREDENTIALS",
+ "CUA_API_KEY",
+ "CUA_SANDBOX_NAME",
+ ]
+
+ missing_vars = [var for var in required_vars if not os.environ.get(var)]
+ if missing_vars:
+ raise RuntimeError(
+ f"Missing required environment variables: {', '.join(missing_vars)}\n"
+ f"Please check your .env file and ensure all keys are set.\n"
+ f"See the setup guide for details on configuring Vertex AI credentials."
+ )
+
+ signal.signal(signal.SIGINT, handle_sigint)
+
+ asyncio.run(complex_ui_navigation())
+
+ except Exception as e:
+ logger.error(f"Error running automation: {e}")
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ main()
+```
+
+ </Tab>
+ <Tab value="Linux on Docker">
+
+```python
+import asyncio
+import logging
+import os
+import signal
+import traceback
+
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def handle_sigint(sig, frame):
+ print("\n\nExecution interrupted by user. Exiting gracefully...")
+ exit(0)
+
+async def complex_ui_navigation():
+ """
+ Demonstrate Gemini 3's exceptional UI grounding capabilities
+ with complex, multi-step navigation tasks.
+ """
+ try:
+ async with Computer(
+ os_type="linux",
+ provider_type=VMProviderType.DOCKER,
+ image="trycua/cua-xfce:latest",
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ # Use OmniParser with Gemini 3 Pro for optimal GUI grounding
+ model="omniparser+vertex_ai/gemini-3-pro-preview",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=False,
+ max_trajectory_budget=5.0,
+ # Gemini 3-specific parameters
+ thinking_level="high", # Enables deeper reasoning (vs "low")
+ media_resolution="high", # High-resolution image processing (vs "low" or "medium")
+ )
+
+ # Complex GUI grounding tasks inspired by ScreenSpot-Pro benchmark
+ tasks = [
+ {
+ "instruction": (
+ "Go to github.com/trycua/cua. "
+ "Find and click on the 'Issues' tab. "
+ "Then locate and click on the search box within the issues page "
+ "(not the global GitHub search). "
+ "Type 'omniparser' and press Enter."
+ ),
+ "description": "Tests precise UI element distinction in a complex interface",
+ },
+ ]
+
+ history = []
+
+ for i, task_info in enumerate(tasks, 1):
+ task = task_info["instruction"]
+ print(f"\n{'='*60}")
+ print(f"[Task {i}/{len(tasks)}] {task_info['description']}")
+ print(f"{'='*60}")
+ print(f"\nInstruction: {task}\n")
+
+ history.append({"role": "user", "content": task})
+
+ async for result in agent.run(history, stream=False):
+ history += result.get("output", [])
+
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for content_part in content:
+ if content_part.get("text"):
+ logger.info(f"Agent: {content_part.get('text')}")
+ elif item.get("type") == "computer_call":
+ action = item.get("action", {})
+ action_type = action.get("type", "")
+ logger.debug(f"Computer Action: {action_type}")
+
+ print(f"\n✅ Task {i}/{len(tasks)} completed")
+
+ print("\n🎉 All complex UI navigation tasks completed successfully!")
+
+ except Exception as e:
+ logger.error(f"Error in complex_ui_navigation: {e}")
+ traceback.print_exc()
+ raise
+
+def main():
+ try:
+ load_dotenv()
+
+ required_vars = [
+ "GOOGLE_CLOUD_PROJECT",
+ "GOOGLE_APPLICATION_CREDENTIALS",
+ ]
+
+ missing_vars = [var for var in required_vars if not os.environ.get(var)]
+ if missing_vars:
+ raise RuntimeError(
+ f"Missing required environment variables: {', '.join(missing_vars)}\n"
+ f"Please check your .env file."
+ )
+
+ signal.signal(signal.SIGINT, handle_sigint)
+
+ asyncio.run(complex_ui_navigation())
+
+ except Exception as e:
+ logger.error(f"Error running automation: {e}")
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ main()
+```
+
+ </Tab>
+ <Tab value="macOS Sandbox">
+
+```python
+import asyncio
+import logging
+import os
+import signal
+import traceback
+
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def handle_sigint(sig, frame):
+ print("\n\nExecution interrupted by user. Exiting gracefully...")
+ exit(0)
+
+async def complex_ui_navigation():
+ """
+ Demonstrate Gemini 3's exceptional UI grounding capabilities
+ with complex, multi-step navigation tasks.
+ """
+ try:
+ async with Computer(
+ os_type="macos",
+ provider_type=VMProviderType.LUME,
+ name="macos-sequoia-cua:latest",
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ # Use OmniParser with Gemini 3 Pro for optimal GUI grounding
+ model="omniparser+vertex_ai/gemini-3-pro-preview",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=False,
+ max_trajectory_budget=5.0,
+ # Gemini 3-specific parameters
+ thinking_level="high", # Enables deeper reasoning (vs "low")
+ media_resolution="high", # High-resolution image processing (vs "low" or "medium")
+ )
+
+ # Complex GUI grounding tasks inspired by ScreenSpot-Pro benchmark
+ tasks = [
+ {
+ "instruction": (
+ "Go to github.com/trycua/cua. "
+ "Find and click on the 'Issues' tab. "
+ "Then locate and click on the search box within the issues page "
+ "(not the global GitHub search). "
+ "Type 'omniparser' and press Enter."
+ ),
+ "description": "Tests precise UI element distinction in a complex interface",
+ },
+ ]
+
+ history = []
+
+ for i, task_info in enumerate(tasks, 1):
+ task = task_info["instruction"]
+ print(f"\n{'='*60}")
+ print(f"[Task {i}/{len(tasks)}] {task_info['description']}")
+ print(f"{'='*60}")
+ print(f"\nInstruction: {task}\n")
+
+ history.append({"role": "user", "content": task})
+
+ async for result in agent.run(history, stream=False):
+ history += result.get("output", [])
+
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for content_part in content:
+ if content_part.get("text"):
+ logger.info(f"Agent: {content_part.get('text')}")
+ elif item.get("type") == "computer_call":
+ action = item.get("action", {})
+ action_type = action.get("type", "")
+ logger.debug(f"Computer Action: {action_type}")
+
+ print(f"\n✅ Task {i}/{len(tasks)} completed")
+
+ print("\n🎉 All complex UI navigation tasks completed successfully!")
+
+ except Exception as e:
+ logger.error(f"Error in complex_ui_navigation: {e}")
+ traceback.print_exc()
+ raise
+
+def main():
+ try:
+ load_dotenv()
+
+ required_vars = [
+ "GOOGLE_CLOUD_PROJECT",
+ "GOOGLE_APPLICATION_CREDENTIALS",
+ ]
+
+ missing_vars = [var for var in required_vars if not os.environ.get(var)]
+ if missing_vars:
+ raise RuntimeError(
+ f"Missing required environment variables: {', '.join(missing_vars)}\n"
+ f"Please check your .env file."
+ )
+
+ signal.signal(signal.SIGINT, handle_sigint)
+
+ asyncio.run(complex_ui_navigation())
+
+ except Exception as e:
+ logger.error(f"Error running automation: {e}")
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ main()
+```
+
+ </Tab>
+</Tabs>
+
+</Step>
+
+<Step>
+
+### Run Your Script
+
+Execute your complex UI navigation automation:
+
+```bash
+python gemini_ui_navigation.py
+```
+
+The agent will:
+
+1. Navigate to GitHub and locate specific UI elements
+2. Distinguish between similar elements (e.g., global search vs. issues search)
+3. Perform multi-step interactions with visual feedback
+4. Use Gemini 3's advanced reasoning for precise element grounding
+
+Monitor the output to see the agent's progress through each task.
+
+</Step>
+
+</Steps>
+
+---
+
+## Understanding Gemini 3-Specific Parameters
+
+### `thinking_level`
+
+Controls the amount of internal reasoning the model performs:
+
+- `"high"`: Deeper reasoning, better for complex UI navigation (recommended for ScreenSpot-like tasks)
+- `"low"`: Faster responses, suitable for simpler tasks
+
+### `media_resolution`
+
+Controls vision processing for multimodal inputs:
+
+- `"high"`: Best for complex UIs with many small elements (recommended)
+- `"medium"`: Balanced quality and speed
+- `"low"`: Faster processing for simple interfaces
+
+<Callout type="info">
+ For tasks requiring precise GUI element location (like ScreenSpot-Pro), use
+ `thinking_level="high"` and `media_resolution="high"` for optimal performance.
+</Callout>
+
+---
+
+## Benchmark Performance
+
+Gemini 3 Pro's performance on ScreenSpot-Pro demonstrates its exceptional UI grounding capabilities:
+
+| Model | ScreenSpot-Pro Score |
+| ----------------- | -------------------- |
+| **Gemini 3 Pro** | **72.7%** |
+| Claude Sonnet 4.5 | 36.2% |
+| Gemini 2.5 Pro | 11.4% |
+| GPT-5.1 | 3.5% |
+
+This makes Gemini 3 the ideal choice for complex UI navigation, element detection, and professional GUI automation tasks.
+
+---
+
+## Troubleshooting
+
+### Authentication Issues
+
+If you encounter authentication errors:
+
+1. Verify your service account JSON key path is correct
+2. Ensure the service account has the **Vertex AI User** role
+3. Check that the Vertex AI API is enabled in your project
+4. Confirm your `GOOGLE_CLOUD_PROJECT` matches your actual project ID
+
+### "Vertex AI API not enabled" Error
+
+Run this command to enable the API:
+
+```bash
+gcloud services enable aiplatform.googleapis.com --project=YOUR_PROJECT_ID
+```
+
+### Billing Issues
+
+Ensure billing is enabled for your Google Cloud project. Visit the [Billing section](https://console.cloud.google.com/billing) to verify.
+
+---
+
+## Next Steps
+
+- Learn more about [OmniParser agent loops](/agent-sdk/agent-loops)
+- Explore [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing)
+- Read about [ScreenSpot-Pro benchmark](https://github.com/likaixin2000/ScreenSpot-Pro-GUI-Grounding)
+- Check out [Google's Gemini 3 announcement](https://blog.google/products/gemini/gemini-3/)
+- Join our [Discord community](https://discord.com/invite/mVnXXpdE85) for help
diff --git a/docs/content/docs/example-usecases/meta.json b/docs/content/examples/example-usecases/meta.json
similarity index 100%
rename from docs/content/docs/example-usecases/meta.json
rename to docs/content/examples/example-usecases/meta.json
diff --git a/docs/content/examples/example-usecases/post-event-contact-export.mdx b/docs/content/examples/example-usecases/post-event-contact-export.mdx
new file mode 100644
index 0000000000..7eaef59662
--- /dev/null
+++ b/docs/content/examples/example-usecases/post-event-contact-export.mdx
@@ -0,0 +1,482 @@
+---
+title: Post-Event Contact Export
+description: Run overnight contact extraction from LinkedIn, X, or other social platforms after networking events
+---
+
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+## Overview
+
+After networking events, you need to export new connections from LinkedIn, X, or other platforms into your CRM. This automation handles it for you.
+
+**The workflow**: Kick off the script after an event and let it run overnight. Wake up to a clean CSV ready for your CRM or email tool.
+
+This example focuses on LinkedIn but works across platforms. It uses [Cua Computer Framework](/computer-sdk/computers) to interact with web interfaces and [Agent Loops](/agent-sdk/agent-loops) to iterate through connections with conversation history.
+
+### Why Cua is Perfect for This
+
+**Cua's VMs save your session data**, bypassing bot detection entirely:
+
+- **Log in once manually** through the VM browser
+- **Session persists** - you appear as a regular user, not a bot
+- **No captchas** - the platform treats automation like normal browsing
+- **No login code** - script doesn't handle authentication
+- **Run overnight** - kick off and forget
+
+Traditional web scraping triggers anti-bot measures immediately. Cua's approach works across all platforms.
+
+### What You Get
+
+The script generates two files with your extracted connections:
+
+**CSV Export** (`linkedin_connections_20250116_143022.csv`):
+
+```csv
+first,last,role,company,met_at,linkedin
+John,Smith,Software Engineer,Acme Corp,Google Devfest Toronto,https://www.linkedin.com/in/johnsmith
+Sarah,Johnson,Product Manager,Tech Inc,Google Devfest Toronto,https://www.linkedin.com/in/sarahjohnson
+```
+
+**Messaging Links** (`linkedin_messaging_links_20250116_143022.txt`):
+
+```
+LinkedIn Messaging Compose Links
+================================================================================
+
+1. https://www.linkedin.com/messaging/compose/?recipient=johnsmith
+2. https://www.linkedin.com/messaging/compose/?recipient=sarahjohnson
+```
+
+---
+
+<Steps>
+
+<Step>
+
+### Set Up Your Environment
+
+First, install the required dependencies:
+
+Create a `requirements.txt` file:
+
+```text
+cua-agent
+cua-computer
+python-dotenv>=1.0.0
+```
+
+Install the dependencies using uv (recommended):
+
+```bash
+uv pip install -r requirements.txt
+```
+
+Or using pip:
+
+```bash
+pip install -r requirements.txt
+```
+
+Create a `.env` file with your API keys:
+
+```text
+ANTHROPIC_API_KEY=your-anthropic-api-key # optional, BYOK. By default, this cookbook uses the Cua VLM Router
+CUA_API_KEY=sk_cua-api01...
+CUA_CONTAINER_NAME=m-linux-...
+```
+
+Finally, setup your sandbox. Refer to the [quickstart guide](https://cua.ai/docs/get-started/quickstart) on how to setup the computer environment.
+
+</Step>
+
+<Step>
+
+### Log Into LinkedIn Manually
+
+**Important**: Before running the script, manually log into LinkedIn through your VM:
+
+1. Access your VM through the Cua dashboard
+2. Open a browser and navigate to LinkedIn
+3. Log in with your credentials (handle any captchas manually)
+4. Close the browser but leave the VM running
+5. Your session is now saved and ready for automation!
+
+This one-time manual login bypasses all bot detection.
+
+</Step>
+
+<Step>
+
+### Configure and Create Your Script
+
+Create a Python file (e.g., `contact_export.py`). You can customize:
+
+```python
+# Where you met these connections (automatically added to CSV)
+MET_AT_REASON = "Google Devfest Toronto"
+
+# Number of contacts to extract (in the main loop)
+for contact_num in range(1, 21): # Change 21 to extract more/fewer contacts
+```
+
+Select your environment:
+
+<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS Sandbox', 'Windows Sandbox']}>
+ <Tab value="Cloud Sandbox">
+
+```python
+import asyncio
+import csv
+import logging
+import os
+import signal
+import traceback
+from datetime import datetime
+
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Configuration: Define where you met these connections
+MET_AT_REASON = "Google Devfest Toronto"
+
+def handle_sigint(sig, frame):
+ print("\n\nExecution interrupted by user. Exiting gracefully...")
+ exit(0)
+
+def extract_public_id_from_linkedin_url(linkedin_url):
+ """Extract public ID from LinkedIn profile URL."""
+ if not linkedin_url:
+ return None
+
+ url = linkedin_url.split('?')[0].rstrip('/')
+
+ if '/in/' in url:
+ public_id = url.split('/in/')[-1]
+ return public_id
+
+ return None
+
+def extract_contact_from_response(result_output):
+ """
+ Extract contact information from agent's response.
+ Expects format:
+ FIRST: value
+ LAST: value
+ ROLE: value
+ COMPANY: value
+ LINKEDIN: value
+ """
+ contact = {
+ 'first': '',
+ 'last': '',
+ 'role': '',
+ 'company': '',
+ 'met_at': MET_AT_REASON,
+ 'linkedin': ''
+ }
+
+ for item in result_output:
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for content_part in content:
+ text = content_part.get("text", "")
+ if text:
+ for line in text.split('\n'):
+ line = line.strip()
+ line_upper = line.upper()
+
+ if line_upper.startswith("FIRST:"):
+ value = line[6:].strip()
+ if value and value.upper() != "N/A":
+ contact['first'] = value
+ elif line_upper.startswith("LAST:"):
+ value = line[5:].strip()
+ if value and value.upper() != "N/A":
+ contact['last'] = value
+ elif line_upper.startswith("ROLE:"):
+ value = line[5:].strip()
+ if value and value.upper() != "N/A":
+ contact['role'] = value
+ elif line_upper.startswith("COMPANY:"):
+ value = line[8:].strip()
+ if value and value.upper() != "N/A":
+ contact['company'] = value
+ elif line_upper.startswith("LINKEDIN:"):
+ value = line[9:].strip()
+ if value and value.upper() != "N/A":
+ contact['linkedin'] = value
+
+ return contact
+
+async def scrape_linkedin_connections():
+ """Scrape LinkedIn connections and export to CSV."""
+
+ timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+ csv_filename = f"linkedin_connections_{timestamp}.csv"
+ csv_path = os.path.join(os.getcwd(), csv_filename)
+
+ # Initialize CSV file
+ with open(csv_path, 'w', newline='', encoding='utf-8') as csvfile:
+ writer = csv.DictWriter(csvfile, fieldnames=['first', 'last', 'role', 'company', 'met_at', 'linkedin'])
+ writer.writeheader()
+
+ print(f"\n🚀 Starting LinkedIn connections scraper")
+ print(f"📁 Output file: {csv_path}")
+ print(f"📍 Met at: {MET_AT_REASON}")
+ print("=" * 80)
+
+ try:
+ async with Computer(
+ os_type="linux",
+ provider_type=VMProviderType.CLOUD,
+ name=os.environ["CUA_CONTAINER_NAME"], # Your sandbox name
+ api_key=os.environ["CUA_API_KEY"],
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=True,
+ max_trajectory_budget=10.0,
+ )
+
+ history = []
+
+ # Task 1: Navigate to LinkedIn connections page
+ navigation_task = (
+ "STEP 1 - NAVIGATE TO LINKEDIN CONNECTIONS PAGE:\n"
+ "1. Open a web browser (Chrome or Firefox)\n"
+ "2. Navigate to https://www.linkedin.com/mynetwork/invite-connect/connections/\n"
+ "3. Wait for the page to fully load\n"
+ "4. Confirm you can see the list of connections\n"
+ "5. Ready to start extracting contacts"
+ )
+
+ print(f"\n[Task 1/21] Navigating to LinkedIn...")
+ history.append({"role": "user", "content": navigation_task})
+
+ async for result in agent.run(history, stream=False):
+ history += result.get("output", [])
+
+ print(f"✅ Navigation completed\n")
+
+ # Extract 20 contacts
+ contacts_extracted = 0
+ linkedin_urls = []
+ previous_contact_name = None
+
+ for contact_num in range(1, 21):
+ # Build extraction task
+ if contact_num == 1:
+ extraction_task = (
+ f"STEP {contact_num + 1} - EXTRACT CONTACT {contact_num} OF 20:\n"
+ f"1. Click on the first connection's profile\n"
+ f"2. Extract: FIRST, LAST, ROLE, COMPANY, LINKEDIN URL\n"
+ f"3. Return in exact format:\n"
+ f"FIRST: [value]\n"
+ f"LAST: [value]\n"
+ f"ROLE: [value]\n"
+ f"COMPANY: [value]\n"
+ f"LINKEDIN: [value]\n"
+ f"4. Navigate back to connections list"
+ )
+ else:
+ extraction_task = (
+ f"STEP {contact_num + 1} - EXTRACT CONTACT {contact_num} OF 20:\n"
+ f"1. Find '{previous_contact_name}' in the list\n"
+ f"2. Click on the contact BELOW them\n"
+ f"3. Extract: FIRST, LAST, ROLE, COMPANY, LINKEDIN URL\n"
+ f"4. Return in exact format:\n"
+ f"FIRST: [value]\n"
+ f"LAST: [value]\n"
+ f"ROLE: [value]\n"
+ f"COMPANY: [value]\n"
+ f"LINKEDIN: [value]\n"
+ f"5. Navigate back"
+ )
+
+ print(f"[Task {contact_num + 1}/21] Extracting contact {contact_num}/20...")
+ history.append({"role": "user", "content": extraction_task})
+
+ all_output = []
+ async for result in agent.run(history, stream=False):
+ output = result.get("output", [])
+ history += output
+ all_output.extend(output)
+
+ contact_data = extract_contact_from_response(all_output)
+
+ has_name = bool(contact_data['first'] and contact_data['last'])
+ has_linkedin = bool(contact_data['linkedin'] and 'linkedin.com' in contact_data['linkedin'])
+
+ if has_name or has_linkedin:
+ with open(csv_path, 'a', newline='', encoding='utf-8') as csvfile:
+ writer = csv.DictWriter(csvfile, fieldnames=['first', 'last', 'role', 'company', 'met_at', 'linkedin'])
+ writer.writerow(contact_data)
+ contacts_extracted += 1
+
+ if contact_data['linkedin']:
+ linkedin_urls.append(contact_data['linkedin'])
+
+ if has_name:
+ previous_contact_name = f"{contact_data['first']} {contact_data['last']}".strip()
+
+ name_str = f"{contact_data['first']} {contact_data['last']}" if has_name else "[No name]"
+ print(f"✅ Contact {contact_num}/20 saved: {name_str}")
+ else:
+ print(f"⚠️ Could not extract valid data for contact {contact_num}")
+
+ if contact_num % 5 == 0:
+ print(f"\n📈 Progress: {contacts_extracted}/{contact_num} contacts extracted\n")
+
+ # Create messaging links file
+ messaging_filename = f"linkedin_messaging_links_{timestamp}.txt"
+ messaging_path = os.path.join(os.getcwd(), messaging_filename)
+
+ with open(messaging_path, 'w', encoding='utf-8') as txtfile:
+ txtfile.write("LinkedIn Messaging Compose Links\n")
+ txtfile.write("=" * 80 + "\n\n")
+
+ for i, linkedin_url in enumerate(linkedin_urls, 1):
+ public_id = extract_public_id_from_linkedin_url(linkedin_url)
+ if public_id:
+ messaging_url = f"https://www.linkedin.com/messaging/compose/?recipient={public_id}"
+ txtfile.write(f"{i}. {messaging_url}\n")
+
+ print("\n" + "="*80)
+ print("🎉 All tasks completed!")
+ print(f"📁 CSV file saved to: {csv_path}")
+ print(f"📊 Total contacts extracted: {contacts_extracted}/20")
+ print(f"💬 Messaging links saved to: {messaging_path}")
+ print("="*80)
+
+ except Exception as e:
+ print(f"\n❌ Error: {e}")
+ traceback.print_exc()
+ raise
+
+def main():
+ try:
+ load_dotenv()
+
+ if "ANTHROPIC_API_KEY" not in os.environ:
+ raise RuntimeError("Please set ANTHROPIC_API_KEY in .env")
+
+ if "CUA_API_KEY" not in os.environ:
+ raise RuntimeError("Please set CUA_API_KEY in .env")
+
+ if "CUA_CONTAINER_NAME" not in os.environ:
+ raise RuntimeError("Please set CUA_CONTAINER_NAME in .env")
+
+ signal.signal(signal.SIGINT, handle_sigint)
+
+ asyncio.run(scrape_linkedin_connections())
+
+ except Exception as e:
+ print(f"\n❌ Error: {e}")
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ main()
+```
+
+ </Tab>
+ <Tab value="Linux on Docker">
+
+```python
+# Same code as Cloud Sandbox, but change Computer initialization to:
+async with Computer(
+ os_type="linux",
+ provider_type=VMProviderType.DOCKER,
+ image="trycua/cua-xfce:latest",
+ verbosity=logging.INFO,
+) as computer:
+```
+
+And remove the `CUA_API_KEY` and `CUA_CONTAINER_NAME` requirements from `.env` and the validation checks.
+
+ </Tab>
+ <Tab value="macOS Sandbox">
+
+```python
+# Same code as Cloud Sandbox, but change Computer initialization to:
+async with Computer(
+ os_type="macos",
+ provider_type=VMProviderType.LUME,
+ name="macos-sequoia-cua:latest",
+ verbosity=logging.INFO,
+) as computer:
+```
+
+And remove the `CUA_API_KEY` and `CUA_CONTAINER_NAME` requirements from `.env` and the validation checks.
+
+ </Tab>
+ <Tab value="Windows Sandbox">
+
+```python
+# Same code as Cloud Sandbox, but change Computer initialization to:
+async with Computer(
+ os_type="windows",
+ provider_type=VMProviderType.WINDOWS_SANDBOX,
+ verbosity=logging.INFO,
+) as computer:
+```
+
+And remove the `CUA_API_KEY` and `CUA_CONTAINER_NAME` requirements from `.env` and the validation checks.
+
+ </Tab>
+</Tabs>
+
+</Step>
+
+<Step>
+
+### Run Your Script
+
+Execute your contact extraction automation:
+
+```bash
+python contact_export.py
+```
+
+The agent will:
+
+1. Navigate to your LinkedIn connections page
+2. Extract data from 20 contacts (first name, last name, role, company, LinkedIn URL)
+3. Save contacts to a timestamped CSV file
+4. Generate messaging compose links for easy follow-up
+
+Monitor the output to see the agent's progress. The script will show a progress update every 5 contacts.
+
+</Step>
+
+</Steps>
+
+---
+
+## How It Works
+
+This script demonstrates a practical workflow for extracting LinkedIn connection data:
+
+1. **Session Persistence** - Manually log into LinkedIn through the VM once, and the VM saves your session
+2. **Navigation** - The script navigates to your connections page using your saved authenticated session
+3. **Data Extraction** - For each contact, the agent clicks their profile, extracts data, and navigates back
+4. **Python Processing** - Python parses responses, validates data, and writes to CSV incrementally
+5. **Output Files** - Generates a CSV with contact data and a text file with messaging URLs
+
+## Next Steps
+
+- Learn more about [Cua Computer Framework](/computer-sdk/computers) and [Computer Commands](/computer-sdk/commands)
+- Read about [Agent Loops](/agent-sdk/agent-loops), [Tools](/agent-sdk/custom-tools), and [Supported Model Providers](/agent-sdk/supported-model-providers/)
+- Experiment with different [Models and Providers](/agent-sdk/supported-model-providers/)
+- Adapt this script for other platforms (Twitter/X, email extraction, etc.)
+- Join our [Discord community](https://discord.com/invite/mVnXXpdE85) for help
diff --git a/docs/content/examples/example-usecases/windows-app-behind-vpn.mdx b/docs/content/examples/example-usecases/windows-app-behind-vpn.mdx
new file mode 100644
index 0000000000..7779a40fed
--- /dev/null
+++ b/docs/content/examples/example-usecases/windows-app-behind-vpn.mdx
@@ -0,0 +1,629 @@
+---
+title: Windows App behind VPN
+description: Automate legacy Windows desktop applications behind VPN with Cua
+---
+
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+## Overview
+
+This guide demonstrates how to automate Windows desktop applications (like eGecko HR/payroll systems) that run behind corporate VPN. This is a common enterprise scenario where legacy desktop applications require manual data entry, report generation, or workflow execution.
+
+**Use cases:**
+
+- HR/payroll processing (employee onboarding, payroll runs, benefits administration)
+- Desktop ERP systems behind corporate networks
+- Legacy financial applications requiring VPN access
+- Compliance reporting from on-premise systems
+
+**Architecture:**
+
+- Client-side Cua agent (Python SDK or Playground UI)
+- Windows VM/Sandbox with VPN client configured
+- RDP/remote desktop connection to target environment
+- Desktop application automation via computer vision and UI control
+
+<Callout type="info">
+ **Production Deployment**: For production use, consider workflow mining and custom finetuning to
+ create vertical-specific actions (e.g., "Run payroll", "Onboard employee") instead of generic UI
+ automation. This provides better audit trails and higher success rates.
+</Callout>
+
+---
+
+## Video Demo
+
+<div className="rounded-lg border bg-card text-card-foreground shadow-sm p-4 mb-6">
+ <video
+ src="https://github.com/user-attachments/assets/8ab07646-6018-4128-87ce-53180cfea696"
+ controls
+ className="w-full rounded"
+ >
+ Your browser does not support the video tag.
+ </video>
+ <div className="text-sm text-muted-foreground mt-2">
+ Demo showing Cua automating an eGecko-like desktop application on Windows behind AWS VPN
+ </div>
+</div>
+
+---
+
+<Steps>
+
+<Step>
+
+### Set Up Your Environment
+
+Install the required dependencies:
+
+Create a `requirements.txt` file:
+
+```text
+cua-agent
+cua-computer
+python-dotenv>=1.0.0
+```
+
+Install the dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Create a `.env` file with your API keys:
+
+```text
+ANTHROPIC_API_KEY=your-anthropic-api-key
+CUA_API_KEY=sk_cua-api01...
+CUA_SANDBOX_NAME=your-windows-sandbox
+```
+
+</Step>
+
+<Step>
+
+### Configure Windows Sandbox with VPN
+
+<Tabs items={['Cloud Sandbox (Recommended)', 'Windows Sandbox', 'Self-Hosted VM']}>
+ <Tab value="Cloud Sandbox (Recommended)">
+
+For enterprise deployments, use Cua Cloud Sandbox with pre-configured VPN:
+
+1. Go to [cua.ai/signin](https://cua.ai/signin)
+2. Navigate to **Dashboard > Containers > Create Instance**
+3. Create a **Windows** sandbox (Medium or Large for desktop apps)
+4. Configure VPN settings:
+ - Upload your AWS VPN Client configuration (`.ovpn` file)
+ - Or configure VPN credentials directly in the dashboard
+5. Note your sandbox name and API key
+
+Your Windows sandbox will launch with VPN automatically connected.
+
+ </Tab>
+ <Tab value="Windows Sandbox">
+
+For local development on Windows 10 Pro/Enterprise or Windows 11:
+
+1. Enable [Windows Sandbox](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-install)
+2. Install the `pywinsandbox` dependency:
+ ```bash
+ pip install -U git+git://github.com/karkason/pywinsandbox.git
+ ```
+3. Create a VPN setup script that runs on sandbox startup
+4. Configure your desktop application installation within the sandbox
+
+<Callout type="warn">
+ **Manual VPN Setup**: Windows Sandbox requires manual VPN configuration each time it starts. For
+ production use, consider Cloud Sandbox or self-hosted VMs with persistent VPN connections.
+</Callout>
+
+ </Tab>
+ <Tab value="Self-Hosted VM">
+
+For self-managed infrastructure:
+
+1. Deploy Windows VM on your preferred cloud (AWS, Azure, GCP)
+2. Install and configure VPN client (AWS VPN Client, OpenVPN, etc.)
+3. Install target desktop application and any dependencies
+4. Install `cua-computer-server`:
+ ```bash
+ pip install cua-computer-server
+ python -m computer_server
+ ```
+5. Configure firewall rules to allow Cua agent connections
+
+ </Tab>
+</Tabs>
+
+</Step>
+
+<Step>
+
+### Create Your Automation Script
+
+Create a Python file (e.g., `hr_automation.py`):
+
+<Tabs items={['Cloud Sandbox', 'Windows Sandbox', 'Self-Hosted']}>
+ <Tab value="Cloud Sandbox">
+
+```python
+import asyncio
+import logging
+import os
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+load_dotenv()
+
+async def automate_hr_workflow():
+ """
+ Automate HR/payroll desktop application workflow.
+
+ This example demonstrates:
+ - Launching Windows desktop application
+ - Navigating complex desktop UI
+ - Data entry and form filling
+ - Report generation and export
+ """
+ try:
+ # Connect to Windows Cloud Sandbox with VPN
+ async with Computer(
+ os_type="windows",
+ provider_type=VMProviderType.CLOUD,
+ name=os.environ["CUA_SANDBOX_NAME"],
+ api_key=os.environ["CUA_API_KEY"],
+ verbosity=logging.INFO,
+ ) as computer:
+
+ # Configure agent with specialized instructions
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=True,
+ max_trajectory_budget=10.0,
+ instructions="""
+You are automating a Windows desktop HR/payroll application.
+
+IMPORTANT GUIDELINES:
+- Always wait for windows and dialogs to fully load before interacting
+- Look for loading indicators and wait for them to disappear
+- Verify each action by checking on-screen confirmation messages
+- If a button or field is not visible, try scrolling or navigating tabs
+- Desktop apps often have nested menus - explore systematically
+- Save work frequently using File > Save or Ctrl+S
+- Before closing, always verify changes were saved
+
+COMMON UI PATTERNS:
+- Menu bar navigation (File, Edit, View, etc.)
+- Ribbon interfaces with tabs
+- Modal dialogs that block interaction
+- Data grids/tables for viewing records
+- Form fields with validation
+- Status bars showing operation progress
+ """.strip()
+ )
+
+ # Define workflow tasks
+ tasks = [
+ "Launch the HR application from the desktop or start menu",
+ "Log in with the credentials shown in credentials.txt on the desktop",
+ "Navigate to Employee Management section",
+ "Create a new employee record with information from new_hire.xlsx on desktop",
+ "Verify the employee was created successfully by searching for their name",
+ "Generate an onboarding report for the new employee",
+ "Export the report as PDF to the desktop",
+ "Log out of the application"
+ ]
+
+ history = []
+
+ for task in tasks:
+ logger.info(f"\n{'='*60}")
+ logger.info(f"Task: {task}")
+ logger.info(f"{'='*60}\n")
+
+ history.append({"role": "user", "content": task})
+
+ async for result in agent.run(history):
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for block in content:
+ if block.get("type") == "text":
+ response = block.get("text", "")
+ logger.info(f"Agent: {response}")
+ history.append({"role": "assistant", "content": response})
+
+ logger.info("\nTask completed. Moving to next task...\n")
+
+ logger.info("\n" + "="*60)
+ logger.info("All tasks completed successfully!")
+ logger.info("="*60)
+
+ except Exception as e:
+ logger.error(f"Error during automation: {e}")
+ import traceback
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ asyncio.run(automate_hr_workflow())
+```
+
+ </Tab>
+ <Tab value="Windows Sandbox">
+
+```python
+import asyncio
+import logging
+import os
+from agent import ComputerAgent
+from computer import Computer, VMProviderType
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+load_dotenv()
+
+async def automate_hr_workflow():
+ try:
+ # Connect to Windows Sandbox
+ async with Computer(
+ os_type="windows",
+ provider_type=VMProviderType.WINDOWS_SANDBOX,
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=True,
+ max_trajectory_budget=10.0,
+ instructions="""
+You are automating a Windows desktop HR/payroll application.
+
+IMPORTANT GUIDELINES:
+- Always wait for windows and dialogs to fully load before interacting
+- Verify each action by checking on-screen confirmation messages
+- Desktop apps often have nested menus - explore systematically
+- Save work frequently using File > Save or Ctrl+S
+ """.strip()
+ )
+
+ tasks = [
+ "Launch the HR application from the desktop",
+ "Log in with credentials from credentials.txt on desktop",
+ "Navigate to Employee Management and create new employee from new_hire.xlsx",
+ "Generate and export onboarding report as PDF",
+ "Log out of the application"
+ ]
+
+ history = []
+
+ for task in tasks:
+ logger.info(f"\nTask: {task}")
+ history.append({"role": "user", "content": task})
+
+ async for result in agent.run(history):
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for block in content:
+ if block.get("type") == "text":
+ response = block.get("text", "")
+ logger.info(f"Agent: {response}")
+ history.append({"role": "assistant", "content": response})
+
+ logger.info("\nAll tasks completed!")
+
+ except Exception as e:
+ logger.error(f"Error: {e}")
+ import traceback
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ asyncio.run(automate_hr_workflow())
+```
+
+ </Tab>
+ <Tab value="Self-Hosted">
+
+```python
+import asyncio
+import logging
+import os
+from agent import ComputerAgent
+from computer import Computer
+from dotenv import load_dotenv
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+load_dotenv()
+
+async def automate_hr_workflow():
+ try:
+ # Connect to self-hosted Windows VM running computer-server
+ async with Computer(
+ use_host_computer_server=True,
+ base_url="http://your-windows-vm-ip:5757", # Update with your VM IP
+ verbosity=logging.INFO,
+ ) as computer:
+
+ agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ only_n_most_recent_images=3,
+ verbosity=logging.INFO,
+ trajectory_dir="trajectories",
+ use_prompt_caching=True,
+ max_trajectory_budget=10.0,
+ instructions="""
+You are automating a Windows desktop HR/payroll application.
+
+IMPORTANT GUIDELINES:
+- Always wait for windows and dialogs to fully load before interacting
+- Verify each action by checking on-screen confirmation messages
+- Save work frequently using File > Save or Ctrl+S
+ """.strip()
+ )
+
+ tasks = [
+ "Launch the HR application",
+ "Log in with provided credentials",
+ "Complete the required HR workflow",
+ "Generate and export report",
+ "Log out"
+ ]
+
+ history = []
+
+ for task in tasks:
+ logger.info(f"\nTask: {task}")
+ history.append({"role": "user", "content": task})
+
+ async for result in agent.run(history):
+ for item in result.get("output", []):
+ if item.get("type") == "message":
+ content = item.get("content", [])
+ for block in content:
+ if block.get("type") == "text":
+ response = block.get("text", "")
+ logger.info(f"Agent: {response}")
+ history.append({"role": "assistant", "content": response})
+
+ logger.info("\nAll tasks completed!")
+
+ except Exception as e:
+ logger.error(f"Error: {e}")
+ import traceback
+ traceback.print_exc()
+
+if __name__ == "__main__":
+ asyncio.run(automate_hr_workflow())
+```
+
+ </Tab>
+</Tabs>
+
+</Step>
+
+<Step>
+
+### Run Your Automation
+
+Execute the script:
+
+```bash
+python hr_automation.py
+```
+
+The agent will:
+
+1. Connect to your Windows environment (with VPN if configured)
+2. Launch and navigate the desktop application
+3. Execute each workflow step sequentially
+4. Verify actions and handle errors
+5. Save trajectory logs for audit and debugging
+
+Monitor the console output to see the agent's progress through each task.
+
+</Step>
+
+</Steps>
+
+---
+
+## Key Configuration Options
+
+### Agent Instructions
+
+The `instructions` parameter is critical for reliable desktop automation:
+
+```python
+instructions="""
+You are automating a Windows desktop HR/payroll application.
+
+IMPORTANT GUIDELINES:
+- Always wait for windows and dialogs to fully load before interacting
+- Look for loading indicators and wait for them to disappear
+- Verify each action by checking on-screen confirmation messages
+- If a button or field is not visible, try scrolling or navigating tabs
+- Desktop apps often have nested menus - explore systematically
+- Save work frequently using File > Save or Ctrl+S
+- Before closing, always verify changes were saved
+
+COMMON UI PATTERNS:
+- Menu bar navigation (File, Edit, View, etc.)
+- Ribbon interfaces with tabs
+- Modal dialogs that block interaction
+- Data grids/tables for viewing records
+- Form fields with validation
+- Status bars showing operation progress
+
+APPLICATION-SPECIFIC:
+- Login is at top-left corner
+- Employee records are under "HR Management" > "Employees"
+- Reports are generated via "Tools" > "Reports" > "Generate"
+- Always click "Save" before navigating away from a form
+""".strip()
+```
+
+### Budget Management
+
+For long-running workflows, adjust budget limits:
+
+```python
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ max_trajectory_budget=20.0, # Increase for complex workflows
+ # ... other params
+)
+```
+
+### Image Retention
+
+Balance context and cost by retaining only recent screenshots:
+
+```python
+agent = ComputerAgent(
+ # ...
+ only_n_most_recent_images=3, # Keep last 3 screenshots
+ # ...
+)
+```
+
+---
+
+## Production Considerations
+
+<Callout type="warn" title="Production Deployment">
+ For enterprise production deployments, consider these additional steps:
+</Callout>
+
+### 1. Workflow Mining
+
+Before deploying, analyze your actual workflows:
+
+- Record user interactions with the application
+- Identify common patterns and edge cases
+- Map out decision trees and validation requirements
+- Document application-specific quirks and timing issues
+
+### 2. Custom Finetuning
+
+Create vertical-specific actions instead of generic UI automation:
+
+```python
+# Instead of generic steps:
+tasks = ["Click login", "Type username", "Type password", "Click submit"]
+
+# Create semantic actions:
+tasks = ["onboard_employee", "run_payroll", "generate_compliance_report"]
+```
+
+This provides:
+
+- Better audit trails
+- Approval gates at business logic level
+- Higher success rates
+- Easier maintenance and updates
+
+### 3. Human-in-the-Loop
+
+Add approval gates for critical operations:
+
+```python
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ # Add human approval callback for sensitive operations
+ callbacks=[ApprovalCallback(require_approval_for=["payroll", "termination"])]
+)
+```
+
+### 4. Deployment Options
+
+Choose your deployment model:
+
+**Managed (Recommended)**
+
+- Cua hosts Windows sandboxes, VPN/RDP stack, and agent runtime
+- You get UI/API endpoints for triggering workflows
+- Automatic scaling, monitoring, and maintenance
+- SLA guarantees and enterprise support
+
+**Self-Hosted**
+
+- You manage Windows VMs, VPN infrastructure, and agent deployment
+- Full control over data and security
+- Custom network configurations
+- On-premise or your preferred cloud
+
+---
+
+## Troubleshooting
+
+### VPN Connection Issues
+
+If the agent cannot reach the application:
+
+1. Verify VPN is connected: Check VPN client status in the Windows sandbox
+2. Test network connectivity: Try pinging internal resources
+3. Check firewall rules: Ensure RDP and application ports are open
+4. Review VPN logs: Look for authentication or routing errors
+
+### Application Not Launching
+
+If the desktop application fails to start:
+
+1. Verify installation: Check the application is installed in the sandbox
+2. Check dependencies: Ensure all required DLLs and frameworks are present
+3. Review permissions: Application may require admin rights
+4. Check logs: Look for error messages in Windows Event Viewer
+
+### UI Element Not Found
+
+If the agent cannot find buttons or fields:
+
+1. Increase wait times: Some applications load slowly
+2. Check screen resolution: UI elements may be off-screen
+3. Verify DPI scaling: High DPI settings can affect element positions
+4. Update instructions: Provide more specific navigation guidance
+
+### Cost Management
+
+If costs are higher than expected:
+
+1. Reduce `max_trajectory_budget`
+2. Decrease `only_n_most_recent_images`
+3. Use prompt caching: Set `use_prompt_caching=True`
+4. Optimize task descriptions: Be more specific to reduce retry attempts
+
+---
+
+## Next Steps
+
+- **Explore Custom Tools**: Learn how to create [Custom Tools](/agent-sdk/custom-tools) for application-specific actions
+- **Implement Callbacks**: Add [Monitoring and Logging](/agent-sdk/callbacks) for production workflows
+- **Join community**: Get help in our [Discord](https://discord.com/invite/mVnXXpdE85)
+
+---
+
+## Related Examples
+
+- [Form Filling](/example-usecases/form-filling) - Web form automation
+- [Post-Event Contact Export](/example-usecases/post-event-contact-export) - Data extraction workflows
+- [Custom Tools](/agent-sdk/custom-tools) - Building application-specific functions
diff --git a/docs/content/examples/index.mdx b/docs/content/examples/index.mdx
new file mode 100644
index 0000000000..c68a56d119
--- /dev/null
+++ b/docs/content/examples/index.mdx
@@ -0,0 +1,48 @@
+---
+title: Examples
+description: Real-world examples of building with Cua
+---
+
+import { Code2, Monitor, FileText, Globe } from 'lucide-react';
+
+<div className="not-prose -mt-2 mb-6">
+ <p className="text-fd-primary font-semibold text-sm mb-1">Examples</p>
+ <h1 className="text-3xl font-bold tracking-tight md:text-4xl">Real-World Examples</h1>
+</div>
+
+Explore practical examples and use cases built with Cua. These examples demonstrate how to build computer-use agents for various automation tasks.
+
+## Featured Examples
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mt-6">
+ <Card
+ icon={<Monitor className="w-4 h-4" />}
+ href="/examples/example-usecases/windows-app-behind-vpn"
+ title="Windows App Behind VPN"
+ description="Automate legacy Windows applications securely behind VPN"
+ />
+ <Card
+ icon={<FileText className="w-4 h-4" />}
+ href="/examples/example-usecases/form-filling"
+ title="PDF to Form Automation"
+ description="Enhance interactions between form filling and local file systems"
+ />
+ <Card
+ icon={<Globe className="w-4 h-4" />}
+ href="/examples/example-usecases/post-event-contact-export"
+ title="Contact Export"
+ description="Export contacts from post-event platforms automatically"
+ />
+ <Card
+ icon={<Code2 className="w-4 h-4" />}
+ href="/examples/example-usecases/gemini-complex-ui-navigation"
+ title="Complex UI Navigation"
+ description="Navigate complex UIs with Gemini vision capabilities"
+ />
+</div>
+
+## More Resources
+
+- Check out our [GitHub examples](https://github.com/trycua/cua/tree/main/examples) for code samples
+- Explore [Jupyter notebooks](https://github.com/trycua/cua/tree/main/notebooks) for interactive tutorials
+- Read our [blog tutorials](https://cua.ai/blog) for step-by-step guides
diff --git a/docs/content/examples/meta.json b/docs/content/examples/meta.json
new file mode 100644
index 0000000000..af22048108
--- /dev/null
+++ b/docs/content/examples/meta.json
@@ -0,0 +1,10 @@
+{
+ "title": "Examples",
+ "description": "Example use cases and cookbook",
+ "root": true,
+ "defaultOpen": true,
+ "pages": [
+ "index",
+ "...example-usecases"
+ ]
+}
diff --git a/docs/content/docs/get-started/meta.json b/docs/content/guide/get-started/meta.json
similarity index 75%
rename from docs/content/docs/get-started/meta.json
rename to docs/content/guide/get-started/meta.json
index a14e8acb19..f7f9fac24b 100644
--- a/docs/content/docs/get-started/meta.json
+++ b/docs/content/guide/get-started/meta.json
@@ -3,5 +3,5 @@
"description": "Get started with Cua",
"defaultOpen": true,
"icon": "Rocket",
- "pages": ["../index", "quickstart"]
+ "pages": ["quickstart"]
}
diff --git a/docs/content/docs/get-started/quickstart.mdx b/docs/content/guide/get-started/quickstart.mdx
similarity index 100%
rename from docs/content/docs/get-started/quickstart.mdx
rename to docs/content/guide/get-started/quickstart.mdx
diff --git a/docs/content/guide/index.mdx b/docs/content/guide/index.mdx
new file mode 100644
index 0000000000..2306c7009c
--- /dev/null
+++ b/docs/content/guide/index.mdx
@@ -0,0 +1,60 @@
+---
+title: Guide
+description: Get started with Cua
+---
+
+import { Monitor, Code, BookOpen, Zap, Bot, Boxes, Rocket } from 'lucide-react';
+
+<div className="not-prose -mt-2 mb-6">
+ <p className="text-fd-primary font-semibold text-sm mb-1">Welcome</p>
+ <h1 className="text-3xl font-bold tracking-tight md:text-4xl">Welcome to Cua</h1>
+</div>
+
+**Cua** is an open-source framework for building and evaluating Computer-Use Agents - AI systems that autonomously interact with computer interfaces by understanding visual elements and executing actions.
+
+<div className="not-prose relative rounded-xl overflow-hidden my-8 w-full">
+ <img src="/docs/img/hero.png" alt="Cua" className="w-full h-auto rounded-xl" />
+</div>
+
+## What is a Computer-Use Agent?
+
+Computer-Use Agents (CUAs) are AI systems that can autonomously interact with computer interfaces through visual understanding and action execution. They work by capturing screenshots, feeding them to a vision-language model (VLM), and letting the model determine the next action to take - such as clicking, typing, or scrolling - in a continuous loop until the task is complete.
+
+## What is a Computer-Use Sandbox?
+
+Computer-Use Sandboxes are isolated, controlled environments where AI agents can safely interact with computer interfaces. They provide a secure execution space for agents to perform actions such as clicking, typing, and running code, test automation workflows, and learn from interactions without affecting production systems.
+
+## Key Features
+
+With **Cua Computer Framework**, you can:
+
+- Automate **Windows, Linux, and macOS** sandboxes with a consistent, pyautogui-like API
+- Create & manage sandboxes locally or using **Cua Cloud**
+
+With **Cua Agent Framework**, you can:
+
+- Run computer-use models with a consistent schema
+- Benchmark on **OSWorld-Verified**, **SheetBench-V2**, and **ScreenSpot**
+- Combine UI grounding models with any LLM using **composed agents**
+- Use **100+ models** via API or local inference (Claude, GPT-4, Gemini, Ollama, MLX)
+
+## Get Started
+
+Follow the [Quickstart guide](/guide/get-started/quickstart) for step-by-step setup with Python or TypeScript.
+
+Check out our [tutorials](https://cua.ai/blog), [examples](https://github.com/trycua/cua/tree/main/examples), and [notebooks](https://github.com/trycua/cua/tree/main/notebooks) to start building with Cua today.
+
+<div className="grid grid-cols-2 md:grid-cols-4 gap-2 mt-4 text-sm">
+ <Card icon={<Rocket className="w-4 h-4" />} href="/guide/get-started/quickstart" title="Quickstart" />
+ <Card icon={<Zap className="w-4 h-4" />} href="/reference/agent-sdk/agent-loops" title="Agent Loops" />
+ <Card
+ icon={<BookOpen className="w-4 h-4" />}
+ href="/reference/computer-sdk/computers"
+ title="Cua Computer"
+ />
+ <Card
+ icon={<Monitor className="w-4 h-4" />}
+ href="/examples/example-usecases/form-filling"
+ title="Examples"
+ />
+</div>
diff --git a/docs/content/guide/introduction.mdx b/docs/content/guide/introduction.mdx
new file mode 100644
index 0000000000..f9dbeb22c1
--- /dev/null
+++ b/docs/content/guide/introduction.mdx
@@ -0,0 +1,59 @@
+---
+title: Introduction
+---
+
+import { Monitor, Code, BookOpen, Zap, Bot, Boxes, Rocket } from 'lucide-react';
+
+<div className="not-prose -mt-2 mb-6">
+ <p className="text-fd-primary font-semibold text-sm mb-1">Welcome</p>
+ <h1 className="text-3xl font-bold tracking-tight md:text-4xl">Welcome to Cua</h1>
+</div>
+
+**Cua** is an open-source framework for building and evaluating Computer-Use Agents - AI systems that autonomously interact with computer interfaces by understanding visual elements and executing actions.
+
+<div className="not-prose relative rounded-xl overflow-hidden my-8 w-full">
+ <img src="/docs/img/hero.png" alt="Cua" className="w-full h-auto rounded-xl" />
+</div>
+
+## What is a Computer-Use Agent?
+
+Computer-Use Agents (CUAs) are AI systems that can autonomously interact with computer interfaces through visual understanding and action execution. They work by capturing screenshots, feeding them to a vision-language model (VLM), and letting the model determine the next action to take - such as clicking, typing, or scrolling - in a continuous loop until the task is complete.
+
+## What is a Computer-Use Sandbox?
+
+Computer-Use Sandboxes are isolated, controlled environments where AI agents can safely interact with computer interfaces. They provide a secure execution space for agents to perform actions such as clicking, typing, and running code, test automation workflows, and learn from interactions without affecting production systems.
+
+## Key Features
+
+With **Cua Computer Framework**, you can:
+
+- Automate **Windows, Linux, and macOS** sandboxes with a consistent, pyautogui-like API
+- Create & manage sandboxes locally or using **Cua Cloud**
+
+With **Cua Agent Framework**, you can:
+
+- Run computer-use models with a consistent schema
+- Benchmark on **OSWorld-Verified**, **SheetBench-V2**, and **ScreenSpot**
+- Combine UI grounding models with any LLM using **composed agents**
+- Use **100+ models** via API or local inference (Claude, GPT-4, Gemini, Ollama, MLX)
+
+## Get Started
+
+Follow the [Quickstart guide](/guide/get-started/quickstart) for step-by-step setup with Python or TypeScript.
+
+Check out our [tutorials](https://cua.ai/blog), [examples](https://github.com/trycua/cua/tree/main/examples), and [notebooks](https://github.com/trycua/cua/tree/main/notebooks) to start building with Cua today.
+
+<div className="grid grid-cols-2 md:grid-cols-4 gap-2 mt-4 text-sm">
+ <Card icon={<Rocket className="w-4 h-4" />} href="/guide/get-started/quickstart" title="Quickstart" />
+ <Card icon={<Zap className="w-4 h-4" />} href="/reference/agent-sdk/agent-loops" title="Agent Loops" />
+ <Card
+ icon={<BookOpen className="w-4 h-4" />}
+ href="/reference/computer-sdk/computers"
+ title="Cua Computer"
+ />
+ <Card
+ icon={<Monitor className="w-4 h-4" />}
+ href="/examples/example-usecases/form-filling"
+ title="Examples"
+ />
+</div>
diff --git a/docs/content/guide/meta.json b/docs/content/guide/meta.json
new file mode 100644
index 0000000000..1031551f6b
--- /dev/null
+++ b/docs/content/guide/meta.json
@@ -0,0 +1,10 @@
+{
+ "title": "Guide",
+ "description": "Get started with Cua",
+ "root": true,
+ "defaultOpen": true,
+ "pages": [
+ "index",
+ "...get-started"
+ ]
+}
diff --git a/docs/content/docs/agent-sdk/agent-loops.mdx b/docs/content/reference/agent-sdk/agent-loops.mdx
similarity index 92%
rename from docs/content/docs/agent-sdk/agent-loops.mdx
rename to docs/content/reference/agent-sdk/agent-loops.mdx
index 0b759b3e79..2fe4cea9fb 100644
--- a/docs/content/docs/agent-sdk/agent-loops.mdx
+++ b/docs/content/reference/agent-sdk/agent-loops.mdx
@@ -4,18 +4,15 @@ description: Supported computer-using agent loops and models
---
<Callout>
- A corresponding{' '}
- <a href="https://github.com/trycua/cua/blob/main/notebooks/agent_nb.ipynb" target="_blank">
- Jupyter Notebook
- </a>{' '}
- is available for this documentation.
+ A corresponding <a href="https://github.com/trycua/cua/blob/main/notebooks/agent_nb.ipynb" target="_blank">Jupyter Notebook</a> is available for this documentation.
</Callout>
-An agent can be thought of as a loop - it generates actions, executes them, and repeats until done:
+An **agent loop** runs iteratively until a task is complete:
-1. **Generate**: Your `model` generates `output_text`, `computer_call`, `function_call`
-2. **Execute**: The `computer` safely executes those items
-3. **Complete**: If the model has no more calls, it's done!
+1. **Observe** → Take a screenshot
+2. **Reason** → VLM decides the next action
+3. **Act** → Execute (click, type, scroll)
+4. **Repeat** → Until done
To run an agent loop simply do:
diff --git a/docs/content/reference/agent-sdk/benchmarks/index.mdx b/docs/content/reference/agent-sdk/benchmarks/index.mdx
new file mode 100644
index 0000000000..685a8f92fe
--- /dev/null
+++ b/docs/content/reference/agent-sdk/benchmarks/index.mdx
@@ -0,0 +1,29 @@
+---
+title: Benchmarks
+description: Computer Agent SDK benchmarks for agentic GUI tasks
+---
+
+The benchmark system evaluates models on GUI grounding tasks, specifically agent loop success rate and click prediction accuracy. It supports both:
+
+- **Computer Agent SDK providers** (using model strings like `"huggingface-local/HelloKKMe/GTA1-7B"`)
+- **Reference agent implementations** (custom model classes implementing the `ModelProtocol`)
+
+## Available Benchmarks
+
+- **[ScreenSpot-v2](./benchmarks/screenspot-v2)** - Standard resolution GUI grounding
+- **[ScreenSpot-Pro](./benchmarks/screenspot-pro)** - High-resolution GUI grounding
+- **[Interactive Testing](./benchmarks/interactive)** - Real-time testing and visualization
+
+## Quick Start
+
+```bash
+# Clone the benchmark repository
+git clone https://github.com/trycua/cua
+cd libs/python/agent/benchmarks
+
+# Install dependencies
+pip install "cua-agent[all]"
+
+# Run a benchmark
+python ss-v2.py
+```
diff --git a/docs/content/reference/agent-sdk/benchmarks/interactive.mdx b/docs/content/reference/agent-sdk/benchmarks/interactive.mdx
new file mode 100644
index 0000000000..43170ca461
--- /dev/null
+++ b/docs/content/reference/agent-sdk/benchmarks/interactive.mdx
@@ -0,0 +1,21 @@
+---
+title: Interactive Tool
+description: Real-time testing and visualization tool for GUI grounding models
+---
+
+This tool allows you to test multiple models interactively by providing natural language instructions. It automatically captures screenshots and tests all configured models sequentially, providing immediate feedback and visual results.
+
+## Usage
+
+```bash
+# Start the interactive tool
+cd libs/python/agent/benchmarks
+python interactive.py
+```
+
+## Commands
+
+- **Type instruction**: Screenshot + test all models
+- **`screenshot`**: Take screenshot without prediction
+- **`models`**: List available models
+- **`quit`/`exit`**: Exit the tool
diff --git a/docs/content/reference/agent-sdk/benchmarks/introduction.mdx b/docs/content/reference/agent-sdk/benchmarks/introduction.mdx
new file mode 100644
index 0000000000..67a90769bd
--- /dev/null
+++ b/docs/content/reference/agent-sdk/benchmarks/introduction.mdx
@@ -0,0 +1,58 @@
+---
+title: Introduction
+description: Overview of benchmarking in the Cua agent framework
+---
+
+The Cua agent framework uses benchmarks to test the performance of supported models and providers at various agentic tasks.
+
+## Benchmark Types
+
+Computer-Agent benchmarks evaluate two key capabilities:
+
+- **Plan Generation**: Breaking down complex tasks into a sequence of actions
+- **Coordinate Generation**: Predicting precise click locations on GUI elements
+
+## Using State-of-the-Art Models
+
+Let's see how to use the SOTA vision-language models in the Cua agent framework.
+
+### Plan Generation + Coordinate Generation
+
+**[OS-World](https://os-world.github.io/)** - Benchmark for complete computer-use agents
+
+This leaderboard tests models that can understand instructions and automatically perform the full sequence of actions needed to complete tasks.
+
+```python
+# UI-TARS-1.5 is a SOTA unified plan generation + coordinate generation VLM
+# This makes it suitable for agentic loops for computer-use
+agent = ComputerAgent("huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B", tools=[computer])
+agent.run("Open Firefox and go to github.com")
+# Success! 🎉
+```
+
+### Coordinate Generation Only
+
+**[GUI Agent Grounding Leaderboard](https://gui-agent.github.io/grounding-leaderboard/)** - Benchmark for click prediction accuracy
+
+This leaderboard tests models that specialize in finding exactly where to click on screen elements, but needs to be told what specific action to take.
+
+```python
+# GTA1-7B is a SOTA coordinate generation VLM
+# It can only generate coordinates, not plan:
+agent = ComputerAgent("huggingface-local/HelloKKMe/GTA1-7B", tools=[computer])
+agent.predict_click("find the button to open the settings") # (27, 450)
+# This will raise an error:
+# agent.run("Open Firefox and go to github.com")
+```
+
+### Composed Agent
+
+The Cua agent framework also supports composed agents, which combine a planning model with a clicking model for the best of both worlds. Any liteLLM model can be used as the plan generation model.
+
+```python
+# It can be paired with any LLM to form a composed agent:
+# "gemini/gemini-1.5-pro" will be used as the plan generation LLM
+agent = ComputerAgent("huggingface-local/HelloKKMe/GTA1-7B+gemini/gemini-1.5-pro", tools=[computer])
+agent.run("Open Firefox and go to github.com")
+# Success! 🎉
+```
diff --git a/docs/content/reference/agent-sdk/benchmarks/meta.json b/docs/content/reference/agent-sdk/benchmarks/meta.json
new file mode 100644
index 0000000000..8067bb0114
--- /dev/null
+++ b/docs/content/reference/agent-sdk/benchmarks/meta.json
@@ -0,0 +1,3 @@
+{
+ "pages": ["introduction", "screenspot-v2", "screenspot-pro", "interactive", "osworld-verified"]
+}
diff --git a/docs/content/reference/agent-sdk/benchmarks/osworld-verified.mdx b/docs/content/reference/agent-sdk/benchmarks/osworld-verified.mdx
new file mode 100644
index 0000000000..26e4b7e44e
--- /dev/null
+++ b/docs/content/reference/agent-sdk/benchmarks/osworld-verified.mdx
@@ -0,0 +1,8 @@
+---
+title: OSWorld-Verified
+description: Benchmark ComputerAgent on OSWorld tasks using HUD
+---
+
+OSWorld-Verified is a curated subset of OSWorld tasks that can be run using the HUD framework.
+
+Use [ComputerAgent with HUD](../integrations/hud) to benchmark on these tasks.
diff --git a/docs/content/reference/agent-sdk/benchmarks/screenspot-pro.mdx b/docs/content/reference/agent-sdk/benchmarks/screenspot-pro.mdx
new file mode 100644
index 0000000000..15739d9d11
--- /dev/null
+++ b/docs/content/reference/agent-sdk/benchmarks/screenspot-pro.mdx
@@ -0,0 +1,25 @@
+---
+title: ScreenSpot-Pro
+description: High-resolution GUI grounding benchmark
+---
+
+ScreenSpot-Pro is a benchmark for evaluating click prediction accuracy on high-resolution GUI screenshots with complex layouts.
+
+## Usage
+
+```bash
+# Run the benchmark
+cd libs/python/agent/benchmarks
+python ss-pro.py
+
+# Run with custom sample limit
+python ss-pro.py --samples 50
+```
+
+## Results
+
+| Model | Accuracy | Failure Rate | Samples |
+| ----------- | -------- | ------------ | ------- |
+| Coming Soon | - | - | - |
+
+Results will be populated after running benchmarks with various models.
diff --git a/docs/content/reference/agent-sdk/benchmarks/screenspot-v2.mdx b/docs/content/reference/agent-sdk/benchmarks/screenspot-v2.mdx
new file mode 100644
index 0000000000..ba78d5f915
--- /dev/null
+++ b/docs/content/reference/agent-sdk/benchmarks/screenspot-v2.mdx
@@ -0,0 +1,25 @@
+---
+title: ScreenSpot-v2
+description: Standard resolution GUI grounding benchmark
+---
+
+ScreenSpot-v2 is a benchmark for evaluating click prediction accuracy on standard resolution GUI screenshots.
+
+## Usage
+
+```bash
+# Run the benchmark
+cd libs/python/agent/benchmarks
+python ss-v2.py
+
+# Run with custom sample limit
+python ss-v2.py --samples 100
+```
+
+## Results
+
+| Model | Accuracy | Failure Rate | Samples |
+| ----------- | -------- | ------------ | ------- |
+| Coming Soon | - | - | - |
+
+Results will be populated after running benchmarks with various models.
diff --git a/docs/content/docs/agent-sdk/callbacks/agent-lifecycle.mdx b/docs/content/reference/agent-sdk/callbacks/agent-lifecycle.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/callbacks/agent-lifecycle.mdx
rename to docs/content/reference/agent-sdk/callbacks/agent-lifecycle.mdx
diff --git a/docs/content/docs/agent-sdk/callbacks/cost-saving.mdx b/docs/content/reference/agent-sdk/callbacks/cost-saving.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/callbacks/cost-saving.mdx
rename to docs/content/reference/agent-sdk/callbacks/cost-saving.mdx
diff --git a/docs/content/docs/agent-sdk/callbacks/index.mdx b/docs/content/reference/agent-sdk/callbacks/index.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/callbacks/index.mdx
rename to docs/content/reference/agent-sdk/callbacks/index.mdx
diff --git a/docs/content/docs/agent-sdk/callbacks/logging.mdx b/docs/content/reference/agent-sdk/callbacks/logging.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/callbacks/logging.mdx
rename to docs/content/reference/agent-sdk/callbacks/logging.mdx
diff --git a/docs/content/docs/agent-sdk/callbacks/meta.json b/docs/content/reference/agent-sdk/callbacks/meta.json
similarity index 100%
rename from docs/content/docs/agent-sdk/callbacks/meta.json
rename to docs/content/reference/agent-sdk/callbacks/meta.json
diff --git a/docs/content/docs/agent-sdk/callbacks/pii-anonymization.mdx b/docs/content/reference/agent-sdk/callbacks/pii-anonymization.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/callbacks/pii-anonymization.mdx
rename to docs/content/reference/agent-sdk/callbacks/pii-anonymization.mdx
diff --git a/docs/content/docs/agent-sdk/callbacks/trajectories.mdx b/docs/content/reference/agent-sdk/callbacks/trajectories.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/callbacks/trajectories.mdx
rename to docs/content/reference/agent-sdk/callbacks/trajectories.mdx
diff --git a/docs/content/reference/agent-sdk/chat-history.mdx b/docs/content/reference/agent-sdk/chat-history.mdx
new file mode 100644
index 0000000000..e6740fc339
--- /dev/null
+++ b/docs/content/reference/agent-sdk/chat-history.mdx
@@ -0,0 +1,92 @@
+---
+title: Chat History
+description: Managing conversation history and message arrays
+---
+
+Managing conversation history is essential for multi-turn agent interactions. The agent maintains a messages array that tracks the entire conversation flow.
+
+## Managing History
+
+### Continuous Conversation
+
+```python
+history = []
+
+while True:
+ user_input = input("> ")
+ history.append({"role": "user", "content": user_input})
+
+ async for result in agent.run(history, stream=False):
+ history += result["output"]
+```
+
+## Message Array Structure
+
+The messages array contains different types of messages that represent the conversation state:
+
+```python
+messages = [
+ # user input
+ {
+ "role": "user",
+ "content": "go to trycua on gh"
+ },
+ # first agent turn adds the model output to the history
+ {
+ "summary": [
+ {
+ "text": "Searching Firefox for Trycua GitHub",
+ "type": "summary_text"
+ }
+ ],
+ "type": "reasoning"
+ },
+ {
+ "action": {
+ "text": "Trycua GitHub",
+ "type": "type"
+ },
+ "call_id": "call_QI6OsYkXxl6Ww1KvyJc4LKKq",
+ "status": "completed",
+ "type": "computer_call"
+ },
+ # second agent turn adds the computer output to the history
+ {
+ "type": "computer_call_output",
+ "call_id": "call_QI6OsYkXxl6Ww1KvyJc4LKKq",
+ "output": {
+ "type": "input_image",
+ "image_url": "data:image/png;base64,..."
+ }
+ },
+ # final agent turn adds the agent output text to the history
+ {
+ "type": "message",
+ "role": "assistant",
+ "content": [
+ {
+ "text": "Success! The Trycua GitHub page has been opened.",
+ "type": "output_text"
+ }
+ ]
+ }
+]
+```
+
+## Message Types
+
+See the complete schema in [Message Format](./message-format).
+
+### Memory Management
+
+For long conversations, consider using the `only_n_most_recent_images` parameter to manage memory:
+
+```python
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ only_n_most_recent_images=3
+)
+```
+
+This automatically removes old images from the conversation history to prevent context window overflow.
diff --git a/docs/content/reference/agent-sdk/custom-tools.mdx b/docs/content/reference/agent-sdk/custom-tools.mdx
new file mode 100644
index 0000000000..cf1652dd29
--- /dev/null
+++ b/docs/content/reference/agent-sdk/custom-tools.mdx
@@ -0,0 +1,49 @@
+---
+title: Custom Tools
+slug: custom-tools
+---
+
+The Agent SDK supports defining custom Python tools that run securely in sandboxed environments on remote Cua Computer Frameworks. This enables safe execution of user-defined functions, isolation of dependencies, and robust automation workflows.
+
+## Custom Tools
+
+Define a custom tool for an agent:
+
+```python
+def calculate(a: int, b: int) -> int:
+ """Calculate the sum of two integers"""
+ return a + b
+
+# Use with agent
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer, calculate]
+)
+```
+
+## Sandboxed Tools
+
+Define a sandboxed tool:
+
+```python
+from computer.helpers import sandboxed
+
+@sandboxed()
+def read_file(location: str) -> str:
+ """Read contents of a file"""
+ with open(location, 'r') as f:
+ return f.read()
+```
+
+You can then register this as a tool for your agent:
+
+```python
+from agent import ComputerAgent
+from computer import Computer
+
+computer = Computer(...)
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer, read_file],
+)
+```
diff --git a/docs/content/reference/agent-sdk/customizing-computeragent.mdx b/docs/content/reference/agent-sdk/customizing-computeragent.mdx
new file mode 100644
index 0000000000..158495e07c
--- /dev/null
+++ b/docs/content/reference/agent-sdk/customizing-computeragent.mdx
@@ -0,0 +1,130 @@
+---
+title: Customize ComputerAgent
+---
+
+<Callout>
+ A corresponding{' '}
+ <a
+ href="https://github.com/trycua/cua/blob/main/notebooks/customizing_computeragent.ipynb"
+ target="_blank"
+ >
+ Jupyter Notebook
+ </a>{' '}
+ is available for this documentation.
+</Callout>
+
+The `ComputerAgent` interface provides an easy proxy to any computer-using model configuration, and it is a powerful framework for extending and building your own agentic systems.
+
+This guide shows four proven ways to increase capabilities and success rate:
+
+- 1 — Simple: Prompt engineering
+- 2 — Easy: Tools
+- 3 — Intermediate: Callbacks
+- 4 — Expert: Custom `@register_agent`
+
+## 1) Simple: Prompt engineering
+
+Provide guiding instructions to shape behavior. `ComputerAgent` accepts an optional `instructions: str | None` which acts like a system-style preface. Internally, this uses a callback that pre-pends a user message before each LLM call.
+
+```python
+from agent.agent import ComputerAgent
+
+agent = ComputerAgent(
+ model="openai/computer-use-preview",
+ tools=[computer],
+ instructions=(
+ "You are a meticulous software operator. Prefer safe, deterministic actions. "
+ "Always confirm via on-screen text before proceeding."
+ ),
+)
+```
+
+## 2) Easy: Tools
+
+Expose deterministic capabilities as tools (Python functions or custom computer handlers). The agent will call them when appropriate.
+
+```python
+def calculate_percentage(numerator: float, denominator: float) -> str:
+ """Calculate percentage as a string.
+
+ Args:
+ numerator: Numerator value
+ denominator: Denominator value
+ Returns:
+ A formatted percentage string (e.g., '75.00%').
+ """
+ if denominator == 0:
+ return "0.00%"
+ return f"{(numerator/denominator)*100:.2f}%"
+
+agent = ComputerAgent(
+ model="openai/computer-use-preview",
+ tools=[computer, calculate_percentage],
+)
+```
+
+- See `docs/agent-sdk/custom-tools` for authoring function tools.
+- See `docs/agent-sdk/custom-computer-handlers` for building full computer interfaces.
+
+## 3) Intermediate: Callbacks
+
+Callbacks provide lifecycle hooks to preprocess messages, postprocess outputs, record trajectories, manage costs, and more.
+
+```python
+from agent.callbacks import ImageRetentionCallback, TrajectorySaverCallback, BudgetManagerCallback
+
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ callbacks=[
+ ImageRetentionCallback(only_n_most_recent_images=3),
+ TrajectorySaverCallback("./trajectories"),
+ BudgetManagerCallback(max_budget=10.0, raise_error=True),
+ ],
+)
+```
+
+- Browse implementations in `libs/python/agent/agent/loops/`.
+
+## 4) Expert: Custom `@register_agent`
+
+Build your own agent configuration class to control prompting, message shaping, and tool handling. This is the most flexible option for specialized domains.
+
+- Register your own `model=...` loop using `@register_agent`
+- Browse implementations in `libs/python/agent/agent/loops/`.
+- Implement `predict_step()` (and optionally `predict_click()`) and return the standardized output schema.
+
+```python
+from agent.decorators import register_agent
+
+@register_agent(models=r".*my-special-model.*", priority=10)
+class MyCustomAgentConfig:
+ async def predict_step(self, messages, model, tools, **kwargs):
+ # 1) Format messages for your provider
+ # 2) Call provider
+ # 3) Convert responses to the agent output schema
+ return {"output": [], "usage": {}}
+
+ async def predict_click(self, model, image_b64, instruction):
+ # Optional: click-only capability
+ return None
+
+ def get_capabilities(self):
+ return ["step"]
+```
+
+## HUD integration (optional)
+
+When using the HUD evaluation integration (`agent/integrations/hud/`), you can pass `instructions`, `tools`, and `callbacks` directly
+
+```python
+from agent.integrations.hud import run_single_task
+
+await run_single_task(
+ dataset="username/dataset-name",
+ model="openai/computer-use-preview",
+ instructions="Operate carefully. Always verify on-screen text before actions.",
+ # tools=[your_custom_function],
+ # callbacks=[YourCustomCallback()],
+)
+```
diff --git a/docs/content/reference/agent-sdk/integrations/hud.mdx b/docs/content/reference/agent-sdk/integrations/hud.mdx
new file mode 100644
index 0000000000..7bfcbdea35
--- /dev/null
+++ b/docs/content/reference/agent-sdk/integrations/hud.mdx
@@ -0,0 +1,141 @@
+---
+title: HUD Evals
+description: Use ComputerAgent with HUD for benchmarking and evaluation
+---
+
+<Callout>
+ A corresponding{' '}
+ <a href="https://github.com/trycua/cua/blob/main/notebooks/eval_osworld.ipynb" target="_blank">
+ Jupyter Notebook
+ </a>{' '}
+ is available for this documentation.
+</Callout>
+
+The HUD integration allows an agent to be benchmarked using the [HUD framework](https://www.hud.so/). Through the HUD integration, the agent controls a computer inside HUD, where tests are run to evaluate the success of each task.
+
+## Installation
+
+First, install the required package:
+
+```bash
+pip install "cua-agent[hud]"
+## or install hud-python directly
+# pip install hud-python==0.4.12
+```
+
+## Environment Variables
+
+Before running any evaluations, you’ll need to set up your environment variables for HUD and your model providers:
+
+```bash
+# HUD access
+export HUD_API_KEY="your_hud_api_key"
+
+# Model provider keys (at least one required)
+export OPENAI_API_KEY="your_openai_key"
+export ANTHROPIC_API_KEY="your_anthropic_key"
+```
+
+## Running a Single Task
+
+You can run a single task from a HUD dataset for quick verification.
+
+### Example
+
+```python
+from agent.integrations.hud import run_single_task
+
+await run_single_task(
+ dataset="hud-evals/OSWorld-Verified", # or another HUD dataset
+ model="openai/computer-use-preview+openai/gpt-5-nano", # any supported model string
+ task_id=155, # e.g., reopen last closed tab
+)
+```
+
+### Parameters
+
+- `task_id` (`int`): Default: `0`
+ Index of the task to run from the dataset.
+
+## Running a Full Dataset
+
+To benchmark your agent at scale, you can run an entire dataset (or a subset) in parallel.
+
+### Example
+
+```python
+from agent.integrations.hud import run_full_dataset
+
+results = await run_full_dataset(
+ dataset="hud-evals/OSWorld-Verified", # can also pass a Dataset or list[dict]
+ model="openai/computer-use-preview",
+ split="train[:3]", # try a few tasks to start
+ max_concurrent=20, # tune to your infra
+ max_steps=50 # safety cap per task
+)
+```
+
+### Parameters
+
+- `job_name` (`str` | `None`):
+ Optional human-readable name for the evaluation job (shows up in HUD UI).
+- `max_concurrent` (`int`): Default: `30`
+ Number of tasks to run in parallel. Scale this based on your infra.
+- `max_steps` (`int`): Default: `50`
+ Safety cap on steps per task to prevent infinite loops.
+- `split` (`str`): Default: `"train"`
+ Dataset split or subset to run. Uses the [Hugging Face split format](https://huggingface.co/docs/datasets/v1.11.0/splits.html), e.g., `"train[:10]"` for the first 10 tasks.
+
+## Additional Parameters
+
+Both single-task and full-dataset runs share a common set of configuration options. These let you fine-tune how the evaluation runs.
+
+- `dataset` (`str` | `Dataset` | `list[dict]`): **Required**
+ HUD dataset name (e.g. `"hud-evals/OSWorld-Verified"`), a loaded `Dataset`, or a list of tasks.
+- `model` (`str`): Default: `"computer-use-preview"`
+ Model string, e.g. `"openai/computer-use-preview+openai/gpt-5-nano"`. Supports composition with `+` (planning + grounding).
+- `allowed_tools` (`list[str]`): Default: `["openai_computer"]`
+ Restrict which tools the agent may use.
+- `tools` (`list[Any]`):
+ Extra tool configs to inject.
+- `custom_loop` (`Callable`):
+ Optional custom agent loop function. If provided, overrides automatic loop selection.
+- `only_n_most_recent_images` (`int`): Default: `5` for full dataset, `None` for single task.
+ Retain only the last N screenshots in memory.
+- `callbacks` (`list[Any]`):
+ Hook functions for logging, telemetry, or side effects.
+- `verbosity` (`int`):
+ Logging level. Set `2` for debugging every call/action.
+- `trajectory_dir` (`str` | `dict`):
+ Save local copies of trajectories for replay/analysis.
+- `max_retries` (`int`): Default: `3`
+ Number of retries for failed model/tool calls.
+- `screenshot_delay` (`float` | `int`): Default: `0.5`
+ Delay (seconds) between screenshots to avoid race conditions.
+- `use_prompt_caching` (`bool`): Default: `False`
+ Cache repeated prompts to reduce API calls.
+- `max_trajectory_budget` (`float` | `dict`):
+ Limit on trajectory size/budget (e.g., tokens, steps).
+- `telemetry_enabled` (`bool`): Default: `True`
+ Whether to send telemetry/traces to HUD.
+- `**kwargs` (`any`):
+ Any additional keyword arguments are passed through to the agent loop or model provider.
+
+## Available Benchmarks
+
+HUD provides multiple benchmark datasets for realistic evaluation.
+
+1. **[OSWorld-Verified](/agent-sdk/benchmarks/osworld-verified)** – Benchmark on 369+ real-world desktop tasks across Chrome, LibreOffice, GIMP, VS Code, etc.
+ _Best for_: evaluating full computer-use agents in realistic environments.
+ _Verified variant_: fixes 300+ issues from earlier versions for reliability.
+
+**Coming soon:** SheetBench (spreadsheet automation) and other specialized HUD datasets.
+
+See the [HUD docs](https://docs.hud.so/environment-creation) for more eval environments.
+
+## Tips
+
+- **Debugging:** set `verbosity=2` to see every model call and tool action.
+- **Performance:** lower `screenshot_delay` for faster runs; raise it if you see race conditions.
+- **Safety:** always set `max_steps` (defaults to 50) to prevent runaway loops.
+- **Custom tools:** pass extra `tools=[...]` into the agent config if you need beyond `openai_computer`.
diff --git a/docs/content/docs/agent-sdk/integrations/meta.json b/docs/content/reference/agent-sdk/integrations/meta.json
similarity index 100%
rename from docs/content/docs/agent-sdk/integrations/meta.json
rename to docs/content/reference/agent-sdk/integrations/meta.json
diff --git a/docs/content/reference/agent-sdk/integrations/observability.mdx b/docs/content/reference/agent-sdk/integrations/observability.mdx
new file mode 100644
index 0000000000..44db0ea461
--- /dev/null
+++ b/docs/content/reference/agent-sdk/integrations/observability.mdx
@@ -0,0 +1,66 @@
+---
+title: Observability
+description: Trace CUA execution steps and sessions
+---
+
+## Observability
+
+CUA has a native integration with [Laminar](https://laminar.sh/) – open-source platform for tracing, evals, and labeling of autonomous AI agents. Read more about Laminar in the [Laminar docs](https://docs.lmnr.ai/).
+
+## Setup
+
+Register on [Laminar Cloud](https://laminar.sh/) or spin up a [local instance](https://github.com/lmnr-ai/lmnr) and get the key from your project settings. Set the `LMNR_PROJECT_API_KEY` environment variable to your key.
+
+```bash
+pip install lmnr[all]
+export LMNR_PROJECT_API_KEY=your-key
+```
+
+## Usage
+
+Then, initialize Laminar at the entry point of your application, register Laminar LiteLLM callback, and all steps of CUA will be automatically traced.
+
+```python
+import os
+
+import litellm
+
+from agent import ComputerAgent
+from computer import Computer
+from lmnr import Laminar, LaminarLiteLLMCallback # [!code highlight]
+
+Laminar.initialize() # [!code highlight]
+litellm.callbacks.append(LaminarLiteLLMCallback()) # [!code highlight]
+
+computer = Computer(
+ os_type="linux",
+ provider_type="cloud",
+ name=os.getenv("CUA_CONTAINER_NAME"),
+ api_key=os.getenv("CUA_API_KEY"),
+)
+
+agent = ComputerAgent(
+ model="openai/computer-use-preview",
+ tools=[computer],
+)
+
+async def main():
+ async for step in agent.run("Create a new file called 'test.txt' in the current directory"):
+ print(step["output"])
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+## Viewing traces
+
+You can view traces in the Laminar UI by going to the traces tab in your project. When you select a trace,
+you will see all the agent execution steps, including computer actions, LLM calls, and screenshots.
+
+For each step, you will see the LLM call, the computer action. The computer actions are highlighted in the timeline in yellow.
+
+<img
+ src="/docs/img/laminar_trace_example.png"
+ alt="Example trace in Laminar showing the litellm.response span and its output."
+ width="800px"
+/>
diff --git a/docs/content/reference/agent-sdk/mcp-server/client-integrations.mdx b/docs/content/reference/agent-sdk/mcp-server/client-integrations.mdx
new file mode 100644
index 0000000000..43d76ab57d
--- /dev/null
+++ b/docs/content/reference/agent-sdk/mcp-server/client-integrations.mdx
@@ -0,0 +1,123 @@
+---
+title: Client Integrations
+---
+
+## Claude Desktop Integration
+
+To use with Claude Desktop, add an entry to your Claude Desktop configuration (`claude_desktop_config.json`, typically found in `~/.config/claude-desktop/`):
+
+### Package Installation Method
+
+```json
+{
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/bin/bash",
+ "args": ["~/.cua/start_mcp_server.sh"],
+ "env": {
+ "CUA_MODEL_NAME": "anthropic/claude-sonnet-4-20250514",
+ "ANTHROPIC_API_KEY": "your-anthropic-api-key-here",
+ "CUA_MAX_IMAGES": "3",
+ "CUA_USE_HOST_COMPUTER_SERVER": "false"
+ }
+ }
+ }
+}
+```
+
+### Development Method
+
+If you're working with the CUA source code:
+
+**Standard VM Mode:**
+
+```json
+{
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/usr/bin/env",
+ "args": [
+ "bash",
+ "-lc",
+ "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-20250514'; export ANTHROPIC_API_KEY='your-anthropic-api-key-here'; /path/to/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
+ ]
+ }
+ }
+}
+```
+
+**Host Computer Control Mode:**
+
+```json
+{
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/usr/bin/env",
+ "args": [
+ "bash",
+ "-lc",
+ "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-20250514'; export ANTHROPIC_API_KEY='your-anthropic-api-key-here'; export CUA_USE_HOST_COMPUTER_SERVER='true'; export CUA_MAX_IMAGES='1'; /path/to/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
+ ]
+ }
+ }
+}
+```
+
+**Note**: Replace `/path/to/cua` with the absolute path to your CUA repository directory.
+
+**⚠️ Host Computer Control Setup**: When using `CUA_USE_HOST_COMPUTER_SERVER='true'`, you must also:
+
+1. Install computer server dependencies: `python3 -m pip install uvicorn fastapi`
+2. Install the computer server: `python3 -m pip install -e libs/python/computer-server --break-system-packages`
+3. Start the computer server: `python -m computer_server --log-level debug`
+4. The AI will have direct access to your desktop - use with caution!
+
+For more information on MCP with Claude Desktop, see the [official MCP User Guide](https://modelcontextprotocol.io/quickstart/user).
+
+## Cursor Integration
+
+To use with Cursor, add an MCP configuration file in one of these locations:
+
+- **Project-specific**: Create `.cursor/mcp.json` in your project directory
+- **Global**: Create `~/.cursor/mcp.json` in your home directory
+
+Example configuration for Cursor:
+
+```json
+{
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/bin/bash",
+ "args": ["~/.cua/start_mcp_server.sh"],
+ "env": {
+ "CUA_MODEL_NAME": "anthropic/claude-sonnet-4-20250514",
+ "ANTHROPIC_API_KEY": "your-anthropic-api-key-here"
+ }
+ }
+ }
+}
+```
+
+After configuration, you can simply tell Cursor's Agent to perform computer tasks by explicitly mentioning the CUA agent, such as "Use the computer control tools to open Safari."
+
+For more information on MCP with Cursor, see the [official Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol).
+
+## Other MCP Clients
+
+The MCP server is compatible with any MCP-compliant client. The server exposes the following tools:
+
+- `run_cua_task` - Execute single computer tasks
+- `run_multi_cua_tasks` - Execute multiple tasks (sequential or concurrent)
+- `screenshot_cua` - Capture screenshots
+- `get_session_stats` - Monitor session statistics
+- `cleanup_session` - Manage session lifecycle
+
+### Configuration Options
+
+All MCP clients can configure the server using environment variables:
+
+- `CUA_MODEL_NAME` - Model to use for task execution
+- `CUA_MAX_IMAGES` - Maximum images to keep in context
+- `CUA_USE_HOST_COMPUTER_SERVER` - Use host system instead of VM
+
+See the [Configuration](/docs/libraries/mcp-server/configuration) page for detailed configuration options.
diff --git a/docs/content/reference/agent-sdk/mcp-server/configuration.mdx b/docs/content/reference/agent-sdk/mcp-server/configuration.mdx
new file mode 100644
index 0000000000..106ce6d983
--- /dev/null
+++ b/docs/content/reference/agent-sdk/mcp-server/configuration.mdx
@@ -0,0 +1,73 @@
+---
+title: Configuration
+---
+
+The server is configured using environment variables (can be set in the Claude Desktop config):
+
+| Variable | Description | Default |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| `CUA_MODEL_NAME` | Model string (e.g., "anthropic/claude-sonnet-4-20250514", "openai/computer-use-preview", "huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B", "omniparser+litellm/gpt-4o", "omniparser+ollama_chat/gemma3") | anthropic/claude-sonnet-4-20250514 |
+| `ANTHROPIC_API_KEY` | Your Anthropic API key (required for Anthropic models) | None |
+| `CUA_MAX_IMAGES` | Maximum number of images to keep in context | 3 |
+| `CUA_USE_HOST_COMPUTER_SERVER` | Target your local desktop instead of a VM. Set to "true" to use your host system. **Warning:** AI models may perform risky actions. | false |
+
+## Model Configuration
+
+The `CUA_MODEL_NAME` environment variable supports various model providers through LiteLLM integration:
+
+### Supported Providers
+
+- **Anthropic**: `anthropic/claude-sonnet-4-20250514`,
+- **OpenAI**: `openai/computer-use-preview`, `openai/gpt-4o`
+- **Local Models**: `huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B`
+- **Omni + LiteLLM**: `omniparser+litellm/gpt-4o`, `omniparser+litellm/claude-3-haiku`
+- **Ollama**: `omniparser+ollama_chat/gemma3`
+
+### Example Configurations
+
+**Claude Desktop Configuration:**
+
+```json
+{
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/bin/bash",
+ "args": ["~/.cua/start_mcp_server.sh"],
+ "env": {
+ "CUA_MODEL_NAME": "anthropic/claude-sonnet-4-20250514",
+ "ANTHROPIC_API_KEY": "your-anthropic-api-key-here",
+ "CUA_MAX_IMAGES": "5",
+ "CUA_USE_HOST_COMPUTER_SERVER": "false"
+ }
+ }
+ }
+}
+```
+
+**Local Model Configuration:**
+
+```json
+{
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/bin/bash",
+ "args": ["~/.cua/start_mcp_server.sh"],
+ "env": {
+ "CUA_MODEL_NAME": "huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B",
+ "CUA_MAX_IMAGES": "3"
+ }
+ }
+ }
+}
+```
+
+## Session Management Configuration
+
+The MCP server automatically manages sessions with the following defaults:
+
+- **Max Concurrent Sessions**: 10
+- **Session Timeout**: 10 minutes of inactivity
+- **Computer Pool Size**: 5 instances
+- **Automatic Cleanup**: Enabled
+
+These settings are optimized for typical usage and don't require configuration for most users.
diff --git a/docs/content/reference/agent-sdk/mcp-server/index.mdx b/docs/content/reference/agent-sdk/mcp-server/index.mdx
new file mode 100644
index 0000000000..108437f306
--- /dev/null
+++ b/docs/content/reference/agent-sdk/mcp-server/index.mdx
@@ -0,0 +1,17 @@
+---
+title: MCP Server
+description: Run Cua agents through Claude Desktop and other MCP clients
+---
+
+The MCP Server exposes Cua agents as tools for [Model Context Protocol](https://modelcontextprotocol.io/) clients like Claude Desktop. This lets you ask Claude to perform computer tasks directly from the chat interface.
+
+```bash
+pip install cua-mcp-server
+```
+
+## Key Features
+
+- **Claude Desktop integration** - Use Cua agents directly in Claude's chat
+- **Multi-client support** - Concurrent sessions with automatic resource management
+- **Progress reporting** - Real-time updates during task execution
+- **VM safety** - Runs in sandboxed VMs by default
diff --git a/docs/content/reference/agent-sdk/mcp-server/installation.mdx b/docs/content/reference/agent-sdk/mcp-server/installation.mdx
new file mode 100644
index 0000000000..b9c14f0939
--- /dev/null
+++ b/docs/content/reference/agent-sdk/mcp-server/installation.mdx
@@ -0,0 +1,140 @@
+---
+title: Installation
+---
+
+Install the package from PyPI:
+
+```bash
+pip install cua-mcp-server
+```
+
+This will install:
+
+- The MCP server
+- CUA agent and computer dependencies
+- An executable `cua-mcp-server` script in your PATH
+
+## Easy Setup Script
+
+If you want to simplify installation, you can use this one-liner to download and run the installation script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/python/mcp-server/scripts/install_mcp_server.sh | bash
+```
+
+This script will:
+
+- Create the ~/.cua directory if it doesn't exist
+- Generate a startup script at ~/.cua/start_mcp_server.sh
+- Make the script executable
+- The startup script automatically manages Python virtual environments and installs/updates the cua-mcp-server package
+
+You can then use the script in your MCP configuration like this:
+
+```json
+{
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/bin/bash",
+ "args": ["~/.cua/start_mcp_server.sh"],
+ "env": {
+ "CUA_MODEL_NAME": "anthropic/claude-sonnet-4-20250514",
+ "ANTHROPIC_API_KEY": "your-anthropic-api-key-here"
+ }
+ }
+ }
+}
+```
+
+**Important**: You must include your Anthropic API key for the MCP server to work properly.
+
+## Development Setup
+
+If you're working with the CUA source code directly (like in the CUA repository), you can use the development script instead:
+
+```json
+{
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/usr/bin/env",
+ "args": [
+ "bash",
+ "-lc",
+ "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-20250514'; export ANTHROPIC_API_KEY='your-anthropic-api-key-here'; /path/to/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
+ ]
+ }
+ }
+}
+```
+
+**For host computer control** (development setup):
+
+1. **Install Computer Server Dependencies**:
+
+ ```bash
+ python3 -m pip install uvicorn fastapi
+ python3 -m pip install -e libs/python/computer-server --break-system-packages
+ ```
+
+2. **Start the Computer Server**:
+
+ ```bash
+ cd /path/to/cua
+ python -m computer_server --log-level debug
+ ```
+
+ This will start the computer server on `http://localhost:8000` that controls your actual desktop.
+
+3. **Configure Claude Desktop**:
+ ```json
+ {
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/usr/bin/env",
+ "args": [
+ "bash",
+ "-lc",
+ "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-20250514'; export ANTHROPIC_API_KEY='your-anthropic-api-key-here'; export CUA_USE_HOST_COMPUTER_SERVER='true'; export CUA_MAX_IMAGES='1'; /path/to/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
+ ]
+ }
+ }
+ }
+ ```
+
+**Note**: Replace `/path/to/cua` with the absolute path to your CUA repository directory.
+
+**⚠️ Important**: When using host computer control (`CUA_USE_HOST_COMPUTER_SERVER='true'`), the AI will have direct access to your desktop and can perform actions like opening applications, clicking, typing, and taking screenshots. Make sure you're comfortable with this level of access.
+
+### Troubleshooting
+
+**Common Issues:**
+
+1. **"Claude's response was interrupted"** - This usually means:
+ - Missing API key: Add `ANTHROPIC_API_KEY` to your environment variables
+ - Invalid model name: Use a valid model like `anthropic/claude-sonnet-4-20250514`
+ - Check logs for specific error messages
+
+2. **"Missing Anthropic API Key"** - Add your API key to the configuration:
+
+ ```json
+ "env": {
+ "ANTHROPIC_API_KEY": "your-api-key-here"
+ }
+ ```
+
+3. **"model not found"** - Use a valid model name:
+ - ✅ `anthropic/claude-sonnet-4-20250514`
+
+4. **Script not found** - If you get a `/bin/bash: ~/cua/libs/python/mcp-server/scripts/start_mcp_server.sh: No such file or directory` error, try changing the path to the script to be absolute instead of relative.
+
+5. **Host Computer Control Issues** - If using `CUA_USE_HOST_COMPUTER_SERVER='true'`:
+ - **Computer Server not running**: Make sure you've started the computer server with `python -m computer_server --log-level debug`
+ - **Port 8000 in use**: Check if another process is using port 8000 with `lsof -i :8000`
+ - **Missing dependencies**: Install `uvicorn` and `fastapi` with `python3 -m pip install uvicorn fastapi`
+ - **Image size errors**: Use `CUA_MAX_IMAGES='1'` to reduce image context size
+
+**Viewing Logs:**
+
+```bash
+tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
+```
diff --git a/docs/content/reference/agent-sdk/mcp-server/llm-integrations.mdx b/docs/content/reference/agent-sdk/mcp-server/llm-integrations.mdx
new file mode 100644
index 0000000000..656def704f
--- /dev/null
+++ b/docs/content/reference/agent-sdk/mcp-server/llm-integrations.mdx
@@ -0,0 +1,18 @@
+---
+title: LLM Integrations
+---
+
+## LiteLLM Integration
+
+This MCP server features comprehensive liteLLM integration, allowing you to use any supported LLM provider with a simple model string configuration.
+
+- **Unified Configuration**: Use a single `CUA_MODEL_NAME` environment variable with a model string
+- **Automatic Provider Detection**: The agent automatically detects the provider and capabilities from the model string
+- **Extensive Provider Support**: Works with Anthropic, OpenAI, local models, and any liteLLM-compatible provider
+
+### Model String Examples:
+
+- **Anthropic**: `"anthropic/claude-sonnet-4-5-20250929"`
+- **OpenAI**: `"openai/computer-use-preview"`
+- **UI-TARS**: `"huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B"`
+- **Omni + Any LiteLLM**: `"omniparser+litellm/gpt-4o"`, `"omniparser+litellm/claude-3-haiku"`, `"omniparser+ollama_chat/gemma3"`
diff --git a/docs/content/reference/agent-sdk/mcp-server/meta.json b/docs/content/reference/agent-sdk/mcp-server/meta.json
new file mode 100644
index 0000000000..f5ccb9baee
--- /dev/null
+++ b/docs/content/reference/agent-sdk/mcp-server/meta.json
@@ -0,0 +1,10 @@
+{
+ "pages": [
+ "installation",
+ "configuration",
+ "usage",
+ "tools",
+ "client-integrations",
+ "llm-integrations"
+ ]
+}
diff --git a/docs/content/reference/agent-sdk/mcp-server/tools.mdx b/docs/content/reference/agent-sdk/mcp-server/tools.mdx
new file mode 100644
index 0000000000..0b4616ef05
--- /dev/null
+++ b/docs/content/reference/agent-sdk/mcp-server/tools.mdx
@@ -0,0 +1,66 @@
+---
+title: Tools
+---
+
+## Available Tools
+
+The MCP server exposes the following tools to Claude:
+
+### Core Task Execution Tools
+
+1. **`run_cua_task`** - Run a single Computer-Use Agent task with the given instruction
+ - `task` (string): The task description for the agent to execute
+ - `session_id` (string, optional): Session ID for multi-client support. If not provided, a new session will be created
+ - Returns: Tuple of (combined text output, final screenshot)
+
+2. **`run_multi_cua_tasks`** - Run multiple tasks in sequence or concurrently
+ - `tasks` (list of strings): List of task descriptions to execute
+ - `session_id` (string, optional): Session ID for multi-client support. If not provided, a new session will be created
+ - `concurrent` (boolean, optional): If true, run tasks concurrently. If false, run sequentially (default)
+ - Returns: List of tuples (combined text output, screenshot) for each task
+
+### Utility Tools
+
+3. **`screenshot_cua`** - Take a screenshot of the current screen
+ - `session_id` (string, optional): Session ID for multi-client support. If not provided, a new session will be created
+ - Returns: Screenshot image
+
+4. **`get_session_stats`** - Get statistics about active sessions and resource usage
+ - Returns: Dictionary with session statistics including total sessions, active tasks, and session details
+
+5. **`cleanup_session`** - Cleanup a specific session and release its resources
+ - `session_id` (string): The session ID to cleanup
+ - Returns: Confirmation message
+
+## Session Management
+
+The MCP server supports multi-client sessions with automatic resource management:
+
+- **Session Isolation**: Each client can have its own session with isolated computer instances
+- **Resource Pooling**: Computer instances are pooled for efficient resource usage
+- **Automatic Cleanup**: Idle sessions are automatically cleaned up after 10 minutes
+- **Concurrent Tasks**: Multiple tasks can run concurrently within the same session
+- **Progress Reporting**: Real-time progress updates during task execution
+
+## Usage Examples
+
+### Basic Task Execution
+
+```
+"Open Chrome and navigate to github.com"
+"Create a folder called 'Projects' on my desktop"
+```
+
+### Multi-Task Execution
+
+```
+"Run these tasks: 1) Open Finder, 2) Navigate to Documents, 3) Create a new folder called 'Work'"
+```
+
+### Session Management
+
+```
+"Take a screenshot of the current screen"
+"Show me the session statistics"
+"Cleanup session abc123"
+```
diff --git a/docs/content/reference/agent-sdk/mcp-server/usage.mdx b/docs/content/reference/agent-sdk/mcp-server/usage.mdx
new file mode 100644
index 0000000000..d65fc64466
--- /dev/null
+++ b/docs/content/reference/agent-sdk/mcp-server/usage.mdx
@@ -0,0 +1,169 @@
+---
+title: Usage
+---
+
+## Basic Usage
+
+Once configured, you can simply ask Claude to perform computer tasks:
+
+- "Open Chrome and go to github.com"
+- "Create a folder called 'Projects' on my desktop"
+- "Find all PDFs in my Downloads folder"
+- "Take a screenshot and highlight the error message"
+
+Claude will automatically use your CUA agent to perform these tasks.
+
+## Advanced Features
+
+### Progress Reporting
+
+The MCP server provides real-time progress updates during task execution:
+
+- Task progress is reported as percentages (0-100%)
+- Multi-task operations show progress for each individual task
+- Progress updates are streamed to the MCP client for real-time feedback
+
+### Error Handling
+
+Robust error handling ensures reliable operation:
+
+- Failed tasks return error messages with screenshots when possible
+- Session state is preserved even when individual tasks fail
+- Automatic cleanup prevents resource leaks
+- Detailed error logging for troubleshooting
+
+### Concurrent Task Execution
+
+For improved performance, multiple tasks can run concurrently:
+
+- Set `concurrent=true` in `run_multi_cua_tasks` for parallel execution
+- Each task runs in its own context with isolated state
+- Progress tracking works for both sequential and concurrent modes
+- Resource pooling ensures efficient computer instance usage
+
+### Session Management
+
+Multi-client support with automatic resource management:
+
+- Each client gets isolated sessions with separate computer instances
+- Sessions automatically clean up after 10 minutes of inactivity
+- Resource pooling prevents resource exhaustion
+- Session statistics available for monitoring
+
+## Target Computer Options
+
+By default, the MCP server runs CUA in a virtual machine for safety. However, you can also configure it to run on your local system.
+
+### Default: Using a VM (Recommended)
+
+The MCP server will automatically start and connect to a VM based on your platform. This is the safest option as AI actions are isolated from your host system.
+
+No additional configuration is needed - this is the default behavior.
+
+### Option: Targeting Your Local Desktop
+
+<Callout type="warn">
+ **Warning:** When targeting your local system, AI models have direct access to your desktop and
+ may perform risky actions. Use with caution.
+</Callout>
+
+To have the MCP server control your local desktop instead of a VM:
+
+1. **Start the Computer Server on your host:**
+
+```bash
+pip install cua-computer-server
+python -m computer_server
+```
+
+2. **Configure the MCP server to use your host system:**
+
+Add the `CUA_USE_HOST_COMPUTER_SERVER` environment variable to your MCP client configuration:
+
+<Tabs items={['Claude Desktop', 'Other MCP Clients']}>
+ <Tab value="Claude Desktop">
+ Update your Claude Desktop config (see [Installation](/docs/libraries/mcp-server/installation)) to include the environment variable:
+
+ ```json
+ {
+ "mcpServers": {
+ "cua-agent": {
+ "command": "/bin/bash",
+ "args": ["~/.cua/start_mcp_server.sh"],
+ "env": {
+ "CUA_MODEL_NAME": "anthropic/claude-sonnet-4-5-20250929",
+ "CUA_USE_HOST_COMPUTER_SERVER": "true"
+ }
+ }
+ }
+ }
+ ```
+
+ </Tab>
+ <Tab value="Other MCP Clients">
+ Set the environment variable in your MCP client configuration:
+
+ ```bash
+ export CUA_USE_HOST_COMPUTER_SERVER=true
+ ```
+
+ Then start your MCP client as usual.
+
+ </Tab>
+</Tabs>
+
+3. **Restart your MCP client** (e.g., Claude Desktop) to apply the changes.
+
+Now Claude will control your local desktop directly when you ask it to perform computer tasks.
+
+## Usage Examples
+
+### Single Task Execution
+
+```
+"Open Safari and navigate to apple.com"
+"Create a new folder on the desktop called 'My Projects'"
+"Take a screenshot of the current screen"
+```
+
+### Multi-Task Execution (Sequential)
+
+```
+"Run these tasks in order: 1) Open Finder, 2) Navigate to Documents folder, 3) Create a new folder called 'Work'"
+```
+
+### Multi-Task Execution (Concurrent)
+
+```
+"Run these tasks simultaneously: 1) Open Chrome, 2) Open Safari, 3) Open Finder"
+```
+
+### Session Management
+
+```
+"Show me the current session statistics"
+"Take a screenshot using session abc123"
+"Cleanup session xyz789"
+```
+
+### Error Recovery
+
+```
+"Try to open a non-existent application and show me the error"
+"Find all files with .tmp extension and delete them safely"
+```
+
+## First-time Usage Notes
+
+**API Keys**: Ensure you have valid API keys:
+
+- Add your Anthropic API key in the Claude Desktop config (as shown above)
+- Or set it as an environment variable in your shell profile
+- **Required**: The MCP server needs an API key to authenticate with the model provider
+
+**Model Selection**: Choose the appropriate model for your needs:
+
+- **Claude Sonnet 4**: Latest model with best performance (`anthropic/claude-sonnet-4-20250514`)
+- **Computer-Use Preview**: Specialized for computer tasks (`openai/computer-use-preview`)
+- **Local Models**: For privacy-sensitive environments
+- **Ollama**: For offline usage
diff --git a/docs/content/reference/agent-sdk/message-format.mdx b/docs/content/reference/agent-sdk/message-format.mdx
new file mode 100644
index 0000000000..ac329d4d20
--- /dev/null
+++ b/docs/content/reference/agent-sdk/message-format.mdx
@@ -0,0 +1,201 @@
+---
+title: Message Format
+---
+
+This page documents the Python message and response schema used by the Agent SDK.
+It mirrors the structure shown in Chat History and provides precise type definitions you can target in your own code.
+
+All examples below use Python type hints with `TypedDict` and `Literal` from the standard `typing` module.
+
+## Response
+
+The agent yields response chunks as an async generator of objects with `output` and `usage`.
+
+```python
+from typing import List, TypedDict
+
+class Usage(TypedDict, total=False):
+ prompt_tokens: int
+ completion_tokens: int
+ total_tokens: int
+ response_cost: float # USD cost if available
+
+class AgentResponse(TypedDict):
+ output: List["AgentMessage"]
+ usage: Usage
+```
+
+## Messages
+
+Agent messages represent the state of the conversation and the agent's actions.
+
+```python
+from typing import List, Literal, Optional, TypedDict, Union
+
+# Union of all message variants
+AgentMessage = Union[
+ "UserMessage",
+ "AssistantMessage",
+ "ReasoningMessage",
+ "ComputerCallMessage",
+ "ComputerCallOutputMessage",
+ "FunctionCallMessage",
+ "FunctionCallOutputMessage",
+]
+
+# Input message (role: user/system/developer)
+class UserMessage(TypedDict, total=False):
+ type: Literal["message"] # optional for user input
+ role: Literal["user", "system", "developer"]
+ content: Union[str, List["InputContent"]]
+
+# Output message (assistant text)
+class AssistantMessage(TypedDict):
+ type: Literal["message"]
+ role: Literal["assistant"]
+ content: List["OutputContent"]
+
+# Output reasoning/thinking message
+class ReasoningMessage(TypedDict):
+ type: Literal["reasoning"]
+ summary: List["SummaryContent"]
+
+# Output computer action call (agent intends to act)
+class ComputerCallMessage(TypedDict):
+ type: Literal["computer_call"]
+ call_id: str
+ status: Literal["completed", "failed", "pending"]
+ action: "ComputerAction"
+
+# Output computer action result (always a screenshot)
+class ComputerCallOutputMessage(TypedDict):
+ type: Literal["computer_call_output"]
+ call_id: str
+ output: "ComputerResultContent"
+
+# Output function call (agent calls a Python tool)
+class FunctionCallMessage(TypedDict):
+ type: Literal["function_call"]
+ call_id: str
+ status: Literal["completed", "failed", "pending"]
+ name: str
+ arguments: str # JSON-serialized kwargs
+
+# Output function call result (text)
+class FunctionCallOutputMessage(TypedDict):
+ type: Literal["function_call_output"]
+ call_id: str
+ output: str
+```
+
+## Message Content
+
+These content items appear inside `content` arrays for the message types above.
+
+```python
+# Input content kinds
+class InputContent(TypedDict):
+ type: Literal["input_image", "input_text"]
+ text: Optional[str]
+ image_url: Optional[str] # e.g., data URL
+
+# Assistant output content
+class OutputContent(TypedDict):
+ type: Literal["output_text"]
+ text: str
+
+# Reasoning/summary output content
+class SummaryContent(TypedDict):
+ type: Literal["summary_text"]
+ text: str
+
+# Computer call outputs (screenshots)
+class ComputerResultContent(TypedDict):
+ type: Literal["computer_screenshot", "input_image"]
+ image_url: str # data URL (e.g., "data:image/png;base64,....")
+```
+
+## Actions
+
+Computer actions represent concrete operations the agent will perform on the computer.
+
+Two broad families exist depending on the provider: OpenAI-style and Anthropic-style.
+
+```python
+# Union of all supported computer actions
+ComputerAction = Union[
+ "ClickAction",
+ "DoubleClickAction",
+ "DragAction",
+ "KeyPressAction",
+ "MoveAction",
+ "ScreenshotAction",
+ "ScrollAction",
+ "TypeAction",
+ "WaitAction",
+ # Anthropic variants
+ "LeftMouseDownAction",
+ "LeftMouseUpAction",
+]
+
+# OpenAI Computer Actions
+class ClickAction(TypedDict):
+ type: Literal["click"]
+ button: Literal["left", "right", "wheel", "back", "forward"]
+ x: int
+ y: int
+
+class DoubleClickAction(TypedDict, total=False):
+ type: Literal["double_click"]
+ button: Literal["left", "right", "wheel", "back", "forward"]
+ x: int
+ y: int
+
+class DragAction(TypedDict, total=False):
+ type: Literal["drag"]
+ button: Literal["left", "right", "wheel", "back", "forward"]
+ path: List[tuple[int, int]] # [(x1, y1), (x2, y2), ...]
+
+class KeyPressAction(TypedDict):
+ type: Literal["keypress"]
+ keys: List[str] # e.g., ["ctrl", "a"]
+
+class MoveAction(TypedDict):
+ type: Literal["move"]
+ x: int
+ y: int
+
+class ScreenshotAction(TypedDict):
+ type: Literal["screenshot"]
+
+class ScrollAction(TypedDict):
+ type: Literal["scroll"]
+ scroll_x: int
+ scroll_y: int
+ x: int
+ y: int
+
+class TypeAction(TypedDict):
+ type: Literal["type"]
+ text: str
+
+class WaitAction(TypedDict):
+ type: Literal["wait"]
+
+# Anthropic Computer Actions
+class LeftMouseDownAction(TypedDict):
+ type: Literal["left_mouse_down"]
+ x: int
+ y: int
+
+class LeftMouseUpAction(TypedDict):
+ type: Literal["left_mouse_up"]
+ x: int
+ y: int
+```
+
+## Notes
+
+- The agent runtime may add provider-specific fields when available (e.g., usage cost). Unknown fields should be ignored for forward compatibility.
+- Computer action outputs are screenshots as data URLs. For security and storage, some serializers may redact or omit large fields in persisted metadata.
+- The message flow typically alternates between reasoning, actions, screenshots, and concluding assistant text. See [Chat History](./chat-history) for a step-by-step example.
diff --git a/docs/content/docs/agent-sdk/meta.json b/docs/content/reference/agent-sdk/meta.json
similarity index 100%
rename from docs/content/docs/agent-sdk/meta.json
rename to docs/content/reference/agent-sdk/meta.json
diff --git a/docs/content/reference/agent-sdk/migration-guide.mdx b/docs/content/reference/agent-sdk/migration-guide.mdx
new file mode 100644
index 0000000000..fd67b282dc
--- /dev/null
+++ b/docs/content/reference/agent-sdk/migration-guide.mdx
@@ -0,0 +1,140 @@
+---
+title: Migration Guide
+---
+
+This guide lists **breaking changes** when migrating from the original `ComputerAgent` (v0.3.x) to the rewritten `ComputerAgent` (v0.4.x) and shows old vs new usage for all four agent loops.
+
+## Breaking Changes
+
+- **Initialization:**
+ - `ComputerAgent` (v0.4.x) uses `model` as a string (e.g. "anthropic/claude-sonnet-4-5-20250929") instead of `LLM` and `AgentLoop` objects.
+ - `tools` is a list (can include multiple computers and decorated functions).
+ - `callbacks` are now first-class for extensibility (image retention, budget, trajectory, logging, etc).
+- **No explicit `loop` parameter:**
+ - Loop is inferred from the `model` string (e.g. `anthropic/`, `openai/`, `omniparser+`, `ui-tars`).
+- **No explicit `computer` parameter:**
+ - Computers are added to `tools` list.
+
+---
+
+## Usage Examples: Old vs New
+
+### 1. Anthropic Loop
+
+**Old:**
+
+```python
+async with Computer() as computer:
+ agent = ComputerAgent(
+ computer=computer,
+ loop=AgentLoop.ANTHROPIC,
+ model=LLM(provider=LLMProvider.ANTHROPIC)
+ )
+ async for result in agent.run("Take a screenshot"):
+ print(result)
+```
+
+**New:**
+
+```python
+async with Computer() as computer:
+ agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+ )
+ messages = [{"role": "user", "content": "Take a screenshot"}]
+ async for result in agent.run(messages):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+```
+
+### 2. OpenAI Loop
+
+**Old:**
+
+```python
+async with Computer() as computer:
+ agent = ComputerAgent(
+ computer=computer,
+ loop=AgentLoop.OPENAI,
+ model=LLM(provider=LLMProvider.OPENAI)
+ )
+ async for result in agent.run("Take a screenshot"):
+ print(result)
+```
+
+**New:**
+
+```python
+async with Computer() as computer:
+ agent = ComputerAgent(
+ model="openai/computer-use-preview",
+ tools=[computer]
+ )
+ messages = [{"role": "user", "content": "Take a screenshot"}]
+ async for result in agent.run(messages):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+```
+
+### 3. UI-TARS Loop
+
+**Old:**
+
+```python
+async with Computer() as computer:
+ agent = ComputerAgent(
+ computer=computer,
+ loop=AgentLoop.UITARS,
+ model=LLM(provider=LLMProvider.OAICOMPAT, name="ByteDance-Seed/UI-TARS-1.5-7B", provider_base_url="https://.../v1")
+ )
+ async for result in agent.run("Take a screenshot"):
+ print(result)
+```
+
+**New:**
+
+```python
+async with Computer() as computer:
+ agent = ComputerAgent(
+ model="huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B",
+ tools=[computer]
+ )
+ messages = [{"role": "user", "content": "Take a screenshot"}]
+ async for result in agent.run(messages):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+```
+
+### 4. Omni Loop
+
+**Old:**
+
+```python
+async with Computer() as computer:
+ agent = ComputerAgent(
+ computer=computer,
+ loop=AgentLoop.OMNI,
+ model=LLM(provider=LLMProvider.OLLAMA, name="gemma3")
+ )
+ async for result in agent.run("Take a screenshot"):
+ print(result)
+```
+
+**New:**
+
+```python
+async with Computer() as computer:
+ agent = ComputerAgent(
+ model="omniparser+ollama_chat/gemma3",
+ tools=[computer]
+ )
+ messages = [{"role": "user", "content": "Take a screenshot"}]
+ async for result in agent.run(messages):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+```
diff --git a/docs/content/reference/agent-sdk/prompt-caching.mdx b/docs/content/reference/agent-sdk/prompt-caching.mdx
new file mode 100644
index 0000000000..633830ecf5
--- /dev/null
+++ b/docs/content/reference/agent-sdk/prompt-caching.mdx
@@ -0,0 +1,59 @@
+---
+title: Prompt Caching
+sidebar_position: 8
+description: How to use prompt caching in ComputerAgent and agent loops.
+---
+
+Prompt caching is a cost-saving feature offered by some LLM API providers that helps avoid reprocessing the same prompt, improving efficiency and reducing costs for repeated or long-running tasks.
+
+## Usage
+
+The `use_prompt_caching` argument is available for `ComputerAgent` and agent loops:
+
+```python
+agent = ComputerAgent(
+ ...,
+ use_prompt_caching=True,
+)
+```
+
+- **Type:** `bool`
+- **Default:** `False`
+- **Purpose:** Use prompt caching to avoid reprocessing the same prompt.
+
+## Anthropic CUAs
+
+When using Anthropic-based CUAs (Claude models), setting `use_prompt_caching=True` will automatically add `{ "cache_control": "ephemeral" }` to your messages. This enables prompt caching for the session and can speed up repeated runs with the same prompt.
+
+<Callout title="Note">
+ This argument is only required for Anthropic CUAs. For other providers, it is ignored.
+</Callout>
+
+## OpenAI Provider
+
+With the OpenAI provider, prompt caching is handled automatically for prompts of 1000+ tokens. You do **not** need to set `use_prompt_caching`—caching will occur for long prompts without any extra configuration.
+
+## Example
+
+```python
+from agent import ComputerAgent
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ use_prompt_caching=True,
+)
+```
+
+## Implementation Details
+
+- For Anthropic: Adds `{ "cache_control": "ephemeral" }` to messages when enabled.
+- For OpenAI: Caching is automatic for long prompts; the argument is ignored.
+
+## When to Use
+
+- Enable for Anthropic CUAs if you want to avoid reprocessing the same prompt in repeated or iterative tasks.
+- Not needed for OpenAI models unless you want explicit ephemeral cache control (not required for most users).
+
+## See Also
+
+- [Agent Loops](./agent-loops)
+- [Migration Guide](./migration-guide)
diff --git a/docs/content/docs/agent-sdk/supported-agents/composed-agents.mdx b/docs/content/reference/agent-sdk/supported-agents/composed-agents.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/supported-agents/composed-agents.mdx
rename to docs/content/reference/agent-sdk/supported-agents/composed-agents.mdx
diff --git a/docs/content/docs/agent-sdk/supported-agents/computer-use-agents.mdx b/docs/content/reference/agent-sdk/supported-agents/computer-use-agents.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/supported-agents/computer-use-agents.mdx
rename to docs/content/reference/agent-sdk/supported-agents/computer-use-agents.mdx
diff --git a/docs/content/docs/agent-sdk/supported-agents/grounding-models.mdx b/docs/content/reference/agent-sdk/supported-agents/grounding-models.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/supported-agents/grounding-models.mdx
rename to docs/content/reference/agent-sdk/supported-agents/grounding-models.mdx
diff --git a/docs/content/docs/agent-sdk/supported-agents/human-in-the-loop.mdx b/docs/content/reference/agent-sdk/supported-agents/human-in-the-loop.mdx
similarity index 100%
rename from docs/content/docs/agent-sdk/supported-agents/human-in-the-loop.mdx
rename to docs/content/reference/agent-sdk/supported-agents/human-in-the-loop.mdx
diff --git a/docs/content/docs/agent-sdk/supported-agents/meta.json b/docs/content/reference/agent-sdk/supported-agents/meta.json
similarity index 100%
rename from docs/content/docs/agent-sdk/supported-agents/meta.json
rename to docs/content/reference/agent-sdk/supported-agents/meta.json
diff --git a/docs/content/reference/agent-sdk/supported-model-providers/cua-vlm-router.mdx b/docs/content/reference/agent-sdk/supported-model-providers/cua-vlm-router.mdx
new file mode 100644
index 0000000000..d09cfe9f92
--- /dev/null
+++ b/docs/content/reference/agent-sdk/supported-model-providers/cua-vlm-router.mdx
@@ -0,0 +1,441 @@
+---
+title: Cua VLM Router
+description: Intelligent vision-language model routing with cost optimization and unified access
+---
+
+# Cua VLM Router
+
+The **Cua VLM Router** is an intelligent inference API that provides unified access to multiple vision-language model providers through a single API key. It offers cost optimization and detailed observability for production AI applications.
+
+## Overview
+
+Instead of managing multiple API keys and provider-specific code, Cua VLM Router acts as a smart cloud gateway that:
+
+- **Unifies access** to multiple model providers
+- **Optimizes costs** through intelligent routing and provider selection
+- **Tracks usage** and costs with detailed metadata
+- **Provides observability** with routing decisions and attempt logs
+- **Managed infrastructure** - no need to manage provider API keys yourself
+
+## Quick Start
+
+### 1. Get Your API Key
+
+Sign up at [cua.ai](https://cua.ai/signin) and get your Cua API key from the dashboard.
+
+### 2. Set Environment Variable
+
+```bash
+export CUA_API_KEY="sk_cua-api01_..."
+```
+
+### 3. Use with Agent SDK
+
+```python
+from agent import ComputerAgent
+from computer import Computer
+
+computer = Computer(os_type="linux", provider_type="docker")
+
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer],
+ max_trajectory_budget=5.0
+)
+
+messages = [{"role": "user", "content": "Take a screenshot and tell me what's on screen"}]
+
+async for result in agent.run(messages):
+ for item in result["output"]:
+ if item["type"] == "message":
+ print(item["content"][0]["text"])
+```
+
+## Available Models
+
+The Cua VLM Router currently supports these models:
+
+| Model ID | Provider | Description | Best For |
+| --------------------------------- | --------- | ----------------- | --------------------------------------- |
+| `cua/anthropic/claude-sonnet-4.5` | Anthropic | Claude Sonnet 4.5 | General-purpose tasks, recommended |
+| `cua/anthropic/claude-opus-4.5` | Anthropic | Claude Opus 4.5 | Enhanced agentic and computer-use tasks |
+| `cua/anthropic/claude-haiku-4.5` | Anthropic | Claude Haiku 4.5 | Fast responses, cost-effective |
+| `cua/qwen/qwen3-vl-235b` | Qwen | Qwen3 VL 235B | Large-scale vision-language tasks |
+
+## How It Works
+
+### Intelligent Routing
+
+When you make a request to Cua VLM Router:
+
+1. **Model Resolution**: Your model ID (e.g., `cua/anthropic/claude-sonnet-4.5`) is resolved to the appropriate provider
+2. **Provider Selection**: Cua routes your request to the appropriate model provider
+3. **Response**: You receive an OpenAI-compatible response with metadata
+
+## API Reference
+
+### Base URL
+
+```
+https://inference.cua.ai/v1
+```
+
+### Authentication
+
+All requests require an API key in the Authorization header:
+
+```bash
+Authorization: Bearer sk_cua-api01_...
+```
+
+### Endpoints
+
+#### List Available Models
+
+```bash
+GET /v1/models
+```
+
+**Response:**
+
+```json
+{
+ "data": [
+ {
+ "id": "anthropic/claude-sonnet-4.5",
+ "name": "Claude Sonnet 4.5",
+ "object": "model",
+ "owned_by": "cua"
+ }
+ ],
+ "object": "list"
+}
+```
+
+#### Chat Completions
+
+```bash
+POST /v1/chat/completions
+Content-Type: application/json
+```
+
+**Request:**
+
+```json
+{
+ "model": "anthropic/claude-sonnet-4.5",
+ "messages": [{ "role": "user", "content": "Hello!" }],
+ "max_tokens": 100,
+ "temperature": 0.7,
+ "stream": false
+}
+```
+
+**Response:**
+
+```json
+{
+ "id": "gen_...",
+ "object": "chat.completion",
+ "created": 1763554838,
+ "model": "anthropic/claude-sonnet-4.5",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": "Hello! How can I help you today?"
+ },
+ "finish_reason": "stop"
+ }
+ ],
+ "usage": {
+ "prompt_tokens": 10,
+ "completion_tokens": 12,
+ "total_tokens": 22,
+ "cost": 0.01,
+ "is_byok": true
+ }
+}
+```
+
+#### Streaming
+
+Set `"stream": true` to receive server-sent events:
+
+```bash
+curl -X POST https://inference.cua.ai/v1/chat/completions \
+ -H "Authorization: Bearer sk_cua-api01_..." \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "anthropic/claude-sonnet-4.5",
+ "messages": [{"role": "user", "content": "Count to 5"}],
+ "stream": true
+ }'
+```
+
+**Response (SSE format):**
+
+```
+data: {"id":"gen_...","choices":[{"delta":{"content":"1"}}],"object":"chat.completion.chunk"}
+
+data: {"id":"gen_...","choices":[{"delta":{"content":"\n2"}}],"object":"chat.completion.chunk"}
+
+data: {"id":"gen_...","choices":[{"delta":{"content":"\n3\n4\n5"}}],"object":"chat.completion.chunk"}
+
+data: {"id":"gen_...","choices":[{"delta":{},"finish_reason":"stop"}],"usage":{...}}
+```
+
+#### Check Balance
+
+```bash
+GET /v1/balance
+```
+
+**Response:**
+
+```json
+{
+ "balance": 211689.85,
+ "currency": "credits"
+}
+```
+
+## Cost Tracking
+
+CUA VLM Router provides detailed cost information in every response:
+
+### Credit System
+
+Requests are billed in **credits**:
+
+- Credits are deducted from your CUA account balance
+- Prices vary by model and usage
+- CUA manages all provider API keys and infrastructure
+
+### Response Cost Fields
+
+```json
+{
+ "usage": {
+ "cost": 0.01, // CUA gateway cost in credits
+ "market_cost": 0.000065 // Actual upstream API cost
+ }
+}
+```
+
+**Note:** Cua VLM Router is a fully managed cloud service. If you want to use your own provider API keys directly (BYOK), see the [Supported Model Providers](/agent-sdk/supported-model-providers/) page for direct provider access via the agent SDK.
+
+## Response Metadata
+
+Cua VLM Router includes metadata about routing decisions and costs in the response. This information helps with debugging and monitoring your application's model usage.
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required: Your Cua API key
+export CUA_API_KEY="sk_cua-api01_..."
+
+# Optional: Custom endpoint (defaults to https://inference.cua.ai/v1)
+export CUA_BASE_URL="https://custom-endpoint.cua.ai/v1"
+```
+
+### Python SDK Configuration
+
+```python
+from agent import ComputerAgent
+
+# Using environment variables (recommended)
+agent = ComputerAgent(model="cua/anthropic/claude-sonnet-4.5")
+
+# Or explicit configuration
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ # CUA adapter automatically loads from CUA_API_KEY
+)
+```
+
+## Benefits Over Direct Provider Access
+
+| Feature | Cua VLM Router | Direct Provider (BYOK) |
+| -------------------------- | ---------------------------- | --------------------------------- |
+| **Single API Key** | ✅ One key for all providers | ❌ Multiple keys to manage |
+| **Managed Infrastructure** | ✅ No API key management | ❌ Manage multiple provider keys |
+| **Usage Tracking** | ✅ Unified dashboard | ❌ Per-provider tracking |
+| **Model Switching** | ✅ Change model string only | ❌ Change code + keys |
+| **Setup Complexity** | ✅ One environment variable | ❌ Multiple environment variables |
+
+## Error Handling
+
+### Common Error Responses
+
+#### Invalid API Key
+
+```json
+{
+ "detail": "Insufficient credits. Current balance: 0.00 credits"
+}
+```
+
+#### Missing Authorization
+
+```json
+{
+ "detail": "Missing Authorization: Bearer token"
+}
+```
+
+#### Invalid Model
+
+```json
+{
+ "detail": "Invalid or unavailable model"
+}
+```
+
+### Best Practices
+
+1. **Check balance periodically** using `/v1/balance`
+2. **Handle rate limits** with exponential backoff
+3. **Log generation IDs** for debugging
+4. **Set up usage alerts** in your CUA dashboard
+
+## Examples
+
+### Basic Usage
+
+```python
+from agent import ComputerAgent
+from computer import Computer
+
+computer = Computer(os_type="linux", provider_type="docker")
+
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[computer]
+)
+
+messages = [{"role": "user", "content": "Open Firefox"}]
+
+async for result in agent.run(messages):
+ print(result)
+```
+
+### Direct API Call (curl)
+
+```bash
+curl -X POST https://inference.cua.ai/v1/chat/completions \
+ -H "Authorization: Bearer ${CUA_API_KEY}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "anthropic/claude-sonnet-4.5",
+ "messages": [
+ {"role": "user", "content": "Explain quantum computing"}
+ ],
+ "max_tokens": 200
+ }'
+```
+
+### With Custom Parameters
+
+```python
+agent = ComputerAgent(
+ model="cua/anthropic/claude-haiku-4.5",
+ tools=[computer],
+ max_trajectory_budget=10.0,
+ temperature=0.7
+)
+```
+
+### Using Qwen3 VL 235B
+
+```python
+from agent import ComputerAgent
+from computer import Computer
+
+computer = Computer(os_type="linux", provider_type="docker")
+
+agent = ComputerAgent(
+ model="cua/qwen/qwen3-vl-235b",
+ tools=[computer],
+ only_n_most_recent_images=3
+)
+
+messages = [{"role": "user", "content": "Open a browser and search for Python tutorials"}]
+
+async for result in agent.run(messages):
+ print(result)
+```
+
+### Using Claude Opus 4.5
+
+```python
+from agent import ComputerAgent
+from computer import Computer
+
+computer = Computer(
+ os_type="linux",
+ provider_type="cloud",
+ name="your-container-name",
+ api_key="your-cua-api-key"
+)
+
+agent = ComputerAgent(
+ model="cua/anthropic/claude-opus-4.5",
+ tools=[computer],
+ instructions="You are a helpful assistant that can control computers",
+ only_n_most_recent_images=3
+)
+
+messages = [{"role": "user", "content": "Open a browser and search for Python tutorials"}]
+
+async for result in agent.run(messages):
+ print(result)
+```
+
+## Migration from Direct Provider Access
+
+Switching from direct provider access (BYOK) to Cua VLM Router is simple:
+
+**Before (Direct Provider Access with BYOK):**
+
+```python
+import os
+# Required: Provider-specific API key
+os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..."
+
+agent = ComputerAgent(
+ model="anthropic/claude-sonnet-4-5-20250929",
+ tools=[computer]
+)
+```
+
+**After (Cua VLM Router - Cloud Service):**
+
+```python
+import os
+# Required: Cua API key only (no provider keys needed)
+os.environ["CUA_API_KEY"] = "sk_cua-api01_..."
+
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5", # Add "cua/" prefix
+ tools=[computer]
+)
+```
+
+That's it! Same code structure, just different model format. Cua manages all provider infrastructure and credentials for you.
+
+## Support
+
+- **Documentation**: [cua.ai/docs](https://cua.ai/docs)
+- **Discord**: [Join our community](https://discord.com/invite/mVnXXpdE85)
+- **Issues**: [GitHub Issues](https://github.com/trycua/cua/issues)
+
+## Next Steps
+
+- Explore [Agent Loops](/agent-sdk/agent-loops) to customize agent behavior
+- Learn about [Cost Saving Callbacks](/agent-sdk/callbacks/cost-saving)
+- Try [Example Use Cases](/example-usecases/form-filling)
+- Review [Supported Model Providers](/agent-sdk/supported-model-providers/) for all options
diff --git a/docs/content/reference/agent-sdk/supported-model-providers/index.mdx b/docs/content/reference/agent-sdk/supported-model-providers/index.mdx
new file mode 100644
index 0000000000..d27aab31dd
--- /dev/null
+++ b/docs/content/reference/agent-sdk/supported-model-providers/index.mdx
@@ -0,0 +1,118 @@
+---
+title: Supported Model Providers
+---
+
+## Supported Models
+
+### Cua VLM Router (Recommended)
+
+Use Cua's cloud inference API for intelligent routing and cost optimization with a single API key. Cua manages all provider infrastructure and credentials for you.
+
+```python
+# Anthropic Claude models
+model="cua/anthropic/claude-sonnet-4.5" # Claude Sonnet 4.5 (recommended)
+model="cua/anthropic/claude-haiku-4.5" # Claude Haiku 4.5 (faster)
+
+# Google Gemini models
+model="cua/google/gemini-3-pro-preview" # Gemini 3 Pro Preview (most powerful)
+model="cua/google/gemini-3-flash-preview" # Gemini 3 Flash Preview (fastest and cheapest, recommended for balance)
+```
+
+**Benefits:**
+
+- Single API key for multiple providers
+- Cost tracking and optimization
+- Fully managed infrastructure (no provider keys to manage)
+
+[Learn more about Cua VLM Router →](/agent-sdk/supported-model-providers/cua-vlm-router)
+
+---
+
+### Anthropic Claude (Computer Use API - BYOK)
+
+Access Anthropic's computer use models directly or through Azure AI Foundry using your own API key (BYOK).
+
+#### Via Anthropic API
+
+```python
+model="anthropic/claude-haiku-4-5-20251001" # Claude Haiku 4.5 (fastest, cost-effective)
+model="anthropic/claude-sonnet-4-5-20250929" # Claude Sonnet 4.5 (recommended)
+model="anthropic/claude-opus-4-5-20251101" # Claude Opus 4.5 (most advanced)
+```
+
+**Setup:** Set `ANTHROPIC_API_KEY` environment variable with your Anthropic API key.
+
+#### Via Azure AI Foundry
+
+```python
+model="anthropic/claude-haiku-4-5"
+model="anthropic/claude-sonnet-4-5"
+model="anthropic/claude-opus-4-5"
+```
+
+**Setup:**
+
+- Set `ANTHROPIC_API_KEY` environment variable with your Azure AI Foundry key
+- Set `ANTHROPIC_API_BASE` to your Azure endpoint (e.g., `https://<your-resource>.services.ai.azure.com/anthropic`)
+
+### OpenAI Computer Use Preview (BYOK)
+
+Direct access to OpenAI's computer use models using your own OpenAI API key (BYOK).
+
+```python
+model="openai/computer-use-preview"
+```
+
+**Setup:** Set `OPENAI_API_KEY` environment variable with your OpenAI API key.
+
+### Google Gemini (BYOK)
+
+Access Google's Gemini models with native computer use capabilities using your own credentials (BYOK).
+
+```python
+model="gemini-3-flash-preview" # Gemini 3 Flash (fastest, cheapest)
+model="gemini-2.5-computer-use-preview" # Computer Use Specific Gemini and general computer use
+model="gemini-3-pro-preview" # Gemini 3 Pro (most advanced)
+```
+
+**Setup Options:**
+
+#### Option 1: Google AI Studio (Recommended for quick start)
+
+Set the `GOOGLE_API_KEY` environment variable with your Google AI Studio API key.
+
+```bash
+export GOOGLE_API_KEY="your-google-ai-studio-key"
+```
+
+#### Option 2: Google Cloud Vertex AI
+
+For production deployments or enterprise use, configure Vertex AI credentials:
+
+```bash
+export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
+export GOOGLE_CLOUD_LOCATION="us-central1" # or your preferred region
+```
+
+**Note:** When `GOOGLE_API_KEY` is set, it takes precedence. If not set, the SDK will automatically use Vertex AI with the configured Google Cloud credentials.
+
+### UI-TARS (Local or Huggingface Inference)
+
+Run UI-TARS models locally for privacy and offline use.
+
+```python
+model="huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B"
+model="ollama_chat/0000/ui-tars-1.5-7b"
+```
+
+### Omniparser + Any LLM
+
+Combine Omniparser for UI understanding with any LLM provider.
+
+```python
+model="omniparser+ollama_chat/mistral-small3.2"
+model="omniparser+vertex_ai/gemini-pro"
+model="omniparser+anthropic/claude-sonnet-4-5-20250929"
+model="omniparser+openai/gpt-4o"
+```
diff --git a/docs/content/reference/agent-sdk/supported-model-providers/local-models.mdx b/docs/content/reference/agent-sdk/supported-model-providers/local-models.mdx
new file mode 100644
index 0000000000..b147a538f5
--- /dev/null
+++ b/docs/content/reference/agent-sdk/supported-model-providers/local-models.mdx
@@ -0,0 +1,35 @@
+---
+title: Running Models Locally
+---
+
+You can run open-source LLMs and vision models on your own machine using Cua, without relying on cloud APIs. This is ideal for development, privacy, or running on air-gapped systems.
+
+## Hugging Face (transformers)
+
+Use the `huggingface-local/` prefix to run any Hugging Face model locally via the `transformers` library. This supports most text and vision models from the Hugging Face Hub.
+
+**Example:**
+
+```python
+model = "huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B"
+```
+
+## MLX (Apple Silicon)
+
+Use the `mlx/` prefix to run models using the `mlx-vlm` library, optimized for Apple Silicon (M1/M2/M3). This allows fast, local inference for many open-source models.
+
+**Example:**
+
+```python
+model = "mlx/mlx-community/UI-TARS-1.5-7B-6bit"
+```
+
+## Ollama
+
+Use the `ollama_chat/` prefix to run models using the `ollama` library. This allows fast, local inference for many open-source models.
+
+**Example:**
+
+```python
+model = "omniparser+ollama_chat/llama3.2:latest"
+```
diff --git a/docs/content/reference/agent-sdk/telemetry.mdx b/docs/content/reference/agent-sdk/telemetry.mdx
new file mode 100644
index 0000000000..4dcb80a897
--- /dev/null
+++ b/docs/content/reference/agent-sdk/telemetry.mdx
@@ -0,0 +1,135 @@
+---
+title: Telemetry
+description: How telemetry works in Cua and how to control it
+---
+
+# Telemetry
+
+Cua collects anonymized usage and error statistics. We follow [Posthog's ethical telemetry approach](https://posthog.com/blog/open-source-telemetry-ethical). To opt out, set `telemetry_enabled` to false.
+
+## What we collect
+
+### Enabled by default (opt-out)
+
+- System info: OS, OS version, Python version
+- Module initialization: When modules are imported and their versions
+- Performance: Agent run durations, step counts, token usage, API costs
+- Session tracking: Anonymous session IDs and run IDs
+
+### Disabled by default (opt-in)
+
+**Trajectory logging** captures full conversation history:
+
+- User messages and agent responses
+- Computer actions and outputs
+- Agent reasoning traces
+
+Must be explicitly enabled.
+
+### We don't collect
+
+- Personal information or user identifiers
+- API keys or credentials
+- File contents or application data
+- Files being accessed
+- Screenshots or screen contents (unless trajectory logging is enabled)
+- Text being typed, user inputs, model outputs, computer outputs, or tool call outputs (unless trajectory logging is enabled)
+
+## How to disable
+
+### Environment variable (global)
+
+Set `CUA_TELEMETRY_ENABLED` to a falsy value (`0`, `false`, `no`, or `off`):
+
+```bash
+export CUA_TELEMETRY_ENABLED=false
+```
+
+Or in Python:
+
+```python
+import os
+os.environ["CUA_TELEMETRY_ENABLED"] = "false"
+```
+
+<Callout type="info">
+ **Deprecated environment variables:** The environment variables `CUA_TELEMETRY` and
+ `CUA_TELEMETRY_DISABLED` are deprecated and no longer have any effect. Use `CUA_TELEMETRY_ENABLED`
+ instead.
+</Callout>
+
+### Per instance
+
+**Computer SDK:**
+
+```python
+from computer import Computer
+
+computer = Computer(telemetry_enabled=False)
+```
+
+**Agent SDK:**
+
+```python
+from agent import ComputerAgent
+import os
+
+# Basic telemetry - performance metrics only (opt-out, enabled by default)
+agent = ComputerAgent(
+ model="claude-sonnet-4-5-20250929",
+ telemetry_enabled=True # Default is True
+)
+
+# Enable telemetry with full conversation trajectory logging (opt-in)
+agent = ComputerAgent(
+ model="claude-sonnet-4-5-20250929",
+ telemetry_enabled={
+ "log_trajectory": True # Logs full conversation items
+ }
+)
+
+# Disable completely
+agent = ComputerAgent(
+ model="claude-sonnet-4-5-20250929",
+ telemetry_enabled=False
+)
+
+# Enable trajectory logging (opt-in)
+agent = ComputerAgent(
+ model="claude-sonnet-4-5-20250929",
+ telemetry_enabled={"log_trajectory": True}
+)
+```
+
+Check status:
+
+```python
+print(computer.telemetry_enabled) # True or False
+print(agent.telemetry_enabled) # True, False, or dict
+```
+
+Telemetry settings are configured at initialization and can't be changed afterward.
+
+## Events collected
+
+### Computer SDK
+
+| Event Name | Data Collected | Trigger Notes |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| **computer_initialized** | • `os`: Operating system (e.g., 'windows', 'darwin', 'linux')<br />• `os_version`: OS version<br />• `python_version`: Python version | Triggered when a Computer instance is created |
+| **module_init** | • `module`: "computer"<br />• `version`: Package version<br />• `python_version`: Full Python version string | Triggered once when the computer package is imported for the first time |
+
+### Agent SDK
+
+| Event Name | Data Collected | Trigger Notes |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| **module_init** | • `module`: "agent"<br />• `version`: Package version<br />• `python_version`: Full Python version string | Triggered once when the agent package is imported for the first time |
+| **agent_session_start** | • `session_id`: Unique UUID for this agent instance<br />• `agent_type`: Class name (e.g., "ComputerAgent")<br />• `model`: Model name (e.g., "claude-sonnet-4-5")<br />• `os`: Operating system<br />• `os_version`: OS version<br />• `python_version`: Python version | Triggered when TelemetryCallback is initialized (agent instantiation) |
+| **agent_run_start** | • `session_id`: Agent session UUID<br />• `run_id`: Unique UUID for this run<br />• `start_time`: Unix timestamp<br />• `input_context_size`: Character count of input messages<br />• `num_existing_messages`: Count of existing messages<br />• `uploaded_trajectory`: Full conversation items (opt-in) | Triggered at the start of each agent.run() call |
+| **agent_run_end** | • `session_id`: Agent session UUID<br />• `run_id`: Run UUID<br />• `end_time`: Unix timestamp<br />• `duration_seconds`: Total run duration<br />• `num_steps`: Total steps taken in this run<br />• `total_usage`: Accumulated token usage and costs<br />• `uploaded_trajectory`: Full conversation items (opt-in) | Triggered at the end of each agent.run() call |
+| **agent_step** | • `session_id`: Agent session UUID<br />• `run_id`: Run UUID<br />• `step`: Step number (incremental)<br />• `timestamp`: Unix timestamp<br />• `duration_seconds`: Duration of previous step | Triggered on each agent response/step during a run |
+| **agent_usage** | • `session_id`: Agent session UUID<br />• `run_id`: Run UUID<br />• `step`: Current step number<br />• `prompt_tokens`: Tokens in prompt<br />• `completion_tokens`: Tokens in response<br />• `total_tokens`: Total tokens used<br />• `response_cost`: Cost of this API call | Triggered whenever usage information is received from LLM API |
+
+## Questions
+
+Questions about telemetry? Open an issue on our [GitHub repository](https://github.com/trycua/cua).
diff --git a/docs/content/reference/agent-sdk/usage-tracking.mdx b/docs/content/reference/agent-sdk/usage-tracking.mdx
new file mode 100644
index 0000000000..425c694e36
--- /dev/null
+++ b/docs/content/reference/agent-sdk/usage-tracking.mdx
@@ -0,0 +1,64 @@
+---
+title: Usage Tracking
+sidebar_position: 9
+description: How to track token usage and cost in ComputerAgent and agent loops.
+---
+
+Tracking usage is important for monitoring costs and optimizing your agent workflows. The ComputerAgent API provides easy access to token and cost usage for every run.
+
+## Accessing Usage Data
+
+Whenever you run an agent loop, each result contains a `usage` dictionary with token and cost information:
+
+```python
+async for result in agent.run(...):
+ print(result["usage"])
+ # Example output:
+ # {
+ # "prompt_tokens": 150,
+ # "completion_tokens": 75,
+ # "total_tokens": 225,
+ # "response_cost": 0.01,
+ # }
+```
+
+- `prompt_tokens`: Number of tokens in the prompt
+- `completion_tokens`: Number of tokens in the agent's response
+- `total_tokens`: Total tokens used
+- `response_cost`: Estimated cost (USD) for this turn
+
+## Tracking Total Usage
+
+You can accumulate usage across multiple turns:
+
+```python
+total_usage = {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "response_cost": 0.0}
+async for result in agent.run(...):
+ for k in total_usage:
+ total_usage[k] += result["usage"].get(k, 0)
+print("Total usage:", total_usage)
+```
+
+## Using Callbacks for Usage Tracking
+
+You can also use a callback to automatically track usage. Implement the `on_usage` method in your callback class:
+
+```python
+from agent.callbacks import AsyncCallbackHandler
+
+class UsageTrackerCallback(AsyncCallbackHandler):
+ async def on_usage(self, usage):
+ print("Usage update:", usage)
+
+agent = ComputerAgent(
+ ...,
+ callbacks=[UsageTrackerCallback()]
+)
+```
+
+See also: [Budget Manager Callbacks](./callbacks/cost-saving)
+
+## See Also
+
+- [Prompt Caching](./prompt-caching)
+- [Callbacks](./callbacks)
diff --git a/docs/content/reference/cli-playbook/commands.mdx b/docs/content/reference/cli-playbook/commands.mdx
new file mode 100644
index 0000000000..d123221c6b
--- /dev/null
+++ b/docs/content/reference/cli-playbook/commands.mdx
@@ -0,0 +1,433 @@
+---
+title: Command Reference
+description: Complete reference for all Cua CLI commands
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+## Overview
+
+The Cua CLI provides commands for authentication and sandbox management.
+
+### Command Styles
+
+The CLI supports **two command styles** for flexibility:
+
+**Flat style** (quick & concise):
+
+```bash
+cua list
+cua create --os linux --size small --region north-america
+cua start my-sandbox
+```
+
+**Grouped style** (explicit & clear):
+
+```bash
+cua sb list # or: cua sandbox list
+cua sb create # or: cua sandbox create
+cua sb start # or: cua sandbox start
+```
+
+Both styles work identically - use whichever you prefer!
+
+### Available Commands
+
+- **Authentication** - `cua auth login`, `cua auth env`, `cua auth logout` (also available as flat commands: `cua login`, `cua env`, `cua logout`)
+- **Sandbox Management** - `cua list`, `cua create`, `cua get`, `cua start`, `cua stop`, `cua restart`, `cua delete`, `cua vnc`
+
+## Authentication Commands
+
+### `cua auth login`
+
+Authenticate with your Cua account using browser-based OAuth flow.
+
+```bash
+# Interactive browser login
+cua auth login
+
+# Direct API key login
+cua auth login --api-key sk-your-api-key-here
+
+# Alternative flat style
+cua login
+cua login --api-key sk-your-api-key-here
+```
+
+**Options:**
+
+- `--api-key <key>` - Provide API key directly instead of browser flow
+
+**Example:**
+
+```bash
+$ cua auth login
+Opening browser for CLI auth...
+API key saved
+```
+
+### `cua auth env`
+
+Create or update a `.env` file in the current directory with your Cua API key.
+
+```bash
+cua auth env
+
+# Alternative flat style
+cua env
+```
+
+**Example:**
+
+```bash
+$ cua auth env
+Wrote /path/to/your/project/.env
+```
+
+The generated `.env` file will contain:
+
+```
+CUA_API_KEY=sk-your-api-key-here
+```
+
+### `cua auth logout`
+
+Remove the stored API key from your system.
+
+```bash
+cua auth logout
+
+# Alternative flat style
+cua logout
+```
+
+**Example:**
+
+```bash
+$ cua auth logout
+Logged out
+```
+
+## Sandbox Commands
+
+### `cua list`
+
+List all your sandboxes with their current status. Passwords are hidden by default for security.
+
+```bash
+# List sandboxes (passwords hidden)
+cua list
+
+# Show passwords explicitly
+cua list --show-passwords
+
+# Alternative aliases
+cua ls
+cua ps
+```
+
+**Example Output (default, passwords hidden):**
+
+```
+NAME STATUS HOST
+my-dev-sandbox running my-dev-sandbox.sandbox.cua.ai
+test-windows stopped test-windows.sandbox.cua.ai
+```
+
+**Example Output (with --show-passwords):**
+
+```
+NAME STATUS PASSWORD HOST
+my-dev-sandbox running secure-pass-123 my-dev-sandbox.sandbox.cua.ai
+test-windows stopped another-pass-456 test-windows.sandbox.cua.ai
+```
+
+### `cua create`
+
+Create a new sandbox.
+
+```bash
+cua create --os <OS> --size <SIZE> --region <REGION>
+```
+
+**Required Options:**
+
+- `--os` - Operating system: `linux`, `windows`, `macos`
+- `--size` - Sandbox size: `small`, `medium`, `large`
+- `--region` - Region: `north-america`, `europe`, `asia-pacific`, `south-america`
+
+**Examples:**
+
+```bash
+# Create a small Linux sandbox in North America
+cua create --os linux --size small --region north-america
+
+# Create a medium Windows sandbox in Europe
+cua create --os windows --size medium --region europe
+
+# Create a large macOS sandbox in Asia Pacific
+cua create --os macos --size large --region asia-pacific
+```
+
+**Response Types:**
+
+**Immediate (Status 200):**
+
+```bash
+Sandbox created and ready: my-new-sandbox-abc123
+Password: secure-password-here
+Host: my-new-sandbox-abc123.sandbox.cua.ai
+```
+
+**Provisioning (Status 202):**
+
+```bash
+Sandbox provisioning started: my-new-sandbox-abc123
+Job ID: job-xyz789
+Use 'cua list' to monitor provisioning progress
+```
+
+### `cua get`
+
+Get detailed information about a specific sandbox, including computer-server health status.
+
+```bash
+cua get <name>
+
+# With additional options
+cua get <name> --json
+cua get <name> --show-passwords
+cua get <name> --show-vnc-url
+```
+
+**Options:**
+
+- `--json` - Output all details in JSON format
+- `--show-passwords` - Include password in output
+- `--show-vnc-url` - Include computed NoVNC URL
+
+**Example Output (default):**
+
+```bash
+$ cua get my-dev-sandbox
+Name: my-dev-sandbox
+Status: running
+Host: my-dev-sandbox.containers.cloud.trycua.com
+OS Type: linux
+Computer Server Version: 0.1.30
+Computer Server Status: healthy
+```
+
+**Example Output (with --show-passwords and --show-vnc-url):**
+
+```bash
+$ cua get my-dev-sandbox --show-passwords --show-vnc-url
+Name: my-dev-sandbox
+Status: running
+Host: my-dev-sandbox.containers.cloud.trycua.com
+Password: secure-pass-123
+OS Type: linux
+Computer Server Version: 0.1.30
+Computer Server Status: healthy
+VNC URL: https://my-dev-sandbox.containers.cloud.trycua.com/vnc.html?autoconnect=true&password=secure-pass-123
+```
+
+**Example Output (JSON format):**
+
+```bash
+$ cua get my-dev-sandbox --json
+{
+ "name": "my-dev-sandbox",
+ "status": "running",
+ "host": "my-dev-sandbox.containers.cloud.trycua.com",
+ "os_type": "linux",
+ "computer_server_version": "0.1.30",
+ "computer_server_status": "healthy"
+}
+```
+
+**Computer Server Health Check:**
+
+The `cua get` command automatically probes the computer-server when the sandbox is running:
+
+- Checks OS type via `https://{host}:8443/status`
+- Checks version via `https://{host}:8443/cmd`
+- Shows "Computer Server Status: healthy" when both probes succeed
+- Uses a 3-second timeout for each probe
+
+<Callout type="info">
+ The computer server status is only checked for running sandboxes. Stopped or suspended sandboxes
+ will not show computer server information.
+</Callout>
+
+### `cua start`
+
+Start a stopped sandbox.
+
+```bash
+cua start <name>
+```
+
+**Example:**
+
+```bash
+$ cua start my-dev-sandbox
+Start accepted
+```
+
+### `cua stop`
+
+Stop a running sandbox.
+
+```bash
+cua stop <name>
+```
+
+**Example:**
+
+```bash
+$ cua stop my-dev-sandbox
+stopping
+```
+
+### `cua restart`
+
+Restart a sandbox.
+
+```bash
+cua restart <name>
+```
+
+**Example:**
+
+```bash
+$ cua restart my-dev-sandbox
+restarting
+```
+
+### `cua delete`
+
+Delete a sandbox permanently.
+
+```bash
+cua delete <name>
+```
+
+**Example:**
+
+```bash
+$ cua delete old-test-sandbox
+Sandbox deletion initiated: deleting
+```
+
+<Callout type="warn">
+ This action is irreversible. All data on the sandbox will be permanently lost.
+</Callout>
+
+### `cua vnc`
+
+Open the VNC interface for a sandbox in your browser.
+
+```bash
+cua vnc <name>
+
+# Alternative alias
+cua open <name>
+```
+
+**Example:**
+
+```bash
+$ cua vnc my-dev-sandbox
+Opening NoVNC: https://my-dev-sandbox.sandbox.cua.ai/vnc.html?autoconnect=true&password=...
+```
+
+This command automatically opens your default browser to the VNC interface with the correct password pre-filled.
+
+## Global Options
+
+### Help
+
+Get help for any command:
+
+```bash
+cua --help
+cua auth login --help
+cua create --help
+cua list --help
+```
+
+## Error Handling
+
+The CLI provides clear error messages for common issues:
+
+### Authentication Errors
+
+```bash
+$ cua list
+Unauthorized. Try 'cua auth login' again.
+```
+
+### Sandbox Not Found
+
+```bash
+$ cua start nonexistent-sandbox
+Sandbox not found
+```
+
+### Invalid Configuration
+
+```bash
+$ cua create --os invalid --configuration small --region north-america
+Invalid request or unsupported configuration
+```
+
+## Tips and Best Practices
+
+### 1. Use Descriptive Sandbox Names
+
+```bash
+# Good
+cua create --os linux --size small --region north-america
+# Then rename or use meaningful names in the dashboard
+
+# Better workflow
+cua list # Check the generated name
+# Use that name consistently
+```
+
+### 2. Environment Management
+
+```bash
+# Set up your project with API key
+cd my-project
+cua auth env
+# Now your project has CUA_API_KEY in .env
+```
+
+### 3. Quick Sandbox Access
+
+```bash
+# Create aliases for frequently used sandboxes
+alias dev-sandbox="cua vnc my-development-sandbox"
+alias prod-sandbox="cua vnc my-production-sandbox"
+```
+
+### 4. Monitoring Provisioning
+
+```bash
+# For sandboxes that need provisioning time
+cua create --os windows --size large --region europe
+# Sandbox provisioning started: my-sandbox-abc123
+# Job ID: job-xyz789
+
+# Check status periodically
+watch -n 5 cua list
+```
+
+## Next Steps
+
+- [Get started with the quickstart guide](/get-started/quickstart#cli-quickstart)
+- [Learn about CUA computers](/computer-sdk/computers)
+- [Explore agent automation](/agent-sdk/agent-loops)
diff --git a/docs/content/reference/cli-playbook/index.mdx b/docs/content/reference/cli-playbook/index.mdx
new file mode 100644
index 0000000000..f600cdce27
--- /dev/null
+++ b/docs/content/reference/cli-playbook/index.mdx
@@ -0,0 +1,63 @@
+---
+title: Getting Started
+description: Install and set up the Cua CLI
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+The Cua CLI is a command-line tool for managing your Cua cloud sandboxes. Create, start, stop, and connect to sandboxes directly from your terminal.
+
+## Installation
+
+<Tabs items={['macOS / Linux', 'Windows']}>
+ <Tab value="macOS / Linux">```bash curl -LsSf https://cua.ai/cli/install.sh | sh ```</Tab>
+ <Tab value="Windows">
+ ```powershell powershell -ExecutionPolicy ByPass -c "irm https://cua.ai/cli/install.ps1 | iex"
+ ```
+ </Tab>
+</Tabs>
+
+This installs [Bun](https://bun.sh) and the Cua CLI. Verify with:
+
+```bash
+cua --help
+```
+
+## Authentication
+
+Login to your Cua account:
+
+```bash
+# Browser-based login
+cua auth login
+
+# Or with API key
+cua auth login --api-key sk-your-api-key-here
+```
+
+Generate a `.env` file for your project:
+
+```bash
+cua auth env
+```
+
+## Quick Start
+
+```bash
+# Create a sandbox
+cua create --os linux --size small --region north-america
+
+# List sandboxes
+cua list
+
+# Open VNC in browser
+cua vnc my-sandbox
+
+# Stop a sandbox
+cua stop my-sandbox
+```
+
+## Next Steps
+
+- [Command Reference](/cli-playbook/commands) - Full list of available commands
diff --git a/docs/content/docs/cli-playbook/meta.json b/docs/content/reference/cli-playbook/meta.json
similarity index 100%
rename from docs/content/docs/cli-playbook/meta.json
rename to docs/content/reference/cli-playbook/meta.json
diff --git a/docs/content/reference/computer-sdk/cloud-vm-management.mdx b/docs/content/reference/computer-sdk/cloud-vm-management.mdx
new file mode 100644
index 0000000000..21174bd4f3
--- /dev/null
+++ b/docs/content/reference/computer-sdk/cloud-vm-management.mdx
@@ -0,0 +1,267 @@
+---
+title: Cloud Sandbox Management
+description: Manage your Cua Cloud sandboxes via Python SDK or HTTP API
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+Using the Cua Cloud API, you can manage your Cua Cloud sandboxes with Python or HTTP (curl).
+
+All examples require a Cua API key. You can obtain one from the [Dashboard](https://www.cua.ai/dashboard/keys).
+
+---
+
+## List Sandboxes
+
+<Tabs items={['Python', 'curl']}>
+ <Tab value="Python">
+
+```python
+import asyncio
+from computer.providers.cloud.provider import CloudProvider
+
+async def main():
+ # CloudProvider automatically reads CUA_API_KEY from environment
+ # You can also pass api_key explicitly: CloudProvider(api_key="your-api-key")
+ # Optional: point to a different API base
+ # os.environ["CUA_API_BASE"] = "https://api.cua.ai"
+
+ provider = CloudProvider(verbose=False)
+ async with provider:
+ vms = await provider.list_vms()
+ for vm in vms:
+ print({
+ "name": vm["name"],
+ "status": vm["status"],
+ "api_url": vm.get("api_url"),
+ "vnc_url": vm.get("vnc_url"),
+ })
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+ </Tab>
+ <Tab value="curl">
+
+```bash
+curl -H "Authorization: Bearer $CUA_API_KEY" \
+ "https://api.cua.ai/v1/vms"
+```
+
+Responses:
+
+- 200: Array of minimal sandbox objects with fields `{ name, password, status }`
+- 401: Unauthorized (missing/invalid API key)
+
+```json
+[
+ {
+ "name": "s-windows-x4snp46ebf",
+ "password": "49b8daa3",
+ "status": "running"
+ }
+]
+```
+
+Status values:
+
+- `pending`: Sandbox deployment in progress
+- `running`: Sandbox is active and accessible
+- `stopped`: Sandbox is stopped but not terminated
+- `terminated`: Sandbox has been permanently destroyed
+- `failed`: Sandbox deployment or operation failed
+
+---
+
+ </Tab>
+
+ </Tabs>
+
+---
+
+## Start a Sandbox
+
+Provide the sandbox name you want to start.
+
+<Tabs items={["Python", "curl"]}>
+ <Tab value="Python">
+
+```python
+import asyncio
+from computer.providers.cloud.provider import CloudProvider
+
+async def main():
+ # CloudProvider automatically reads CUA_API_KEY from environment
+ name = "my-vm-name" # e.g., "m-linux-96lcxd2c2k"
+
+ provider = CloudProvider()
+ async with provider:
+ resp = await provider.run_vm(name)
+ print(resp) # { "name": name, "status": "starting" }
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+ </Tab>
+ <Tab value="curl">
+
+```bash
+curl -X POST \
+ -H "Authorization: Bearer $CUA_API_KEY" \
+ "https://api.cua.ai/v1/vms/my-vm-name/start" -i
+```
+
+Responses:
+
+- 204: No Content (start accepted)
+- 401: Unauthorized (missing/invalid API key)
+- 404: Sandbox not found or not owned by the user
+
+```text
+HTTP/1.1 204 No Content
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+## Stop a Sandbox
+
+Stops the sandbox asynchronously.
+
+<Tabs items={["Python", "curl"]}>
+ <Tab value="Python">
+
+```python
+import asyncio
+from computer.providers.cloud.provider import CloudProvider
+
+async def main():
+ # CloudProvider automatically reads CUA_API_KEY from environment
+ name = "my-vm-name"
+
+ provider = CloudProvider()
+ async with provider:
+ resp = await provider.stop_vm(name)
+ print(resp) # { "name": name, "status": "stopping" }
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+ </Tab>
+ <Tab value="curl">
+
+```bash
+curl -X POST \
+ -H "Authorization: Bearer $CUA_API_KEY" \
+ "https://api.cua.ai/v1/vms/my-vm-name/stop"
+```
+
+Responses:
+
+- 202: Accepted with `{ "status": "stopping" }`
+- 401: Unauthorized (missing/invalid API key)
+- 404: Sandbox not found or not owned by the user
+
+```json
+{ "status": "stopping" }
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+## Restart a Sandbox
+
+Restarts the sandbox asynchronously.
+
+<Tabs items={["Python", "curl"]}>
+ <Tab value="Python">
+
+```python
+import asyncio
+from computer.providers.cloud.provider import CloudProvider
+
+async def main():
+ # CloudProvider automatically reads CUA_API_KEY from environment
+ name = "my-vm-name"
+
+ provider = CloudProvider()
+ async with provider:
+ resp = await provider.restart_vm(name)
+ print(resp) # { "name": name, "status": "restarting" }
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+ </Tab>
+ <Tab value="curl">
+
+```bash
+curl -X POST \
+ -H "Authorization: Bearer $CUA_API_KEY" \
+ "https://api.cua.ai/v1/vms/my-vm-name/restart"
+```
+
+Responses:
+
+- 202: Accepted with `{ "status": "restarting" }`
+- 401: Unauthorized (missing/invalid API key)
+- 404: Sandbox not found or not owned by the user
+
+```json
+{ "status": "restarting" }
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+## Query a Sandbox by name
+
+Query the computer-server running on the sandbox. Useful for checking details like status or OS type.
+
+<Tabs items={["Python", "curl"]}>
+ <Tab value="Python">
+
+```python
+import asyncio
+from computer.providers.cloud.provider import CloudProvider
+
+async def main():
+ # CloudProvider automatically reads CUA_API_KEY from environment
+ name = "my-vm-name"
+
+ provider = CloudProvider()
+ async with provider:
+ info = await provider.get_vm(name)
+ print(info)
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+ </Tab>
+ <Tab value="curl">
+
+```bash
+curl "https://my-vm-name.containers.cloud.cua.ai:8443/status"
+```
+
+Responses:
+
+- 200: Server available
+
+```json
+{ "status": "ok", "os_type": "linux", "features": ["agent"] }
+```
+
+ </Tab>
+</Tabs>
diff --git a/docs/content/reference/computer-sdk/commands.mdx b/docs/content/reference/computer-sdk/commands.mdx
new file mode 100644
index 0000000000..4fc7b0ffdb
--- /dev/null
+++ b/docs/content/reference/computer-sdk/commands.mdx
@@ -0,0 +1,383 @@
+---
+title: Commands
+description: Computer commands and interface methods
+---
+
+This page describes the set of supported **commands** you can use to control a Cua Computer Framework directly via the Python SDK.
+
+These commands map to the same actions available in the [Computer Server API Commands Reference](/computer-sdk/computer-server/Commands), and provide low-level, async access to system operations from your agent or automation code.
+
+## Shell Actions
+
+Execute shell commands and get detailed results:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ ```python
+ # Run shell command
+ result = await computer.interface.run_command(cmd) # result.stdout, result.stderr, result.returncode
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ ```typescript
+ // Run shell command
+ const result = await computer.interface.runCommand(cmd); // result.stdout, result.stderr, result.returncode
+ ```
+
+ </Tab>
+</Tabs>
+
+## Window Management
+
+Control application launching and windows:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ ```python
+ # Launch applications
+ await computer.interface.launch("xfce4-terminal")
+ await computer.interface.launch("libreoffice --writer")
+ await computer.interface.open("https://www.google.com")
+
+ # Window management
+ windows = await computer.interface.get_application_windows("xfce4-terminal")
+ window_id = windows[0]
+ await computer.interface.activate_window(window_id)
+
+ window_id = await computer.interface.get_current_window_id() # get the current active window id
+ await computer.interface.window_size(window_id)
+ await computer.interface.get_window_title(window_id)
+ await computer.interface.get_window_position(window_id)
+ await computer.interface.set_window_size(window_id, 1200, 800)
+ await computer.interface.set_window_position(window_id, 100, 100)
+ await computer.interface.maximize_window(window_id)
+ await computer.interface.minimize_window(window_id)
+ await computer.interface.close_window(window_id)
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ ```typescript
+ // Launch applications
+ await computer.interface.launch("xfce4-terminal");
+ await computer.interface.launch("libreoffice --writer");
+ await computer.interface.open("https://www.google.com");
+
+ // Window management
+ const windows = await computer.interface.getApplicationWindows("xfce4-terminal");
+ let windowId = windows[0];
+ await computer.interface.activateWindow(windowId);
+
+ windowId = await computer.interface.getCurrentWindowId(); // current active window id
+ await computer.interface.getWindowSize(windowId);
+ await computer.interface.getWindowName(windowId);
+ await computer.interface.getWindowPosition(windowId);
+ await computer.interface.setWindowSize(windowId, 1200, 800);
+ await computer.interface.setWindowPosition(windowId, 100, 100);
+ await computer.interface.maximizeWindow(windowId);
+ await computer.interface.minimizeWindow(windowId);
+ await computer.interface.closeWindow(windowId);
+ ```
+
+ </Tab>
+</Tabs>
+
+## Mouse Actions
+
+Precise mouse control and interaction:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ ```python
+ # Basic clicks
+ await computer.interface.left_click(x, y) # Left click at coordinates
+ await computer.interface.right_click(x, y) # Right click at coordinates
+ await computer.interface.double_click(x, y) # Double click at coordinates
+
+ # Cursor movement and dragging
+ await computer.interface.move_cursor(x, y) # Move cursor to coordinates
+ await computer.interface.drag_to(x, y, duration) # Drag to coordinates
+ await computer.interface.get_cursor_position() # Get current cursor position
+
+ # Advanced mouse control
+ await computer.interface.mouse_down(x, y, button="left") # Press and hold a mouse button
+ await computer.interface.mouse_up(x, y, button="left") # Release a mouse button
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ ```typescript
+ // Basic clicks
+ await computer.interface.leftClick(x, y); // Left click at coordinates
+ await computer.interface.rightClick(x, y); // Right click at coordinates
+ await computer.interface.doubleClick(x, y); // Double click at coordinates
+
+ // Cursor movement and dragging
+ await computer.interface.moveCursor(x, y); // Move cursor to coordinates
+ await computer.interface.dragTo(x, y, duration); // Drag to coordinates
+ await computer.interface.getCursorPosition(); // Get current cursor position
+
+ // Advanced mouse control
+ await computer.interface.mouseDown(x, y, "left"); // Press and hold a mouse button
+ await computer.interface.mouseUp(x, y, "left"); // Release a mouse button
+ ```
+
+ </Tab>
+</Tabs>
+
+## Keyboard Actions
+
+Text input and key combinations:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ ```python
+ # Text input
+ await computer.interface.type_text("Hello") # Type text
+ await computer.interface.press_key("enter") # Press a single key
+
+ # Key combinations and advanced control
+ await computer.interface.hotkey("command", "c") # Press key combination
+ await computer.interface.key_down("command") # Press and hold a key
+ await computer.interface.key_up("command") # Release a key
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ ```typescript
+ // Text input
+ await computer.interface.typeText("Hello"); // Type text
+ await computer.interface.pressKey("enter"); // Press a single key
+
+ // Key combinations and advanced control
+ await computer.interface.hotkey("command", "c"); // Press key combination
+ await computer.interface.keyDown("command"); // Press and hold a key
+ await computer.interface.keyUp("command"); // Release a key
+ ```
+
+ </Tab>
+</Tabs>
+
+## Scrolling Actions
+
+Mouse wheel and scrolling control:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ ```python
+ # Scrolling
+ await computer.interface.scroll(x, y) # Scroll the mouse wheel
+ await computer.interface.scroll_down(clicks) # Scroll down
+ await computer.interface.scroll_up(clicks) # Scroll up
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ ```typescript
+ // Scrolling
+ await computer.interface.scroll(x, y); // Scroll the mouse wheel
+ await computer.interface.scrollDown(clicks); // Scroll down
+ await computer.interface.scrollUp(clicks); // Scroll up
+ ```
+
+ </Tab>
+</Tabs>
+
+## Screen Actions
+
+Screen capture and display information:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ ```python
+ # Screen operations
+ await computer.interface.screenshot() # Take a screenshot
+ await computer.interface.get_screen_size() # Get screen dimensions
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ ```typescript
+ // Screen operations
+ await computer.interface.screenshot(); // Take a screenshot
+ await computer.interface.getScreenSize(); // Get screen dimensions
+ ```
+
+ </Tab>
+</Tabs>
+
+## Desktop Actions
+
+Control desktop environment features like wallpaper:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+ ```python
+ # Get current desktop environment (e.g., 'xfce4', 'gnome', 'kde', 'mac', 'windows')
+ env = await computer.interface.get_desktop_environment()
+ print(env) # "xfce4"
+
+ # Set desktop wallpaper to an image file accessible on the sandbox
+ await computer.interface.set_wallpaper("/home/cua/shared/wallpaper.png")
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+ ```typescript
+ // Get current desktop environment
+ const env = await computer.interface.getDesktopEnvironment();
+ print(env) # "xfce4"
+
+ // Set desktop wallpaper to an image file accessible on the sandbox
+ await computer.interface.setWallpaper('/home/cua/shared/wallpaper.png');
+ ```
+
+ </Tab>
+</Tabs>
+
+## Clipboard Actions
+
+System clipboard management:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ ```python
+ # Clipboard operations
+ await computer.interface.set_clipboard(text) # Set clipboard content
+ await computer.interface.copy_to_clipboard() # Get clipboard content
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ ```typescript
+ // Clipboard operations
+ await computer.interface.setClipboard(text); // Set clipboard content
+ await computer.interface.copyToClipboard(); // Get clipboard content
+ ```
+
+ </Tab>
+</Tabs>
+
+## File System Operations
+
+Direct file and directory manipulation:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ ```python
+ # File existence checks
+ await computer.interface.file_exists(path) # Check if file exists
+ await computer.interface.directory_exists(path) # Check if directory exists
+
+ # File content operations
+ await computer.interface.read_text(path, encoding="utf-8") # Read file content
+ await computer.interface.write_text(path, content, encoding="utf-8") # Write file content
+ await computer.interface.read_bytes(path) # Read file content as bytes
+ await computer.interface.write_bytes(path, content) # Write file content as bytes
+
+ # File and directory management
+ await computer.interface.delete_file(path) # Delete file
+ await computer.interface.create_dir(path) # Create directory
+ await computer.interface.delete_dir(path) # Delete directory
+ await computer.interface.list_dir(path) # List directory contents
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ ```typescript
+ // File existence checks
+ await computer.interface.fileExists(path); // Check if file exists
+ await computer.interface.directoryExists(path); // Check if directory exists
+
+ // File content operations
+ await computer.interface.readText(path, "utf-8"); // Read file content
+ await computer.interface.writeText(path, content, "utf-8"); // Write file content
+ await computer.interface.readBytes(path); // Read file content as bytes
+ await computer.interface.writeBytes(path, content); // Write file content as bytes
+
+ // File and directory management
+ await computer.interface.deleteFile(path); // Delete file
+ await computer.interface.createDir(path); // Create directory
+ await computer.interface.deleteDir(path); // Delete directory
+ await computer.interface.listDir(path); // List directory contents
+ ```
+
+ </Tab>
+</Tabs>
+
+## Accessibility
+
+Access system accessibility information:
+
+<Tabs items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+ ```python
+ # Get accessibility tree
+ await computer.interface.get_accessibility_tree()
+ ```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+ ```typescript
+ // Get accessibility tree
+ await computer.interface.getAccessibilityTree();
+ ```
+
+ </Tab>
+</Tabs>
+
+## Delay Configuration
+
+Control timing between actions:
+
+<Tabs items={['Python']}>
+ <Tab value="Python">
+
+ ```python
+ # Set default delay between all actions (in seconds)
+ computer.interface.delay = 0.5 # 500ms delay between actions
+
+ # Or specify delay for individual actions
+ await computer.interface.left_click(x, y, delay=1.0) # 1 second delay after click
+ await computer.interface.type_text("Hello", delay=0.2) # 200ms delay after typing
+ await computer.interface.press_key("enter", delay=0.5) # 500ms delay after key press
+ ```
+
+ </Tab>
+</Tabs>
+
+## Python Virtual Environment Operations
+
+Manage Python environments:
+
+<Tabs items={['Python']}>
+ <Tab value="Python">
+
+ ```python
+ # Virtual environment management
+ await computer.venv_install("demo_venv", ["requests", "macos-pyxa"]) # Install packages in a virtual environment
+ await computer.venv_cmd("demo_venv", "python -c 'import requests; print(requests.get(`https://httpbin.org/ip`).json())'') # Run a shell command in a virtual environment
+ await computer.venv_exec("demo_venv", python_function_or_code, *args, **kwargs) # Run a Python function in a virtual environment and return the result / raise an exception
+ ```
+
+ </Tab>
+</Tabs>
diff --git a/docs/content/docs/computer-sdk/computer-server/Commands.mdx b/docs/content/reference/computer-sdk/computer-server/Commands.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/computer-server/Commands.mdx
rename to docs/content/reference/computer-sdk/computer-server/Commands.mdx
diff --git a/docs/content/docs/computer-sdk/computer-server/REST-API.mdx b/docs/content/reference/computer-sdk/computer-server/REST-API.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/computer-server/REST-API.mdx
rename to docs/content/reference/computer-sdk/computer-server/REST-API.mdx
diff --git a/docs/content/docs/computer-sdk/computer-server/WebSocket-API.mdx b/docs/content/reference/computer-sdk/computer-server/WebSocket-API.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/computer-server/WebSocket-API.mdx
rename to docs/content/reference/computer-sdk/computer-server/WebSocket-API.mdx
diff --git a/docs/content/docs/computer-sdk/computer-server/index.mdx b/docs/content/reference/computer-sdk/computer-server/index.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/computer-server/index.mdx
rename to docs/content/reference/computer-sdk/computer-server/index.mdx
diff --git a/docs/content/docs/computer-sdk/computer-server/meta.json b/docs/content/reference/computer-sdk/computer-server/meta.json
similarity index 100%
rename from docs/content/docs/computer-sdk/computer-server/meta.json
rename to docs/content/reference/computer-sdk/computer-server/meta.json
diff --git a/docs/content/reference/computer-sdk/computer-ui.mdx b/docs/content/reference/computer-sdk/computer-ui.mdx
new file mode 100644
index 0000000000..3e576f03d5
--- /dev/null
+++ b/docs/content/reference/computer-sdk/computer-ui.mdx
@@ -0,0 +1,99 @@
+---
+title: Computer UI
+---
+
+<Callout type="warn" title="Deprecated">
+ The Computer UI is deprecated and will be replaced with a revamped playground experience soon. We
+ recommend using VNC or Screen Sharing for precise control of the computer instead.
+</Callout>
+
+The computer module includes a Gradio UI for creating and sharing demonstration data. We make it easy for people to build community datasets for better computer use models with an upload to Huggingface feature.
+
+```bash
+# Install with UI support
+pip install "cua-computer[ui]"
+```
+
+<Callout title="Note">
+ For precise control of the computer, we recommend using VNC or Screen Sharing instead of the
+ Computer Gradio UI.
+</Callout>
+
+### Building and Sharing Demonstrations with Huggingface
+
+Follow these steps to contribute your own demonstrations:
+
+#### 1. Set up Huggingface Access
+
+Set your HF_TOKEN in a .env file or in your environment variables:
+
+```bash
+# In .env file
+HF_TOKEN=your_huggingface_token
+```
+
+#### 2. Launch the Computer UI
+
+```python
+# launch_ui.py
+from computer.ui.gradio.app import create_gradio_ui
+from dotenv import load_dotenv
+load_dotenv('.env')
+
+app = create_gradio_ui()
+app.launch(share=False)
+```
+
+For examples, see [Computer UI Examples](https://github.com/trycua/cua/tree/main/examples/computer_ui_examples.py)
+
+#### 3. Record Your Tasks
+
+<details open>
+ <summary>View demonstration video</summary>
+ <video
+ src="https://github.com/user-attachments/assets/de3c3477-62fe-413c-998d-4063e48de176"
+ controls
+ width="600"
+ ></video>
+</details>
+
+Record yourself performing various computer tasks using the UI.
+
+#### 4. Save Your Demonstrations
+
+<details open>
+ <summary>View demonstration video</summary>
+ <video
+ src="https://github.com/user-attachments/assets/5ad1df37-026a-457f-8b49-922ae805faef"
+ controls
+ width="600"
+ ></video>
+</details>
+
+Save each task by picking a descriptive name and adding relevant tags (e.g., "office", "web-browsing", "coding").
+
+#### 5. Record Additional Demonstrations
+
+Repeat steps 3 and 4 until you have a good amount of demonstrations covering different tasks and scenarios.
+
+#### 6. Upload to Huggingface
+
+<details open>
+ <summary>View demonstration video</summary>
+ <video
+ src="https://github.com/user-attachments/assets/c586d460-3877-4b5f-a736-3248886d2134"
+ controls
+ width="600"
+ ></video>
+</details>
+
+Upload your dataset to Huggingface by:
+
+- Naming it as `{your_username}/{dataset_name}`
+- Choosing public or private visibility
+- Optionally selecting specific tags to upload only tasks with certain tags
+
+#### Examples and Resources
+
+- Example Dataset: [ddupont/test-dataset](https://huggingface.co/datasets/ddupont/test-dataset)
+- Find Community Datasets: 🔍 [Browse CUA Datasets on Huggingface](https://huggingface.co/datasets?other=cua)
diff --git a/docs/content/docs/computer-sdk/computers.mdx b/docs/content/reference/computer-sdk/computers.mdx
similarity index 100%
rename from docs/content/docs/computer-sdk/computers.mdx
rename to docs/content/reference/computer-sdk/computers.mdx
diff --git a/docs/content/reference/computer-sdk/custom-computer-handlers.mdx b/docs/content/reference/computer-sdk/custom-computer-handlers.mdx
new file mode 100644
index 0000000000..d166888344
--- /dev/null
+++ b/docs/content/reference/computer-sdk/custom-computer-handlers.mdx
@@ -0,0 +1,130 @@
+---
+title: Custom Computers
+slug: custom-computer-handlers
+---
+
+The Agent SDK supports defining custom computer handlers using a simple dictionary interface. This enables integration with custom automation backends, testing frameworks, or specialized computer control systems.
+
+## Example: Defining a Custom Computer Handler
+
+```python
+import asyncio
+from PIL import Image
+
+# Define your custom computer functions
+async def take_screenshot():
+ """Your custom screenshot implementation"""
+ # Return PIL Image, bytes, or base64 string
+ return Image.new('RGB', (1920, 1080), color='white')
+
+# Create dict-based computer handler - only 'screenshot' is required
+custom_computer = {
+ 'screenshot': take_screenshot, # required
+
+ # everything below is optional
+ 'environment': 'linux', # linux, mac, windows, browser
+ 'dimensions': (1920, 1080), # (width, height)
+ 'click': lambda x, y, button: print(f"Clicking at ({x}, {y}) with {button} button"),
+}
+```
+
+You can then use this as a tool for your agent:
+
+```python
+from agent import ComputerAgent
+
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[custom_computer],
+)
+
+# Agent will automatically convert dict to agent.computers.CustomComputerHandler
+await agent.run("Take a screenshot and click at coordinates 100, 200")
+```
+
+## Class-Based Implementation
+
+For more complex implementations, you can create a custom class by inheriting from `AsyncComputerHandler`:
+
+```python
+from agent.computers import AsyncComputerHandler
+from PIL import Image
+from typing import Literal, List, Dict, Union, Optional
+
+class MyCustomComputer(AsyncComputerHandler):
+ """Custom computer handler implementation."""
+
+ def __init__(self):
+ # Initialize your custom computer interface here
+ pass
+
+ # ==== Computer-Use-Preview Action Space ====
+
+ async def get_environment(self) -> Literal["windows", "mac", "linux", "browser"]:
+ """Get the current environment type."""
+ ...
+
+ async def get_dimensions(self) -> tuple[int, int]:
+ """Get screen dimensions as (width, height)."""
+ ...
+
+ async def screenshot(self) -> str:
+ """Take a screenshot and return as base64 string."""
+ ...
+
+ async def click(self, x: int, y: int, button: str = "left") -> None:
+ """Click at coordinates with specified button."""
+ ...
+
+ async def double_click(self, x: int, y: int) -> None:
+ """Double click at coordinates."""
+ ...
+
+ async def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) -> None:
+ """Scroll at coordinates with specified scroll amounts."""
+ ...
+
+ async def type(self, text: str) -> None:
+ """Type text."""
+ ...
+
+ async def wait(self, ms: int = 1000) -> None:
+ """Wait for specified milliseconds."""
+ ...
+
+ async def move(self, x: int, y: int) -> None:
+ """Move cursor to coordinates."""
+ ...
+
+ async def keypress(self, keys: Union[List[str], str]) -> None:
+ """Press key combination."""
+ ...
+
+ async def drag(self, path: List[Dict[str, int]]) -> None:
+ """Drag along specified path."""
+ ...
+
+ async def get_current_url(self) -> str:
+ """Get current URL (for browser environments)."""
+ ...
+
+ # ==== Anthropic Action Space ====
+
+ async def left_mouse_down(self, x: Optional[int] = None, y: Optional[int] = None) -> None:
+ """Left mouse down at coordinates."""
+ ...
+
+ async def left_mouse_up(self, x: Optional[int] = None, y: Optional[int] = None) -> None:
+ """Left mouse up at coordinates."""
+ ...
+
+# Use with agent
+custom_computer = MyCustomComputer()
+
+agent = ComputerAgent(
+ model="cua/anthropic/claude-sonnet-4.5",
+ tools=[custom_computer],
+)
+
+await agent.run("Take a screenshot and click at coordinates 100, 200")
+```
diff --git a/docs/content/docs/computer-sdk/meta.json b/docs/content/reference/computer-sdk/meta.json
similarity index 100%
rename from docs/content/docs/computer-sdk/meta.json
rename to docs/content/reference/computer-sdk/meta.json
diff --git a/docs/content/reference/computer-sdk/sandboxed-python.mdx b/docs/content/reference/computer-sdk/sandboxed-python.mdx
new file mode 100644
index 0000000000..8db37c13f5
--- /dev/null
+++ b/docs/content/reference/computer-sdk/sandboxed-python.mdx
@@ -0,0 +1,86 @@
+---
+title: Sandboxed Python
+slug: sandboxed-python
+---
+
+<Callout>
+ A corresponding{' '}
+ <a
+ href="https://github.com/trycua/cua/blob/main/examples/sandboxed_functions_examples.py"
+ target="_blank"
+ >
+ Python example
+ </a>{' '}
+ is available for this documentation.
+</Callout>
+
+You can run Python functions securely inside a sandboxed virtual environment on a remote Cua Computer Framework. This is useful for executing untrusted user code, isolating dependencies, or providing a safe environment for automation tasks.
+
+## How It Works
+
+The `sandboxed` decorator from the Computer SDK wraps a Python function so that it is executed remotely in a specified virtual environment on the target Computer. The function and its arguments are serialized, sent to the remote, and executed in isolation. Results or errors are returned to the caller.
+
+## Example Usage
+
+```python
+from computer import Computer
+from computer.helpers import sandboxed
+
+@sandboxed()
+def read_file(location: str) -> str:
+ """Read contents of a file"""
+ with open(location, 'r') as f:
+ return f.read()
+
+async def main():
+ async with Computer(os_type="linux", provider_type="cloud", name="my-sandbox", api_key="...") as computer:
+ # Call the sandboxed function (runs remotely)
+ result = await read_file("/etc/hostname")
+ print(result)
+```
+
+## Installing Python Packages
+
+You can specify the virtual environment name and target computer:
+
+```python
+@sandboxed(venv_name="myenv", computer=my_computer, max_retries=5)
+def my_function(...):
+ ...
+```
+
+You can also install packages in the virtual environment using the `venv_install` method:
+
+```python
+await my_computer.venv_install("myenv", ["requests"])
+```
+
+## Example: Interacting with macOS Applications
+
+You can use sandboxed functions to interact with macOS applications on a local Cua Computer Framework (requires `os_type="darwin"`). This is particularly useful for automation tasks that involve GUI applications.
+
+```python
+# Example: Use sandboxed functions to execute code in a Cua Sandbox
+from computer.helpers import sandboxed
+
+await computer.venv_install("demo_venv", ["macos-pyxa"]) # Install packages in a virtual environment
+
+@sandboxed("demo_venv")
+def greet_and_print(name):
+ """Get the HTML of the current Safari tab"""
+ import PyXA
+ safari = PyXA.Application("Safari")
+ html = safari.current_document.source()
+ print(f"Hello from inside the sandbox, {name}!")
+ return {"greeted": name, "safari_html": html}
+
+# When a @sandboxed function is called, it will execute in the sandbox
+result = await greet_and_print("Cua")
+# Result: {"greeted": "Cua", "safari_html": "<html>...</html>"}
+# stdout and stderr are also captured and printed / raised
+print("Result from sandboxed function:", result)
+```
+
+## Error Handling
+
+If the remote execution fails, the decorator will retry up to `max_retries` times. If all attempts fail, the last exception is raised locally.
diff --git a/docs/content/reference/computer-sdk/tracing-api.mdx b/docs/content/reference/computer-sdk/tracing-api.mdx
new file mode 100644
index 0000000000..9595b144aa
--- /dev/null
+++ b/docs/content/reference/computer-sdk/tracing-api.mdx
@@ -0,0 +1,345 @@
+---
+title: Tracing
+description: Record computer interactions for debugging, training, and analysis
+---
+
+# Tracing
+
+The Computer tracing API provides a powerful way to record computer interactions for debugging, training, analysis, and compliance purposes. Inspired by Playwright's tracing functionality, it offers flexible recording options and standardized output formats.
+
+## Overview
+
+The tracing API allows you to:
+
+- Record screenshots at key moments
+- Log all API calls and their results
+- Capture accessibility tree snapshots
+- Add custom metadata
+- Export recordings in standardized formats
+- Support for both automated and human-in-the-loop workflows
+
+## Basic Usage
+
+### Starting and Stopping Traces
+
+```python
+from computer import Computer
+
+computer = Computer(os_type="macos")
+await computer.run()
+
+# Start tracing with default options
+await computer.tracing.start()
+
+# Perform some operations
+await computer.interface.left_click(100, 200)
+await computer.interface.type_text("Hello, World!")
+await computer.interface.press_key("enter")
+
+# Stop tracing and save
+trace_path = await computer.tracing.stop()
+print(f"Trace saved to: {trace_path}")
+```
+
+### Custom Configuration
+
+```python
+# Start tracing with custom configuration
+await computer.tracing.start({
+ 'video': False, # Record video frames
+ 'screenshots': True, # Record screenshots (default: True)
+ 'api_calls': True, # Record API calls (default: True)
+ 'accessibility_tree': True, # Record accessibility snapshots
+ 'metadata': True, # Allow custom metadata (default: True)
+ 'name': 'my_custom_trace', # Custom trace name
+ 'path': './my_traces' # Custom output directory
+})
+
+# Add custom metadata during tracing
+await computer.tracing.add_metadata('user_id', 'user123')
+await computer.tracing.add_metadata('test_case', 'login_flow')
+
+# Stop with custom options
+trace_path = await computer.tracing.stop({
+ 'path': './exports/trace.zip',
+ 'format': 'zip' # 'zip' or 'dir'
+})
+```
+
+## Configuration Options
+
+### Start Options
+
+| Option | Type | Default | Description |
+| -------------------- | ---- | -------------- | ------------------------------------- |
+| `video` | bool | `False` | Record video frames (future feature) |
+| `screenshots` | bool | `True` | Capture screenshots after key actions |
+| `api_calls` | bool | `True` | Log all interface method calls |
+| `accessibility_tree` | bool | `False` | Record accessibility tree snapshots |
+| `metadata` | bool | `True` | Enable custom metadata recording |
+| `name` | str | auto-generated | Custom name for the trace |
+| `path` | str | auto-generated | Custom directory for trace files |
+
+### Stop Options
+
+| Option | Type | Default | Description |
+| -------- | ---- | -------------- | ---------------------------------- |
+| `path` | str | auto-generated | Custom output path for final trace |
+| `format` | str | `'zip'` | Output format: `'zip'` or `'dir'` |
+
+## Use Cases
+
+### Custom Agent Development
+
+```python
+from computer import Computer
+
+async def test_custom_agent():
+ computer = Computer(os_type="linux")
+ await computer.run()
+
+ # Start tracing for this test session
+ await computer.tracing.start({
+ 'name': 'custom_agent_test',
+ 'screenshots': True,
+ 'accessibility_tree': True
+ })
+
+ # Your custom agent logic here
+ screenshot = await computer.interface.screenshot()
+ await computer.interface.left_click(500, 300)
+ await computer.interface.type_text("test input")
+
+ # Add context about what the agent is doing
+ await computer.tracing.add_metadata('action', 'filling_form')
+ await computer.tracing.add_metadata('confidence', 0.95)
+
+ # Save the trace
+ trace_path = await computer.tracing.stop()
+ return trace_path
+```
+
+### Training Data Collection
+
+```python
+async def collect_training_data():
+ computer = Computer(os_type="macos")
+ await computer.run()
+
+ tasks = [
+ "open_browser_and_search",
+ "create_document",
+ "send_email"
+ ]
+
+ for task in tasks:
+ # Start a new trace for each task
+ await computer.tracing.start({
+ 'name': f'training_{task}',
+ 'screenshots': True,
+ 'accessibility_tree': True,
+ 'metadata': True
+ })
+
+ # Add task metadata
+ await computer.tracing.add_metadata('task_type', task)
+ await computer.tracing.add_metadata('difficulty', 'beginner')
+
+ # Perform the task (automated or human-guided)
+ await perform_task(computer, task)
+
+ # Save this training example
+ await computer.tracing.stop({
+ 'path': f'./training_data/{task}.zip'
+ })
+```
+
+### Human-in-the-Loop Recording
+
+```python
+async def record_human_demonstration():
+ computer = Computer(os_type="windows")
+ await computer.run()
+
+ # Start recording human demonstration
+ await computer.tracing.start({
+ 'name': 'human_demo_excel_workflow',
+ 'screenshots': True,
+ 'api_calls': True, # Will capture any programmatic actions
+ 'metadata': True
+ })
+
+ print("Trace recording started. Perform your demonstration...")
+ print("The system will record all computer interactions.")
+
+ # Add metadata about the demonstration
+ await computer.tracing.add_metadata('demonstrator', 'expert_user')
+ await computer.tracing.add_metadata('workflow', 'excel_data_analysis')
+
+ # Human performs actions manually or through other tools
+ # Tracing will still capture any programmatic interactions
+
+ input("Press Enter when demonstration is complete...")
+
+ # Stop and save the demonstration
+ trace_path = await computer.tracing.stop()
+ print(f"Human demonstration saved to: {trace_path}")
+```
+
+### RPA Debugging
+
+```python
+async def debug_rpa_workflow():
+ computer = Computer(os_type="linux")
+ await computer.run()
+
+ # Start tracing with full debugging info
+ await computer.tracing.start({
+ 'name': 'rpa_debug_session',
+ 'screenshots': True,
+ 'accessibility_tree': True,
+ 'api_calls': True
+ })
+
+ try:
+ # Your RPA workflow
+ await rpa_login_sequence(computer)
+ await rpa_data_entry(computer)
+ await rpa_generate_report(computer)
+
+ await computer.tracing.add_metadata('status', 'success')
+
+ except Exception as e:
+ # Record the error in the trace
+ await computer.tracing.add_metadata('error', str(e))
+ await computer.tracing.add_metadata('status', 'failed')
+ raise
+ finally:
+ # Always save the debug trace
+ trace_path = await computer.tracing.stop()
+ print(f"Debug trace saved to: {trace_path}")
+```
+
+## Output Format
+
+### Directory Structure
+
+When using `format='dir'`, traces are saved with this structure:
+
+```
+trace_20240922_143052_abc123/
+├── trace_metadata.json # Overall trace information
+├── event_000001_trace_start.json
+├── event_000002_api_call.json
+├── event_000003_api_call.json
+├── 000001_initial_screenshot.png
+├── 000002_after_left_click.png
+├── 000003_after_type_text.png
+└── event_000004_trace_end.json
+```
+
+### Metadata Format
+
+The `trace_metadata.json` contains:
+
+```json
+{
+ "trace_id": "trace_20240922_143052_abc123",
+ "config": {
+ "screenshots": true,
+ "api_calls": true,
+ "accessibility_tree": false,
+ "metadata": true
+ },
+ "start_time": 1695392252.123,
+ "end_time": 1695392267.456,
+ "duration": 15.333,
+ "total_events": 12,
+ "screenshot_count": 5,
+ "events": [...] // All events in chronological order
+}
+```
+
+### Event Format
+
+Individual events follow this structure:
+
+```json
+{
+ "type": "api_call",
+ "timestamp": 1695392255.789,
+ "relative_time": 3.666,
+ "data": {
+ "method": "left_click",
+ "args": { "x": 100, "y": 200, "delay": null },
+ "result": null,
+ "error": null,
+ "screenshot": "000002_after_left_click.png",
+ "success": true
+ }
+}
+```
+
+## Integration with ComputerAgent
+
+The tracing API works seamlessly with existing ComputerAgent workflows:
+
+```python
+from agent import ComputerAgent
+from computer import Computer
+
+# Create computer and start tracing
+computer = Computer(os_type="macos")
+await computer.run()
+
+await computer.tracing.start({
+ 'name': 'agent_with_tracing',
+ 'screenshots': True,
+ 'metadata': True
+})
+
+# Create agent using the same computer
+agent = ComputerAgent(
+ model="openai/computer-use-preview",
+ tools=[computer]
+)
+
+# Agent operations will be automatically traced
+async for _ in agent.run("open cua.ai and navigate to docs"):
+ pass
+
+# Save the combined trace
+trace_path = await computer.tracing.stop()
+```
+
+## Privacy Considerations
+
+The tracing API is designed with privacy in mind:
+
+- Clipboard content is not recorded (only content length)
+- Screenshots can be disabled
+- Sensitive text input can be filtered
+- Custom metadata allows you to control what information is recorded
+
+## Comparison with ComputerAgent Trajectories
+
+| Feature | ComputerAgent Trajectories | Computer.tracing |
+| ---------------------- | -------------------------- | -------------------- |
+| **Scope** | ComputerAgent only | Any Computer usage |
+| **Flexibility** | Fixed format | Configurable options |
+| **Custom Agents** | Not supported | Fully supported |
+| **Human-in-the-loop** | Limited | Full support |
+| **Real-time Control** | No | Start/stop anytime |
+| **Output Format** | Agent-specific | Standardized |
+| **Accessibility Data** | No | Optional |
+
+## Best Practices
+
+1. **Start tracing early**: Begin recording before your main workflow to capture the complete session
+2. **Use meaningful names**: Provide descriptive trace names for easier organization
+3. **Add contextual metadata**: Include information about what you're testing or demonstrating
+4. **Handle errors gracefully**: Always stop tracing in a finally block
+5. **Choose appropriate options**: Only record what you need to minimize overhead
+6. **Organize output**: Use custom paths to organize traces by project or use case
+
+The Computer tracing API provides a powerful foundation for recording, analyzing, and improving computer automation workflows across all use cases.
diff --git a/docs/content/reference/index.mdx b/docs/content/reference/index.mdx
new file mode 100644
index 0000000000..9f16e17499
--- /dev/null
+++ b/docs/content/reference/index.mdx
@@ -0,0 +1,54 @@
+---
+title: Reference
+description: SDK and CLI reference documentation
+---
+
+import { Bot, Monitor, Terminal, Server } from 'lucide-react';
+
+<div className="not-prose -mt-2 mb-6">
+ <p className="text-fd-primary font-semibold text-sm mb-1">Reference</p>
+ <h1 className="text-3xl font-bold tracking-tight md:text-4xl">API Reference</h1>
+</div>
+
+Complete reference documentation for all Cua SDKs and CLIs. Find detailed API documentation, configuration options, and usage examples.
+
+## SDKs
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mt-6">
+ <Card
+ icon={<Bot className="w-4 h-4" />}
+ href="/reference/agent-sdk/agent-loops"
+ title="Agent SDK"
+ description="Build computer-using agents with the Agent SDK"
+ />
+ <Card
+ icon={<Monitor className="w-4 h-4" />}
+ href="/reference/computer-sdk/computers"
+ title="Computer SDK"
+ description="Manage computer sandboxes and automation"
+ />
+</div>
+
+## CLIs
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mt-6">
+ <Card
+ icon={<Terminal className="w-4 h-4" />}
+ href="/reference/cli-playbook"
+ title="Cloud CLI"
+ description="Manage Cua Cloud resources from the command line"
+ />
+ <Card
+ icon={<Server className="w-4 h-4" />}
+ href="/reference/macos-vm-cli-playbook/lume"
+ title="macOS VM CLI"
+ description="Manage local macOS virtual machines with Lume"
+ />
+</div>
+
+## Quick Links
+
+- [Agent Loops](/reference/agent-sdk/agent-loops) - Understanding how agent loops work
+- [Supported Model Providers](/reference/agent-sdk/supported-model-providers) - Configure your preferred LLM provider
+- [Custom Tools](/reference/agent-sdk/custom-tools) - Extend agents with custom functionality
+- [Benchmarks](/reference/agent-sdk/benchmarks) - Evaluate agent performance
diff --git a/docs/content/reference/macos-vm-cli-playbook/lume/cli-reference.mdx b/docs/content/reference/macos-vm-cli-playbook/lume/cli-reference.mdx
new file mode 100644
index 0000000000..201206163f
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lume/cli-reference.mdx
@@ -0,0 +1,238 @@
+---
+title: Lume CLI Reference
+description: Command Line Interface reference for Lume
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Once installed, you can start using Lume with these common workflows:
+
+### Run a Prebuilt VM
+
+```bash
+# Run a macOS Sequoia VM
+lume run macos-sequoia-vanilla:latest
+
+# Run an Ubuntu VM
+lume run ubuntu-noble-vanilla:latest
+```
+
+<Callout>
+ We provide [prebuilt VM images](../lume/prebuilt-images) in our [ghcr
+ registry](https://github.com/orgs/trycua/packages).
+</Callout>
+
+### Create a Custom VM
+
+```bash
+# Create a new macOS VM
+lume create my-macos-vm --cpu 4 --memory 8GB --disk-size 50GB
+
+# Create a Linux VM
+lume create my-linux-vm --os linux --cpu 2 --memory 4GB
+```
+
+<Callout title="Disk Space">
+The actual disk space used by sparse images will be much lower than the logical size listed. You can resize VM disks after creation using `lume set <name> --disk-size <size>`.
+</Callout>
+
+## VM Management
+
+lume create &lt;name&gt;
+Create a new macOS or Linux virtual machine.
+
+**Options:**
+
+- `--os <os>` - Operating system to install (macOS or linux, default: macOS)
+- `--cpu <cores>` - Number of CPU cores (default: 4)
+- `--memory <size>` - Memory size, e.g., 8GB (default: 4GB)
+- `--disk-size <size>` - Disk size, e.g., 50GB (default: 40GB)
+- `--display <res>` - Display resolution (default: 1024x768)
+- `--ipsw <path>` - Path to IPSW file or 'latest' for macOS VMs
+- `--storage <name>` - VM storage location to use
+
+**Examples:**
+
+```bash
+# Create macOS VM with custom specs
+lume create my-mac --cpu 6 --memory 16GB --disk-size 100GB
+
+# Create Linux VM
+lume create my-ubuntu --os linux --cpu 2 --memory 8GB
+
+# Create macOS VM with latest IPSW
+lume create my-sequoia --ipsw latest
+```
+
+lume run &lt;name&gt;
+Start and run a virtual machine.
+
+**Options:**
+
+- `--no-display` - Do not start the VNC client app
+- `--shared-dir <dir>` - Share directory with VM (format: path[:ro|rw])
+- `--mount <path>` - For Linux VMs only, attach a read-only disk image
+- `--registry <url>` - Container registry URL (default: ghcr.io)
+- `--organization <org>` - Organization to pull from (default: trycua)
+- `--vnc-port <port>` - Port to use for the VNC server (default: 0 for auto-assign)
+- `--recovery-mode <boolean>` - For macOS VMs only, start VM in recovery mode (default: false)
+- `--storage <name>` - VM storage location to use
+
+**Examples:**
+
+```bash
+# Run VM with shared directory
+lume run my-vm --shared-dir /path/to/share:rw
+
+# Run VM without display (headless)
+lume run my-vm --no-display
+
+# Run macOS VM in recovery mode
+lume run my-mac --recovery-mode true
+```
+
+lume stop &lt;name&gt;
+Stop a running virtual machine.
+
+**Options:**
+
+- `--storage <name>` - VM storage location to use
+
+### lume delete &lt;name&gt;
+
+Delete a virtual machine and its associated files.
+
+**Options:**
+
+- `--force` - Force deletion without confirmation
+- `--storage <name>` - VM storage location to use
+
+### lume clone &lt;name&gt; &lt;new-name&gt;
+
+Create a copy of an existing virtual machine.
+
+**Options:**
+
+- `--source-storage <name>` - Source VM storage location
+- `--dest-storage <name>` - Destination VM storage location
+
+## VM Information and Configuration
+
+### lume ls
+
+List all virtual machines and their status.
+
+### lume get &lt;name&gt;
+
+Get detailed information about a specific virtual machine.
+
+**Options:**
+
+- `-f, --format <format>` - Output format (json|text)
+- `--storage <name>` - VM storage location to use
+
+### lume set &lt;name&gt;
+
+Modify virtual machine configuration.
+
+**Options:**
+
+- `--cpu <cores>` - New number of CPU cores (e.g., 4)
+- `--memory <size>` - New memory size (e.g., 8192MB or 8GB)
+- `--disk-size <size>` - New disk size (e.g., 40960MB or 40GB)
+- `--display <res>` - New display resolution in format WIDTHxHEIGHT (e.g., 1024x768)
+- `--storage <name>` - VM storage location to use
+
+**Examples:**
+
+```bash
+# Increase VM memory
+lume set my-vm --memory 16GB
+
+# Change display resolution
+lume set my-vm --display 1920x1080
+
+# Add more CPU cores
+lume set my-vm --cpu 8
+```
+
+## Image Management
+
+### lume images
+
+List available macOS images in local cache.
+
+### lume pull &lt;image&gt;
+
+Download a VM image from a container registry.
+
+**Options:**
+
+- `--registry <url>` - Container registry URL (default: ghcr.io)
+- `--organization <org>` - Organization to pull from (default: trycua)
+- `--storage <name>` - VM storage location to use
+
+### lume push &lt;name&gt; &lt;image:tag&gt;
+
+Upload a VM image to a container registry.
+
+**Options:**
+
+- `--additional-tags <tags...>` - Additional tags to push the same image to
+- `--registry <url>` - Container registry URL (default: ghcr.io)
+- `--organization <org>` - Organization/user to push to (default: trycua)
+- `--storage <name>` - VM storage location to use
+- `--chunk-size-mb <size>` - Chunk size for disk image upload in MB (default: 512)
+- `--verbose` - Enable verbose logging
+- `--dry-run` - Prepare files and show plan without uploading
+- `--reassemble` - Verify integrity by reassembling chunks (requires --dry-run)
+
+### lume ipsw
+
+Get the latest macOS restore image URL.
+
+### lume prune
+
+Remove cached images to free up disk space.
+
+## Configuration
+
+### lume config
+
+Manage Lume configuration settings.
+
+**Subcommands:**
+
+##### Storage Management
+
+- `lume config storage add <name> <path>` - Add a new VM storage location
+- `lume config storage remove <name>` - Remove a VM storage location
+- `lume config storage list` - List all VM storage locations
+- `lume config storage default <name>` - Set the default VM storage location
+
+##### Cache Management
+
+- `lume config cache get` - Get current cache directory
+- `lume config cache set <path>` - Set cache directory
+
+##### Image Caching
+
+- `lume config caching get` - Show current caching status
+- `lume config caching set <boolean>` - Enable or disable image caching
+
+## API Server
+
+### lume serve
+
+Start the Lume API server for programmatic access.
+
+**Options:**
+
+- `--port <port>` - Port to listen on (default: 7777)
+
+## Global Options
+
+These options are available for all commands:
+
+- `--help` - Show help information
+- `--version` - Show version number
diff --git a/docs/content/reference/macos-vm-cli-playbook/lume/faq.md b/docs/content/reference/macos-vm-cli-playbook/lume/faq.md
new file mode 100644
index 0000000000..4009a94ec2
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lume/faq.md
@@ -0,0 +1,120 @@
+---
+title: FAQ
+---
+
+### Where are the VMs stored?
+
+VMs are stored in `~/.lume` by default. You can configure additional storage locations using the `lume config` command.
+
+### How are images cached?
+
+Images are cached in `~/.lume/cache`. When doing `lume pull <image>`, it will check if the image is already cached. If not, it will download the image and cache it, removing any older versions.
+
+### Where is the configuration file stored?
+
+Lume follows the XDG Base Directory specification for the configuration file:
+
+- Configuration is stored in `$XDG_CONFIG_HOME/lume/config.yaml` (defaults to `~/.config/lume/config.yaml`)
+
+By default, other data is stored in:
+
+- VM data: `~/.lume`
+- Cache files: `~/.lume/cache`
+
+The config file contains settings for:
+
+- VM storage locations and the default location
+- Cache directory location
+- Whether caching is enabled
+
+You can view and modify these settings using the `lume config` commands:
+
+```bash
+# View current configuration
+lume config get
+
+# Manage VM storage locations
+lume config storage list # List all VM storage locations
+lume config storage add <name> <path> # Add a new VM storage location
+lume config storage remove <name> # Remove a VM storage location
+lume config storage default <name> # Set the default VM storage location
+
+# Manage cache settings
+lume config cache get # Get current cache directory
+lume config cache set <path> # Set cache directory
+
+# Manage image caching settings
+lume config caching get # Show current caching status
+lume config caching set <boolean> # Enable or disable image caching
+```
+
+### How do I use multiple VM storage locations?
+
+Lume supports storing VMs in different locations (e.g., internal drive, external SSD). After configuring storage locations, you can specify which location to use with the `--storage` parameter in various commands:
+
+```bash
+# Create a VM in a specific storage location
+lume create my-vm --os macos --ipsw latest --storage ssd
+
+# Run a VM from a specific storage location
+lume run my-vm --storage ssd
+
+# Delete a VM from a specific storage location
+lume delete my-vm --storage ssd
+
+# Pull an image to a specific storage location
+lume pull macos-sequoia-vanilla:latest --name my-vm --storage ssd
+
+# Clone a VM between storage locations
+lume clone source-vm cloned-vm --source-storage default --dest-storage ssd
+```
+
+If you don't specify a storage location, Lume will use the default one or search across all configured locations.
+
+### Are VM disks taking up all the disk space?
+
+No, macOS uses sparse files, which only allocate space as needed. For example, VM disks totaling 50 GB may only use 20 GB on disk.
+
+### How do I get the latest macOS restore image URL?
+
+```bash
+lume ipsw
+```
+
+### How do I delete a VM?
+
+```bash
+lume delete <name>
+```
+
+### How to Install macOS from an IPSW Image
+
+#### Create a new macOS VM using the latest supported IPSW image:
+
+Run the following command to create a new macOS virtual machine using the latest available IPSW image:
+
+```bash
+lume create <name> --os macos --ipsw latest
+```
+
+#### Create a new macOS VM using a specific IPSW image:
+
+To create a macOS virtual machine from an older or specific IPSW file, first download the desired IPSW (UniversalMac) from a trusted source.
+
+Then, use the downloaded IPSW path:
+
+```bash
+lume create <name> --os macos --ipsw <downloaded_ipsw_path>
+```
+
+### How do I install a custom Linux image?
+
+The process for creating a custom Linux image differs than macOS, with IPSW restore files not being used. You need to create a linux VM first, then mount a setup image file to the VM for the first boot.
+
+```bash
+lume create <name> --os linux
+
+lume run <name> --mount <path-to-setup-image>
+
+lume run <name>
+```
diff --git a/docs/content/reference/macos-vm-cli-playbook/lume/http-api.mdx b/docs/content/reference/macos-vm-cli-playbook/lume/http-api.mdx
new file mode 100644
index 0000000000..f908f85e20
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lume/http-api.mdx
@@ -0,0 +1,1260 @@
+---
+title: HTTP Server API
+description: Lume exposes a local HTTP API server that listens at localhost for programmatic management of VMs.
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+## Default URL
+
+```
+http://localhost:7777
+```
+
+<Callout type="info">
+ The HTTP API service runs on port `7777` by default. If you'd like to use a different port, pass
+ the `--port` option during installation or when running `lume serve`.
+</Callout>
+
+## Endpoints
+
+---
+
+### Create VM
+
+Create a new virtual machine.
+
+`POST: /lume/vms`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| -------- | ------- | -------- | ------------------------------------ |
+| name | string | Yes | Name of the VM |
+| os | string | Yes | Guest OS (`macOS`, `linux`, etc.) |
+| cpu | integer | Yes | Number of CPU cores |
+| memory | string | Yes | Memory size (e.g. `4GB`) |
+| diskSize | string | Yes | Disk size (e.g. `64GB`) |
+| display | string | No | Display resolution (e.g. `1024x768`) |
+| ipsw | string | No | IPSW version (e.g. `latest`) |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "lume_vm",
+ "os": "macOS",
+ "cpu": 2,
+ "memory": "4GB",
+ "diskSize": "64GB",
+ "display": "1024x768",
+ "ipsw": "latest",
+ "storage": "ssd"
+ }' \
+ http://localhost:7777/lume/vms
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+payload = {
+ "name": "lume_vm",
+ "os": "macOS",
+ "cpu": 2,
+ "memory": "4GB",
+ "diskSize": "64GB",
+ "display": "1024x768",
+ "ipsw": "latest",
+ "storage": "ssd"
+}
+r = requests.post("http://localhost:7777/lume/vms", json=payload, timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const payload = {
+ name: 'lume_vm',
+ os: 'macOS',
+ cpu: 2,
+ memory: '4GB',
+ diskSize: '64GB',
+ display: '1024x768',
+ ipsw: 'latest',
+ storage: 'ssd',
+};
+
+const res = await fetch('http://localhost:7777/lume/vms', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+### Run VM
+
+Run a virtual machine instance.
+
+`POST: /lume/vms/:name/run`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ----------------- | --------------- | -------- | --------------------------------------------------- |
+| noDisplay | boolean | No | If true, do not start VNC client |
+| sharedDirectories | array of object | No | List of shared directories (`hostPath`, `readOnly`) |
+| recoveryMode | boolean | No | Start in recovery mode |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+# Basic run
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ http://localhost:7777/lume/vms/my-vm-name/run
+
+# Run with VNC client started and shared directory
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "noDisplay": false,
+ "sharedDirectories": [
+ {
+ "hostPath": "~/Projects",
+ "readOnly": false
+ }
+ ],
+ "recoveryMode": false,
+ "storage": "ssd"
+ }' \
+ http://localhost:7777/lume/vms/lume_vm/run
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+# Basic run
+r = requests.post("http://localhost:7777/lume/vms/my-vm-name/run", timeout=50)
+print(r.json())
+
+# With VNC and shared directory
+payload = {
+ "noDisplay": False,
+ "sharedDirectories": [
+ {"hostPath": "~/Projects", "readOnly": False}
+ ],
+ "recoveryMode": False,
+ "storage": "ssd"
+}
+r = requests.post("http://localhost:7777/lume/vms/lume_vm/run", json=payload, timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+// Basic run
+let res = await fetch('http://localhost:7777/lume/vms/my-vm-name/run', {
+ method: 'POST',
+});
+console.log(await res.json());
+
+// With VNC and shared directory
+const payload = {
+ noDisplay: false,
+ sharedDirectories: [{ hostPath: '~/Projects', readOnly: false }],
+ recoveryMode: false,
+ storage: 'ssd',
+};
+res = await fetch('http://localhost:7777/lume/vms/lume_vm/run', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+### List VMs
+
+List all virtual machines.
+
+`GET: /lume/vms`
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ http://localhost:7777/lume/vms
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+r = requests.get("http://localhost:7777/lume/vms", timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/vms');
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+```json
+[
+ {
+ "name": "my-vm",
+ "state": "stopped",
+ "os": "macOS",
+ "cpu": 2,
+ "memory": "4GB",
+ "diskSize": "64GB"
+ },
+ {
+ "name": "my-vm-2",
+ "state": "stopped",
+ "os": "linux",
+ "cpu": 2,
+ "memory": "4GB",
+ "diskSize": "64GB"
+ }
+]
+```
+
+---
+
+### Get VM Details
+
+Get details for a specific virtual machine.
+
+`GET: /lume/vms/:name`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ------- | ------ | -------- | -------------------------- |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+# Basic get
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ http://localhost:7777/lume/vms/lume_vm
+
+# Get with specific storage
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ http://localhost:7777/lume/vms/lume_vm?storage=ssd
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+# Basic get
+details = requests.get("http://localhost:7777/lume/vms/lume_vm", timeout=50)
+print(details.json())
+
+# Get with specific storage
+details = requests.get("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50)
+print(details.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+// Basic get
+let res = await fetch('http://localhost:7777/lume/vms/lume_vm');
+console.log(await res.json());
+
+// Get with specific storage
+res = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd');
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+```json
+{
+ "name": "lume_vm",
+ "state": "stopped",
+ "os": "macOS",
+ "cpu": 2,
+ "memory": "4GB",
+ "diskSize": "64GB",
+ "display": "1024x768",
+ "ipAddress": "192.168.65.2",
+ "vncPort": 5900,
+ "sharedDirectories": [
+ {
+ "hostPath": "~/Projects",
+ "readOnly": false,
+ "tag": "com.apple.virtio-fs.automount"
+ }
+ ]
+}
+```
+
+---
+
+### Update VM Configuration
+
+Update the configuration of a virtual machine.
+
+`PATCH: /lume/vms/:name`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| -------- | ------- | -------- | ------------------------------------- |
+| cpu | integer | No | Number of CPU cores |
+| memory | string | No | Memory size (e.g. `8GB`) |
+| diskSize | string | No | Disk size (e.g. `100GB`) |
+| display | string | No | Display resolution (e.g. `1920x1080`) |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X PATCH \
+ -H "Content-Type: application/json" \
+ -d '{
+ "cpu": 4,
+ "memory": "8GB",
+ "diskSize": "100GB",
+ "display": "1920x1080",
+ "storage": "ssd"
+ }' \
+ http://localhost:7777/lume/vms/lume_vm
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+payload = {
+ "cpu": 4,
+ "memory": "8GB",
+ "diskSize": "100GB",
+ "display": "1920x1080",
+ "storage": "ssd"
+}
+r = requests.patch("http://localhost:7777/lume/vms/lume_vm", json=payload, timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const payload = {
+ cpu: 4,
+ memory: '8GB',
+ diskSize: '100GB',
+ display: '1920x1080',
+ storage: 'ssd',
+};
+const res = await fetch('http://localhost:7777/lume/vms/lume_vm', {
+ method: 'PATCH',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+### Stop VM
+
+Stop a running virtual machine.
+
+`POST: /lume/vms/:name/stop`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ------- | ------ | -------- | -------------------------- |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+# Basic stop
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ http://localhost:7777/lume/vms/lume_vm/stop
+
+# Stop with storage location specified
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+# Basic stop
+r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", timeout=50)
+print(r.json())
+
+# Stop with storage location specified
+r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", params={"storage": "ssd"}, timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+// Basic stop
+let res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop', {
+ method: 'POST',
+});
+console.log(await res.json());
+
+// Stop with storage location specified
+res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop?storage=ssd', {
+ method: 'POST',
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+### Delete VM
+
+Delete a virtual machine instance.
+
+`DELETE: /lume/vms/:name`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ------- | ------ | -------- | -------------------------- |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+# Basic delete
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X DELETE \
+ http://localhost:7777/lume/vms/lume_vm
+
+# Delete with specific storage
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X DELETE \
+ http://localhost:7777/lume/vms/lume_vm?storage=ssd
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+# Basic delete
+r = requests.delete("http://localhost:7777/lume/vms/lume_vm", timeout=50)
+print(r.status_code)
+
+# Delete with specific storage
+r = requests.delete("http://localhost:7777/lume/vms/lume_vm", params={"storage": "ssd"}, timeout=50)
+print(r.status_code)
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+// Basic delete
+let res = await fetch('http://localhost:7777/lume/vms/lume_vm', {
+ method: 'DELETE',
+});
+console.log(res.status);
+
+// Delete with specific storage
+res = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd', {
+ method: 'DELETE',
+});
+console.log(res.status);
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+### Clone VM
+
+Clone an existing virtual machine.
+
+`POST: /lume/vms/clone`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| -------------- | ------ | -------- | ----------------------------------- |
+| name | string | Yes | Source VM name |
+| newName | string | Yes | New VM name |
+| sourceLocation | string | No | Source storage location (`default`) |
+| destLocation | string | No | Destination storage location |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "source-vm",
+ "newName": "cloned-vm",
+ "sourceLocation": "default",
+ "destLocation": "ssd"
+ }' \
+ http://localhost:7777/lume/vms/clone
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+payload = {
+ "name": "source-vm",
+ "newName": "cloned-vm",
+ "sourceLocation": "default",
+ "destLocation": "ssd"
+}
+r = requests.post("http://localhost:7777/lume/vms/clone", json=payload, timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const payload = {
+ name: 'source-vm',
+ newName: 'cloned-vm',
+ sourceLocation: 'default',
+ destLocation: 'ssd',
+};
+const res = await fetch('http://localhost:7777/lume/vms/clone', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+### Pull VM Image
+
+Pull a VM image from a registry.
+
+`POST: /lume/pull`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ------------ | ------ | -------- | ------------------------------------- |
+| image | string | Yes | Image name (e.g. `macos-sequoia-...`) |
+| name | string | No | VM name for the pulled image |
+| registry | string | No | Registry host (e.g. `ghcr.io`) |
+| organization | string | No | Organization name |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "image": "macos-sequoia-vanilla:latest",
+ "name": "my-vm-name",
+ "registry": "ghcr.io",
+ "organization": "trycua",
+ "storage": "ssd"
+ }' \
+ http://localhost:7777/lume/pull
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+payload = {
+ "image": "macos-sequoia-vanilla:latest",
+ "name": "my-vm-name",
+ "registry": "ghcr.io",
+ "organization": "trycua",
+ "storage": "ssd"
+}
+r = requests.post("http://localhost:7777/lume/pull", json=payload, timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const payload = {
+ image: 'macos-sequoia-vanilla:latest',
+ name: 'my-vm-name',
+ registry: 'ghcr.io',
+ organization: 'trycua',
+ storage: 'ssd',
+};
+const res = await fetch('http://localhost:7777/lume/pull', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+### Push VM Image
+
+Push a VM to a registry as an image (asynchronous operation).
+
+`POST: /lume/vms/push`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ------------ | ----------- | -------- | ------------------------------------ |
+| name | string | Yes | Local VM name to push |
+| imageName | string | Yes | Image name in registry |
+| tags | array | Yes | Image tags (e.g. `["latest", "v1"]`) |
+| organization | string | Yes | Organization name |
+| registry | string | No | Registry host (e.g. `ghcr.io`) |
+| chunkSizeMb | integer | No | Chunk size in MB for upload |
+| storage | string/null | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "my-local-vm",
+ "imageName": "my-image",
+ "tags": ["latest", "v1"],
+ "organization": "my-org",
+ "registry": "ghcr.io",
+ "chunkSizeMb": 512,
+ "storage": null
+ }' \
+ http://localhost:7777/lume/vms/push
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+payload = {
+ "name": "my-local-vm",
+ "imageName": "my-image",
+ "tags": ["latest", "v1"],
+ "organization": "my-org",
+ "registry": "ghcr.io",
+ "chunkSizeMb": 512,
+ "storage": None
+}
+r = requests.post("http://localhost:7777/lume/vms/push", json=payload, timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const payload = {
+ name: 'my-local-vm',
+ imageName: 'my-image',
+ tags: ['latest', 'v1'],
+ organization: 'my-org',
+ registry: 'ghcr.io',
+ chunkSizeMb: 512,
+ storage: null,
+};
+const res = await fetch('http://localhost:7777/lume/vms/push', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+**Response (202 Accepted):**
+
+```json
+{
+ "message": "Push initiated in background",
+ "name": "my-local-vm",
+ "imageName": "my-image",
+ "tags": ["latest", "v1"]
+}
+```
+
+---
+
+### List Images
+
+List available VM images.
+
+`GET: /lume/images`
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ http://localhost:7777/lume/images
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+r = requests.get("http://localhost:7777/lume/images", timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/images');
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+```json
+{
+ "local": ["macos-sequoia-xcode:latest", "macos-sequoia-vanilla:latest"]
+}
+```
+
+---
+
+### Prune Images
+
+Remove unused VM images to free up disk space.
+
+`POST: /lume/prune`
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ http://localhost:7777/lume/prune
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+r = requests.post("http://localhost:7777/lume/prune", timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/prune', {
+ method: 'POST',
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+### Get Latest IPSW URL
+
+Get the URL for the latest macOS IPSW file.
+
+`GET: /lume/ipsw`
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ http://localhost:7777/lume/ipsw
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+r = requests.get("http://localhost:7777/lume/ipsw", timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/ipsw');
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+## Configuration Management
+
+### Get Configuration
+
+Get current Lume configuration settings.
+
+`GET: /lume/config`
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ http://localhost:7777/lume/config
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+r = requests.get("http://localhost:7777/lume/config", timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/config');
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+```json
+{
+ "homeDirectory": "~/.lume",
+ "cacheDirectory": "~/.lume/cache",
+ "cachingEnabled": true
+}
+```
+
+### Update Configuration
+
+Update Lume configuration settings.
+
+`POST: /lume/config`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| -------------- | ------- | -------- | ------------------------- |
+| homeDirectory | string | No | Lume home directory path |
+| cacheDirectory | string | No | Cache directory path |
+| cachingEnabled | boolean | No | Enable or disable caching |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "homeDirectory": "~/custom/lume",
+ "cacheDirectory": "~/custom/lume/cache",
+ "cachingEnabled": true
+ }' \
+ http://localhost:7777/lume/config
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+payload = {
+ "homeDirectory": "~/custom/lume",
+ "cacheDirectory": "~/custom/lume/cache",
+ "cachingEnabled": True
+}
+r = requests.post("http://localhost:7777/lume/config", json=payload, timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const payload = {
+ homeDirectory: '~/custom/lume',
+ cacheDirectory: '~/custom/lume/cache',
+ cachingEnabled: true,
+};
+const res = await fetch('http://localhost:7777/lume/config', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+## Storage Location Management
+
+### Get VM Storage Locations
+
+List all configured VM storage locations.
+
+`GET: /lume/config/locations`
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ http://localhost:7777/lume/config/locations
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+r = requests.get("http://localhost:7777/lume/config/locations", timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/config/locations');
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+```json
+[
+ {
+ "name": "default",
+ "path": "~/.lume/vms",
+ "isDefault": true
+ },
+ {
+ "name": "ssd",
+ "path": "/Volumes/SSD/lume/vms",
+ "isDefault": false
+ }
+]
+```
+
+### Add VM Storage Location
+
+Add a new VM storage location.
+
+`POST: /lume/config/locations`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ---- | ------ | -------- | ---------------------------- |
+| name | string | Yes | Storage location name |
+| path | string | Yes | File system path for storage |
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "ssd",
+ "path": "/Volumes/SSD/lume/vms"
+ }' \
+ http://localhost:7777/lume/config/locations
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+payload = {
+ "name": "ssd",
+ "path": "/Volumes/SSD/lume/vms"
+}
+r = requests.post("http://localhost:7777/lume/config/locations", json=payload, timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const payload = {
+ name: 'ssd',
+ path: '/Volumes/SSD/lume/vms',
+};
+const res = await fetch('http://localhost:7777/lume/config/locations', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
+
+### Remove VM Storage Location
+
+Remove a VM storage location.
+
+`DELETE: /lume/config/locations/:name`
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X DELETE \
+ http://localhost:7777/lume/config/locations/ssd
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+r = requests.delete("http://localhost:7777/lume/config/locations/ssd", timeout=50)
+print(r.status_code)
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/config/locations/ssd', {
+ method: 'DELETE',
+});
+console.log(res.status);
+```
+
+ </Tab>
+</Tabs>
+
+### Set Default VM Storage Location
+
+Set a storage location as the default.
+
+`POST: /lume/config/locations/default/:name`
+
+#### Example Request
+
+<Tabs groupId="language" persist items={['Curl', 'Python', 'TypeScript']}>
+ <Tab value="Curl">
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ http://localhost:7777/lume/config/locations/default/ssd
+```
+
+ </Tab>
+ <Tab value="Python">
+
+```python
+import requests
+
+r = requests.post("http://localhost:7777/lume/config/locations/default/ssd", timeout=50)
+print(r.json())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/config/locations/default/ssd', {
+ method: 'POST',
+});
+console.log(await res.json());
+```
+
+ </Tab>
+</Tabs>
diff --git a/docs/content/reference/macos-vm-cli-playbook/lume/index.mdx b/docs/content/reference/macos-vm-cli-playbook/lume/index.mdx
new file mode 100644
index 0000000000..152d08c743
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lume/index.mdx
@@ -0,0 +1,8 @@
+---
+title: Lume
+description: Reference for the current version of the Lume CLI.
+github:
+ - https://github.com/trycua/cua/tree/main/libs/lume
+---
+
+Lume is a lightweight Command Line Interface and local API server for creating, running and managing **macOS and Linux virtual machines** with near-native performance on Apple Silicon, using Apple's [Virtualization.Framework](https://developer.apple.com/documentation/virtualization).
diff --git a/docs/content/reference/macos-vm-cli-playbook/lume/installation.mdx b/docs/content/reference/macos-vm-cli-playbook/lume/installation.mdx
new file mode 100644
index 0000000000..aa6da45a90
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lume/installation.mdx
@@ -0,0 +1,53 @@
+---
+title: Installation
+description: Installation instructions for the current version of the Lume CLI.
+---
+
+## Quickstart
+
+Install and run a prebuilt macOS sandbox in two commands:
+
+```bash
+# Install Lume
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+# Pull & start a macOS image
+lume run macos-sequoia-vanilla:latest
+```
+
+<Callout title="Security Note">
+ All prebuilt images use the default password `lume`. Change this immediately after your first
+ login using the `passwd` command.
+</Callout>
+
+**System Requirements**:
+
+- Apple Silicon Mac (M1, M2, M3, etc.)
+- macOS 13.0 or later
+- At least 8GB of RAM (16GB recommended)
+- At least 50GB of free disk space
+
+## Install with Script
+
+Install with a single command:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+```
+
+### Manual Start (No Background Service)
+
+By default, Lume is installed as a background service that starts automatically on login. If you prefer to start the Lume API service manually when needed, you can use the `--no-background-service` option:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh) --no-background-service"
+```
+
+<Callout title="Note">
+ With this option, you'll need to manually start the Lume API service by running `lume serve` in
+ your terminal whenever you need to use tools or libraries that rely on the Lume API (such as the
+ Computer-Use Agent).
+</Callout>
+
+## Manual Download and Installation
+
+You can also download the `lume.pkg.tar.gz` archive from the [latest release](https://github.com/trycua/cua/releases?q=lume&expanded=true), extract it, and install the package manually.
diff --git a/docs/content/reference/macos-vm-cli-playbook/lume/meta.json b/docs/content/reference/macos-vm-cli-playbook/lume/meta.json
new file mode 100644
index 0000000000..42aeac1d01
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lume/meta.json
@@ -0,0 +1,3 @@
+{
+ "pages": ["installation", "prebuilt-images", "cli-reference", "http-api", "faq"]
+}
diff --git a/docs/content/reference/macos-vm-cli-playbook/lume/prebuilt-images.mdx b/docs/content/reference/macos-vm-cli-playbook/lume/prebuilt-images.mdx
new file mode 100644
index 0000000000..4e4e3e67ca
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lume/prebuilt-images.mdx
@@ -0,0 +1,33 @@
+---
+title: Prebuilt Images
+---
+
+Pre-built images are available in the registry [ghcr.io/trycua](https://github.com/orgs/trycua/packages). These images come with an SSH server pre-configured and auto-login enabled.
+
+<Callout>
+ The default password on pre-built images is `lume`. For the security of your VM, change this
+ password after your first login.
+</Callout>
+
+## Available Images
+
+The following pre-built images are available to download via `lume pull`:
+
+| Image | Tag | Description | Logical Size |
+| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------- | ------------ |
+| `macos-sequoia-vanilla` | `latest`, `15.2` | macOS Sequoia 15.2 image | 20GB |
+| `macos-sequoia-xcode` | `latest`, `15.2` | macOS Sequoia 15.2 image with Xcode command line tools | 22GB |
+| `macos-sequoia-cua` | `latest`, `15.3` | macOS Sequoia 15.3 image compatible with the Computer interface | 24GB |
+| `ubuntu-noble-vanilla` | `latest`, `24.04.1` | [Ubuntu Server for ARM 24.04.1 LTS](https://ubuntu.com/download/server/arm) with Ubuntu Desktop | 20GB |
+
+## Disk Space
+
+For additional disk space, resize the VM disk after pulling the image using the `lume set <name> --disk-size <size>` command. Note that the actual disk space used by sparse images will be much lower than the logical size listed.
+
+<Callout>
+ **Important Note (v0.2.0+):** Images are being re-uploaded with sparse file system optimizations
+ enabled, resulting in significantly lower actual disk usage. Older images (without the `-sparse`
+ suffix) are now **deprecated**. The last version of `lume` fully supporting the non-sparse images
+ was `v0.1.x`. Starting from `v0.2.0`, lume will automatically pull images optimized with sparse
+ file system support.
+</Callout>
diff --git a/docs/content/reference/macos-vm-cli-playbook/lumier/building-lumier.mdx b/docs/content/reference/macos-vm-cli-playbook/lumier/building-lumier.mdx
new file mode 100644
index 0000000000..bd9b99514b
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lumier/building-lumier.mdx
@@ -0,0 +1,42 @@
+---
+title: Building Lumier
+---
+
+If you want to customize the Lumier container or build it from source, you can follow these steps:
+
+```bash
+# 1. Navigate to the Lumier directory
+cd libs/lumier
+
+# 2. Build the Docker image locally
+docker build -t lumier-custom:latest .
+
+# 3. Run your custom build
+docker run -it --rm \
+ --name lumier-vm \
+ -p 8006:8006 \
+ -e VM_NAME=lumier-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ -e CPU_CORES=4 \
+ -e RAM_SIZE=8192 \
+ lumier-custom:latest
+```
+
+### Customization Options
+
+The Dockerfile provides several customization points:
+
+1. **Base image**: The container uses Debian Bullseye Slim as the base. You can modify this if needed.
+2. **Installed packages**: You can add or remove packages in the apt-get install list.
+3. **Hooks**: Check the `/run/hooks/` directory for scripts that run at specific points during VM lifecycle.
+4. **Configuration**: Review `/run/config/constants.sh` for default settings.
+
+After making your modifications, you can build and push your custom image to your own Docker Hub repository:
+
+```bash
+# Build with a custom tag
+docker build -t yourusername/lumier:custom .
+
+# Push to Docker Hub (after docker login)
+docker push yourusername/lumier:custom
+```
diff --git a/docs/content/reference/macos-vm-cli-playbook/lumier/docker-compose.mdx b/docs/content/reference/macos-vm-cli-playbook/lumier/docker-compose.mdx
new file mode 100644
index 0000000000..312598e74b
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lumier/docker-compose.mdx
@@ -0,0 +1,45 @@
+---
+title: Docker Compose
+---
+
+You can also use Docker Compose to run Lumier with a simple configuration file. Create a `docker-compose.yml` file with the following content:
+
+```yaml
+version: '3'
+
+services:
+ lumier:
+ image: trycua/lumier:latest
+ container_name: lumier-vm
+ restart: unless-stopped
+ ports:
+ - '8006:8006' # Port for VNC access
+ volumes:
+ - ./storage:/storage # VM persistent storage
+ - ./shared:/shared # Shared folder accessible in the VM
+ environment:
+ - VM_NAME=lumier-vm
+ - VERSION=ghcr.io/trycua/macos-sequoia-cua:latest
+ - CPU_CORES=4
+ - RAM_SIZE=8192
+ - HOST_STORAGE_PATH=${PWD}/storage
+ - HOST_SHARED_PATH=${PWD}/shared
+ stop_signal: SIGINT
+ stop_grace_period: 2m
+```
+
+Then run Lumier using:
+
+```bash
+# First create the required directories
+mkdir -p storage shared
+
+# Start the container
+docker-compose up -d
+
+# View the logs
+docker-compose logs -f
+
+# Stop the container when done
+docker-compose down
+```
diff --git a/docs/content/reference/macos-vm-cli-playbook/lumier/docker.mdx b/docs/content/reference/macos-vm-cli-playbook/lumier/docker.mdx
new file mode 100644
index 0000000000..b7c7205061
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lumier/docker.mdx
@@ -0,0 +1,128 @@
+---
+title: Docker
+---
+
+You can use Lumier through Docker:
+
+### Run a macOS VM (ephemeral)
+
+```bash
+# Run the container with temporary storage (using pre-built image from Docker Hub)
+docker run -it --rm \
+ --name macos-vm \
+ -p 8006:8006 \
+ -e VM_NAME=macos-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ -e CPU_CORES=4 \
+ -e RAM_SIZE=8192 \
+ trycua/lumier:latest
+```
+
+Access the VM in your browser at **http://localhost:8006**.
+
+After running the command above, you can access your macOS VM through a web browser (e.g., http://localhost:8006).
+
+<Callout title="Note">
+ With the basic setup above, your VM will be reset when you stop the container (ephemeral mode).
+ This means any changes you make inside the macOS VM will be lost. See the section below for how to
+ save your VM state.
+</Callout>
+
+## Saving Your VM State
+
+To save your VM state between sessions (so your changes persist when you stop and restart the container), you'll need to set up a storage location:
+
+```bash
+# First, create a storage directory if it doesn't exist
+mkdir -p storage
+
+# Then run the container with persistent storage
+docker run -it --rm \
+ --name lumier-vm \
+ -p 8006:8006 \
+ -v $(pwd)/storage:/storage \
+ -e VM_NAME=lumier-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ -e CPU_CORES=4 \
+ -e RAM_SIZE=8192 \
+ -e HOST_STORAGE_PATH=$(pwd)/storage \
+ trycua/lumier:latest
+```
+
+This command creates a connection between a folder on your Mac (`$(pwd)/storage`) and a folder inside the Docker container (`/storage`). The `-v` flag (volume mount) and the `HOST_STORAGE_PATH` variable work together to ensure your VM data is saved on your host Mac.
+
+## Sharing Files with Your VM
+
+To share files between your Mac and the virtual machine, you can set up a shared folder:
+
+```bash
+# Create both storage and shared folders
+mkdir -p storage shared
+
+# Run with both persistent storage and a shared folder
+docker run -it --rm \
+ --name lumier-vm \
+ -p 8006:8006 \
+ -v $(pwd)/storage:/storage \
+ -v $(pwd)/shared:/shared \
+ -e VM_NAME=lumier-vm \
+ -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
+ -e CPU_CORES=4 \
+ -e RAM_SIZE=8192 \
+ -e HOST_STORAGE_PATH=$(pwd)/storage \
+ -e HOST_SHARED_PATH=$(pwd)/shared \
+ trycua/lumier:latest
+```
+
+With this setup, any files you place in the `shared` folder on your Mac will be accessible from within the macOS VM, and vice versa.
+
+## Automating VM Startup with on-logon.sh
+
+You can automatically run scripts when the VM starts up by placing an `on-logon.sh` script in the shared folder's lifecycle directory. This is useful for setting up your VM environment each time it starts.
+
+```bash
+# Create the lifecycle directory in your shared folder
+mkdir -p shared/lifecycle
+
+# Create a sample on-logon.sh script
+cat > shared/lifecycle/on-logon.sh << 'EOF'
+#!/usr/bin/env bash
+
+# Create a file on the desktop
+echo "Hello from Lumier!" > /Users/lume/Desktop/hello_lume.txt
+
+# You can add more commands to execute at VM startup
+# For example:
+# - Configure environment variables
+# - Start applications
+# - Mount network drives
+# - Set up development environments
+EOF
+
+# Make the script executable
+chmod +x shared/lifecycle/on-logon.sh
+```
+
+The script will be automatically executed when the VM starts up. It runs in the VM context and has access to:
+
+- The `/Users/lume` user directory (home directory in the VM)
+- The shared folder at `/Volumes/My Shared Files` inside the VM
+- Any resources available to the VM
+
+This feature enables automation of VM setup without modifying the base VM image.
+
+## Configuration Options
+
+When running Lumier, you'll need to configure a few things:
+
+- **Port forwarding** (`-p 8006:8006`): Makes the VM's VNC interface accessible in your browser. If port 8006 is already in use, you can use a different port like `-p 8007:8006`.
+
+- **Environment variables** (`-e`): Configure your VM settings:
+ - `VM_NAME`: A name for your virtual machine
+ - `VERSION`: The macOS image to use
+ - `CPU_CORES`: Number of CPU cores to allocate
+ - `RAM_SIZE`: Memory in MB to allocate
+ - `HOST_STORAGE_PATH`: Path to save VM state (when using persistent storage)
+ - `HOST_SHARED_PATH`: Path to the shared folder (optional)
+
+- **Background service**: The `lume serve` service should be running on your host (starts automatically when you install Lume using the `install.sh` script above).
diff --git a/docs/content/reference/macos-vm-cli-playbook/lumier/index.mdx b/docs/content/reference/macos-vm-cli-playbook/lumier/index.mdx
new file mode 100644
index 0000000000..d21768f4c3
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lumier/index.mdx
@@ -0,0 +1,28 @@
+---
+title: Lumier
+description: Reference for the current version of the Lumier library.
+github:
+ - https://github.com/trycua/cua/tree/main/libs/lumier
+---
+
+**Lumier** is an interface for running macOS virtual machines with minimal setup. It uses Docker as a packaging system to deliver a pre-configured environment that connects to the `lume` virtualization service running on your host machine. With Lumier, you get:
+
+- A ready-to-use macOS or Linux virtual machine in minutes
+- Browser-based VNC access to your VM
+- Easy file sharing between your host and VM
+- Simple configuration through environment variables
+
+## How It Works
+
+<Callout title="Note">
+ We're using Docker primarily as a convenient delivery mechanism, not as an isolation layer. Unlike
+ traditional Docker containers, Lumier leverages the Apple Virtualization Framework (Apple Vz)
+ through the `lume` CLI to create true virtual machines.
+</Callout>
+
+Here's what's happening behind the scenes:
+
+1. The Docker container provides a consistent environment to run the Lumier interface
+2. Lumier connects to the Lume service running on your host Mac
+3. Lume uses Apple's Virtualization Framework to create a true macOS virtual machine
+4. The VM runs with hardware acceleration using your Mac's native virtualization capabilities
diff --git a/docs/content/reference/macos-vm-cli-playbook/lumier/installation.mdx b/docs/content/reference/macos-vm-cli-playbook/lumier/installation.mdx
new file mode 100644
index 0000000000..d2e6239932
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lumier/installation.mdx
@@ -0,0 +1,15 @@
+---
+title: Installation
+---
+
+Before using Lumier, make sure you have:
+
+1. **Docker for Apple Silicon** - download it [here](https://desktop.docker.com/mac/main/arm64/Docker.dmg) and follow the installation instructions.
+
+2. **Lume** - This is the virtualization CLI that powers Lumier. Install it with this command:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+```
+
+After installation, Lume runs as a background service and listens on port 7777. This service allows Lumier to create and manage virtual machines. If port 7777 is already in use on your system, you can specify a different port with the `--port` option when running the `install.sh` script.
diff --git a/docs/content/reference/macos-vm-cli-playbook/lumier/meta.json b/docs/content/reference/macos-vm-cli-playbook/lumier/meta.json
new file mode 100644
index 0000000000..bfe2572455
--- /dev/null
+++ b/docs/content/reference/macos-vm-cli-playbook/lumier/meta.json
@@ -0,0 +1,3 @@
+{
+ "pages": ["installation", "docker", "docker-compose", "building-lumier"]
+}
diff --git a/docs/content/docs/macos-vm-cli-playbook/meta.json b/docs/content/reference/macos-vm-cli-playbook/meta.json
similarity index 100%
rename from docs/content/docs/macos-vm-cli-playbook/meta.json
rename to docs/content/reference/macos-vm-cli-playbook/meta.json
diff --git a/docs/content/reference/meta.json b/docs/content/reference/meta.json
new file mode 100644
index 0000000000..1165fc2000
--- /dev/null
+++ b/docs/content/reference/meta.json
@@ -0,0 +1,17 @@
+{
+ "title": "Reference",
+ "description": "SDK and CLI reference documentation",
+ "root": true,
+ "defaultOpen": true,
+ "pages": [
+ "index",
+ "---[Bot]Agent SDK---",
+ "...agent-sdk",
+ "---[Monitor]Computer SDK---",
+ "...computer-sdk",
+ "---[Terminal]Cloud CLI---",
+ "...cli-playbook",
+ "---[Terminal]macOS VM CLI---",
+ "...macos-vm-cli-playbook"
+ ]
+}
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index fdb996c11f..0582d36e52 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -38,20 +38,12 @@ const config = {
permanent: true, // 301 redirect to preserve SEO authority
basePath: false,
},
- // Redirects for documentation restructure (PR #568)
- // Moved quickstart-devs to get-started section
+ // Redirects for old URLs
{
source: '/quickstart-devs',
destination: '/get-started/quickstart',
permanent: true,
},
- // Moved telemetry to agent-sdk section
- {
- source: '/telemetry',
- destination: '/agent-sdk/telemetry',
- permanent: true,
- },
- // Removed quickstart-cli, consolidated into main quickstart
{
source: '/quickstart-cli',
destination: '/get-started/quickstart',
diff --git a/docs/source.config.ts b/docs/source.config.ts
index d915345e7a..28c92e7175 100644
--- a/docs/source.config.ts
+++ b/docs/source.config.ts
@@ -1,18 +1,21 @@
import { defineConfig, defineDocs, frontmatterSchema, metaSchema } from 'fumadocs-mdx/config';
import { z } from 'zod';
-// You can customise Zod schemas for frontmatter and `meta.json` here
-// see https://fumadocs.vercel.app/docs/mdx/collections#define-docs
+// Extended frontmatter schema
+const extendedFrontmatter = frontmatterSchema.extend({
+ macos: z.boolean().optional(),
+ windows: z.boolean().optional(),
+ linux: z.boolean().optional(),
+ pypi: z.string().optional(),
+ npm: z.string().optional(),
+ github: z.array(z.string()).optional(),
+});
+
+// Single docs collection
export const docs = defineDocs({
+ dir: 'content/docs',
docs: {
- schema: frontmatterSchema.extend({
- macos: z.boolean().optional(),
- windows: z.boolean().optional(),
- linux: z.boolean().optional(),
- pypi: z.string().optional(),
- npm: z.string().optional(),
- github: z.array(z.string()).optional(),
- }),
+ schema: extendedFrontmatter,
},
meta: {
schema: metaSchema,
diff --git a/docs/src/app/(home)/[[...slug]]/page.tsx b/docs/src/app/(docs)/[...slug]/page.tsx
similarity index 94%
rename from docs/src/app/(home)/[[...slug]]/page.tsx
rename to docs/src/app/(docs)/[...slug]/page.tsx
index 4354012e04..39c8f0e012 100644
--- a/docs/src/app/(home)/[[...slug]]/page.tsx
+++ b/docs/src/app/(docs)/[...slug]/page.tsx
@@ -5,16 +5,16 @@ import { Popover, PopoverContent, PopoverTrigger } from 'fumadocs-ui/components/
import { createRelativeLink } from 'fumadocs-ui/mdx';
import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/page';
import { cn } from 'fumadocs-ui/utils/cn';
-import { ChevronDown, CodeXml, ExternalLink } from 'lucide-react';
+import { ChevronDown, ExternalLink } from 'lucide-react';
import type { Metadata } from 'next';
import Link from 'next/link';
import { notFound } from 'next/navigation';
import { PageFeedback } from '@/components/page-feedback';
import { DocActionsMenu } from '@/components/doc-actions-menu';
-export default async function Page(props: { params: Promise<{ slug?: string[] }> }) {
+export default async function Page(props: { params: Promise<{ slug: string[] }> }) {
const params = await props.params;
- const slug = params.slug || [];
+ const slug = params.slug;
const page = source.getPage(slug);
if (!page) notFound();
@@ -165,14 +165,6 @@ export default async function Page(props: { params: Promise<{ slug?: string[] }>
</PopoverContent>
</Popover>
))}
- {/*slug.includes('libraries') && (
- <a
- className="inline-flex gap-2 w-fit items-center justify-center rounded-md text-sm font-medium transition-colors duration-100 disabled:pointer-events-none disabled:opacity-50 focus-visible:outline-none hover:bg-fd-accent hover:text-fd-accent-foreground p-1.5 [&amp;_svg]:size-5 text-fd-muted-foreground md:[&amp;_svg]:size-4.5"
- href={`/api/${page.data.title.toLowerCase()}`}>
- <CodeXml size={12} />
- Reference
- </a>
- )*/}
</div>
<hr className="my-2 border-t border-fd-border" />
</div>
@@ -181,7 +173,6 @@ export default async function Page(props: { params: Promise<{ slug?: string[] }>
const tocFooter = () => {
// Construct file path from slug
- // For root index, use 'index.mdx', otherwise join slug parts
const filePath = slug.length === 0 ? 'index.mdx' : `${slug.join('/')}.mdx`;
return (
@@ -276,23 +267,21 @@ export default async function Page(props: { params: Promise<{ slug?: string[] }>
);
}
-export async function generateStaticParams() {
+export function generateStaticParams() {
return source.generateParams();
}
export async function generateMetadata(props: {
- params: Promise<{ slug?: string[] }>;
+ params: Promise<{ slug: string[] }>;
}): Promise<Metadata> {
const params = await props.params;
const page = source.getPage(params.slug);
if (!page) notFound();
- let title = `${page.data.title} | Cua`;
- if (page.url.includes('api')) title = `${page.data.title} | Cua API`;
- if (page.url.includes('guide')) title = ` Guide: ${page.data.title} | Cua`;
+ const title = `${page.data.title} | Cua`;
// Canonical URL points to cua.ai to consolidate all SEO authority on main domain
- const canonicalUrl = `https://cua.ai${page.url}`;
+ const canonicalUrl = `https://cua.ai/docs${page.url}`;
// Extract keywords from the page for SEO
const keywords = [
diff --git a/docs/src/app/(docs)/layout.tsx b/docs/src/app/(docs)/layout.tsx
new file mode 100644
index 0000000000..b8cfa24297
--- /dev/null
+++ b/docs/src/app/(docs)/layout.tsx
@@ -0,0 +1,50 @@
+import { baseOptions } from '@/app/layout.config';
+import { source } from '@/lib/source';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import { Compass, Blocks, BookOpen } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+export default function Layout({ children }: { children: ReactNode }) {
+ return (
+ <DocsLayout
+ tree={source.pageTree}
+ {...baseOptions}
+ sidebar={{
+ tabs: [
+ {
+ title: 'Guide',
+ description: 'Learn how to build with Cua',
+ url: '/guide',
+ icon: (
+ <span className="flex items-center justify-center">
+ <Compass className="size-4" />
+ </span>
+ ),
+ },
+ {
+ title: 'Examples',
+ description: 'Real-world examples',
+ url: '/examples',
+ icon: (
+ <span className="flex items-center justify-center">
+ <Blocks className="size-4" />
+ </span>
+ ),
+ },
+ {
+ title: 'Reference',
+ description: 'CLI tools and API reference',
+ url: '/reference',
+ icon: (
+ <span className="flex items-center justify-center">
+ <BookOpen className="size-4" />
+ </span>
+ ),
+ },
+ ],
+ }}
+ >
+ {children}
+ </DocsLayout>
+ );
+}
diff --git a/docs/src/app/(home)/layout.tsx b/docs/src/app/(home)/layout.tsx
deleted file mode 100644
index f73f4f1d4c..0000000000
--- a/docs/src/app/(home)/layout.tsx
+++ /dev/null
@@ -1,12 +0,0 @@
-import { baseOptions } from '@/app/layout.config';
-import { source } from '@/lib/source';
-import { DocsLayout } from 'fumadocs-ui/layouts/docs';
-import type { ReactNode } from 'react';
-
-export default function Layout({ children }: { children: ReactNode }) {
- return (
- <DocsLayout tree={source.pageTree} {...baseOptions}>
- {children}
- </DocsLayout>
- );
-}
diff --git a/docs/src/app/(landing)/layout.tsx b/docs/src/app/(landing)/layout.tsx
new file mode 100644
index 0000000000..1062deb2b6
--- /dev/null
+++ b/docs/src/app/(landing)/layout.tsx
@@ -0,0 +1,7 @@
+import type { ReactNode } from 'react';
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { baseOptions } from '@/app/layout.config';
+
+export default function LandingLayout({ children }: { children: ReactNode }) {
+ return <HomeLayout {...baseOptions}>{children}</HomeLayout>;
+}
diff --git a/docs/src/app/(landing)/page.tsx b/docs/src/app/(landing)/page.tsx
new file mode 100644
index 0000000000..f56ddebf34
--- /dev/null
+++ b/docs/src/app/(landing)/page.tsx
@@ -0,0 +1,308 @@
+import Link from 'next/link';
+import Image from 'next/image';
+import { BookOpen, Code2, FileCode, Play, ArrowRight, ChevronRight } from 'lucide-react';
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+ title: 'Cua Documentation',
+ description:
+ 'Build computer use agents that see screens, click buttons, type and run code — with Cua.',
+};
+
+// Navigation card data
+const navCards = [
+ {
+ icon: BookOpen,
+ title: 'Guide',
+ description:
+ 'Everything you need to know to use Cua. Dive deep into all of our features and best practices.',
+ href: '/guide',
+ },
+ {
+ icon: Code2,
+ title: 'Examples',
+ description:
+ 'Practical examples built with Cua. Explore guided starting points for your use case.',
+ href: '/examples',
+ },
+ {
+ icon: FileCode,
+ title: 'Reference',
+ description:
+ 'Technical information about the Cua APIs. Quickly refer to basic descriptions of various programming functionalities.',
+ href: '/reference',
+ },
+ {
+ icon: Play,
+ title: 'Playground',
+ description:
+ 'Interactive tutorials to learn how to use Cua. Run serverless cloud functions from your browser.',
+ href: '/guide/get-started/quickstart',
+ },
+];
+
+// Featured examples data
+const featuredExamples = [
+ {
+ title: 'Windows App Behind VPN',
+ description: 'Automate legacy Windows applications securely behind VPN',
+ href: '/examples/example-usecases/windows-app-behind-vpn',
+ },
+ {
+ title: 'PDF to Form Automation',
+ description: 'Enhance interactions between form filling and local file systems',
+ href: '/examples/example-usecases/form-filling',
+ },
+ {
+ title: 'Contact Export',
+ description: 'Export contacts from post-event platforms automatically',
+ href: '/examples/example-usecases/post-event-contact-export',
+ },
+ {
+ title: 'Complex UI Navigation',
+ description: 'Navigate complex UIs with Gemini vision capabilities',
+ href: '/examples/example-usecases/gemini-complex-ui-navigation',
+ },
+];
+
+export default function LandingPage() {
+ return (
+ <div className="relative min-h-screen">
+ {/* Hero Section with background image */}
+ <section className="relative overflow-hidden pb-16 pt-8 md:pb-24 md:pt-16">
+ {/* Background image - dark/light mode */}
+ <div className="pointer-events-none absolute inset-0">
+ <Image
+ src="/docs/img/bg-dark.jpg"
+ alt=""
+ fill
+ className="hidden object-cover object-top opacity-50 dark:block"
+ priority
+ />
+ <Image
+ src="/docs/img/bg-light.jpg"
+ alt=""
+ fill
+ className="block object-cover object-top opacity-30 dark:hidden"
+ priority
+ />
+ </div>
+
+ {/* Gradient overlay */}
+ <div className="pointer-events-none absolute inset-0 bg-gradient-to-b from-transparent via-fd-background/50 to-fd-background" />
+
+ <div className="container relative mx-auto px-6 lg:px-8">
+ <div className="grid items-center gap-12 lg:grid-cols-2 lg:gap-16">
+ {/* Text content */}
+ <div className="max-w-xl">
+ {/* Badge */}
+ <div className="mb-6 inline-flex items-center gap-2 rounded-lg border border-fd-border bg-fd-card/50 px-3 py-1.5 text-sm backdrop-blur-sm">
+ <span className="h-2 w-2 rounded-full bg-emerald-500" />
+ <span className="text-fd-muted-foreground">Open Source Documentation</span>
+ </div>
+
+ <h1
+ className="text-4xl font-bold tracking-tight sm:text-5xl md:text-6xl"
+ style={{ fontFamily: 'var(--font-urbanist)' }}
+ >
+ <span className="text-fd-foreground">Cua </span>
+ <span className="text-sky-500">Documentation</span>
+ </h1>
+
+ <p className="mt-6 text-lg leading-relaxed text-fd-muted-foreground">
+ Build computer use agents that see screens, click buttons, type and run code —
+ without thinking about infrastructure.
+ </p>
+
+ {/* CTA Buttons */}
+ <div className="mt-8 flex flex-wrap items-center gap-4">
+ <Link
+ href="/guide/get-started/what-is-cua"
+ className="group inline-flex items-center gap-2 rounded-xl bg-fd-foreground px-6 py-2.5 text-sm font-medium text-fd-background transition-all hover:bg-fd-foreground/90"
+ >
+ Get Started
+ <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-0.5" />
+ </Link>
+ <a
+ href="https://github.com/trycua/cua"
+ target="_blank"
+ rel="noreferrer"
+ className="inline-flex items-center gap-2 rounded-xl border border-fd-border bg-fd-background/50 px-6 py-2.5 text-sm font-medium backdrop-blur-sm transition-all hover:bg-fd-accent"
+ >
+ <svg className="h-5 w-5" viewBox="0 0 24 24" fill="currentColor">
+ <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12" />
+ </svg>
+ Star on GitHub
+ </a>
+ </div>
+ </div>
+
+ {/* Hero image */}
+ <div className="relative hidden lg:block">
+ <div className="relative mx-auto max-w-md">
+ {/* Glow effect behind image */}
+ <div className="absolute -inset-4 rounded-3xl bg-gradient-to-br from-sky-500/20 via-emerald-500/10 to-purple-500/20 blur-2xl" />
+ <div className="relative overflow-hidden rounded-2xl border border-fd-border/50 bg-fd-card/30 p-4 backdrop-blur-sm">
+ <Image
+ src="/docs/img/hero.png"
+ alt="Cua Platform"
+ width={400}
+ height={400}
+ className="rounded-xl"
+ priority
+ />
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ </section>
+
+ {/* Navigation Cards Section */}
+ <section className="container mx-auto px-6 py-12 lg:px-8">
+ <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+ {navCards.map((card) => {
+ const Icon = card.icon;
+ return (
+ <Link
+ key={card.title}
+ href={card.href}
+ className="group relative overflow-hidden rounded-xl border border-fd-border bg-fd-card/50 p-6 backdrop-blur-sm transition-all duration-300 hover:border-fd-primary/30 hover:bg-fd-card"
+ >
+ {/* Hover glow effect */}
+ <div className="pointer-events-none absolute inset-0 opacity-0 transition-opacity duration-300 group-hover:opacity-100">
+ <div className="absolute inset-0 bg-gradient-to-br from-sky-500/5 to-emerald-500/5" />
+ </div>
+
+ <div className="relative">
+ <div className="mb-4 inline-flex rounded-lg bg-gradient-to-br from-sky-500/10 to-emerald-500/10 p-3">
+ <Icon className="h-6 w-6 text-sky-500" />
+ </div>
+ <h3 className="mb-2 text-lg font-semibold">{card.title}</h3>
+ <p className="text-sm leading-relaxed text-fd-muted-foreground">
+ {card.description}
+ </p>
+ <div className="mt-4 inline-flex items-center text-sm font-medium text-sky-500 opacity-0 transition-all duration-300 group-hover:opacity-100">
+ Explore
+ <ArrowRight className="ml-1 h-4 w-4 transition-transform group-hover:translate-x-1" />
+ </div>
+ </div>
+ </Link>
+ );
+ })}
+ </div>
+ </section>
+
+ {/* Featured Examples Section */}
+ <section className="container mx-auto px-6 py-12 lg:px-8">
+ <div className="mb-8 flex items-center justify-between">
+ <div>
+ <h2
+ className="text-2xl font-bold md:text-3xl"
+ style={{ fontFamily: 'var(--font-urbanist)' }}
+ >
+ Featured Examples
+ </h2>
+ <p className="mt-2 text-fd-muted-foreground">
+ Real-world examples to get you started quickly
+ </p>
+ </div>
+ <Link
+ href="/examples"
+ className="hidden items-center gap-1 text-sm font-medium text-fd-muted-foreground transition-colors hover:text-fd-foreground sm:inline-flex"
+ >
+ View all
+ <ChevronRight className="h-4 w-4" />
+ </Link>
+ </div>
+
+ <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+ {featuredExamples.map((example) => (
+ <Link
+ key={example.title}
+ href={example.href}
+ className="group relative overflow-hidden rounded-xl border border-fd-border bg-fd-card/50 backdrop-blur-sm transition-all duration-300 hover:border-fd-primary/30 hover:bg-fd-card"
+ >
+ {/* Gradient header */}
+ <div className="relative aspect-[16/10] overflow-hidden bg-gradient-to-br from-fd-muted to-fd-accent">
+ {/* Decorative elements */}
+ <div className="absolute inset-0 flex items-center justify-center">
+ <div
+ className="h-20 w-20 rounded-xl border border-fd-border/50 bg-fd-background/80 backdrop-blur-sm transition-transform duration-300 group-hover:scale-105"
+ style={{
+ boxShadow: '0 8px 32px rgba(0, 0, 0, 0.1)',
+ }}
+ >
+ <div className="flex h-full w-full items-center justify-center">
+ <Code2 className="h-8 w-8 text-fd-muted-foreground" />
+ </div>
+ </div>
+ </div>
+ {/* Subtle gradient overlay */}
+ <div className="absolute inset-0 bg-gradient-to-t from-fd-card/80 to-transparent" />
+ </div>
+
+ <div className="p-4">
+ <h3 className="font-semibold transition-colors group-hover:text-sky-500">
+ {example.title}
+ </h3>
+ <p className="mt-1 line-clamp-2 text-sm text-fd-muted-foreground">
+ {example.description}
+ </p>
+ </div>
+ </Link>
+ ))}
+ </div>
+
+ {/* Mobile "View all" link */}
+ <div className="mt-6 text-center sm:hidden">
+ <Link
+ href="/examples"
+ className="inline-flex items-center gap-1 text-sm font-medium text-fd-muted-foreground transition-colors hover:text-fd-foreground"
+ >
+ View all examples
+ <ChevronRight className="h-4 w-4" />
+ </Link>
+ </div>
+ </section>
+
+ {/* Quick links section */}
+ <section className="container mx-auto px-6 py-12 lg:px-8">
+ <div className="rounded-xl border border-fd-border bg-gradient-to-br from-fd-card/50 to-fd-card p-8 backdrop-blur-sm">
+ <div className="mx-auto max-w-2xl text-center">
+ <h2
+ className="text-xl font-bold md:text-2xl"
+ style={{ fontFamily: 'var(--font-urbanist)' }}
+ >
+ Ready to build?
+ </h2>
+ <p className="mt-2 text-fd-muted-foreground">
+ Start building computer-use agents in minutes with our quickstart guide.
+ </p>
+ <div className="mt-6 flex flex-wrap items-center justify-center gap-3">
+ <Link
+ href="/guide/get-started/quickstart"
+ className="inline-flex items-center gap-2 rounded-xl bg-fd-foreground px-6 py-2.5 text-sm font-medium text-fd-background transition-colors hover:bg-fd-foreground/90"
+ >
+ Quickstart Guide
+ <ArrowRight className="h-4 w-4" />
+ </Link>
+ <Link
+ href="/reference/agent-sdk/agent-loops"
+ className="inline-flex items-center gap-2 rounded-xl border border-fd-border px-6 py-2.5 text-sm font-medium transition-colors hover:bg-fd-accent"
+ >
+ Agent Loops
+ </Link>
+ <Link
+ href="/reference/computer-sdk/computers"
+ className="inline-flex items-center gap-2 rounded-xl border border-fd-border px-6 py-2.5 text-sm font-medium transition-colors hover:bg-fd-accent"
+ >
+ Computer SDK
+ </Link>
+ </div>
+ </div>
+ </div>
+ </section>
+ </div>
+ );
+}
diff --git a/docs/src/app/layout.config.tsx b/docs/src/app/layout.config.tsx
index b0622452f2..87414d2c17 100644
--- a/docs/src/app/layout.config.tsx
+++ b/docs/src/app/layout.config.tsx
@@ -1,78 +1,50 @@
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
-
import Image from 'next/image';
import LogoBlack from '@/assets/logo-black.svg';
import LogoWhite from '@/assets/logo-white.svg';
-import DiscordWhite from '@/assets/discord-white.svg';
-import DiscordBlack from '@/assets/discord-black.svg';
-import { HomeIcon } from 'lucide-react';
/**
- * Shared layout configurations
- *
- * you can customise layouts individually from:
- * Home Layout: app/(home)/layout.tsx
- * Docs Layout: app/docs/layout.tsx
+ * Shared layout configurations using Fumadocs native navigation
*/
export const baseOptions: BaseLayoutProps = {
nav: {
title: (
<div className="flex items-center gap-2">
<Image
- width={40}
- height={40}
+ width={24}
+ height={24}
src={LogoBlack}
aria-label="Logo"
className="block dark:hidden"
alt="Logo"
/>
<Image
- width={40}
- height={40}
+ width={24}
+ height={24}
src={LogoWhite}
aria-label="Logo"
className="hidden dark:block"
alt="Logo"
/>
- <span className="text-lg font-bold" style={{ fontFamily: 'var(--font-urbanist)' }}>
+ <span className="font-semibold" style={{ fontFamily: 'var(--font-urbanist)' }}>
Cua
</span>
+ <span className="text-sky-500 font-medium">Docs</span>
</div>
),
- url: 'https://cua.ai',
},
- githubUrl: 'https://github.com/trycua/cua',
links: [
{
- url: 'https://cua.ai',
- text: 'Cua Home',
type: 'icon',
- icon: <HomeIcon />,
- external: true,
- },
- {
url: 'https://discord.com/invite/mVnXXpdE85',
text: 'Discord',
- type: 'icon',
icon: (
- <>
- <Image
- width={20}
- height={20}
- alt="Discord"
- className="hidden dark:block opacity-70 hover:opacity-100"
- src={DiscordWhite}
- />
- <Image
- width={20}
- height={20}
- alt="Discord"
- className="dark:hidden block opacity-55 hover:opacity-100"
- src={DiscordBlack}
- />
- </>
+ <svg viewBox="0 0 24 24" fill="currentColor" className="w-5 h-5">
+ <path 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" />
+ </svg>
),
external: true,
},
],
+ githubUrl: 'https://github.com/trycua/cua',
};
diff --git a/docs/src/app/layout.tsx b/docs/src/app/layout.tsx
index 727b2aedea..cd5ef8c131 100644
--- a/docs/src/app/layout.tsx
+++ b/docs/src/app/layout.tsx
@@ -32,8 +32,26 @@ export default function Layout({ children }: { children: ReactNode }) {
>
<head>
<link rel="icon" href="/docs/favicon.ico" sizes="any" />
+ <script
+ dangerouslySetInnerHTML={{
+ __html: `
+ // Suppress Radix UI hydration warnings in development
+ if (typeof window !== 'undefined') {
+ const originalError = console.error;
+ console.error = (...args) => {
+ if (args[0]?.includes?.('A tree hydrated but some attributes') ||
+ args[0]?.includes?.('Hydration failed') ||
+ (typeof args[0] === 'string' && args[0].includes('aria-controls'))) {
+ return;
+ }
+ originalError.apply(console, args);
+ };
+ }
+ `,
+ }}
+ />
</head>
- <body className="flex min-h-screen flex-col">
+ <body className="flex min-h-screen flex-col" suppressHydrationWarning>
<PHProvider>
<Suspense fallback={null}>
<PostHogPageView />
diff --git a/docs/src/lib/source.ts b/docs/src/lib/source.ts
index 401b3f7270..edc67ce558 100644
--- a/docs/src/lib/source.ts
+++ b/docs/src/lib/source.ts
@@ -34,6 +34,15 @@ const brandIcons: Record<string, () => React.ReactElement> = {
),
};
+// Icon resolver
+function iconResolver(icon: string | undefined) {
+ if (!icon) return;
+ // Check brand icons first (github, discord, etc.)
+ if (icon in brandIcons) return brandIcons[icon]();
+ // Fall back to Lucide icons
+ if (icon in icons) return createElement(icons[icon as keyof typeof icons]);
+}
+
/**
* Returns available API doc versions for a given section (e.g., 'agent').
* Each version is an object: { label, slug }
@@ -66,16 +75,9 @@ export async function getApiVersions(
];
}
-// See https://fumadocs.vercel.app/docs/headless/source-api for more info
+// Single docs source
export const source = loader({
- // it assigns a URL to your pages
baseUrl: '/',
source: docs.toFumadocsSource(),
- icon(icon) {
- if (!icon) return;
- // Check brand icons first (github, discord, etc.)
- if (icon in brandIcons) return brandIcons[icon]();
- // Fall back to Lucide icons
- if (icon in icons) return createElement(icons[icon as keyof typeof icons]);
- },
+ icon: iconResolver,
});
diff --git a/docs/src/middleware.ts b/docs/src/middleware.ts
new file mode 100644
index 0000000000..6a35451c9a
--- /dev/null
+++ b/docs/src/middleware.ts
@@ -0,0 +1,20 @@
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+ const requestHeaders = new Headers(request.headers);
+ requestHeaders.set('x-pathname', request.nextUrl.pathname);
+
+ return NextResponse.next({
+ request: {
+ headers: requestHeaders,
+ },
+ });
+}
+
+export const config = {
+ matcher: [
+ // Match all paths except static files
+ '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
+ ],
+};