Skip to content

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.

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 is https://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-ts or chainguard-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 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 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)
Sessions APISDKloop[until guest_started_time is set]the SDK cancels the stream (detach)CreateSession(parent, session with workspace and document)1Session (phase CREATING)2GetSession(name)3AttachSession: Open, then one empty FULL_TAR WorkspaceChunk4Opened, then WorkspaceReady5Exec(name, argv, stdin, deadline), once per command or file call6stdout and stderr chunks, then Exited(code, timed_out)7DeleteSession(name)8
  • Sessions: the Session resource 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 AttachSession exchange the SDK needs.
  • Authentication and Organizations: the login, token refresh and organization lookup.
  • Status Codes: gRPC status codes and the SDK errors they become.