Quickstart

Run a web server in a sandbox on your machine and call it. The cloud variant changes one line: local=False.

Prerequisites#

• Python 3.11 or newer:

pip install cua-sandbox

• Locally, a container engine (Docker, Podman or Colima). Check the host and install what is missing:

cua runtime doctor
cua runtime setup

• For the cloud, sign in once with cua auth login (credentials).

Run#

import asyncio
 
from cua_sandbox import Image, Sandbox, http
 
 
async def main():
    async with Sandbox.ephemeral(
        Image.from_registry("python:3.12-slim"),
        command=["python", "-m", "http.server", "8000"],
        services={"web": 8000},
        wait_for=http("web", "/"),
        local=True,
    ) as sb:
        print((await sb.service("web").request("GET", "/")).status_code)
        print(await sb.service("web").url())
 
 
asyncio.run(main())

Result#

200
http://127.0.0.1:53817

In the cloud the URL is a short-lived signed https:// URL, and the first start of an image can take a few minutes.

Clean up#

Sandbox.ephemeral deletes the sandbox when the block exits. A CLI sandbox stays until you remove it: cua sb rm web -f. cua cache du shows what images and sandboxes take on disk (Disk usage).

Images#

Pass any registry reference. Each official tag resolves to the variant the backend runs. Linux images run as user cua with passwordless sudo; open the desktop in the browser with cua sb view NAME (Browser view). Full list: image catalog details.

Image.linux() is the Linux container and Image.linux(kind="vm") the same desktop as a VM. Image.windows() is a Windows Server 2022 VM, amd64, no license included. Image.macos() is Tahoe and Image.macos("15") Sequoia, both local only on Apple silicon.

Adapter benchmark images#

Each has a container tag and a -disk VM tag, and runs locally or in the cloud with cb run.

Next#

• Control the desktop
• Run a service
• Run sandboxes in the cloud