Using the Computer SDK

Python Version Compatibility

Cua packages require Python 3.12 or 3.13. Python 3.14 is not currently supported due to dependency compatibility issues (pydantic-core/PyO3 compatibility). If you encounter build errors on Python 3.14, please use Python 3.13 or earlier.

The Computer SDK lets you connect to your sandbox and perform basic interactions like taking screenshots, clicking, and typing. This is an important verification step before adding AI agents.

Installation

Using uv (recommended):

uv pip install cua-computer

Or with pip:

pip install cua-computer

npm install @trycua/computer

Connect to Your Sandbox

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

import os
from computer import Computer
import asyncio

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

computer = Computer(
    os_type="linux",  # or "windows" or "macos"
    provider_type="cloud",
    name="your-sandbox-name"  # from CLI or website
)

async def main():
    await computer.run()  # Connect to the sandbox

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

asyncio.run(main())

from computer import Computer
import asyncio

computer = Computer(
    os_type="linux",
    provider_type="docker",
    image="trycua/cua-xfce:latest"  # or "trycua/cua-ubuntu:latest"
)

async def main():
    await computer.run()  # Launch & connect to the sandbox

    try:
        screenshot = await computer.interface.screenshot()
        await computer.interface.left_click(100, 100)
        await computer.interface.type_text("Hello!")
    finally:
        await computer.disconnect()

asyncio.run(main())

from computer import Computer
import asyncio

computer = Computer(
    os_type="linux",
    provider_type="docker",
    image="trycua/cua-qemu-linux:latest",
    storage="~/cua-storage/linux",
    run_opts={
        "devices": ["/dev/kvm"],  # Optional but recommended
    },
)

async def main():
    await computer.run()  # Boot from golden image

    try:
        screenshot = await computer.interface.screenshot()
        await computer.interface.left_click(100, 100)
        await computer.interface.type_text("Hello!")
    finally:
        await computer.disconnect()

asyncio.run(main())

from computer import Computer
import asyncio

computer = Computer(
    os_type="windows",
    provider_type="docker",
    image="trycua/cua-qemu-windows:latest",
    storage="~/cua-storage/windows",
    run_opts={
        "devices": ["/dev/kvm"],  # Optional but recommended
    },
)

async def main():
    await computer.run()  # Boot from golden image

    try:
        screenshot = await computer.interface.screenshot()
        await computer.interface.left_click(100, 100)
        await computer.interface.type_text("Hello!")
    finally:
        await computer.disconnect()

asyncio.run(main())

from computer import Computer
import asyncio

computer = Computer(
    os_type="android",
    provider_type="docker",
    image="trycua/cua-qemu-android:latest",
    timeout=150,  # Emulator needs more time to boot
    run_opts={
        "devices": ["/dev/kvm"],  # Required for Android emulator
        "env": {
            "EMULATOR_DEVICE": "Samsung Galaxy S10",
        },
    },
)

async def main():
    await computer.run()  # Launch & connect to Android emulator

    try:
        screenshot = await computer.interface.screenshot()
        await computer.interface.left_click(100, 100)
        await computer.interface.type_text("Hello!")
    finally:
        await computer.disconnect()

asyncio.run(main())

from computer import Computer
import asyncio

computer = Computer(
    os_type="macos",
    provider_type="lume",
    name="macos-sequoia-cua:latest"
)

async def main():
    await computer.run()  # Launch & connect to the sandbox

    try:
        screenshot = await computer.interface.screenshot()
        await computer.interface.left_click(100, 100)
        await computer.interface.type_text("Hello!")
    finally:
        await computer.disconnect()

asyncio.run(main())

from computer import Computer
import asyncio

computer = Computer(
    os_type="windows",
    provider_type="windows_sandbox"
)

async def main():
    await computer.run()  # Launch & connect to the sandbox

    try:
        screenshot = await computer.interface.screenshot()
        await computer.interface.left_click(100, 100)
        await computer.interface.type_text("Hello!")
    finally:
        await computer.disconnect()

asyncio.run(main())

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
import asyncio

computer = Computer(use_host_computer_server=True)

async def main():
    await computer.run()  # Connect to the host desktop

    try:
        screenshot = await computer.interface.screenshot()
        await computer.interface.left_click(100, 100)
        await computer.interface.type_text("Hello!")
    finally:
        await computer.disconnect()

asyncio.run(main())

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.disconnect();
}

Common Operations

Operation	Python	TypeScript
Screenshot	`await computer.interface.screenshot()`	`await computer.interface.screenshot()`
Left click	`await computer.interface.left_click(x, y)`	`await computer.interface.leftClick(x, y)`
Right click	`await computer.interface.right_click(x, y)`	`await computer.interface.rightClick(x, y)`
Double click	`await computer.interface.double_click(x, y)`	`await computer.interface.doubleClick(x, y)`
Type text	`await computer.interface.type_text("text")`	`await computer.interface.typeText("text")`
Press key	`await computer.interface.key("Enter")`	`await computer.interface.key("Enter")`
Scroll	`await computer.interface.scroll(x, y, clicks)`	`await computer.interface.scroll(x, y, clicks)`

Lifecycle Methods

computer.run() - Connect to an already-running sandbox
computer.start() - Start and connect to the sandbox (if not running)
computer.disconnect() - Disconnect but keep sandbox running
computer.stop() - Fully stop the sandbox and disconnect

Managing Cloud Sandboxes

For cloud sandboxes, you can programmatically manage VM lifecycle using the CloudProvider:

import os
import asyncio
from computer.providers.cloud.provider import CloudProvider

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

async def main():
    provider = CloudProvider()

    # List all your sandboxes
    sandboxes = await provider.list_vms()
    for vm in sandboxes:
        print(f"{vm['name']}: {vm['status']}")

    # Start a sandbox
    await provider.run_vm("my-sandbox")

    # Check sandbox status
    info = await provider.get_vm("my-sandbox")
    print(f"Status: {info['status']}")

    # Stop when done
    await provider.stop_vm("my-sandbox")

asyncio.run(main())

import { CloudProvider } from "@trycua/computer";

const provider = new CloudProvider({
  apiKey: process.env.CUA_API_KEY!,
});

async function main() {
  // List all your sandboxes
  const sandboxes = await provider.listVMs();
  for (const vm of sandboxes) {
    console.log(`${vm.name}: ${vm.status}`);
  }

  // Start a sandbox
  await provider.runVM("my-sandbox");

  // Check sandbox status
  const info = await provider.getVM("my-sandbox");
  console.log(`Status: ${info.status}`);

  // Stop when done
  await provider.stopVM("my-sandbox");
}

main();

Available operations:

Operation	Description
`list_vms()`	List all sandboxes in your account
`get_vm(name)`	Get status and details for a specific sandbox
`run_vm(name)`	Start a sandbox (hot-start in under 1 second)
`stop_vm(name)`	Stop a running sandbox
`restart_vm(name)`	Restart a sandbox

This is useful for orchestrating multiple sandboxes, building CI/CD pipelines, or programmatically managing sandbox lifecycle.

Next Step

Once you've verified your sandbox connection works, proceed to Using the Agent SDK to add AI automation.

For more details on available commands, see the Computer SDK Reference reference.

Was this page helpful?