Cua Docs

Run code and drive the GUI in a sandbox

Spin up a cloud Linux sandbox, run code and a GUI action against it with the Python SDK, then let it tear down.

Run code and drive the GUI in a sandbox

In this tutorial, you create an ephemeral cloud Linux sandbox, run Python code inside it, set and read the sandbox clipboard, and save a screenshot from the sandbox to your current directory.

Prerequisites: Python 3.12 or 3.13. A Cua API key from cua.ai under Dashboard > API Keys > New API Key. No Anthropic key is needed.

Sign in and create an API key

Sign in at cua.ai.

Open Dashboard > API Keys > New API Key.

Copy the API key immediately. You will use it in your terminal in the next step.

Install the SDK

Open a terminal and install the Python SDK:

pip install cua

Set your API key

Set CUA_API_KEY in the same terminal:

export CUA_API_KEY=sk_cua-...

Replace sk_cua-... with the API key you copied from the dashboard.

Create the script

Create a file named drive_sandbox.py:

import asyncio
from cua import Sandbox, Image
 
async def main():
    async with Sandbox.ephemeral(Image.linux()) as sb:
        result = await sb.shell.run("python3 -c 'print(1 + 1)'")
        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 drive_sandbox.py

You should see output like this:

2
 
Hello from the sandbox clipboard
Screenshot saved to screenshot.png

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

What just happened

Sandbox.ephemeral(Image.linux()) created a cloud Linux sandbox. sb.shell.run("python3 -c 'print(1 + 1)'") executed code inside the cloud container and returned a CommandResult with stdout, stderr, returncode, and the success boolean property. The script printed result.stdout.

sb.clipboard.set(...) changed the sandbox desktop clipboard state. sb.clipboard.get() read that GUI state back as a string. sb.screenshot() captured the sandbox display as PNG bytes and wrote them to screenshot.png.

When the async with block exited, the sandbox destroyed itself. No agent was involved.

Next steps