Use Spaces from code

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. Then start from a full agent app in TypeScript, Rust or Swift.

This walkthrough is for developers. A Space is a desktop your agents can use and you can watch. 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.

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.

Examples in other languages#

Cua Bots is the featured example, in SwiftUI. The OpenKoalaBots samples build a smaller agent app three times, in TypeScript, Rust (Tauri) and Swift, so you can start from the language you ship in. Each one runs named bots as long-lived agent threads on a shared Space, streams the Space's desktop next to the thread, sends files into it and runs routines.

Source#

All three pass one headless test, examples/openkoalabot-example-scenario.

Run one#

From a clone of trycua/cua. The samples build the cua SDK from source, so you need Rust.

(cd libs/cua && cargo build --release -p cua-sdk)
(cd libs/cua/typescript && npm ci && npm run stage:uniffi && npm run build && npm run build:browser)
cd examples/openkoalabot-example-ts
npm ci && npm run build && npm run build:web
npm run serve    # open the URL it prints

Each app needs a Space: create one with New Space, or add one by address.

Where each part is explained#

Next#

• Reach another machine: connect the SDK to any machine that runs cua-spacesd, by address and token.
• Add a machine: let your laptop create Spaces on another machine, over the relay, ssh or Tailscale.
• Create a Space: any image, progress, GPUs.
• Space kinds: pass kind (container, vm or microvm) to SpaceCreateOptions.