Quickstart

Your first sandbox. Run a web server in a sandbox on your machine and call it.

Run a web server in a sandbox on your machine and call it. Sandboxes run locally by default, so the code passes no location.

Prerequisites#

• Python 3.11 or newer:

pip install cua-sandbox

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

cua runtime doctor
cua runtime setup

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", "/"),
    ) 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

The first start of an image pulls it, which 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 with cb run.

Next#

• Control the desktop and the browser
• Run services, sidecars and secrets
• Reach another machine