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.

chore: remove legacy docs directories

f-trycua76d8e2b892b3
diff --git a/docs/content/examples/example-usecases/form-filling.mdx b/docs/content/examples/example-usecases/form-filling.mdx
deleted file mode 100644
index d133aa026f..0000000000
--- a/docs/content/examples/example-usecases/form-filling.mdx
+++ /dev/null
@@ -1,500 +0,0 @@
----
-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
deleted file mode 100644
index 4a3d1d0fbc..0000000000
--- a/docs/content/examples/example-usecases/gemini-complex-ui-navigation.mdx
+++ /dev/null
@@ -1,640 +0,0 @@
----
-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/examples/example-usecases/meta.json b/docs/content/examples/example-usecases/meta.json
deleted file mode 100644
index ca97021975..0000000000
--- a/docs/content/examples/example-usecases/meta.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "title": "Cookbook",
- "description": "Real-world examples of building with Cua",
- "pages": [
- "windows-app-behind-vpn",
- "form-filling",
- "post-event-contact-export",
- "gemini-complex-ui-navigation"
- ]
-}
diff --git a/docs/content/examples/example-usecases/post-event-contact-export.mdx b/docs/content/examples/example-usecases/post-event-contact-export.mdx
deleted file mode 100644
index 7eaef59662..0000000000
--- a/docs/content/examples/example-usecases/post-event-contact-export.mdx
+++ /dev/null
@@ -1,482 +0,0 @@
----
-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
deleted file mode 100644
index 7779a40fed..0000000000
--- a/docs/content/examples/example-usecases/windows-app-behind-vpn.mdx
+++ /dev/null
@@ -1,629 +0,0 @@
----
-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
deleted file mode 100644
index c68a56d119..0000000000
--- a/docs/content/examples/index.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-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
deleted file mode 100644
index af22048108..0000000000
--- a/docs/content/examples/meta.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "title": "Examples",
- "description": "Example use cases and cookbook",
- "root": true,
- "defaultOpen": true,
- "pages": [
- "index",
- "...example-usecases"
- ]
-}
diff --git a/docs/content/guide/get-started/meta.json b/docs/content/guide/get-started/meta.json
deleted file mode 100644
index f7f9fac24b..0000000000
--- a/docs/content/guide/get-started/meta.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
- "title": "Get Started",
- "description": "Get started with Cua",
- "defaultOpen": true,
- "icon": "Rocket",
- "pages": ["quickstart"]
-}
diff --git a/docs/content/guide/get-started/quickstart.mdx b/docs/content/guide/get-started/quickstart.mdx
deleted file mode 100644
index bd1448467d..0000000000
--- a/docs/content/guide/get-started/quickstart.mdx
+++ /dev/null
@@ -1,1084 +0,0 @@
----
-title: Quickstart
-description: Get started with Cua
----
-
-import { Step, Steps } from 'fumadocs-ui/components/steps';
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
-import { Code, Terminal } from 'lucide-react';
-
-{/* Choose your quickstart path:
-
-<div className="grid grid-cols-1 md:grid-cols-2 gap-6 mt-8 mb-8">
- <Card icon={<Code />} href="#developer-quickstart" title="Developer Quickstart">
- Build with Python or TypeScript SDKs - full programmatic control
- </Card>
- <Card icon={<Terminal />} href="#cli-quickstart" title="CLI Quickstart">
- Get started quickly with the command-line interface
- </Card>
-</div> */}
-
-## Set Up Your Computer Sanbox
-
-Choose how you want to run your Cua sandbox. This will be the isolated environment where your automated tasks will execute.
-
-You can run your Cua sandbox in the cloud (recommended for easiest setup), locally in a Docker container on any platform, on a macOS VM with Lume, or on Windows with a Windows Sandbox. Choose the option that matches your system and needs.
-
-<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>
-
----
-
-## Automate Your Sandbox
-
-<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>
-
-This section guides you through building automation in layers:
-
-1. **Cua Computer Framework** - Direct sandbox control for manual automation and testing
-2. **Cua Agent Framework** - Adds AI automation on top, using vision-language models to understand and interact with the UI
-
-Start by setting up Cua Computer Framework to verify your sandbox works, then add Cua Agent Framework on top to enable intelligent, autonomous automation.
-
-<Steps>
-
-<Step>
-
-### Step 1: Connect with Cua Computer Framework
-
-Install Cua Computer Framework and verify your sandbox is working by performing basic interactions such as taking screenshots or simulating user input. This is an important verification step before adding AI agents.
-
-<Tabs items={['Python', 'TypeScript']}>
- <Tab value="Python">
- Install the Cua computer Python SDK:
-
- **Using uv (recommended):**
- ```bash
- uv pip install cua-computer
- ```
-
- **Or with pip:**
- ```bash
- pip install cua-computer
- ```
-
- Then, connect to your desired computer environment:
-
- <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
- # Alternative: If your VM is not running, use start() instead:
- # await computer.start() # Start and 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()
- # Alternative: If you want to fully stop the VM, use stop() instead:
- # await computer.stop() # Fully stop VM and 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
- # Alternative: If your VM is not running, use start() instead:
- # await computer.start() # Start and 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()
- # Alternative: If you want to fully stop the VM, use stop() instead:
- # await computer.stop() # Fully stop VM and 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
- # Alternative: If your VM is not running, use start() instead:
- # await computer.start() # Start and connect
-
- 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()
- # Alternative: If you want to fully stop the VM, use stop() instead:
- # await computer.stop() # Fully stop VM and 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
- # Alternative: If your VM is not running, use start() instead:
- # await computer.start() # Start and connect
-
- 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()
- # Alternative: If you want to fully stop the VM, use stop() instead:
- # await computer.stop() # Fully stop VM and 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:
- # Take a screenshot of the Android screen
- 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>
- </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
- # Alternative: If your VM is not running, use start() instead:
- # await computer.start() # Start and 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()
- # Alternative: If you want to fully stop the VM, use stop() instead:
- # await computer.stop() # Fully stop VM and 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
- # Alternative: If your VM is not running, use start() instead:
- # await computer.start() # Start and 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()
- # Alternative: If you want to fully stop the VM, use stop() instead:
- # await computer.stop() # Fully stop VM and 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
- # Alternative: If your computer server is not running, use start() instead:
- # await computer.start() # Start and connect to the host desktop
-
- 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()
- # Alternative: If you want to fully stop everything, use stop() instead:
- # await computer.stop() # Fully stop and disconnect
-
- asyncio.run(main())
- ```
- </Tab>
- </Tabs>
-
- </Tab>
- <Tab value="TypeScript">
- Install the Cua computer TypeScript SDK:
- ```bash
- npm install @trycua/computer
- ```
-
- Then, connect to your desired computer environment:
-
- <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>
-
-Learn more about computers in the [Cua computers documentation](/computer-sdk/computers).
-
-</Step>
-
-<Step>
-
-### Step 2: Add AI Automation with Cua Agent Framework
-
-![What Is a Computer Use Agent?](/img/what-is-cua.png)
-
-Now that you've verified your sandbox works, use an Agent to automate complex tasks by providing it with a goal. The agent will interact with the computer environment using a vision-language model to understand the UI and execute actions.
-
-While you can build your own agent loop with any LLM, Cua Agent Framework is the recommended approach as it 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
-
-<Tabs items={['Python', 'TypeScript']}>
- <Tab value="Python">
- Install the Cua agent Python SDK:
-
- **Using uv (recommended):**
- ```bash
- uv pip install "cua-agent[all]"
- ```
-
- **Or with pip:**
- ```bash
- pip install "cua-agent[all]"
- ```
-
- Choose how you want to access vision-language models for your agent:
-
-<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.
-
- **Use the agent with Cua models:**
- ```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
- # Alternative: If your VM is not running, use start() instead:
- # await computer.start() # Start and 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()
- # Alternative: If you want to fully stop the VM, use stop() instead:
- # await computer.stop() # Fully stop VM and 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, recommended for balance)
-
- **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.
-
- **Use the agent with your provider:**
- ```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
- # Alternative: If your VM is not running, use start() instead:
- # await computer.start() # Start and 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()
- # Alternative: If you want to fully stop the VM, use stop() instead:
- # await computer.stop() # Fully stop VM and 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](/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. The Vercel AI SDK provides a unified interface for building multi-step agent workflows with language models.
-
- Install the required packages:
-
- ```bash
- npm install @trycua/computer ai
- ```
-
- Here's an example of building an agent loop with the Vercel AI SDK:
-
- ```typescript
- import Anthropic from "@anthropic-ai/sdk";
- import { Computer, OSType } from "@trycua/computer";
- import { generateText } from "ai";
- import { anthropic } from "@ai-sdk/anthropic";
-
- 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[] = [];
-
- // First message with goal
- messages.push({
- role: "user",
- content: goal,
- });
-
- // Agent loop
- for (let i = 0; i < 10; i++) {
- // Get model response with tool use
- const response = await client.messages.create({
- model: "claude-opus-4-1-20250805",
- max_tokens: 4096,
- tools: [computerTool],
- messages: messages,
- });
-
- // Check if we're done
- if (response.stop_reason === "end_turn") {
- console.log("Task completed!");
- break;
- }
-
- // Add assistant response to history
- messages.push({
- role: "assistant",
- content: response.content,
- });
-
- // Process tool calls
- const toolResults = [];
- for (const block of response.content) {
- if (block.type === "tool_use") {
- try {
- 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;
- case "key_press":
- result = await computer.interface.key_press(block.input.text);
- break;
- default:
- result = { error: "Unknown action" };
- }
-
- toolResults.push({
- type: "tool_result",
- tool_use_id: block.id,
- content: JSON.stringify(result),
- });
- } catch (error) {
- toolResults.push({
- type: "tool_result",
- tool_use_id: block.id,
- content: `Error: ${error}`,
- is_error: true,
- });
- }
- }
- }
-
- // Add tool results to messages
- if (toolResults.length > 0) {
- messages.push({
- role: "user",
- content: toolResults,
- });
- }
- }
-
- await computer.disconnect();
- }
-
- // Run the agent
- runAgentLoop("Take a screenshot and tell me what you see");
- ```
-
- For more details and examples, see the [Vercel AI SDK Computer Use Cookbook](https://ai-sdk.dev/cookbook/guides/computer-use).
-
- </Tab>
-</Tabs>
-
-Learn more about agents in [Agent Loops](/agent-sdk/agent-loops) and available models in [Supported Models](/agent-sdk/supported-model-providers/).
-
-</Step>
-</Steps>
-
-### Next Steps
-
-- Explore [Cua Computer Framework Commands](/computer-sdk/commands) for more sandbox interactions
-- Learn about [Agent Loops](/agent-sdk/agent-loops) and advanced agent configuration
-- Check out [Custom Tools](/agent-sdk/custom-tools) to extend your agents
-- Review [Supported Model Providers](/agent-sdk/supported-model-providers/) for more LLM options
-- Try the [Form Filling](/example-usecases/form-filling) example use case
-- Join our [Discord community](https://discord.com/invite/cua-ai) for help and discussion
-
-{/* ---
-
-## CLI Quickstart
-
-Get started quickly with the Cua CLI - the easiest way to manage cloud sandboxes and run AI agents.
-
-<Steps>
-<Step>
-
-### Install the Cua CLI
-
-<Tabs items={['macOS / Linux', 'Windows', 'Bun (Alternative)', 'From Source']}>
- <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>
- <Tab value="Bun (Alternative)">
- ```bash
- # Install Bun if you don't have it
- curl -fsSL https://bun.sh/install | bash
-
- # Install Cua CLI
- bun add -g @trycua/cli
- ```
- </Tab>
- <Tab value="From Source">
- ```bash
- # Install Bun (macOS/Linux)
- curl -fsSL https://bun.sh/install | bash
-
- # Install Bun (Windows)
- # powershell -c "irm bun.sh/install.ps1|iex"
-
- # Clone the repo
- git clone https://github.com/trycua/cua
- cd cua/libs/typescript/cua-cli
-
- # Install the CLI
- bun install
- bun link
- bun link cua-cli
- ```
-
- </Tab>
-</Tabs>
-
-</Step>
-
-<Step>
-
-### Authenticate with CUA
-
-Login to your CUA account:
-
-```bash
-# Interactive browser login (recommended)
-cua auth login
-
-# Or provide your API key directly
-cua auth login --api-key sk-your-api-key-here
-```
-
-If you don't have a CUA account yet, sign up at [cua.ai/signin](https://cua.ai/signin).
-
-</Step>
-
-<Step>
-
-### Create Your First Sandbox
-
-Create a cloud sandbox where your AI agents will run:
-
-```bash
-# Create a Linux sandbox (recommended for most use cases)
-cua sb create --os linux --size small --region north-america
-
-# Or create a Windows sandbox
-cua sb create --os windows --size small --region north-america
-
-```
-
-Your sandbox will be created and you'll see output like:
-
-```
-Sandbox created and ready: my-sandbox-abc123
-Password: secure-password-here
-Host: my-sandbox-abc123.sandbox.cua.ai
-```
-
-</Step>
-
-<Step>
-
-### Start Using Your Sandbox
-
-You can now interact with your sandbox in multiple ways:
-
-
-
-#### Option 1: Access VNC Desktop
-
-```bash
-cua sb vnc my-sandbox-abc123
-```
-
-This opens a remote desktop connection to your sandbox.
-
-#### Option 2: List and Manage Sandboxes
-
-```bash
-# List all your sandboxes
-cua sb list
-
-# Start/stop sandboxes as needed
-cua sb stop my-sandbox-abc123
-cua sb start my-sandbox-abc123
-
-# Delete sandboxes when done
-cua sb delete my-sandbox-abc123
-```
-
-</Step>
-
-</Steps>
-
-### What's Next?
-
-- **Explore more commands**: Check out the [complete CLI reference](/libraries/cua-cli/commands)
-- **Learn about programming**: Try the [Developer Quickstart](#developer-quickstart) to build custom automations
-- **Join the community**: Get help in our [Discord community](https://discord.com/invite/mVnXXpdE85)
-
----
-
-For running models locally, see [Running Models Locally](/agent-sdk/supported-model-providers/local-models). */}
diff --git a/docs/content/guide/index.mdx b/docs/content/guide/index.mdx
deleted file mode 100644
index 2306c7009c..0000000000
--- a/docs/content/guide/index.mdx
+++ /dev/null
@@ -1,60 +0,0 @@
----
-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
deleted file mode 100644
index d729bd2d3c..0000000000
--- a/docs/content/guide/introduction.mdx
+++ /dev/null
@@ -1,61 +0,0 @@
----
-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?
-
-![What is a Computer-Use Agent?](/img/what-is-cua.png)
-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?
-
-![What is a Computer-Use Sandbox?](/img/what-is-sandbox.png)
-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, GUI automation 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
deleted file mode 100644
index 1031551f6b..0000000000
--- a/docs/content/guide/meta.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "title": "Guide",
- "description": "Get started with Cua",
- "root": true,
- "defaultOpen": true,
- "pages": [
- "index",
- "...get-started"
- ]
-}
diff --git a/docs/content/reference/agent-sdk/agent-loops.mdx b/docs/content/reference/agent-sdk/agent-loops.mdx
deleted file mode 100644
index 2fe4cea9fb..0000000000
--- a/docs/content/reference/agent-sdk/agent-loops.mdx
+++ /dev/null
@@ -1,202 +0,0 @@
----
-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.
-
-### Response Format
-
-```python
-{
- "output": [
- {
- "type": "message",
- "role": "assistant",
- "content": [{"type": "output_text", "text": "I can see..."}]
- },
- {
- "type": "computer_call",
- "action": {"type": "screenshot"},
- "call_id": "call_123"
- },
- {
- "type": "computer_call_output",
- "call_id": "call_123",
- "output": {"image_url": "data:image/png;base64,..."}
- }
- ],
- "usage": {
- "prompt_tokens": 150,
- "completion_tokens": 75,
- "total_tokens": 225,
- "response_cost": 0.01,
- }
-}
-```
-
-### Environment Variables
-
-Use the following environment variables to configure the agent and its access to cloud computers and LLM providers:
-
-```bash
-# Computer instance (cloud)
-export CUA_SANDBOX_NAME="your-sandbox-name"
-export CUA_API_KEY="your-cua-api-key"
-
-# LLM API keys
-export ANTHROPIC_API_KEY="your-anthropic-key"
-export OPENAI_API_KEY="your-openai-key"
-```
-
-### Input and output
-
-The input prompt passed to `Agent.run` can either be a string or a list of message dictionaries:
-
-```python
-messages = [
- {
- "role": "user",
- "content": "Take a screenshot and describe what you see"
- },
- {
- "role": "assistant",
- "content": "I'll take a screenshot for you."
- }
-]
-```
-
-The output is an AsyncGenerator that yields response chunks.
-
-### Parameters
-
-The `ComputerAgent` constructor provides a wide range of options for customizing agent behavior, tool integration, callbacks, resource management, and more.
-
-- `model` (`str`): Default: **required**
- The LLM or agent model to use. Determines which agent loop is selected unless `custom_loop` is provided. (e.g., "claude-sonnet-4-5-20250929", "computer-use-preview", "omni+vertex_ai/gemini-pro")
-- `tools` (`List[Any]`):
- List of tools the agent can use (e.g., `Computer`, sandboxed Python functions, etc.).
-- `custom_loop` (`Callable`):
- Optional custom agent loop function. If provided, overrides automatic loop selection.
-- `only_n_most_recent_images` (`int`):
- If set, only the N most recent images are kept in the message history. Useful for limiting memory usage. Automatically adds `ImageRetentionCallback`.
-- `callbacks` (`List[Any]`):
- List of callback instances for advanced preprocessing, postprocessing, logging, or custom hooks. See [Callbacks & Extensibility](#callbacks--extensibility).
-- `verbosity` (`int`):
- Logging level (e.g., `logging.INFO`). If set, adds a logging callback.
-- `trajectory_dir` (`str`):
- Directory path to save full trajectory data, including screenshots and responses. Adds `TrajectorySaverCallback`.
-- `max_retries` (`int`): Default: `3`
- Maximum number of retries for failed API calls (default: 3).
-- `screenshot_delay` (`float` | `int`): Default: `0.5`
- Delay (in seconds) before taking screenshots (default: 0.5).
-- `use_prompt_caching` (`bool`): Default: `False`
- Enables prompt caching for repeated prompts (mainly for Anthropic models).
-- `max_trajectory_budget` (`float` | `dict`):
- If set (float or dict), adds a budget manager callback that tracks usage costs and stops execution if the budget is exceeded. Dict allows advanced options (e.g., `{ "max_budget": 5.0, "raise_error": True }`).
-- `instructions` (`str` | `list[str]`):
- System instructions for the agent. Can be a single string or multiple strings in a tuple/list for readability; they are concatenated into one system prompt.
-- `api_key` (`str`):
- Optional API key override for the model provider.
-- `api_base` (`str`):
- Optional API base URL override for the model provider.
-- `**additional_generation_kwargs` (`any`):
- Any additional keyword arguments are passed through to the agent loop or model provider.
-
-**Example with advanced options:**
-
-```python
-from agent import ComputerAgent
-from computer import Computer
-from agent.callbacks import ImageRetentionCallback
-
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- tools=[Computer(...)],
- only_n_most_recent_images=3,
- callbacks=[ImageRetentionCallback(only_n_most_recent_images=3)],
- verbosity=logging.INFO,
- trajectory_dir="trajectories",
- max_retries=5,
- screenshot_delay=1.0,
- use_prompt_caching=True,
- max_trajectory_budget={"max_budget": 5.0, "raise_error": True},
- instructions=(
- "You are a helpful computer-using agent"
- "Output computer calls until you complete the given task"
- ),
- api_key="your-api-key",
- api_base="https://your-api-base.com/v1",
-)
-```
-
-### Streaming Responses
-
-```python
-async for result in agent.run(messages, stream=True):
- # Process streaming chunks
- for item in result["output"]:
- if item["type"] == "message":
- print(item["content"][0]["text"], end="", flush=True)
- elif item["type"] == "computer_call":
- action = item["action"]
- print(f"\n[Action: {action['type']}]")
-```
-
-### Error Handling
-
-```python
-try:
- async for result in agent.run(messages):
- # Process results
- pass
-except BudgetExceededException:
- print("Budget limit exceeded")
-except Exception as e:
- print(f"Agent error: {e}")
-```
diff --git a/docs/content/reference/agent-sdk/benchmarks/index.mdx b/docs/content/reference/agent-sdk/benchmarks/index.mdx
deleted file mode 100644
index 685a8f92fe..0000000000
--- a/docs/content/reference/agent-sdk/benchmarks/index.mdx
+++ /dev/null
@@ -1,29 +0,0 @@
----
-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
deleted file mode 100644
index 43170ca461..0000000000
--- a/docs/content/reference/agent-sdk/benchmarks/interactive.mdx
+++ /dev/null
@@ -1,21 +0,0 @@
----
-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
deleted file mode 100644
index 67a90769bd..0000000000
--- a/docs/content/reference/agent-sdk/benchmarks/introduction.mdx
+++ /dev/null
@@ -1,58 +0,0 @@
----
-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
deleted file mode 100644
index 8067bb0114..0000000000
--- a/docs/content/reference/agent-sdk/benchmarks/meta.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
- "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
deleted file mode 100644
index 26e4b7e44e..0000000000
--- a/docs/content/reference/agent-sdk/benchmarks/osworld-verified.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
----
-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
deleted file mode 100644
index 15739d9d11..0000000000
--- a/docs/content/reference/agent-sdk/benchmarks/screenspot-pro.mdx
+++ /dev/null
@@ -1,25 +0,0 @@
----
-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
deleted file mode 100644
index ba78d5f915..0000000000
--- a/docs/content/reference/agent-sdk/benchmarks/screenspot-v2.mdx
+++ /dev/null
@@ -1,25 +0,0 @@
----
-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/reference/agent-sdk/callbacks/agent-lifecycle.mdx b/docs/content/reference/agent-sdk/callbacks/agent-lifecycle.mdx
deleted file mode 100644
index 1fb4afe79b..0000000000
--- a/docs/content/reference/agent-sdk/callbacks/agent-lifecycle.mdx
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Agent Lifecycle
-description: Agent callback lifecycle and hooks
----
-
-# Callbacks
-
-Callbacks provide hooks into the agent lifecycle for extensibility. They're called in a specific order during agent execution.
-
-## Callback Lifecycle
-
-### 1. `on_run_start(kwargs, old_items)`
-
-Called once when agent run begins. Initialize tracking, logging, or state.
-
-### 2. `on_run_continue(kwargs, old_items, new_items)` → bool
-
-Called before each iteration. Return `False` to stop execution (e.g., budget limits).
-
-### 3. `on_llm_start(messages)` → messages
-
-Preprocess messages before LLM call. Use for PII anonymization, image retention.
-
-### 4. `on_api_start(kwargs)`
-
-Called before each LLM API call.
-
-### 5. `on_api_end(kwargs, result)`
-
-Called after each LLM API call completes.
-
-### 6. `on_usage(usage)`
-
-Called when usage information is received from LLM.
-
-### 7. `on_llm_end(messages)` → messages
-
-Postprocess messages after LLM call. Use for PII deanonymization.
-
-### 8. `on_responses(kwargs, responses)`
-
-Called when responses are received from agent loop.
-
-### 9. Response-specific hooks:
-
-- `on_text(item)` - Text messages
-- `on_computer_call_start(item)` - Before computer actions
-- `on_computer_call_end(item, result)` - After computer actions
-- `on_function_call_start(item)` - Before function calls
-- `on_function_call_end(item, result)` - After function calls
-- `on_screenshot(screenshot, name)` - When screenshots are taken
-
-### 10. `on_run_end(kwargs, old_items, new_items)`
-
-Called when agent run completes. Finalize tracking, save trajectories.
diff --git a/docs/content/reference/agent-sdk/callbacks/cost-saving.mdx b/docs/content/reference/agent-sdk/callbacks/cost-saving.mdx
deleted file mode 100644
index 636eda3bbb..0000000000
--- a/docs/content/reference/agent-sdk/callbacks/cost-saving.mdx
+++ /dev/null
@@ -1,92 +0,0 @@
----
-title: Cost Optimization
-description: Budget management and image retention for cost optimization
----
-
-# Cost Optimization Callbacks
-
-Optimize agent costs with budget management and image retention callbacks.
-
-## Budget Manager Callbacks Example
-
-```python
-from 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
- )
- ]
-)
-```
-
-## Budget Manager Shorthand
-
-```python
-# Simple budget limit
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- max_trajectory_budget=5.0 # $5 limit
-)
-```
-
-**Or with options:**
-
-```python
-# Advanced budget configuration
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- max_trajectory_budget={
- "max_budget": 10.0,
- "raise_error": True, # Raise error when exceeded
- "reset_after_each_run": False # Persistent across runs
- }
-)
-```
-
-## Image Retention Callbacks Example
-
-```python
-from agent.callbacks import ImageRetentionCallback
-
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- tools=[computer],
- callbacks=[
- ImageRetentionCallback(only_n_most_recent_images=3)
- ]
-)
-```
-
-## Image Retention Shorthand
-
-```python
-agent = ComputerAgent(
- model="anthropic/claude-sonnet-4-5-20250929",
- tools=[computer],
- 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
-)
-```
-
-## Budget Manager 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)
diff --git a/docs/content/reference/agent-sdk/callbacks/index.mdx b/docs/content/reference/agent-sdk/callbacks/index.mdx
deleted file mode 100644
index a02cea9e33..0000000000
--- a/docs/content/reference/agent-sdk/callbacks/index.mdx
+++ /dev/null
@@ -1,64 +0,0 @@
----
-title: Callbacks
----
-
-Callbacks in the Agent SDK provide hooks into the agent's lifecycle, allowing for custom functionality to be executed at various stages of an agent's run. They enable extensibility by allowing developers to integrate their own logic for tasks such as logging, cost management, and data anonymization.
-
-## Usage
-
-You can add preprocessing and postprocessing hooks using callbacks, or write your own by subclassing `AsyncCallbackHandler`.
-
-### Built-in Callbacks
-
-Built-in callbacks can be used as follows:
-
-```python
-from 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)
- ]
-)
-```
-
-The following built-in callbacks are available:
-
-- [BudgetManagerCallback](callbacks/cost-saving): Stops execution when budget exceeded
-- [LoggingCallback](callbacks/trajectories): Logs agent activities
-- **ImageRetentionCallback**: Limits recent images in context
-- **TrajectorySaverCallback**: Saves conversation trajectories
-- [PII Anonymization](callbacks/pii-anonymization)
-
-### Custom Callbacks
-
-Create custom callbacks using knowlege of the callback lifecycle as described in [Agent Lifecycle](callbacks/agent-lifecycle).
-
-```python
-from 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/reference/agent-sdk/callbacks/logging.mdx b/docs/content/reference/agent-sdk/callbacks/logging.mdx
deleted file mode 100644
index 62e3d9b253..0000000000
--- a/docs/content/reference/agent-sdk/callbacks/logging.mdx
+++ /dev/null
@@ -1,89 +0,0 @@
----
-title: Logging
-description: Agent logging and custom logger implementation
----
-
-# Logging Callback
-
-Built-in logging callback and custom logger creation for agent monitoring.
-
-## Callbacks Example
-
-```python
-from 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 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)
-
- # Add console handler
- 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")]
-)
-```
-
-## Available Hooks
-
-Log any agent event using these callback methods:
-
-- `on_run_start/end` - Run lifecycle
-- `on_computer_call_start/end` - Computer actions
-- `on_api_start/end` - LLM API calls
-- `on_usage` - Cost tracking
-- `on_screenshot` - Screenshot events
diff --git a/docs/content/reference/agent-sdk/callbacks/meta.json b/docs/content/reference/agent-sdk/callbacks/meta.json
deleted file mode 100644
index b1b7085aba..0000000000
--- a/docs/content/reference/agent-sdk/callbacks/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "title": "Callbacks",
- "description": "Extending agents with callback hooks and built-in handlers",
- "pages": ["agent-lifecycle", "trajectories", "logging", "cost-saving", "pii-anonymization"]
-}
diff --git a/docs/content/reference/agent-sdk/callbacks/pii-anonymization.mdx b/docs/content/reference/agent-sdk/callbacks/pii-anonymization.mdx
deleted file mode 100644
index fcfd0861ae..0000000000
--- a/docs/content/reference/agent-sdk/callbacks/pii-anonymization.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: PII Anonymization
-description: PII anonymization and data protection callbacks
----
-
-# PII Anonymization Callback
-
-🚧 Coming Soon 🚧
-
-🔒 🕵️ 🛡️ 📝 ✨
-
-🚀 Stay tuned for PII anonymization features! 🚀
diff --git a/docs/content/reference/agent-sdk/callbacks/trajectories.mdx b/docs/content/reference/agent-sdk/callbacks/trajectories.mdx
deleted file mode 100644
index ade285f3e8..0000000000
--- a/docs/content/reference/agent-sdk/callbacks/trajectories.mdx
+++ /dev/null
@@ -1,60 +0,0 @@
----
-title: Trajectories
-description: Recording and viewing agent conversation trajectories
----
-
-# Trajectory Saving Callback
-
-The TrajectorySaverCallback records complete agent conversations including messages, actions, and screenshots for debugging and analysis.
-
-## Callbacks Example
-
-```python
-from 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
-
-Trajectories are saved with:
-
-- Complete conversation history
-- Usage statistics and costs
-- Timestamps and metadata
-- Screenshots and computer actions
-
-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)
diff --git a/docs/content/reference/agent-sdk/chat-history.mdx b/docs/content/reference/agent-sdk/chat-history.mdx
deleted file mode 100644
index e6740fc339..0000000000
--- a/docs/content/reference/agent-sdk/chat-history.mdx
+++ /dev/null
@@ -1,92 +0,0 @@
----
-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
deleted file mode 100644
index cf1652dd29..0000000000
--- a/docs/content/reference/agent-sdk/custom-tools.mdx
+++ /dev/null
@@ -1,49 +0,0 @@
----
-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
deleted file mode 100644
index 158495e07c..0000000000
--- a/docs/content/reference/agent-sdk/customizing-computeragent.mdx
+++ /dev/null
@@ -1,130 +0,0 @@
----
-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
deleted file mode 100644
index 7bfcbdea35..0000000000
--- a/docs/content/reference/agent-sdk/integrations/hud.mdx
+++ /dev/null
@@ -1,141 +0,0 @@
----
-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/reference/agent-sdk/integrations/meta.json b/docs/content/reference/agent-sdk/integrations/meta.json
deleted file mode 100644
index 39da855e2b..0000000000
--- a/docs/content/reference/agent-sdk/integrations/meta.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "title": "Integrations",
- "pages": ["hud", "observability"]
-}
diff --git a/docs/content/reference/agent-sdk/integrations/observability.mdx b/docs/content/reference/agent-sdk/integrations/observability.mdx
deleted file mode 100644
index 44db0ea461..0000000000
--- a/docs/content/reference/agent-sdk/integrations/observability.mdx
+++ /dev/null
@@ -1,66 +0,0 @@
----
-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
deleted file mode 100644
index 43d76ab57d..0000000000
--- a/docs/content/reference/agent-sdk/mcp-server/client-integrations.mdx
+++ /dev/null
@@ -1,123 +0,0 @@
----
-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
deleted file mode 100644
index 106ce6d983..0000000000
--- a/docs/content/reference/agent-sdk/mcp-server/configuration.mdx
+++ /dev/null
@@ -1,73 +0,0 @@
----
-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
deleted file mode 100644
index 108437f306..0000000000
--- a/docs/content/reference/agent-sdk/mcp-server/index.mdx
+++ /dev/null
@@ -1,17 +0,0 @@
----
-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
deleted file mode 100644
index b9c14f0939..0000000000
--- a/docs/content/reference/agent-sdk/mcp-server/installation.mdx
+++ /dev/null
@@ -1,140 +0,0 @@
----
-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
deleted file mode 100644
index 656def704f..0000000000
--- a/docs/content/reference/agent-sdk/mcp-server/llm-integrations.mdx
+++ /dev/null
@@ -1,18 +0,0 @@
----
-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
deleted file mode 100644
index f5ccb9baee..0000000000
--- a/docs/content/reference/agent-sdk/mcp-server/meta.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "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
deleted file mode 100644
index 0b4616ef05..0000000000
--- a/docs/content/reference/agent-sdk/mcp-server/tools.mdx
+++ /dev/null
@@ -1,66 +0,0 @@
----
-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
deleted file mode 100644
index d65fc64466..0000000000
--- a/docs/content/reference/agent-sdk/mcp-server/usage.mdx
+++ /dev/null
@@ -1,169 +0,0 @@
----
-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
deleted file mode 100644
index ac329d4d20..0000000000
--- a/docs/content/reference/agent-sdk/message-format.mdx
+++ /dev/null
@@ -1,201 +0,0 @@
----
-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/reference/agent-sdk/meta.json b/docs/content/reference/agent-sdk/meta.json
deleted file mode 100644
index 6bb01b62c7..0000000000
--- a/docs/content/reference/agent-sdk/meta.json
+++ /dev/null
@@ -1,20 +0,0 @@
-{
- "title": "Agent SDK",
- "description": "Build computer-using agents with the Agent SDK",
- "pages": [
- "agent-loops",
- "supported-agents",
- "supported-model-providers",
- "chat-history",
- "message-format",
- "customizing-computeragent",
- "callbacks",
- "custom-tools",
- "prompt-caching",
- "usage-tracking",
- "telemetry",
- "benchmarks",
- "integrations",
- "mcp-server"
- ]
-}
diff --git a/docs/content/reference/agent-sdk/migration-guide.mdx b/docs/content/reference/agent-sdk/migration-guide.mdx
deleted file mode 100644
index fd67b282dc..0000000000
--- a/docs/content/reference/agent-sdk/migration-guide.mdx
+++ /dev/null
@@ -1,140 +0,0 @@
----
-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
deleted file mode 100644
index 633830ecf5..0000000000
--- a/docs/content/reference/agent-sdk/prompt-caching.mdx
+++ /dev/null
@@ -1,59 +0,0 @@
----
-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/reference/agent-sdk/supported-agents/composed-agents.mdx b/docs/content/reference/agent-sdk/supported-agents/composed-agents.mdx
deleted file mode 100644
index 89d426cc8d..0000000000
--- a/docs/content/reference/agent-sdk/supported-agents/composed-agents.mdx
+++ /dev/null
@@ -1,128 +0,0 @@
----
-title: Composed Agents
-description: Combine grounding models with any LLM for computer-use capabilities
----
-
-Composed agents combine the best of both worlds: specialized grounding models for precise click prediction and powerful LLMs for task planning and reasoning.
-
-Use the format `"grounding_model+planning_model"` to create a composed agent with any vision-enabled LiteLLM-compatible model.
-
-## How Composed Agents Work
-
-1. **Planning Phase**: The planning model (LLM) analyzes the task and decides what actions to take (e.g., `click("find the login button")`, `type("username")`)
-2. **Grounding Phase**: The grounding model converts element descriptions to precise coordinates
-3. **Execution**: Actions are performed using the predicted coordinates
-
-## Supported Grounding Models
-
-Any model that supports `predict_click()` can be used as the grounding component. See the full list on [Grounding Models](./grounding-models).
-
-- OpenCUA: `huggingface-local/xlangai/OpenCUA-{7B,32B}`
-- GTA1 family: `huggingface-local/HelloKKMe/GTA1-{7B,32B,72B}`
-- Holo 1.5 family: `huggingface-local/Hcompany/Holo1.5-{3B,7B,72B}`
-- InternVL 3.5 family: `huggingface-local/OpenGVLab/InternVL3_5-{1B,2B,4B,8B,...}`
-- UI‑TARS 1.5: `huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B` (also supports full CU)
-- OmniParser (OCR): `omniparser` (requires combination with a LiteLLM vision model)
-- Moondream3: `moondream3` (requires combination with a LiteLLM vision/text model)
-
-## Supported Planning Models
-
-Any vision-enabled LiteLLM-compatible model can be used as the planning component:
-
-- Any All‑in‑one CUA (planning-capable). See [All‑in‑one CUAs](./computer-use-agents).
-- Any VLM via LiteLLM providers: `anthropic/*`, `openai/*`, `openrouter/*`, `gemini/*`, `vertex_ai/*`, `huggingface-local/*`, `mlx/*`, etc.
-- Examples:
- - **Anthropic**: `anthropic/claude-sonnet-4-5-20250929`, `anthropic/claude-opus-4-1-20250805`
- - **OpenAI**: `openai/gpt-5`, `openai/gpt-o3`, `openai/gpt-4o`
- - **Google**: `gemini/gemini-1.5-pro`, `vertex_ai/gemini-pro-vision`
- - **Local models**: Any Hugging Face vision-language model
-
-## Usage Examples
-
-### GTA1 + GPT-5
-
-Use OpenAI's GPT-5 for planning with specialized grounding:
-
-```python
-agent = ComputerAgent(
- "huggingface-local/HelloKKMe/GTA1-7B+openai/gpt-5",
- tools=[computer]
-)
-
-async for _ in agent.run("Take a screenshot, analyze the UI, and click on the most prominent button"):
- pass
-```
-
-### GTA1 + Claude 4.5 Sonnet
-
-Combine state-of-the-art grounding with powerful reasoning:
-
-```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
-# Success! 🎉
-# - Claude 3.5 Sonnet plans the sequence of actions
-# - GTA1-7B provides precise click coordinates for each UI element
-```
-
-### UI-TARS + GPT-4o
-
-Combine two different vision models for enhanced capabilities:
-
-```python
-agent = ComputerAgent(
- "huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B+openai/gpt-4o",
- tools=[computer]
-)
-
-async for _ in agent.run("Help me fill out this form with my personal information"):
- pass
-```
-
-### Moondream3 + GPT-4o
-
-Use the built-in Moondream3 grounding with any planning model. Moondream3 will detect UI elements on the latest screenshot, label them, and provide a user message listing detected element names.
-
-```python
-from agent import ComputerAgent
-from computer import computer
-
-agent = ComputerAgent(
- "moondream3+openai/gpt-4o",
- tools=[computer]
-)
-
-async for _ in agent.run("Close the settings window, then open the Downloads folder"):
- pass
-```
-
-## Benefits of Composed Agents
-
-- **Specialized Grounding**: Use models optimized for click prediction accuracy
-- **Flexible Planning**: Choose any LLM for task reasoning and planning
-- **Cost Optimization**: Use smaller grounding models with larger planning models only when needed
-- **Performance**: Leverage the strengths of different model architectures
-
-## Capabilities
-
-Composed agents support both capabilities:
-
-```python
-agent = ComputerAgent("huggingface-local/HelloKKMe/GTA1-7B+anthropic/claude-sonnet-4-5-20250929")
-
-# Full computer-use agent capabilities
-async for _ in agent.run("Complete this online form"):
- pass
-
-# Direct click prediction (uses grounding model only)
-coords = agent.predict_click("find the submit button")
-```
-
----
-
-For more information on individual model capabilities, see [Computer-Use Agents](./computer-use-agents) and [Grounding Models](./grounding-models).
diff --git a/docs/content/reference/agent-sdk/supported-agents/computer-use-agents.mdx b/docs/content/reference/agent-sdk/supported-agents/computer-use-agents.mdx
deleted file mode 100644
index f799b278ed..0000000000
--- a/docs/content/reference/agent-sdk/supported-agents/computer-use-agents.mdx
+++ /dev/null
@@ -1,93 +0,0 @@
----
-title: All‑in‑one CUA Models
-description: Models that support full computer-use agent capabilities with ComputerAgent.run()
----
-
-These models support complete computer-use agent functionality through `ComputerAgent.run()`. They can understand natural language instructions and autonomously perform sequences of actions to complete tasks.
-
-All agent loops are compatible with any LLM provider supported by LiteLLM.
-
-See [Running Models Locally](/agent-sdk/supported-model-providers/local-models) for how to use Hugging Face and MLX models on your own machine.
-
-## Gemini CUA
-
-Gemini models with computer-use capabilities:
-
-- 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
-```
-
-## Anthropic CUAs
-
-Claude models with computer-use capabilities:
-
-- 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
-```
-
-## OpenAI CUA Preview
-
-OpenAI's computer-use preview model:
-
-- 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
-```
-
-## GLM-4.5V
-
-Zhipu AI's GLM-4.5V vision-language model with computer-use capabilities:
-
-- `openrouter/z-ai/glm-4.5v`
-- `huggingface-local/zai-org/GLM-4.5V`
-
-```python
-agent = ComputerAgent("openrouter/z-ai/glm-4.5v", tools=[computer])
-async for _ in agent.run("Click on the search bar and type 'hello world'"):
- pass
-```
-
-## InternVL 3.5
-
-InternVL 3.5 family:
-
-- `huggingface-local/OpenGVLab/InternVL3_5-{1B,2B,4B,8B,...}`
-
-```python
-agent = ComputerAgent("huggingface-local/OpenGVLab/InternVL3_5-1B", tools=[computer])
-async for _ in agent.run("Open Firefox and navigate to github.com"):
- pass
-```
-
-## UI-TARS 1.5
-
-Unified vision-language model for computer-use:
-
-- `huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B`
-- `huggingface/ByteDance-Seed/UI-TARS-1.5-7B` (requires TGI endpoint)
-
-```python
-agent = ComputerAgent("huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B", tools=[computer])
-async for _ in agent.run("Open the settings menu and change the theme to dark mode"):
- pass
-```
-
----
-
-CUAs also support direct click prediction. See [Grounding Models](./grounding-models) for details on `predict_click()`.
-
-For details on agent loop behavior and usage, see [Agent Loops](../agent-loops).
diff --git a/docs/content/reference/agent-sdk/supported-agents/grounding-models.mdx b/docs/content/reference/agent-sdk/supported-agents/grounding-models.mdx
deleted file mode 100644
index aa808615d8..0000000000
--- a/docs/content/reference/agent-sdk/supported-agents/grounding-models.mdx
+++ /dev/null
@@ -1,109 +0,0 @@
----
-title: Grounding Models
-description: Models that support click prediction with ComputerAgent.predict_click()
----
-
-These models specialize in UI element grounding and click prediction. They can identify precise coordinates for UI elements based on natural language descriptions, but cannot perform autonomous task planning.
-
-Use `ComputerAgent.predict_click()` to get coordinates for specific UI elements.
-
-All models that support `ComputerAgent.run()` also support `ComputerAgent.predict_click()`. See [All‑in‑one CUAs](./computer-use-agents).
-
-### Anthropic CUAs
-
-- Claude 4.5: `claude-sonnet-4-5-20250929`
-- 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`
-
-### OpenAI CUA Preview
-
-- Computer-use-preview: `computer-use-preview`
-
-### Gemini CUAs
-
-- Gemini 3 Pro Preview: `gemini-3-pro-preview`
-- Gemini 3 Flash Preview: `gemini-3-flash-preview`
-
-### UI-TARS 1.5 (Unified VLM with grounding support)
-
-- `huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B`
-- `huggingface/ByteDance-Seed/UI-TARS-1.5-7B` (requires TGI endpoint)
-
-## Specialized Grounding Models
-
-These models are optimized specifically for click prediction and UI element grounding:
-
-### OpenCUA
-
-- `huggingface-local/xlangai/OpenCUA-{7B,32B}`
-
-### GTA1 Family
-
-- `huggingface-local/HelloKKMe/GTA1-{7B,32B,72B}`
-
-### Holo 1.5 Family
-
-- `huggingface-local/Hcompany/Holo1.5-{3B,7B,72B}`
-
-### InternVL 3.5 Family
-
-- `huggingface-local/OpenGVLab/InternVL3_5-{1B,2B,4B,8B,...}`
-
-### OmniParser (OCR)
-
-OCR-focused set-of-marks model that requires an LLM for click prediction:
-
-- `omniparser` (requires combination with any LiteLLM vision model)
-
-### Moondream3 (Local Grounding)
-
-Moondream3 is a powerful small model that can perform UI grounding and click prediction.
-
-- `moondream3`
-
-## Usage Examples
-
-```python
-# Using any grounding model for click prediction
-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")
-menu_coords = agent.predict_click("find the hamburger menu icon")
-
-print(f"Login button: {login_coords}")
-print(f"Search field: {search_coords}")
-print(f"Menu icon: {menu_coords}")
-```
-
-```python
-# OmniParser is just for OCR, so it requires an LLM for predict_click
-agent = ComputerAgent("omniparser+anthropic/claude-sonnet-4-5-20250929", tools=[computer])
-
-# Predict click coordinates using composed agent
-coords = agent.predict_click("find the submit button")
-print(f"Click coordinates: {coords}") # (450, 320)
-
-# Note: Cannot use omniparser alone for click prediction
-# This will raise an error:
-# agent = ComputerAgent("omniparser", tools=[computer])
-# coords = agent.predict_click("find button") # Error!
-```
-
-```python
-agent = ComputerAgent("huggingface-local/HelloKKMe/GTA1-7B", tools=[computer])
-
-# Predict click coordinates for UI elements
-coords = agent.predict_click("find the submit button")
-print(f"Click coordinates: {coords}") # (450, 320)
-
-# Note: GTA1 cannot perform autonomous task planning
-# This will raise an error:
-# agent.run("Fill out the form and submit it")
-```
-
----
-
-For information on combining grounding models with planning capabilities, see [Composed Agents](./composed-agents) and [All‑in‑one CUAs](./computer-use-agents).
diff --git a/docs/content/reference/agent-sdk/supported-agents/human-in-the-loop.mdx b/docs/content/reference/agent-sdk/supported-agents/human-in-the-loop.mdx
deleted file mode 100644
index f157489116..0000000000
--- a/docs/content/reference/agent-sdk/supported-agents/human-in-the-loop.mdx
+++ /dev/null
@@ -1,64 +0,0 @@
----
-title: Human-In-The-Loop
-description: Use humans as agents for evaluation, demonstrations, and interactive control
----
-
-The Agent SDK provides a human tool, with native support for using a human-in-the-loop as a way to evaluate your environment, tools, or to create demonstrations. You can use it by doing `grounding_model+human/human` or `human/human` directly.
-
-## Getting Started
-
-To start the human agent tool, simply run:
-
-```bash
-python -m agent.human_tool
-```
-
-The UI will show you pending completions. Select a completion to take control of the agent.
-
-## Usage Examples
-
-### Direct Human Agent
-
-```python
-from agent import ComputerAgent
-from agent.computer import computer
-
-agent = ComputerAgent(
- "human/human",
- tools=[computer]
-)
-
-async for _ in agent.run("Take a screenshot, analyze the UI, 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 the settings page and enable dark mode"):
- pass
-```
-
-## Features
-
-The human-in-the-loop interface provides:
-
-- **Interactive UI**: Web-based interface for reviewing and responding to agent requests
-- **Image Display**: Screenshots with click handlers for direct interaction
-- **Action Accordions**: Support for various computer actions (click, type, keypress, etc.)
-- **Tool Calls**: Full OpenAI-compatible tool call support
-- **Real-time Updates**: Smart polling for responsive UI updates
-
-## Use Cases
-
-- **Evaluation**: Have humans evaluate agent performance and provide ground truth responses
-- **Demonstrations**: Create training data by having humans demonstrate tasks
-- **Interactive Control**: Take manual control when automated agents need human guidance
-- **Testing**: Validate agent, tool, and environment behavior manually
-
----
diff --git a/docs/content/reference/agent-sdk/supported-agents/meta.json b/docs/content/reference/agent-sdk/supported-agents/meta.json
deleted file mode 100644
index e812c4fbc1..0000000000
--- a/docs/content/reference/agent-sdk/supported-agents/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "title": "Supported Agents",
- "description": "Models and configurations supported by the Agent SDK",
- "pages": ["computer-use-agents", "grounding-models", "composed-agents", "human-in-the-loop"]
-}
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
deleted file mode 100644
index d56bec360d..0000000000
--- a/docs/content/reference/agent-sdk/supported-model-providers/cua-vlm-router.mdx
+++ /dev/null
@@ -1,442 +0,0 @@
----
-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/google/gemini-3-pro-preview` | Google | Gemini 3 Pro Preview | Advanced reasoning and vision tasks |
-| `cua/google/gemini-3-flash-preview` | Google | Gemini 3 Flash Preview | Fast responses, cost-effective |
-
-## 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 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)
-```
-
-### Using Gemini 3 Pro Preview
-
-```python
-from agent import ComputerAgent
-from computer import Computer
-
-computer = Computer(os_type="linux", provider_type="docker")
-
-agent = ComputerAgent(
- model="cua/google/gemini-3-pro-preview",
- 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)
-```
-
-## 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
deleted file mode 100644
index d27aab31dd..0000000000
--- a/docs/content/reference/agent-sdk/supported-model-providers/index.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-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
deleted file mode 100644
index b147a538f5..0000000000
--- a/docs/content/reference/agent-sdk/supported-model-providers/local-models.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-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
deleted file mode 100644
index 4dcb80a897..0000000000
--- a/docs/content/reference/agent-sdk/telemetry.mdx
+++ /dev/null
@@ -1,135 +0,0 @@
----
-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
deleted file mode 100644
index 425c694e36..0000000000
--- a/docs/content/reference/agent-sdk/usage-tracking.mdx
+++ /dev/null
@@ -1,64 +0,0 @@
----
-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
deleted file mode 100644
index d123221c6b..0000000000
--- a/docs/content/reference/cli-playbook/commands.mdx
+++ /dev/null
@@ -1,433 +0,0 @@
----
-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
deleted file mode 100644
index f600cdce27..0000000000
--- a/docs/content/reference/cli-playbook/index.mdx
+++ /dev/null
@@ -1,63 +0,0 @@
----
-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/reference/cli-playbook/meta.json b/docs/content/reference/cli-playbook/meta.json
deleted file mode 100644
index 2447541fb6..0000000000
--- a/docs/content/reference/cli-playbook/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "title": "Cloud CLI",
- "description": "Command-line interface for CUA Cloud",
- "pages": ["index", "commands"]
-}
diff --git a/docs/content/reference/computer-sdk/cloud-vm-management.mdx b/docs/content/reference/computer-sdk/cloud-vm-management.mdx
deleted file mode 100644
index 21174bd4f3..0000000000
--- a/docs/content/reference/computer-sdk/cloud-vm-management.mdx
+++ /dev/null
@@ -1,267 +0,0 @@
----
-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
deleted file mode 100644
index 4fc7b0ffdb..0000000000
--- a/docs/content/reference/computer-sdk/commands.mdx
+++ /dev/null
@@ -1,383 +0,0 @@
----
-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/reference/computer-sdk/computer-server/Commands.mdx b/docs/content/reference/computer-sdk/computer-server/Commands.mdx
deleted file mode 100644
index 9c22082605..0000000000
--- a/docs/content/reference/computer-sdk/computer-server/Commands.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-title: Supported Commands
-description: List of all commands supported by the Computer Server API (WebSocket and REST).
----
-
-# Commands Reference
-
-This page lists all supported commands for the Computer Server, available via both WebSocket and REST API endpoints.
-
-| Command | Description |
-| ---------------------- | ------------------------------------- |
-| version | Get protocol and package version info |
-| run_command | Run a shell command |
-| screenshot | Capture a screenshot |
-| get_screen_size | Get the screen size |
-| get_cursor_position | Get the current mouse cursor position |
-| mouse_down | Mouse button down |
-| mouse_up | Mouse button up |
-| left_click | Left mouse click |
-| right_click | Right mouse click |
-| double_click | Double mouse click |
-| move_cursor | Move mouse cursor to coordinates |
-| drag_to | Drag mouse to coordinates |
-| drag | Drag mouse by offset |
-| key_down | Keyboard key down |
-| key_up | Keyboard key up |
-| type_text | Type text |
-| press_key | Press a single key |
-| hotkey | Press a hotkey combination |
-| scroll | Scroll the screen |
-| scroll_down | Scroll down |
-| scroll_up | Scroll up |
-| copy_to_clipboard | Copy text to clipboard |
-| set_clipboard | Set clipboard content |
-| file_exists | Check if a file exists |
-| directory_exists | Check if a directory exists |
-| list_dir | List files/directories in a directory |
-| read_text | Read text from a file |
-| write_text | Write text to a file |
-| read_bytes | Read bytes from a file |
-| write_bytes | Write bytes to a file |
-| get_file_size | Get file size |
-| delete_file | Delete a file |
-| create_dir | Create a directory |
-| delete_dir | Delete a directory |
-| get_accessibility_tree | Get accessibility tree (if supported) |
-| find_element | Find element in accessibility tree |
-| diorama_cmd | Run a diorama command (if supported) |
diff --git a/docs/content/reference/computer-sdk/computer-server/REST-API.mdx b/docs/content/reference/computer-sdk/computer-server/REST-API.mdx
deleted file mode 100644
index 18f5980b7c..0000000000
--- a/docs/content/reference/computer-sdk/computer-server/REST-API.mdx
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: REST API Reference
-description: Reference for the /cmd REST endpoint of the Computer Server.
----
-
-# REST API Reference
-
-The Computer Server exposes a single REST endpoint for command execution:
-
-- `http://localhost:8000/cmd`
-- `https://your-container.containers.cloud.trycua.com:8443/cmd` (cloud)
-
-## POST /cmd
-
-- Accepts commands as JSON in the request body
-- Returns results as a streaming response (text/event-stream)
-
-### Request Format
-
-```json
-{
- "command": "<command_name>",
- "params": { ... }
-}
-```
-
-### Required Headers (for cloud containers)
-
-- `X-Container-Name`: Name of the container (cloud only)
-- `X-API-Key`: API key for authentication (cloud only)
-
-### Example Request (Python)
-
-```python
-import requests
-
-url = "http://localhost:8000/cmd"
-body = {"command": "screenshot", "params": {}}
-resp = requests.post(url, json=body)
-print(resp.text)
-```
-
-### Example Request (Cloud)
-
-```python
-import requests
-
-url = "https://your-container.containers.cloud.trycua.com:8443/cmd"
-headers = {
- "X-Container-Name": "your-container",
- "X-API-Key": "your-api-key"
-}
-body = {"command": "screenshot", "params": {}}
-resp = requests.post(url, json=body, headers=headers)
-print(resp.text)
-```
-
-### Response Format
-
-Streaming text/event-stream with JSON objects, e.g.:
-
-```
-data: {"success": true, "content": "..."}
-
-data: {"success": false, "error": "..."}
-```
-
-### Supported Commands
-
-See [Commands Reference](./Commands) for the full list of commands and parameters.
diff --git a/docs/content/reference/computer-sdk/computer-server/WebSocket-API.mdx b/docs/content/reference/computer-sdk/computer-server/WebSocket-API.mdx
deleted file mode 100644
index 00d20d2154..0000000000
--- a/docs/content/reference/computer-sdk/computer-server/WebSocket-API.mdx
+++ /dev/null
@@ -1,96 +0,0 @@
----
-title: WebSocket API Reference
-description: Reference for the /ws WebSocket endpoint of the Computer Server.
----
-
-# WebSocket API Reference
-
-The Computer Server exposes a WebSocket endpoint for real-time command execution and streaming results.
-
-- `ws://localhost:8000/ws`
-- `wss://your-container.containers.cloud.trycua.com:8443/ws` (cloud)
-
-### Authentication (Cloud Only)
-
-For cloud containers, you must authenticate immediately after connecting:
-
-```json
-{
- "command": "authenticate",
- "params": {
- "container_name": "your-container",
- "api_key": "your-api-key"
- }
-}
-```
-
-If authentication fails, the connection is closed.
-
-### Command Format
-
-Send JSON messages:
-
-```json
-{
- "command": "<command_name>",
- "params": { ... }
-}
-```
-
-### Example (Python)
-
-```python
-import websockets
-import asyncio
-import json
-
-async def main():
- uri = "ws://localhost:8000/ws"
- async with websockets.connect(uri) as ws:
- await ws.send(json.dumps({"command": "version", "params": {}}))
- response = await ws.recv()
- print(response)
-
-asyncio.run(main())
-```
-
-### Example (Cloud)
-
-```python
-import websockets
-import asyncio
-import json
-
-async def main():
- uri = "wss://your-container.containers.cloud.trycua.com:8443/ws"
- async with websockets.connect(uri) as ws:
- await ws.send(json.dumps({
- "command": "authenticate",
- "params": {
- "container_name": "your-container",
- "api_key": "your-api-key"
- }
- }))
- auth_response = await ws.recv()
- print(auth_response)
- await ws.send(json.dumps({"command": "version", "params": {}}))
- response = await ws.recv()
- print(response)
-
-asyncio.run(main())
-```
-
-### Response Format
-
-Each response is a JSON object:
-
-```json
-{
- "success": true,
- ...
-}
-```
-
-### Supported Commands
-
-See [Commands Reference](./Commands) for the full list of commands and parameters.
diff --git a/docs/content/reference/computer-sdk/computer-server/index.mdx b/docs/content/reference/computer-sdk/computer-server/index.mdx
deleted file mode 100644
index 1e47c90b05..0000000000
--- a/docs/content/reference/computer-sdk/computer-server/index.mdx
+++ /dev/null
@@ -1,15 +0,0 @@
----
-title: Computer Server
-description: HTTP/WebSocket server for remote computer control
----
-
-The Computer Server is an HTTP and WebSocket server that runs inside each Cua sandbox (VM or container). It exposes APIs for remote computer control - allowing the Computer SDK and agents to execute actions like clicking, typing, taking screenshots, and running commands on the sandboxed environment.
-
-When you use `Computer(provider_type="cloud")` or any other provider, the Computer SDK communicates with this server running inside the sandbox to execute your automation commands.
-
-## Key Features
-
-- **REST API** - Execute commands, take screenshots, manage files
-- **WebSocket API** - Real-time streaming for continuous interaction
-- **Cross-platform** - Runs on Linux, macOS, and Windows sandboxes
-- **Secure** - Isolated inside the sandbox environment
diff --git a/docs/content/reference/computer-sdk/computer-server/meta.json b/docs/content/reference/computer-sdk/computer-server/meta.json
deleted file mode 100644
index 40cccfd898..0000000000
--- a/docs/content/reference/computer-sdk/computer-server/meta.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "title": "Computer Server",
- "pages": ["index", "Commands", "REST-API", "WebSocket-API"]
-}
diff --git a/docs/content/reference/computer-sdk/computer-ui.mdx b/docs/content/reference/computer-sdk/computer-ui.mdx
deleted file mode 100644
index 3e576f03d5..0000000000
--- a/docs/content/reference/computer-sdk/computer-ui.mdx
+++ /dev/null
@@ -1,99 +0,0 @@
----
-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/reference/computer-sdk/computers.mdx b/docs/content/reference/computer-sdk/computers.mdx
deleted file mode 100644
index be83073857..0000000000
--- a/docs/content/reference/computer-sdk/computers.mdx
+++ /dev/null
@@ -1,197 +0,0 @@
----
-title: Computer Types
-description: Understanding Cua computer types and connection methods
----
-
-{/* 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>
-
-Before we can automate apps using AI, we need to first connect to a Computer Server to give the AI a safe environment to execute workflows in.
-
-The Cua Computer Framework provides access to preconfigured sandboxes running the Computer Server. These can be either macOS, Linux, or Windows instances, available either as cloud-native sandboxes or running locally on your host desktop.
-
-## Cloud Sandbox
-
-**Easiest & safest way to get started - works on any host OS**
-
-This is a Cloud Sandbox running the Computer Server. Get a sandbox at [cua.ai](https://cua.ai/).
-
-<Tabs items={['Python', 'TypeScript']}>
- <Tab value="Python">
- ```python
- from computer import Computer
-
- computer = Computer(
- os_type="linux",
- provider_type="cloud",
- name="your-sandbox-name",
- api_key="your-api-key"
- )
-
- await computer.run() # Connect to the sandbox
- ```
-
- </Tab>
- <Tab value="TypeScript">
- ```typescript
- import { Computer, OSType } from '@trycua/computer';
-
- const computer = new Computer({
- osType: OSType.LINUX,
- name: "your-sandbox-name",
- apiKey: "your-api-key"
- });
-
- await computer.run(); // Connect to the sandbox
- ```
-
- </Tab>
-</Tabs>
-
-## Linux on Docker
-
-**Run Linux desktop locally on macOS, Windows, or Linux hosts**
-
-Cua provides two Docker images for running Linux desktops:
-
-<Tabs items={['XFCE (Lightweight)', 'KASM (Full-Featured)']}>
- <Tab value="XFCE (Lightweight)">
-
- **Recommended for most use cases** - lightweight XFCE desktop with Firefox
-
- 1. Install Docker Desktop or Docker Engine
-
- 2. Pull the CUA XFCE image
-
- ```bash
- docker pull --platform=linux/amd64 trycua/cua-xfce:latest
- ```
-
- 3. Connect with Computer
-
- ```python
- from computer import Computer
-
- computer = Computer(
- os_type="linux",
- provider_type="docker",
- image="trycua/cua-xfce:latest",
- name="my-xfce-sandbox"
- )
-
- await computer.run() # Launch & connect to Docker sandbox
- ```
-
- </Tab>
- <Tab value="KASM (Full-Featured)">
-
- **Full-featured Ubuntu desktop** with additional applications
-
- 1. Install Docker Desktop or Docker Engine
-
- 2. Build or pull the CUA KASM image
-
- ```bash
- # Option 1: Pull from Docker Hub
- docker pull --platform=linux/amd64 trycua/cua-ubuntu:latest
-
- # Option 2: Build locally
- cd libs/kasm
- docker build -t cua-ubuntu:latest .
- ```
-
- 3. Connect with Computer
-
- ```python
- from computer import Computer
-
- computer = Computer(
- os_type="linux",
- provider_type="docker",
- image="trycua/cua-ubuntu:latest",
- name="my-kasm-sandbox"
- )
-
- await computer.run() # Launch & connect to Docker sandbox
- ```
-
- </Tab>
-</Tabs>
-
-## Windows Sandbox
-
-**Windows hosts only - requires Windows 10 Pro/Enterprise or Windows 11**
-
-1. Enable Windows Sandbox
-2. Install pywinsandbox dependency
-
-```bash
-pip install -U git+git://github.com/karkason/pywinsandbox.git
-```
-
-3. Connect with Computer
-
-```python
-from computer import Computer
-
-computer = Computer(
- os_type="windows",
- provider_type="winsandbox",
- ephemeral=True # Windows Sandbox is always ephemeral
-)
-
-await computer.run() # Launch & connect to Windows Sandbox
-```
-
-## macOS Sandbox
-
-**macOS hosts only - requires Lume CLI**
-
-1. Install 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 macOS sandbox
-
-```bash
-lume run macos-sequoia-cua:latest
-```
-
-3. Connect with Computer
-
-```python
-from computer import Computer
-
-computer = Computer(
- os_type="macos",
- provider_type="lume",
- name="macos-sequoia-cua:latest"
-)
-
-await computer.run() # Launch & connect to the sandbox
-```
-
-## Your host desktop
-
-You can also have agents control your desktop directly by running Computer Server without any containerization layer. Beware that AI models may perform risky actions.
-
-```bash
-pip install cua-computer-server
-python -m computer_server
-```
-
-Connect with:
-
-<Tabs items={['Python']}>
- <Tab value="Python">
- ```python
-
- computer = Computer(use_host_computer_server=True)
- await computer.run() # Connect to the host desktop
-
- ```
-
- </Tab>
-</Tabs>
diff --git a/docs/content/reference/computer-sdk/custom-computer-handlers.mdx b/docs/content/reference/computer-sdk/custom-computer-handlers.mdx
deleted file mode 100644
index d166888344..0000000000
--- a/docs/content/reference/computer-sdk/custom-computer-handlers.mdx
+++ /dev/null
@@ -1,130 +0,0 @@
----
-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/reference/computer-sdk/meta.json b/docs/content/reference/computer-sdk/meta.json
deleted file mode 100644
index 83d06b59b9..0000000000
--- a/docs/content/reference/computer-sdk/meta.json
+++ /dev/null
@@ -1,13 +0,0 @@
-{
- "title": "Computer SDK",
- "description": "Build computer-using agents with the Computer SDK",
- "pages": [
- "computers",
- "commands",
- "tracing-api",
- "sandboxed-python",
- "custom-computer-handlers",
- "computer-ui",
- "computer-server"
- ]
-}
diff --git a/docs/content/reference/computer-sdk/sandboxed-python.mdx b/docs/content/reference/computer-sdk/sandboxed-python.mdx
deleted file mode 100644
index 8db37c13f5..0000000000
--- a/docs/content/reference/computer-sdk/sandboxed-python.mdx
+++ /dev/null
@@ -1,86 +0,0 @@
----
-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
deleted file mode 100644
index 9595b144aa..0000000000
--- a/docs/content/reference/computer-sdk/tracing-api.mdx
+++ /dev/null
@@ -1,345 +0,0 @@
----
-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
deleted file mode 100644
index 9f16e17499..0000000000
--- a/docs/content/reference/index.mdx
+++ /dev/null
@@ -1,54 +0,0 @@
----
-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
deleted file mode 100644
index 201206163f..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lume/cli-reference.mdx
+++ /dev/null
@@ -1,238 +0,0 @@
----
-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
deleted file mode 100644
index 4009a94ec2..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lume/faq.md
+++ /dev/null
@@ -1,120 +0,0 @@
----
-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
deleted file mode 100644
index f908f85e20..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lume/http-api.mdx
+++ /dev/null
@@ -1,1260 +0,0 @@
----
-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
deleted file mode 100644
index 152d08c743..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lume/index.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
----
-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
deleted file mode 100644
index aa6da45a90..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lume/installation.mdx
+++ /dev/null
@@ -1,53 +0,0 @@
----
-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
deleted file mode 100644
index 42aeac1d01..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lume/meta.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
- "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
deleted file mode 100644
index 4e4e3e67ca..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lume/prebuilt-images.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-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
deleted file mode 100644
index bd9b99514b..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lumier/building-lumier.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-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
deleted file mode 100644
index 312598e74b..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lumier/docker-compose.mdx
+++ /dev/null
@@ -1,45 +0,0 @@
----
-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
deleted file mode 100644
index b7c7205061..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lumier/docker.mdx
+++ /dev/null
@@ -1,128 +0,0 @@
----
-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
deleted file mode 100644
index d21768f4c3..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lumier/index.mdx
+++ /dev/null
@@ -1,28 +0,0 @@
----
-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
deleted file mode 100644
index d2e6239932..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lumier/installation.mdx
+++ /dev/null
@@ -1,15 +0,0 @@
----
-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
deleted file mode 100644
index bfe2572455..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/lumier/meta.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
- "pages": ["installation", "docker", "docker-compose", "building-lumier"]
-}
diff --git a/docs/content/reference/macos-vm-cli-playbook/meta.json b/docs/content/reference/macos-vm-cli-playbook/meta.json
deleted file mode 100644
index a9c98b66d8..0000000000
--- a/docs/content/reference/macos-vm-cli-playbook/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "title": "macOS VM CLI",
- "description": "CLI tools for macOS virtualization",
- "pages": ["lume", "lumier"]
-}
diff --git a/docs/content/reference/meta.json b/docs/content/reference/meta.json
deleted file mode 100644
index 1165fc2000..0000000000
--- a/docs/content/reference/meta.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
- "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"
- ]
-}