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 an agent a full, isolated computer it can both run code in and drive through the graphical interface. In this tutorial you create an ephemeral Linux sandbox on your local machine using Docker, run a command inside it, interact with the sandbox clipboard, and save a screenshot to disk. When the script exits, the sandbox destroys itself automatically — no cleanup required.
Prerequisites: Python 3.11 or later (3.12/3.13 recommended) and Docker Desktop or Docker Engine running on your machine.

​
Steps

1

Install the SDK

Open a terminal and install the Python SDK:
pip install cua
This installs the cua meta-package, which includes cua-sandbox, cua-agent, and cua-cli. If you only need the sandbox SDK (and want a wider Python version range), you can install cua-sandbox directly — it supports Python 3.11–3.13.
2

Create the script

Create a file named first_sandbox.py:
first_sandbox.py
import asyncio
from cua import Sandbox, Image

async def main():
    async with Sandbox.ephemeral(
        Image.linux(kind="container"),
        local=True,
    ) as sb:
        # Run a shell command inside the sandbox
        result = await sb.shell.run("uname -a")
        print(result.stdout)

        # Read and write the sandbox clipboard
        await sb.clipboard.set("Hello from the sandbox clipboard")
        value = await sb.clipboard.get()
        print(value)

        # Take a screenshot of the sandbox desktop
        screenshot = await sb.screenshot()
        with open("screenshot.png", "wb") as f:
            f.write(screenshot)
        print("Screenshot saved to screenshot.png")

asyncio.run(main())
Image.linux(kind="container") selects a lightweight Linux desktop container as the sandbox’s starting environment. Passing local=True tells the SDK to use your local Docker daemon rather than the cloud backend.
3

Run the script

Run the script from the same directory:
python first_sandbox.py
You should see output like:
Linux sandbox-abc123 6.6.0 #1 SMP ... x86_64 GNU/Linux
Hello from the sandbox clipboard
Screenshot saved to screenshot.png
A file named screenshot.png will appear in your current directory showing the sandbox desktop.
4

Understand what happened

Sandbox.ephemeral(..., local=True) created a Linux desktop container through Docker. The script ran uname -a inside that container, printed the output, changed and read the sandbox clipboard, took a screenshot of the virtual desktop, and wrote it to screenshot.png.When the async with block exited, the sandbox destroyed itself. Ephemeral sandboxes are temporary by design — they accumulate state only while they live, and leave nothing behind.

​
What the sandbox gives you

The sandbox exposes two complementary halves of the same computer: The code half lets you run programs inside the sandbox: 
# Shell commands
result = await sb.shell.run("ls -la /home")

# Interactive PTY
pty = await sb.computer.pty()
await pty.write("top\n")

# Clipboard
await sb.clipboard.set("some text")
text = await sb.clipboard.get()
The GUI half lets you drive the sandbox like a desktop computer: 
# Take a screenshot
screenshot = await sb.screenshot()

# Mouse
await sb.mouse.click(100, 200)
await sb.mouse.double_click(300, 400)

# Keyboard
await sb.keyboard.type("Hello!")
await sb.keyboard.press("Return")

# Scroll
await sb.mouse.scroll(100, 200, direction="down")
Because both halves point to the same machine, you can mix them freely within one task — run a shell command to create a file, then open that file through the GUI.

​
Sandbox images

An Image is the immutable description of the sandbox’s starting environment. It defines the OS type, installed packages, environment variables, and setup commands. Multiple Image variants are available: 
Image.linux(kind="container")   # Fast Linux desktop via Docker
Image.linux(kind="vm")          # Full Linux VM via QEMU
Image.macos()                   # macOS VM (Apple Silicon, via Lume)
Image.windows()                 # Windows VM via QEMU/Hyper-V
Image.android()                 # Android VM via QEMU

​
Ephemeral vs. persistent sandboxes

By default, sandboxes are ephemeral — they are destroyed when the async with block exits. For work that needs to survive process restarts, you can create a named persistent sandbox:
persistent_sandbox.py
from cua import Sandbox, Image

# Create once, identified by name
sandbox = await Sandbox.create("my-workspace", Image.linux(kind="container"), local=True)

# Connect to it later in a different process
async with Sandbox.connect("my-workspace") as sb:
    result = await sb.shell.run("ls /my-project")

​
Next steps

How sandboxes work

Understand isolation, runtime backends, images, snapshots, forks, and lifecycle patterns.

Sandbox lifecycle

Learn how to create, connect, snapshot, fork, and delete sandboxes.

Choose a sandbox image

Pick and customize an Image for your OS and workload.

Sandbox SDK reference

Complete API reference for all sandbox methods and types.

Build docs developers (and LLMs) love

Get started for freeTalk to us