Quickstart

Install the cua CLI and the Cua Spaces app (macOS, Windows or Linux), 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. On Windows the app is a preview. See Install.
• Docker, for the local Space.

Cua Spaces on Linux#

The supported Linux package is the .deb on Ubuntu 24.04 (x64 and arm64), installed with sudo apt install ./cua-spaces_<version>_<arch>.deb. It is sandboxed, installs the confirmation prompt the Keyvault needs, and sudo apt remove cua-spaces turns off what the app set up (see Unattended access). Other distributions and desktops are untested.

The AppImage is a portable build, not a supported one. It cannot use the browser sandbox (it starts with --no-sandbox), and without the system's confirmation prompt the Keyvault is unavailable. Use it to try Cua Spaces without installing; install the .deb to keep it.

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 (selected by default on macOS, Linux and 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. See Install for per-platform steps.

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.