Quickstart

Install the cua CLI (and the macOS-only Cua Spaces app), run a Linux desktop locally, and register it as your first Space.

Prerequisites#

• macOS, Linux or Windows. The Cua Spaces app for macOS needs macOS 26 or later.
• Docker, for the local Space.

For CLI-managed local Linux Spaces, use Docker (gVisor runsc, when installed, adds isolation) or QEMU. QEMU needs read/write access to /dev/kvm for hardware acceleration of same-architecture guests. The managed runtime is macOS-only.

Run#

curl -fsSL https://cua.ai/install.sh | sh

In a terminal it first shows a checklist: the cua CLI, the Cua Spaces app (macOS only, selected by default there), the cua-driver MCP and skill for your agents, and hosting this machine. On Linux and Windows the Spaces app is skipped. Then it signs you in and offers to set up your AI coding agents. Flags: --select ITEMS, --only ITEMS, --cli-only, --app-only, --mode host|client, --version X, --no-onboarding, --dry-run, --yes (-Select, -CliOnly, ... on Windows). GUI installers are on GitHub releases.

Start the canonical Linux image with a token:

TOKEN=$(openssl rand -hex 24)
docker run -d --name my-space -e CUA_ENV_TOKEN=$TOKEN -p 127.0.0.1:3211:3211 \
  ghcr.io/trycua/linux:24.04

Register it and run a command in it (use http://127.0.0.1:3211 and your $TOKEN):

import asyncio
import cua
 
async def main():
    spaces = cua.embedded().spaces()      # or cua.connect().spaces()
    info = await spaces.add("http://10.0.0.5:3211", "TOKEN", "lab")
    space = await spaces.space(info.id)
    out = await space.bash("uname -a", None)
    print(info.id, out.stdout)
 
asyncio.run(main())

Result#

The program prints the Space id (direct:127.0.0.1:3211) and the guest's uname -a. The Space is now in the shared registry, so the app and the CLI see it too:

cua --version
cua auth status
cua spaces ls

Clean up#

docker rm -f my-space

Next#

• Add a Space: create one locally or in the cloud, from any image.
• Stream a desktop.
• Use Spaces from an agent.
• Cua Bots: an example app of persistent bots, each with its own Space.