Host Spaces
cua.env.v1 HostSpacesService: Spaces a host creates for its owner's devices through the relay.
cua.env.v1 HostSpacesService: Spaces a host creates for its owner's devices through the relay.
Spaces a machine set up with cua host setup --provide-spaces creates for its owner's enrolled devices: settings, capacity, create and delete. The host's cua-spacesd forwards each call to its cua daemon.
Source: libs/cua/proto/cua/env/v1/host.proto.
cua.env.v1.HostSpacesService
Spaces a host provides: a machine set up with cua host setup --provide-spaces creates Spaces (macOS VMs with Lume on a Mac, Linux
containers with Docker, whatever else runs locally) for the owner's
enrolled devices and the accounts it is shared with, through the relay.
The host's cua-spacesd serves this service only in join mode with a host
policy, and only to relay-asserted editors (the owner, or an account on
the machine's allowlist) and the local token holder: a view-only share is
refused. It forwards each call to the host's cua daemon, which creates and
deletes the Spaces with its own runtimes, attaches each new Space to the
relay as its own machine, and records every create and delete in the
host's hash-chained audit log (~/.cua/host/spaces-audit.jsonl).
Providing Spaces never exposes the host's own desktop or files: with the
host setting share_desktop off, a relayed caller reaches only this
service and SystemService GetCapabilities / Health.
A host set up with cua host setup --direct <ip:port> --provide-spaces
serves this service on its direct listener too, without the relay: the
caller is the holder of the host's env token (the owner), and by default
only loopback, Tailscale (100.64.0.0/10, fd7a:115c:a1e0::/48) and private
LAN addresses may call it. A Space created with direct set is not
attached to the relay: the host forwards a TCP port on its own address
(HostSpace.direct_port) to the Space's cua-spacesd.
/cua.env.v1.HostSpacesService/GetHostSpaces, unary: GetHostSpacesRequest to GetHostSpacesResponse.
This host's settings, capacity, the Spaces it provides to the caller (every one for the owner) and, for the owner, its recent audit.
/cua.env.v1.HostSpacesService/CreateHostSpace, unary: CreateHostSpaceRequest to CreateHostSpaceResponse.
Creates one Space on this host and attaches it to the relay as the
machine the caller registered for it (attach). Fails with
RESOURCE_EXHAUSTED when the host is at capacity (two macOS VMs per
Mac, by Apple's license, or the host's max_spaces).
/cua.env.v1.HostSpacesService/DeleteHostSpace, unary: DeleteHostSpaceRequest to DeleteHostSpaceResponse.
Deletes a Space this host provides (its sandbox and its relay machine). The owner deletes any; another account only the ones it created.
/cua.env.v1.HostSpacesService/CancelHostSpace, unary: CancelHostSpaceRequest to CancelHostSpaceResponse.
Cancels a CreateHostSpace the caller started, by the relay machine
it registered for it (attach.machine_id): the create stops (an image
download, a boot) and what it made is removed; one that already
finished is deleted, since the caller gave up on it. Idempotent.
/cua.env.v1.HostSpacesService/SetHostSpacePower, unary: SetHostSpacePowerRequest to SetHostSpacePowerResponse.
Turns a Space this host provides off or on. Off stops it with its disk kept, freeing the host's memory (a runtime that cannot start it again, QEMU, suspends it instead); on boots it again and re-attaches it to its relay machine. The owner powers any; another account only the ones it created.
/cua.env.v1.HostSpacesService/DeleteCloudSpace, unary: DeleteCloudSpaceRequest to DeleteCloudSpaceResponse.
Deletes a Space in the owner's own cloud that this machine created (an AWS, Google Cloud or Modal sandbox, by the relay machine it joined as): its cloud resources, through this machine's ownership records, and its relay machine. Only the owner. Lets another of the owner's devices delete it permanently without the cloud's credentials. Works whether or not this machine provides Spaces.
cua/env/v1/host.proto#The host's two independent settings and its limits.
| Field | # | Type | Description |
|---|---|---|---|
share_desktop | 1 | bool | The host's own desktop is a Space too (screen, input, shell, files). |
provide_spaces | 2 | bool | The host accepts Space create, list and delete requests. |
max_spaces | 3 | uint32 | At most this many provided Spaces at once (0: no limit besides the runtimes' own). |
max_macos_vms | 4 | uint32 | At most this many macOS VMs at once on this Mac (Apple's license allows two; 0 on a host that cannot run macOS VMs). |
How much of one limit is in use.
| Field | # | Type | Description |
|---|---|---|---|
resource | 1 | string | spaces (every provided Space) or macos_vms (macOS VMs on this Mac, provided or not). |
used | 2 | uint32 | In use now. |
limit | 3 | uint32 | The limit (0: none). |
reason | 4 | string | Why the limit exists, for people ("Apple's macOS license allows two macOS VMs per Mac"). |
A Space this host provides.
| Field | # | Type | Description |
|---|---|---|---|
relay_machine | 1 | string | The relay machine the Space is reached as (relay:<machine>). |
local_space | 2 | string | The Space on the host (local:<name>). |
name | 3 | string | Display name. |
image | 4 | string | The image it runs, as requested. |
os | 5 | string | Guest OS family: linux, macos or windows (empty when unknown). |
kind | 6 | string | container or vm (empty when unknown). |
runtime | 7 | string | Engine: lume, runc, gvisor, qemu (empty when unknown). |
created_by | 8 | string | The account that created it (id, or email when the relay shares it). |
created_at_ms | 9 | int64 | When it was created (Unix milliseconds). |
direct_port | 10 | uint32 | A Space created with CreateHostSpaceRequest.direct: the TCP port on the host's own address that the host forwards to the Space's cua-spacesd (direct:<host address>:<direct_port>). 0 for a Space reached through the relay. |
direct_token | 11 | string | The Space's cua-spacesd token, set only in the CreateHostSpace response of a direct Space (the caller stores it like any direct Space's token). Empty otherwise. |
One line of the host's Spaces audit log.
| Field | # | Type | Description |
|---|---|---|---|
ts_ms | 1 | int64 | Unix milliseconds. |
action | 2 | string | create, delete, refused, or config. |
who | 3 | string | Who: an account (name <email> (id)), or local for this machine. |
space | 4 | string | The relay machine or Space the event is about. |
detail | 5 | string | Detail for people. |
Request for HostSpacesService.GetHostSpaces.
No fields.
Response for HostSpacesService.GetHostSpaces.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | This host's display name. |
os | 2 | string | The host's operating system (macos, linux, windows). |
settings | 3 | HostSpacesSettings | Settings and limits. |
capacity | 4 | repeated HostSpacesCapacity | Current use of each limit. |
spaces | 5 | repeated HostSpace | Spaces this host provides: every one for the owner, the caller's own otherwise. |
audit | 6 | repeated HostSpacesAuditEvent | The most recent audit events, newest first (the owner only). |
images | 7 | repeated string | Image aliases this host resolves (macos, linux, ...), for clients to offer. |
Request for HostSpacesService.CreateHostSpace.
| Field | # | Type | Description |
|---|---|---|---|
image | 1 | string | Image: a registry reference or an alias (macos, macos:26, linux). Empty uses the canonical Linux image. |
kind | 2 | string | "auto" (empty), "container" or "vm". |
runtime | 3 | string | "auto" (empty) or a runtime this host offers ("lume", "runc", ...). |
name | 4 | string | Name on the host. Empty generates space-<hex>. |
cpus | 5 | uint32 | vCPUs (0: the default). |
memory_mb | 6 | uint64 | Memory in MiB (0: the default). |
disk_gb | 7 | uint32 | Disk in GiB for a VM (0: the image's). |
attach | 8 | AttachRelayRequest | The relay machine the caller registered for this Space: the host attaches the new Space's driver to it (SystemService.AttachRelay), so the Space is reached as relay:<machine_id> and the host never holds an account credential. Empty when direct is set. |
direct | 9 | bool | Create the Space without the relay (a host set up with --direct): it is reached at the host's address on HostSpace.direct_port, with HostSpace.direct_token. attach must be empty. |
Response for HostSpacesService.CreateHostSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | HostSpace | The new Space. |
Request for HostSpacesService.DeleteHostSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The relay machine of the Space (or its local:<name> on the host). |
Response for HostSpacesService.DeleteHostSpace.
| Field | # | Type | Description |
|---|---|---|---|
message | 1 | string | What happened, for people. |
Request for HostSpacesService.DeleteCloudSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The relay machine the cloud Space joined as. |
Response for HostSpacesService.DeleteCloudSpace.
| Field | # | Type | Description |
|---|---|---|---|
message | 1 | string | What was deleted, for people. |
Request for HostSpacesService.CancelHostSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The relay machine the caller registered for the Space. |
Response for HostSpacesService.CancelHostSpace.
| Field | # | Type | Description |
|---|---|---|---|
message | 1 | string | What happened, for people: what was removed and what stays. |
Request for HostSpacesService.SetHostSpacePower.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The relay machine of the Space (or its local:<name> on the host). |
on | 2 | bool | True turns it on, false off. |
Response for HostSpacesService.SetHostSpacePower.
| Field | # | Type | Description |
|---|---|---|---|
state | 1 | string | "running", "suspended" or "stopped": the state it is in now. |
power | 2 | string | How it turns off: "stop" or "suspend". |
message | 3 | string | What happened, for people. |