Quickstart

Install Cua, 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.

Run#

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

In a terminal it first shows a checklist: the cua CLI, the Cua Spaces app (on by default on macOS; pass --select spaces on Linux, -Select spaces on Windows), the cua-driver MCP and skill for your agents, and hosting this machine. 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.