@@ -116,7 +116,7 @@ For detailed compatibility information including host OS support, VM emulation c
# 🐍 Usage Guide
-Follow these steps to use C/ua in your own Python code. See [Developer Guide](./docs/Developer-Guide.md) for building from source.
+Follow these steps to use Cua in your own Python code. See [Developer Guide](./docs/Developer-Guide.md) for building from source.
### Step 1: Install Lume CLI
@@ -143,15 +143,16 @@ pip install "cua-computer[all]" "cua-agent[all]"
### Step 4: Use in Your Code
```python
+import asyncio
from computer import Computer
-from agent import ComputerAgent, LLM
+from agent import ComputerAgent
async def main():
# Start a local macOS VM
computer = Computer(os_type="macos")
await computer.run()
- # Or with C/ua Cloud Container
+ # Or with Cua Cloud Container
computer = Computer(
os_type="linux",
api_key="your_cua_api_key_here",
@@ -228,10 +229,10 @@ docker run -it --rm \
## Resources
-- [How to use the MCP Server with Claude Desktop or other MCP clients](./libs/python/mcp-server/README.md) - One of the easiest ways to get started with C/ua
+- [How to use the MCP Server with Claude Desktop or other MCP clients](./libs/python/mcp-server/README.md) - One of the easiest ways to get started with Cua
- [How to use OpenAI Computer-Use, Anthropic, OmniParser, or UI-TARS for your Computer-Use Agent](./libs/python/agent/README.md)
- [How to use Lume CLI for managing desktops](./libs/lume/README.md)
-- [Training Computer-Use Models: Collecting Human Trajectories with C/ua (Part 1)](https://www.trycua.com/blog/training-computer-use-models-trajectories-1)
+- [Training Computer-Use Models: Collecting Human Trajectories with Cua (Part 1)](https://www.trycua.com/blog/training-computer-use-models-trajectories-1)
- [Build Your Own Operator on macOS (Part 1)](https://www.trycua.com/blog/build-your-own-operator-on-macos-1)
## Modules
@@ -317,7 +318,7 @@ await computer.venv_install("demo_venv", ["requests", "macos-pyxa"]) # Install p
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
-# Example: Use sandboxed functions to execute code in a C/ua Container
+# Example: Use sandboxed functions to execute code in a Cua Container
from computer.helpers import sandboxed
@sandboxed("demo_venv")
@@ -330,8 +331,8 @@ def greet_and_print(name):
return {"greeted": name, "safari_html": html}
# When a @sandboxed function is called, it will execute in the container
-result = await greet_and_print("C/ua")
-# Result: {"greeted": "C/ua", "safari_html": "..."}
+result = await greet_and_print("Cua")
+# Result: {"greeted": "Cua", "safari_html": "..."}
# stdout and stderr are also captured and printed / raised
print("Result from sandboxed function:", result)
```
@@ -409,4 +410,4 @@ Thank you to all our supporters!
-
+
\ No newline at end of file
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 00000000..55a12ae7
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,28 @@
+# deps
+/node_modules
+
+# generated content
+.contentlayer
+.content-collections
+.source
+
+# test & build
+/coverage
+/.next/
+/out/
+/build
+*.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+/.pnp
+.pnp.js
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# others
+.env*.local
+.vercel
+next-env.d.ts
\ No newline at end of file
diff --git a/docs/.prettierrc b/docs/.prettierrc
new file mode 100644
index 00000000..03af2a8b
--- /dev/null
+++ b/docs/.prettierrc
@@ -0,0 +1,8 @@
+{
+ "useTabs": false,
+ "semi": true,
+ "singleQuote": true,
+ "trailingComma": "es5",
+ "bracketSpacing": true,
+ "jsxBracketSameLine": true
+}
\ No newline at end of file
diff --git a/docs/Developer-Guide.md b/docs/Developer-Guide.md
deleted file mode 100644
index 49aa82ee..00000000
--- a/docs/Developer-Guide.md
+++ /dev/null
@@ -1,293 +0,0 @@
-# Getting Started
-
-## Project Structure
-
-The project is organized as a monorepo with these main packages:
-
-### Python
-- `libs/python/core/` - Base package with telemetry support
-- `libs/python/computer/` - Computer-use interface (CUI) library
-- `libs/python/agent/` - AI agent library with multi-provider support
-- `libs/python/som/` - Set-of-Mark parser
-- `libs/python/computer-server/` - Server component for VM
-- `libs/python/pylume/` - Python bindings for Lume
-
-### TypeScript
-- `libs/typescript/computer/` - Computer-use interface (CUI) library
-- `libs/typescript/agent/` - AI agent library with multi-provider support
-
-### Other
-- `libs/lume/` - Lume CLI
-
-Each package has its own virtual environment and dependencies, managed through PDM.
-
-## Local Development Setup
-
-1. Install Lume CLI:
-
- ```bash
- /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
- ```
-
-2. Clone the repository:
-
- ```bash
- git clone https://github.com/trycua/cua.git
- cd cua
- ```
-
-3. Create a `.env.local` file in the root directory with your API keys:
-
- ```bash
- # Required for Anthropic provider
- ANTHROPIC_API_KEY=your_anthropic_key_here
-
- # Required for OpenAI provider
- OPENAI_API_KEY=your_openai_key_here
- ```
-
-4. Open the workspace in VSCode or Cursor:
-
- ```bash
- # For Cua Python development
- code .vscode/py.code-workspace
-
- # For Lume (Swift) development
- code .vscode/lume.code-workspace
- ```
-
-Using the workspace file is strongly recommended as it:
-
-- Sets up correct Python environments for each package
-- Configures proper import paths
-- Enables debugging configurations
-- Maintains consistent settings across packages
-
-## Lume Development
-
-Refer to the [Lume README](../libs/lume/docs/Development.md) for instructions on how to develop the Lume CLI.
-
-## Python Development
-
-There are two ways to install Lume:
-
-### Run the build script
-
-Run the build script to set up all packages:
-
-```bash
-./scripts/build.sh
-```
-
-The build script creates a shared virtual environment for all packages. The workspace configuration automatically handles import paths with the correct Python path settings.
-
-This will:
-
-- Create a virtual environment for the project
-- Install all packages in development mode
-- Set up the correct Python path
-- Install development tools
-
-### Install with PDM
-
-If PDM is not already installed, you can follow the installation instructions [here](https://pdm-project.org/en/latest/#installation).
-
-To install with PDM, simply run:
-
-```console
-pdm install -G:all
-```
-
-This installs all the dependencies for development, testing, and building the docs. If you'd only like development dependencies, you can run:
-
-```console
-pdm install -d
-```
-
-## Running Examples
-
-The Python workspace includes launch configurations for all packages:
-
-- "Run Computer Examples" - Runs computer examples
-- "Run Computer API Server" - Runs the computer-server
-- "Run Agent Examples" - Runs agent examples
-- "SOM" configurations - Various settings for running SOM
-
-To run examples from VSCode / Cursor:
-
-1. Press F5 or use the Run/Debug view
-2. Select the desired configuration
-
-The workspace also includes compound launch configurations:
-
-- "Run Computer Examples + Server" - Runs both the Computer Examples and Server simultaneously
-
-## Docker Development Environment
-
-As an alternative to installing directly on your host machine, you can use Docker for development. This approach has several advantages:
-
-### Prerequisites
-
-- Docker installed on your machine
-- Lume server running on your host (port 7777): `lume serve`
-
-### Setup and Usage
-
-1. Build the development Docker image:
-
- ```bash
- ./scripts/run-docker-dev.sh build
- ```
-
-2. Run an example in the container:
-
- ```bash
- ./scripts/run-docker-dev.sh run computer_examples.py
- ```
-
-3. Get an interactive shell in the container:
-
- ```bash
- ./scripts/run-docker-dev.sh run --interactive
- ```
-
-4. Stop any running containers:
-
- ```bash
- ./scripts/run-docker-dev.sh stop
- ```
-
-### How it Works
-
-The Docker development environment:
-
-- Installs all required Python dependencies in the container
-- Mounts your source code from the host at runtime
-- Automatically configures the connection to use host.docker.internal:7777 for accessing the Lume server on your host machine
-- Preserves your code changes without requiring rebuilds (source code is mounted as a volume)
-
-> **Note**: The Docker container doesn't include the macOS-specific Lume executable. Instead, it connects to the Lume server running on your host machine via host.docker.internal:7777. Make sure to start the Lume server on your host before running examples in the container.
-
-## Cleanup and Reset
-
-If you need to clean up the environment (non-docker) and start fresh:
-
-```bash
-./scripts/cleanup.sh
-```
-
-This will:
-
-- Remove all virtual environments
-- Clean Python cache files and directories
-- Remove build artifacts
-- Clean PDM-related files
-- Reset environment configurations
-
-## Code Formatting Standards
-
-The cua project follows strict code formatting standards to ensure consistency across all packages.
-
-### Python Code Formatting
-
-#### Tools
-
-The project uses the following tools for code formatting and linting:
-
-- **[Black](https://black.readthedocs.io/)**: Code formatter
-- **[Ruff](https://beta.ruff.rs/docs/)**: Fast linter and formatter
-- **[MyPy](https://mypy.readthedocs.io/)**: Static type checker
-
-These tools are automatically installed when you set up the development environment using the `./scripts/build.sh` script.
-
-#### Configuration
-
-The formatting configuration is defined in the root `pyproject.toml` file:
-
-```toml
-[tool.black]
-line-length = 100
-target-version = ["py311"]
-
-[tool.ruff]
-line-length = 100
-target-version = "py311"
-select = ["E", "F", "B", "I"]
-fix = true
-
-[tool.ruff.format]
-docstring-code-format = true
-
-[tool.mypy]
-strict = true
-python_version = "3.11"
-ignore_missing_imports = true
-disallow_untyped_defs = true
-check_untyped_defs = true
-warn_return_any = true
-show_error_codes = true
-warn_unused_ignores = false
-```
-
-#### Key Formatting Rules
-
-- **Line Length**: Maximum of 100 characters
-- **Python Version**: Code should be compatible with Python 3.11+
-- **Imports**: Automatically sorted (using Ruff's "I" rule)
-- **Type Hints**: Required for all function definitions (strict mypy mode)
-
-#### IDE Integration
-
-The repository includes VSCode workspace configurations that enable automatic formatting. When you open the workspace files (as recommended in the setup instructions), the correct formatting settings are automatically applied.
-
-Python-specific settings in the workspace files:
-
-```json
-"[python]": {
- "editor.formatOnSave": true,
- "editor.defaultFormatter": "ms-python.black-formatter",
- "editor.codeActionsOnSave": {
- "source.organizeImports": "explicit"
- }
-}
-```
-
-Recommended VS Code extensions:
-
-- Black Formatter (ms-python.black-formatter)
-- Ruff (charliermarsh.ruff)
-- Pylance (ms-python.vscode-pylance)
-
-#### Manual Formatting
-
-To manually format code:
-
-```bash
-# Format all Python files using Black
-pdm run black .
-
-# Run Ruff linter with auto-fix
-pdm run ruff check --fix .
-
-# Run type checking with MyPy
-pdm run mypy .
-```
-
-#### Pre-commit Validation
-
-Before submitting a pull request, ensure your code passes all formatting checks:
-
-```bash
-# Run all checks
-pdm run black --check .
-pdm run ruff check .
-pdm run mypy .
-```
-
-### Swift Code (Lume)
-
-For Swift code in the `libs/lume` directory:
-
-- Follow the [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/)
-- Use SwiftFormat for consistent formatting
-- Code will be automatically formatted on save when using the lume workspace
diff --git a/docs/FAQ.md b/docs/FAQ.md
deleted file mode 100644
index e6d77b70..00000000
--- a/docs/FAQ.md
+++ /dev/null
@@ -1,124 +0,0 @@
-# FAQs
-
-### Why a local sandbox?
-
-A local sandbox is a dedicated environment that is isolated from the rest of the system. As AI agents rapidly evolve towards 70-80% success rates on average tasks, having a controlled and secure environment becomes crucial. Cua's Computer-Use AI agents run in a local sandbox to ensure reliability, safety, and controlled execution.
-
-Benefits of using a local sandbox rather than running the Computer-Use AI agent in the host system:
-
-- **Reliability**: The sandbox provides a reproducible environment - critical for benchmarking and debugging agent behavior. Frameworks like [OSWorld](https://github.com/xlang-ai/OSWorld), [Simular AI](https://github.com/simular-ai/Agent-S), Microsoft's [OmniTool](https://github.com/microsoft/OmniParser/tree/master/omnitool), [WindowsAgentArena](https://github.com/microsoft/WindowsAgentArena) and more are using Computer-Use AI agents running in local sandboxes.
-- **Safety & Isolation**: The sandbox is isolated from the rest of the system, protecting sensitive data and system resources. As CUA agent capabilities grow, this isolation becomes increasingly important for preventing potential safety breaches.
-- **Control**: The sandbox can be easily monitored and terminated if needed, providing oversight for autonomous agent operation.
-
-### Where are the sandbox images stored?
-
-Sandbox are stored in `~/.lume`, and cached images are stored in `~/.lume/cache`.
-
-### Which image is Computer using?
-
-Computer uses an optimized macOS image for Computer-Use interactions, with pre-installed apps and settings for optimal performance.
-The image is available on our [ghcr registry](https://github.com/orgs/trycua/packages/container/package/macos-sequoia-cua).
-
-### Are Sandbox 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 delete a VM?
-
-```bash
-lume delete
-```
-
-### How do I fix EasyOCR `[SSL: CERTIFICATE_VERIFY_FAILED]` errors?
-
-**Symptom:**
-When running an agent that uses OCR (e.g., with `AgentLoop.OMNI`), you might encounter an error during the first run or initialization phase that includes:
-```
-ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)
-```
-
-**Cause:**
-This usually happens when EasyOCR attempts to download its language models over HTTPS for the first time. Python's SSL module cannot verify the server's certificate because it can't locate the necessary root Certificate Authority (CA) certificates in your environment's trust store.
-
-**Solution:**
-You need to explicitly tell Python where to find a trusted CA bundle. The `certifi` package provides one. Before running your Python agent script **the first time it needs to download models**, set the following environment variables in the *same terminal session*:
-```bash
-# Ensure certifi is installed: pip show certifi
-export SSL_CERT_FILE=$(python -m certifi)
-export REQUESTS_CA_BUNDLE=$(python -m certifi)
-
-# Now run your Python script that uses the agent...
-# python your_agent_script.py
-```
-This directs Python to use the CA bundle provided by `certifi` for SSL verification. **Note:** Once EasyOCR has successfully downloaded its models, you typically do not need to set these environment variables before every subsequent run.
-
-### How do I troubleshoot the agent failing to get the VM IP address or getting stuck on "VM status changed to: stopped"?
-
-**Symptom:**
-When running your agent script (e.g., using `Computer().run(...)`), the script might hang during the VM startup phase, logging messages like:
-* `Waiting for VM to be ready...`
-* `VM status changed to: stopped (after 0.0s)`
-* `Still waiting for VM IP address... (elapsed: XX.Xs)`
-* Eventually, it might time out, or you might notice the VM window never appears or closes quickly.
-
-**Cause:**
-This is typically due to known instability issues with the `lume serve` background daemon process, as documented in the main `README.md`:
-1. **`lume serve` Crash:** The `lume serve` process might terminate unexpectedly shortly after launch or when the script tries to interact with it. If it's not running, the script cannot get VM status updates or the IP address.
-2. **Incorrect Status Reporting:** Even if `lume serve` is running, its API sometimes incorrectly reports the VM status as `stopped` immediately after startup is initiated. While the underlying `Computer` library tries to poll and wait for the correct `running` status, this initial incorrect report can cause delays or failures if the status doesn't update correctly within the timeout or if `lume serve` crashes during the polling.
-
-**Troubleshooting Steps:**
-1. **Check `lume serve`:** Is the `lume serve` process still running in its terminal? Did it print any errors or exit? If it's not running, stop your agent script (`Ctrl+C`) and proceed to step 2.
-2. **Force Cleanup:** Before *every* run, perform a rigorous cleanup to ensure no old `lume` processes or VM states interfere. Open a **new terminal** and run:
- ```bash
- # Stop any running Lume VM gracefully first (replace if needed)
- lume stop macos-sequoia-cua_latest
-
- # Force kill lume serve and related processes
- pkill -f "lume serve"
- pkill -9 -f "lume"
- pkill -9 -f "VzVirtualMachine" # Kills underlying VM process
-
- # Optional: Verify they are gone
- # ps aux | grep -E 'lume|VzVirtualMachine' | grep -v grep
- ```
-3. **Restart Sequence:**
- * **Terminal 1:** Start `lume serve` cleanly:
- ```bash
- lume serve
- ```
- *(Watch this terminal to ensure it stays running).*
- * **Terminal 2:** Run your agent script (including the `export SSL_CERT_FILE...` commands if *first time* using OCR):
- ```bash
- # export SSL_CERT_FILE=$(python -m certifi) # Only if first run with OCR
- # export REQUESTS_CA_BUNDLE=$(python -m certifi) # Only if first run with OCR
- python your_agent_script.py
- ```
-4. **Retry:** Due to the intermittent nature of the Lume issues, sometimes simply repeating steps 2 and 3 allows the run to succeed if the timing avoids the status reporting bug or the `lume serve` crash.
-
-**Related Issue: "No route to host" Error (macOS Sequoia+)**
-
-* **Symptom:** Even if the `Computer` library logs show the VM has obtained an IP address, you might encounter connection errors like `No route to host` when the agent tries to connect to the internal server, especially when running the agent script from within an IDE (like VS Code or Cursor).
-* **Cause:** This is often due to macOS Sequoia's enhanced local network privacy controls. Applications need explicit permission to access the local network, which includes communicating with the VM.
-* **Solution:** Grant "Local Network" access to the application you are running the script from (e.g., your IDE or terminal application). Go to **System Settings > Privacy & Security > Local Network**, find your application in the list, and toggle the switch ON. You might need to trigger a connection attempt from the application first for it to appear in the list. See [GitHub Issue #61](https://github.com/trycua/cua/issues/61) for more details and discussion.
-
-**Note:** Improving the stability of `lume serve` is an ongoing development area.
-
-### How do I troubleshoot Computer not connecting to lume daemon?
-
-If you're experiencing connection issues between Computer and the lume daemon, it could be because the port 7777 (used by lume) is already in use by an orphaned process. You can diagnose this issue with:
-
-```bash
-sudo lsof -i :7777
-```
-
-This command will show all processes using port 7777. If you see a lume process already running, you can terminate it with:
-
-```bash
-kill
-```
-
-Where `` is the process ID shown in the output of the `lsof` command. After terminating the process, run `lume serve` again to start the lume daemon.
-
-### What information does Cua track?
-
-Cua tracks anonymized usage and error report statistics; we ascribe to Posthog's approach as detailed [here](https://posthog.com/blog/open-source-telemetry-ethical). If you would like to opt out of sending anonymized info, you can set `telemetry_enabled` to false in the Computer or Agent constructor. Check out our [Telemetry](Telemetry.md) documentation for more details.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..b6f494e5
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,45 @@
+# docs
+
+This is a Next.js application generated with
+[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+
+Run development server:
+
+```bash
+npm run dev
+# or
+pnpm dev
+# or
+yarn dev
+```
+
+Open http://localhost:3000 with your browser to see the result.
+
+## Explore
+
+In the project, you can see:
+
+- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
+- `app/layout.config.tsx`: Shared options for layouts, optional but preferred to keep.
+
+| Route | Description |
+| ------------------------- | ------------------------------------------------------ |
+| `app/(home)` | The route group for your landing page and other pages. |
+| `app/docs` | The documentation layout and pages. |
+| `app/api/search/route.ts` | The Route Handler for search. |
+
+### Fumadocs MDX
+
+A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
+
+Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
+
+## Learn More
+
+To learn more about Next.js and Fumadocs, take a look at the following
+resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
+ features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+- [Fumadocs](https://fumadocs.vercel.app) - learn about Fumadocs
diff --git a/docs/Telemetry.md b/docs/Telemetry.md
deleted file mode 100644
index 8f85e761..00000000
--- a/docs/Telemetry.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# Telemetry in CUA
-
-This document explains how telemetry works in CUA libraries and how you can control it.
-
-CUA tracks anonymized usage and error report statistics; we ascribe to Posthog's approach as detailed [here](https://posthog.com/blog/open-source-telemetry-ethical). If you would like to opt out of sending anonymized info, you can set `telemetry_enabled` to false.
-
-## What telemetry data we collect
-
-CUA libraries collect minimal anonymous usage data to help improve our software. The telemetry data we collect is specifically limited to:
-
-- Basic system information:
- - Operating system (e.g., 'darwin', 'win32', 'linux')
- - Python version (e.g., '3.11.0')
-- Module initialization events:
- - When a module (like 'computer' or 'agent') is imported
- - Version of the module being used
-
-We do NOT collect:
-- Personal information
-- Contents of files
-- Specific text being typed
-- Actual screenshots or screen contents
-- User-specific identifiers
-- API keys
-- File contents
-- Application data or content
-- User interactions with the computer
-- Information about files being accessed
-
-## Controlling Telemetry
-
-We are committed to transparency and user control over telemetry. There are two ways to control telemetry:
-
-## 1. Environment Variable (Global Control)
-
-Telemetry is enabled by default. To disable telemetry, set the `CUA_TELEMETRY_ENABLED` environment variable to a falsy value (`0`, `false`, `no`, or `off`):
-
-```bash
-# Disable telemetry before running your script
-export CUA_TELEMETRY_ENABLED=false
-
-# Or as part of the command
-CUA_TELEMETRY_ENABLED=1 python your_script.py
-
-```
-Or from Python:
-```python
-import os
-os.environ["CUA_TELEMETRY_ENABLED"] = "false"
-```
-
-## 2. Instance-Level Control
-
-You can control telemetry for specific CUA instances by setting `telemetry_enabled` when creating them:
-
-```python
-# Disable telemetry for a specific Computer instance
-computer = Computer(telemetry_enabled=False)
-
-# Enable telemetry for a specific Agent instance
-agent = ComputerAgent(telemetry_enabled=True)
-```
-
-You can check if telemetry is enabled for an instance:
-
-```python
-print(computer.telemetry_enabled) # Will print True or False
-```
-
-Note that telemetry settings must be configured during initialization and cannot be changed after the object is created.
-
-## Transparency
-
-We believe in being transparent about the data we collect. If you have any questions about our telemetry practices, please open an issue on our GitHub repository.
\ No newline at end of file
diff --git a/docs/content/docs/agent-sdk/agent-loops.mdx b/docs/content/docs/agent-sdk/agent-loops.mdx
new file mode 100644
index 00000000..bc26cf26
--- /dev/null
+++ b/docs/content/docs/agent-sdk/agent-loops.mdx
@@ -0,0 +1,39 @@
+---
+title: Agent Loops
+description: Supported computer-using agent loops and models
+---
+
+An agent can be thought of as a loop - it generates actions, executes them, and repeats until done:
+
+1. **Generate**: Your `model` generates `output_text`, `computer_call`, `function_call`
+2. **Execute**: The `computer` safely executes those items
+3. **Complete**: If the model has no more calls, it's done!
+
+To run an agent loop simply do:
+
+```python
+from agent import ComputerAgent
+from computer import Computer
+
+computer = Computer() # Connect to a cua container
+
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ tools=[computer]
+)
+
+prompt = "open github, navigate to trycua/cua"
+
+async for result in agent.run(prompt):
+ if result["output"][-1]["type"] == "message":
+ print("Agent:", result["output"][-1]["content"][0]["text"])
+```
+
+We currently support 4 computer-using agent loops:
+
+- Anthropic CUAs
+- OpenAI CUA Preview
+- UI-TARS 1.5
+- Omniparser + LLMs
+
+For a full list of supported models and configurations, see the [Supported Agents](./supported-agents) page.
diff --git a/docs/content/docs/agent-sdk/callbacks/agent-lifecycle.mdx b/docs/content/docs/agent-sdk/callbacks/agent-lifecycle.mdx
new file mode 100644
index 00000000..4b75ebcf
--- /dev/null
+++ b/docs/content/docs/agent-sdk/callbacks/agent-lifecycle.mdx
@@ -0,0 +1,52 @@
+---
+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.
+
+## Built-in Callbacks
+
+- **ImageRetentionCallback**: Limits recent images in context
+- **BudgetManagerCallback**: Stops execution when budget exceeded
+- **TrajectorySaverCallback**: Saves conversation trajectories
+- **LoggingCallback**: Logs agent activities
diff --git a/docs/content/docs/agent-sdk/callbacks/cost-saving.mdx b/docs/content/docs/agent-sdk/callbacks/cost-saving.mdx
new file mode 100644
index 00000000..9a543dc1
--- /dev/null
+++ b/docs/content/docs/agent-sdk/callbacks/cost-saving.mdx
@@ -0,0 +1,87 @@
+---
+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-3-5-sonnet-20241022",
+ tools=[computer],
+ callbacks=[
+ BudgetManagerCallback(
+ max_budget=5.0, # $5 limit
+ reset_after_each_run=False,
+ raise_error=True
+ )
+ ]
+)
+```
+
+## Budget Manager Shorthand
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ tools=[computer],
+ max_trajectory_budget=5.0 # Auto-adds BudgetManagerCallback
+)
+```
+
+**Or with options:**
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ tools=[computer],
+ max_trajectory_budget={"max_budget": 5.0, "raise_error": True}
+)
+```
+
+## Image Retention Callbacks Example
+
+```python
+from agent.callbacks import ImageRetentionCallback
+
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ tools=[computer],
+ callbacks=[
+ ImageRetentionCallback(only_n_most_recent_images=3)
+ ]
+)
+```
+
+## Image Retention Shorthand
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ tools=[computer],
+ only_n_most_recent_images=3 # Auto-adds ImageRetentionCallback
+)
+```
+
+## Combined Cost Optimization
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ 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/docs/agent-sdk/callbacks/logging.mdx b/docs/content/docs/agent-sdk/callbacks/logging.mdx
new file mode 100644
index 00000000..8ab9b2e6
--- /dev/null
+++ b/docs/content/docs/agent-sdk/callbacks/logging.mdx
@@ -0,0 +1,88 @@
+---
+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-3-5-sonnet-20241022",
+ tools=[computer],
+ callbacks=[
+ LoggingCallback(
+ logger=logging.getLogger("cua"),
+ level=logging.INFO
+ )
+ ]
+)
+```
+
+## Shorthand
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ 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-3-5-sonnet-20241022",
+ 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/docs/agent-sdk/callbacks/meta.json b/docs/content/docs/agent-sdk/callbacks/meta.json
new file mode 100644
index 00000000..c9a072b0
--- /dev/null
+++ b/docs/content/docs/agent-sdk/callbacks/meta.json
@@ -0,0 +1,11 @@
+{
+ "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/docs/agent-sdk/callbacks/pii-anonymization.mdx b/docs/content/docs/agent-sdk/callbacks/pii-anonymization.mdx
new file mode 100644
index 00000000..fcfd0861
--- /dev/null
+++ b/docs/content/docs/agent-sdk/callbacks/pii-anonymization.mdx
@@ -0,0 +1,12 @@
+---
+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/docs/agent-sdk/callbacks/trajectories.mdx b/docs/content/docs/agent-sdk/callbacks/trajectories.mdx
new file mode 100644
index 00000000..8799c5eb
--- /dev/null
+++ b/docs/content/docs/agent-sdk/callbacks/trajectories.mdx
@@ -0,0 +1,51 @@
+---
+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-3-5-sonnet-20241022",
+ tools=[computer],
+ callbacks=[
+ TrajectorySaverCallback(
+ trajectory_dir="my_trajectories",
+ save_screenshots=True
+ )
+ ]
+)
+```
+
+## Shorthand
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ tools=[computer],
+ trajectory_dir="trajectories" # Auto-adds TrajectorySaverCallback
+)
+```
+
+## View Trajectories Online
+
+View trajectories in the browser at:
+**[trycua.com/trajectory-viewer](http://trycua.com/trajectory-viewer)**
+
+The viewer provides:
+- Interactive conversation replay
+- Screenshot galleries
+- No data collection
+
+## Trajectory Structure
+
+Each trajectory contains:
+- **metadata.json**: Run info, timestamps, usage stats (`total_tokens`, `response_cost`)
+- **turn_000/**: Turn-by-turn conversation history (api calls, responses, computer calls, screenshots)
diff --git a/docs/content/docs/agent-sdk/chat-history.mdx b/docs/content/docs/agent-sdk/chat-history.mdx
new file mode 100644
index 00000000..83435a70
--- /dev/null
+++ b/docs/content/docs/agent-sdk/chat-history.mdx
@@ -0,0 +1,98 @@
+---
+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
+
+- **user**: User input messages
+- **computer_call**: Computer actions (click, type, keypress, etc.)
+- **computer_call_output**: Results from computer actions (usually screenshots)
+- **function_call**: Function calls (e.g., `computer.call`)
+- **function_call_output**: Results from function calls
+- **reasoning**: Agent's internal reasoning and planning
+- **message**: Agent text responses
+
+### Memory Management
+
+For long conversations, consider using the `only_n_most_recent_images` parameter to manage memory:
+
+```python
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ 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/docs/agent-sdk/local-models.mdx b/docs/content/docs/agent-sdk/local-models.mdx
new file mode 100644
index 00000000..347680a8
--- /dev/null
+++ b/docs/content/docs/agent-sdk/local-models.mdx
@@ -0,0 +1,39 @@
+---
+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"
+```
+
+---
+
+For details on all supported providers, see [Supported Agents](./supported-agents).
diff --git a/docs/content/docs/agent-sdk/meta.json b/docs/content/docs/agent-sdk/meta.json
new file mode 100644
index 00000000..933452cb
--- /dev/null
+++ b/docs/content/docs/agent-sdk/meta.json
@@ -0,0 +1,15 @@
+{
+ "title": "Agent SDK",
+ "description": "Build computer-using agents with the Agent SDK",
+ "pages": [
+ "agent-loops",
+ "supported-agents",
+ "chat-history",
+ "callbacks",
+ "sandboxed-tools",
+ "local-models",
+ "prompt-caching",
+ "usage-tracking",
+ "migration-guide"
+ ]
+}
diff --git a/docs/content/docs/agent-sdk/migration-guide.mdx b/docs/content/docs/agent-sdk/migration-guide.mdx
new file mode 100644
index 00000000..89ee706e
--- /dev/null
+++ b/docs/content/docs/agent-sdk/migration-guide.mdx
@@ -0,0 +1,124 @@
+---
+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-3-5-sonnet-20241022") 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-3-5-sonnet-20241022",
+ 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/docs/agent-sdk/prompt-caching.mdx b/docs/content/docs/agent-sdk/prompt-caching.mdx
new file mode 100644
index 00000000..4c69f99f
--- /dev/null
+++ b/docs/content/docs/agent-sdk/prompt-caching.mdx
@@ -0,0 +1,54 @@
+---
+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.
+
+> **Note:** This argument is only required for Anthropic CUAs. For other providers, it is ignored.
+
+## 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-3-5-sonnet-20240620",
+ use_prompt_caching=True,
+)
+```
+
+## Implementation Details
+- For Anthropic: Adds `{ "cache_control": "ephemeral" }` to messages when enabled.
+- For OpenAI: Caching is automatic for long prompts; the argument is ignored.
+
+## When to Use
+- Enable for Anthropic CUAs if you want to avoid reprocessing the same prompt in repeated or iterative tasks.
+- Not needed for OpenAI models unless you want explicit ephemeral cache control (not required for most users).
+
+## See Also
+- [Agent Loops](./agent-loops)
+- [Migration Guide](./migration-guide)
diff --git a/docs/content/docs/agent-sdk/sandboxed-tools.mdx b/docs/content/docs/agent-sdk/sandboxed-tools.mdx
new file mode 100644
index 00000000..0d71f8ef
--- /dev/null
+++ b/docs/content/docs/agent-sdk/sandboxed-tools.mdx
@@ -0,0 +1,31 @@
+---
+title: Sandboxed Tools
+slug: sandboxed-tools
+---
+
+The Agent SDK supports defining custom Python tools that run securely in sandboxed environments on remote Cua Computers. This enables safe execution of user-defined functions, isolation of dependencies, and robust automation workflows.
+
+## Example: Defining 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="anthropic/claude-3-5-sonnet-20240620",
+ tools=[computer, read_file],
+)
+```
diff --git a/docs/content/docs/agent-sdk/supported-agents.mdx b/docs/content/docs/agent-sdk/supported-agents.mdx
new file mode 100644
index 00000000..61abf521
--- /dev/null
+++ b/docs/content/docs/agent-sdk/supported-agents.mdx
@@ -0,0 +1,34 @@
+---
+title: Supported Agents
+---
+
+This page lists all supported agent loops and their compatible models/configurations in cua.
+
+All agent loops are compatible with any LLM provider supported by LiteLLM.
+
+See [Running Models Locally](./local-models) for how to use Hugging Face and MLX models on your own machine.
+
+## Anthropic CUAs
+
+- Claude 4: `claude-opus-4-20250514`, `claude-sonnet-4-20250514`
+- Claude 3.7: `claude-3-7-sonnet-20250219`
+- Claude 3.5: `claude-3-5-sonnet-20240620`
+
+## OpenAI CUA Preview
+
+- Computer-use-preview: `computer-use-preview`
+
+## UI-TARS 1.5
+
+- `huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B`
+- `huggingface/ByteDance-Seed/UI-TARS-1.5-7B` (requires TGI endpoint)
+
+## Omniparser + LLMs
+
+- `omniparser+vertex_ai/gemini-pro`
+- `omniparser+openai/gpt-4o`
+- Any LiteLLM-compatible model combined with Omniparser
+
+---
+
+For details on agent loop behavior and usage, see [Agent Loops](./agent-loops).
diff --git a/docs/content/docs/agent-sdk/usage-tracking.mdx b/docs/content/docs/agent-sdk/usage-tracking.mdx
new file mode 100644
index 00000000..54bbcaae
--- /dev/null
+++ b/docs/content/docs/agent-sdk/usage-tracking.mdx
@@ -0,0 +1,63 @@
+---
+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/docs/computer-sdk/commands.mdx b/docs/content/docs/computer-sdk/commands.mdx
new file mode 100644
index 00000000..dbac237f
--- /dev/null
+++ b/docs/content/docs/computer-sdk/commands.mdx
@@ -0,0 +1,248 @@
+---
+title: Commands
+description: Computer commands and interface methods
+---
+
+This page describes the set of supported **commands** you can use to control a Cua Computer directly via the Python SDK.
+
+These commands map to the same actions available in the [Computer Server API Commands Reference](../libraries/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:
+
+
+
+ ```python # Run shell command result = await
+ computer.interface.run_command(cmd) # result.stdout, result.stderr,
+ result.returncode ```
+
+
+ ```typescript // Run shell command const result = await
+ computer.interface.runCommand(cmd); // result.stdout, result.stderr,
+ result.returncode ```
+
+
+
+## Mouse Actions
+
+Precise mouse control and interaction:
+
+
+
+ ```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
+ ```
+
+
+
+ ```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
+ ```
+
+
+
+
+## Keyboard Actions
+
+Text input and key combinations:
+
+
+
+ ```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
+ ```
+
+
+
+ ```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
+ ```
+
+
+
+
+## Scrolling Actions
+
+Mouse wheel and scrolling control:
+
+
+
+
+ ```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
+
+ ```
+
+
+
+ ```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
+
+ ```
+
+
+
+## Screen Actions
+
+Screen capture and display information:
+
+
+
+ ```python
+ # Screen operations
+ await computer.interface.screenshot() # Take a screenshot
+ await computer.interface.get_screen_size() # Get screen dimensions
+
+ ```
+
+
+
+ ```typescript
+ // Screen operations
+ await computer.interface.screenshot(); // Take a screenshot
+ await computer.interface.getScreenSize(); // Get screen dimensions
+
+ ```
+
+
+
+## Clipboard Actions
+
+System clipboard management:
+
+
+
+ ```python
+ # Clipboard operations await
+ computer.interface.set_clipboard(text) # Set clipboard content await
+ computer.interface.copy_to_clipboard() # Get clipboard content
+
+ ```
+
+
+
+ ```typescript
+ // Clipboard operations
+ await computer.interface.setClipboard(text); // Set clipboard content
+ await computer.interface.copyToClipboard(); // Get clipboard content
+
+ ```
+
+
+
+
+## File System Operations
+
+Direct file and directory manipulation:
+
+
+
+
+ ```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
+ ```
+
+
+
+ ```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
+ ```
+
+
+
+
+## Accessibility
+
+Access system accessibility information:
+
+
+
+ ```python
+ # Get accessibility tree
+ await computer.interface.get_accessibility_tree()
+
+ ```
+
+
+
+ ```typescript
+ // Get accessibility tree
+ await computer.interface.getAccessibilityTree();
+
+```
+
+
+```
diff --git a/docs/content/docs/computer-sdk/computers.mdx b/docs/content/docs/computer-sdk/computers.mdx
new file mode 100644
index 00000000..470e8a65
--- /dev/null
+++ b/docs/content/docs/computer-sdk/computers.mdx
@@ -0,0 +1,102 @@
+---
+title: Cua Computers
+description: Understanding cua computer types and connection methods
+---
+
+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.
+
+Cua Computers are preconfigured virtual machines running the Computer Server. They can be either macOS, Linux, or Windows. They're found in either a cloud-native container, or on your host desktop.
+
+## cua cloud container
+
+This is a cloud container running the Computer Server. This is the easiest & safest way to get a cua computer, and can be done by going on the trycua.com website.
+
+
+
+ ```python
+ from computer import Computer
+
+ computer = Computer(
+ os_type="linux",
+ provider_type="cloud",
+ name="your-container-name",
+ api_key="your-api-key"
+ )
+
+ await computer.run() # Connect to the container
+ ```
+
+
+
+ ```typescript
+ import { Computer, OSType } from '@trycua/computer';
+
+ const computer = new Computer({
+ osType: OSType.LINUX,
+ name: "your-container-name",
+ apiKey: "your-api-key"
+ });
+
+ await computer.run(); // Connect to the container
+ ```
+
+
+
+
+## cua local containers
+
+cua provides local containers. This can be done using either the Lume CLI (macOS) or Docker CLI (Linux, Windows).
+
+### Lume (macOS Only):
+
+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 container
+
+```bash
+lume run macos-sequoia-cua:latest
+```
+
+3. Connect with Computer
+
+
+
+ ```python
+ computer = Computer(
+ os_type="macos",
+ provider_type="lume",
+ name="macos-sequoia-cua:latest"
+ )
+
+ await computer.run() # Connect to the container
+ ```
+
+
+
+
+## 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:
+
+
+
+ ```python
+
+ computer = Computer(use_host_computer_server=True) await
+ computer.run() # Connect to the host desktop
+
+ ```
+
+
+
diff --git a/docs/content/docs/computer-sdk/meta.json b/docs/content/docs/computer-sdk/meta.json
new file mode 100644
index 00000000..f632538b
--- /dev/null
+++ b/docs/content/docs/computer-sdk/meta.json
@@ -0,0 +1,9 @@
+{
+ "title": "Computer SDK",
+ "description": "Build computer-using agents with the Computer SDK",
+ "pages": [
+ "computers",
+ "commands",
+ "sandboxed-python"
+ ]
+}
diff --git a/docs/content/docs/computer-sdk/sandboxed-python.mdx b/docs/content/docs/computer-sdk/sandboxed-python.mdx
new file mode 100644
index 00000000..1e7f6b78
--- /dev/null
+++ b/docs/content/docs/computer-sdk/sandboxed-python.mdx
@@ -0,0 +1,49 @@
+---
+title: Sandboxed Python
+slug: sandboxed-python
+---
+
+You can run Python functions securely inside a sandboxed virtual environment on a remote Cua Computer. 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-container", 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"])
+```
+
+## 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/docs/index.mdx b/docs/content/docs/index.mdx
new file mode 100644
index 00000000..22d5986e
--- /dev/null
+++ b/docs/content/docs/index.mdx
@@ -0,0 +1,30 @@
+---
+title: Home
+icon: House
+---
+
+import { Monitor, Code, BookOpen } from 'lucide-react';
+
+# Welcome!
+
+Cua is a framework for automating Windows, Mac, and Linux apps powered by computer-using agents (CUAs).
+
+Cua makes every stage of computer-using agent development simple:
+
+- **Development**: Use any LLM provider with liteLLM. The agent SDK makes multiple agent loop providers, trajectory tracing, caching, and budget management easy
+- **Containerization**: cua offers Docker containers pre-installed with everything needed for AI-powered RPA
+- **Deployment**: cua cloud gives you a production-ready cloud environment for your assistants
+
+
+
+
+
diff --git a/docs/content/docs/libraries/agent/index.mdx b/docs/content/docs/libraries/agent/index.mdx
new file mode 100644
index 00000000..177f1b10
--- /dev/null
+++ b/docs/content/docs/libraries/agent/index.mdx
@@ -0,0 +1,125 @@
+---
+title: Agent
+description: Reference for the current version of the Agent library.
+pypi: cua-agent
+github:
+ - https://github.com/trycua/cua/tree/main/libs/python/agent
+---
+
+The Agent library provides the ComputerAgent class and tools for building AI agents that automate workflows on Cua Computers.
+
+## Reference
+
+### Basic Usage
+
+```python
+from agent import ComputerAgent
+from computer import Computer
+
+computer = Computer() # Connect to a cua container
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ tools=[computer]
+)
+
+prompt = "open github, navigate to trycua/cua"
+
+async for result in agent.run(prompt):
+ print("Agent:", result["output"][-1]["content"][0]["text"])
+```
+
+---
+
+### ComputerAgent Constructor Options
+
+The `ComputerAgent` constructor provides a wide range of options for customizing agent behavior, tool integration, callbacks, resource management, and more.
+
+| Parameter | Type | Default | Description |
+| --------------------------- | ----------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
+| `model` | `str` | **required** | Model name (e.g., "claude-3-5-sonnet-20241022", "computer-use-preview", "omni+vertex_ai/gemini-pro") |
+| `tools` | `List[Any]` | `None` | List of tools (e.g., computer objects, decorated functions) |
+| `custom_loop` | `Callable` | `None` | Custom agent loop function (overrides auto-selection) |
+| `only_n_most_recent_images` | `int` | `None` | If set, only keep the N most recent images in message history (adds ImageRetentionCallback) |
+| `callbacks` | `List[Any]` | `None` | List of AsyncCallbackHandler instances for preprocessing/postprocessing |
+| `verbosity` | `int` | `None` | Logging level (`logging.DEBUG`, `logging.INFO`, etc.; adds LoggingCallback) |
+| `trajectory_dir` | `str` | `None` | Directory to save trajectory data (adds TrajectorySaverCallback) |
+| `max_retries` | `int` | `3` | Maximum number of retries for failed API calls |
+| `screenshot_delay` | `float` \| `int` | `0.5` | Delay before screenshots (seconds) |
+| `use_prompt_caching` | `bool` | `False` | Use prompt caching to avoid reprocessing the same prompt (mainly for Anthropic) |
+| `max_trajectory_budget` | `float` \| `dict` | `None` | If set, adds BudgetManagerCallback to track usage costs and stop when budget is exceeded |
+| `**kwargs` | _any_ | | Additional arguments passed to the agent loop |
+
+#### Parameter Details
+
+- **model**: The LLM or agent model to use. Determines which agent loop is selected unless `custom_loop` is provided.
+- **tools**: List of tools the agent can use (e.g., `Computer`, sandboxed Python functions, etc.).
+- **custom_loop**: Optional custom agent loop function. If provided, overrides automatic loop selection.
+- **only_n_most_recent_images**: If set, only the N most recent images are kept in the message history. Useful for limiting memory usage. Automatically adds `ImageRetentionCallback`.
+- **callbacks**: List of callback instances for advanced preprocessing, postprocessing, logging, or custom hooks. See [Callbacks & Extensibility](#callbacks--extensibility).
+- **verbosity**: Logging level (e.g., `logging.INFO`). If set, adds a logging callback.
+- **trajectory_dir**: Directory path to save full trajectory data, including screenshots and responses. Adds `TrajectorySaverCallback`.
+- **max_retries**: Maximum number of retries for failed API calls (default: 3).
+- **screenshot_delay**: Delay (in seconds) before taking screenshots (default: 0.5).
+- **use_prompt_caching**: Enables prompt caching for repeated prompts (mainly for Anthropic models).
+- **max_trajectory_budget**: 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 }`).
+- **\*\*kwargs**: 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-3-5-sonnet-20241022",
+ 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}
+)
+```
+
+---
+
+### Message Array (Multi-turn)
+
+```python
+messages = [
+ {"role": "user", "content": "go to trycua on gh"},
+ # ... (reasoning, computer_call, computer_call_output, etc)
+]
+async for result in agent.run(messages):
+ # Handle output, tool invocations, screenshots, etc.
+ print("Agent:", result["output"][-1]["content"][0]["text"])
+ messages += result["output"] # Add agent output to message array
+ ...
+```
+
+### Supported Agent Loops
+
+- **Anthropic**: Claude 4, 3.7, 3.5 models
+- **OpenAI**: computer-use-preview
+- **UITARS**: UI-TARS 1.5 models (Hugging Face, TGI)
+- **Omni**: Omniparser + any LLM
+
+See [Agent Loops](../../agent-sdk/agent-loops) for supported models and details.
+
+### Callbacks & Extensibility
+
+You can add preprocessing and postprocessing hooks using callbacks, or write your own by subclassing `AsyncCallbackHandler`:
+
+```python
+from agent.callbacks import ImageRetentionCallback, PIIAnonymizationCallback
+
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ tools=[computer],
+ callbacks=[ImageRetentionCallback(only_n_most_recent_images=3)]
+)
+```
diff --git a/docs/content/docs/libraries/computer-server/Commands.mdx b/docs/content/docs/libraries/computer-server/Commands.mdx
new file mode 100644
index 00000000..269162a1
--- /dev/null
+++ b/docs/content/docs/libraries/computer-server/Commands.mdx
@@ -0,0 +1,48 @@
+---
+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/docs/libraries/computer-server/REST-API.mdx b/docs/content/docs/libraries/computer-server/REST-API.mdx
new file mode 100644
index 00000000..369565de
--- /dev/null
+++ b/docs/content/docs/libraries/computer-server/REST-API.mdx
@@ -0,0 +1,63 @@
+---
+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": "",
+ "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/docs/libraries/computer-server/WebSocket-API.mdx b/docs/content/docs/libraries/computer-server/WebSocket-API.mdx
new file mode 100644
index 00000000..98d6d7ad
--- /dev/null
+++ b/docs/content/docs/libraries/computer-server/WebSocket-API.mdx
@@ -0,0 +1,86 @@
+---
+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": "",
+ "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/docs/libraries/computer-server/index.mdx b/docs/content/docs/libraries/computer-server/index.mdx
new file mode 100644
index 00000000..c2a9c43c
--- /dev/null
+++ b/docs/content/docs/libraries/computer-server/index.mdx
@@ -0,0 +1,13 @@
+---
+title: Computer Server
+descrption: Reference for the current version of the Computer Server library.
+pypi: cua-computer-server
+github:
+ - https://github.com/trycua/cua/tree/main/libs/python/computer-server
+---
+
+The Computer Server API reference documentation is currently under development.
+
+## Overview
+
+The Computer Server provides WebSocket and REST API endpoints for remote computer control and automation.
diff --git a/docs/content/docs/libraries/computer/index.mdx b/docs/content/docs/libraries/computer/index.mdx
new file mode 100644
index 00000000..4ac698d6
--- /dev/null
+++ b/docs/content/docs/libraries/computer/index.mdx
@@ -0,0 +1,209 @@
+---
+title: Computer
+description: Reference for the current version of the Computer library.
+pypi: cua-computer
+npm: '@trycua/computer'
+github:
+ - https://github.com/trycua/cua/tree/main/libs/python/computer
+ - https://github.com/trycua/cua/tree/main/libs/typescript/computer
+---
+
+The Computer library provides a Computer class that can be used to control and automate a container running the Computer Server.
+
+## Reference
+
+### Basic Usage
+
+Connect to a cua cloud container:
+
+
+
+ ```python
+ from computer import Computer
+
+ computer = Computer(
+ os_type="linux",
+ provider_type="cloud",
+ name="your-container-name",
+ api_key="your-api-key"
+ )
+
+ computer = await computer.run() # Connect to a cua cloud container
+ ```
+
+
+
+ ```typescript
+ import { Computer, OSType } from '@trycua/computer';
+
+ const computer = new Computer({
+ osType: OSType.LINUX,
+ name: "your-container-name",
+ apiKey: "your-api-key"
+ });
+
+ await computer.run(); // Connect to a cua cloud container
+ ```
+
+
+
+
+Connect to a cua local container:
+
+
+
+ ```python
+ from computer import Computer
+
+ computer = Computer(
+ os_type="macos"
+ )
+
+ computer = await computer.run() # Connect to the container
+ ```
+
+
+
+
+### Interface Actions
+
+
+
+ ```python
+ # Shell Actions
+ result = await computer.interface.run_command(cmd) # Run shell command
+ # result.stdout, result.stderr, result.returncode
+
+ # Mouse Actions
+ 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
+ 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
+ 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
+
+ # Keyboard Actions
+ await computer.interface.type_text("Hello") # Type text
+ await computer.interface.press_key("enter") # Press a single key
+ 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
+
+ # Scrolling Actions
+ 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
+
+ # Screen Actions
+ await computer.interface.screenshot() # Take a screenshot
+ await computer.interface.get_screen_size() # Get screen dimensions
+
+ # Clipboard Actions
+ await computer.interface.set_clipboard(text) # Set clipboard content
+ await computer.interface.copy_to_clipboard() # Get clipboard content
+
+ # File System Operations
+ await computer.interface.file_exists(path) # Check if file exists
+ await computer.interface.directory_exists(path) # Check if directory exists
+ 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
+ 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
+
+ # Accessibility
+ await computer.interface.get_accessibility_tree() # Get accessibility tree
+
+ # Delay Configuration
+ # 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
+
+ # Python Virtual Environment Operations
+ 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
+
+ # Example: Use sandboxed functions to execute code in a Cua Container
+ from computer.helpers import sandboxed
+
+ @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 container, {name}!")
+ return {"greeted": name, "safari_html": html}
+
+ # When a @sandboxed function is called, it will execute in the container
+ result = await greet_and_print("Cua")
+ # Result: {"greeted": "Cua", "safari_html": "..."}
+ # stdout and stderr are also captured and printed / raised
+ print("Result from sandboxed function:", result)
+ ```
+
+
+
+ ```typescript
+ // Shell Actions
+ const result = await computer.interface.runCommand(cmd); // Run shell command
+ // result.stdout, result.stderr, result.returncode
+
+ // Mouse Actions
+ 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
+ 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
+ await computer.interface.mouseDown(x, y, "left"); // Press and hold a mouse button
+ await computer.interface.mouseUp(x, y, "left"); // Release a mouse button
+
+ // Keyboard Actions
+ await computer.interface.typeText("Hello"); // Type text
+ await computer.interface.pressKey("enter"); // Press a single key
+ 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
+
+ // Scrolling Actions
+ await computer.interface.scroll(x, y); // Scroll the mouse wheel
+ await computer.interface.scrollDown(clicks); // Scroll down
+ await computer.interface.scrollUp(clicks); // Scroll up
+
+ // Screen Actions
+ await computer.interface.screenshot(); // Take a screenshot
+ await computer.interface.getScreenSize(); // Get screen dimensions
+
+ // Clipboard Actions
+ await computer.interface.setClipboard(text); // Set clipboard content
+ await computer.interface.copyToClipboard(); // Get clipboard content
+
+ // File System Operations
+ await computer.interface.fileExists(path); // Check if file exists
+ await computer.interface.directoryExists(path); // Check if directory exists
+ 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
+ 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
+
+ // Accessibility
+ await computer.interface.getAccessibilityTree(); // Get accessibility tree
+ ```
+
+
+
diff --git a/docs/content/docs/libraries/core/index.mdx b/docs/content/docs/libraries/core/index.mdx
new file mode 100644
index 00000000..394c7547
--- /dev/null
+++ b/docs/content/docs/libraries/core/index.mdx
@@ -0,0 +1,13 @@
+---
+title: Core
+description: Reference for the current version of the Core library.
+pypi: cua-core
+npm: '@trycua/core'
+github:
+ - https://github.com/trycua/cua/tree/main/libs/python/core
+ - https://github.com/trycua/cua/tree/main/libs/typescript/core
+---
+
+## Overview
+
+The Core library provides foundational utilities and shared functionality across the CUA ecosystem.
diff --git a/docs/content/docs/libraries/lume/cli-reference.mdx b/docs/content/docs/libraries/lume/cli-reference.mdx
new file mode 100644
index 00000000..da8bdee1
--- /dev/null
+++ b/docs/content/docs/libraries/lume/cli-reference.mdx
@@ -0,0 +1,71 @@
+---
+title: Lume CLI Reference
+description: Command Line Interface reference for 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).
+
+## Quick Start
+
+Install and run a prebuilt macOS VM 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
+```
+
+> **Security Note**: All prebuilt images use the default password `lume`. Change this immediately after your first login using the `passwd` command.
+
+**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
+
+Install with a single command:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+```
+
+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"
+```
+
+> **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).
+
+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.
+
+## Using Lume
+
+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
+```
+
+> We provide [prebuilt VM images](#prebuilt-images) in our [ghcr registry](https://github.com/orgs/trycua/packages).
+
+### 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
+```
+
+> **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 --disk-size `.
diff --git a/docs/content/docs/libraries/lume/http-api.mdx b/docs/content/docs/libraries/lume/http-api.mdx
new file mode 100644
index 00000000..5191119c
--- /dev/null
+++ b/docs/content/docs/libraries/lume/http-api.mdx
@@ -0,0 +1,598 @@
+---
+title: HTTP Server API
+description: Lume exposes a local HTTP API server that listens at localhost for programatic management of VMs.
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+
+## Default URL
+
+```
+http://localhost:7777
+```
+
+
+ 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`.
+
+
+## Endpoints
+
+### Create VM
+
+Create a new virtual machine.
+
+`POST: /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
+
+
+
+
+```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
+```
+
+
+
+
+```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())
+```
+
+
+
+
+```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', {
+ methdo: 'POST'
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json())
+```
+
+
+
+
+### Run VM
+
+Run a virtual machine instance.
+
+`POST: /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
+
+
+
+
+```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
+```
+
+
+
+
+```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())
+```
+
+
+
+
+```typescript
+// Basic run
+const 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',
+};
+const res2 = await fetch('http://localhost:7777/lume/vms/lume_vm/run', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res2.json());
+```
+
+
+
+
+### List VMs
+
+List all virtual machines.
+
+`GET: /vms`
+
+#### Example Request
+
+
+
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ http://localhost:7777/lume/vms
+```
+
+
+
+
+```python
+import requests
+
+r = requests.get("http://localhost:7777/lume/vms", timeout=50)
+print(r.json())
+```
+
+
+
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/vms');
+console.log(await res.json());
+```
+
+
+
+
+```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: /vms/:name`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ------- | ------ | -------- | -------------------------- |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+
+
+
+```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
+```
+
+
+
+
+```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())
+```
+
+
+
+
+```typescript
+// Basic get
+const res = await fetch('http://localhost:7777/lume/vms/lume_vm');
+console.log(await res.json());
+
+// Get with specific storage
+const res2 = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd');
+console.log(await res2.json());
+```
+
+
+
+
+```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.
+
+`PUT: /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
+
+
+
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X PUT \
+ -H "Content-Type: application/json" \
+ -d '{
+ "cpu": 4,
+ "memory": "8GB",
+ "diskSize": "100GB",
+ "display": "1920x1080",
+ "storage": "ssd"
+ }' \
+ http://localhost:7777/lume/vms/lume_vm
+```
+
+
+
+
+```python
+import requests
+
+payload = {
+ "cpu": 4,
+ "memory": "8GB",
+ "diskSize": "100GB",
+ "display": "1920x1080",
+ "storage": "ssd"
+}
+r = requests.put("http://localhost:7777/lume/vms/lume_vm", json=payload, timeout=50)
+print(r.json())
+```
+
+
+
+
+```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: 'PUT',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+
+
+
+### Stop VM
+
+Stop a running virtual machine.
+
+`POST: /vms/:name/stop`
+
+#### Example Request
+
+
+
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ http://localhost:7777/lume/vms/lume_vm/stop
+```
+
+
+
+
+```python
+import requests
+
+r = requests.post("http://localhost:7777/lume/vms/lume_vm/stop", timeout=50)
+print(r.json())
+```
+
+
+
+
+```typescript
+const res = await fetch('http://localhost:7777/lume/vms/lume_vm/stop', {
+ method: 'POST',
+});
+console.log(await res.json());
+```
+
+
+
+
+### Delete VM
+
+Delete a virtual machine instance.
+
+`DELETE: /vms/:name`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ------- | ------ | -------- | -------------------------- |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+
+
+
+```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
+```
+
+
+
+
+```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)
+```
+
+
+
+
+```typescript
+// Basic delete
+const res = await fetch('http://localhost:7777/lume/vms/lume_vm', {
+ method: 'DELETE',
+});
+console.log(res.status);
+
+// Delete with specific storage
+const res2 = await fetch('http://localhost:7777/lume/vms/lume_vm?storage=ssd', {
+ method: 'DELETE',
+});
+console.log(res2.status);
+```
+
+
+
+
+### Pull VM Image
+
+Pull a VM image from a registry.
+
+`POST: /images/pull`
+
+#### Parameters
+
+| Name | Type | Required | Description |
+| ------------ | ------ | -------- | ------------------------------------- |
+| image | string | Yes | Image name (e.g. `macos-sequoia-...`) |
+| registry | string | Yes | Registry host (e.g. `ghcr.io`) |
+| organization | string | Yes | Organization name |
+| storage | string | No | Storage type (`ssd`, etc.) |
+
+#### Example Request
+
+
+
+
+```bash
+curl --connect-timeout 6000 \
+ --max-time 5000 \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "image": "macos-sequoia-vanilla:latest",
+ "registry": "ghcr.io",
+ "organization": "trycua",
+ "storage": "ssd"
+ }' \
+ http://localhost:7777/lume/images/pull
+```
+
+
+
+
+```python
+import requests
+
+payload = {
+ "image": "macos-sequoia-vanilla:latest",
+ "registry": "ghcr.io",
+ "organization": "trycua",
+ "storage": "ssd"
+}
+r = requests.post("http://localhost:7777/lume/images/pull", json=payload, timeout=50)
+print(r.json())
+```
+
+
+
+
+```typescript
+const payload = {
+ image: 'macos-sequoia-vanilla:latest',
+ registry: 'ghcr.io',
+ organization: 'trycua',
+ storage: 'ssd',
+};
+const res = await fetch('http://localhost:7777/lume/images/pull', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(payload),
+});
+console.log(await res.json());
+```
+
+
+
diff --git a/docs/content/docs/libraries/lume/index.mdx b/docs/content/docs/libraries/lume/index.mdx
new file mode 100644
index 00000000..28080bff
--- /dev/null
+++ b/docs/content/docs/libraries/lume/index.mdx
@@ -0,0 +1,10 @@
+---
+title: Lume
+description: Reference for the current version of the Lume CLI.
+github:
+ - https://github.com/trycua/cua/tree/main/libs/lume
+---
+
+## Overview
+
+The Lume CLI provides command line tools for managing virtual machines with Lume.
diff --git a/docs/content/docs/libraries/lumier/index.mdx b/docs/content/docs/libraries/lumier/index.mdx
new file mode 100644
index 00000000..3858504d
--- /dev/null
+++ b/docs/content/docs/libraries/lumier/index.mdx
@@ -0,0 +1,69 @@
+---
+title: Lumier
+description: Reference for the current version of the Lumier library.
+github:
+ - https://github.com/trycua/cua/tree/main/libs/lumier
+---
+
+## Overview
+
+The Lumier library provides a Docker-based interface for creating performant macOS virtual machines.
+
+## Installation
+
+**Requirements:**
+- Docker for Apple Silicon (or compatible Mac)
+- Lume virtualization CLI (install with: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"`)
+
+## Usage
+
+### Run a macOS VM (ephemeral)
+```bash
+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](http://localhost:8006).
+
+### Persistent Storage
+```bash
+mkdir -p 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
+```
+
+### Shared Folder
+```bash
+mkdir -p shared
+
+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
+```
+
+---
+
+See the [Lumier README](https://github.com/trycua/cua/tree/main/libs/lumier) for advanced options, Docker Compose setup, and automation scripts.
\ No newline at end of file
diff --git a/docs/content/docs/libraries/mcp-server/index.mdx b/docs/content/docs/libraries/mcp-server/index.mdx
new file mode 100644
index 00000000..f9885bf1
--- /dev/null
+++ b/docs/content/docs/libraries/mcp-server/index.mdx
@@ -0,0 +1,19 @@
+---
+title: MCP Server
+description: Reference for the current version of the MCP Server library.
+pypi: cua-mcp-server
+github:
+ - https://github.com/trycua/cua/tree/main/libs/python/mcp-server
+---
+
+## ⚠️ 🚧 Under Construction 🚧 ⚠️
+
+The MCP Server API reference documentation is currently under development.
+
+## Overview
+
+The MCP Server provides Model Context Protocol endpoints for AI model integration.
+
+## API Documentation
+
+Coming soon.
diff --git a/docs/content/docs/libraries/som/index.mdx b/docs/content/docs/libraries/som/index.mdx
new file mode 100644
index 00000000..e61f7a05
--- /dev/null
+++ b/docs/content/docs/libraries/som/index.mdx
@@ -0,0 +1,58 @@
+---
+title: Set-of-Mark
+description: Reference for the current version of the Set-of-Mark library.
+pypi: cua-som
+github:
+ - https://github.com/trycua/cua/tree/main/libs/python/som
+---
+
+## Overview
+
+The SOM library provides visual element detection and interaction capabilities. It is based on the [Set-of-Mark](https://arxiv.org/abs/2310.11441) research paper and the [OmniParser](https://github.com/microsoft/OmniParser) model.
+
+## API Documentation
+
+### OmniParser Class
+
+```python
+class OmniParser:
+ def __init__(self, device: str = "auto"):
+ """Initialize the parser with automatic device detection"""
+
+ def parse(
+ self,
+ image: PIL.Image,
+ box_threshold: float = 0.3,
+ iou_threshold: float = 0.1,
+ use_ocr: bool = True,
+ ocr_engine: str = "easyocr"
+ ) -> ParseResult:
+ """Parse UI elements from an image"""
+```
+
+### ParseResult Object
+
+```python
+@dataclass
+class ParseResult:
+ elements: List[UIElement] # Detected elements
+ visualized_image: PIL.Image # Annotated image
+ processing_time: float # Time in seconds
+
+ def to_dict(self) -> dict:
+ """Convert to JSON-serializable dictionary"""
+
+ def filter_by_type(self, elem_type: str) -> List[UIElement]:
+ """Filter elements by type ('icon' or 'text')"""
+```
+
+### UIElement
+
+```python
+class UIElement(BaseModel):
+ id: Optional[int] = Field(None) # Element ID (1-indexed)
+ type: Literal["icon", "text"] # Element type
+ bbox: BoundingBox # Bounding box coordinates { x1, y1, x2, y2 }
+ interactivity: bool = Field(default=False) # Whether the element is interactive
+ confidence: float = Field(default=1.0) # Detection confidence
+```
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
new file mode 100644
index 00000000..9aea034a
--- /dev/null
+++ b/docs/content/docs/meta.json
@@ -0,0 +1,19 @@
+{
+ "title": "Home",
+ "description": "Documentation Home",
+ "root": true,
+ "defaultOpen": true,
+ "pages": [
+ "index",
+ "quickstart-ui",
+ "quickstart-cli",
+ "quickstart-devs",
+ "telemetry",
+ "---[BookCopy]Computer Playbook---",
+ "...computer-sdk",
+ "---[BookCopy]Agent Playbook---",
+ "...agent-sdk",
+ "---[CodeXml]API Reference---",
+ "...libraries"
+ ]
+}
\ No newline at end of file
diff --git a/docs/content/docs/quickstart-cli.mdx b/docs/content/docs/quickstart-cli.mdx
new file mode 100644
index 00000000..84aa80ae
--- /dev/null
+++ b/docs/content/docs/quickstart-cli.mdx
@@ -0,0 +1,281 @@
+---
+title: Quickstart (CLI)
+description: Get started with the cua Agent CLI in 4 steps
+icon: Rocket
+---
+
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
+
+Get up and running with the cua Agent CLI in 4 simple steps.
+
+
+
+
+## Introduction
+
+cua combines Computer (interface) + Agent (AI) for automating desktop apps. The Agent CLI provides a clean terminal interface to control your remote computer using natural language commands.
+
+
+
+
+
+## Create Your First cua Container
+
+1. Go to [trycua.com/signin](https://www.trycua.com/signin)
+2. Navigate to **Dashboard > Containers > Create Instance**
+3. Create a **Medium, Ubuntu 22** container
+4. Note your container name and API key
+
+
+
+
+
+## Install cua
+
+
+
+
+
+### Install uv
+
+
+
+
+```bash
+# Use curl to download the script and execute it with sh:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# If your system doesn't have curl, you can use wget:
+# wget -qO- https://astral.sh/uv/install.sh | sh
+```
+
+
+
+
+```powershell
+# Use irm to download the script and execute it with iex:
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+
+
+
+### Install Python 3.12
+
+```bash
+uv python install 3.12
+# uv will install cua dependencies automatically when you use --with "cua-agent[cli]"
+```
+
+
+
+
+
+### Install conda
+
+
+
+
+```bash
+mkdir -p ~/miniconda3
+curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/miniconda3/miniconda.sh
+bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
+rm ~/miniconda3/miniconda.sh
+source ~/miniconda3/bin/activate
+```
+
+
+
+
+```bash
+mkdir -p ~/miniconda3
+wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
+bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
+rm ~/miniconda3/miniconda.sh
+source ~/miniconda3/bin/activate
+```
+
+
+
+
+```powershell
+wget "https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe" -outfile ".\miniconda.exe"
+Start-Process -FilePath ".\miniconda.exe" -ArgumentList "/S" -Wait
+del .\miniconda.exe
+```
+
+
+
+
+### Create and activate Python 3.12 environment
+
+```bash
+conda create -n cua python=3.12
+conda activate cua
+```
+
+### Install cua
+
+```bash
+pip install "cua-agent[cli]" cua-computer
+```
+
+
+
+
+
+### Install cua
+
+```bash
+pip install "cua-agent[cli]" cua-computer
+```
+
+
+
+
+
+
+
+
+
+## Run cua CLI
+
+Choose your preferred AI model:
+
+### OpenAI Computer Use Preview
+
+
+
+
+```bash
+uv run --with "cua-agent[cli]" -m agent.cli openai/computer-use-preview
+```
+
+
+
+
+```bash
+python -m agent.cli openai/computer-use-preview
+```
+
+
+
+
+### Anthropic Claude
+
+
+
+
+```bash
+uv run --with "cua-agent[cli]" -m agent.cli anthropic/claude-3-5-sonnet-20241022
+uv run --with "cua-agent[cli]" -m agent.cli anthropic/claude-opus-4-20250514
+uv run --with "cua-agent[cli]" -m agent.cli anthropic/claude-sonnet-4-20250514
+```
+
+
+
+
+```bash
+python -m agent.cli anthropic/claude-3-5-sonnet-20241022
+python -m agent.cli anthropic/claude-opus-4-20250514
+python -m agent.cli anthropic/claude-sonnet-4-20250514
+```
+
+
+
+
+### Omniparser + LLMs
+
+
+
+
+```bash
+uv run --with "cua-agent[cli]" -m agent.cli omniparser+anthropic/claude-3-5-sonnet-20241022
+uv run --with "cua-agent[cli]" -m agent.cli omniparser+openai/gpt-4o
+uv run --with "cua-agent[cli]" -m agent.cli omniparser+vertex_ai/gemini-pro
+```
+
+
+
+
+```bash
+python -m agent.cli omniparser+anthropic/claude-3-5-sonnet-20241022
+python -m agent.cli omniparser+openai/gpt-4o
+python -m agent.cli omniparser+vertex_ai/gemini-pro
+```
+
+
+
+
+### Local Models
+
+
+
+
+```bash
+# Hugging Face models (local)
+uv run --with "cua-agent[cli]" -m agent.cli huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B
+
+# MLX models (Apple Silicon)
+uv run --with "cua-agent[cli]" -m agent.cli mlx/mlx-community/UI-TARS-1.5-7B-6bit
+
+# Ollama models
+uv run --with "cua-agent[cli]" -m agent.cli omniparser+ollama_chat/llama3.2:latest
+```
+
+
+
+
+```bash
+# Hugging Face models (local)
+python -m agent.cli huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B
+
+# MLX models (Apple Silicon)
+python -m agent.cli mlx/mlx-community/UI-TARS-1.5-7B-6bit
+
+# Ollama models
+python -m agent.cli omniparser+ollama_chat/llama3.2:latest
+```
+
+
+
+
+### Interactive Setup
+
+If you haven't set up environment variables, the CLI will guide you through the setup:
+
+1. **Container Name**: Enter your cua container name (or get one at [trycua.com](https://www.trycua.com/))
+2. **CUA API Key**: Enter your cua API key
+3. **Provider API Key**: Enter your AI provider API key (OpenAI, Anthropic, etc.)
+
+### Start Chatting
+
+Once connected, you'll see:
+
+```
+💻 Connected to your-container-name (model, agent_loop)
+Type 'exit' to quit.
+
+>
+```
+
+You can ask your agent to perform actions like:
+
+- "Take a screenshot and tell me what's on the screen"
+- "Open Firefox and go to github.com"
+- "Type 'Hello world' into the terminal"
+- "Close the current window"
+- "Click on the search button"
+
+
+
+
+---
+
+For advanced Python usage and GUI interface, see the [Quickstart (GUI)](/quickstart-ui) and [Quickstart for Developers](/quickstart-devs).
+
+For a complete list of supported models, see [Supported Agents](/agent-sdk/supported-agents).
+
+For running models locally, see [Running Models Locally](/agent-sdk/local-models).
diff --git a/docs/content/docs/quickstart-devs.mdx b/docs/content/docs/quickstart-devs.mdx
new file mode 100644
index 00000000..cd002746
--- /dev/null
+++ b/docs/content/docs/quickstart-devs.mdx
@@ -0,0 +1,127 @@
+---
+title: Quickstart (for Developers)
+description: Get started with cua in 5 steps
+icon: Rocket
+---
+
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+Get up and running with cua in 5 simple steps.
+
+
+
+
+## Introduction
+
+cua combines Computer (interface) + Agent (AI) for automating desktop apps. Computer handles clicks/typing, Agent provides the intelligence.
+
+
+
+
+
+## Create Your First cua Container
+
+1. Go to [trycua.com/signin](https://www.trycua.com/signin)
+2. Navigate to **Dashboard > Containers > Create Instance**
+3. Create a **Medium, Ubuntu 22** container
+4. Note your container name and API key
+
+
+
+
+
+## Install cua
+
+
+
+ ```bash pip install "cua-agent[all]" cua-computer ```
+
+ ```bash npm install @trycua/computer ```
+
+
+
+
+
+
+## Using Computer
+
+
+
+ ```python
+ from computer import Computer
+
+ async with Computer(
+ os_type="linux",
+ provider_type="cloud",
+ name="your-container-name",
+ api_key="your-api-key"
+ ) as computer:
+ # Take screenshot
+ screenshot = await computer.interface.screenshot()
+
+ # Click and type
+ await computer.interface.left_click(100, 100)
+ await computer.interface.type("Hello!")
+ ```
+
+
+
+ ```typescript
+ import { Computer, OSType } from '@trycua/computer';
+
+ const computer = new Computer({
+ osType: OSType.LINUX,
+ name: "your-container-name",
+ apiKey: "your-api-key"
+ });
+
+ await computer.run();
+
+ try {
+ // Take screenshot
+ const screenshot = await computer.interface.screenshot();
+
+ // Click and type
+ await computer.interface.leftClick(100, 100);
+ await computer.interface.typeText("Hello!");
+ } finally {
+ await computer.close();
+ }
+ ```
+
+
+
+
+
+
+
+
+## Using Agent
+
+```python
+from agent import ComputerAgent
+
+agent = ComputerAgent(
+ model="anthropic/claude-3-5-sonnet-20241022",
+ 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"])
+```
+
+
+
+
+## Next Steps
+
+{/* - Explore the [SDK documentation](/sdk) for advanced features */}
+
+- Learn about [trajectory tracking](/agent-sdk/callbacks/trajectories) and [callbacks](/agent-sdk/callbacks/agent-lifecycle)
+- Join our [Discord community](https://discord.com/invite/mVnXXpdE85) for support
diff --git a/docs/content/docs/quickstart-ui.mdx b/docs/content/docs/quickstart-ui.mdx
new file mode 100644
index 00000000..fb7a2b0d
--- /dev/null
+++ b/docs/content/docs/quickstart-ui.mdx
@@ -0,0 +1,166 @@
+---
+title: Quickstart (GUI)
+description: Get started with the cua Agent UI in 3 steps
+icon: Rocket
+---
+
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
+
+Get up and running with the cua Agent UI in 3 simple steps.
+
+
+
+
+## Introduction
+
+cua combines Computer (interface) + Agent (AI) for automating desktop apps. The Agent UI provides a simple chat interface to control your remote computer using natural language.
+
+
+
+
+
+## Create Your First cua Container
+
+1. Go to [trycua.com/signin](https://www.trycua.com/signin)
+2. Navigate to **Dashboard > Containers > Create Instance**
+3. Create a **Medium, Ubuntu 22** container
+4. Note your container name and API key
+
+
+
+
+
+## Install and Run cua
+
+
+
+
+
+### Install uv
+
+
+
+
+```bash
+# Use curl to download the script and execute it with sh:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# If your system doesn't have curl, you can use wget:
+# wget -qO- https://astral.sh/uv/install.sh | sh
+```
+
+
+
+
+```powershell
+# Use irm to download the script and execute it with iex:
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+
+
+
+### Install Python 3.12
+
+```bash
+uv python install 3.12
+```
+
+### Run cua
+
+```bash
+uv run --with "cua-agent[ui]" -m agent.ui
+```
+
+
+
+
+
+### Install conda
+
+
+
+
+```bash
+mkdir -p ~/miniconda3
+curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/miniconda3/miniconda.sh
+bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
+rm ~/miniconda3/miniconda.sh
+source ~/miniconda3/bin/activate
+```
+
+
+
+
+```bash
+mkdir -p ~/miniconda3
+wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
+bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
+rm ~/miniconda3/miniconda.sh
+source ~/miniconda3/bin/activate
+```
+
+
+
+
+```powershell
+wget "https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe" -outfile ".\miniconda.exe"
+Start-Process -FilePath ".\miniconda.exe" -ArgumentList "/S" -Wait
+del .\miniconda.exe
+```
+
+
+
+
+### Create and activate Python 3.12 environment
+
+```bash
+conda create -n cua python=3.12
+conda activate cua
+```
+
+### Install and run cua
+
+```bash
+pip install "cua-agent[ui]" cua-computer
+python -m agent.ui
+```
+
+
+
+
+
+### Install cua
+
+```bash
+pip install "cua-agent[ui]" cua-computer
+```
+
+### Run the Agent UI
+
+```bash
+python -m agent.ui
+```
+
+
+
+
+
+### Start Chatting
+
+Open your browser to the displayed URL and start chatting with your computer-using agent.
+
+You can ask your agent to perform actions like:
+
+- "Open Firefox and go to github.com"
+- "Take a screenshot and tell me what's on the screen"
+- "Type 'Hello world' into the terminal"
+
+
+
+
+---
+
+For advanced Python usage, see the [Quickstart for Developers](/quickstart-devs).
diff --git a/docs/content/docs/telemetry.mdx b/docs/content/docs/telemetry.mdx
new file mode 100644
index 00000000..a62b4f5f
--- /dev/null
+++ b/docs/content/docs/telemetry.mdx
@@ -0,0 +1,144 @@
+---
+title: Telemetry
+description: This document explains how telemetry works in CUA libraries and how you can control it.
+icon: RadioTower
+---
+
+# Telemetry in CUA
+
+CUA tracks anonymized usage and error report statistics; we ascribe to Posthog's approach as detailed [here](https://posthog.com/blog/open-source-telemetry-ethical). If you would like to opt out of sending anonymized info, you can set `telemetry_enabled` to false.
+
+## What telemetry data we collect
+
+CUA libraries collect usage data to help improve our software. We have two categories of telemetry:
+
+### Opt-Out Telemetry (Enabled by Default)
+
+Basic performance metrics and system information that help us understand usage patterns:
+
+- **System Information**: Operating system, OS version, Python version
+- **Module Initialization**: When modules are imported and their versions
+- **Performance Metrics**: Agent run durations, step counts, token usage, and API costs
+- **Session Tracking**: Anonymous session IDs and run IDs for performance analysis
+
+### Opt-In Telemetry (Disabled by Default)
+
+**Conversation Trajectory Logging**: Full conversation history including:
+- User messages and agent responses
+- Computer actions and their outputs
+- Reasoning traces from the agent
+
+**Important**: Trajectory logging is **opt-in only** and must be explicitly enabled.
+
+### We do NOT collect:
+
+- Personal information or user identifiers
+- API keys or credentials
+- File contents or application data
+- Information about files being accessed
+- Actual screenshots or screen contents (unless trajectory logging is enabled)
+- Specific text being typed, including user inputs, model outputs, computer outputs, or tool call outputs (unless trajectory logging is enabled)
+
+## Controlling Telemetry
+
+We are committed to transparency and user control over telemetry. There are two ways to control telemetry:
+
+### 1. Environment Variable (Global Control)
+
+Telemetry is enabled by default. To disable telemetry, set the `CUA_TELEMETRY_ENABLED` environment variable to a falsy value (`0`, `false`, `no`, or `off`):
+
+```bash
+# Disable telemetry before running your script
+export CUA_TELEMETRY_ENABLED=false
+
+# Or as part of the command
+CUA_TELEMETRY_ENABLED=1 python your_script.py
+
+```
+
+Or from Python:
+
+```python
+import os
+os.environ["CUA_TELEMETRY_ENABLED"] = "false"
+```
+
+### 2. Instance-Level Control
+
+#### Computer SDK
+
+```python
+from computer import Computer
+
+# Enable telemetry (default)
+computer = Computer(telemetry_enabled=True)
+
+# Disable telemetry
+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-3-5-sonnet-20241022",
+ telemetry_enabled=True # Default is True
+)
+
+# Enable telemetry with full conversation trajectory logging (opt-in)
+agent = ComputerAgent(
+ model="claude-3-5-sonnet-20241022",
+ telemetry_enabled={
+ "log_trajectory": True # Logs full conversation items
+ }
+)
+
+# Disable telemetry completely
+agent = ComputerAgent(
+ model="claude-3-5-sonnet-20241022",
+ telemetry_enabled=False
+)
+
+# Disable telemetry completely using environment variables
+os.environ["CUA_TELEMETRY_ENABLED"] = "false"
+agent = ComputerAgent(
+ model="claude-3-5-sonnet-20241022"
+)
+```
+
+You can check if telemetry is enabled for an instance:
+
+```python
+print(computer.telemetry_enabled) # Will print True or False
+print(agent.telemetry_enabled) # Will print True, False, or dict
+```
+
+Note that telemetry settings must be configured during initialization and cannot be changed after the object is created.
+
+## Detailed Telemetry Events
+
+### Computer SDK Events
+
+| Event Name | Data Collected | Trigger Notes |
+|------------|----------------|---------------|
+| **computer_initialized** | • `os`: Operating system (e.g., 'windows', 'darwin', 'linux')
+ {hasAnyPlatform && (
+
+ {windows && (
+
+ Windows
+
+ )}
+ {macos && (
+
+ macOS
+
+ )}
+ {linux && (
+
+ Linux
+
+ )}
+
+ )}
+
+
+ {pypi && (
+
+
+ )}
+ {npm && (
+
+
+ )}
+
+
+
+
+ {github &&
+ github.length > 0 &&
+ (github.length === 1 ? (
+
+
+
+ Source
+
+ ) : (
+
+
+
+
+ Source
+
+
+
+
+
+ ))}
+ {slug.includes('libraries') && (
+
+
+ )}
+
+
+
+
+
+
+
{page.data.title}
+
+
+ {apiSection && versionItems.length > 1 && (
+
+
+ {(() => {
+ // Find the current version label
+ let currentLabel = 'Current';
+ if (apiVersionSlug.length > 0) {
+ const found = versionItems.find(
+ (item) =>
+ item.label !== 'Current' &&
+ apiVersionSlug[0] === item.label
+ );
+ if (found) currentLabel = found.label;
+ }
+ return (
+ <>
+ API Version: {currentLabel}
+
+
+ {versionItems.map((item) => {
+ // Build the href for each version
+ const href =
+ item.label === 'Current'
+ ? `/api/${apiSection}`
+ : `/api/${apiSection}/${item.label}`;
+ // Highlight current version
+ const isCurrent =
+ (item.label === 'Current' &&
+ apiVersionSlug.length === 0) ||
+ (item.label !== 'Current' &&
+ apiVersionSlug[0] === item.label);
+ return (
+
+
+ )}
+
+
+
+ {page.data.description}
+
+
+
+
+
+ );
+}
+
+export async function generateStaticParams() {
+ return source.generateParams();
+}
+
+export async function generateMetadata(props: {
+ params: Promise<{ slug?: string[] }>;
+}): Promise {
+ const params = await props.params;
+ const page = source.getPage(params.slug);
+ if (!page) notFound();
+
+ let title = `${page.data.title} | Cua Docs`;
+ if (page.url.includes('api')) title = `${page.data.title} | Cua API Docs`;
+ if (page.url.includes('guide'))
+ title = ` Guide: ${page.data.title} | Cua Docs`;
+
+ return {
+ title,
+ description: page.data.description,
+ openGraph: {
+ title,
+ description: page.data.description,
+ type: 'article',
+ siteName: 'Cua Docs',
+ url: 'https://trycua.com/docs',
+ },
+ };
+}
diff --git a/docs/src/app/(home)/layout.tsx b/docs/src/app/(home)/layout.tsx
new file mode 100644
index 00000000..f73f4f1d
--- /dev/null
+++ b/docs/src/app/(home)/layout.tsx
@@ -0,0 +1,12 @@
+import { baseOptions } from '@/app/layout.config';
+import { source } from '@/lib/source';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { ReactNode } from 'react';
+
+export default function Layout({ children }: { children: ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
diff --git a/docs/src/app/api/search/route.ts b/docs/src/app/api/search/route.ts
new file mode 100644
index 00000000..df889626
--- /dev/null
+++ b/docs/src/app/api/search/route.ts
@@ -0,0 +1,4 @@
+import { source } from '@/lib/source';
+import { createFromSource } from 'fumadocs-core/search/server';
+
+export const { GET } = createFromSource(source);
diff --git a/docs/src/app/favicon.ico b/docs/src/app/favicon.ico
new file mode 100644
index 00000000..dd75e7d8
Binary files /dev/null and b/docs/src/app/favicon.ico differ
diff --git a/docs/src/app/global.css b/docs/src/app/global.css
new file mode 100644
index 00000000..50b3bc29
--- /dev/null
+++ b/docs/src/app/global.css
@@ -0,0 +1,3 @@
+@import 'tailwindcss';
+@import 'fumadocs-ui/css/neutral.css';
+@import 'fumadocs-ui/css/preset.css';
diff --git a/docs/src/app/layout.config.tsx b/docs/src/app/layout.config.tsx
new file mode 100644
index 00000000..f29509bd
--- /dev/null
+++ b/docs/src/app/layout.config.tsx
@@ -0,0 +1,74 @@
+import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+
+import Image from 'next/image';
+import LogoBlack from '@/assets/logo-black.svg';
+import LogoWhite from '@/assets/logo-white.svg';
+import DiscordWhite from '@/assets/discord-white.svg';
+import DiscordBlack from '@/assets/discord-black.svg';
+import { HomeIcon } from 'lucide-react';
+
+/**
+ * Shared layout configurations
+ *
+ * you can customise layouts individually from:
+ * Home Layout: app/(home)/layout.tsx
+ * Docs Layout: app/docs/layout.tsx
+ */
+export const baseOptions: BaseLayoutProps = {
+ nav: {
+ title: (
+ <>
+ {children}
+
+
+ );
+}
diff --git a/docs/src/app/llms.mdx/[[...slug]]/route.ts b/docs/src/app/llms.mdx/[[...slug]]/route.ts
new file mode 100644
index 00000000..15b8e678
--- /dev/null
+++ b/docs/src/app/llms.mdx/[[...slug]]/route.ts
@@ -0,0 +1,21 @@
+import { type NextRequest, NextResponse } from 'next/server';
+import { getLLMText } from '@/lib/llms';
+import { source } from '@/lib/source';
+import { notFound } from 'next/navigation';
+
+export const revalidate = false;
+
+export async function GET(
+ _req: NextRequest,
+ { params }: { params: Promise<{ slug?: string[] }> }
+) {
+ const { slug } = await params;
+ const page = source.getPage(slug);
+ if (!page) notFound();
+
+ return new NextResponse(await getLLMText(page));
+}
+
+export function generateStaticParams() {
+ return source.generateParams();
+}
diff --git a/docs/src/app/llms.txt/route.ts b/docs/src/app/llms.txt/route.ts
new file mode 100644
index 00000000..5c913bf1
--- /dev/null
+++ b/docs/src/app/llms.txt/route.ts
@@ -0,0 +1,12 @@
+import { source } from '@/lib/source';
+import { getLLMText } from '@/lib/llms';
+
+// cached forever
+export const revalidate = false;
+
+export async function GET() {
+ const scan = source.getPages().map(getLLMText);
+ const scanned = await Promise.all(scan);
+
+ return new Response(scanned.join('\n\n'));
+}
diff --git a/docs/src/assets/discord-black.svg b/docs/src/assets/discord-black.svg
new file mode 100644
index 00000000..c3b16e5e
--- /dev/null
+++ b/docs/src/assets/discord-black.svg
@@ -0,0 +1 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/src/assets/logo-white.svg b/docs/src/assets/logo-white.svg
new file mode 100644
index 00000000..ec40ab17
--- /dev/null
+++ b/docs/src/assets/logo-white.svg
@@ -0,0 +1,49 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/src/components/iou.tsx b/docs/src/components/iou.tsx
new file mode 100644
index 00000000..275f2c4d
--- /dev/null
+++ b/docs/src/components/iou.tsx
@@ -0,0 +1,106 @@
+'use client';
+import React, { useRef, useEffect, useState, useCallback } from 'react';
+
+interface Rectangle {
+ left: number;
+ top: number;
+ width: number;
+ height: number;
+ fill: string;
+ name: string;
+}
+
+interface IOUProps {
+ title: string;
+ description: string;
+ rect1: Rectangle;
+ rect2: Rectangle;
+}
+
+export default function IOU({ title, description, rect1, rect2 }: IOUProps) {
+ const canvasRef = useRef(null);
+ const [actualIOU, setActualIOU] = useState(0);
+
+ const getBbox = (rect: Rectangle) => ({
+ left: rect.left,
+ right: rect.left + rect.width,
+ top: rect.top,
+ bottom: rect.top + rect.height,
+ });
+
+ const calcIntersection = (bbox1: any, bbox2: any): number => {
+ const x1 = Math.max(bbox1.left, bbox2.left);
+ const x2 = Math.min(bbox1.right, bbox2.right);
+ const y1 = Math.max(bbox1.top, bbox2.top);
+ const y2 = Math.min(bbox1.bottom, bbox2.bottom);
+
+ // Check if there's actually an overlap
+ if (x2 <= x1 || y2 <= y1) {
+ return 0;
+ }
+
+ const intersection = (x2 - x1) * (y2 - y1);
+ return intersection;
+ };
+
+ const calcArea = (rect: Rectangle): number => {
+ return rect.width * rect.height;
+ };
+
+ const drawCanvas = useCallback(() => {
+ const canvas = canvasRef.current;
+ if (!canvas) return;
+
+ const ctx = canvas.getContext('2d');
+ if (!ctx) return;
+
+ // Clear canvas
+ ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+ // Calculate IOU
+ const bbox1 = getBbox(rect1);
+ const bbox2 = getBbox(rect2);
+ const intersection = calcIntersection(bbox1, bbox2);
+ const union = calcArea(rect1) + calcArea(rect2) - intersection;
+ const iou = intersection / union;
+ setActualIOU(iou);
+
+ // Draw rectangles
+ [rect1, rect2].forEach((rect) => {
+ ctx.fillStyle = rect.fill;
+ ctx.fillRect(rect.left, rect.top, rect.width, rect.height);
+
+ ctx.strokeStyle = '#000';
+ ctx.lineWidth = 2;
+ ctx.strokeRect(rect.left, rect.top, rect.width, rect.height);
+
+ ctx.fillStyle = '#000';
+ ctx.font = '12px';
+ ctx.fillText(rect.name, rect.left + 5, rect.top + 15);
+ });
+ }, [rect1, rect2]);
+
+ useEffect(() => {
+ drawCanvas();
+ }, [drawCanvas]);
+
+ return (
+
+
{title}
+
+
+
+
+
IOU = {actualIOU.toFixed(3)}
+
{description}
+
+
+
+
(null);
+ const currentChartRef = useRef(null);
+ const { resolvedTheme } = useTheme();
+
+ useEffect(() => {
+ if (currentChartRef.current === chart || !containerRef.current) return;
+ const container = containerRef.current;
+ currentChartRef.current = chart;
+
+ async function renderChart() {
+ const { default: mermaid } = await import('mermaid');
+
+ try {
+ // configure mermaid
+ mermaid.initialize({
+ startOnLoad: false,
+ securityLevel: 'loose',
+ fontFamily: 'inherit',
+ themeCSS: 'margin: 1.5rem auto 0;',
+ theme: resolvedTheme === 'dark' ? 'dark' : 'default',
+ });
+
+ const { svg, bindFunctions } = await mermaid.render(
+ id,
+ chart.replaceAll('\\n', '\n'),
+ );
+
+ bindFunctions?.(container);
+ setSvg(svg);
+ } catch (error) {
+ console.error('Error while rendering mermaid', error);
+ }
+ }
+
+ void renderChart();
+ }, [chart, id, resolvedTheme]);
+
+ return
;
+}
\ No newline at end of file
diff --git a/docs/src/lib/llms.ts b/docs/src/lib/llms.ts
new file mode 100644
index 00000000..e485bed2
--- /dev/null
+++ b/docs/src/lib/llms.ts
@@ -0,0 +1,26 @@
+import { remark } from 'remark';
+import remarkGfm from 'remark-gfm';
+import remarkMdx from 'remark-mdx';
+import { remarkInclude } from 'fumadocs-mdx/config';
+import { source } from '@/lib/source';
+import type { InferPageType } from 'fumadocs-core/source';
+
+const processor = remark()
+ .use(remarkMdx)
+ // needed for Fumadocs MDX
+ .use(remarkInclude)
+ .use(remarkGfm);
+
+export async function getLLMText(page: InferPageType) {
+ const processed = await processor.process({
+ path: page.data._file.absolutePath,
+ value: page.data.content,
+ });
+
+ return `# ${page.data.title}
+URL: ${page.url}
+
+${page.data.description}
+
+${processed.value}`;
+}
diff --git a/docs/src/lib/source.ts b/docs/src/lib/source.ts
new file mode 100644
index 00000000..a202cf80
--- /dev/null
+++ b/docs/src/lib/source.ts
@@ -0,0 +1,52 @@
+import { docs } from '@/.source';
+import { loader } from 'fumadocs-core/source';
+import { icons } from 'lucide-react';
+import { createElement } from 'react';
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Returns available API doc versions for a given section (e.g., 'agent').
+ * Each version is an object: { label, slug }
+ * - 'Current' (index.mdx) → slug: []
+ * - '[version].mdx' → slug: [version]
+ */
+export async function getApiVersions(
+ section: string
+): Promise<{ label: string; slug: string[] }[]> {
+ const dir = path.join(process.cwd(), 'content/docs/api', section);
+ let files: string[] = [];
+ try {
+ files = (await fs.readdir(dir)).filter((f) => f.endsWith('.mdx'));
+ } catch (_e) {
+ return [];
+ }
+ const versions = files.map((file) => {
+ if (file === 'index.mdx') {
+ return { label: 'Current', slug: [] };
+ }
+ const version = file.replace(/\.mdx$/, '');
+ return { label: version, slug: [version] };
+ });
+ // Always put 'Current' first, then others sorted descending (semver-ish)
+ return [
+ ...versions.filter((v) => v.label === 'Current'),
+ ...versions
+ .filter((v) => v.label !== 'Current')
+ .sort((a, b) =>
+ b.label.localeCompare(a.label, undefined, { numeric: true })
+ ),
+ ];
+}
+
+// See https://fumadocs.vercel.app/docs/headless/source-api for more info
+export const source = loader({
+ // it assigns a URL to your pages
+ baseUrl: '/',
+ source: docs.toFumadocsSource(),
+ icon(icon) {
+ if (!icon) return;
+ if (icon in icons) return createElement(icons[icon as keyof typeof icons]);
+ },
+});
diff --git a/docs/src/mdx-components.tsx b/docs/src/mdx-components.tsx
new file mode 100644
index 00000000..3b27cf8c
--- /dev/null
+++ b/docs/src/mdx-components.tsx
@@ -0,0 +1,16 @@
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import * as TabsComponents from 'fumadocs-ui/components/tabs';
+import type { MDXComponents } from 'mdx/types';
+import { Mermaid } from './components/mermaid';
+import IOU from './components/iou';
+
+// use this function to get MDX components, you will need it for rendering MDX
+export function getMDXComponents(components?: MDXComponents): MDXComponents {
+ return {
+ ...defaultMdxComponents,
+ Mermaid,
+ IOU,
+ ...TabsComponents,
+ ...components,
+ };
+}
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
new file mode 100644
index 00000000..504b2911
--- /dev/null
+++ b/docs/tsconfig.json
@@ -0,0 +1,45 @@
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true,
+ "paths": {
+ "@/.source": [
+ "./.source/index.ts"
+ ],
+ "@/*": [
+ "./src/*"
+ ]
+ },
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
+ },
+ "include": [
+ "next-env.d.ts",
+ "**/*.ts",
+ "**/*.tsx",
+ ".next/types/**/*.ts"
+ ],
+ "exclude": [
+ "node_modules"
+ ]
+}
\ No newline at end of file
diff --git a/examples/agent_examples.py b/examples/agent_examples.py
index d6a565bf..4d211f7f 100644
--- a/examples/agent_examples.py
+++ b/examples/agent_examples.py
@@ -29,7 +29,7 @@ async def run_agent_example():
verbosity=logging.DEBUG,
)
- # Create a remote Linux computer with C/ua
+ # Create a remote Linux computer with Cua
# computer = Computer(
# os_type="linux",
# api_key=os.getenv("CUA_API_KEY"),
diff --git a/examples/agent_ui_examples.py b/examples/agent_ui_examples.py
index d5a37119..97f54856 100644
--- a/examples/agent_ui_examples.py
+++ b/examples/agent_ui_examples.py
@@ -13,7 +13,7 @@ from utils import load_dotenv_files
load_dotenv_files()
# Import the create_gradio_ui function
-from agent.ui.gradio.app import create_gradio_ui
+from agent.ui.gradio.ui_components import create_gradio_ui
if __name__ == "__main__":
print("Launching Computer-Use Agent Gradio UI with advanced features...")
diff --git a/examples/computer-example-ts/README.md b/examples/computer-example-ts/README.md
index 1e61eab0..935588aa 100644
--- a/examples/computer-example-ts/README.md
+++ b/examples/computer-example-ts/README.md
@@ -1,10 +1,10 @@
# cua-cloud-openai Example
-This example demonstrates how to control a c/ua Cloud container using the OpenAI `computer-use-preview` model and the `@trycua/computer` TypeScript library.
+This example demonstrates how to control a cua Cloud container using the OpenAI `computer-use-preview` model and the `@trycua/computer` TypeScript library.
## Overview
-- Connects to a c/ua Cloud container via the `@trycua/computer` library
+- Connects to a cua Cloud container via the `@trycua/computer` library
- Sends screenshots and instructions to OpenAI's computer-use model
- Executes AI-generated actions (clicks, typing, etc.) inside the container
- Designed for Linux containers, but can be adapted for other OS types
@@ -20,7 +20,7 @@ This example demonstrates how to control a c/ua Cloud container using the OpenAI
2. **Set up environment variables:**
Create a `.env` file with the following variables:
- `OPENAI_KEY` — your OpenAI API key
- - `CUA_KEY` — your c/ua Cloud API key
+ - `CUA_KEY` — your cua Cloud API key
- `CUA_CONTAINER_NAME` — the name of your provisioned container
3. **Run the example:**
@@ -38,7 +38,7 @@ This example demonstrates how to control a c/ua Cloud container using the OpenAI
For a step-by-step tutorial and more detailed explanation, see the accompanying blog post:
-➡️ [Controlling a c/ua Cloud Container with JavaScript](https://placeholder-url-to-blog-post.com)
+➡️ [Controlling a cua Cloud Container with JavaScript](https://placeholder-url-to-blog-post.com)
_(This link will be updated once the article is published.)_
diff --git a/examples/computer_examples.py b/examples/computer_examples.py
index 227beb8c..bb9e7ad9 100644
--- a/examples/computer_examples.py
+++ b/examples/computer_examples.py
@@ -43,7 +43,7 @@ async def main():
ephemeral=False,
)
- # Create a remote Linux computer with C/ua
+ # Create a remote Linux computer with Cua
# computer = Computer(
# os_type="linux",
# api_key=os.getenv("CUA_API_KEY"),
diff --git a/examples/sandboxed_functions_examples.py b/examples/sandboxed_functions_examples.py
index caa733b9..93d93021 100644
--- a/examples/sandboxed_functions_examples.py
+++ b/examples/sandboxed_functions_examples.py
@@ -22,7 +22,7 @@ from computer.computer import Computer
from computer.helpers import sandboxed
async def main():
- # Initialize the computer in a C/ua Container
+ # Initialize the computer in a Cua Container
computer = Computer()
await computer.run()
@@ -34,7 +34,7 @@ async def main():
await asyncio.sleep(2)
# Define a sandboxed function
- # This function will run inside the C/ua Container
+ # This function will run inside the Cua Container
@sandboxed("demo_venv")
def greet_and_print(name):
# get .html of the current Safari tab
@@ -47,7 +47,7 @@ async def main():
return {"greeted": name, "safari_html_length": len(html), "safari_html_snippet": html[:200]}
# Call with args and kwargs
- result = await greet_and_print("C/ua")
+ result = await greet_and_print("Cua")
print("Result from sandboxed function:", result)
if __name__ == "__main__":
diff --git a/libs/python/agent/agent/adapters/huggingfacelocal_adapter.py b/libs/python/agent/agent/adapters/huggingfacelocal_adapter.py
index 5692401d..e8281114 100644
--- a/libs/python/agent/agent/adapters/huggingfacelocal_adapter.py
+++ b/libs/python/agent/agent/adapters/huggingfacelocal_adapter.py
@@ -8,7 +8,7 @@ from litellm import completion, acompletion
# Try to import HuggingFace dependencies
try:
import torch
- from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessor
+ from transformers import AutoModelForImageTextToText, AutoProcessor
HF_AVAILABLE = True
except ImportError:
HF_AVAILABLE = False
@@ -40,7 +40,7 @@ class HuggingFaceLocalAdapter(CustomLLM):
"""
if model_name not in self.models:
# Load model
- model = Qwen2_5_VLForConditionalGeneration.from_pretrained(
+ model = AutoModelForImageTextToText.from_pretrained(
model_name,
torch_dtype=torch.float16,
device_map=self.device,
@@ -145,8 +145,7 @@ class HuggingFaceLocalAdapter(CustomLLM):
)
# Move inputs to the same device as model
- if torch.cuda.is_available() and self.device != "cpu":
- inputs = inputs.to("cuda")
+ inputs = inputs.to(model.device)
# Generate response
with torch.no_grad():
diff --git a/libs/python/agent/agent/agent.py b/libs/python/agent/agent/agent.py
index 06f617c2..79a4b9a6 100644
--- a/libs/python/agent/agent/agent.py
+++ b/libs/python/agent/agent/agent.py
@@ -422,6 +422,9 @@ class ComputerAgent:
# Perform computer actions
action = item.get("action")
action_type = action.get("type")
+ if action_type is None:
+ print(f"Action type cannot be `None`: action={action}, action_type={action_type}")
+ return []
# Extract action arguments (all fields except 'type')
action_args = {k: v for k, v in action.items() if k != "type"}
diff --git a/libs/python/agent/agent/callbacks/pii_anonymization.py b/libs/python/agent/agent/callbacks/pii_anonymization.py
index 592b7273..68f4b2fc 100644
--- a/libs/python/agent/agent/callbacks/pii_anonymization.py
+++ b/libs/python/agent/agent/callbacks/pii_anonymization.py
@@ -93,4 +93,4 @@ class PIIAnonymizationCallback(AsyncCallbackHandler):
async def _deanonymize_item(self, item: Dict[str, Any]) -> Dict[str, Any]:
# TODO: Implement _deanonymize_item
- return item
\ No newline at end of file
+ return item
diff --git a/libs/python/agent/agent/ui/gradio/app.py b/libs/python/agent/agent/ui/gradio/app.py
index 13c0786f..be04d931 100644
--- a/libs/python/agent/agent/ui/gradio/app.py
+++ b/libs/python/agent/agent/ui/gradio/app.py
@@ -178,13 +178,20 @@ def create_computer_instance(
"""Create or get the global Computer instance."""
global global_computer
if global_computer is None:
- global_computer = Computer(
- verbosity=verbosity,
- os_type=os_type,
- provider_type=provider_type,
- name=name if name else "",
- api_key=api_key
- )
+ if provider_type == "localhost":
+ global_computer = Computer(
+ verbosity=verbosity,
+ os_type=os_type,
+ use_host_computer_server=True
+ )
+ else:
+ global_computer = Computer(
+ verbosity=verbosity,
+ os_type=os_type,
+ provider_type=provider_type,
+ name=name if name else "",
+ api_key=api_key
+ )
return global_computer
diff --git a/libs/python/agent/agent/ui/gradio/ui_components.py b/libs/python/agent/agent/ui/gradio/ui_components.py
index dfcceb4e..c601fb6c 100644
--- a/libs/python/agent/agent/ui/gradio/ui_components.py
+++ b/libs/python/agent/agent/ui/gradio/ui_components.py
@@ -211,7 +211,7 @@ if __name__ == "__main__":
is_windows = platform.system().lower() == "windows"
is_mac = platform.system().lower() == "darwin"
- providers = ["cloud"]
+ providers = ["cloud", "localhost"]
if is_mac:
providers += ["lume"]
if is_windows:
@@ -403,6 +403,23 @@ if __name__ == "__main__":
type="password",
)
+ # Provider visibility update function
+ def update_provider_visibility(provider):
+ """Update visibility of container name and API key based on selected provider."""
+ is_localhost = provider == "localhost"
+ return [
+ gr.update(visible=not is_localhost), # container_name
+ gr.update(visible=not is_localhost and not has_cua_key) # cua_cloud_api_key
+ ]
+
+ # Connect provider change event
+ computer_provider.change(
+ fn=update_provider_visibility,
+ inputs=[computer_provider],
+ outputs=[container_name, cua_cloud_api_key],
+ queue=False
+ )
+
# Connect UI update events
for dropdown in [agent_loop, omni_model_choice, uitars_model_choice, openai_model_choice, anthropic_model_choice]:
dropdown.change(
diff --git a/libs/python/agent/pyproject.toml b/libs/python/agent/pyproject.toml
index 232aaa48..75f8159a 100644
--- a/libs/python/agent/pyproject.toml
+++ b/libs/python/agent/pyproject.toml
@@ -19,7 +19,7 @@ dependencies = [
"pydantic>=2.6.4",
"rich>=13.7.1",
"python-dotenv>=1.0.1",
- "cua-computer>=0.3.0,<0.5.0",
+ "cua-computer>=0.4.0,<0.5.0",
"cua-core>=0.1.8,<0.2.0",
"certifi>=2024.2.2",
"litellm>=1.74.12"
diff --git a/libs/python/computer/computer/ui/gradio/app.py b/libs/python/computer/computer/ui/gradio/app.py
index 8c3708db..d8c5c513 100644
--- a/libs/python/computer/computer/ui/gradio/app.py
+++ b/libs/python/computer/computer/ui/gradio/app.py
@@ -302,7 +302,7 @@ def upload_to_huggingface(dataset_name, visibility, filter_tags=None):
)
card = DatasetCard.from_template(
card_data=card_data,
- template_str="---\n{{ card_data }}\n---\n\n# Uploaded computer interface trajectories\n\nThese trajectories were generated and uploaded using [c/ua](https://github.com/trycua/cua)"
+ template_str="---\n{{ card_data }}\n---\n\n# Uploaded computer interface trajectories\n\nThese trajectories were generated and uploaded using [cua](https://github.com/trycua/cua)"
)
card.push_to_hub(
dataset_name,
diff --git a/libs/python/computer/pyproject.toml b/libs/python/computer/pyproject.toml
index 2e564fa9..4a9b41bb 100644
--- a/libs/python/computer/pyproject.toml
+++ b/libs/python/computer/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "pdm.backend"
[project]
name = "cua-computer"
-version = "0.3.0"
+version = "0.4.0"
description = "Computer-Use Interface (CUI) framework powering Cua"
readme = "README.md"
authors = [
diff --git a/libs/python/mcp-server/README.md b/libs/python/mcp-server/README.md
index 3f3c8bbb..a94da8a7 100644
--- a/libs/python/mcp-server/README.md
+++ b/libs/python/mcp-server/README.md
@@ -16,6 +16,21 @@
**cua-mcp-server** is a MCP server for the Computer-Use Agent (CUA), allowing you to run CUA through Claude Desktop or other MCP clients.
+
+## 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-3-5-sonnet-20241022"`
+- **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"`
+
### Get started with Agent
## Prerequisites
@@ -65,10 +80,7 @@ You can then use the script in your MCP configuration like this:
"command": "/bin/bash",
"args": ["~/.cua/start_mcp_server.sh"],
"env": {
- "CUA_AGENT_LOOP": "OMNI",
- "CUA_MODEL_PROVIDER": "ANTHROPIC",
- "CUA_MODEL_NAME": "claude-3-7-sonnet-20250219",
- "CUA_PROVIDER_API_KEY": "your-api-key"
+ "CUA_MODEL_NAME": "anthropic/claude-3-5-sonnet-20241022"
}
}
}
@@ -86,11 +98,7 @@ If you want to develop with the cua-mcp-server directly without installation, yo
"command": "/bin/bash",
"args": ["~/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"],
"env": {
- "CUA_AGENT_LOOP": "UITARS",
- "CUA_MODEL_PROVIDER": "OAICOMPAT",
- "CUA_MODEL_NAME": "ByteDance-Seed/UI-TARS-1.5-7B",
- "CUA_PROVIDER_BASE_URL": "https://****************.us-east-1.aws.endpoints.huggingface.cloud/v1",
- "CUA_PROVIDER_API_KEY": "your-api-key"
+ "CUA_MODEL_NAME": "huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B"
}
}
}
@@ -142,10 +150,7 @@ The server is configured using environment variables (can be set in the Claude D
| Variable | Description | Default |
|----------|-------------|---------|
-| `CUA_AGENT_LOOP` | Agent loop to use (OPENAI, ANTHROPIC, UITARS, OMNI) | OMNI |
-| `CUA_MODEL_PROVIDER` | Model provider (ANTHROPIC, OPENAI, OLLAMA, OAICOMPAT) | ANTHROPIC |
-| `CUA_MODEL_NAME` | Model name to use | None (provider default) |
-| `CUA_PROVIDER_BASE_URL` | Base URL for provider API | None |
+| `CUA_MODEL_NAME` | Model string (e.g., "anthropic/claude-3-5-sonnet-20241022", "openai/computer-use-preview", "huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B", "omniparser+litellm/gpt-4o", "omniparser+ollama_chat/gemma3") | anthropic/claude-3-5-sonnet-20241022 |
| `CUA_MAX_IMAGES` | Maximum number of images to keep in context | 3 |
## Available Tools
diff --git a/libs/python/mcp-server/mcp_server/server.py b/libs/python/mcp-server/mcp_server/server.py
index 03971cb6..73996d5e 100644
--- a/libs/python/mcp-server/mcp_server/server.py
+++ b/libs/python/mcp-server/mcp_server/server.py
@@ -3,6 +3,7 @@ import base64
import logging
import os
import sys
+from tabnanny import verbose
import traceback
from typing import Any, Dict, List, Optional, Union, Tuple
@@ -28,7 +29,7 @@ except ImportError as e:
try:
from computer import Computer
- from agent import ComputerAgent, LLMProvider, LLM, AgentLoop
+ from agent import ComputerAgent
logger.debug("Successfully imported Computer and Agent modules")
except ImportError as e:
@@ -92,49 +93,27 @@ def serve() -> FastMCP:
global_computer = Computer(verbosity=logging.INFO)
await global_computer.run()
- # Determine which loop to use
- loop_str = os.getenv("CUA_AGENT_LOOP", "OMNI")
- loop = getattr(AgentLoop, loop_str)
+ # Get model name - this now determines the loop and provider
+ model_name = os.getenv("CUA_MODEL_NAME", "anthropic/claude-3-5-sonnet-20241022")
+
+ logger.info(f"Using model: {model_name}")
- # Determine provider
- provider_str = os.getenv("CUA_MODEL_PROVIDER", "ANTHROPIC")
- provider = getattr(LLMProvider, provider_str)
-
- # Get model name (if specified)
- model_name = os.getenv("CUA_MODEL_NAME", None)
-
- # Get base URL for provider (if needed)
- provider_base_url = os.getenv("CUA_PROVIDER_BASE_URL", None)
-
- # Get api key for provider (if needed)
- api_key = os.getenv("CUA_PROVIDER_API_KEY", None)
-
- # Create agent with the specified configuration
+ # Create agent with the new v0.4.x API
agent = ComputerAgent(
- computer=global_computer,
- loop=loop,
- model=LLM(
- provider=provider,
- name=model_name,
- provider_base_url=provider_base_url,
- ),
- api_key=api_key,
- save_trajectory=False,
+ model=model_name,
only_n_most_recent_images=int(os.getenv("CUA_MAX_IMAGES", "3")),
verbosity=logging.INFO,
+ tools=[global_computer]
)
+ # Create messages in the new v0.4.x format
+ messages = [{"role": "user", "content": task}]
+
# Collect all results
full_result = ""
- async for result in agent.run(task):
- logger.info(f"Agent step complete: {result.get('id', 'unknown')}")
- ctx.info(f"Agent step complete: {result.get('id', 'unknown')}")
-
- # Add response ID to output
- full_result += f"\n[Response ID: {result.get('id', 'unknown')}]\n"
-
- if "content" in result:
- full_result += f"Response: {result.get('content', '')}\n"
+ async for result in agent.run(messages):
+ logger.info(f"Agent processing step")
+ ctx.info(f"Agent processing step")
# Process output if available
outputs = result.get("output", [])
@@ -145,25 +124,23 @@ def serve() -> FastMCP:
content = output.get("content", [])
for content_part in content:
if content_part.get("text"):
- full_result += f"\nMessage: {content_part.get('text', '')}\n"
- elif output_type == "reasoning":
- logger.debug(f"Reasoning: {output}")
-
- summary_content = output.get("summary", [])
- if summary_content:
- for summary_part in summary_content:
- if summary_part.get("text"):
- full_result += f"\nReasoning: {summary_part.get('text', '')}\n"
+ full_result += f"Message: {content_part.get('text', '')}\n"
+ elif output_type == "tool_use":
+ logger.debug(f"Tool use: {output}")
+ tool_name = output.get("name", "")
+ full_result += f"Tool: {tool_name}\n"
+ elif output_type == "tool_result":
+ logger.debug(f"Tool result: {output}")
+ result_content = output.get("content", "")
+ if isinstance(result_content, list):
+ for item in result_content:
+ if item.get("type") == "text":
+ full_result += f"Result: {item.get('text', '')}\n"
else:
- full_result += f"\nReasoning: {output.get('text', output.get('content', ''))}\n"
- elif output_type == "computer_call":
- logger.debug(f"Computer call: {output}")
- action = output.get("action", "")
- result_value = output.get("result", "")
- full_result += f"\nComputer Action: {action}\nResult: {result_value}\n"
+ full_result += f"Result: {result_content}\n"
# Add separator between steps
- full_result += "\n" + "-" * 40 + "\n"
+ full_result += "\n" + "-" * 20 + "\n"
logger.info(f"CUA task completed successfully")
ctx.info(f"CUA task completed successfully")
@@ -179,7 +156,21 @@ def serve() -> FastMCP:
error_msg = f"Error running CUA task: {str(e)}\n{traceback.format_exc()}"
logger.error(error_msg)
ctx.error(error_msg)
- return f"Error during task execution: {str(e)}"
+ # Return tuple with error message and a screenshot if possible
+ try:
+ if global_computer is not None:
+ screenshot = await global_computer.interface.screenshot()
+ return (
+ f"Error during task execution: {str(e)}",
+ Image(format="png", data=screenshot)
+ )
+ except:
+ pass
+ # If we can't get a screenshot, return a placeholder
+ return (
+ f"Error during task execution: {str(e)}",
+ Image(format="png", data=b"")
+ )
@server.tool()
async def run_multi_cua_tasks(ctx: Context, tasks: List[str]) -> List:
diff --git a/libs/python/mcp-server/pyproject.toml b/libs/python/mcp-server/pyproject.toml
index ed2ad435..f80a1b6b 100644
--- a/libs/python/mcp-server/pyproject.toml
+++ b/libs/python/mcp-server/pyproject.toml
@@ -13,8 +13,8 @@ authors = [
]
dependencies = [
"mcp>=1.6.0,<2.0.0",
- "cua-agent[all]>=0.3.0,<0.4.0",
- "cua-computer>=0.3.0,<0.4.0",
+ "cua-agent[all]>=0.4.0,<0.5.0",
+ "cua-computer>=0.4.0,<0.5.0",
]
[project.scripts]
diff --git a/libs/typescript/README.md b/libs/typescript/README.md
index 78fda2e7..9474f49d 100644
--- a/libs/typescript/README.md
+++ b/libs/typescript/README.md
@@ -1,6 +1,6 @@
-# C/UA TypeScript Libraries
+# CUA TypeScript Libraries
-This repository contains TypeScript implementations of the C/UA libraries:
+This repository contains TypeScript implementations of the CUA libraries:
- `@trycua/core`: Core functionality including telemetry and logging
- `@trycua/computer`: Computer interaction SDK for VM management and control
@@ -90,7 +90,7 @@ pnpm lint:fix:all
### @trycua/core
-Core functionality for C/UA libraries including:
+Core functionality for CUA libraries including:
- Telemetry with PostHog integration
- Common utilities and types
diff --git a/libs/typescript/computer/LICENSE b/libs/typescript/computer/LICENSE
index 7ff04379..0d9333db 100644
--- a/libs/typescript/computer/LICENSE
+++ b/libs/typescript/computer/LICENSE
@@ -1,6 +1,6 @@
The MIT License (MIT)
-Copyright © 2025 C/UA
+Copyright © 2025 CUA
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/libs/typescript/computer/README.md b/libs/typescript/computer/README.md
index a9d42740..b51713c2 100644
--- a/libs/typescript/computer/README.md
+++ b/libs/typescript/computer/README.md
@@ -1,4 +1,4 @@
-# C/ua Computer TypeScript Library
+# Cua Computer TypeScript Library
The TypeScript library for C/cua Computer - a powerful computer control and automation library.
@@ -87,4 +87,4 @@ pnpm typecheck
## License
-[MIT](./LICENSE) License 2025 [C/UA](https://github.com/trycua)
+[MIT](./LICENSE) License 2025 [CUA](https://github.com/trycua)
diff --git a/libs/typescript/computer/package.json b/libs/typescript/computer/package.json
index ba9c0934..b9d3b76e 100644
--- a/libs/typescript/computer/package.json
+++ b/libs/typescript/computer/package.json
@@ -2,7 +2,7 @@
"name": "@trycua/computer",
"version": "0.1.3",
"packageManager": "pnpm@10.11.0",
- "description": "Typescript SDK for c/ua computer interaction",
+ "description": "Typescript SDK for cua computer interaction",
"type": "module",
"license": "MIT",
"homepage": "https://github.com/trycua/cua/tree/feature/computer/typescript/libs/typescript/computer",
@@ -13,7 +13,7 @@
"type": "git",
"url": "git+https://github.com/trycua/cua.git"
},
- "author": "c/ua",
+ "author": "cua",
"files": [
"dist"
],
diff --git a/libs/typescript/core/LICENSE b/libs/typescript/core/LICENSE
index 74987166..93914d8b 100644
--- a/libs/typescript/core/LICENSE
+++ b/libs/typescript/core/LICENSE
@@ -1,6 +1,6 @@
The MIT License (MIT)
-Copyright © 2025 C/ua
+Copyright © 2025 Cua
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/libs/typescript/core/README.md b/libs/typescript/core/README.md
index 20a77b26..bc585ce8 100644
--- a/libs/typescript/core/README.md
+++ b/libs/typescript/core/README.md
@@ -1,6 +1,6 @@
-# C/ua Core TypeScript Library
+# Cua Core TypeScript Library
-The core c/ua library with support for telemetry and other utilities.
+The core cua library with support for telemetry and other utilities.
## Development
@@ -24,4 +24,4 @@ pnpm build
## License
-[MIT](./LICENSE) License 2025 [C/UA](https://github.com/trycua)
+[MIT](./LICENSE) License 2025 [CUA](https://github.com/trycua)
diff --git a/libs/typescript/core/package.json b/libs/typescript/core/package.json
index d15d4138..21b592d9 100644
--- a/libs/typescript/core/package.json
+++ b/libs/typescript/core/package.json
@@ -2,7 +2,7 @@
"name": "@trycua/core",
"version": "0.1.3",
"packageManager": "pnpm@10.11.0",
- "description": "Typescript SDK for c/ua core.",
+ "description": "Typescript SDK for cua core.",
"type": "module",
"license": "MIT",
"homepage": "https://github.com/trycua/cua/tree/feature/computer/typescript/libs/typescript/computer",
@@ -13,7 +13,7 @@
"type": "git",
"url": "git+https://github.com/trycua/cua.git"
},
- "author": "c/ua",
+ "author": "cua",
"files": [
"dist"
],
diff --git a/libs/typescript/package.json b/libs/typescript/package.json
index 0e0d6ce1..76d313ec 100644
--- a/libs/typescript/package.json
+++ b/libs/typescript/package.json
@@ -1,9 +1,9 @@
{
"name": "cua-ts",
"version": "1.0.0",
- "description": "The c/ua typescript libs.",
+ "description": "The cua typescript libs.",
"keywords": [],
- "author": "c/ua",
+ "author": "cua",
"license": "MIT",
"scripts": {
"lint": "biome check",
diff --git a/notebooks/agent_nb.ipynb b/notebooks/agent_nb.ipynb
index ead27655..61e7288a 100644
--- a/notebooks/agent_nb.ipynb
+++ b/notebooks/agent_nb.ipynb
@@ -6,7 +6,7 @@
"source": [
"## Agent\n",
"\n",
- "This notebook demonstrates how to use Cua's Agent to run workflows in virtual sandboxes, either using C/ua Cloud Containers or local VMs on Apple Silicon Macs."
+ "This notebook demonstrates how to use Cua's Agent to run workflows in virtual sandboxes, either using Cua Cloud Containers or local VMs on Apple Silicon Macs."
]
},
{
@@ -103,7 +103,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "## Option 1: Agent with C/ua Cloud Containers\n",
+ "## Option 1: Agent with Cua Cloud Containers\n",
"\n",
"Use cloud containers for running agents from any system without local setup."
]
@@ -114,7 +114,7 @@
"source": [
"### Prerequisites for Cloud Containers\n",
"\n",
- "To use C/ua Cloud Containers, you need to:\n",
+ "To use Cua Cloud Containers, you need to:\n",
"1. Sign up at https://trycua.com\n",
"2. Create a Cloud Container\n",
"3. Generate an API Key\n",
@@ -126,7 +126,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "Get C/ua API credentials and container details"
+ "Get Cua API credentials and container details"
]
},
{
@@ -136,7 +136,7 @@
"outputs": [],
"source": [
"cua_api_key = os.getenv(\"CUA_API_KEY\") or \\\n",
- " input(\"Enter your C/ua API Key: \")\n",
+ " input(\"Enter your Cua API Key: \")\n",
"container_name = os.getenv(\"CONTAINER_NAME\") or \\\n",
" input(\"Enter your Cloud Container name: \")"
]
@@ -379,7 +379,7 @@
"metadata": {},
"outputs": [],
"source": [
- "from agent.ui.gradio.app import create_gradio_ui\n",
+ "from agent.ui.gradio.ui_components import create_gradio_ui\n",
"\n",
"app = create_gradio_ui()\n",
"app.launch(share=False)"
diff --git a/notebooks/blog/build-your-own-operator-on-macos-2.ipynb b/notebooks/blog/build-your-own-operator-on-macos-2.ipynb
index 52bfd883..ba039bfe 100644
--- a/notebooks/blog/build-your-own-operator-on-macos-2.ipynb
+++ b/notebooks/blog/build-your-own-operator-on-macos-2.ipynb
@@ -85,7 +85,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "## Running a c/ua Agent"
+ "## Running a cua Agent"
]
},
{
diff --git a/notebooks/computer_nb.ipynb b/notebooks/computer_nb.ipynb
index c95d37f2..d1d97d12 100644
--- a/notebooks/computer_nb.ipynb
+++ b/notebooks/computer_nb.ipynb
@@ -6,7 +6,7 @@
"source": [
"## Computer\n",
"\n",
- "This notebook demonstrates how to use Computer to operate sandbox VMs programmatically, either using C/ua Cloud Containers or local Lume VMs on Apple Silicon macOS systems."
+ "This notebook demonstrates how to use Computer to operate sandbox VMs programmatically, either using Cua Cloud Containers or local Lume VMs on Apple Silicon macOS systems."
]
},
{
@@ -53,9 +53,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "## Option 1: C/ua Cloud Containers\n",
+ "## Option 1: Cua Cloud Containers\n",
"\n",
- "C/ua Cloud Containers provide remote VMs that can be accessed from any system without local setup."
+ "Cua Cloud Containers provide remote VMs that can be accessed from any system without local setup."
]
},
{
@@ -64,7 +64,7 @@
"source": [
"### Prerequisites for Cloud Containers\n",
"\n",
- "To use C/ua Cloud Containers, you need to:\n",
+ "To use Cua Cloud Containers, you need to:\n",
"1. Sign up at https://trycua.com\n",
"2. Create a Cloud Container\n",
"3. Generate an API Key\n",
@@ -82,7 +82,7 @@
"import os\n",
"\n",
"cua_api_key = os.getenv(\"CUA_API_KEY\") or \\\n",
- " input(\"Enter your C/ua API Key: \")\n",
+ " input(\"Enter your Cua API Key: \")\n",
"container_name = os.getenv(\"CONTAINER_NAME\") or \\\n",
" input(\"Enter your Cloud Container name: \")"
]
@@ -123,7 +123,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "Connect to your existing C/ua Cloud Container"
+ "Connect to your existing Cua Cloud Container"
]
},
{
diff --git a/scripts/playground-docker.sh b/scripts/playground-docker.sh
index 61b57901..5cfae574 100644
--- a/scripts/playground-docker.sh
+++ b/scripts/playground-docker.sh
@@ -26,13 +26,13 @@ print_warning() {
echo -e "${YELLOW}==> $1${NC}"
}
-echo "🚀 Launching C/ua Computer-Use Agent UI..."
+echo "🚀 Launching Cua Computer-Use Agent UI..."
# Check if Docker is installed
if ! command -v docker &> /dev/null; then
print_error "Docker is not installed!"
echo ""
- echo "To use C/ua with Docker containers, you need to install Docker first:"
+ echo "To use Cua with Docker containers, you need to install Docker first:"
echo ""
echo "📦 Install Docker:"
echo " • macOS: Download Docker Desktop from https://docker.com/products/docker-desktop"
@@ -63,7 +63,7 @@ mkdir -p "$DEMO_DIR"
# Check if we're already in the cua repository
# Look for the specific trycua identifier in pyproject.toml
if [[ -f "pyproject.toml" ]] && grep -q "gh@trycua.com" "pyproject.toml"; then
- print_success "Already in C/ua repository - using current directory"
+ print_success "Already in Cua repository - using current directory"
REPO_DIR="$ORIGINAL_DIR"
USE_EXISTING_REPO=true
else
@@ -79,17 +79,17 @@ cleanup() {
trap cleanup EXIT
echo ""
-echo "Choose your C/ua setup:"
-echo "1) ☁️ C/ua Cloud Containers (works on any system)"
+echo "Choose your Cua setup:"
+echo "1) ☁️ Cua Cloud Containers (works on any system)"
echo "2) 🖥️ Local macOS VMs (requires Apple Silicon Mac + macOS 15+)"
echo "3) 🖥️ Local Windows VMs (requires Windows 10 / 11)"
echo ""
read -p "Enter your choice (1, 2, or 3): " CHOICE
if [[ "$CHOICE" == "1" ]]; then
- # C/ua Cloud Container setup
+ # Cua Cloud Container setup
echo ""
- print_info "Setting up C/ua Cloud Containers..."
+ print_info "Setting up Cua Cloud Containers..."
echo ""
# Check if existing .env.local already has CUA_API_KEY
@@ -116,15 +116,15 @@ if [[ "$CHOICE" == "1" ]]; then
# If no valid API key found, prompt for one
if [[ -z "$CUA_API_KEY" ]]; then
- echo "To use C/ua Cloud Containers, you need to:"
+ echo "To use Cua Cloud Containers, you need to:"
echo "1. Sign up at https://trycua.com"
echo "2. Create a Cloud Container"
echo "3. Generate an Api Key"
echo ""
- read -p "Enter your C/ua Api Key: " CUA_API_KEY
+ read -p "Enter your Cua Api Key: " CUA_API_KEY
if [[ -z "$CUA_API_KEY" ]]; then
- print_error "C/ua Api Key is required for Cloud Containers."
+ print_error "Cua Api Key is required for Cloud Containers."
exit 1
fi
else
@@ -142,7 +142,7 @@ elif [[ "$CHOICE" == "2" ]]; then
# Check for Apple Silicon Mac
if [[ $(uname -s) != "Darwin" || $(uname -m) != "arm64" ]]; then
print_error "Local macOS VMs require an Apple Silicon Mac (M1/M2/M3/M4)."
- echo "💡 Consider using C/ua Cloud Containers instead (option 1)."
+ echo "💡 Consider using Cua Cloud Containers instead (option 1)."
exit 1
fi
@@ -150,7 +150,7 @@ elif [[ "$CHOICE" == "2" ]]; then
OSVERSION=$(sw_vers -productVersion)
if [[ $(echo "$OSVERSION 15.0" | tr " " "\n" | sort -V | head -n 1) != "15.0" ]]; then
print_error "Local macOS VMs require macOS 15 (Sequoia) or newer. You have $OSVERSION."
- echo "💡 Consider using C/ua Cloud Containers instead (option 1)."
+ echo "💡 Consider using Cua Cloud Containers instead (option 1)."
exit 1
fi
@@ -165,7 +165,7 @@ elif [[ "$CHOICE" == "3" ]]; then
# Check if we're on Windows
if [[ $(uname -s) != MINGW* && $(uname -s) != CYGWIN* && $(uname -s) != MSYS* ]]; then
print_error "Local Windows VMs require Windows 10 or 11."
- echo "💡 Consider using C/ua Cloud Containers instead (option 1)."
+ echo "💡 Consider using Cua Cloud Containers instead (option 1)."
echo ""
echo "🔗 If you are using WSL, refer to the blog post to get started: https://www.trycua.com/blog/windows-sandbox"
exit 1
@@ -188,11 +188,11 @@ if [[ "$USE_EXISTING_REPO" == "true" ]]; then
else
# Clone or update the repository
if [[ ! -d "$REPO_DIR" ]]; then
- print_info "Cloning C/ua repository..."
+ print_info "Cloning Cua repository..."
cd "$DEMO_DIR"
git clone https://github.com/trycua/cua.git
else
- print_info "Updating C/ua repository..."
+ print_info "Updating Cua repository..."
cd "$REPO_DIR"
git pull origin main
fi
@@ -303,9 +303,9 @@ chmod +x "$DEMO_DIR/start_ui.sh"
print_success "Setup complete!"
if [[ "$USE_CLOUD" == "true" ]]; then
- echo "☁️ C/ua Cloud Container setup complete!"
+ echo "☁️ Cua Cloud Container setup complete!"
else
- echo "🖥️ C/ua Local VM setup complete!"
+ echo "🖥️ Cua Local VM setup complete!"
fi
echo "📝 Edit $ENV_FILE to update your API keys"
@@ -313,10 +313,10 @@ echo "🖥️ Start the playground by running: $DEMO_DIR/start_ui.sh"
# Start the demo automatically
echo
-print_info "Starting the C/ua Computer-Use Agent UI..."
+print_info "Starting the Cua Computer-Use Agent UI..."
echo ""
-print_success "C/ua Computer-Use Agent UI is now running at http://localhost:7860/"
+print_success "Cua Computer-Use Agent UI is now running at http://localhost:7860/"
echo
echo "🌐 Open your browser and go to: http://localhost:7860/"
echo
diff --git a/scripts/playground.sh b/scripts/playground.sh
index 9be712d2..0cde5a25 100755
--- a/scripts/playground.sh
+++ b/scripts/playground.sh
@@ -2,7 +2,7 @@
set -e
-echo "🚀 Launching C/ua Computer-Use Agent UI..."
+echo "🚀 Launching Cua Computer-Use Agent UI..."
# Save the original working directory
ORIGINAL_DIR="$(pwd)"
@@ -22,18 +22,18 @@ TMP_DIR=$(mktemp -d)
cd "$TMP_DIR"
trap cleanup EXIT
-# Ask user to choose between local macOS VMs or C/ua Cloud Containers
+# Ask user to choose between local macOS VMs or Cua Cloud Containers
echo ""
-echo "Choose your C/ua setup:"
-echo "1) ☁️ C/ua Cloud Containers (works on any system)"
+echo "Choose your Cua setup:"
+echo "1) ☁️ Cua Cloud Containers (works on any system)"
echo "2) 🖥️ Local macOS VMs (requires Apple Silicon Mac + macOS 15+)"
echo ""
read -p "Enter your choice (1 or 2): " CHOICE
if [[ "$CHOICE" == "1" ]]; then
- # C/ua Cloud Container setup
+ # Cua Cloud Container setup
echo ""
- echo "☁️ Setting up C/ua Cloud Containers..."
+ echo "☁️ Setting up Cua Cloud Containers..."
echo ""
# Check if existing .env.local already has CUA_API_KEY (check current dir and demo dir)
@@ -61,15 +61,15 @@ if [[ "$CHOICE" == "1" ]]; then
# If no valid API key found, prompt for one
if [[ -z "$CUA_API_KEY" ]]; then
- echo "To use C/ua Cloud Containers, you need to:"
+ echo "To use Cua Cloud Containers, you need to:"
echo "1. Sign up at https://trycua.com"
echo "2. Create a Cloud Container"
echo "3. Generate an Api Key"
echo ""
- read -p "Enter your C/ua Api Key: " CUA_API_KEY
+ read -p "Enter your Cua Api Key: " CUA_API_KEY
if [[ -z "$CUA_API_KEY" ]]; then
- echo "❌ C/ua Api Key is required for Cloud Containers."
+ echo "❌ Cua Api Key is required for Cloud Containers."
exit 1
fi
fi
@@ -84,7 +84,7 @@ elif [[ "$CHOICE" == "2" ]]; then
# Check for Apple Silicon Mac
if [[ $(uname -s) != "Darwin" || $(uname -m) != "arm64" ]]; then
echo "❌ Local macOS VMs require an Apple Silicon Mac (M1/M2/M3/M4)."
- echo "💡 Consider using C/ua Cloud Containers instead (option 1)."
+ echo "💡 Consider using Cua Cloud Containers instead (option 1)."
exit 1
fi
@@ -92,7 +92,7 @@ elif [[ "$CHOICE" == "2" ]]; then
OSVERSION=$(sw_vers -productVersion)
if [[ $(echo "$OSVERSION 15.0" | tr " " "\n" | sort -V | head -n 1) != "15.0" ]]; then
echo "❌ Local macOS VMs require macOS 15 (Sequoia) or newer. You have $OSVERSION."
- echo "💡 Consider using C/ua Cloud Containers instead (option 1)."
+ echo "💡 Consider using Cua Cloud Containers instead (option 1)."
exit 1
fi
@@ -205,7 +205,7 @@ fi
source "$VENV_DIR/bin/activate"
# Install required packages
-echo "📦 Updating C/ua packages..."
+echo "📦 Updating Cua packages..."
pip install -U pip setuptools wheel Cmake
pip install -U cua-computer "cua-agent[all]"
@@ -257,7 +257,7 @@ from pathlib import Path
from dotenv import load_dotenv
from computer import Computer
from agent import ComputerAgent, LLM, AgentLoop, LLMProvider
-from agent.ui.gradio.app import create_gradio_ui
+from agent.ui.gradio.ui_components import create_gradio_ui
# Load environment variables from .env.local
load_dotenv(Path(__file__).parent / ".env.local")
@@ -292,7 +292,7 @@ from pathlib import Path
from dotenv import load_dotenv
from computer import Computer
from agent import ComputerAgent, LLM, AgentLoop, LLMProvider
-from agent.ui.gradio.app import create_gradio_ui
+from agent.ui.gradio.ui_components import create_gradio_ui
# Load environment variables from .env.local
load_dotenv(Path(__file__).parent / ".env.local")
@@ -336,10 +336,10 @@ fi
# Ask if the user wants to start the demo now
echo
-read -p "Would you like to start the C/ua Computer-Use Agent UI now? (y/n) " -n 1 -r
+read -p "Would you like to start the Cua Computer-Use Agent UI now? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
- echo "🚀 Starting the C/ua Computer-Use Agent UI..."
+ echo "🚀 Starting the Cua Computer-Use Agent UI..."
echo ""
"$DEMO_DIR/start_ui.sh"
fi
diff --git a/tests/files.py b/tests/files.py
index bcfbb4f5..b0ae9c60 100644
--- a/tests/files.py
+++ b/tests/files.py
@@ -2,7 +2,7 @@
File System Interface Tests
Tests for the file system methods of the Computer interface (macOS).
Required environment variables:
-- CUA_API_KEY: API key for C/ua cloud provider
+- CUA_API_KEY: API key for Cua cloud provider
- CUA_CONTAINER_NAME: Name of the container to use
"""
@@ -33,7 +33,7 @@ from computer import Computer, VMProviderType
@pytest.fixture(scope="session")
async def computer():
"""Shared Computer instance for all test cases."""
- # Create a remote Linux computer with C/ua
+ # Create a remote Linux computer with Cua
computer = Computer(
os_type="linux",
api_key=os.getenv("CUA_API_KEY"),
@@ -41,7 +41,7 @@ async def computer():
provider_type=VMProviderType.CLOUD,
)
- # Create a local macOS computer with C/ua
+ # Create a local macOS computer with Cua
# computer = Computer()
# Connect to host computer
diff --git a/tests/shell_bash.py b/tests/shell_bash.py
index af34ff0e..ca7f8e1f 100644
--- a/tests/shell_bash.py
+++ b/tests/shell_bash.py
@@ -2,7 +2,7 @@
Shell Command Tests (Bash)
Tests for the run_command method of the Computer interface using bash commands.
Required environment variables:
-- CUA_API_KEY: API key for C/ua cloud provider
+- CUA_API_KEY: API key for Cua cloud provider
- CUA_CONTAINER_NAME: Name of the container to use
"""
@@ -33,7 +33,7 @@ from computer import Computer, VMProviderType
@pytest.fixture(scope="session")
async def computer():
"""Shared Computer instance for all test cases."""
- # Create a remote Linux computer with C/ua
+ # Create a remote Linux computer with Cua
computer = Computer(
os_type="linux",
api_key=os.getenv("CUA_API_KEY"),
diff --git a/tests/shell_cmd.py b/tests/shell_cmd.py
index a210e453..6062e53e 100644
--- a/tests/shell_cmd.py
+++ b/tests/shell_cmd.py
@@ -2,7 +2,7 @@
Shell Command Tests (CMD)
Tests for the run_command method of the Computer interface using cmd.exe commands.
Required environment variables:
-- CUA_API_KEY: API key for C/ua cloud provider
+- CUA_API_KEY: API key for Cua cloud provider
- CUA_CONTAINER_NAME: Name of the container to use
"""
@@ -33,7 +33,7 @@ from computer import Computer, VMProviderType
@pytest.fixture(scope="session")
async def computer():
"""Shared Computer instance for all test cases."""
- # Create a remote Windows computer with C/ua
+ # Create a remote Windows computer with Cua
computer = Computer(
os_type="windows",
api_key=os.getenv("CUA_API_KEY"),
diff --git a/tests/venv.py b/tests/venv.py
index 522a4727..8479e28f 100644
--- a/tests/venv.py
+++ b/tests/venv.py
@@ -1,9 +1,9 @@
"""
Virtual Environment Testing Module
-This module tests the ability to execute python code in a virtual environment within C/ua Containers.
+This module tests the ability to execute python code in a virtual environment within Cua Containers.
Required environment variables:
-- CUA_API_KEY: API key for C/ua cloud provider
+- CUA_API_KEY: API key for Cua cloud provider
- CUA_CONTAINER_NAME: Name of the container to use
"""
@@ -36,7 +36,7 @@ from computer.helpers import sandboxed, set_default_computer
@pytest.fixture(scope="session")
async def computer():
"""Shared Computer instance for all test cases."""
- # Create a remote Linux computer with C/ua
+ # Create a remote Linux computer with Cua
computer = Computer(
os_type="linux",
api_key=os.getenv("CUA_API_KEY"),
@@ -44,7 +44,7 @@ async def computer():
provider_type=VMProviderType.CLOUD,
)
- # # Create a local macOS computer with C/ua
+ # # Create a local macOS computer with Cua
# computer = Computer()
try:
diff --git a/tests/watchdog.py b/tests/watchdog.py
index 24b268c2..c5a014e6 100644
--- a/tests/watchdog.py
+++ b/tests/watchdog.py
@@ -2,7 +2,7 @@
Watchdog Recovery Tests
Tests for the watchdog functionality to ensure server recovery after hanging commands.
Required environment variables:
-- CUA_API_KEY: API key for C/ua cloud provider
+- CUA_API_KEY: API key for Cua cloud provider
- CUA_CONTAINER_NAME: Name of the container to use
"""
@@ -34,7 +34,7 @@ from computer import Computer, VMProviderType
@pytest.fixture(scope="session")
async def computer():
"""Shared Computer instance for all test cases."""
- # Create a remote Linux computer with C/ua
+ # Create a remote Linux computer with Cua
computer = Computer(
os_type="linux",
api_key=os.getenv("CUA_API_KEY"),
+ 
+