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.

RPCRequestResponseKind
ListSandboxesListSandboxesRequestListSandboxesResponseunary
CreateSandboxCreateSandboxRequestCreateSandboxResponseunary
CreateSandboxStreamCreateSandboxStreamRequestCreateSandboxStreamResponseserver stream
CancelCreateSandboxCancelCreateSandboxRequestCancelCreateSandboxResponseunary
GetSandboxGetSandboxRequestGetSandboxResponseunary
DeleteSandboxDeleteSandboxRequestDeleteSandboxResponseunary
ConnectSandboxConnectSandboxRequestConnectSandboxResponseunary
SuspendSandboxSuspendSandboxRequestSuspendSandboxResponseunary
ResumeSandboxResumeSandboxRequestResumeSandboxResponseunary
RestartSandboxRestartSandboxRequestRestartSandboxResponseunary
ResizeSandboxResizeSandboxRequestResizeSandboxResponseunary
KeepAliveKeepAliveRequestKeepAliveResponseunary
WaitReadyWaitReadyRequestWaitReadyResponseunary
ServiceRequestServiceRequestRequestServiceRequestResponseunary
ForwardPortForwardPortRequestForwardPortResponseunary
CloseForwardCloseForwardRequestCloseForwardResponseunary
GetEnvEndpointGetEnvEndpointRequestGetEnvEndpointResponseunary
GetServiceEndpointGetServiceEndpointRequestGetServiceEndpointResponseunary
GetServiceUrlGetServiceUrlRequestGetServiceUrlResponseunary
CreatePublicUrlCreatePublicUrlRequestCreatePublicUrlResponseunary
RevokePublicUrlRevokePublicUrlRequestRevokePublicUrlResponseunary
CheckpointSandboxCheckpointSandboxRequestCheckpointSandboxResponseunary
ForkSandboxForkSandboxRequestForkSandboxResponseunary
ListCheckpointsListCheckpointsRequestListCheckpointsResponseunary
DeleteCheckpointDeleteCheckpointRequestDeleteCheckpointResponseunary
PinCheckpointPinCheckpointRequestPinCheckpointResponseunary
PruneCheckpointsPruneCheckpointsRequestPruneCheckpointsResponseunary

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.

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#TypeDescription
name1stringName (unique within its location; see id).
provider2SandboxProviderProvider.
state3SandboxStateState.
image4stringImage reference, for example "ghcr.io/trycua/linux:24.04".
endpoints5map of string to stringReachable endpoints by service name, for example {"env": "http://127.0.0.1:52011"&#125;.
labels6map of string to stringUser labels.
created_at7google.protobuf.TimestampCreation time.
error8stringFailure reason when state is SANDBOX_STATE_FAILED.
runtime_type9stringRuntime identifier as persisted in the state file (direct, docker, qemu, lume, ...).
ephemeral10boolTrue when the sandbox has no state file and is torn down on delete.
services11map of string to uint32Declared services: logical name to guest port (0 when only the name is known).
location12stringWhere the sandbox runs: "local", "cloud", "direct" (a machine reached by address) or "relay".
expires_at13google.protobuf.TimestampWhen the sandbox expires unless kept alive. Unset when unknown or never.
provider_details14map of string to stringProvider internals for debugging (local: backend, container_id). Not part of the portable API.
id15stringQualified 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).
kind16stringWhat kind of machine it runs as: "container" or "vm"; empty when not known (an existing machine).
runtime17stringThe engine that runs it: "gvisor", "runc", "qemu", "lume", "firecracker" or a provider's own; empty when not known.
stop_reason18stringWhy 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#TypeDescription
port1uint32Guest port to probe.
http_path2stringHTTP path. Empty means a TCP connect probe.
http_status3uint32Exact 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#TypeDescription
name1stringName, unique within the sandbox (a DNS label other than main). Empty derives it from the image.
image2stringImage reference.
command3repeated stringargv replacing the image's entrypoint. Empty lets the image decide.
env4map of string to stringEnvironment (plain values, not secrets).
ports5repeated uint32Ports it listens on.

RegistrySecret#

Credentials for a private registry. Write-only: never logged, stored in state files or returned.

Field#TypeDescription
registry1stringRegistry host (ghcr.io, localhost:5000). Empty means the image's.
username2stringUser name (AWS for ECR tokens).
password3stringPassword or token.

ImageLayer#

One image build step, as in images.cua.ai/v1alpha1 recipes.

Field#TypeDescription
type1stringapt_install, pip_install, uv_install, run or app_install.
packages2repeated stringPackages (the install types).
command3stringShell command (run).
app_id4stringApp id (app_install).

BuildFile#

A local file copied into a built image.

Field#TypeDescription
source1stringPath on the daemon's machine.
destination2stringAbsolute 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#TypeDescription
layers1repeated ImageLayerSteps, in order.
env2map of string to stringImage environment.
ports3repeated uint32Ports the image exposes.
files4repeated BuildFileFiles copied into the image.
timeout5google.protobuf.DurationBuild budget. Unset uses one hour.

ListSandboxesRequest#

Request for SandboxService.ListSandboxes.

Field#TypeDescription
provider1SandboxProviderDeprecated. Deprecated: use location. Only sandboxes of this provider. Unspecified lists all.
location3stringOnly sandboxes in this location: "local" or "direct". Empty lists every location. Wins over provider.

ListSandboxesResponse#

Response for SandboxService.ListSandboxes.

Field#TypeDescription
sandboxes1repeated SandboxSandboxes.
warnings2repeated stringWhat the listing left out. The listing still succeeds.

CreateSandboxRequest#

Request for SandboxService.CreateSandbox.

Field#TypeDescription
name1stringDesired name. Empty lets the daemon generate one.
provider2SandboxProviderDeprecated. Deprecated: use location. Used only when location is empty.
image3stringImage reference.
url5stringDeprecated: use location "direct:<addr>". The address of an existing machine.
token6stringAccess token for the direct provider's spacesd, if any.
labels7map of string to stringUser labels.
os8stringGuest OS: linux (default), macos or windows.
cpus9uint32vCPUs. 0 uses the provider default.
memory_mb10uint64Memory in MiB. 0 uses the provider default.
ports11repeated uint32Extra guest ports to publish (local) or expose as port-<n> services.
services12map of string to uint32Named services: logical name to guest port. env defaults to 3211.
wait_for13repeated ReadinessProbeReadiness probes.
ready_timeout14google.protobuf.DurationTotal readiness budget. Unset uses the provider default.
env15map of string to stringGuest environment (container environment or cloud-init).
command21repeated stringThe 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.
sidecars22repeated SidecarSidecar containers sharing the sandbox's network namespace. Local containers; VMs reject them.
registry_secret23RegistrySecretCredentials for a private image (and sidecar images on its registry): local pulls use them. Never logged or returned.
build24ImageBuildImage layers built on top of image before the sandbox starts.
container_runtime25stringDeprecated. Deprecated: use runtime. Local container sandboxes: runc or gvisor, used when runtime is empty.
owner_pid27uint32The 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.
network28stringGuest 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.
location29stringWhere 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.
kind30stringWhat 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.
runtime31stringWhich 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_failure32boolKeep 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.
gpu33stringA 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.
forkable34boolA fork source (see checkpoints.proto): a local QEMU VM's RAM is a shared file. Other kinds ignore it.
headless35boolNo desktop: only cua-spacesd runs (exec, files, MCP).
profile40stringSize profile: "rollout" or "default".
spacesd41optional boolInject cua-spacesd into an image without it. Unset: yes.
local_pool42stringA local pool (PoolService): the sandbox takes its image and shape. (4, the Cua Cloud pool, is reserved.)

CreateSandboxResponse#

Response for SandboxService.CreateSandbox.

Field#TypeDescription
sandbox1SandboxThe sandbox.
network2stringThe network applied: none or empty.

CreateSandboxStreamRequest#

Request for SandboxService.CreateSandboxStream.

Field#TypeDescription
create1CreateSandboxRequestThe create, as for CreateSandbox.

CreateSandboxStreamResponse#

One message of SandboxService.CreateSandboxStream.

Field#TypeDescription
progress1CreateSpaceProgress (oneof event)What the create is doing now (space is empty).
result2CreateSandboxResponse (oneof event)The created sandbox (the last message).

GetSandboxRequest#

Request for SandboxService.GetSandbox.

Field#TypeDescription
name1stringSandbox 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#TypeDescription
sandbox1SandboxThe sandbox.

CancelCreateSandboxRequest#

Request for SandboxService.CancelCreateSandbox.

Field#TypeDescription
name1stringThe sandbox's name.

CancelCreateSandboxResponse#

Response for SandboxService.CancelCreateSandbox.

Field#TypeDescription
cancelled1boolA create of that name was running and was stopped.
message2stringWhat was removed and what stays, for people.

DeleteSandboxRequest#

Request for SandboxService.DeleteSandbox.

Field#TypeDescription
name1stringSandbox 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#TypeDescription
name1stringSandbox 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#TypeDescription
sandbox1SandboxThe sandbox.

SuspendSandboxRequest#

Request for SandboxService.SuspendSandbox.

Field#TypeDescription
name1stringSandbox ref (as for GetSandbox) or a name unique across locations.

SuspendSandboxResponse#

Response for SandboxService.SuspendSandbox.

No fields.

ResumeSandboxRequest#

Request for SandboxService.ResumeSandbox.

Field#TypeDescription
name1stringSandbox ref (as for GetSandbox) or a name unique across locations.

ResumeSandboxResponse#

Response for SandboxService.ResumeSandbox.

No fields.

RestartSandboxRequest#

Request for SandboxService.RestartSandbox.

Field#TypeDescription
name1stringSandbox ref (as for GetSandbox) or a name unique across locations.

RestartSandboxResponse#

Response for SandboxService.RestartSandbox.

No fields.

KeepAliveRequest#

Request for SandboxService.KeepAlive.

Field#TypeDescription
name1stringSandbox ref, or a name unique across locations.
duration2google.protobuf.DurationHow long to extend the lease by.
on_expire3stringdelete or suspend (local).

KeepAliveResponse#

Response for SandboxService.KeepAlive.

No fields.

WaitReadyRequest#

Request for SandboxService.WaitReady.

Field#TypeDescription
name1stringSandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations.
probes2repeated ReadinessProbeProbes to wait for.
timeout3google.protobuf.DurationTotal budget.

WaitReadyResponse#

Response for SandboxService.WaitReady.

No fields.

HttpHeader#

One HTTP header.

Field#TypeDescription
name1stringHeader name.
value2stringHeader value.

ServiceRequestRequest#

Request for SandboxService.ServiceRequest.

Field#TypeDescription
name1stringSandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations.
service2stringLogical service name, for example "env" or "server".
method3stringHTTP method. Empty means GET.
path4stringPath (and query) under the service.
body5bytesRequest body.
timeout6google.protobuf.DurationTimeout. Unset means 30 seconds.
headers7repeated HttpHeaderRequest 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#TypeDescription
status1uint32HTTP status.
headers2repeated HttpHeaderResponse headers.
body3bytesResponse body.

ForwardPortRequest#

Request for SandboxService.ForwardPort.

Field#TypeDescription
name1stringSandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations.
port2uint32Guest port.

ForwardPortResponse#

Response for SandboxService.ForwardPort.

Field#TypeDescription
forward_id1stringForward id for CloseForward. Empty when no listener was started (the port is only reachable as url).
guest_port2uint32Guest port.
local_addr3stringLoopback host:port accepting connections, when a TCP forward runs.
url4stringURL to use (a loopback URL).

CloseForwardRequest#

Request for SandboxService.CloseForward.

Field#TypeDescription
forward_id1stringForward id.

CloseForwardResponse#

Response for SandboxService.CloseForward.

No fields.

GetEnvEndpointRequest#

Request for SandboxService.GetEnvEndpoint.

Field#TypeDescription
name1stringSandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations.
probe_timeout2google.protobuf.DurationProbe timeout. Unset uses the daemon default.

GetServiceEndpointRequest#

Request for SandboxService.GetServiceEndpoint.

Field#TypeDescription
name1stringSandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations.
service2stringService name, for example "mcp".

GetServiceEndpointResponse#

Response for SandboxService.GetServiceEndpoint.

Field#TypeDescription
url1stringBase URL, for example "http://127.0.0.1:52011/v1/sandboxes/dev/svc/mcp". Append the path.
headers2repeated HttpHeaderHeaders every request needs (the daemon's loopback bearer).

GetEnvEndpointResponse#

Response for SandboxService.GetEnvEndpoint.

Field#TypeDescription
url1stringLoopback passthrough base URL, for example "http://127.0.0.1:52011/v1/sandboxes/dev/env". Append the gRPC path.
token2stringBearer token for the passthrough (the daemon's loopback token).
spacesd_version3stringspacesd version reported by the probe.

GetServiceUrlRequest#

Request for SandboxService.GetServiceUrl.

Field#TypeDescription
name1stringSandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations.
service2stringLogical service name.

GetServiceUrlResponse#

Response for SandboxService.GetServiceUrl.

Field#TypeDescription
url1stringThe URL (no trailing slash).

PublicUrl#

A shareable, expiring URL of a sandbox service.

Field#TypeDescription
id1stringId for RevokePublicUrl.
url2stringThe URL.
expires_at3google.protobuf.TimestampWhen it stops working.
sandbox4stringSandbox name.
service5stringLogical service name.
provider_details6map of string to stringProvider internals (local: upstream).

CreatePublicUrlRequest#

Request for SandboxService.CreatePublicUrl.

Field#TypeDescription
name1stringSandbox ref or unique name (with upstream_url, only recorded).
service2stringLogical service name.
ttl3google.protobuf.DurationLifetime, 60 s to 24 h. Unset means 1 h.
label4stringLabel shown in listings.
upstream_url5stringShare 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#TypeDescription
public_url1PublicUrlThe URL.

RevokePublicUrlRequest#

Request for SandboxService.RevokePublicUrl.

Field#TypeDescription
name1stringSandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations.
id2stringPublicUrl.id.

RevokePublicUrlResponse#

Response for SandboxService.RevokePublicUrl.

No fields.

ForkSandboxResponse#

Response for SandboxService.ForkSandbox.

Field#TypeDescription
sandbox1SandboxThe 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_UNSPECIFIED0Not set.
SANDBOX_PROVIDER_LOCAL2Run locally through cua-vmm (Lume, QEMU, container).
SANDBOX_PROVIDER_DIRECT3An existing machine reached by URL and token.
SANDBOX_PROVIDER_CONTRIB4A contrib provider (third-party platform).

SandboxState#

Sandbox lifecycle state.

Value#Description
SANDBOX_STATE_UNSPECIFIED0Not reported.
SANDBOX_STATE_PROVISIONING1Being created or booted.
SANDBOX_STATE_RUNNING2Running and ready (per its readiness probes).
SANDBOX_STATE_STOPPED3Suspended or stopped; can resume.
SANDBOX_STATE_DELETING4Being deleted.
SANDBOX_STATE_FAILED5Failed; see Sandbox.error.

Types in cua/daemon/v1/checkpoints.proto#

Checkpoint#

A named checkpoint of a local sandbox.

Field#TypeDescription
name1stringThe checkpoint's name (unique among checkpoints and sandboxes).
source2stringThe sandbox it was taken from.
runtime_type3stringThe engine that holds it ("firecracker", "gvisor", "qemu", ...).
created_at4google.protobuf.TimestampCreation time.
image5stringThe image of the source sandbox.
pinned6boolPinned: kept until unpinned (DeleteCheckpoint and PruneCheckpoints leave it).
shared_memory7boolForks map its RAM copy-on-write and share the pages they do not write (a QEMU memory checkpoint).
release_with_forks8boolTaken to fork a running sandbox many times: deleted with the last of its forks.
forks9uint32How many of its forks still exist (for release_with_forks).
host10stringThe machine of yours that holds it (empty: this one).

CheckpointSandboxRequest#

Request for SandboxService.CheckpointSandbox.

Field#TypeDescription
name1stringSandbox ref ("local:<name>") or a name that is unique across locations.
checkpoint2stringThe checkpoint's name.
pin3boolPin the new checkpoint (see PinCheckpoint).

CheckpointSandboxResponse#

Response for SandboxService.CheckpointSandbox.

Field#TypeDescription
checkpoint1CheckpointThe checkpoint.

ListCheckpointsRequest#

Request for SandboxService.ListCheckpoints.

No fields.

ListCheckpointsResponse#

Response for SandboxService.ListCheckpoints.

Field#TypeDescription
checkpoints1repeated CheckpointCheckpoints, oldest first.

DeleteCheckpointRequest#

Request for SandboxService.DeleteCheckpoint.

Field#TypeDescription
name1stringThe checkpoint's name.

DeleteCheckpointResponse#

Response for SandboxService.DeleteCheckpoint.

No fields.

PinCheckpointRequest#

Request for SandboxService.PinCheckpoint.

Field#TypeDescription
name1stringThe checkpoint's name.
pinned2boolPin (true) or unpin (false) it.

PinCheckpointResponse#

Response for SandboxService.PinCheckpoint.

Field#TypeDescription
checkpoint1CheckpointThe checkpoint, as it is now.

PruneCheckpointsRequest#

Request for SandboxService.PruneCheckpoints.

No fields.

PruneCheckpointsResponse#

Response for SandboxService.PruneCheckpoints.

Field#TypeDescription
deleted1repeated stringThe checkpoints deleted (every one that was not pinned and could be deleted).

ForkSandboxRequest#

Request for SandboxService.ForkSandbox.

Field#TypeDescription
source1stringA sandbox ref or name, or a checkpoint name (a sandbox wins).
name2stringThe new sandbox's name.
labels3map of string to stringUser labels of the new sandbox.

Types in cua/daemon/v1/pools.proto#

CreatePoolRequest#

Request for PoolService.CreatePool.

Field#TypeDescription
name1stringPool name (a DNS label). Empty: the daemon names it.
spec2CreateSandboxRequestWhat 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.
min3uint32Sandboxes kept ready at all times: one is started again as soon as one is created from the pool.
max4uint32Most 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.
idle5google.protobuf.DurationAfter 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#TypeDescription
pool1PoolThe pool as created or updated.

GetPoolRequest#

Request for PoolService.GetPool.

Field#TypeDescription
name1stringPool name.

GetPoolResponse#

Response for PoolService.GetPool.

Field#TypeDescription
pool1PoolThe pool.

ListPoolsRequest#

Request for PoolService.ListPools.

No fields.

ListPoolsResponse#

Response for PoolService.ListPools.

Field#TypeDescription
pools1repeated PoolEvery pool.

DeletePoolRequest#

Request for PoolService.DeletePool.

Field#TypeDescription
name1stringPool name.

DeletePoolResponse#

Response for PoolService.DeletePool.

Field#TypeDescription
deleted1boolWhether a pool of that name existed.

Pool#

A pool (PoolService.CreatePool).

Field#TypeDescription
name1stringName.
image2stringImage, as given.
location3stringWhere its sandboxes run (local).
kind4stringKind, as given (empty: auto).
runtime5stringRuntime, as given (empty: auto).
cpus6uint32CPUs of each sandbox.
memory_mb7uint64Memory of each sandbox (MiB).
min8uint32Sandboxes kept ready at all times.
max9uint32Most sandboxes kept ready.
idle10google.protobuf.DurationIdle time after which it keeps none ready (unset: never).
ready11uint32Sandboxes ready now.
starting12uint32Sandboxes starting.
status13stringWhy 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#TypeDescription
name1stringComponent, for example "lume", "qemu", "docker", "runsc".
status2CheckStatusStatus.
version3stringDetected version, when present.
detail4stringExplanation or remediation.

DoctorRequest#

Request for RuntimeService.Doctor.

No fields.

DoctorResponse#

Response for RuntimeService.Doctor.

Field#TypeDescription
checks1repeated RuntimeCheckChecks, in a stable order.
report_json2stringThe full host report (cua-vmm DoctorReport) as JSON.

SetupRequest#

Request for RuntimeService.Setup.

Field#TypeDescription
components1repeated stringComponents to set up. Empty means every installable component.
dry_run2boolReport the plan without changing anything.

SetupStep#

One setup step.

Field#TypeDescription
name1stringComponent.
status2CheckStatusStatus after the step.
detail3stringWhat was done, or would be done on a dry run.

SetupResponse#

Response for RuntimeService.Setup.

Field#TypeDescription
steps1repeated SetupStepSteps, in execution order.

LocalImage#

A local image.

Field#TypeDescription
reference1stringReference.
kind2stringcontainer or vm.
location3stringLocal disk path (VM images) or engine image reference (containers).
size_bytes4uint64Size in bytes, when known.

PullImageRequest#

Request for RuntimeService.PullImage.

Field#TypeDescription
reference1stringReference, with an optional backend prefix (container:, vm:).

PullImageResponse#

Response for RuntimeService.PullImage.

Field#TypeDescription
image1LocalImageThe pulled image.

BuildImageRequest#

Request for RuntimeService.BuildImage.

Field#TypeDescription
spec_json1stringimages.cua.ai/v1alpha1 Image resource as JSON.
base2stringBase image, with an optional backend prefix (container:, vm:, disk:).
push3stringPush the result to this reference. Empty keeps it local.

BuildImageResponse#

Response for RuntimeService.BuildImage.

Field#TypeDescription
result1stringreference@digest when pushed, else the local output directory.

PushImageRequest#

Request for RuntimeService.PushImage.

Field#TypeDescription
reference1stringSource reference.
destination2stringDestination reference.

PushImageResponse#

Response for RuntimeService.PushImage.

Field#TypeDescription
digest1stringPushed manifest digest.

CheckStatus#

Status of one local runtime component.

Value#Description
CHECK_STATUS_UNSPECIFIED0Not reported.
CHECK_STATUS_OK1Present and usable.
CHECK_STATUS_INSTALLABLE2Missing, but cua runtime setup can install it.
CHECK_STATUS_ERROR3Missing or broken and needs user action.
CHECK_STATUS_NOT_APPLICABLE4Not applicable on this host.