Quickstart

Set Up Your Computer Environment

Choose how you want to run your Cua computer. This will be the environment where your automated tasks will execute.

You can run your Cua computer in the cloud (recommended for easiest setup), locally on macOS with Lume, locally on Windows with a Windows Sandbox, or in a Docker container on any platform. Choose the option that matches your system and needs.

Create and manage cloud sandboxes that run Linux (Ubuntu), Windows, or macOS.

First, create your API key:

Go to cua.ai/signin
Navigate to Dashboard > API Keys > New API Key to create your API key
Important: Copy and save your API key immediately - you won't be able to see it again (you'll need to regenerate if lost)

Then, create your sandbox using either option:

Option 1: Via Website

Navigate to Dashboard > Sandboxes > Create Sandbox
Create a Small sandbox, choosing Linux, Windows, or macOS
Note your sandbox name

Option 2: Via CLI

Install the CUA CLI:

# macOS/Linux
curl -LsSf https://cua.ai/cli/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://cua.ai/cli/install.ps1 | iex"

cua auth login
cua sb create --os linux --size small --region north-america

Note your sandbox name and password from the output

Your Cloud Sandbox will be automatically configured and ready to use.

Run Linux desktop locally on macOS, Windows, or Linux hosts.

Install Docker Desktop or Docker Engine
Pull a CUA Docker image:

# XFCE (Lightweight) - recommended for most use cases
docker pull --platform=linux/amd64 trycua/cua-xfce:latest

# OR KASM (Full-Featured) - full Ubuntu desktop
docker pull --platform=linux/amd64 trycua/cua-ubuntu:latest

macOS hosts only - requires Lume CLI.

Install the Lume CLI:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"

Start a local Cua sandbox:

lume run macos-sequoia-cua:latest

Windows hosts only - requires Windows 10 Pro/Enterprise or Windows 11.

Enable Windows Sandbox
Install the pywinsandbox dependency:

pip install -U git+git://github.com/karkason/pywinsandbox.git

Windows Sandbox will be automatically configured when you run the CLI

Developer Quickstart

Using Computer

Connect to your Cua computer and perform basic interactions, such as taking screenshots or simulating user input.

Install the Cua computer Python SDK:

pip install cua-computer

Then, connect to your desired computer environment:

Set your CUA API key (same key used for model inference) and connect to your sandbox:

import os
from computer import Computer

os.environ["CUA_API_KEY"] = "sk_cua-api01_..."

computer = Computer(
    os_type="linux",  # or "windows" or "macos"
    provider_type="cloud",
    name="your-sandbox-name"  # from CLI or website
)
await computer.run() # Connect to the sandbox

from computer import Computer

computer = Computer(
    os_type="linux",
    provider_type="docker",
    image="trycua/cua-xfce:latest"  # or "trycua/cua-ubuntu:latest"
)
await computer.run() # Launch & connect to the sandbox

from computer import Computer

computer = Computer(
    os_type="macos",
    provider_type="lume",
    name="macos-sequoia-cua:latest"
)
await computer.run() # Launch & connect to the sandbox

from computer import Computer

computer = Computer(
    os_type="windows",
    provider_type="windows_sandbox"
)
await computer.run() # Launch & connect to the sandbox

Install and run cua-computer-server:

pip install cua-computer-server
python -m computer_server

Then, use the Computer object to connect:

from computer import Computer

computer = Computer(use_host_computer_server=True)
await computer.run() # Connect to the host desktop

Once connected, you can perform interactions:

try:
    # Take a screenshot of the computer's current display
    screenshot = await computer.interface.screenshot()
    # Simulate a left-click at coordinates (100, 100)
    await computer.interface.left_click(100, 100)
    # Type "Hello!" into the active application
    await computer.interface.type_text("Hello!")
finally:
    await computer.close()

TypeScript SDK Deprecated

The TypeScript interface is currently deprecated. We're working on version 0.2.0 with improved TypeScript support. In the meantime, please use the Python SDK.

Install the Cua computer TypeScript SDK:

npm install @trycua/computer

Then, connect to your desired computer environment:

Set your CUA API key (same key used for model inference):

export CUA_API_KEY="sk_cua-api01_..."

Then connect to your sandbox:

import { Computer, OSType } from '@trycua/computer';

const computer = new Computer({
  osType: OSType.LINUX,  // or OSType.WINDOWS or OSType.MACOS
  name: "your-sandbox-name"  // from CLI or website
});
await computer.run(); // Connect to the sandbox

import { Computer, OSType, ProviderType } from '@trycua/computer';

const computer = new Computer({
  osType: OSType.LINUX,
  providerType: ProviderType.DOCKER,
  image: "trycua/cua-xfce:latest"  // or "trycua/cua-ubuntu:latest"
});
await computer.run(); // Launch & connect to the sandbox

import { Computer, OSType, ProviderType } from '@trycua/computer';

const computer = new Computer({
  osType: OSType.MACOS,
  providerType: ProviderType.LUME,
  name: "macos-sequoia-cua:latest"
});
await computer.run(); // Launch & connect to the sandbox

import { Computer, OSType, ProviderType } from '@trycua/computer';

const computer = new Computer({
  osType: OSType.WINDOWS,
  providerType: ProviderType.WINDOWS_SANDBOX
});
await computer.run(); // Launch & connect to the sandbox

First, install and run cua-computer-server:

pip install cua-computer-server
python -m computer_server

Then, use the Computer object to connect:

import { Computer } from '@trycua/computer';

const computer = new Computer({ useHostComputerServer: true });
await computer.run(); // Connect to the host desktop

Once connected, you can perform interactions:

try {
  // Take a screenshot of the computer's current display
  const screenshot = await computer.interface.screenshot();
  // Simulate a left-click at coordinates (100, 100)
  await computer.interface.leftClick(100, 100);
  // Type "Hello!" into the active application
  await computer.interface.typeText("Hello!");
} finally {
  await computer.close();
}

Learn more about computers in the Cua computers documentation. You will see how to automate computers with agents in the next step.

Using Agent

Utilize an Agent to automate complex tasks by providing it with a goal and allowing it to interact with the computer environment.

Install the Cua agent Python SDK:

pip install "cua-agent[all]"

Choose how you want to access vision-language models for your agent:

Use CUA's inference API to access multiple model providers with a single API key (same key used for sandbox access). CUA VLM Router provides intelligent routing and cost optimization.

Use the agent with CUA models:

import os
from agent import ComputerAgent

os.environ["CUA_API_KEY"] = "sk_cua-api01_..."

agent = ComputerAgent(
    model="cua/anthropic/claude-sonnet-4.5",  # CUA-routed model
    tools=[computer],
    max_trajectory_budget=5.0
)

messages = [{"role": "user", "content": "Take a screenshot and tell me what you see"}]

async for result in agent.run(messages):
    for item in result["output"]:
        if item["type"] == "message":
            print(item["content"][0]["text"])

Available CUA models:

cua/anthropic/claude-sonnet-4.5 - Claude Sonnet 4.5 (recommended)
cua/anthropic/claude-opus-4.5 - Claude Opus 4.5 (enhanced agentic capabilities)
cua/anthropic/claude-haiku-4.5 - Claude Haiku 4.5 (faster, cost-effective)
cua/qwen/qwen3-vl-235b - Qwen3 VL 235B (large-scale vision-language tasks)

Benefits:

Single API key for multiple providers
Cost tracking and optimization
No need to manage multiple provider keys

Use your own API keys from model providers like Anthropic, OpenAI, or others.

Use the agent with your provider:

import os
from agent import ComputerAgent

# Set your provider API key
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..."  # For Anthropic
# OR
os.environ["OPENAI_API_KEY"] = "sk-..."  # For OpenAI

agent = ComputerAgent(
    model="anthropic/claude-sonnet-4-5-20250929",  # Direct provider model
    tools=[computer],
    max_trajectory_budget=5.0
)

messages = [{"role": "user", "content": "Take a screenshot and tell me what you see"}]

async for result in agent.run(messages):
    for item in result["output"]:
        if item["type"] == "message":
            print(item["content"][0]["text"])

Supported providers:

anthropic/claude-* - Anthropic Claude models
openai/gpt-* - OpenAI GPT models
openai/o1-* - OpenAI o1 models
huggingface-local/* - Local HuggingFace models
And many more via LiteLLM

See Supported Models for the complete list.

Learn more about agents in Agent Loops and available models in Supported Models.

Next Steps

Learn more about Cua computers and computer commands
Read about Agent loops, tools, and supported model providers
Join our Discord community for help
Try out Form Filling preset usecase

Was this page helpful?