Cua SDK

Build agentic applications and workflows on isolated Linux, Windows and macOS desktops on your machine, or on any machine that runs cua-spacesd.

Build agentic apps and workflows on real desktops. Cua SDK gives your application isolated Linux, Windows and macOS machines on your own computer, runs the agents you already use inside them, and streams everything back so your users can watch, take over or teleport work in and out. Cua Driver is how the agents drive each desktop.

Sandboxes run on this machine by default: leave out local= (or on) and the SDK uses Docker or Podman (gVisor when installed), QEMU, or Lume on Apple silicon. Any OCI image works.

from cua_sandbox import Image, Sandbox, http
 
async with Sandbox.ephemeral(
    Image.from_registry("python:3.12-slim"),
    command=["python", "-m", "http.server", "8000"],
    services={"web": 8000},
    wait_for=http("web", "/"),
) as sb:
    print((await sb.service("web").request("GET", "/")).status_code)  # 200

Setup: cua runtime doctor shows what this host has and cua runtime setup installs what is missing (Choose where sandboxes run). Containers run the host's architecture (others run emulated); macOS runs in Lume VMs on Apple silicon.

Reach another machine#

Any machine that runs cua-spacesd, such as a spare Mac, a server on your LAN or Tailscale, or a container you started, connects directly by address and env token. Nothing is created or deleted:

from cua_sandbox import Sandbox
 
async with Sandbox.connect(url="http://10.0.0.5:3211", token="TOKEN") as sb:
    print((await sb.shell.run("uname -a")).stdout)

The CLI does the same with cua sb create --on direct:10.0.0.5:3211 --token "$CUA_ENV_TOKEN". To share machines across a team, use Teams: $30 per seat a month, from 1 seat. See pricing.

Packages#

None of them includes an agent: your own code or agent loop drives the sandbox. See Use Cua in your own harness.

How it fits together#

The SDK is one Rust core with generated bindings, running in your process or in cua daemon. It starts local runtimes itself and connects to other machines directly. Nothing needs to run inside the image; images that ship cua-spacesd (such as Image.linux()) also get the computer interfaces: sb.shell, sb.files, sb.screen, sb.mouse, sb.keyboard. See How sandboxes work.

To control the machine you are on instead of a sandbox, use Cua Driver.

Next: Your first sandbox.