### Run cua CLI and interactive setup

Source: https://docs.trycua.com/docs/quickstart-cli

Launches the cua CLI. If environment variables are not set, it will guide you through an interactive setup process to configure the Container Name, CUA API Key, and Provider API Key.

```shell
cua init
# Follow the prompts to enter your container name, CUA API key, and provider API key.
```

--------------------------------

### Install cua CLI using uv

Source: https://docs.trycua.com/docs/quickstart-cli

Installs the cua CLI using the uv package manager. This is the recommended installation method for cua.

```shell
uv pip install --python 3.12 cua-agent-cli
```

--------------------------------

### Install Python 3.12

Source: https://docs.trycua.com/docs/quickstart-cli

Instructions for installing Python 3.12, a prerequisite for running cua. It covers installation via uv, conda, and pip.

```shell
# Using uv
uv install python@3.12

# Using conda
conda create -n cua python=3.12
conda activate cua

# Using pip (ensure pip is up-to-date)
pip install python==3.12
```

--------------------------------

### Install uv package manager

Source: https://docs.trycua.com/docs/quickstart-cli

Installs the uv package manager, a fast Python package installer and environment manager. This is a recommended way to install cua and its dependencies.

```shell
# macOS / Linux
curl -LsSf https://uv.sh/install.sh | sh

# Windows (using PowerShell)
Invoke-WebRequest -Uri https://uv.sh/install.ps1 -OutFile install.ps1
Set-ExecutionPolicy Bypass -Scope Process -Force; .
install.ps1
```

--------------------------------

### Run Cua Agent UI

Source: https://docs.trycua.com/docs/quickstart-ui

Starts the Cua Agent UI, which provides a chat interface for controlling your computer using natural language. This command assumes Cua is installed and accessible in your environment.

```bash
cua-python
```

--------------------------------

### Install Cua using uv

Source: https://docs.trycua.com/docs/quickstart-ui

Installs the Cua agent using the uv package manager. This command ensures that the necessary Cua packages are installed in the current Python environment.

```bash
uv pip install "cua-python"
```

--------------------------------

### Configure MCP Server to Use Startup Script (Shell)

Source: https://docs.trycua.com/docs/libraries/mcp-server/installation

Example of how to use the generated startup script in your MCP configuration. This ensures the MCP server starts correctly with the Cua agent.

```shell
command: ~/.cua/start_mcp_server.sh
```

--------------------------------

### Install Docker CUA Ubuntu Container

Source: https://docs.trycua.com/docs/quickstart-ui

Pulls the CUA Ubuntu container image from Docker Hub. This is part of the Docker-based setup for running Cua on a cross-platform basis.

```bash
docker pull "ghcr.io/trycua/cua-ubuntu"
```

--------------------------------

### Install pywin32 dependency for Windows Sandbox

Source: https://docs.trycua.com/docs/quickstart-cli

Installs the `pywin32` Python package, which is a dependency for interacting with the Windows Sandbox environment when running cua.

```shell
pip install pywin32
```

--------------------------------

### Install uv CLI (Windows)

Source: https://docs.trycua.com/docs/quickstart-ui

Installs the uv command-line interface on Windows systems. uv is a fast Python package installer and language runtime, recommended for managing Cua's Python environment and dependencies.

```powershell
# Windows
Invoke-WebRequest -Uri "https://github.com/astral-sh/uv/releases/latest/download/uv-install.ps1" -OutFile "uv-install.ps1"; &"uv-install.ps1"
```

--------------------------------

### Install cua CLI using pip

Source: https://docs.trycua.com/docs/quickstart-cli

Installs the cua CLI using pip. This method is suitable if you are managing your Python environment with pip.

```shell
pip install cua-agent-cli
```

--------------------------------

### Install uv CLI (macOS/Linux)

Source: https://docs.trycua.com/docs/quickstart-ui

Installs the uv command-line interface, a fast Python package installer and language runtime, on macOS and Linux systems. This is a recommended method for managing Python environments and dependencies for Cua.

```bash
# macOS / Linux
curl -LsSf https://github.com/astral-sh/uv/releases/latest/download/uv-install.sh | sh
```

--------------------------------

### Install Cua using pip

Source: https://docs.trycua.com/docs/quickstart-ui

Installs the Cua Python package using pip. This command assumes you have a Python environment set up and pip available.

```bash
pip install "cua-python"
```

--------------------------------

### Run Cua Easy Setup Script (Bash)

Source: https://docs.trycua.com/docs/libraries/mcp-server/installation

Downloads and runs a script to simplify Cua installation. It creates the ~/.cua directory, generates a startup script, makes it executable, and manages Python virtual environments and package updates.

```bash
curl -sSL https://raw.githubusercontent.com/cua/cua/master/install.sh | bash
```

--------------------------------

### Install Custom Linux Image with Lume

Source: https://docs.trycua.com/docs/libraries/lume/faq

This outlines the process for installing a custom Linux image using Lume. Unlike macOS, this involves creating a Linux VM first and then mounting a setup image for the initial boot. Specific commands for mounting the setup image are not detailed here.

```bash
# Create a new Linux VM
lume install linux

# Mount a setup image for first boot (example command, specific syntax may vary)
lume attach <vm_name> --image /path/to/setup.img
```

--------------------------------

### Start a local cua container using Docker

Source: https://docs.trycua.com/docs/quickstart-cli

Pulls the CUA Ubuntu container image and starts a local cua container using Docker. This is a cross-platform option for running cua.

```shell
# Pull the CUA Ubuntu container
docker pull cua/ubuntu:latest

# Run the container (example - you might need to adjust ports/volumes)
docker run -it --rm --name cua-agent cua/ubuntu:latest /bin/bash
```

--------------------------------

### Install pywinsandbox dependency

Source: https://docs.trycua.com/docs/quickstart-ui

Installs the pywinsandbox Python package, which is a dependency for using Cua with the Windows Sandbox environment. This is typically done within a Python environment.

```bash
pip install pywinsandbox
```

--------------------------------

### Start Lume API Service (Bash)

Source: https://docs.trycua.com/docs/libraries/lume/installation

Starts the Lume API service manually in your terminal. This command should be run when you need to use tools or libraries that depend on the Lume API, especially if you installed Lume with the `--no-background-service` option.

```bash
lume serve
```

--------------------------------

### Install Lume CLI with Script

Source: https://docs.trycua.com/docs/libraries/lume/installation

Installs the Lume CLI using a single command script. This is the recommended method for a quick and easy setup. Ensure your system meets the prerequisites before running the script.

```bash
curl -fsSL https://install.lume.dev | bash
```

--------------------------------

### Install cua CLI using conda

Source: https://docs.trycua.com/docs/quickstart-cli

Installs the cua CLI within a conda environment. Ensure you have created and activated a Python 3.12 environment first.

```shell
conda activate cua  # Replace 'cua' with your environment name
pip install cua-agent-cli
```

--------------------------------

### Create and activate Python 3.12 environment with conda

Source: https://docs.trycua.com/docs/quickstart-ui

Creates a new Conda environment named 'cua' with Python version 3.12, and then activates it. This isolates the Cua installation and its dependencies.

```bash
conda create -n cua python=3.12
conda activate cua
```

--------------------------------

### Install Cua MCP Server via PyPI (Python)

Source: https://docs.trycua.com/docs/libraries/mcp-server/installation

Installs the MCP server, CUA agent, computer dependencies, and the `cua-mcp-server` executable. This is the manual installation method.

```bash
pip install "cua-mcp-server"
```

--------------------------------

### Run VM

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Starts a virtual machine instance.

```APIDOC
## POST /lume/vms/:name/run

### Description
Run a virtual machine instance.

### Method
POST

### Endpoint
/lume/vms/:name/run

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the VM to run

#### Request Body
- **noDisplay** (boolean) - Optional - If true, do not start VNC client
- **sharedDirectories** (array of object) - Optional - List of shared directories (`hostPath`, `readOnly`)
- **recoveryMode** (boolean) - Optional - Start in recovery mode
- **storage** (string) - Optional - Storage type (`ssd`, etc.)

### Request Example
```json
{
  "noDisplay": false,
  "sharedDirectories": [
    { "hostPath": "/Users/user/shared", "readOnly": false }
  ],
  "recoveryMode": false,
  "storage": "ssd"
}
```

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "VM 'my-vm' is running."
}
```
```

--------------------------------

### Start Lume API Manually (Bash)

Source: https://docs.trycua.com/docs/libraries/lume/installation

Manually starts the Lume API service without running it as a background service. This is useful if you prefer to control the service's lifecycle explicitly. You will need to run `lume serve` manually when needed.

```bash
lume --no-background-service
```

--------------------------------

### Install Lume CLI

Source: https://docs.trycua.com/docs/libraries/lumier/installation

This command installs the Lume virtualization CLI, which is a dependency for Lumier. Ensure Docker for Apple Silicon is installed prior to running this command.

```bash
curl -fsSL https://lume.nu/install.sh | bash
```

--------------------------------

### Connect to WebSocket Endpoint (Python)

Source: https://docs.trycua.com/docs/libraries/computer-server/WebSocket-API

Example of connecting to the Computer Server's WebSocket endpoint using Python. It demonstrates establishing a connection and sending a message. This snippet assumes the 'websocket-client' library is installed.

```python
import websocket

try:
    ws = websocket.create_connection("ws://localhost:8000/ws")
    print("Connected to WebSocket!")
    # Example: Sending a command (replace with actual command)
    ws.send('{"command": "ping"}')
    result = ws.recv()
    print(f"Received: {result}")
    ws.close()
except websocket.WebSocketException as e:
    print(f"WebSocket Error: {e}")
except Exception as e:
    print(f"An error occurred: {e}")
```

--------------------------------

### Automate VM Startup with on-logon.sh in Lumier Docker

Source: https://docs.trycua.com/docs/libraries/lumier/docker

Scripts placed in the `on-logon.sh` file within the shared folder are automatically executed when the macOS VM starts. This allows for automated environment setup within the VM.

```bash
# Place your startup script commands here
echo "VM is starting up!"
# Example: Install a package
# apt-get update && apt-get install -y some-package
```

--------------------------------

### LiteLLM Model String Examples (Anthropic, OpenAI, Local, Omni)

Source: https://docs.trycua.com/docs/libraries/mcp-server/llm-integrations

Examples of model strings used to configure LiteLLM integration in the MCP server. These strings specify the LLM provider and model, allowing for automatic detection and utilization of different LLM services.

```text
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"
```

--------------------------------

### Computer Action Start Callback

Source: https://docs.trycua.com/docs/agent-sdk/callbacks/agent-lifecycle

The `on_computer_call_start` callback is invoked before the agent initiates a computer action (e.g., tool usage). It allows for pre-action setup and receives the specific item representing the action.

```python
def on_computer_call_start(item):
    # Actions before computer actions
    pass
```

--------------------------------

### Install HUD Evals Package

Source: https://docs.trycua.com/docs/agent-sdk/integrations/hud

Installs the necessary package for using HUD Evals. Ensure you have a Python environment set up.

```bash
pip install "computer-agent[hud]"
```

--------------------------------

### API Start Callback

Source: https://docs.trycua.com/docs/agent-sdk/callbacks/agent-lifecycle

The `on_api_start` callback is triggered just before an LLM API call is made. It can be used for any setup required immediately prior to the API interaction, receiving keyword arguments related to the call.

```python
def on_api_start(kwargs):
    # Actions before each LLM API call
    pass
```

--------------------------------

### Start Lume API Server

Source: https://docs.trycua.com/docs/libraries/lume/cli-reference

Initiate the Lume API server for programmatic access using the `lume serve` command. You can specify the port for the server to listen on.

```bash
lume serve --port <port>
```

--------------------------------

### POST /cmd Request Example (Python)

Source: https://docs.trycua.com/docs/libraries/computer-server/REST-API

Example of how to send a POST request to the /cmd endpoint using Python's requests library. This demonstrates the structure of the request body and the necessary headers for cloud deployments.

```python
import requests
import json

# For local testing
# url = "http://localhost:8000/cmd"

# For cloud deployment
url = "https://your-container.containers.cloud.trycua.com:8443/cmd"
container_name = "your-container-name"
api_key = "your-api-key"

headers = {
    "Content-Type": "application/json"
}

# Add cloud-specific headers if deploying to the cloud
# headers["X-Container-Name"] = container_name
# headers["X-API-Key"] = api_key

command_payload = {
    "command": "your_command",
    "parameters": {
        "param1": "value1",
        "param2": "value2"
    }
}

try:
    response = requests.post(url, headers=headers, data=json.dumps(command_payload), stream=True)
    response.raise_for_status()  # Raise an exception for bad status codes

    print(f"Status Code: {response.status_code}")
    print("Streaming Response:")
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))

except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

```

--------------------------------

### Get VM Information with Lume

Source: https://docs.trycua.com/docs/libraries/lume/cli-reference

Retrieve detailed information for a specific virtual machine using `lume get <name>`. The output format can be set to JSON or text, and the storage location can be specified.

```bash
lume get <name> -f <format> --storage <name>
```

--------------------------------

### Pull Prebuilt Images with Lume CLI

Source: https://docs.trycua.com/docs/libraries/lume/prebuilt-images

This command allows users to download pre-built virtual machine images from the Cua registry. Ensure the Lume CLI is installed and configured.

```bash
lume pull <image-name>
```

--------------------------------

### Create macOS VM with Latest IPSW Image

Source: https://docs.trycua.com/docs/libraries/lume/faq

This command creates a new macOS virtual machine using the latest available IPSW image supported by Lume. Ensure Lume is installed and configured correctly before execution.

```bash
lume install macos --latest
```

--------------------------------

### Create macOS VM with Specific IPSW Image

Source: https://docs.trycua.com/docs/libraries/lume/faq

This command creates a new macOS virtual machine using a specified IPSW file. You must first download the desired IPSW file and provide its path. This allows for the installation of older or specific macOS versions.

```bash
lume install macos --ipsw /path/to/your/macOS.ipsw
```

--------------------------------

### Installing Python Packages in Sandboxed Environment

Source: https://docs.trycua.com/docs/computer-sdk/sandboxed-python

Shows how to install Python packages within a sandboxed virtual environment on a remote Cua Computer using the `venv_install` method. This ensures that the remote execution environment has the necessary dependencies.

```python
from computer import Computer

computer = Computer(computer_id="YOUR_COMPUTER_ID")

# Install a package in the specified virtual environment
computer.venv_install("my-venv", "requests")

# You can also install multiple packages
computer.venv_install("my-venv", ["numpy", "pandas"])
```

--------------------------------

### Get VM Details

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Fetches detailed information about a specific virtual machine.

```APIDOC
## GET /lume/vms/:name

### Description
Get details for a specific virtual machine.

### Method
GET

### Endpoint
/lume/vms/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the VM to retrieve details for

#### Query Parameters
- **storage** (string) - Optional - Storage type (`ssd`, etc.)

### Response
#### Success Response (200 OK)
- **name** (string) - Name of the VM
- **id** (string) - Unique identifier for the VM
- **status** (string) - Current status of the VM
- **cpu** (integer) - Number of CPU cores
- **memory** (string) - Memory size
- **diskSize** (string) - Disk size
- **display** (string) - Display resolution
- **os** (string) - Guest OS

#### Response Example
```json
{
  "name": "my-vm",
  "id": "vm-12345",
  "status": "running",
  "cpu": 4,
  "memory": "8GB",
  "diskSize": "128GB",
  "display": "1920x1080",
  "os": "macOS"
}
```
```

--------------------------------

### List VMs using TypeScript

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves a list of all virtual machines using TypeScript and the fetch API. Sends a GET request to the /lume/vms endpoint.

```typescript
async function listVms(): Promise<any[]> {
  const url = "http://localhost:7777/lume/vms";
  const response = await fetch(url);
  return response.json();
}

// Example usage:
// listVms().then(console.log);
```

--------------------------------

### Run a VM with Lume

Source: https://docs.trycua.com/docs/libraries/lume/cli-reference

The `lume run` command starts a virtual machine. Options include disabling the VNC client, sharing directories, mounting read-only disks for Linux, specifying the container registry and organization, setting the VNC port, and enabling recovery mode for macOS VMs.

```bash
lume run <name> \
  --no-display \
  --shared-dir <dir> \
  --mount <path> \
  --registry <url> \
  --organization <org> \
  --vnc-port <port> \
  --recovery-mode <boolean> \
  --storage <name>
```

--------------------------------

### Get VM Storage Locations

Source: https://docs.trycua.com/docs/libraries/lume/http-api

List all configured VM storage locations.

```APIDOC
## Get VM Storage Locations

### Description
List all configured VM storage locations.

### Method
GET

### Endpoint
/lume/config/locations

### Parameters

#### Path Parameters

#### Query Parameters

#### Request Body

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **locations** (array) - A list of VM storage locations.

#### Response Example
```json
{
  "example": "{\"locations\": [\"/mnt/storage1\", \"/mnt/storage2\"]}"
}
```
```

--------------------------------

### Composing Agents with Grounding and Planning Models

Source: https://docs.trycua.com/docs/agent-sdk/supported-agents/composed-agents

This example demonstrates how to compose agents by specifying a grounding model and a planning model using the 'grounding_model+planning_model' format. This allows for combining specialized click prediction with powerful LLM reasoning.

```python
from litellm import completion

# Example: GTA1 grounding model with OpenAI's GPT-5 for planning
composed_agent = "huggingface-local/HelloKKMe/GTA1-7B+openai/gpt-5"

response = completion(
    model=composed_agent,
    messages=[
        {"role": "user", "content": "Find the login button and click it."}
    ]
)

print(response)

# Example: UI-TARS grounding model with Anthropic's Claude 3.5 Sonnet for planning
composed_agent_2 = "huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B+anthropic/claude-3-5-sonnet-20241022"

response_2 = completion(
    model=composed_agent_2,
    messages=[
        {"role": "user", "content": "Navigate to the settings page."}
    ]
)

print(response_2)
```

--------------------------------

### Run Agent Loop with ComputerAgent

Source: https://docs.trycua.com/docs/agent-sdk/agent-loops

This example demonstrates how to instantiate and run an agent loop using the ComputerAgent. It shows basic usage with a required model and optional tools, illustrating the core functionality of agent execution.

```python
from cua.agents import ComputerAgent

agent = ComputerAgent(
    model="claude-3-5-sonnet-20241022",
    tools=[
        # Add your tools here, e.g., Computer(), custom_tool
    ],
)

async for chunk in agent.run("Write a poem about the sea."):
    print(chunk)
```

--------------------------------

### Get Configuration

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves the current Lume configuration settings.

```APIDOC
## GET /lume/config

### Description
Get current Lume configuration settings.

### Method
GET

### Endpoint
/lume/config

### Response
#### Success Response (200 OK)
- **homeDirectory** (string) - Lume home directory path
- **cacheDirectory** (string) - Cache directory path
- **cachingEnabled** (boolean) - Whether caching is enabled

#### Response Example
```json
{
  "homeDirectory": "/Users/user/.lume",
  "cacheDirectory": "/Users/user/.lume/cache",
  "cachingEnabled": true
}
```
```

--------------------------------

### Get VM Details using Python

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves detailed information for a specific virtual machine using Python. Sends a GET request to the /lume/vms/:name endpoint with optional storage parameter.

```python
import requests

def get_vm_details(name, storage=None):
    url = f"http://localhost:7777/lume/vms/{name}"
    params = {}
    if storage:
        params["storage"] = storage
    response = requests.get(url, params=params)
    return response.json()

# Example usage:
# print(get_vm_details("my-vm", storage="ssd"))
```

--------------------------------

### Get VM Details using TypeScript

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves detailed information for a specific virtual machine using TypeScript. Sends a GET request to the /lume/vms/:name endpoint with optional storage parameter.

```typescript
async function getVmDetails(name: string, storage?: string): Promise<any> {
  const url = `http://localhost:7777/lume/vms/${name}`;
  const queryParams = new URLSearchParams();
  if (storage) {
    queryParams.append("storage", storage);
  }
  const response = await fetch(`${url}?${queryParams.toString()}`);
  return response.json();
}

// Example usage:
// getVmDetails("my-vm", "ssd").then(console.log);
```

--------------------------------

### Implement Custom Computer Handler as a Class

Source: https://docs.trycua.com/docs/agent-sdk/custom-computer-handlers

This example shows how to create a custom computer handler by inheriting from `AsyncComputerHandler`. This approach is recommended for more complex implementations, offering greater flexibility and structure. Ensure your class implements the necessary asynchronous methods for interaction with the agent.

```python
from cua.agent import AsyncComputerHandler

class MyCustomComputer(AsyncComputerHandler):
    def __init__(self, name="my_class_computer", description="A custom computer implemented as a class."):
        super().__init__(name=name, description=description)

    async def run(self, prompt: str) -> str:
        # Your complex logic here
        return f"Output from class-based custom computer: {prompt}"

# Instantiate and add to agent:
# custom_class_computer = MyCustomComputer()
# agent.add_tool(custom_class_computer)
```

--------------------------------

### Run Ollama Models Locally with Cua

Source: https://docs.trycua.com/docs/agent-sdk/supported-model-providers/local-models

This snippet demonstrates how to run models locally using Cua through the `ollama` library. It requires Ollama to be installed and running. This integration allows for fast local inference with various Ollama-supported models.

```shell
RUNNING_MODEL="ollama_chat/llama2:7b"

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$RUNNING_MODEL\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"Explain quantum computing simply.\"}
    ]
  }"
```

--------------------------------

### List Images using TypeScript

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves a list of available VM images using TypeScript and the fetch API. Sends a GET request to the /lume/images endpoint.

```typescript
async function listImages(): Promise<any[]> {
  const url = "http://localhost:7777/lume/images";
  const response = await fetch(url);
  return response.json();
}

// Example usage:
// listImages().then(console.log);
```

--------------------------------

### List VMs using Python

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves a list of all virtual machines using Python's requests library. Sends a GET request to the /lume/vms endpoint.

```python
import requests

def list_vms():
    url = "http://localhost:7777/lume/vms"
    response = requests.get(url)
    return response.json()

# Example usage:
# print(list_vms())
```

--------------------------------

### Run Ephemeral macOS VM with Lumier Docker

Source: https://docs.trycua.com/docs/libraries/lumier/docker

This command starts an ephemeral macOS VM using Lumier via Docker. The VM is accessible via a web browser at http://localhost:8006. VM state is reset upon container stop.

```bash
docker run -it --rm -p 8006:8006 -v /var/run/docker.sock:/var/run/docker.sock --name lume lume/lume
```

--------------------------------

### Start Human Agent Tool

Source: https://docs.trycua.com/docs/agent-sdk/supported-agents/human-in-the-loop

This command initiates the human agent tool within the Cua environment. It provides a web-based UI where pending agent requests can be reviewed and acted upon, allowing a human to take control of the agent.

```bash
grounding_model+human/human
```

```bash
human/human
```

--------------------------------

### Run MLX Models Locally on Apple Silicon with Cua

Source: https://docs.trycua.com/docs/agent-sdk/supported-model-providers/local-models

This snippet shows how to use Cua to run models locally on Apple Silicon via the `mlx-vlm` library. Ensure `mlx-vlm` is installed. This method is optimized for performance on M1/M2/M3 chips.

```shell
RUNNING_MODEL="mlx/mistralai/Mistral-7B-Instruct-v0.1-2"

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$RUNNING_MODEL\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"Tell me a joke.\"}
    ]
  }"
```

--------------------------------

### Get Latest IPSW URL

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Fetches the URL for the latest macOS IPSW file.

```APIDOC
## GET /lume/ipsw

### Description
Get the URL for the latest macOS IPSW file.

### Method
GET

### Endpoint
/lume/ipsw

### Response
#### Success Response (200 OK)
- **url** (string) - The URL for the latest macOS IPSW file.

#### Response Example
```json
{
  "url": "https://example.com/ipsw/macOS_14.4.ipsw"
}
```
```

--------------------------------

### List Images using Python

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves a list of available VM images using Python's requests library. Sends a GET request to the /lume/images endpoint.

```python
import requests

def list_images():
    url = "http://localhost:7777/lume/images"
    response = requests.get(url)
    return response.json()

# Example usage:
# print(list_images())
```

--------------------------------

### Agent Run Start Callback

Source: https://docs.trycua.com/docs/agent-sdk/callbacks/agent-lifecycle

The `on_run_start` callback is invoked once at the beginning of an agent's run. It's suitable for initializing tracking mechanisms, setting up logging, or establishing initial state for the agent's execution. It accepts keyword arguments and old items.

```python
def on_run_start(kwargs, old_items):
    # Initialize tracking, logging, or state
    pass
```

--------------------------------

### List VMs using Curl

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves a list of all virtual machines managed by Lume. This is a simple GET request to the /lume/vms endpoint.

```curl
curl http://localhost:7777/lume/vms
```

--------------------------------

### Configure Lumier Docker Environment Variables

Source: https://docs.trycua.com/docs/libraries/lumier/docker

This example shows how to set environment variables when running the Lumier Docker container to configure VM settings. Includes VM name, macOS version, CPU, RAM, and storage paths.

```bash
docker run -it --rm \
  -p 8006:8006 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/storage:/storage \
  -e VM_NAME=my-macos-vm \
  -e VERSION=ventura \
  -e CPU_CORES=4 \
  -e RAM_SIZE=4096 \
  -e HOST_STORAGE_PATH=$(pwd)/storage \
  -e HOST_SHARED_PATH=$(pwd)/shared \
  --name lume \
  lume/lume
```

--------------------------------

### Sandboxed Python Execution Example

Source: https://docs.trycua.com/docs/computer-sdk/sandboxed-python

Demonstrates how to use the `sandboxed` decorator to execute Python functions remotely on a Cua Computer. This involves defining a Python function and applying the decorator to specify the virtual environment and target computer.

```python
from computer import Computer
from computer.decorator import sandboxed

computer = Computer(computer_id="YOUR_COMPUTER_ID")

@sandboxed(venv_name="my-venv", computer=computer)
def my_python_function(arg1: str, arg2: int) -> str:
    # This code runs remotely on the Cua Computer
    print(f"Received arguments: {arg1}, {arg2}")
    return f"Processed {arg1} and {arg2}"

# Call the sandboxed function locally
result = my_python_function("hello", 123)
print(f"Remote result: {result}")
```

--------------------------------

### List Images using Curl

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves a list of all available VM images managed by Lume. This is a simple GET request to the /lume/images endpoint.

```curl
curl http://localhost:7777/lume/images
```

--------------------------------

### Get VM Storage Locations (Curl)

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves a list of all configured VM storage locations. This operation does not require any input parameters.

```curl
curl GET: /lume/config/locations
```

--------------------------------

### Get Latest macOS IPSW URL with Lume

Source: https://docs.trycua.com/docs/libraries/lume/cli-reference

The `lume ipsw` command retrieves the URL for the latest macOS restore image.

```bash
lume ipsw
```

--------------------------------

### LLM Start Callback for Message Preprocessing

Source: https://docs.trycua.com/docs/agent-sdk/callbacks/agent-lifecycle

The `on_llm_start` callback allows for preprocessing of messages before they are sent to the Language Model (LLM). This is useful for tasks like PII anonymization or image retention. It receives a list of messages and should return the processed messages.

```python
def on_llm_start(messages):
    # Preprocess messages before LLM call
    # Use for PII anonymization, image retention.
    return messages
```

--------------------------------

### Function Call Start Callback

Source: https://docs.trycua.com/docs/agent-sdk/callbacks/agent-lifecycle

The `on_function_call_start` callback is triggered before the agent makes a function call. It receives the item detailing the function call, allowing for pre-execution logic.

```python
def on_function_call_start(item):
    # Actions before function calls
    pass
```

--------------------------------

### Agent Input as List of Messages

Source: https://docs.trycua.com/docs/agent-sdk/agent-loops

This example illustrates how to pass a list of message dictionaries as input to the agent's run method. This format is useful for multi-turn conversations or structured interactions with the agent.

```python
from cua.agents import ComputerAgent

agent = ComputerAgent(model="computer-use-preview")

conversation_history = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "And what is its population?"}
]

async for chunk in agent.run(conversation_history):
    print(chunk)
```

--------------------------------

### Run Hugging Face Transformers Models Locally with Cua

Source: https://docs.trycua.com/docs/agent-sdk/supported-model-providers/local-models

This snippet demonstrates how to configure Cua to run Hugging Face models locally using the `transformers` library. It requires the `transformers` library to be installed. The input is typically a model identifier from the Hugging Face Hub.

```shell
RUNNING_MODEL="huggingface-local/meta-llama/Llama-2-7b-chat-hf"

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$RUNNING_MODEL\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"What is Cua?\"}
    ]
  }"
```

--------------------------------

### InternVL 3.5 Family Model Identifiers for Grounding

Source: https://docs.trycua.com/docs/agent-sdk/supported-agents/grounding-models

Lists model identifiers for the InternVL 3.5 family, suitable for UI element grounding. These models are available locally in a range of parameter sizes, starting from 1B.

```text
huggingface-local/OpenGVLab/InternVL3_5-{1B,2B,4B,8B,...}
```

--------------------------------

### Get VM Details using Curl

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves detailed information for a specific virtual machine. Requires the VM's name as a path parameter. Supports optional storage type parameter.

```curl
curl http://localhost:7777/lume/vms/my-vm?storage=ssd
```

--------------------------------

### Manage Lume Cache Directory

Source: https://docs.trycua.com/docs/libraries/lume/cli-reference

Control the Lume cache directory using `lume config cache get` to retrieve the current path and `lume config cache set <path>` to specify a new one.

```bash
lume config cache get
```

```bash
lume config cache set <path>
```

--------------------------------

### Create VM

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Creates a new virtual machine instance with specified configuration.

```APIDOC
## POST /lume/vms

### Description
Create a new virtual machine.

### Method
POST

### Endpoint
/lume/vms

### Parameters
#### Request Body
- **name** (string) - Required - Name of the VM
- **os** (string) - Required - Guest OS (`macOS`, `linux`, etc.)
- **cpu** (integer) - Required - Number of CPU cores
- **memory** (string) - Required - Memory size (e.g. `4GB`)
- **diskSize** (string) - Required - Disk size (e.g. `64GB`)
- **display** (string) - Optional - Display resolution (e.g. `1024x768`)
- **ipsw** (string) - Optional - IPSW version (e.g. `latest`)
- **storage** (string) - Optional - Storage type (`ssd`, etc.)

### Request Example
```json
{
  "name": "my-vm",
  "os": "macOS",
  "cpu": 4,
  "memory": "8GB",
  "diskSize": "128GB",
  "display": "1920x1080",
  "ipsw": "latest",
  "storage": "ssd"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - Unique identifier for the created VM
- **name** (string) - Name of the VM
- **status** (string) - Current status of the VM

#### Response Example
```json
{
  "id": "vm-12345",
  "name": "my-vm",
  "status": "created"
}
```
```

--------------------------------

### Create a New VM with Lume

Source: https://docs.trycua.com/docs/libraries/lume/cli-reference

Use the `lume create` command to provision a new macOS or Linux virtual machine. You can specify the OS, CPU cores, memory, disk size, display resolution, IPSW path for macOS, and storage location.

```bash
lume create <name> \
  --os <os> \
  --cpu <cores> \
  --memory <size> \
  --disk-size <size> \
  --display <res> \
  --ipsw <path> \
  --storage <name>
```

--------------------------------

### Supported Commands

Source: https://docs.trycua.com/docs/libraries/computer-server

Reference for all commands supported by the Computer Server API, available via both WebSocket and REST interfaces.

```APIDOC
## Supported Commands

### Description
This section lists all commands supported by the Computer Server API, which can be accessed through both WebSocket and REST interfaces. Detailed command specifications are available in the SourceReference.

### Method
N/A (Informational)

### Endpoint
N/A (Informational)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Get Latest IPSW URL using Curl

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Retrieves the URL for the latest macOS IPSW file. This is a GET request to the /lume/ipsw endpoint.

```curl
curl http://localhost:7777/lume/ipsw
```

--------------------------------

### Clone VM

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Creates a copy of an existing virtual machine.

```APIDOC
## POST /lume/vms/clone

### Description
Clone an existing virtual machine.

### Method
POST

### Endpoint
/lume/vms/clone

### Parameters
#### Request Body
- **name** (string) - Required - Source VM name
- **newName** (string) - Required - New VM name
- **sourceLocation** (string) - Optional - Source storage location (`default`)
- **destLocation** (string) - Optional - Destination storage location

### Request Example
```json
{
  "name": "original-vm",
  "newName": "cloned-vm",
  "sourceLocation": "default",
  "destLocation": "/mnt/storage"
}
```

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message
- **newVmName** (string) - Name of the newly cloned VM

#### Response Example
```json
{
  "message": "VM 'original-vm' cloned successfully to 'cloned-vm'.",
  "newVmName": "cloned-vm"
}
```
```

--------------------------------

### Create VM using Curl

Source: https://docs.trycua.com/docs/libraries/lume/http-api

Creates a new virtual machine with specified parameters. Requires VM name, OS, CPU, memory, and disk size. Optional parameters include display resolution, IPSW version, and storage type.

```curl
curl -X POST \
  http://localhost:7777/lume/vms \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "my-vm",
  "os": "macOS",
  "cpu": 4,
  "memory": "8GB",
  "diskSize": "64GB"
}'
```

--------------------------------

### Push VM Image with Lume

Source: https://docs.trycua.com/docs/libraries/lume/cli-reference

Upload a VM image to a container registry with `lume push <name> <image:tag>`. Options include additional tags, registry URL, organization, storage location, chunk size for uploads, verbose logging, dry run, and reassembly verification.

```bash
lume push <name> <image:tag> \
  --additional-tags <tags...> \
  --registry <url> \
  --organization <org> \
  --storage <name> \
  --chunk-size-mb <size> \
  --verbose \
  --dry-run \
  --reassemble
```

--------------------------------

### Clone a VM with Lume

Source: https://docs.trycua.com/docs/libraries/lume/cli-reference

Create a duplicate of an existing virtual machine using `lume clone <name> <new-name>`. You can specify source and destination storage locations.

```bash
lume clone <name> <new-name> --source-storage <name> --dest-storage <name>
```

--------------------------------

### ComputerAgent Constructor Parameters

Source: https://docs.trycua.com/docs/agent-sdk/agent-loops

Explains the various parameters available for configuring the ComputerAgent, including model selection, tool integration, callbacks, resource management, and more.

```APIDOC
## ComputerAgent Constructor Parameters

### Description
Configures the behavior of the `ComputerAgent`, allowing customization of agent loops, tool integration, callbacks, resource management, and other advanced options.

### Method
Constructor

### Endpoint
N/A (Class Constructor)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*   **model** (str) - Required - The LLM or agent model to use (e.g., "claude-3-5-sonnet-20241022", "computer-use-preview", "omni+vertex_ai/gemini-pro").
*   **tools** (List[Any]) - Optional - List of tools the agent can use (e.g., `Computer`, sandboxed Python functions).
*   **custom_loop** (Callable) - Optional - A custom agent loop function to override automatic loop selection.
*   **only_n_most_recent_images** (int) - Optional - If set, only the N most recent images are kept in the message history to limit memory usage. Automatically adds `ImageRetentionCallback`.
*   **callbacks** (List[Any]) - Optional - List of callback instances for advanced preprocessing, postprocessing, logging, or custom hooks.
*   **verbosity** (int) - Optional - Logging level (e.g., `logging.INFO`). If set, adds a logging callback.
*   **trajectory_dir** (str) - Optional - Directory path to save full trajectory data, including screenshots and responses. Adds `TrajectorySaverCallback`.
*   **max_retries** (int) - Optional - Default: `3` Maximum number of retries for failed API calls.
*   **screenshot_delay** (float | int) - Optional - Default: `0.5` Delay (in seconds) before taking screenshots.
*   **use_prompt_caching** (bool) - Optional - Default: `False` Enables prompt caching for repeated prompts.
*   **max_trajectory_budget** (float | dict) - Optional - If set, 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) - Optional - Any additional keyword arguments are passed through to the agent loop or model provider.

### Request Example
```json
{
  "model": "claude-3-5-sonnet-20241022",
  "tools": [Computer()],
  "callbacks": [LoggingCallback()],
  "max_retries": 5
}
```

### Response
#### Success Response (200)
N/A (This is a constructor, not an endpoint returning data).

#### Response Example
N/A
```

--------------------------------

### Computer Server REST API Commands

Source: https://docs.trycua.com/docs/libraries/computer-server/Commands

Reference for the /cmd REST endpoint of the Computer Server, detailing all supported commands.

```APIDOC
## Computer Server REST API Reference

### Description
This section provides a reference for the `/cmd` REST endpoint of the Computer Server. It lists all supported commands that can be executed via this API.

### Method
GET, POST (depending on command complexity and data transfer)

### Endpoint
`/cmd`

### Commands Reference

*   **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**: Simulate a mouse button down event.
*   **mouse_up**: Simulate a mouse button up event.
*   **left_click**: Perform a left mouse click.
*   **right_click**: Perform a right mouse click.
*   **double_click**: Perform a double mouse click.
*   **move_cursor**: Move the mouse cursor to specified coordinates.
*   **drag_to**: Drag the mouse to specified coordinates.
*   **drag**: Drag the mouse by a specified offset.
*   **key_down**: Simulate a keyboard key down event.
*   **key_up**: Simulate a keyboard key up event.
*   **type_text**: Type a string of text.
*   **press_key**: Press a single keyboard key.
*   **hotkey**: Press a hotkey combination.
*   **scroll**: Scroll the screen by a specified amount.
*   **scroll_down**: Scroll the screen down.
*   **scroll_up**: Scroll the screen up.
*   **copy_to_clipboard**: Copy specified text to the system clipboard.
*   **set_clipboard**: Set the system clipboard content.
*   **file_exists**: Check if a file exists at the specified path.
*   **directory_exists**: Check if a directory exists at the specified path.
*   **list_dir**: List files and directories within a specified directory.
*   **read_text**: Read text content from a file.
*   **write_text**: Write text content to a file.
*   **read_bytes**: Read raw byte content from a file.
*   **write_bytes**: Write raw byte content to a file.
*   **get_file_size**: Get the size of a specified file.
*   **delete_file**: Delete a specified file.
*   **create_dir**: Create a directory at the specified path.
*   **delete_dir**: Delete a specified directory.
*   **get_accessibility_tree**: Retrieve the accessibility tree (if supported by the system).
*   **find_element**: Find an element within the accessibility tree.
*   **diorama_cmd**: Execute a diorama command (if supported).

### Request Example (Illustrative - actual request depends on the command)
```json
{
  "command": "version"
}
```

### Response Example (Illustrative - actual response depends on the command)
```json
{
  "version": "1.2.3",
  "protocol": "4"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.