Create a Space with the Cua SDK

Create a Linux Space on your own machine from Python or TypeScript, run a command in it, take a screenshot, ask Cua Driver for its windows, watch it, and delete it.

A Space is a desktop your agents can use and you can watch. In this walkthrough you create one on your own machine from code, run a command in it, take a screenshot, ask Cua Driver which windows it sees, watch the desktop, and delete the Space. Nothing leaves your machine.

Requirements: Docker (or Podman or Colima) and about 4 GB of free memory.

1. Install#

curl -fsSL https://cua.ai/install.sh | sh   # the cua CLI
cua runtime doctor                          # checks the container engine

pip install cua

2. Create a Space and use it#

The program passes no location, so the Space runs on this machine: the canonical Linux desktop (ghcr.io/trycua/linux:24.04) in a container.

first_space.py

import asyncio
 
import cua
 
 
async def main():
    spaces = cua.embedded().spaces()
    created = await spaces.create(cua.SpaceCreateOptions())
    space = await spaces.space(created.space.id)
    print("space:", created.space.id)
 
    # Run a command.
    out = await space.bash("uname -sm", None)
    print(out.stdout.strip())
 
    # Take a screenshot.
    shot = await space.screenshot(None)
    with open("space.png", "wb") as f:
        f.write(shot.image)
    print("screenshot: space.png")
 
    # Ask Cua Driver in the Space which windows are open.
    windows = await space.call_tool("list_windows", None, None, None)
    print("driver:", "error" if windows.is_error else "ok")
 
    # Delete the Space. Comment this out to keep it and watch it (step 3).
    await spaces.delete(created.space.id)
 
 
asyncio.run(main())

Run it with python first_space.py or npx tsx first-space.ts. The first run pulls the image, which can take a few minutes.

space: local:space-1a2b3c
Linux x86_64
screenshot: space.png
driver: ok

space.png holds the desktop. On Apple silicon uname prints aarch64.

3. Watch it#

Keep the Space (comment out the delete line), run the program again, then open its desktop in your browser with the id it printed:

cua sb view local:space-1a2b3c

The Cua Spaces app lists the same Space, since the app, the CLI and the SDK share one registry.

4. Clean up#

The program deletes its Space. One you kept goes with:

cua spaces delete local:space-1a2b3c

cua spaces ls shows what is left.

Next#

Reach another machine: connect the SDK to any machine that runs cua-spacesd, by address and token.
Host Spaces on your spare Mac: let your laptop create Spaces on another machine, over the relay, ssh or Tailscale.
Add a Space: any image, progress, GPUs.

2. Create a Space and use it#

The program passes no location, so the Space runs on this machine: the canonical Linux desktop (ghcr.io/trycua/linux:24.04) in a container.

first_space.py

import asyncio
 
import cua
 
 
async def main():
    spaces = cua.embedded().spaces()
    created = await spaces.create(cua.SpaceCreateOptions())
    space = await spaces.space(created.space.id)
    print("space:", created.space.id)
 
    # Run a command.
    out = await space.bash("uname -sm", None)
    print(out.stdout.strip())
 
    # Take a screenshot.
    shot = await space.screenshot(None)
    with open("space.png", "wb") as f:
        f.write(shot.image)
    print("screenshot: space.png")
 
    # Ask Cua Driver in the Space which windows are open.
    windows = await space.call_tool("list_windows", None, None, None)
    print("driver:", "error" if windows.is_error else "ok")
 
    # Delete the Space. Comment this out to keep it and watch it (step 3).
    await spaces.delete(created.space.id)
 
 
asyncio.run(main())

Run it with python first_space.py or npx tsx first-space.ts. The first run pulls the image, which can take a few minutes.

space: local:space-1a2b3c
Linux x86_64
screenshot: space.png
driver: ok

space.png holds the desktop. On Apple silicon uname prints aarch64.