Skip to main content
AgentClient is the low-level transport for talking to agentd through a running sandbox’s relay socket. Most applications should use Sandbox, exec, and fs instead. Use AgentClient when you are building a protocol-level integration or an SDK layer. The Rust client has two tiers:
  • 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. It is not just the inner payload. 
use microsandbox::{
    agent,
    protocol::{
        fs::{FsOp, FsRequest, FsResponse},
        message::MessageType,
    },
};

let client = agent::connect_sandbox("dev").await?;
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()?;

​
connect()

async fn connect(sock_path: impl AsRef<Path>) -> AgentClientResult<AgentClient>
Connect to an agent relay socket by path. The connection performs the relay handshake, validates the cached core.ready frame, and starts one background reader task.

​
agent::connect_sandbox()

async fn agent::connect_sandbox(name: &str) -> AgentClientResult<AgentClient>
Resolve a sandbox name to its relay socket path and connect to it. Sandbox names are limited to 128 UTF-8 bytes.

​
request()

async fn request<T: Serialize>(&self, t: MessageType, payload: &T) -> AgentClientResult<Message>
Send one typed protocol message and wait for one response frame with the same correlation id. Use this for one-shot RPCs such as filesystem stat/list requests.

​
stream()

async fn stream<T: Serialize>(&self, t: MessageType, payload: &T) -> AgentClientResult<(u32, Receiver<Message>)>
Open a typed streaming session. The returned id is the protocol correlation id. Use it with 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.

​
send()

async fn send<T: Serialize>(&self, id: u32, t: MessageType, payload: &T) -> AgentClientResult<()>
Send a typed follow-up message on an existing correlation id.

​
request_raw()

async fn request_raw(&self, flags: u8, body: Vec<u8>) -> AgentClientResult<RawFrame>
Allocate a correlation id, send one raw frame, and wait for one raw response frame.

​
stream_raw()

async fn stream_raw(&self, flags: u8, body: Vec<u8>) -> AgentClientResult<(u32, Receiver<RawFrame>)>
Open a raw streaming session. The receiver yields raw frames for the returned correlation id until a terminal frame is delivered or the receiver is dropped.

​
send_raw()

async fn send_raw(&self, id: u32, flags: u8, body: &[u8]) -> AgentClientResult<()>
Send a raw follow-up frame on an existing correlation id.

​
ready()

fn ready(&self) -> AgentClientResult<Ready>
Return the decoded core.ready payload from the handshake.

​
ready_bytes()

fn ready_bytes(&self) -> &[u8]
Return the cached handshake core.ready frame body as CBOR bytes.

​
close()

async fn close(self)
Close the client by consuming it. Dropping the client has the same effect.

​
RawFrame

pub struct RawFrame {
    pub id: u32,
    pub flags: u8,
    pub body: Vec<u8>,
}
id is the protocol correlation id, flags is the frame flag byte, and body is the CBOR-encoded protocol message body.