Cua daemon: sandboxes and runtimes
cua.daemon.v1 SandboxService and RuntimeService: sandbox lifecycle across locations, checkpoints and forks, local pools, and the local runtimes and images.
The local cua daemon API (a Unix socket on the host, not cua-spacesd): sandbox lifecycle across locations; checkpoints of local sandboxes that new sandboxes fork from (ForkSandbox); local pools of ready sandboxes (ApplyPool, ListPools, DeletePool, claimed by a create that names one in local_pool); and the local runtimes (gVisor, runc, QEMU, Lume, Firecracker) and images it orchestrates. Spaces and the daemon's identity are on Daemon: Spaces and service.
Source: libs/cua/proto/cua/daemon/v1/sandboxes.proto, libs/cua/proto/cua/daemon/v1/checkpoints.proto, libs/cua/proto/cua/daemon/v1/pools.proto, libs/cua/proto/cua/daemon/v1/runtime.proto.
SandboxService#
cua.daemon.v1.SandboxService
Sandbox lifecycle across providers (local VMM, direct, contrib).
Sandboxes are daemon-agnostic: nothing here assumes cua-spacesd is installed in the guest.
SandboxService.ListSandboxes#
/cua.daemon.v1.SandboxService/ListSandboxes, unary: ListSandboxesRequest to ListSandboxesResponse.
Lists sandboxes known to the daemon.
SandboxService.CreateSandbox#
/cua.daemon.v1.SandboxService/CreateSandbox, unary: CreateSandboxRequest to CreateSandboxResponse.
Creates a sandbox where location says (local by default), or
connects to an existing machine (direct:<addr>).
SandboxService.CreateSandboxStream#
/cua.daemon.v1.SandboxService/CreateSandboxStream, server stream: CreateSandboxStreamRequest to CreateSandboxStreamResponse.
CreateSandbox, streaming progress events (pulling with bytes,
creating, booting, probes) in order, then exactly one result. A
failed create ends the stream with its status; closing it cancels.
SandboxService.CancelCreateSandbox#
/cua.daemon.v1.SandboxService/CancelCreateSandbox, unary: CancelCreateSandboxRequest to CancelCreateSandboxResponse.
Cancels a CreateSandbox of a named sandbox still running: the work
in flight stops (an image download, a boot) and what the
create made is deleted; a sandbox of that name that existed before is
never touched. Finished image downloads stay cached. Returns once the
clean-up is done. Idempotent: cancelled is false when no create of
that name was running. A CreateSandbox whose caller goes away (a
closed connection) is cleaned up the same way.
SandboxService.GetSandbox#
/cua.daemon.v1.SandboxService/GetSandbox, unary: GetSandboxRequest to GetSandboxResponse.
Returns one sandbox.
SandboxService.DeleteSandbox#
/cua.daemon.v1.SandboxService/DeleteSandbox, unary: DeleteSandboxRequest to DeleteSandboxResponse.
Deletes (or releases, or detaches from) a sandbox.
SandboxService.ConnectSandbox#
/cua.daemon.v1.SandboxService/ConnectSandbox, unary: ConnectSandboxRequest to ConnectSandboxResponse.
Reattaches to a sandbox by ref (a state file or an address) and keeps the handle in the daemon.
SandboxService.SuspendSandbox#
/cua.daemon.v1.SandboxService/SuspendSandbox, unary: SuspendSandboxRequest to SuspendSandboxResponse.
Suspends a sandbox (local: pause).
SandboxService.ResumeSandbox#
/cua.daemon.v1.SandboxService/ResumeSandbox, unary: ResumeSandboxRequest to ResumeSandboxResponse.
Resumes a suspended sandbox.
SandboxService.RestartSandbox#
/cua.daemon.v1.SandboxService/RestartSandbox, unary: RestartSandboxRequest to RestartSandboxResponse.
Restarts a sandbox.
SandboxService.ResizeSandbox#
/cua.daemon.v1.SandboxService/ResizeSandbox, unary: ResizeSandboxRequest to ResizeSandboxResponse.
Resizes a local VM.
SandboxService.KeepAlive#
/cua.daemon.v1.SandboxService/KeepAlive, unary: KeepAliveRequest to KeepAliveResponse.
Extends the lifetime of a provider sandbox that expires.
SandboxService.WaitReady#
/cua.daemon.v1.SandboxService/WaitReady, unary: WaitReadyRequest to WaitReadyResponse.
Waits until user-declared readiness probes pass.
SandboxService.ServiceRequest#
/cua.daemon.v1.SandboxService/ServiceRequest, unary: ServiceRequestRequest to ServiceRequestResponse.
Sends one HTTP request to a named service of a sandbox. Credentials (for example a provider's access token) stay in the daemon.
SandboxService.ForwardPort#
/cua.daemon.v1.SandboxService/ForwardPort, unary: ForwardPortRequest to ForwardPortResponse.
Forwards a daemon loopback port to a guest port.
SandboxService.CloseForward#
/cua.daemon.v1.SandboxService/CloseForward, unary: CloseForwardRequest to CloseForwardResponse.
Stops a forward started by ForwardPort.
SandboxService.GetEnvEndpoint#
/cua.daemon.v1.SandboxService/GetEnvEndpoint, unary: GetEnvEndpointRequest to GetEnvEndpointResponse.
Probes cua-spacesd in the sandbox and returns the daemon's loopback
passthrough endpoint for it. cua.env.v1 calls sent there are proxied
with the sandbox credentials attached by the daemon.
SandboxService.GetServiceEndpoint#
/cua.daemon.v1.SandboxService/GetServiceEndpoint, unary: GetServiceEndpointRequest to GetServiceEndpointResponse.
The daemon's loopback passthrough for a named service of a sandbox:
any HTTP request (streamed both ways) sent to url + path reaches that
path on the service with the sandbox's route and credentials attached.
SandboxService.GetServiceUrl#
/cua.daemon.v1.SandboxService/GetServiceUrl, unary: GetServiceUrlRequest to GetServiceUrlResponse.
Returns a URL for a named service usable from this machine without credentials: the published loopback port locally.
SandboxService.CreatePublicUrl#
/cua.daemon.v1.SandboxService/CreatePublicUrl, unary: CreatePublicUrlRequest to CreatePublicUrlResponse.
Creates a shareable URL for a named service that expires: a loopback proxy URL with its own token, served by the daemon.
SandboxService.RevokePublicUrl#
/cua.daemon.v1.SandboxService/RevokePublicUrl, unary: RevokePublicUrlRequest to RevokePublicUrlResponse.
Revokes a URL created by CreatePublicUrl.
SandboxService.CheckpointSandbox#
/cua.daemon.v1.SandboxService/CheckpointSandbox, unary: CheckpointSandboxRequest to CheckpointSandboxResponse.
Saves a local sandbox's state as a named checkpoint (see checkpoints.proto).
SandboxService.ForkSandbox#
/cua.daemon.v1.SandboxService/ForkSandbox, unary: ForkSandboxRequest to ForkSandboxResponse.
Creates and starts a new local sandbox from a sandbox or a checkpoint (see checkpoints.proto for what a fork keeps).
SandboxService.ListCheckpoints#
/cua.daemon.v1.SandboxService/ListCheckpoints, unary: ListCheckpointsRequest to ListCheckpointsResponse.
Lists checkpoints.
SandboxService.DeleteCheckpoint#
/cua.daemon.v1.SandboxService/DeleteCheckpoint, unary: DeleteCheckpointRequest to DeleteCheckpointResponse.
Deletes a checkpoint (forks made from it keep running).
SandboxService.PinCheckpoint#
/cua.daemon.v1.SandboxService/PinCheckpoint, unary: PinCheckpointRequest to PinCheckpointResponse.
Pins or unpins a checkpoint (see checkpoints.proto).
SandboxService.PruneCheckpoints#
/cua.daemon.v1.SandboxService/PruneCheckpoints, unary: PruneCheckpointsRequest to PruneCheckpointsResponse.
Deletes every unpinned checkpoint.
PoolService#
cua.daemon.v1.PoolService
Pools of the daemon's machine. Pools are kept across daemon restarts.
| RPC | Request | Response | Kind |
|---|---|---|---|
CreatePool | CreatePoolRequest | CreatePoolResponse | unary |
GetPool | GetPoolRequest | GetPoolResponse | unary |
ListPools | ListPoolsRequest | ListPoolsResponse | unary |
DeletePool | DeletePoolRequest | DeletePoolResponse | unary |
PoolService.CreatePool#
/cua.daemon.v1.PoolService/CreatePool, unary: CreatePoolRequest to CreatePoolResponse.
Creates a pool, or updates the pool of that name.
PoolService.GetPool#
/cua.daemon.v1.PoolService/GetPool, unary: GetPoolRequest to GetPoolResponse.
One pool, with what it holds now.
PoolService.ListPools#
/cua.daemon.v1.PoolService/ListPools, unary: ListPoolsRequest to ListPoolsResponse.
Every pool, with what each holds now.
PoolService.DeletePool#
/cua.daemon.v1.PoolService/DeletePool, unary: DeletePoolRequest to DeletePoolResponse.
Deletes a pool and its ready sandboxes; sandboxes created from it stay.
RuntimeService#
cua.daemon.v1.RuntimeService
Local runtime provisioning (cua runtime doctor|setup).
RuntimeService.Doctor#
/cua.daemon.v1.RuntimeService/Doctor, unary: DoctorRequest to DoctorResponse.
Inspects local runtimes (Lume, QEMU, container engine, runsc) without changing anything.
RuntimeService.Setup#
/cua.daemon.v1.RuntimeService/Setup, unary: SetupRequest to SetupResponse.
Installs or starts missing local runtime components. Every step is explicit and logged in the response.
RuntimeService.PullImage#
/cua.daemon.v1.RuntimeService/PullImage, unary: PullImageRequest to PullImageResponse.
Pulls an image into the local cache or container engine.
RuntimeService.BuildImage#
/cua.daemon.v1.RuntimeService/BuildImage, unary: BuildImageRequest to BuildImageResponse.
Builds an image from an images.cua.ai/v1alpha1 Image resource.
RuntimeService.PushImage#
/cua.daemon.v1.RuntimeService/PushImage, unary: PushImageRequest to PushImageResponse.
Copies an image (host architecture) to another registry reference.
Types in cua/daemon/v1/sandboxes.proto#
Sandbox#
A sandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Name (unique within its location; see id). |
provider | 2 | SandboxProvider | Provider. |
state | 3 | SandboxState | State. |
image | 4 | string | Image reference, for example "ghcr.io/trycua/linux:24.04". |
endpoints | 5 | map of string to string | Reachable endpoints by service name, for example {"env": "http://127.0.0.1:52011"}. |
labels | 6 | map of string to string | User labels. |
created_at | 7 | google.protobuf.Timestamp | Creation time. |
error | 8 | string | Failure reason when state is SANDBOX_STATE_FAILED. |
runtime_type | 9 | string | Runtime identifier as persisted in the state file (direct, docker, qemu, lume, ...). |
ephemeral | 10 | bool | True when the sandbox has no state file and is torn down on delete. |
services | 11 | map of string to uint32 | Declared services: logical name to guest port (0 when only the name is known). |
location | 12 | string | Where the sandbox runs: "local", "cloud", "direct" (a machine reached by address) or "relay". |
expires_at | 13 | google.protobuf.Timestamp | When the sandbox expires unless kept alive. Unset when unknown or never. |
provider_details | 14 | map of string to string | Provider internals for debugging (local: backend, container_id). Not part of the portable API. |
id | 15 | string | Qualified ref: "local:<name>", "direct:<host:port>" or "<provider>:<name>". Every request's name accepts it (and a bare name when that name is unique across locations). |
kind | 16 | string | What kind of machine it runs as: "container" or "vm"; empty when not known (an existing machine). |
runtime | 17 | string | The engine that runs it: "gvisor", "runc", "qemu", "lume", "firecracker" or a provider's own; empty when not known. |
stop_reason | 18 | string | Why a local sandbox stopped without being asked to, in plain words: "out of memory", "killed", "exited" or "exited with code N". Empty otherwise, and once it is started again. |
ReadinessProbe#
A user-declared readiness probe. With no probes a sandbox is ready as soon as its provider reports it running.
| Field | # | Type | Description |
|---|---|---|---|
port | 1 | uint32 | Guest port to probe. |
http_path | 2 | string | HTTP path. Empty means a TCP connect probe. |
http_status | 3 | uint32 | Exact HTTP status to wait for. 0 accepts any 2xx. |
Sidecar#
An extra container sharing a sandbox's network namespace: the sandbox
reaches its ports on localhost, and services may name them. Local
containers only.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Name, unique within the sandbox (a DNS label other than main). Empty derives it from the image. |
image | 2 | string | Image reference. |
command | 3 | repeated string | argv replacing the image's entrypoint. Empty lets the image decide. |
env | 4 | map of string to string | Environment (plain values, not secrets). |
ports | 5 | repeated uint32 | Ports it listens on. |
RegistrySecret#
Credentials for a private registry. Write-only: never logged, stored in state files or returned.
| Field | # | Type | Description |
|---|---|---|---|
registry | 1 | string | Registry host (ghcr.io, localhost:5000). Empty means the image's. |
username | 2 | string | User name (AWS for ECR tokens). |
password | 3 | string | Password or token. |
ImageLayer#
One image build step, as in images.cua.ai/v1alpha1 recipes.
| Field | # | Type | Description |
|---|---|---|---|
type | 1 | string | apt_install, pip_install, uv_install, run or app_install. |
packages | 2 | repeated string | Packages (the install types). |
command | 3 | string | Shell command (run). |
app_id | 4 | string | App id (app_install). |
BuildFile#
A local file copied into a built image.
| Field | # | Type | Description |
|---|---|---|---|
source | 1 | string | Path on the daemon's machine. |
destination | 2 | string | Absolute path in the image. |
ImageBuild#
Image layers built on top of the sandbox's image, built into the local container engine and cached by content.
| Field | # | Type | Description |
|---|---|---|---|
layers | 1 | repeated ImageLayer | Steps, in order. |
env | 2 | map of string to string | Image environment. |
ports | 3 | repeated uint32 | Ports the image exposes. |
files | 4 | repeated BuildFile | Files copied into the image. |
timeout | 5 | google.protobuf.Duration | Build budget. Unset uses one hour. |
ListSandboxesRequest#
Request for SandboxService.ListSandboxes.
| Field | # | Type | Description |
|---|---|---|---|
provider | 1 | SandboxProvider | Deprecated. Deprecated: use location. Only sandboxes of this provider. Unspecified lists all. |
location | 3 | string | Only sandboxes in this location: "local" or "direct". Empty lists every location. Wins over provider. |
ListSandboxesResponse#
Response for SandboxService.ListSandboxes.
| Field | # | Type | Description |
|---|---|---|---|
sandboxes | 1 | repeated Sandbox | Sandboxes. |
warnings | 2 | repeated string | What the listing left out. The listing still succeeds. |
CreateSandboxRequest#
Request for SandboxService.CreateSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Desired name. Empty lets the daemon generate one. |
provider | 2 | SandboxProvider | Deprecated. Deprecated: use location. Used only when location is empty. |
image | 3 | string | Image reference. |
url | 5 | string | Deprecated: use location "direct:<addr>". The address of an existing machine. |
token | 6 | string | Access token for the direct provider's spacesd, if any. |
labels | 7 | map of string to string | User labels. |
os | 8 | string | Guest OS: linux (default), macos or windows. |
cpus | 9 | uint32 | vCPUs. 0 uses the provider default. |
memory_mb | 10 | uint64 | Memory in MiB. 0 uses the provider default. |
ports | 11 | repeated uint32 | Extra guest ports to publish (local) or expose as port-<n> services. |
services | 12 | map of string to uint32 | Named services: logical name to guest port. env defaults to 3211. |
wait_for | 13 | repeated ReadinessProbe | Readiness probes. |
ready_timeout | 14 | google.protobuf.Duration | Total readiness budget. Unset uses the provider default. |
env | 15 | map of string to string | Guest environment (container environment or cloud-init). |
command | 21 | repeated string | The sandbox's command (argv), replacing the image's entrypoint. Empty lets the image decide. Local containers: ENTRYPOINT; local Linux VMs: run by cloud-init. macOS guests reject it. |
sidecars | 22 | repeated Sidecar | Sidecar containers sharing the sandbox's network namespace. Local containers; VMs reject them. |
registry_secret | 23 | RegistrySecret | Credentials for a private image (and sidecar images on its registry): local pulls use them. Never logged or returned. |
build | 24 | ImageBuild | Image layers built on top of image before the sandbox starts. |
container_runtime | 25 | string | Deprecated. Deprecated: use runtime. Local container sandboxes: runc or gvisor, used when runtime is empty. |
owner_pid | 27 | uint32 | The client process that owns an ephemeral sandbox (no name). The daemon records it in the lease and reaps the sandbox after that client dies. 0: the daemon itself owns it. |
network | 28 | string | Guest network: empty or default gives outbound network (like a Docker container); none cuts egress while published ports still work. Only local QEMU VMs honour none; containers and Lume reject it. |
location | 29 | string | Where it runs: "local", "direct:<addr>" (an existing machine running cua-spacesd), or a registered provider (SANDBOX_PROVIDER_CONTRIB, e.g. "e2b"). Empty uses the default (default.on in the config, CUA_DEFAULT_ON, else "local"); clients resolve the default on their side and send it explicitly. |
kind | 30 | string | What kind of machine: "auto" (empty), "container", "vm" or "microvm". Auto decides from the image: macOS and Windows images are VMs, an image with a container rootfs is a container, a disk-only image is a VM. A microVM (only by name) boots the container rootfs with its own kernel. |
runtime | 31 | string | Which engine: "auto" (empty) or one the location offers for the kind. Local: "gvisor", "runc" (containers), "qemu", "lume" (VMs), "firecracker" (microVMs). A registered provider offers its own engines. Anything else is DAEMON_ERROR_REASON_INVALID_PLACEMENT, listing the valid values. |
keep_on_failure | 32 | bool | Keep a named sandbox whose readiness check fails (its VM or container, and its record) for debugging. False: a failed create deletes what it made. Ephemeral sandboxes are always deleted. |
gpu | 33 | string | A GPU option of the runtime it runs on (GetGpuSupport): "paravirtual" (macOS VMs on Lume, experimental), "virgl" (QEMU on Linux), "nvidia" (a runc container on Linux), a contrib provider's GPU type; "auto" picks the runtime's own. Empty: no GPU. An option the runtime lacks fails, saying why. |
forkable | 34 | bool | A fork source (see checkpoints.proto): a local QEMU VM's RAM is a shared file. Other kinds ignore it. |
headless | 35 | bool | No desktop: only cua-spacesd runs (exec, files, MCP). |
profile | 40 | string | Size profile: "rollout" or "default". |
spacesd | 41 | optional bool | Inject cua-spacesd into an image without it. Unset: yes. |
local_pool | 42 | string | A local pool (PoolService): the sandbox takes its image and shape. (4, the Cua Cloud pool, is reserved.) |
CreateSandboxResponse#
Response for SandboxService.CreateSandbox.
| Field | # | Type | Description |
|---|---|---|---|
sandbox | 1 | Sandbox | The sandbox. |
network | 2 | string | The network applied: none or empty. |
CreateSandboxStreamRequest#
Request for SandboxService.CreateSandboxStream.
| Field | # | Type | Description |
|---|---|---|---|
create | 1 | CreateSandboxRequest | The create, as for CreateSandbox. |
CreateSandboxStreamResponse#
One message of SandboxService.CreateSandboxStream.
| Field | # | Type | Description |
|---|---|---|---|
progress | 1 | CreateSpaceProgress (oneof event) | What the create is doing now (space is empty). |
result | 2 | CreateSandboxResponse (oneof event) | The created sandbox (the last message). |
GetSandboxRequest#
Request for SandboxService.GetSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
GetSandboxResponse#
Response for SandboxService.GetSandbox.
| Field | # | Type | Description |
|---|---|---|---|
sandbox | 1 | Sandbox | The sandbox. |
CancelCreateSandboxRequest#
Request for SandboxService.CancelCreateSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The sandbox's name. |
CancelCreateSandboxResponse#
Response for SandboxService.CancelCreateSandbox.
| Field | # | Type | Description |
|---|---|---|---|
cancelled | 1 | bool | A create of that name was running and was stopped. |
message | 2 | string | What was removed and what stays, for people. |
DeleteSandboxRequest#
Request for SandboxService.DeleteSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
DeleteSandboxResponse#
Response for SandboxService.DeleteSandbox.
No fields.
ConnectSandboxRequest#
Request for SandboxService.ConnectSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
ConnectSandboxResponse#
Response for SandboxService.ConnectSandbox.
| Field | # | Type | Description |
|---|---|---|---|
sandbox | 1 | Sandbox | The sandbox. |
SuspendSandboxRequest#
Request for SandboxService.SuspendSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref (as for GetSandbox) or a name unique across locations. |
SuspendSandboxResponse#
Response for SandboxService.SuspendSandbox.
No fields.
ResumeSandboxRequest#
Request for SandboxService.ResumeSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref (as for GetSandbox) or a name unique across locations. |
ResumeSandboxResponse#
Response for SandboxService.ResumeSandbox.
No fields.
RestartSandboxRequest#
Request for SandboxService.RestartSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref (as for GetSandbox) or a name unique across locations. |
RestartSandboxResponse#
Response for SandboxService.RestartSandbox.
No fields.
KeepAliveRequest#
Request for SandboxService.KeepAlive.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref, or a name unique across locations. |
duration | 2 | google.protobuf.Duration | How long to extend the lease by. |
on_expire | 3 | string | delete or suspend (local). |
KeepAliveResponse#
Response for SandboxService.KeepAlive.
No fields.
WaitReadyRequest#
Request for SandboxService.WaitReady.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
probes | 2 | repeated ReadinessProbe | Probes to wait for. |
timeout | 3 | google.protobuf.Duration | Total budget. |
WaitReadyResponse#
Response for SandboxService.WaitReady.
No fields.
HttpHeader#
One HTTP header.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Header name. |
value | 2 | string | Header value. |
ServiceRequestRequest#
Request for SandboxService.ServiceRequest.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
service | 2 | string | Logical service name, for example "env" or "server". |
method | 3 | string | HTTP method. Empty means GET. |
path | 4 | string | Path (and query) under the service. |
body | 5 | bytes | Request body. |
timeout | 6 | google.protobuf.Duration | Timeout. Unset means 30 seconds. |
headers | 7 | repeated HttpHeader | Request headers (for example content-type, or accept and mcp-session-id for MCP). Headers a provider's route sets (access tokens) are added by the daemon and may not be set here. |
ServiceRequestResponse#
Response for SandboxService.ServiceRequest.
| Field | # | Type | Description |
|---|---|---|---|
status | 1 | uint32 | HTTP status. |
headers | 2 | repeated HttpHeader | Response headers. |
body | 3 | bytes | Response body. |
ForwardPortRequest#
Request for SandboxService.ForwardPort.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
port | 2 | uint32 | Guest port. |
ForwardPortResponse#
Response for SandboxService.ForwardPort.
| Field | # | Type | Description |
|---|---|---|---|
forward_id | 1 | string | Forward id for CloseForward. Empty when no listener was started (the port is only reachable as url). |
guest_port | 2 | uint32 | Guest port. |
local_addr | 3 | string | Loopback host:port accepting connections, when a TCP forward runs. |
url | 4 | string | URL to use (a loopback URL). |
CloseForwardRequest#
Request for SandboxService.CloseForward.
| Field | # | Type | Description |
|---|---|---|---|
forward_id | 1 | string | Forward id. |
CloseForwardResponse#
Response for SandboxService.CloseForward.
No fields.
GetEnvEndpointRequest#
Request for SandboxService.GetEnvEndpoint.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
probe_timeout | 2 | google.protobuf.Duration | Probe timeout. Unset uses the daemon default. |
GetServiceEndpointRequest#
Request for SandboxService.GetServiceEndpoint.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
service | 2 | string | Service name, for example "mcp". |
GetServiceEndpointResponse#
Response for SandboxService.GetServiceEndpoint.
| Field | # | Type | Description |
|---|---|---|---|
url | 1 | string | Base URL, for example "http://127.0.0.1:52011/v1/sandboxes/dev/svc/mcp". Append the path. |
headers | 2 | repeated HttpHeader | Headers every request needs (the daemon's loopback bearer). |
GetEnvEndpointResponse#
Response for SandboxService.GetEnvEndpoint.
| Field | # | Type | Description |
|---|---|---|---|
url | 1 | string | Loopback passthrough base URL, for example "http://127.0.0.1:52011/v1/sandboxes/dev/env". Append the gRPC path. |
token | 2 | string | Bearer token for the passthrough (the daemon's loopback token). |
spacesd_version | 3 | string | spacesd version reported by the probe. |
GetServiceUrlRequest#
Request for SandboxService.GetServiceUrl.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
service | 2 | string | Logical service name. |
GetServiceUrlResponse#
Response for SandboxService.GetServiceUrl.
| Field | # | Type | Description |
|---|---|---|---|
url | 1 | string | The URL (no trailing slash). |
PublicUrl#
A shareable, expiring URL of a sandbox service.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Id for RevokePublicUrl. |
url | 2 | string | The URL. |
expires_at | 3 | google.protobuf.Timestamp | When it stops working. |
sandbox | 4 | string | Sandbox name. |
service | 5 | string | Logical service name. |
provider_details | 6 | map of string to string | Provider internals (local: upstream). |
CreatePublicUrlRequest#
Request for SandboxService.CreatePublicUrl.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref or unique name (with upstream_url, only recorded). |
service | 2 | string | Logical service name. |
ttl | 3 | google.protobuf.Duration | Lifetime, 60 s to 24 h. Unset means 1 h. |
label | 4 | string | Label shown in listings. |
upstream_url | 5 | string | Share this loopback http:// URL instead of resolving name and service (an embedded SDK runtime asking the daemon to host its URL). |
CreatePublicUrlResponse#
Response for SandboxService.CreatePublicUrl.
| Field | # | Type | Description |
|---|---|---|---|
public_url | 1 | PublicUrl | The URL. |
RevokePublicUrlRequest#
Request for SandboxService.RevokePublicUrl.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
id | 2 | string | PublicUrl.id. |
RevokePublicUrlResponse#
Response for SandboxService.RevokePublicUrl.
No fields.
ForkSandboxResponse#
Response for SandboxService.ForkSandbox.
| Field | # | Type | Description |
|---|---|---|---|
sandbox | 1 | Sandbox | The new sandbox, running. |
SandboxProvider#
Where a sandbox comes from. Deprecated: requests use the location
string (local, cloud, direct:<addr>), which also names third-party
providers; responses carry Sandbox.location.
| Value | # | Description |
|---|---|---|
SANDBOX_PROVIDER_UNSPECIFIED | 0 | Not set. |
SANDBOX_PROVIDER_LOCAL | 2 | Run locally through cua-vmm (Lume, QEMU, container). |
SANDBOX_PROVIDER_DIRECT | 3 | An existing machine reached by URL and token. |
SANDBOX_PROVIDER_CONTRIB | 4 | A contrib provider (third-party platform). |
SandboxState#
Sandbox lifecycle state.
| Value | # | Description |
|---|---|---|
SANDBOX_STATE_UNSPECIFIED | 0 | Not reported. |
SANDBOX_STATE_PROVISIONING | 1 | Being created or booted. |
SANDBOX_STATE_RUNNING | 2 | Running and ready (per its readiness probes). |
SANDBOX_STATE_STOPPED | 3 | Suspended or stopped; can resume. |
SANDBOX_STATE_DELETING | 4 | Being deleted. |
SANDBOX_STATE_FAILED | 5 | Failed; see Sandbox.error. |
Types in cua/daemon/v1/checkpoints.proto#
Checkpoint#
A named checkpoint of a local sandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The checkpoint's name (unique among checkpoints and sandboxes). |
source | 2 | string | The sandbox it was taken from. |
runtime_type | 3 | string | The engine that holds it ("firecracker", "gvisor", "qemu", ...). |
created_at | 4 | google.protobuf.Timestamp | Creation time. |
image | 5 | string | The image of the source sandbox. |
pinned | 6 | bool | Pinned: kept until unpinned (DeleteCheckpoint and PruneCheckpoints leave it). |
shared_memory | 7 | bool | Forks map its RAM copy-on-write and share the pages they do not write (a QEMU memory checkpoint). |
release_with_forks | 8 | bool | Taken to fork a running sandbox many times: deleted with the last of its forks. |
forks | 9 | uint32 | How many of its forks still exist (for release_with_forks). |
host | 10 | string | The machine of yours that holds it (empty: this one). |
CheckpointSandboxRequest#
Request for SandboxService.CheckpointSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>") or a name that is unique across locations. |
checkpoint | 2 | string | The checkpoint's name. |
pin | 3 | bool | Pin the new checkpoint (see PinCheckpoint). |
CheckpointSandboxResponse#
Response for SandboxService.CheckpointSandbox.
| Field | # | Type | Description |
|---|---|---|---|
checkpoint | 1 | Checkpoint | The checkpoint. |
ListCheckpointsRequest#
Request for SandboxService.ListCheckpoints.
No fields.
ListCheckpointsResponse#
Response for SandboxService.ListCheckpoints.
| Field | # | Type | Description |
|---|---|---|---|
checkpoints | 1 | repeated Checkpoint | Checkpoints, oldest first. |
DeleteCheckpointRequest#
Request for SandboxService.DeleteCheckpoint.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The checkpoint's name. |
DeleteCheckpointResponse#
Response for SandboxService.DeleteCheckpoint.
No fields.
PinCheckpointRequest#
Request for SandboxService.PinCheckpoint.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The checkpoint's name. |
pinned | 2 | bool | Pin (true) or unpin (false) it. |
PinCheckpointResponse#
Response for SandboxService.PinCheckpoint.
| Field | # | Type | Description |
|---|---|---|---|
checkpoint | 1 | Checkpoint | The checkpoint, as it is now. |
PruneCheckpointsRequest#
Request for SandboxService.PruneCheckpoints.
No fields.
PruneCheckpointsResponse#
Response for SandboxService.PruneCheckpoints.
| Field | # | Type | Description |
|---|---|---|---|
deleted | 1 | repeated string | The checkpoints deleted (every one that was not pinned and could be deleted). |
ForkSandboxRequest#
Request for SandboxService.ForkSandbox.
| Field | # | Type | Description |
|---|---|---|---|
source | 1 | string | A sandbox ref or name, or a checkpoint name (a sandbox wins). |
name | 2 | string | The new sandbox's name. |
labels | 3 | map of string to string | User labels of the new sandbox. |
Types in cua/daemon/v1/pools.proto#
CreatePoolRequest#
Request for PoolService.CreatePool.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Pool name (a DNS label). Empty: the daemon names it. |
spec | 2 | CreateSandboxRequest | What its sandboxes are: a create request's image, location (only local today), kind, runtime, cpus, memory, env, ports and services. Its name, token and pool are ignored. |
min | 3 | uint32 | Sandboxes kept ready at all times: one is started again as soon as one is created from the pool. |
max | 4 | uint32 | Most sandboxes kept ready (not counting those created from the pool). 0: min. Above min, more are kept ready only while creates from the pool come faster than sandboxes start. |
idle | 5 | google.protobuf.Duration | After this long without a create from the pool, it keeps none ready until the next create (which starts on the default tier and refills the pool). Unset: never. |
CreatePoolResponse#
Response for PoolService.CreatePool.
| Field | # | Type | Description |
|---|---|---|---|
pool | 1 | Pool | The pool as created or updated. |
GetPoolRequest#
Request for PoolService.GetPool.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Pool name. |
GetPoolResponse#
Response for PoolService.GetPool.
| Field | # | Type | Description |
|---|---|---|---|
pool | 1 | Pool | The pool. |
ListPoolsRequest#
Request for PoolService.ListPools.
No fields.
ListPoolsResponse#
Response for PoolService.ListPools.
| Field | # | Type | Description |
|---|---|---|---|
pools | 1 | repeated Pool | Every pool. |
DeletePoolRequest#
Request for PoolService.DeletePool.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Pool name. |
DeletePoolResponse#
Response for PoolService.DeletePool.
| Field | # | Type | Description |
|---|---|---|---|
deleted | 1 | bool | Whether a pool of that name existed. |
Pool#
A pool (PoolService.CreatePool).
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Name. |
image | 2 | string | Image, as given. |
location | 3 | string | Where its sandboxes run (local). |
kind | 4 | string | Kind, as given (empty: auto). |
runtime | 5 | string | Runtime, as given (empty: auto). |
cpus | 6 | uint32 | CPUs of each sandbox. |
memory_mb | 7 | uint64 | Memory of each sandbox (MiB). |
min | 8 | uint32 | Sandboxes kept ready at all times. |
max | 9 | uint32 | Most sandboxes kept ready. |
idle | 10 | google.protobuf.Duration | Idle time after which it keeps none ready (unset: never). |
ready | 11 | uint32 | Sandboxes ready now. |
starting | 12 | uint32 | Sandboxes starting. |
status | 13 | string | Why it holds what it holds, or why it cannot (an image that does not pool here, too little memory, idle). |
Types in cua/daemon/v1/runtime.proto#
RuntimeCheck#
One doctor check.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Component, for example "lume", "qemu", "docker", "runsc". |
status | 2 | CheckStatus | Status. |
version | 3 | string | Detected version, when present. |
detail | 4 | string | Explanation or remediation. |
DoctorRequest#
Request for RuntimeService.Doctor.
No fields.
DoctorResponse#
Response for RuntimeService.Doctor.
| Field | # | Type | Description |
|---|---|---|---|
checks | 1 | repeated RuntimeCheck | Checks, in a stable order. |
report_json | 2 | string | The full host report (cua-vmm DoctorReport) as JSON. |
SetupRequest#
Request for RuntimeService.Setup.
| Field | # | Type | Description |
|---|---|---|---|
components | 1 | repeated string | Components to set up. Empty means every installable component. |
dry_run | 2 | bool | Report the plan without changing anything. |
SetupStep#
One setup step.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Component. |
status | 2 | CheckStatus | Status after the step. |
detail | 3 | string | What was done, or would be done on a dry run. |
SetupResponse#
Response for RuntimeService.Setup.
| Field | # | Type | Description |
|---|---|---|---|
steps | 1 | repeated SetupStep | Steps, in execution order. |
LocalImage#
A local image.
| Field | # | Type | Description |
|---|---|---|---|
reference | 1 | string | Reference. |
kind | 2 | string | container or vm. |
location | 3 | string | Local disk path (VM images) or engine image reference (containers). |
size_bytes | 4 | uint64 | Size in bytes, when known. |
PullImageRequest#
Request for RuntimeService.PullImage.
| Field | # | Type | Description |
|---|---|---|---|
reference | 1 | string | Reference, with an optional backend prefix (container:, vm:). |
PullImageResponse#
Response for RuntimeService.PullImage.
| Field | # | Type | Description |
|---|---|---|---|
image | 1 | LocalImage | The pulled image. |
BuildImageRequest#
Request for RuntimeService.BuildImage.
| Field | # | Type | Description |
|---|---|---|---|
spec_json | 1 | string | images.cua.ai/v1alpha1 Image resource as JSON. |
base | 2 | string | Base image, with an optional backend prefix (container:, vm:, disk:). |
push | 3 | string | Push the result to this reference. Empty keeps it local. |
BuildImageResponse#
Response for RuntimeService.BuildImage.
| Field | # | Type | Description |
|---|---|---|---|
result | 1 | string | reference@digest when pushed, else the local output directory. |
PushImageRequest#
Request for RuntimeService.PushImage.
| Field | # | Type | Description |
|---|---|---|---|
reference | 1 | string | Source reference. |
destination | 2 | string | Destination reference. |
PushImageResponse#
Response for RuntimeService.PushImage.
| Field | # | Type | Description |
|---|---|---|---|
digest | 1 | string | Pushed manifest digest. |
CheckStatus#
Status of one local runtime component.
| Value | # | Description |
|---|---|---|
CHECK_STATUS_UNSPECIFIED | 0 | Not reported. |
CHECK_STATUS_OK | 1 | Present and usable. |
CHECK_STATUS_INSTALLABLE | 2 | Missing, but cua runtime setup can install it. |
CHECK_STATUS_ERROR | 3 | Missing or broken and needs user action. |
CHECK_STATUS_NOT_APPLICABLE | 4 | Not applicable on this host. |