Protocol
Sessions
A sandbox is a Workspaces session. This page covers the Session resource and the six unary calls the
SDK makes on it. Running commands is on the Exec page.
The Session Resource
Section titled “The Session Resource”Session has about fifty fields. These are the ones the SDK sets or reads:
message Session { string name = 1; // output: instances/…/sessions/… string display_name = 2; string short_id = 3; // output string owner = 4; // output google.protobuf.Timestamp create_time = 5; // output
oneof environment { // immutable; the SDK sets one Source source = 7; // start from a repository Workspace workspace = 33; // start empty (the default) }
Phase phase = 11; // output google.protobuf.Timestamp park_after = 13; // output google.protobuf.Timestamp expire_time = 14; // output string message = 18; // output: the latest status text google.protobuf.Timestamp guest_started_time = 23; // output: the VM booted bool workspace_pending = 24; // output: first attach still due google.protobuf.Timestamp held_until = 34; // output IdlePolicy idle = 35; string region = 43; // output SessionResourceLimit max_resource_class = 44; // output: the VM's size ParkRequest park_request = 53;
enum ParkRequest { PARK_REQUEST_UNSPECIFIED = 0; PARK_REQUEST_PARK = 1; // snapshot and stop now PARK_REQUEST_RESTART = 2; // not used by the SDK }}
message SessionResourceLimit { int32 cpus = 1; int64 memory_mib = 2; optional int64 disk_mib = 3;}
enum Phase { PHASE_UNSPECIFIED = 0; CREATING = 1; ATTACHED = 2; IDLE = 3; PARKED = 4; REAPED = 5;}
enum IdlePolicy { IDLE_POLICY_UNSPECIFIED = 0; PARK_WHEN_IDLE = 1; KEEP_RUNNING = 2; AUTO_HOLD = 3; // what the SDK sends}How the SDK uses them:
| Field | Used for |
|---|---|
name |
Every later call. Sandbox.name in the SDKs |
short_id |
The sandbox ID (sbx.id, Sandbox.connect(id)) |
display_name, region, create_time |
get_info() |
max_resource_class |
get_info(): the sandbox’s CPUs and memory |
phase |
get_info().state: CREATING → creating; ATTACHED or IDLE → running; PARKED → paused; anything else → stopped |
guest_started_time |
create returns once it’s set |
message |
Detecting a session placed on a host that can’t start it (below) |
workspace_pending |
Whether the first attach is still needed |
idle |
Sent as AUTO_HOLD on create: the session parks when idle unless it’s busy or held |
park_request |
pause |
Starting Empty or From a Repository
Section titled “Starting Empty or From a Repository”The session’s environment is set once, at create:
message Workspace { // Session.workspace: empty /work string label = 1; // required string repository = 2; // not set by the SDK string revision = 3; // not set by the SDK bytes document = 4; // required: environment (YAML) Provenance provenance = 5; // required}
message Source { // Session.source: clone a repository string repository = 1; // required: https://github.com/o/r string revision = 2; // branch, tag or commit; empty: default bytes fallback_document = 3; // used if the repo has no environment bool fallback_used = 4; // output}
enum Provenance { PROVENANCE_UNSPECIFIED = 0; AUTHORED = 1; // what the SDK sends MIGRATED = 2; SYNTHESIZED = 3;}- Empty (the default):
workspace.labelis/chainguard-sandbox/<name>(namedefaults tosandbox). The label is howSandbox.listtells the SDK’s sandboxes from other sessions.documentis the generated environment document below, andprovenanceisAUTHORED. - From a repository (
sourceoption):source.repositoryis the URL normalized tohttps://…,source.revisionthe revision, andsource.fallback_documentthe generated document.
The generated environment document lists your packages and the egress policy (see Environments):
# Generated by chainguard-sandbox-sdk.version: 1environment: packages: - "bash" - "coreutils" - "python-3.13"checks: develop: network: egress: - "*" policy: "deny"CreateSession
Section titled “CreateSession”message CreateSessionRequest { string parent = 1; // required: instances/{org} Session session = 2; // required // replay_bindings = 3, kernel_module_overrides = 4: not set by the SDK}The response is the new Session in phase CREATING. The SDK then polls GetSession about once a second
until guest_started_time is set (6–10 s in practice; the SDK gives up after start_timeout, 3 minutes by
default).
- Bad placement: if
messagecontainsstarting guest failedfor more than 30 s, the session landed on a host that can’t start it. The SDK deletes it and creates a new one, up to 3 attempts. - Limits: creating past your plan’s sandbox limit fails with
RESOURCE_EXHAUSTED(see Status Codes). - Next: a new empty session has
workspace_pending = trueand refusesExecuntil the first attach.
GetSession
Section titled “GetSession”message GetSessionRequest { string name = 1; // required}Returns the Session. A deleted (or never existing) session is NOT_FOUND.
ListSessions
Section titled “ListSessions”message ListSessionsRequest { string parent = 1; // required: instances/{org} int32 page_size = 2; string page_token = 3; string owner = 4; // empty: the caller's own sessions}
message ListSessionsResponse { repeated Session sessions = 1; string next_page_token = 2; // empty on the last page}The SDK follows next_page_token until it’s empty, then keeps the sessions whose workspace.label starts
with /chainguard-sandbox/. It sends no page size, so the service’s default applies.
UpdateSession: Pause
Section titled “UpdateSession: Pause”message UpdateSessionRequest { Session session = 1; // required google.protobuf.FieldMask update_mask = 2; // required}pause sends session = {name, park_request: PARK_REQUEST_PARK} with update_mask.paths = ["park_request"].
The call returns at once; the session reaches PARKED in about 40 s. Any later Exec (or attach) resumes
it, which the service does on its own.
HeartbeatSession: Keep Alive
Section titled “HeartbeatSession: Keep Alive”message HeartbeatSessionRequest { string name = 1; // required google.protobuf.Duration hold_for = 2; // keep running this long}keep_alive(seconds) sends hold_for; the session’s held_until moves accordingly.
DeleteSession
Section titled “DeleteSession”message DeleteSessionRequest { string name = 1; // required}Returns google.protobuf.Empty. The session is gone (GetSession returns NOT_FOUND) 1–8 s later. kill
waits for that, because the plan’s per-user sandbox slot is only free once the session is gone.
