Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt

Use this file to discover all available pages before exploring further.

AgentClient is the low-level raw transport for talking to agentd through a running sandbox’s relay socket. Most applications should use Sandbox, exec, and fs instead. Use this API when you are building protocol-level tools or higher-level SDK helpers. All request bodies and response bodies are raw CBOR bytes. The SDK handles framing and correlation ids, but it does not encode or decode the CBOR message body for you. The raw body is the full CBOR-encoded protocol Message body: v, t, and p. It is not just the inner payload. 
import { AgentClient } from "microsandbox";

const client = await AgentClient.connectSandbox("dev");
const ready = client.readyBytes();
await client.close();

​
Constants

NameValueDescription
FLAG_TERMINAL0b0000_0001Last frame for a correlation id
FLAG_SESSION_START0b0000_0010First frame of a streaming session
FLAG_SHUTDOWN0b0000_0100Shutdown frame

​
AgentClient.connectSandbox()

static connectSandbox(name: string): Promise<AgentClient>
Connect to a running sandbox by name.

​
AgentClient.connect()

static connect(path: string): Promise<AgentClient>
Connect to an agent relay socket by path.

​
request()

request(flags: number, body: Buffer): Promise<RawFrame>
Send one raw frame and wait for one response frame.

​
stream()

stream(flags: number, body: Buffer): Promise<AgentStream>
Open a raw streaming session. The returned stream carries the protocol correlation id and is also an async iterator of raw frames. 
const stream = await client.stream(FLAG_SESSION_START, body);
for await (const frame of stream) {
  if ((frame.flags & FLAG_TERMINAL) !== 0) break;
}

​
send()

send(id: number, flags: number, body: Buffer): Promise<void>
Send a follow-up frame on an existing correlation id. Use this with the id on the AgentStream returned by stream().

​
readyBytes()

readyBytes(): Buffer
Return the cached handshake core.ready frame body as CBOR bytes.

​
close()

close(): Promise<void>
Close the client. Calling it more than once is safe.

​
RawFrame

interface RawFrame {
  readonly id: number;
  readonly flags: number;
  readonly body: Buffer;
}
id is the protocol correlation id, flags is the frame flag byte, and body is the CBOR-encoded protocol message body.

​
AgentStream

class AgentStream implements AsyncIterableIterator<RawFrame> {
  readonly id: number;
  next(): Promise<IteratorResult<RawFrame>>;
  close(): Promise<void>;
}
id is the protocol correlation id. Pass it to AgentClient.send() for follow-up frames in the same session. close() releases the stream handle early.