Cua Docs

Your first cloud sandbox

Create a cloud Linux sandbox with the Python SDK, run one command, and save a screenshot.

Your first cloud sandbox

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

Prerequisites: Python 3.12 or 3.13. A free account at cua.ai for cloud sandboxes.

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 first_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("uname -a")
        print(result.stdout)
 
        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 printed in your terminal.

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 container. The script ran uname -a inside that container, printed the command output, 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