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 using either the website or CLI.

Option 1: Via CLI (Recommended)

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

Option 2: Via Website

Go to cua.ai/signin
Navigate to Dashboard > Containers > Create Instance
Create a Small sandbox, choosing Linux, Windows, or macOS
Note your sandbox name and API key

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

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:

from computer import Computer

computer = Computer(
    os_type="linux",  # or "windows" or "macos"
    provider_type="cloud",
    name="your-sandbox-name",  # from CLI or website
    api_key="your-api-key"
)
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:

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
  apiKey: "your-api-key"
});
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]"

Then, use the ComputerAgent object:

from agent import ComputerAgent

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

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

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

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?