Cua DocumentationCua Computers
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.
Cloud Sandbox
Easiest & safest way to get started - works on any host OS
This is a Cloud Sandbox running the Computer Server. Get a container at trycua.com.
from computer import Computer
computer = Computer(
os_type="linux",
provider_type="cloud",
name="your-sandbox-name",
api_key="your-api-key"
)
await computer.run() # Connect to the sandboximport { Computer, OSType } from '@trycua/computer';
const computer = new Computer({
osType: OSType.LINUX,
name: "your-sandbox-name",
apiKey: "your-api-key"
});
await computer.run(); // Connect to the sandboxLinux on Docker
Run Linux desktop locally on macOS, Windows, or Linux hosts
Cua provides two Docker images for running Linux desktops:
Recommended for most use cases - lightweight XFCE desktop with Firefox
-
Install Docker Desktop or Docker Engine
-
Pull the CUA XFCE image
docker pull --platform=linux/amd64 trycua/cua-xfce:latest- Connect with Computer
from computer import Computer
computer = Computer(
os_type="linux",
provider_type="docker",
image="trycua/cua-xfce:latest",
name="my-xfce-container"
)
await computer.run() # Launch & connect to Docker sandboxFull-featured Ubuntu desktop with additional applications
-
Install Docker Desktop or Docker Engine
-
Build or pull the CUA KASM image
# Option 1: Pull from Docker Hub
docker pull --platform=linux/amd64 trycua/cua-ubuntu:latest
# Option 2: Build locally
cd libs/kasm
docker build -t cua-ubuntu:latest .- Connect with Computer
from computer import Computer
computer = Computer(
os_type="linux",
provider_type="docker",
image="trycua/cua-ubuntu:latest",
name="my-kasm-container"
)
await computer.run() # Launch & connect to Docker sandboxWindows Sandbox
Windows hosts only - requires Windows 10 Pro/Enterprise or Windows 11
- Enable Windows Sandbox
- Install pywinsandbox dependency
pip install -U git+git://github.com/karkason/pywinsandbox.git- Connect with Computer
from computer import Computer
computer = Computer(
os_type="windows",
provider_type="winsandbox",
ephemeral=True # Windows Sandbox is always ephemeral
)
await computer.run() # Launch & connect to Windows SandboxmacOS VM
macOS hosts only - requires Lume CLI
- Install lume cli
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"- Start a local Cua macOS VM
lume run macos-sequoia-cua:latest- Connect with Computer
from computer import Computer
computer = Computer(
os_type="macos",
provider_type="lume",
name="macos-sequoia-cua:latest"
)
await computer.run() # Launch & connect to the sandboxYour 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.
pip install cua-computer-server
python -m computer_serverConnect with:
computer = Computer(use_host_computer_server=True)
await computer.run() # Connect to the host desktopWas this page helpful?