--- title: Agent client description: Rust SDK - Low-level agentd client reference --- `AgentClient` is the low-level transport for talking to `agentd` through a running sandbox's relay socket. Most applications should use [`Sandbox`](/sdk/rust/sandbox), [`exec`](/sdk/rust/execution), and [`fs`](/sdk/rust/filesystem) instead. Reach for `AgentClient` when you are building a protocol-level integration or an SDK layer. [`AgentBridge`](#agentbridge) wraps the same connection in concrete, FFI-shaped types for the Node, Python, and Go bindings. The client has two tiers that share one socket and one background reader task: - **Typed** methods encode and decode microsandbox protocol messages for you. - **Raw** methods move framed CBOR bytes without decoding the message body. The raw body is the full CBOR-encoded protocol `Message` body (`v`, `t`, and `p`), not just the inner payload. The typed and raw methods reach the connection through `Deref` to the underlying client; everything below is callable directly on the value `connect_sandbox` returns.

Module functions2

agent::connect_sandbox()resolve a name and connect agent::connect_sandbox_with_timeout()connect with a handshake timeout

Static · AgentClient7

AgentClient::connect()dial a socket path AgentClient::connect_with_timeout()dial with a timeout AgentClient::connect_with_deadline()dial with a deadline AgentClient::connect_sandbox()resolve a name and connect AgentClient::connect_sandbox_with_timeout()resolve a name, with timeout AgentClient::socket_path()resolve a path without connecting AgentClient::ensure_version_compat_for()gate a type at a generation

Instance · AgentClient15

client.request()one-shot typed RPC client.stream()open a typed stream client.send()typed follow-up message client.request_raw()one-shot raw RPC client.stream_raw()open a raw stream client.send_raw()raw follow-up frame client.ready()decoded handshake payload client.ready_bytes()raw handshake CBOR client.protocol()codec generation client.is_legacy_protocol()pre-0.5 relay? client.negotiated_version()negotiated capability generation client.agent_version()runtime package version client.supports()message type available? client.ensure_version_compat()gate a type, error if too old client.close()close the connection

Static · AgentBridge4

AgentBridge::connect_sandbox()connect by sandbox name AgentBridge::connect_sandbox_with_timeout()connect by name, with timeout AgentBridge::connect_path()connect to a socket path AgentBridge::connect_path_with_timeout()connect to a path, with timeout

Instance · AgentBridge7

bridge.request()one-shot raw request bridge.send()follow-up frame bridge.stream_open()open a stream bridge.stream_next()pull the next frame bridge.stream_close()close a stream bridge.ready_bytes()raw handshake CBOR bridge.close()close the connection

Types

AgentClient AgentBridge BridgeFrame StreamHandle AgentProtocol RawFrame AgentClientError AgentClientResult

Typical flow

```rust use microsandbox::{ agent, protocol::{ fs::{FsOp, FsRequest, FsResponse}, message::MessageType, }, }; let client = agent::connect_sandbox("dev").await?; // 1. resolve name + connect let response = client // 2. one-shot typed RPC .request( MessageType::FsRequest, &FsRequest { op: FsOp::Stat { path: "/etc/os-release".to_string(), follow_symlink: true, }, }, ) .await?; let fs_response: FsResponse = response.payload()?; // 3. decode the payload client.close().await; // 4. close ``` ## Module functions --- #### agent::connect_sandbox()
staticasync
```rust async fn connect_sandbox(name: &str) -> AgentClientResult ``` Resolve a sandbox name to its agent relay socket path and connect, using the default ten-second handshake timeout. The socket lives under the SDK's configured runtime directory at a short, name-derived path. Sandbox names are limited to 128 UTF-8 bytes.

Parameters

name&str
Sandbox name, up to 128 UTF-8 bytes.

Returns

AgentClient
Connected client.
```rust use microsandbox::agent; let client = agent::connect_sandbox("dev").await?; ``` --- #### agent::connect_sandbox_with_timeout()
staticasync
```rust async fn connect_sandbox_with_timeout(name: &str, timeout: Duration) -> AgentClientResult ``` Like [`connect_sandbox`](#agentconnect_sandbox), but with an explicit handshake timeout instead of the ten-second default.

Parameters

name&str
Sandbox name, up to 128 UTF-8 bytes.
timeoutDuration
Maximum time to wait for the relay handshake.

Returns

AgentClient
Connected client.
```rust use std::time::Duration; use microsandbox::agent; let client = agent::connect_sandbox_with_timeout("dev", Duration::from_secs(2)).await?; ``` ## AgentClient: static methods --- #### AgentClient::connect()
staticasync
```rust async fn connect(sock_path: impl AsRef) -> AgentClientResult ``` Connect to an arbitrary agent relay socket by path, using the default ten-second handshake timeout. The connection performs the relay handshake, validates the cached `core.ready` frame, and starts one background reader task.

Parameters

sock_pathimpl AsRef<Path>
Path to the agent relay socket.

Returns

Connected client.
```rust use microsandbox::agent::AgentClient; let path = AgentClient::socket_path("dev")?; let client = AgentClient::connect(&path).await?; ``` --- #### AgentClient::connect_with_timeout()
staticasync
```rust async fn connect_with_timeout(sock_path: impl AsRef, timeout: Duration) -> AgentClientResult ``` Connect to an arbitrary agent relay socket by path with an explicit handshake timeout.

Parameters

sock_pathimpl AsRef<Path>
Path to the agent relay socket.
timeoutDuration
Maximum time to wait for the relay handshake.

Returns

Connected client.
--- #### AgentClient::connect_with_deadline()
staticasync
```rust async fn connect_with_deadline(sock_path: impl AsRef, deadline: Instant) -> AgentClientResult ``` Connect to an arbitrary agent relay socket by path with an explicit handshake deadline. The deadline bounds both handshake reads, so an accepted connection that stalls before writing the handshake bytes cannot block this call indefinitely.

Parameters

sock_pathimpl AsRef<Path>
Path to the agent relay socket.
deadlineInstant
Tokio instant by which the handshake must complete.

Returns

Connected client.
--- #### AgentClient::connect_sandbox()
staticasync
```rust async fn connect_sandbox(name: &str) -> AgentClientResult ``` Resolve a sandbox name to its agent socket path and connect. Equivalent to the module-level [`agent::connect_sandbox`](#agentconnect_sandbox).

Parameters

name&str
Sandbox name, up to 128 UTF-8 bytes.

Returns

Connected client.
--- #### AgentClient::connect_sandbox_with_timeout()
staticasync
```rust async fn connect_sandbox_with_timeout(name: &str, timeout: Duration) -> AgentClientResult ``` Resolve a sandbox name to its agent socket path and connect with an explicit handshake timeout. Equivalent to the module-level [`agent::connect_sandbox_with_timeout`](#agentconnect_sandbox_with_timeout).

Parameters

name&str
Sandbox name, up to 128 UTF-8 bytes.
timeoutDuration
Maximum time to wait for the relay handshake.

Returns

Connected client.
--- #### AgentClient::socket_path()
static
```rust fn socket_path(name: &str) -> MicrosandboxResult ``` Resolve a sandbox's relay socket path **without connecting**. Returns the same path [`connect_sandbox`](#agentconnect_sandbox) would dial: the hashed path under the runtime directory when it fits the platform's Unix-socket length limit, and the legacy name-derived path otherwise. Useful for talking 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.

Parameters

name&str
Sandbox name, up to 128 UTF-8 bytes.

Returns

PathBuf
Relay socket path.
```rust use microsandbox::agent::AgentClient; let path = AgentClient::socket_path("dev")?; println!("{}", path.display()); ``` --- #### AgentClient::ensure_version_compat_for()
static
```rust fn ensure_version_compat_for(t: MessageType, negotiated: u8) -> AgentClientResult<()> ``` Check a message type against an explicit negotiated generation. The single place the rule lives, exposed for callers that hold the negotiated generation but not a live client. Returns [`AgentClientError::UnsupportedOperation`](#agentclienterror) if the type was introduced after the given generation.

Parameters

tMessageType
Protocol message type to gate.
negotiatedu8
Protocol generation to check against.
```rust use microsandbox::{agent::AgentClient, protocol::message::MessageType}; AgentClient::ensure_version_compat_for(MessageType::FsRequest, 2)?; ``` ## AgentClient: instance methods --- #### client.request()
instanceasync
```rust async fn request(&self, t: MessageType, payload: &T) -> AgentClientResult ``` Send one typed protocol message and wait for one response frame with the same correlation id. Flags are derived from the message type. Use this for one-shot RPCs such as filesystem stat or list requests. Fails fast with [`AgentClientError::UnsupportedOperation`](#agentclienterror) if the connected sandbox is too old for the message type.

Parameters

tMessageType
Protocol message type.
payload&T: Serialize
Message payload, serialized with CBOR.

Returns

Message
Decoded response message.
```rust use microsandbox::protocol::{ fs::{FsOp, FsRequest, FsResponse}, message::MessageType, }; let response = client .request( MessageType::FsRequest, &FsRequest { op: FsOp::Stat { path: "/etc/os-release".to_string(), follow_symlink: true, }, }, ) .await?; let fs_response: FsResponse = response.payload()?; ``` --- #### client.stream()
instanceasync
```rust async fn stream(&self, t: MessageType, payload: &T) -> AgentClientResult<(u32, Receiver)> ``` Open a typed streaming session. The returned id is the protocol correlation id. Use it with [`send()`](#client-send) for follow-up messages such as stdin, resize, signal, or file data chunks. The receiver yields messages until a terminal frame is delivered or the connection closes.

Parameters

tMessageType
Protocol message type for the opening frame.
payload&T: Serialize
Opening message payload, serialized with CBOR.

Returns

(u32, Receiver<Message>)
Correlation id and a typed message receiver.
```rust use microsandbox::protocol::{exec::ExecRequest, message::MessageType}; let (id, mut rx) = client .stream(MessageType::ExecRequest, &ExecRequest { cmd: "echo".into(), args: vec!["hi".into()], env: Vec::new(), cwd: None, user: None, tty: false, rows: 24, cols: 80, rlimits: Vec::new(), }) .await?; while let Some(msg) = rx.recv().await { println!("{:?}", msg.t); } ``` --- #### client.send()
instanceasync
```rust async fn send(&self, id: u32, t: MessageType, payload: &T) -> AgentClientResult<()> ``` Send a typed follow-up message on an existing correlation id (the id returned by [`stream()`](#client-stream)).

Parameters

idu32
Correlation id from the open stream.
tMessageType
Protocol message type.
payload&T: Serialize
Message payload, serialized with CBOR.
```rust use microsandbox::protocol::{exec::ExecStdin, message::MessageType}; client.send(id, MessageType::ExecStdin, &ExecStdin { data: b"input\n".to_vec() }).await?; ``` --- #### client.request_raw()
instanceasync
```rust async fn request_raw(&self, flags: u8, body: Vec) -> AgentClientResult ``` Allocate a correlation id, send one raw frame with `(flags, body)`, and wait for one raw response frame with the matching id. CBOR encoding and decoding are left to the caller.

Parameters

flagsu8
Frame flag byte.
bodyVec<u8>
CBOR-encoded protocol message body.

Returns

Raw response frame.
```rust let frame = client.request_raw(flags, body).await?; println!("id={} flags={}", frame.id, frame.flags); ``` --- #### client.stream_raw()
instanceasync
```rust async fn stream_raw(&self, flags: u8, body: Vec) -> AgentClientResult<(u32, Receiver)> ``` Open a raw streaming session. The receiver yields raw frames for the returned correlation id until a frame with the terminal flag arrives or the receiver is dropped. Use [`send_raw()`](#client-send_raw) with the returned id to send follow-up frames.

Parameters

flagsu8
Frame flag byte for the opening frame.
bodyVec<u8>
CBOR-encoded protocol message body.

Returns

(u32, Receiver<RawFrame>)
Correlation id and a raw frame receiver.
--- #### client.send_raw()
instanceasync
```rust async fn send_raw(&self, id: u32, flags: u8, body: &[u8]) -> AgentClientResult<()> ``` Send a raw follow-up frame on an existing correlation id (the id returned by [`stream_raw()`](#client-stream_raw)).

Parameters

idu32
Correlation id from the open raw stream.
flagsu8
Frame flag byte.
body&[u8]
CBOR-encoded protocol message body.
--- #### client.ready()
instance
```rust fn ready(&self) -> AgentClientResult ``` Return the decoded `core.ready` payload captured during the handshake (boot timings and the runtime's self-reported version).

Returns

Ready
Decoded handshake payload.
```rust let ready = client.ready()?; println!("boot {} ns", ready.boot_time_ns); ``` --- #### client.ready_bytes()
instance
```rust fn ready_bytes(&self) -> &[u8] ``` Return the cached handshake `core.ready` frame body as CBOR bytes. Useful for bindings that want to deserialize the ready payload with their own CBOR tooling. For typed access, use [`ready()`](#client-ready).

Returns

&[u8]
CBOR-encoded ready frame body.
--- #### client.protocol()
instance
```rust fn protocol(&self) -> AgentProtocol ``` The agent protocol generation (wire codec) negotiated for this connection.

Returns

Codec generation: Current or LegacyV1.
--- #### client.is_legacy_protocol()
instance
```rust fn is_legacy_protocol(&self) -> bool ``` Whether this connection is using the legacy pre-0.5 protocol.

Returns

bool
true if the relay speaks the pre-0.5 protocol.
--- #### client.negotiated_version()
instance
```rust fn negotiated_version(&self) -> u8 ``` The negotiated protocol generation for this connection: the lower of what this client speaks and what the sandbox advertised at handshake. This is the capability gate that drives [`supports()`](#client-supports) and the typed send path, and it is distinct from [`protocol()`](#client-protocol), which selects the wire codec.

Returns

u8
Negotiated capability generation.
--- #### client.agent_version()
instance
```rust fn agent_version(&self) -> &str ``` The runtime's self-reported package version, taken from its `core.ready` frame. Empty when the runtime predates this field (an older agent), in which case fall back to the generation for diagnostics.

Returns

&str
Runtime package version, or empty if unknown.
--- #### client.supports()
instance
```rust fn supports(&self, t: MessageType) -> bool ``` Whether the connected sandbox is new enough to handle the given message type. The single source of truth for feature gating: callers that cannot gate by sending (for example the SSH/SFTP layer) consult this instead of inspecting the protocol generation directly.

Parameters

tMessageType
Protocol message type to check.

Returns

bool
true if the runtime can handle the type.
```rust use microsandbox::protocol::message::MessageType; if client.supports(MessageType::FsRequest) { // safe to issue filesystem RPCs } ``` --- #### client.ensure_version_compat()
instance
```rust fn ensure_version_compat(&self, t: MessageType) -> AgentClientResult<()> ``` Reject a message type the connected sandbox is too old to handle, against this connection's negotiated generation. Fails before any bytes are sent, so only that one operation fails and the session continues. The typed [`request()`](#client-request), [`stream()`](#client-stream), and [`send()`](#client-send) methods call this internally.

Parameters

tMessageType
Protocol message type to gate.
```rust use microsandbox::protocol::message::MessageType; client.ensure_version_compat(MessageType::TcpConnect)?; ``` --- #### client.close()
instanceasync
```rust async fn close(self) ``` Close the client by consuming it. Drops the writer and aborts the reader task; any in-flight requests resolve with [`AgentClientError::Closed`](#agentclienterror). Dropping the client has the same effect. ```rust client.close().await; ``` ## AgentBridge Bytes-in/bytes-out wrapper around [`AgentClient`](#agentclient), with concrete, monomorphic types suitable for crossing FFI boundaries. The Node, Python, and Go bindings build on it. No generics, no consuming-`self` methods, no callbacks across FFI: each method takes `&self` and is idempotent where the underlying operation allows. CBOR (de)serialization happens entirely in the caller's language; the bridge only moves bytes. One instance owns one Unix-socket connection; multiple concurrent streams are supported, each identified by an opaque [`StreamHandle`](#streamhandle). --- #### AgentBridge::connect_sandbox()
staticasync
```rust async fn connect_sandbox(name: &str) -> AgentClientResult ``` Connect to a sandbox by name, resolving the socket path from SDK config. Sandbox names are limited to 128 UTF-8 bytes.

Parameters

name&str
Sandbox name, up to 128 UTF-8 bytes.

Returns

Connected bridge.
--- #### AgentBridge::connect_sandbox_with_timeout()
staticasync
```rust async fn connect_sandbox_with_timeout(name: &str, timeout: Duration) -> AgentClientResult ``` Connect to a sandbox by name with an explicit handshake timeout.

Parameters

name&str
Sandbox name, up to 128 UTF-8 bytes.
timeoutDuration
Maximum time to wait for the relay handshake.

Returns

Connected bridge.
--- #### AgentBridge::connect_path()
staticasync
```rust async fn connect_path(path: &str) -> AgentClientResult ``` Connect to an arbitrary agentd relay socket by path.

Parameters

path&str
Path to the agent relay socket.

Returns

Connected bridge.
--- #### AgentBridge::connect_path_with_timeout()
staticasync
```rust async fn connect_path_with_timeout(path: &str, timeout: Duration) -> AgentClientResult ``` Connect to an arbitrary agentd relay socket by path with an explicit handshake timeout.

Parameters

path&str
Path to the agent relay socket.
timeoutDuration
Maximum time to wait for the relay handshake.

Returns

Connected bridge.
--- #### bridge.request()
instanceasync
```rust async fn request(&self, flags: u8, body: Vec) -> AgentClientResult ``` One-shot request: send `(flags, body)` and wait for one response frame.

Parameters

flagsu8
Frame flag byte.
bodyVec<u8>
CBOR-encoded protocol message body.

Returns

Response frame.
--- #### bridge.send()
instanceasync
```rust async fn send(&self, id: u32, flags: u8, body: Vec) -> AgentClientResult<()> ``` Send a follow-up frame on an existing correlation id.

Parameters

idu32
Correlation id from an open stream.
flagsu8
Frame flag byte.
bodyVec<u8>
CBOR-encoded protocol message body.
--- #### bridge.stream_open()
instanceasync
```rust async fn stream_open(&self, flags: u8, body: Vec) -> AgentClientResult<(u32, StreamHandle)> ``` Open a streaming session. Returns the protocol correlation id (for follow-up sends via [`send()`](#bridge-send)) and an opaque stream handle (for [`stream_next()`](#bridge-stream_next) and [`stream_close()`](#bridge-stream_close)).

Parameters

flagsu8
Frame flag byte for the opening frame.
bodyVec<u8>
CBOR-encoded protocol message body.

Returns

Correlation id and an opaque stream handle.
--- #### bridge.stream_next()
instanceasync
```rust async fn stream_next(&self, handle: StreamHandle) -> AgentClientResult> ``` Pull the next frame from a stream. Returns `None` when the stream has ended (the terminal frame was already delivered, or the stream was closed or dropped).

Parameters

Handle returned by stream_open().

Returns

Option<BridgeFrame>
Next frame, or None at end of stream.
```rust let (id, handle) = bridge.stream_open(flags, body).await?; while let Some(frame) = bridge.stream_next(handle).await? { // decode frame.body with your own CBOR tooling } ``` --- #### bridge.stream_close()
instanceasync
```rust async fn stream_close(&self, handle: StreamHandle) ``` Close a stream and drop its handle. Idempotent.

Parameters

Handle returned by stream_open().
--- #### bridge.ready_bytes()
instance
```rust fn ready_bytes(&self) -> AgentClientResult> ``` The cached handshake `core.ready` frame body bytes (CBOR). Errors with [`AgentClientError::Closed`](#agentclienterror) if the bridge has been closed.

Returns

Vec<u8>
CBOR-encoded ready frame body.
--- #### bridge.close()
instanceasync
```rust async fn close(&self) ``` Close the connection. Idempotent. After close, every operation except another close returns [`AgentClientError::Closed`](#agentclienterror). ```rust bridge.close().await; ``` ## Types --- ### AgentClient
struct

Returned by agent::connect_sandbox(), AgentClient::connect() · wrapped by AgentBridge

Client for communicating with `agentd` through a running sandbox's relay. A newtype over the underlying `microsandbox_agent_client::AgentClient`; the typed and raw transport methods reach the inner client through `Deref`. See the [static](#agentclient-static-methods) and [instance](#agentclient-instance-methods) method sections above. --- ### BridgeFrame
struct

Returned by bridge.request(), bridge.stream_next()

FFI-friendly view of a [`RawFrame`](#rawframe): id, flags, body bytes. | Field | Type | Description | | --- | --- | --- | | `id` | `u32` | Correlation ID from the frame header. | | `flags` | `u8` | Frame flags from the frame header. | | `body` | `Vec` | Raw CBOR-encoded body bytes. | --- ### StreamHandle
type alias

Returned by bridge.stream_open() · used by bridge.stream_next(), bridge.stream_close()

```rust pub type StreamHandle = u64; ``` Opaque handle identifying an open stream on an [`AgentBridge`](#agentbridge). Foreign-language wrappers reference streams by this `u64` instead of owning a tokio receiver. --- ### AgentProtocol
enum

Returned by client.protocol()

Agent protocol generation (wire codec) spoken by a connected sandbox relay. | Variant | Description | | --- | --- | | `Current` | Current protocol generation. | | `LegacyV1` | Pre-0.5 microsandbox relay handshake and agent protocol. | --- ### RawFrame
struct

Returned by client.request_raw(), client.stream_raw()

A framed protocol message at the byte level. `id` is the protocol correlation id, `flags` is the frame flag byte, and `body` is the CBOR-encoded protocol message body. Re-exported from `microsandbox::protocol::codec`. | Field | Type | Description | | --- | --- | --- | | `id` | `u32` | Protocol correlation id. | | `flags` | `u8` | Frame flag byte. | | `body` | `Vec` | CBOR-encoded protocol message body. | --- ### AgentClientError
enum

Error variant of AgentClientResult

Errors raised by [`AgentClient`](#agentclient) and [`AgentBridge`](#agentbridge). | Variant | Description | | --- | --- | | `Connect { path, source }` | Failed to open the Unix socket connection to the relay. | | `Handshake(String)` | Handshake with the relay failed (timeout, EOF, or malformed frame). | | `SandboxNotFound(String)` | Sandbox name could not be resolved to an agent socket path. | | `InvalidSandboxName(String)` | Sandbox name failed SDK validation before socket resolution. | | `Io(std::io::Error)` | An I/O error occurred on the socket after connect. | | `Protocol(ProtocolError)` | A wire-protocol error (framing, CBOR, oversize frame). | | `Cbor(String)` | CBOR encoding or decoding failed. | | `InvalidPacket(String)` | The supplied packet did not contain exactly one complete transport frame. | | `UnsupportedOperation { msg_type, needs, peer }` | The connected sandbox's runtime is older than the requested feature needs; restart the sandbox to update its runtime. | | `ReaderClosed(u32)` | The reader task closed before the in-flight request received its response. | | `Closed` | The client has been closed. | | `IdRangeExhausted` | The relay-assigned correlation ID range has no available IDs. | | `NotImplemented(&'static str)` | The operation is not implemented yet. | --- ### AgentClientResult
type alias

Returned by most AgentClient and AgentBridge methods

```rust pub type AgentClientResult = Result; ``` Result alias for agent client operations. The error is [`AgentClientError`](#agentclienterror).