Your first cloud sandbox

In this walkthrough you start a Linux desktop sandbox in the Cua cloud, write a file into it, hash the file in the guest, check the hash on your computer, look at the desktop, and release the sandbox. You do it first with the cua CLI, then as a script.

Sandboxes run on your machine by default; --on cloud (or local=False in Python) sends the same calls to the cloud. To stay local, start with the Cua SDK quickstart.

The walkthrough uses the canonical Linux image, ghcr.io/trycua/linux:24.04, which ships cua-spacesd on port 3211. The CLI and SDK send shell, file and screenshot calls to it through the cloud gateway.

1. Sign in#

Install the cua CLI, then sign in:

curl -fsSL https://cua.ai/install.sh | sh
cua auth login
cua auth whoami

whoami verifies the session against the cloud. On a machine without a browser, use cua auth login --remote.

2. Start a sandbox with the CLI#

cua sb create ghcr.io/trycua/linux:24.04 --on cloud --name first-fleet

Canonical images keep warm capacity, so this usually takes seconds; the first start of another image can take a few minutes. Without a running cua daemon, the sandbox expires 15 minutes after the command unless you run cua sb keep-alive first-fleet, which is plenty for this walkthrough.

Write a file, hash it in the guest, and hash the same bytes locally:

printf 'pear\napple\npear\nbanana\n' > fruit.txt
cua sb cp fruit.txt first-fleet:/tmp/fruit.txt
cua sb exec first-fleet sha256sum /tmp/fruit.txt
shasum -a 256 fruit.txt

Both commands print d9359aad71bda9a11a4fd2e8d72044d6f0f77519c6b6fb30d251806febcfb4d0. Your computer computed the second value, so the check does not rely on the guest to verify itself.

Take a screenshot, or open the live desktop in your browser with the viewer:

cua sb screenshot first-fleet -o first-fleet.png
cua sb view first-fleet

Release the sandbox:

cua sb rm -f first-fleet

3. Do the same from a script#

Scripts read cloud credentials from the environment. Create an API key and export it (the secret is printed once):

cua auth keys create first-fleet

export CUA_CLIENT_ID="<client-id>"
export CUA_CLIENT_SECRET="<client-secret>"

The TypeScript example can also use your cua auth login session when no key is set.

curl -fsSLO https://cua.ai/docs-assets/scripts/first-cloud-fleet/first_cloud_fleet.py
uv run first_cloud_fleet.py

async with Sandbox.ephemeral(image, local=False, cpu=4, memory_mb=4096) as sandbox:
    await sandbox.files.write_text(SOURCE_PATH, SOURCE_TEXT)
    result = await sandbox.shell.run(f"sha256sum {SOURCE_PATH}")
    ...
    SCREENSHOT.write_bytes(await sandbox.screenshot())

A successful run prints:

Claimed ...
Verified SHA-256: d9359aad71bda9a11a4fd2e8d72044d6f0f77519c6b6fb30d251806febcfb4d0
Screenshot: .../first-cloud-fleet.png
Claim released

Both scripts release the sandbox even when a step fails. If a process is killed first, the sandbox expires on its own after its TTL (15 minutes by default). Idle managed pools are deleted after 30 minutes, or now with cua fleet pools gc; see Clean up leftovers.

What you built#

You ran a cloud sandbox from a registry image with no capacity setup. The CLI and the SDK reached cua-spacesd in the guest, and releasing the sandbox ended the charge.

Next steps#

• Fleets quickstart: apply a pool of your own and claim from it.
• Run sandboxes in the cloud: credentials, regions and options.
• Run a service in a sandbox and reach it from your machine.
• Manage sandbox lifecycle: named sandboxes, reconnecting, keep-alive.
• Control the desktop: screenshots, input and the viewer.