Cua Docs

Your first local sandbox

Create a local Linux sandbox with Docker, run one command, and save a screenshot.

In this tutorial, you create an ephemeral Linux sandbox on your machine, run uname -a inside it, touch the sandbox clipboard, and save a screenshot from the sandbox to your current directory.

Prerequisites: Python 3.12 or 3.13 and Docker Desktop or Docker Engine.

This tutorial does not currently work. The published trycua/cua-xfce:latest runs computer-server bound to 127.0.0.1:8000 inside the container (computer_server/cli.py:34 defaults --host to 127.0.0.1), so Docker's published port mapping forwards to nothing and the script fails with TimeoutError: Container <name> not ready after 120s. The image needs rebuilding. In the meantime, drop kind="container" and use Image.linux(), which boots as a VM under QEMU and does not go through that image. It needs qemu-system-x86_64 installed instead of Docker — see Choose and build a sandbox image.

Install the SDK#

Open a terminal and install the Python SDK:

pip install cua

Create the script#

Create a file named 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:
        result = await sb.shell.run("uname -a")
        print(result.stdout)
 
        await sb.clipboard.set("Hello from the sandbox clipboard")
        value = await sb.clipboard.get()
        print(value)
 
        screenshot = await sb.screenshot()
        with open("screenshot.png", "wb") as f:
            f.write(screenshot)
        print("Screenshot saved to screenshot.png")
 
asyncio.run(main())

Run it#

Run the script from the same directory:

python first_sandbox.py

You should see a Linux kernel string and the clipboard value printed in your terminal.

You should also see a new file named screenshot.png in the current directory.

What just happened#

Sandbox.ephemeral(..., local=True) created a Linux desktop container through Docker on your machine. The script ran uname -a inside that container, printed the command output, changed and read the sandbox desktop clipboard, took a screenshot, and wrote it to screenshot.png.

When the async with block exited, the sandbox destroyed itself. No cleanup is needed.

Next steps#