Protocol
Protocol Overview
This section describes the wire protocol behind the Simple Chainguard Sandbox SDK: the gRPC calls, the protobuf messages and fields, and the two HTTP endpoints that the Go, Python, TypeScript and Rust packages use. It’s meant for debugging, for writing a client in another language, and for understanding what each SDK call costs.
Scope: only what the simple sandboxing API uses. The Workspaces API is much larger. Interactive
terminals, workspace syncing (delta uploads of a git checkout), git mirrors and identities, credential and
HTTP forwarding, checks (RunCI), sharing, policies and limits aren’t covered here, because the SDK
doesn’t use them.
The messages match the Sessions API as used by chainctl 0.2.398. The SDK generates its code from
proto/sandbox/runtime/session/v1/session.proto,
which holds exactly this subset. Excerpts show only the fields the SDK
reads or writes; field numbers are the real ones.
Endpoints
Section titled “Endpoints”| What | Endpoint | Protocol |
|---|---|---|
| Sessions API | sessions.chainbox.dev:443 |
gRPC over TLS (HTTP/2) |
| Login and token refresh | https://issuer.enforce.dev |
HTTPS, browser redirect and a POST |
| Organization lookup (optional) | https://console-api.enforce.dev |
HTTPS, one GET |
Every gRPC call carries two pieces of metadata:
authorization: Bearer <token>: a Chainguard token whose audience ishttps://sessions.chainbox.dev(see Authentication and Organizations). The SDKs refuse to send it over plaintext.user-agent:chainguard-sandbox-sdk-go,chainguard-sandbox-sdk-py,chainguard-sandbox-sdk-tsorchainguard-sandbox-sdk-rs.
The service is chainguard.sandbox.runtime.session.v1.Sessions. The SDK uses eight of its RPCs:
package chainguard.sandbox.runtime.session.v1;
service Sessions { rpc CreateSession (CreateSessionRequest) returns (Session); rpc GetSession (GetSessionRequest) returns (Session); rpc ListSessions (ListSessionsRequest) returns (ListSessionsResponse); rpc UpdateSession (UpdateSessionRequest) returns (Session); rpc DeleteSession (DeleteSessionRequest) returns (google.protobuf.Empty); rpc HeartbeatSession (HeartbeatSessionRequest) returns (Session); rpc Exec (ExecRequest) returns (stream ExecResponse); rpc AttachSession (stream AttachRequest) returns (stream AttachResponse);}The service also declares google.api.http REST mappings (for example GET /v1/{name=instances/*/sessions/*})
for every RPC except AttachSession. The SDKs use gRPC only.
Resource Names
Section titled “Resource Names”| Resource | Name | Example |
|---|---|---|
| Organization (“instance”) | instances/{organization ID} |
instances/XXXXXX |
| Sandbox (a session) | instances/{organization ID}/sessions/{session ID} |
returned by CreateSession in Session.name |
A sandbox’s short ID (Session.short_id) and display name are for people; every RPC
takes the full resource name. connect accepts all three and resolves short IDs and display names with
ListSessions.
SDK Calls and Their RPCs
Section titled “SDK Calls and Their RPCs”| SDK call | RPCs |
|---|---|
Sandbox.create |
CreateSession, then GetSession about once a second until the guest starts, then one short AttachSession (the first attach) |
Sandbox.connect(id) |
GetSession (full name), or ListSessions (short ID or display name); the first attach if it hasn’t happened |
Sandbox.list |
ListSessions, keeping sessions whose workspace label starts with /chainguard-sandbox/ |
get_info, is_running |
GetSession |
commands.run, commands.*, files.* |
Exec (one per call; see Exec) |
pause |
UpdateSession with park_request = PARK_REQUEST_PARK |
keep_alive(seconds) |
HeartbeatSession with hold_for |
kill |
DeleteSession, then GetSession until it returns NOT_FOUND |
workspaces_status, enable_workspaces |
Platform API calls over HTTPS, not Sessions RPCs (see Enabling Workspaces) |
| choosing the organization | GET console-api.enforce.dev/iam/v1/groups when none is set (see Authentication and Organizations) |
Pages in This Section
Section titled “Pages in This Section”- Sessions: the
Sessionresource and the create, get, list, update, delete and heartbeat calls. - Exec: running a process, and how commands and files are built on it.
- First Attach: the one
AttachSessionexchange the SDK needs. - Authentication and Organizations: the login, token refresh and organization lookup.
- Status Codes: gRPC status codes and the SDK errors they become.
