Processes and files
cua.env.v1 ProcessService and FilesystemService: guest processes, and stat, list, watch, read, chunked upload and signed URLs.
Detached, reattachable guest processes with PTY support and bounded scrollback; file and directory operations, watchers, chunked transfers and signed HTTP URLs.
Source: libs/cua/proto/cua/env/v1/process.proto, libs/cua/proto/cua/env/v1/filesystem.proto.
ProcessService#
cua.env.v1.ProcessService
Runs and supervises guest processes.
Processes are detached from the RPC that started them: a client disconnect
does not kill the process unless StartProcessRequest.kill_on_disconnect
is set. Output goes to a bounded scrollback ring so a client can reattach
with ConnectProcess (by pid or tag) and replay recent output. After a
process exits, its exit status and scrollback stay in a retention cache
(at least 10 minutes and the most recent 256 processes) so a late
ConnectProcess still observes the ProcessEnd.
Output offsets: every byte a process writes to stdout, stderr or its PTY
is numbered in one combined, monotonically increasing byte space starting
at 0. ProcessData.offset is the offset of the chunk's first byte, which
lets a reconnecting client drop output it has already seen.
ProcessService.StartProcess#
/cua.env.v1.ProcessService/StartProcess, server stream: StartProcessRequest to StartProcessResponse.
Starts a process and streams its lifecycle and output. The first event is
always ProcessStart, the last is ProcessEnd (unless the client
disconnects first). Cancelling this RPC detaches; it does not signal the
process unless kill_on_disconnect is set.
ProcessService.ConnectProcess#
/cua.env.v1.ProcessService/ConnectProcess, server stream: ConnectProcessRequest to ConnectProcessResponse.
Attaches to a running or recently exited process. The stream begins with
ProcessStart, then up to replay_bytes of scrollback, then live
output, then ProcessEnd.
ProcessService.ListProcesses#
/cua.env.v1.ProcessService/ListProcesses, unary: ListProcessesRequest to ListProcessesResponse.
Lists managed processes.
ProcessService.SendInput#
/cua.env.v1.ProcessService/SendInput, unary: SendInputRequest to SendInputResponse.
Writes one chunk to a process's stdin or PTY. The unary, gRPC-Web-safe
equivalent of StreamInput. Chunks may carry sequence numbers for
exactly-once, in-order delivery across retries.
ProcessService.StreamInput#
/cua.env.v1.ProcessService/StreamInput, client stream: StreamInputRequest to StreamInputResponse.
Streams stdin or PTY input. Native gRPC only; gRPC-Web clients use
SendInput. The first message must set process.
SendInput instead (/cua.env.v1.ProcessService/SendInput).ProcessService.SignalProcess#
/cua.env.v1.ProcessService/SignalProcess, unary: SignalProcessRequest to SignalProcessResponse.
Sends a signal to a process (or its process group).
ProcessService.CloseStdin#
/cua.env.v1.ProcessService/CloseStdin, unary: CloseStdinRequest to CloseStdinResponse.
Closes a process's stdin (EOF). For PTY processes, sends the terminal's EOF character instead.
ProcessService.ResizePty#
/cua.env.v1.ProcessService/ResizePty, unary: ResizePtyRequest to ResizePtyResponse.
Resizes a PTY process's terminal (delivers SIGWINCH on Unix).
ProcessService.GetExecRecord#
/cua.env.v1.ProcessService/GetExecRecord, unary: GetExecRecordRequest to GetExecRecordResponse.
Looks up the exec ledger entry of a StartProcessRequest.request_id
without starting anything. A durable harness uses it after a crash to
learn whether a command it may have started ran, still runs, or was lost.
ProcessService.AdvanceEpoch#
/cua.env.v1.ProcessService/AdvanceEpoch, unary: AdvanceEpochRequest to AdvanceEpochResponse.
Raises the Space's fencing epoch. Every running process started with a
lower non-zero StartProcessRequest.epoch is killed (SIGKILL to its
process group), and later requests carrying a lower epoch fail with
FAILED_PRECONDITION / ERROR_REASON_STALE_EPOCH.
ProcessService.PutService#
/cua.env.v1.ProcessService/PutService, unary: PutServiceRequest to PutServiceResponse.
Keeps a command running as a named service: started at once, started
again by its restart policy when it exits or fails its health check,
started when cua-spacesd starts (after the guest boots) unless
start_on_boot is false, and its output kept in log files. Putting a
name that exists replaces it (the old process is stopped first).
ProcessService.DeleteService#
/cua.env.v1.ProcessService/DeleteService, unary: DeleteServiceRequest to DeleteServiceResponse.
Stops a service and forgets it (its log files go too).
ProcessService.ListServices#
/cua.env.v1.ProcessService/ListServices, unary: ListServicesRequest to ListServicesResponse.
Lists services with their state.
ProcessService.ControlService#
/cua.env.v1.ProcessService/ControlService, unary: ControlServiceRequest to ControlServiceResponse.
Starts, stops or restarts a service. A stopped service stays stopped until started (also across a restart of cua-spacesd).
ProcessService.GetServiceLogs#
/cua.env.v1.ProcessService/GetServiceLogs, unary: GetServiceLogsRequest to GetServiceLogsResponse.
The end of a service's log.
FilesystemService#
cua.env.v1.FilesystemService
Guest filesystem access.
Paths are absolute, or relative to the default working directory set by
SystemService.Init. A leading "~" expands to the acting user's home.
Operations run as the user the service runs as, unless a request names
another user in run_as (see "Acting as another user" below).
Acting as another user: run_as on a request makes the operation run
with that guest user's identity (uid, gid and supplementary groups), so
permission checks apply to that user and created files are owned by
that user. It needs privilege: the service must run as root, or as a
user that may run sudo -n without a password (the Linux images' cua
user). Otherwise the call fails with PERMISSION_DENIED and a message
naming the missing privilege. ~ expands to that user's home. A viewer
ticket may not use run_as. Unix guests only.
Extended attributes: a write can attach string metadata that is stored
as extended attributes under a key prefix (xattr_namespace, default
user.cua.meta.), and Stat, ListDir, ReadFile and watch events
report them in metadata. Limits: at most 32 keys, a key is 1 to 128
bytes of ASCII letters, digits and ._:/@+-, a value is at most 1024
bytes, and keys plus values total at most 3072 bytes. The namespace must
start with user., end with ., be at most 64 bytes of letters, digits
and ._-. A file system without extended attribute support fails a
write that carries metadata with FAILED_PRECONDITION and reports none.
Large payloads: there is no total size cap. Reads stream in chunks
(ReadFile). Writes use either the native-gRPC client stream
(WriteFile) or the gRPC-Web-safe, resumable unary chunk protocol
(BeginUpload / UploadChunk / CommitUpload). Browsers and <img> tags
can use signed URLs on the plain-HTTP /files route instead
(CreateSignedUrl).
Writes are atomic: data goes to a temporary file in the destination directory and is renamed into place on success.
FilesystemService.Stat#
/cua.env.v1.FilesystemService/Stat, unary: StatRequest to StatResponse.
Returns metadata for one path.
FilesystemService.ListDir#
/cua.env.v1.FilesystemService/ListDir, unary: ListDirRequest to ListDirResponse.
Lists a directory, optionally recursively.
FilesystemService.MakeDir#
/cua.env.v1.FilesystemService/MakeDir, unary: MakeDirRequest to MakeDirResponse.
Creates a directory.
FilesystemService.Move#
/cua.env.v1.FilesystemService/Move, unary: MoveRequest to MoveResponse.
Moves or renames a file or directory.
FilesystemService.Remove#
/cua.env.v1.FilesystemService/Remove, unary: RemoveRequest to RemoveResponse.
Removes a file or directory.
FilesystemService.WatchDir#
/cua.env.v1.FilesystemService/WatchDir, server stream: WatchDirRequest to WatchDirResponse.
Streams change events under a directory. The first message is
WatchStarted, sent once the watch is armed, so changes made after it
arrives are guaranteed to be observed.
FilesystemService.CreateWatcher#
/cua.env.v1.FilesystemService/CreateWatcher, unary: CreateWatcherRequest to CreateWatcherResponse.
Polling alternative to WatchDir for clients that cannot hold a stream:
creates a server-side watcher that buffers events.
FilesystemService.GetWatcherEvents#
/cua.env.v1.FilesystemService/GetWatcherEvents, unary: GetWatcherEventsRequest to GetWatcherEventsResponse.
Drains buffered events from a watcher.
FilesystemService.RemoveWatcher#
/cua.env.v1.FilesystemService/RemoveWatcher, unary: RemoveWatcherRequest to RemoveWatcherResponse.
Deletes a watcher. Watchers not polled for 5 minutes are deleted automatically.
FilesystemService.ReadFile#
/cua.env.v1.FilesystemService/ReadFile, server stream: ReadFileRequest to ReadFileResponse.
Streams a file (or a byte range of it) in chunks.
FilesystemService.WriteFile#
/cua.env.v1.FilesystemService/WriteFile, client stream: WriteFileRequest to WriteFileResponse.
Writes a file from a client stream. Native gRPC only; gRPC-Web clients
use BeginUpload / UploadChunk / CommitUpload. The first message
must be a WriteFileHeader.
UploadChunk instead (/cua.env.v1.FilesystemService/UploadChunk).FilesystemService.BeginUpload#
/cua.env.v1.FilesystemService/BeginUpload, unary: BeginUploadRequest to BeginUploadResponse.
Starts, or resumes, a resumable chunked upload.
FilesystemService.UploadChunk#
/cua.env.v1.FilesystemService/UploadChunk, unary: UploadChunkRequest to UploadChunkResponse.
Appends one chunk to an upload.
FilesystemService.CommitUpload#
/cua.env.v1.FilesystemService/CommitUpload, unary: CommitUploadRequest to CommitUploadResponse.
Verifies and atomically publishes an upload at its destination path.
FilesystemService.AbortUpload#
/cua.env.v1.FilesystemService/AbortUpload, unary: AbortUploadRequest to AbortUploadResponse.
Discards an upload and its partial data.
FilesystemService.CreateSignedUrl#
/cua.env.v1.FilesystemService/CreateSignedUrl, unary: CreateSignedUrlRequest to CreateSignedUrlResponse.
Mints a time-limited URL on the plain-HTTP /files route for GET
(download) or PUT (upload) of one path.
Types in cua/env/v1/process.proto#
ProcessConfig#
What to run.
| Field | # | Type | Description |
|---|---|---|---|
command | 1 | string | Executable name or path. Resolved against the process's PATH. No shell is involved; to run a shell command line, pass the shell explicitly (for example command: "/bin/bash", args: ["-lc", "echo hi"]). |
args | 2 | repeated string | Arguments, not including argv[0]. |
env | 3 | map of string to string | Environment variables layered over the user's login environment and the InitRequest.env defaults. |
cwd | 4 | string | Working directory. Empty means the Init default workdir, else the user's home directory. |
user | 5 | string | OS user to run as. Empty means the Init default user. Requires the driver to run with sufficient privilege to switch users. |
timeout | 6 | google.protobuf.Duration | Wall-clock limit. When it elapses the process receives SIGTERM, then SIGKILL after 5 seconds, and ProcessEnd.timed_out is set. Unset means no limit. |
PtyConfig#
Pseudo-terminal settings. Present means "run under a PTY".
| Field | # | Type | Description |
|---|---|---|---|
size | 1 | PtySize | Initial terminal size. |
term | 2 | string | Value of TERM. Empty means "xterm-256color". |
PtySize#
Terminal size.
| Field | # | Type | Description |
|---|---|---|---|
cols | 1 | uint32 | Columns. Must be at least 1. |
rows | 2 | uint32 | Rows. Must be at least 1. |
pixel_width | 3 | uint32 | Width in pixels, 0 when unknown. |
pixel_height | 4 | uint32 | Height in pixels, 0 when unknown. |
ProcessSelector#
Identifies a managed process.
| Field | # | Type | Description |
|---|---|---|---|
pid | 1 | uint32 (oneof selector) | Guest process id. Pids are reused by the OS; prefer tag for long-lived references. |
tag | 2 | string (oneof selector) | Client-assigned tag from StartProcessRequest.tag. |
StartProcessRequest#
Request for ProcessService.StartProcess.
| Field | # | Type | Description |
|---|---|---|---|
config | 1 | ProcessConfig | What to run. |
pty | 2 | PtyConfig | Run under a PTY when set. PTY output arrives as ProcessData.pty and stdout and stderr are merged into it. |
tag | 3 | string | Unique, client-assigned name for reattaching. Starting a process with a tag that belongs to a running process fails with ALREADY_EXISTS. Tags of exited processes may be reused; the old entry leaves the retention cache. |
stdin | 4 | bool | Keep stdin open for SendInput / StreamInput. When false, stdin is connected to /dev/null (or NUL). |
keepalive_interval | 5 | google.protobuf.Duration | Interval between KeepAlive events on this stream. Unset means 30 seconds. Keep it below the idle timeout of any proxy in the path. |
scrollback_bytes | 6 | uint64 | Size of this process's scrollback ring in bytes. 0 means the server default (Limits.default_scrollback_bytes). |
kill_on_disconnect | 7 | bool | Kill the process (SIGTERM, then SIGKILL) when this RPC ends before the process does. Default false: processes are detached. |
request_id | 8 | string | Idempotency key. When set, the start is recorded in the exec ledger (a file in the server's data directory, written and synced before the process is spawned) and a later StartProcess with the same key does not run the command again: it reattaches to the running process (replaying retained output from the start), or replays the recorded outcome (ProcessStart.deduplicated is set, then the retained output tail, then ProcessEnd). A process that was running when the server stopped is recorded as lost and replays as ProcessEnd.lost. Empty means no ledger entry. At most 256 bytes. |
epoch | 9 | uint64 | Fencing epoch. 0 means unfenced. A value lower than the Space's current epoch fails with FAILED_PRECONDITION / ERROR_REASON_STALE_EPOCH; a higher value advances the epoch first, as AdvanceEpoch does. |
StartProcessResponse#
One message of the ProcessService.StartProcess stream.
| Field | # | Type | Description |
|---|---|---|---|
event | 1 | ProcessEvent | The event. |
ConnectProcessRequest#
Request for ProcessService.ConnectProcess.
| Field | # | Type | Description |
|---|---|---|---|
process | 1 | ProcessSelector | Which process. |
replay_bytes | 2 | uint64 | How many bytes of scrollback to replay before live output. 0 replays nothing. Values larger than the retained scrollback replay everything retained. Use replay_from_offset instead to resume precisely. |
replay_from_offset | 3 | optional uint64 | When set, replay retained output starting at this combined output offset (typically the last offset the client saw plus its length; 0 replays everything retained). Takes precedence over replay_bytes. If the offset has already been evicted from the ring, replay starts at the oldest retained byte and the first ProcessData.offset reveals the gap. |
keepalive_interval | 4 | google.protobuf.Duration | Interval between KeepAlive events. Unset means 30 seconds. |
ConnectProcessResponse#
One message of the ProcessService.ConnectProcess stream.
| Field | # | Type | Description |
|---|---|---|---|
event | 1 | ProcessEvent | The event. |
ProcessEvent#
A process lifecycle or output event.
| Field | # | Type | Description |
|---|---|---|---|
start | 1 | ProcessStart (oneof event) | The process started (or, on ConnectProcess, is known). |
data | 2 | ProcessData (oneof event) | Output bytes. |
end | 3 | ProcessEnd (oneof event) | The process ended. |
keepalive | 4 | KeepAlive (oneof event) | Idle stream heartbeat. |
ProcessStart#
Sent first on every process stream.
| Field | # | Type | Description |
|---|---|---|---|
pid | 1 | uint32 | Guest process id. |
tag | 2 | string | Tag, if any. |
started_at | 3 | google.protobuf.Timestamp | When the process started. |
scrollback_start_offset | 4 | uint64 | Combined output offset of the oldest byte still in the scrollback ring. |
output_end_offset | 5 | uint64 | Combined output offset one past the newest byte produced so far. |
deduplicated | 6 | bool | True when StartProcessRequest.request_id matched an earlier start, so this stream reattached to it or replays its recorded outcome instead of running the command again. |
request_id | 7 | string | The request's idempotency key, if any. |
ProcessData#
A chunk of process output.
| Field | # | Type | Description |
|---|---|---|---|
offset | 1 | uint64 | Combined output offset of the first byte in this chunk. |
stdout | 2 | bytes (oneof output) | Bytes written to stdout. |
stderr | 3 | bytes (oneof output) | Bytes written to stderr. |
pty | 4 | bytes (oneof output) | Bytes written to the PTY (stdout and stderr merged). |
ProcessEnd#
Sent last on every process stream once the process has exited.
| Field | # | Type | Description |
|---|---|---|---|
exit_code | 1 | optional int32 | Exit code, when the process exited normally. |
signal | 2 | Signal | Terminating signal, when the process was killed by a signal. |
timed_out | 3 | bool | True if the process was stopped because ProcessConfig.timeout elapsed. |
error | 4 | string | Set when the process could not be started or supervised (for example "executable not found"). exit_code and signal are unset then. |
ended_at | 5 | google.protobuf.Timestamp | When the process ended. |
lost | 6 | bool | True when the outcome is unknown: the process was running when the server stopped (crash, restart or Space restore), so it may have run partially or to completion. Only reported for request_id processes. |
signal_number | 7 | int32 | Raw number of the terminating signal on the guest's OS, set for every signal death (also those signal cannot name, such as SIGSEGV or SIGABRT, which leave signal unspecified). Zero when no signal ended the process. |
signal_name | 8 | string | Conventional name of the terminating signal without the SIG prefix and in upper case ("SEGV", "ABRT", "PIPE"). Unlike the number it does not depend on the guest's OS. Empty when no signal ended the process, or the number has no conventional name. |
ListProcessesRequest#
Request for ProcessService.ListProcesses.
| Field | # | Type | Description |
|---|---|---|---|
include_exited | 1 | bool | Also list exited processes still in the retention cache. |
tag_prefix | 2 | string | Only list processes whose tag starts with this prefix. |
ListProcessesResponse#
Response for ProcessService.ListProcesses.
| Field | # | Type | Description |
|---|---|---|---|
processes | 1 | repeated ProcessInfo | Matching processes, newest first. |
ProcessInfo#
A managed process.
| Field | # | Type | Description |
|---|---|---|---|
pid | 1 | uint32 | Guest process id. |
tag | 2 | string | Tag, if any. |
config | 3 | ProcessConfig | How it was started. Environment values are redacted to "" when the key looks secret (contains TOKEN, SECRET, KEY or PASSWORD). |
pty | 4 | bool | True if it runs under a PTY. |
state | 5 | ProcessState | Current state. |
end | 6 | ProcessEnd | Exit details, once exited. |
started_at | 7 | google.protobuf.Timestamp | When it started. |
scrollback_start_offset | 8 | uint64 | Combined output offset of the oldest retained byte. |
output_end_offset | 9 | uint64 | Combined output offset one past the newest byte. |
attached_clients | 10 | uint32 | Number of streams currently attached (StartProcess + ConnectProcess). |
ProcessInput#
Bytes destined for a process.
| Field | # | Type | Description |
|---|---|---|---|
stdin | 1 | bytes (oneof input) | Bytes for stdin. Requires StartProcessRequest.stdin. |
pty | 2 | bytes (oneof input) | Bytes for the PTY (keystrokes). Requires a PTY process. |
SendInputRequest#
Request for ProcessService.SendInput.
| Field | # | Type | Description |
|---|---|---|---|
process | 1 | ProcessSelector | Which process. |
input | 2 | ProcessInput | The bytes. At most Limits.max_chunk_bytes. |
sequence | 3 | uint64 | Optional ordering and de-duplication. 0 means "unsequenced": the chunk is applied in arrival order with no retry protection. When non-zero, sequences are tracked per (process, writer_id): the first sequenced chunk may start at any value, each later chunk must be exactly one greater than the last applied one, a chunk at or below the last applied sequence is acknowledged as a duplicate without being written again, and a gap fails with FAILED_PRECONDITION / ERROR_REASON_SEQUENCE_GAP. The SDK owns this counter; applications never set it. |
writer_id | 4 | string | Distinguishes independent sequenced writers to the same process. Empty is a valid writer id. |
SendInputResponse#
Response for ProcessService.SendInput.
| Field | # | Type | Description |
|---|---|---|---|
applied_sequence | 1 | uint64 | Highest sequence applied for this writer (0 for unsequenced input). |
duplicate | 2 | bool | True if this chunk was a retry of an already-applied sequence and was not written again. |
StreamInputRequest#
One message of the ProcessService.StreamInput client stream.
| Field | # | Type | Description |
|---|---|---|---|
process | 1 | ProcessSelector (oneof message) | First message only: which process to write to. |
input | 2 | ProcessInput (oneof message) | Subsequent messages: bytes to write, in order. |
keepalive | 3 | KeepAlive (oneof message) | Heartbeat from the client for long idle input streams. |
StreamInputResponse#
Response for ProcessService.StreamInput, sent when the client half-closes.
| Field | # | Type | Description |
|---|---|---|---|
bytes_written | 1 | uint64 | Total bytes written to the process. |
SignalProcessRequest#
Request for ProcessService.SignalProcess.
| Field | # | Type | Description |
|---|---|---|---|
process | 1 | ProcessSelector | Which process. |
signal | 2 | Signal | Which signal. |
process_group | 3 | bool | Signal the whole process group instead of the leader only. |
SignalProcessResponse#
Response for ProcessService.SignalProcess.
No fields.
CloseStdinRequest#
Request for ProcessService.CloseStdin.
| Field | # | Type | Description |
|---|---|---|---|
process | 1 | ProcessSelector | Which process. |
CloseStdinResponse#
Response for ProcessService.CloseStdin.
No fields.
ResizePtyRequest#
Request for ProcessService.ResizePty.
| Field | # | Type | Description |
|---|---|---|---|
process | 1 | ProcessSelector | Which process. Must run under a PTY. |
size | 2 | PtySize | New terminal size. |
ResizePtyResponse#
Response for ProcessService.ResizePty.
No fields.
GetExecRecordRequest#
Request for ProcessService.GetExecRecord.
| Field | # | Type | Description |
|---|---|---|---|
request_id | 1 | string | The StartProcessRequest.request_id to look up. |
GetExecRecordResponse#
Response for ProcessService.GetExecRecord.
| Field | # | Type | Description |
|---|---|---|---|
record | 1 | ExecRecord | The ledger entry. Absent when the key was never started here (or the entry was evicted: the ledger keeps the most recent 4096 keys). |
epoch | 2 | uint64 | The Space's current fencing epoch. |
ExecRecord#
What the exec ledger knows about one request_id.
| Field | # | Type | Description |
|---|---|---|---|
request_id | 1 | string | The idempotency key. |
state | 2 | ExecState | Where the command is. |
epoch | 3 | uint64 | The StartProcessRequest.epoch it was started with. |
pid | 4 | uint32 | Guest process id (0 when it never started). |
started_at | 5 | google.protobuf.Timestamp | When it was started. |
end | 6 | ProcessEnd | How it ended, once EXEC_STATE_EXITED or EXEC_STATE_LOST. |
output_bytes | 7 | uint64 | Total bytes of combined output (stdout, stderr, PTY), once exited. |
output_sha256 | 8 | string | Lowercase hex SHA-256 of the combined output in offset order, once exited. |
tail | 9 | repeated ProcessData | The last bytes of output (at most 64 KiB), in offset order, once exited. The first chunk's offset reveals what was dropped. |
AdvanceEpochRequest#
Request for ProcessService.AdvanceEpoch.
| Field | # | Type | Description |
|---|---|---|---|
epoch | 1 | uint64 | The new epoch. Must not be lower than the current epoch. |
AdvanceEpochResponse#
Response for ProcessService.AdvanceEpoch.
| Field | # | Type | Description |
|---|---|---|---|
epoch | 1 | uint64 | The current epoch after the call. |
killed | 2 | uint32 | Running processes killed because they carried a lower epoch. |
HealthProbe#
How a service's health is checked. Set exactly one of exec, http,
tcp.
| Field | # | Type | Description |
|---|---|---|---|
exec | 1 | ProcessConfig | A command that exits 0 when the service is healthy. |
http | 2 | string | A URL that answers 2xx or 3xx (http://127.0.0.1:8080/health). |
tcp | 3 | string | A port that accepts a TCP connection (127.0.0.1:5432). |
interval | 4 | google.protobuf.Duration | Between checks. Unset: 10 seconds. |
timeout | 5 | google.protobuf.Duration | For one check. Unset: 5 seconds. |
failure_threshold | 6 | uint32 | Failed checks in a row that mark it unhealthy and restart it. 0: 3. |
start_period | 7 | google.protobuf.Duration | Grace after a start before the first check counts. Unset: 10 seconds. |
ServiceSpec#
A service: a named command kept running.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Name: lowercase letters, digits, -, _ and ., 1 to 63 of them, starting with a letter or digit. |
config | 2 | ProcessConfig | What to run (timeout is ignored). |
restart | 3 | RestartPolicy | When it is started again. Unset: always. |
backoff_min | 4 | google.protobuf.Duration | First wait before a restart; it doubles on each quick failure. Unset: 1 second. |
backoff_max | 5 | google.protobuf.Duration | Longest wait before a restart. Unset: 60 seconds. |
probe | 6 | HealthProbe | Health check. Unset: the service is healthy while it runs. |
start_on_boot | 7 | optional bool | Start it when cua-spacesd starts. Unset: true. |
log_max_bytes | 8 | uint64 | Size at which the log file is rotated (one older file is kept). 0: 10 MiB. |
ServiceStatus#
A service and how it is doing.
| Field | # | Type | Description |
|---|---|---|---|
spec | 1 | ServiceSpec | What it runs. |
state | 2 | ServiceState | Where it is. |
pid | 3 | uint32 | Its current process, while it runs. |
restarts | 4 | uint32 | Starts after the first one. |
started_at | 5 | google.protobuf.Timestamp | When the current (or last) process started. |
last_end | 6 | ProcessEnd | How the last process ended. |
probe_error | 7 | string | The last failed health check, empty when the last one passed. |
next_start_at | 8 | google.protobuf.Timestamp | When it starts again (state SERVICE_STATE_BACKOFF). |
log_path | 9 | string | Its log file in the guest. |
PutServiceRequest#
Request for ProcessService.PutService.
| Field | # | Type | Description |
|---|---|---|---|
spec | 1 | ServiceSpec | The service. |
PutServiceResponse#
Response for ProcessService.PutService.
| Field | # | Type | Description |
|---|---|---|---|
service | 1 | ServiceStatus | Its state right after it was put. |
DeleteServiceRequest#
Request for ProcessService.DeleteService.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Name. |
DeleteServiceResponse#
Response for ProcessService.DeleteService.
No fields.
ListServicesRequest#
Request for ProcessService.ListServices.
No fields.
ListServicesResponse#
Response for ProcessService.ListServices.
| Field | # | Type | Description |
|---|---|---|---|
services | 1 | repeated ServiceStatus | By name. |
ControlServiceRequest#
Request for ProcessService.ControlService.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Name. |
action | 2 | ServiceAction | What to do. |
ControlServiceResponse#
Response for ProcessService.ControlService.
| Field | # | Type | Description |
|---|---|---|---|
service | 1 | ServiceStatus | Its state after the action. |
GetServiceLogsRequest#
Request for ProcessService.GetServiceLogs.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Name. |
tail_bytes | 2 | uint64 | How many bytes from the end. 0: 64 KiB; at most 4 MiB. |
GetServiceLogsResponse#
Response for ProcessService.GetServiceLogs.
| Field | # | Type | Description |
|---|---|---|---|
data | 1 | bytes | The end of its output (stdout and stderr interleaved as written). |
truncated | 2 | bool | True when older output was left out. |
ProcessState#
Lifecycle state of a managed process.
| Value | # | Description |
|---|---|---|
PROCESS_STATE_UNSPECIFIED | 0 | Not reported. |
PROCESS_STATE_RUNNING | 1 | Running (or stopped by SIGSTOP). |
PROCESS_STATE_EXITED | 2 | Exited; details in ProcessInfo.end. |
Signal#
POSIX signals. On Windows only SIGNAL_KILL and SIGNAL_TERM (mapped to
a console close / terminate) and SIGNAL_INT (CTRL_C_EVENT) are
supported; others fail with ERROR_REASON_FEATURE_UNSUPPORTED. Numbers
follow Linux x86-64 for readability only; the server maps each value to
the guest's native signal number.
| Value | # | Description |
|---|---|---|
SIGNAL_UNSPECIFIED | 0 | Not set. |
SIGNAL_HUP | 1 | SIGHUP. |
SIGNAL_INT | 2 | SIGINT. |
SIGNAL_QUIT | 3 | SIGQUIT. |
SIGNAL_KILL | 9 | SIGKILL. |
SIGNAL_USR1 | 10 | SIGUSR1. |
SIGNAL_USR2 | 12 | SIGUSR2. |
SIGNAL_TERM | 15 | SIGTERM. |
SIGNAL_CONT | 18 | SIGCONT. |
SIGNAL_STOP | 19 | SIGSTOP. |
SIGNAL_TSTP | 20 | SIGTSTP. |
SIGNAL_WINCH | 28 | SIGWINCH. |
ExecState#
Lifecycle of an exec ledger entry.
| Value | # | Description |
|---|---|---|
EXEC_STATE_UNSPECIFIED | 0 | Not reported. |
EXEC_STATE_RUNNING | 1 | Started by this server and still running. |
EXEC_STATE_EXITED | 2 | Exited (or could not start); ExecRecord.end says how. |
EXEC_STATE_LOST | 3 | Was running when the server stopped: the outcome is unknown. |
RestartPolicy#
When a service is started again.
| Value | # | Description |
|---|---|---|
RESTART_POLICY_UNSPECIFIED | 0 | Unset: RESTART_POLICY_ALWAYS. |
RESTART_POLICY_ALWAYS | 1 | Whenever it ends, however it ends. |
RESTART_POLICY_ON_FAILURE | 2 | When it ends with a non-zero code, a signal, or a failed health check. |
RESTART_POLICY_NEVER | 3 | Never: it runs once. |
ServiceState#
Where a service is.
| Value | # | Description |
|---|---|---|
SERVICE_STATE_UNSPECIFIED | 0 | Not reported. |
SERVICE_STATE_STARTING | 1 | Starting (or waiting for its first health check). |
SERVICE_STATE_RUNNING | 2 | Running, and healthy when it has a check. |
SERVICE_STATE_UNHEALTHY | 3 | Running, but its last checks failed. |
SERVICE_STATE_BACKOFF | 4 | Ended; waiting next_start_at to start again. |
SERVICE_STATE_STOPPED | 5 | Stopped by a caller. |
SERVICE_STATE_EXITED | 6 | Ended and its policy does not start it again. |
SERVICE_STATE_FAILED | 7 | Could not be started (the command does not exist, ...). |
ServiceAction#
What ControlService does.
| Value | # | Description |
|---|---|---|
SERVICE_ACTION_UNSPECIFIED | 0 | Not set (refused). |
SERVICE_ACTION_START | 1 | Start it (no-op when it runs). |
SERVICE_ACTION_STOP | 2 | Stop it and keep it stopped. |
SERVICE_ACTION_RESTART | 3 | Stop it, then start it. |
Types in cua/env/v1/filesystem.proto#
EntryInfo#
Metadata for one filesystem entry.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Final path component. |
path | 2 | string | Absolute, normalized path. |
type | 3 | FileType | Entry type. |
size | 4 | uint64 | Size in bytes (0 for directories). |
mode | 5 | uint32 | Unix permission bits (for example 0o644). Synthesized on Windows. |
owner | 6 | string | Owning user name. |
group | 7 | string | Owning group name (empty on Windows). |
modified_at | 8 | google.protobuf.Timestamp | Last modification time. |
symlink_target | 9 | string | Target of a symbolic link, when type is FILE_TYPE_SYMLINK. |
metadata | 10 | map of string to string | Extended attributes under the request's xattr_namespace (default user.cua.meta.), with the prefix removed. Empty when the entry has none or the file system has no extended attributes. |
StatRequest#
Request for FilesystemService.Stat.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Path to inspect. |
no_follow_symlinks | 2 | bool | Report the link itself rather than its target. |
xattr_namespace | 3 | string | Extended-attribute key prefix to report in EntryInfo.metadata. Empty means user.cua.meta.. |
run_as | 4 | string | Guest user to act as. Empty means the service's own user. |
StatResponse#
Response for FilesystemService.Stat.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The entry. |
ListDirRequest#
Request for FilesystemService.ListDir.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Directory to list. |
depth | 2 | uint32 | Recursion depth. 0 and 1 both list direct children only; 2 includes grandchildren, and so on. Symbolic links are never followed during recursion. |
include_hidden | 3 | bool | Include entries whose name starts with "." (and hidden entries on Windows). |
page_size | 4 | uint32 | Maximum entries per page. 0 means 1000. At most 10000. |
page_token | 5 | string | Continuation token from a previous ListDirResponse. |
xattr_namespace | 6 | string | Extended-attribute key prefix for EntryInfo.metadata. Empty means user.cua.meta.. |
run_as | 7 | string | Guest user to act as. Empty means the service's own user. |
ListDirResponse#
Response for FilesystemService.ListDir.
| Field | # | Type | Description |
|---|---|---|---|
entries | 1 | repeated EntryInfo | Entries in depth-first order, directories before their contents. |
next_page_token | 2 | string | Token for the next page, empty on the last page. |
MakeDirRequest#
Request for FilesystemService.MakeDir.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Directory to create. |
parents | 2 | bool | Create missing parents too. |
mode | 3 | uint32 | Permission bits. 0 means 0o755. |
run_as | 4 | string | Guest user to act as; created directories are owned by that user. |
MakeDirResponse#
Response for FilesystemService.MakeDir.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The directory. |
created | 2 | bool | False if it already existed (not an error). |
MoveRequest#
Request for FilesystemService.Move.
| Field | # | Type | Description |
|---|---|---|---|
source | 1 | string | Existing path. |
destination | 2 | string | New path. |
overwrite | 3 | bool | Replace an existing destination. Without it an existing destination fails with ALREADY_EXISTS / ERROR_REASON_PATH_EXISTS. |
create_parents | 4 | bool | Create missing parents of destination. |
run_as | 5 | string | Guest user to act as. |
MoveResponse#
Response for FilesystemService.Move.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The entry at its new path. |
RemoveRequest#
Request for FilesystemService.Remove.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Path to remove. |
recursive | 2 | bool | Remove a non-empty directory and its contents. |
missing_ok | 3 | bool | Succeed when the path does not exist. |
run_as | 4 | string | Guest user to act as. |
RemoveResponse#
Response for FilesystemService.Remove.
No fields.
FsEvent#
One filesystem change.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Absolute path of the affected entry. |
type | 2 | FsEventType | What happened. |
old_path | 3 | string | Previous path for renames, when the platform reports it. |
observed_at | 4 | google.protobuf.Timestamp | When the server observed the change. |
metadata | 5 | map of string to string | Extended attributes of the entry (see EntryInfo.metadata), read when the event is delivered; empty for removals and when the entry is gone. |
WatchDirRequest#
Request for FilesystemService.WatchDir.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Directory to watch. |
recursive | 2 | bool | Watch the whole subtree. |
keepalive_interval | 3 | google.protobuf.Duration | Interval between keepalive messages. Unset means 30 seconds. |
xattr_namespace | 4 | string | Extended-attribute key prefix for FsEvent.metadata. Empty means user.cua.meta.. |
run_as | 5 | string | Guest user to watch as. |
WatchStarted#
Sent once when a watch is armed.
No fields.
WatchOverflow#
Sent when the kernel event queue overflowed and events were lost. Clients should rescan.
No fields.
WatchDirResponse#
One message of the FilesystemService.WatchDir stream.
| Field | # | Type | Description |
|---|---|---|---|
started | 1 | WatchStarted (oneof message) | First message: the watch is armed. |
event | 2 | FsEvent (oneof message) | A change. |
overflow | 3 | WatchOverflow (oneof message) | Events were dropped. |
keepalive | 4 | KeepAlive (oneof message) | Idle stream heartbeat. |
CreateWatcherRequest#
Request for FilesystemService.CreateWatcher.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Directory to watch. |
recursive | 2 | bool | Watch the whole subtree. |
xattr_namespace | 3 | string | Extended-attribute key prefix for FsEvent.metadata. Empty means user.cua.meta.. |
run_as | 4 | string | Guest user to watch as. |
CreateWatcherResponse#
Response for FilesystemService.CreateWatcher. The watcher is armed when
this returns.
| Field | # | Type | Description |
|---|---|---|---|
watcher_id | 1 | string | Watcher id for GetWatcherEvents and RemoveWatcher. |
GetWatcherEventsRequest#
Request for FilesystemService.GetWatcherEvents.
| Field | # | Type | Description |
|---|---|---|---|
watcher_id | 1 | string | Which watcher. |
max_events | 2 | uint32 | Maximum events to return. 0 means all buffered. |
GetWatcherEventsResponse#
Response for FilesystemService.GetWatcherEvents.
| Field | # | Type | Description |
|---|---|---|---|
events | 1 | repeated FsEvent | Buffered events, oldest first. Returned events are removed from the buffer. |
overflowed | 2 | bool | True if the watcher's buffer (10000 events) overflowed since the last poll and events were dropped. Clients should rescan. |
RemoveWatcherRequest#
Request for FilesystemService.RemoveWatcher.
| Field | # | Type | Description |
|---|---|---|---|
watcher_id | 1 | string | Which watcher. |
RemoveWatcherResponse#
Response for FilesystemService.RemoveWatcher.
No fields.
ReadFileRequest#
Request for FilesystemService.ReadFile.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | File to read. |
offset | 2 | uint64 | First byte to read. |
length | 3 | uint64 | Maximum bytes to read. 0 means to end of file. |
chunk_size | 4 | uint32 | Preferred chunk size. 0 means Limits.preferred_chunk_bytes (1 MiB). Clamped to Limits.max_chunk_bytes. |
compute_sha256 | 5 | bool | Compute the SHA-256 of the bytes sent and report it in ReadFileEnd. |
bulk_slot | 8 | uint32 | Deliver through the bulk lane instead of the stream: n stages the bytes (at most BulkLane.slot_bytes, so length must be set) in slot n - 1 of the bulk disk, and the stream carries entry and end (bytes_read, sha256) but no chunks. 0 streams. Fails with ERROR_REASON_FEATURE_UNSUPPORTED when the guest has no bulk lane. |
xattr_namespace | 6 | string | Extended-attribute key prefix for the first message's EntryInfo.metadata. Empty means user.cua.meta.. |
run_as | 7 | string | Guest user to read as. |
ReadFileResponse#
One message of the FilesystemService.ReadFile stream: entry first,
then zero or more chunks in order, then end.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo (oneof message) | File metadata, sent first. |
chunk | 2 | FileChunk (oneof message) | File content. |
end | 3 | ReadFileEnd (oneof message) | Sent last. |
FileChunk#
A slice of file content.
| Field | # | Type | Description |
|---|---|---|---|
offset | 1 | uint64 | Absolute file offset of data[0]. |
data | 2 | bytes | The bytes. |
ReadFileEnd#
Final message of a ReadFile stream.
| Field | # | Type | Description |
|---|---|---|---|
bytes_read | 1 | uint64 | Bytes sent in chunks. |
sha256 | 2 | string | Lowercase hex SHA-256 of the bytes sent, when requested. |
WriteFileHeader#
Destination and options for a write.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Destination path. |
mode | 2 | WriteMode | How to treat an existing file. |
permissions | 3 | uint32 | Permission bits for a new file. 0 means 0o644. |
create_parents | 4 | bool | Create missing parent directories. |
expected_size | 5 | uint64 | Expected total size in bytes, 0 if unknown. Checked on completion when non-zero. |
expected_sha256 | 6 | string | Expected lowercase hex SHA-256 of the full content. Checked on completion when set; a mismatch discards the data and fails with ERROR_REASON_CHECKSUM_MISMATCH. |
run_as | 7 | string | Guest user to write as. The file (and any parents created with create_parents) is owned by that user. Uploads keep the user they began with. |
metadata | 8 | map of string to string | Extended attributes to store on the new file, published atomically with the content. Keys are stored under xattr_namespace. |
xattr_namespace | 9 | string | Key prefix for metadata and for the reported EntryInfo.metadata. Empty means user.cua.meta.. |
WriteFileRequest#
One message of the FilesystemService.WriteFile client stream.
| Field | # | Type | Description |
|---|---|---|---|
header | 1 | WriteFileHeader (oneof message) | First message only. |
data | 2 | bytes (oneof message) | File content, strictly sequential. Each chunk is at most Limits.max_chunk_bytes. |
WriteFileResponse#
Response for FilesystemService.WriteFile.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The written file. |
sha256 | 2 | string | Lowercase hex SHA-256 of the bytes received. |
BeginUploadRequest#
Request for FilesystemService.BeginUpload.
| Field | # | Type | Description |
|---|---|---|---|
header | 1 | WriteFileHeader | Destination and options. expected_sha256 is strongly recommended. |
upload_id | 2 | string | Client-chosen id that makes this call idempotent and resumable. If an unexpired upload with this id exists for the same path, the call returns its current received_bytes instead of starting over. Empty lets the server generate an id (not resumable after the response is lost). |
ttl | 3 | google.protobuf.Duration | How long partial data is kept without progress. Unset means 1 hour. At most 24 hours. |
BeginUploadResponse#
Response for FilesystemService.BeginUpload.
| Field | # | Type | Description |
|---|---|---|---|
upload_id | 1 | string | Upload id for later calls. |
received_bytes | 2 | uint64 | Bytes already received. 0 for a new upload; the resume point otherwise. |
max_chunk_bytes | 3 | uint32 | Largest chunk the server accepts. |
expires_at | 4 | google.protobuf.Timestamp | When the partial upload expires if no further chunks arrive. |
UploadChunkRequest#
Request for FilesystemService.UploadChunk.
| Field | # | Type | Description |
|---|---|---|---|
upload_id | 1 | string | Which upload. |
offset | 2 | uint64 | Offset of data[0]. Must equal the server's received_bytes; a chunk wholly below it is acknowledged as a duplicate, anything else fails with ERROR_REASON_OFFSET_MISMATCH and metadata["expected_offset"]. |
data | 3 | bytes | The bytes. At most max_chunk_bytes. Empty with bulk_slot. |
bulk_slot | 4 | uint32 | The bytes are in slot n - 1 of the bulk disk (bulk_len of them, at most BulkLane.slot_bytes) instead of data. 0 uses data. |
bulk_len | 5 | uint64 | Length of the bulk slot's bytes. |
UploadChunkResponse#
Response for FilesystemService.UploadChunk.
| Field | # | Type | Description |
|---|---|---|---|
received_bytes | 1 | uint64 | Total bytes received so far. |
duplicate | 2 | bool | True if the chunk was a retry and was not written again. |
expires_at | 3 | google.protobuf.Timestamp | New expiry of the partial upload. |
CommitUploadRequest#
Request for FilesystemService.CommitUpload.
| Field | # | Type | Description |
|---|---|---|---|
upload_id | 1 | string | Which upload. |
sha256 | 2 | string | Expected lowercase hex SHA-256, overriding the header's. Optional. |
CommitUploadResponse#
Response for FilesystemService.CommitUpload.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The published file. |
sha256 | 2 | string | Lowercase hex SHA-256 of the committed content. |
AbortUploadRequest#
Request for FilesystemService.AbortUpload.
| Field | # | Type | Description |
|---|---|---|---|
upload_id | 1 | string | Which upload. |
AbortUploadResponse#
Response for FilesystemService.AbortUpload.
No fields.
CreateSignedUrlRequest#
Request for FilesystemService.CreateSignedUrl.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Path the URL grants access to. Exactly this path; no traversal. |
method | 2 | SignedUrlMethod | Allowed method. |
ttl | 3 | google.protobuf.Duration | Validity. Required; at most 24 hours. |
content_type | 4 | string | For GET: Content-Type to serve. Empty means guessed from the name. |
download_name | 5 | string | For GET: serve with Content-Disposition: attachment using this file name. Empty means inline. |
run_as | 6 | string | Guest user the URL acts as. Part of the signature, so it cannot be changed or added by the holder of the URL. A PUT URL may also be used with POST multipart/form-data (first file part). |
create_parents | 7 | bool | For PUT: create missing parent directories of the file (owned by run_as when set). Part of the signature. |
CreateSignedUrlResponse#
Response for FilesystemService.CreateSignedUrl.
| Field | # | Type | Description |
|---|---|---|---|
url_path | 1 | string | Path and query to append to the spacesd's base URL, for example "/files?path=%2Fhome%2Fu%2Fa.png&method=GET&exp=1767225600&sig=…". The server does not know how it is addressed (direct, gateway, relay), so it never returns an absolute URL. The signature is HMAC-SHA256 over method, path and expiry with a key derived from the access token; rotating the token revokes every outstanding URL. |
expires_at | 2 | google.protobuf.Timestamp | When the URL stops working. |
FileType#
Type of a filesystem entry.
| Value | # | Description |
|---|---|---|
FILE_TYPE_UNSPECIFIED | 0 | Not reported. |
FILE_TYPE_FILE | 1 | Regular file. |
FILE_TYPE_DIRECTORY | 2 | Directory. |
FILE_TYPE_SYMLINK | 3 | Symbolic link (only when not following links). |
FILE_TYPE_OTHER | 4 | Anything else (socket, FIFO, device). |
FsEventType#
Kind of filesystem change.
| Value | # | Description |
|---|---|---|
FS_EVENT_TYPE_UNSPECIFIED | 0 | Not reported. |
FS_EVENT_TYPE_CREATE | 1 | Entry created. |
FS_EVENT_TYPE_WRITE | 2 | File content written. |
FS_EVENT_TYPE_REMOVE | 3 | Entry removed. |
FS_EVENT_TYPE_RENAME | 4 | Entry renamed or moved. path is the new path when known. |
FS_EVENT_TYPE_CHMOD | 5 | Permissions or ownership changed. |
WriteMode#
How WriteFile and uploads treat an existing destination.
| Value | # | Description |
|---|---|---|
WRITE_MODE_UNSPECIFIED | 0 | Not set. Treated as WRITE_MODE_OVERWRITE. |
WRITE_MODE_OVERWRITE | 1 | Replace any existing file atomically. |
WRITE_MODE_CREATE_NEW | 2 | Fail with ERROR_REASON_PATH_EXISTS if the destination exists. |
WRITE_MODE_APPEND | 3 | Append to the existing file (created if missing). Not atomic. |
SignedUrlMethod#
HTTP method a signed URL is valid for.
| Value | # | Description |
|---|---|---|
SIGNED_URL_METHOD_UNSPECIFIED | 0 | Not set. Rejected. |
SIGNED_URL_METHOD_GET | 1 | Download with GET (supports Range). |
SIGNED_URL_METHOD_PUT | 2 | Upload with PUT (the body replaces the file atomically). The same URL also accepts POST multipart/form-data: the first file part replaces the file atomically and the response is the JSON list [{"name","path","type"}]. |