piperhex/remoteai/cua-sandboxes

cua sandboxes

A sandbox is a disposable computer: a container or VM on this machine. The cua CLI and the cua SDK (Python, TypeScript, Swift, Kotlin, Rust) share one runtime and one list of sandboxes.

Before you start

cua --version            # the Rust cua CLI
cua config get default.on   # where sandboxes run without --on (local unless changed)
cua runtime doctor       # local runtimes (containers, gVisor, QEMU, Lume); read-only

Local sandboxes need no account. Delete them when you are done.

Create

cua sb create linux --name dev                 # local (default): a gVisor container
cua sb create linux --kind vm --name dev       # local Linux VM (QEMU)
cua sb create macos --name mac                 # local macOS VM (Apple silicon, Lume)
cua sb create ghcr.io/org/image:tag --name x   # any OCI image
cua sb create --on direct:127.0.0.1:3211 --token TOKEN --name mine   # an existing machine running cua-spacesd

--on is where (local, direct:<addr>), --kind what (auto, container, vm), --runtime which engine (auto, gvisor, runc, qemu, lume). An impossible combination fails with invalid placement and lists the valid values. Local runtimes are set up on first use (cua runtime setup does it explicitly). Omit --name for a generated name. cua sb ls prints each sandbox's ref (local:dev, direct:host:port); every NAME argument takes a ref or a bare name that is unique across locations (--local narrows it). Add --json to any command for machine-readable output. exec, shell, cp, screenshots and GUI control go through cua-spacesd, so use an image that ships it (the linux alias does). Plain images still get lifecycle, logs and port-forward.

Use

cua sb ls                          # every location (--local filters)
cua sb exec dev -- uname -a        # run a command
cua sb shell dev                   # interactive shell
cua sb screenshot dev              # save a screenshot
cua sb vnc dev                     # open the desktop in a browser

For GUI work, select the sandbox once and use cua do (see the gui-automation skill):

cua do switch dev
cua do screenshot
cua do click 400 300

Clean up

cua sb rm dev --force              # delete
cua sb suspend dev                 # or pause it and `cua sb resume dev` later

From code (Python)

import asyncio, cua
async def main():
    c = cua.embedded()
    sb = await c.sandboxes().create(cua.SandboxCreateOptions(
        on="local",
        image="ghcr.io/trycua/linux:24.04", name="dev"))
    env = await sb.spacesd(None)
    out = await env.run(cua.SpacesdCommand(program="uname", args=["-a"]))
    print(out.stdout.decode())
    await sb.delete()
asyncio.run(main())

The TypeScript, Swift and Kotlin bindings expose the same objects (Cua, sandboxes(), Sandbox.spacesd()).

From the cua MCP server

When the cua MCP server is connected, prefer its tools: images_list (which images exist), sandbox_list, sandbox_create, sandbox_get, sandbox_delete, then the computer_* tools (screenshot, click, type, shell, file) against the sandbox.

Browse the web

Browse inside a sandbox, never in the user's own browser. Everything below is cua MCP tool calls; no other browser tool or setup is needed.

1. Pick an image: images_list {"browser": true} (the canonical

ghcr.io/trycua/linux:24.04 ships Chromium).

1. Create it with a browser: `sandbox_create {"browser": true, "url":

"https://example.com"}. It returns id, session and browser.target_id / browser.tab_id`.

1. Drive the browser with `call_tool {"space": <id>, "tool": <tool>,

"arguments": {"session", "target_id", "tab_id", ...}}`:

• read: get_browser_state {"snapshot_format": "semantic_v2"} returns

an outline and refs (p1:0); add "include_screenshot": true for an image;

• browser_navigate {"url"}, `browser_click {"ref", "delivery_mode":

"foreground"}, browser_type {"ref", "text", "replace": true} (text "\n" with "mode": "keystrokes" presses Enter), browser_pointer` (hover, scroll, drag);

• read again after every page change: refs are per snapshot.

To test a local app, run it in the sandbox (space_write, space_bash) and open http://127.0.0.1:<port>.

1. Logged-in sites: only when the user asks. teleport_browser_session

with the exact sites first returns what would move and a consent requirement; show it to the user and continue only after they approve. Never move a session without that approval.

1. Clean up: sandbox_delete {"name": <id>}.

From a terminal: cua images ls --browser, cua sb create --browser --open https://example.com, cua sb view <id> to watch.

Rules

• Never run destructive commands on the user's own machine when a sandbox

would do.

• Delete the sandboxes you created as soon as the task ends.
• Report the sandbox name you used so the user can inspect or remove it.