Skip to content

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.

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

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.label is /chainguard-sandbox/<name> (name defaults to sandbox). The label is how Sandbox.list tells the SDK’s sandboxes from other sessions. document is the generated environment document below, and provenance is AUTHORED.
  • From a repository (source option): source.repository is the URL normalized to https://…, source.revision the revision, and source.fallback_document the generated document.

The generated environment document lists your packages and the egress policy (see Environments):

# Generated by chainguard-sandbox-sdk.
version: 1
environment:
packages:
- "bash"
- "coreutils"
- "python-3.13"
checks:
develop:
network:
egress:
- "*"
policy: "deny"
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 message contains starting guest failed for 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 = true and refuses Exec until the first attach.
message GetSessionRequest {
string name = 1; // required
}

Returns the Session. A deleted (or never existing) session is NOT_FOUND.

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.

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.

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.

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.