Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/trycua/cua/llms.txt

Use this file to discover all available pages before exploring further.

Cua Sandbox gives you a full, isolated computer — not a container shell or a remote desktop session — through a single Python API. Each sandbox is a disposable machine that starts from a known state, runs whatever code or GUI automation your agent needs, and can be destroyed without touching the host. Because both the code half (sb.shell, sb.terminal) and the GUI half (sb.mouse, sb.keyboard, sb.screen) share one filesystem and one OS state, an agent can click through a UI workflow and then immediately inspect the files it produced using a shell command.

​
What is Cua Sandbox?

The cua-sandbox package (imported as cua) is the core SDK. The cua meta-package bundles cua-sandbox together with the agent framework and CLI so you can pip install cua and have everything in one step. The cua meta-package requires Python 3.12+. The cua-sandbox package alone requires Python 3.11+.

​
OS matrix

Cua Sandbox supports five operating systems across two execution modes: cloud (managed by cua.ai) and local (runs on your own hardware using Docker, QEMU, Lume, or Hyper-V).
ImageKindCloudLocal runtime
Image.linux()VM✅QEMU
Image.linux(kind='container')Container✅Docker Desktop
Image.macos()VM✅Lume (Apple Silicon)
Image.windows()VM✅QEMU / Hyper-V
Image.android()VM✅QEMU
BYOI (.qcow2, .iso)VM🔜 soon✅ QEMU
Linux containers share the host kernel and start faster. Full VMs boot their own kernel for higher OS fidelity. Choose containers for fast Linux CI work and VMs when behavior must match a real machine.

​
Minimal working example

The snippet below creates an ephemeral Ubuntu 24.04 VM, runs a shell command, and takes a screenshot — all in under ten lines. The sandbox is automatically destroyed when the async with block exits. 
import asyncio
from cua import Sandbox, Image

async def main():
    async with Sandbox.ephemeral(Image.linux()) as sb:
        result = await sb.shell.run("echo hello")
        print(result.stdout)          # hello
        screenshot = await sb.screenshot()
        print(f"captured {len(screenshot)} bytes")

asyncio.run(main())
Pass local=True to run on your own machine instead of the cloud: 
async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
    result = await sb.shell.run("uname -a")
    print(result.stdout)

​
Cloud vs local execution

import os
from cua import Sandbox, Image

# Set CUA_API_KEY in your environment or pass api_key= directly
async with Sandbox.ephemeral(
    Image.linux(),
    api_key=os.environ["CUA_API_KEY"],
    region="us-east-1",
) as sb:
    await sb.shell.run("echo running in cloud")
Cloud sandboxes are provisioned on cua.ai infrastructure. No local virtualization software is required.

​
Sandbox interfaces

Every Sandbox instance exposes the same set of interfaces regardless of the OS or runtime:
AttributePurpose
sb.shellRun shell commands, get stdout/stderr/returncode
sb.mouseClick, double-click, drag, scroll
sb.keyboardType text, press key combinations
sb.screenTake screenshots, query screen size
sb.clipboardRead and write clipboard text
sb.tunnelForward sandbox ports to localhost
sb.terminalOpen interactive PTY sessions
sb.windowQuery the active window title
sb.mobileAndroid touch and hardware-key control

Images

Configure OS type, install packages, copy files, and chain builder calls into a reproducible image spec.

Lifecycle

Understand ephemeral vs persistent sandboxes, context managers, reconnect, list, and delete.

Scale Out

Run dozens of sandboxes in parallel with asyncio.gather, Semaphore, and Queue patterns.

Secrets

Inject API keys and credentials at runtime without baking them into the image.

Build docs developers (and LLMs) love

Get started for freeTalk to us