Processes
cua.env.v1 ProcessService: start, attach to, feed and signal guest processes.
cua.env.v1 ProcessService: start, attach to, feed and signal guest processes.
Detached, reattachable guest processes with PTY support and bounded scrollback.
Source: libs/cua/proto/cua/env/v1/process.proto.
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.
/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.
/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.
/cua.env.v1.ProcessService/ListProcesses, unary: ListProcessesRequest to ListProcessesResponse.
Lists managed processes.
/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.
/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)./cua.env.v1.ProcessService/SignalProcess, unary: SignalProcessRequest to SignalProcessResponse.
Sends a signal to a process (or its process group).
/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.
/cua.env.v1.ProcessService/ResizePty, unary: ResizePtyRequest to ResizePtyResponse.
Resizes a PTY process's terminal (delivers SIGWINCH on Unix).
cua/env/v1/process.proto#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. |
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". |
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. |
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. |
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. |
One message of the ProcessService.StartProcess stream.
| Field | # | Type | Description |
|---|---|---|---|
event | 1 | ProcessEvent | The event. |
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. |
One message of the ProcessService.ConnectProcess stream.
| Field | # | Type | Description |
|---|---|---|---|
event | 1 | ProcessEvent | The event. |
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. |
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. |
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). |
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. |
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. |
Response for ProcessService.ListProcesses.
| Field | # | Type | Description |
|---|---|---|---|
processes | 1 | repeated ProcessInfo | Matching processes, newest first. |
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). |
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. |
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. |
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. |
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. |
Response for ProcessService.StreamInput, sent when the client half-closes.
| Field | # | Type | Description |
|---|---|---|---|
bytes_written | 1 | uint64 | Total bytes written to the process. |
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. |
Response for ProcessService.SignalProcess.
No fields.
Request for ProcessService.CloseStdin.
| Field | # | Type | Description |
|---|---|---|---|
process | 1 | ProcessSelector | Which process. |
Response for ProcessService.CloseStdin.
No fields.
Request for ProcessService.ResizePty.
| Field | # | Type | Description |
|---|---|---|---|
process | 1 | ProcessSelector | Which process. Must run under a PTY. |
size | 2 | PtySize | New terminal size. |
Response for ProcessService.ResizePty.
No fields.
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. |
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. |