--- title: Agent client description: TypeScript SDK - Low-level agentd client reference --- `AgentClient` is the low-level raw transport for talking to `agentd` through a running sandbox's relay socket. Most applications should use [`Sandbox`](/sdk/typescript/sandbox), [`exec`](/sdk/typescript/execution), and [`fs`](/sdk/typescript/filesystem) instead. Reach for this API when you are building protocol-level tools or higher-level SDK helpers. All request 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: decode it with a library such as `cbor-x`. The raw body is the full CBOR-encoded protocol `Message` body (`v`, `t`, `p`), not just the inner payload.

Constants3

FLAG_TERMINALlast frame for a correlation id FLAG_SESSION_STARTfirst frame of a session FLAG_SHUTDOWNrequest sandbox shutdown

Static · AgentClient3

AgentClient.connectSandbox()connect by sandbox name AgentClient.connect()connect by socket path AgentClient.socketPath()resolve socket path only

Instance · AgentClient5

client.request()one frame, one response client.stream()open a streaming session client.send()follow-up frame on an id client.readyBytes()cached handshake frame client.close()close the connection

Instance · AgentStream4

stream.idprotocol correlation id stream.next()pull the next frame stream.close()release the stream handle stream.return()iterator early-exit hook

Types

AgentClient AgentStream RawFrame AgentConnectOptions

Typical flow

```typescript import { encode, decode } from "cbor-x"; import { AgentClient, FLAG_SESSION_START } from "microsandbox"; const client = await AgentClient.connectSandbox("dev"); // 1. connect const body = encode({ // 2. build a CBOR Message v: 1, t: "core.fs.request", p: encode({ op: { Stat: { path: "/etc" } } }), }); const frame = await client.request(FLAG_SESSION_START, body); // 3. request / response console.log(decode(frame.body)); await client.close(); // 4. close ``` ## Constants --- #### FLAG_TERMINAL
const
```typescript const FLAG_TERMINAL = 0b0000_0001 ``` Frame flag: this is the last message for the given correlation id. When a frame on an open stream carries this bit, no further frames will arrive for that id. --- #### FLAG_SESSION_START
const
```typescript const FLAG_SESSION_START = 0b0000_0010 ``` Frame flag: this is the first message of a new session. Set it on the opening frame of a request/response RPC or a streaming session. --- #### FLAG_SHUTDOWN
const
```typescript const FLAG_SHUTDOWN = 0b0000_0100 ``` Frame flag: this message requests sandbox shutdown. ## Static methods --- #### AgentClient.connectSandbox()
staticasync
```typescript static connectSandbox(name: string, opts?: AgentConnectOptions): Promise ``` Connect to a running sandbox by name. Resolves the sandbox's relay socket path and performs the `core.ready` handshake. Sandbox names are limited to 128 UTF-8 bytes.

Parameters

namestring
Sandbox name, up to 128 UTF-8 bytes.
optsAgentConnectOptions
Optional connect settings, e.g. handshake timeout.

Returns

Promise<AgentClient>
Connected client.
```typescript const client = await AgentClient.connectSandbox("dev", { timeoutMs: 5000 }); ``` --- #### AgentClient.connect()
staticasync
```typescript static connect(path: string, opts?: AgentConnectOptions): Promise ``` Connect to an `agentd` relay socket by path. Use this when you already have the socket path, for example one returned by [`socketPath()`](#agentclient-socketpath).

Parameters

pathstring
Filesystem path of the relay socket.
optsAgentConnectOptions
Optional connect settings, e.g. handshake timeout.

Returns

Promise<AgentClient>
Connected client.
```typescript const path = AgentClient.socketPath("dev"); const client = await AgentClient.connect(path); ``` --- #### AgentClient.socketPath()
static
```typescript static socketPath(name: string): string ``` Resolve a sandbox's `agentd` relay socket path **without connecting**. Returns the same path [`connectSandbox()`](#agentclient-connectsandbox) would dial, so you can talk to `agentd` over a raw byte transport (for example a transparent relay that splices bytes to and from the socket) instead of this frame client. The sandbox need not be running. Sandbox names are limited to 128 UTF-8 bytes.

Parameters

namestring
Sandbox name, up to 128 UTF-8 bytes.

Returns

string
Relay socket path.
```typescript const path = AgentClient.socketPath("dev"); ``` ## Instance methods --- #### client.request()
instanceasync
```typescript request(flags: number, body: Buffer): Promise ``` Send one frame and await a single response frame. Use for request/response RPCs that produce exactly one terminal response (for example `FsRequest` to `FsResponse`).

Parameters

flagsnumber
Frame flag byte, e.g. FLAG_SESSION_START.
bodyBuffer
CBOR-encoded protocol message body.

Returns

The single response frame.
```typescript import { encode, decode } from "cbor-x"; import { FLAG_SESSION_START } from "microsandbox"; const body = encode({ v: 1, t: "core.fs.request", p: encode({ op: { Stat: { path: "/etc" } } }) }); const frame = await client.request(FLAG_SESSION_START, body); console.log(decode(frame.body)); ``` --- #### client.stream()
instanceasync
```typescript stream(flags: number, body: Buffer): Promise ``` Open a streaming session. The returned [`AgentStream`](#agentstream) carries the protocol correlation `id` (pass it to [`send()`](#client-send) for follow-up frames) and is also an async iterator of raw frames.

Parameters

flagsnumber
Frame flag byte for the opening frame, e.g. FLAG_SESSION_START.
bodyBuffer
CBOR-encoded protocol message body.

Returns

Open stream of raw frames.
```typescript import { FLAG_SESSION_START, FLAG_TERMINAL } from "microsandbox"; const stream = await client.stream(FLAG_SESSION_START, body); for await (const frame of stream) { if ((frame.flags & FLAG_TERMINAL) !== 0) break; } ``` --- #### client.send()
instanceasync
```typescript send(id: number, flags: number, body: Buffer): Promise ``` Send a follow-up frame on an existing correlation id (for example stdin, a signal, a resize, or data chunks on an open session). Use the `id` of the [`AgentStream`](#agentstream) returned by [`stream()`](#client-stream).

Parameters

idnumber
Correlation id of an open session.
flagsnumber
Frame flag byte.
bodyBuffer
CBOR-encoded protocol message body.
```typescript await client.send(stream.id, 0, encode({ v: 1, t: "core.pty.stdin", p: encode({ data: "ls\n" }) })); ``` --- #### client.readyBytes()
instance
```typescript readyBytes(): Buffer ``` Return the cached handshake `core.ready` frame body as CBOR bytes. Captured during connect, so this is a synchronous accessor with no protocol traffic.

Returns

Buffer
CBOR-encoded core.ready frame body.
```typescript import { decode } from "cbor-x"; const ready = decode(client.readyBytes()); ``` --- #### client.close()
instanceasync
```typescript close(): Promise ``` Close the connection. Idempotent: calling it more than once is safe. ```typescript await client.close(); ``` ## Types ### AgentClient
class
Low-level client for talking to `agentd` through the sandbox relay socket. All bodies are raw CBOR bytes: encode and decode them in your code with a library like `cbor-x`, and build typed convenience methods on top of this class. Construct it with one of the static connect methods. | Property / Method | Type | Description | |-------------------|------|-------------| | AgentClient.connectSandbox(name, opts?) | `Promise<`[`AgentClient`](#agentclient)`>` | Connect by sandbox name | | AgentClient.connect(path, opts?) | `Promise<`[`AgentClient`](#agentclient)`>` | Connect by relay socket path | | AgentClient.socketPath(name) | `string` | Resolve the relay socket path without connecting | | request(flags, body) | `Promise<`[`RawFrame`](#rawframe)`>` | Send one frame, await one response | | stream(flags, body) | `Promise<`[`AgentStream`](#agentstream)`>` | Open a streaming session | | send(id, flags, body) | `Promise` | Send a follow-up frame on a correlation id | | readyBytes() | `Buffer` | Cached `core.ready` handshake frame body | | close() | `Promise` | Close the connection (idempotent) | ### AgentStream
class

Returned by stream()

An open raw agent stream. Implements `AsyncIterableIterator`, so it can be driven with `for await`. The iterator ends after a frame carrying [`FLAG_TERMINAL`](#flag_terminal) or when the underlying stream is exhausted. | Property / Method | Type | Description | |-------------------|------|-------------| | id | `number` | Protocol correlation id; pass to [`send()`](#client-send) for follow-up frames | | next() | `Promise>` | Pull the next frame; `done` once terminal or exhausted | | close() | `Promise` | Release the stream handle early (idempotent) | | return() | `Promise>` | Async-iterator early-exit hook; closes the stream | | [Symbol.asyncIterator]() | [`AgentStream`](#agentstream) | Returns itself so the stream is iterable | ### RawFrame
interface

Returned by request() · iterated from AgentStream

A raw protocol frame. The `body` is the CBOR-encoded `Message` body (`v`, `t`, `p`) as it appeared on the wire; decode it with a CBOR library such as `cbor-x`. | Field | Type | Description | |-------|------|-------------| | id | `number` | Correlation id from the frame header | | flags | `number` | Frame flags (`FLAG_TERMINAL`, `FLAG_SESSION_START`, ...) | | body | `Buffer` | Raw CBOR-encoded body bytes | ### AgentConnectOptions
interface

Used by connectSandbox() · connect()

Options for connecting to an agent relay. | Field | Type | Description | |-------|------|-------------| | timeoutMs | `number` | Handshake timeout in milliseconds. Defaults to `10_000`. |