Attach to or run cua-spacesd

Use any machine that runs cua-spacesd as a sandbox, run and configure cua-spacesd yourself, and publish it through the relay.

cua-spacesd serves the desktop, shell, files and media of a machine (Control the desktop). This page covers attaching to one you did not create and running it yourself.

Attach to any spacesd#

Any machine that runs spacesd can be used as a sandbox: a container you started, a machine on your LAN, or one behind the relay. You need its address and env token. Nothing is created or deleted.

export CUA_ENV_TOKEN=$(openssl rand -hex 24)
docker run -d --name envbox --shm-size=512m -e CUA_ENV_TOKEN \
  -p 127.0.0.1:3211:3211 ghcr.io/trycua/linux:24.04

cua spacesd caps http://127.0.0.1:3211      # version, OS, features
cua spacesd shell http://127.0.0.1:3211
cua sb create --on direct:127.0.0.1:3211 --token "$CUA_ENV_TOKEN" --name envbox
cua sb rm envbox          # forgets the record; the machine keeps running

In Python, Sandbox.connect(url="http://127.0.0.1:3211", token=...) returns a regular Sandbox; in TypeScript, embedded().spacesd(url, token) returns the typed spacesd client.

Addresses can be direct (http://10.0.0.5:3211), a sandbox's env service URL, or a relay URL (https://<relay>/m/<machine-id>). To run spacesd on a machine, see Run spacesd yourself; its RPCs are in the protocol reference.

Run spacesd yourself#

On a machine you own, cua host setup installs spacesd as a service (Unattended access). To run the binary by hand:

CUA_ENV_TOKEN=... cua-spacesd            # same as `cua-spacesd serve`
cua-spacesd --print-config               # effective config, never the token

A non-loopback bind without a token is refused. Logs go to stderr (CUA_ENV_LOG, default info). Other subcommands: join, token-sync (Unix), doctor and build-info; cua-spacesd --help lists every flag.

Viewer architecture#

One web app and protocol (crate cua-spacesd-html5), served two ways:

The page itself is public; every call it makes is authorized by the viewer ticket. The viewer ships with Cua Spaces (source-available, FSL-1.1-MIT): the cua in the Spaces apps runs cua viewer, and the open source cua hands the command to it.

Tokens#

spacesd takes the first non-empty token from --token, CUA_ENV_TOKEN, then --token-file. Clients send it as authorization: Bearer <token> or x-cua-env-authorization (use it when a gateway keeps authorization for itself).

Relay (join)#

cua-spacesd join serves on loopback and publishes the machine through a cua-relay over one outbound WebSocket, so a machine behind NAT needs no inbound port. Clients reach it at https://<relay>/m/<machine-id>/ (Spaces: relay:<machine-id>).

CUA_ENV_TOKEN=... cua-spacesd join --relay wss://relay.example --relay-token-file ~/.cua/relay-token

Install as a service#

libs/cua-spacesd/packaging/install.sh (--binary, --version, --token, --token-file, --no-service, --dry-run) installs the binary and one of: