Skip to content

Protocol

First Attach

AttachSession is the bidirectional stream that chainctl develop uses for interactive terminals. The simple SDK uses it for one thing only: completing a new sandbox’s first attach, which the service requires before it allows Exec.

A session created with a workspace environment expects the client’s files to be uploaded on the first interactive attach (Session.workspace_pending is true until then). Until that happens:

  • Exec is refused: FAILED_PRECONDITION “attach with a shell first to upload the workspace”.
  • A forwarding-only attach doesn’t count: open.no_shell needs open.endpoints (“open.endpoints: required for a no_shell attach”).

So right after CreateSession (and in connect, if a sandbox still has workspace_pending), the SDK opens one short shell attach, uploads an empty tree, and detaches. It takes about 0.2 s. A session started from a repository (source) doesn’t need it.

Sessions APISDKthe SDK cancels the stream: that's the detachAttachRequest.open {name, resume: {}}1AttachResponse.opened {workspace_pending: true, workspace_encodings}2AttachRequest.workspace_chunk {data: empty tar, last: true, format: FULL_TAR}3AttachResponse.workspace_ready {bytes, elapsed}4
  1. Open: the first message must be open. The SDK sends only the session name and an empty resume. Terminal size, working directory and the other options are left unset.
  2. Opened: the service answers opened. If workspace_pending is false, there’s nothing to upload and the SDK detaches right away.
  3. Upload: one workspace_chunk with an empty tar archive (1,024 zero bytes, the tar end-of-archive marker), last = true, format = FULL_TAR. If opened.workspace_encodings includes GZIP, the SDK gzips it and sets encoding = GZIP.
  4. Ready: the service unpacks it into /work (nothing) and answers workspace_ready.
  5. Detach: the SDK cancels the RPC. The session keeps running and is now ready for Exec.

Only the parts of the two oneofs the SDK uses are shown:

rpc AttachSession (stream AttachRequest) returns (stream AttachResponse);
message AttachRequest {
oneof input {
Open open = 1; // first message
WorkspaceChunk workspace_chunk = 4;
// not used by the simple SDK: stdin = 2, resize = 3, forward_response = 6,
// stdin_eof = 7, grant = 8, resume = 9, credentials, PTY control, sharing
}
message Open {
string name = 1; // required: the session
Resume resume = 4; // the SDK sends an empty Resume
// rows = 2, cols = 3, no_shell = 5, endpoints = 6, handoff = 7, org_consent = 8,
// working_dir = 9, multi_pty = 10, end_input_at_prompt = 11: left unset
}
message Resume {
uint64 incarnation = 1; // all zero on a first attach
int64 offset = 2;
uint32 pty_id = 3;
}
message WorkspaceChunk {
bytes data = 1;
bool last = 2;
Format format = 3;
Encoding encoding = 4;
enum Format {
FORMAT_UNSPECIFIED = 0;
FULL_TAR = 1; // what the SDK sends
DELTA_TAR = 2; // git-delta uploads: not used
}
enum Encoding {
ENCODING_UNSPECIFIED = 0;
GZIP = 1;
}
}
}
message AttachResponse {
oneof output {
Opened opened = 5;
WorkspaceReady workspace_ready = 6;
Detached detached = 4; // another client took over
// not used by the simple SDK: stdout = 1, stderr = 2, exit = 3,
// forwarding, credential, PTY and sharing messages
}
message Opened {
int32 rows = 1;
int32 cols = 2;
string session_name = 3;
bool workspace_pending = 4; // an upload is expected
repeated AttachRequest.WorkspaceChunk.Encoding workspace_encodings = 6;
}
message WorkspaceReady {
int64 bytes = 1;
google.protobuf.Duration elapsed = 2;
}
message Detached {}
}
  • While the stream is open, the SDK’s attach holds the session’s lease (shell_attach_holder), so a concurrent Exec would wait. The SDK makes no other calls until it has detached.
  • Right after the detach, the first Exec can get FAILED_PRECONDITION “instance held by another controller” for a moment; the SDK retries it (see Exec).