What APIs Are Exposed by Microsandbox to the Sandboxed Environment?

Microsandbox exposes seven core APIs to sandboxed workloads—Bootstrap, Heartbeat, Exec, Filesystem, TCP, Message/Codec, and Error—implemented through a custom CBOR-based binary protocol in the crates/protocol crate.

Microsandbox is an open-source sandboxing platform that runs untrusted code inside lightweight virtual machines. To let guest workloads interact safely with the host, microsandbox exposes a well-defined, capability-limited API surface that sandboxes can use to spawn processes, access files, and communicate over TCP—all without direct kernel access. This article examines each API, its source implementation, and how guest SDKs consume these interfaces.

The Protocol Architecture

Microsandbox communicates with the guest via a custom binary protocol defined in the crates/protocol crate. The protocol uses CBOR serialization for message encoding, providing a compact, schema-flexible format that works across Rust, Python, Node.js, and Go SDKs.

The protocol is modular: each API lives in its own submodule and builds on the shared message/codec infrastructure in crates/protocol/lib/message.rs and crates/protocol/lib/codec.rs.

API Reference

Bootstrap API

The Bootstrap API initializes the sandbox environment and delivers critical configuration to the guest. It negotiates protocol versions and transmits the sandbox specification—including declared volumes, network policies, and security profiles.

• Core file: crates/protocol/lib/bootstrap.rs
• Key purpose: Delivers launch metadata and validates compatibility between host and guest

This handshake occurs before the guest's main workload starts, ensuring the sandbox knows its constraints from the first instruction.

Heartbeat API

The Heartbeat API maintains liveness signaling between host and guest. The guest sends periodic heartbeats to prove it remains responsive, while the host can inject graceful shutdown requests through this channel.

• Core file: crates/protocol/lib/heartbeat.rs
• Key purpose: Enables health monitoring and clean termination workflows

Exec API

The Exec API is the gateway for sandboxed programs to spawn external processes. Since the guest VM cannot execute binaries directly, it requests the host to run commands on its behalf—with full stdin/stdout/stderr streaming and exit status propagation.

• Core file: crates/protocol/lib/exec.rs
• Key capabilities:
  • exec.run: Synchronous command execution with captured output
  • exec.spawn: Asynchronous process spawning with stream handles
  • Full I/O piping between guest and subprocess

This API powers common operations like curl requests, ssh connections, or any external tool invocation.

Filesystem (FS) API

The FS API provides controlled file access confined to explicitly declared volumes. The host validates every operation against the sandbox's volume mounts, preventing directory traversal or unauthorized access.

• Core file: crates/protocol/lib/fs.rs
• Supported operations:

Operation	Description
fs.open	Open files with specified modes
fs.read / fs.write	Byte-level I/O
fs.stat	File metadata retrieval
fs.readdir	Directory listing
fs.create / fs.remove	File lifecycle management

All paths are resolved relative to granted volumes, with the host enforcing strict containment.

TCP API

The TCP API exposes socket-like networking to the guest without raw network stack access. Internally, microsandbox wraps the smoltcp stack to provide this functionality.

• Core file: crates/protocol/lib/tcp.rs
• Key capabilities:
  • tcp.connect: Outbound TCP connections to external services
  • tcp.bind: Publishing ports that guests can listen on

This design lets sandboxes reach external APIs or expose services while the host maintains network policy enforcement.

Message and Codec API

The Message API and Codec API form the serialization foundation that all other APIs build upon.

• Core files: crates/protocol/lib/message.rs, crates/protocol/lib/codec.rs
• Technology: CBOR (Concise Binary Object Representation)
• Role: Defines request/response envelopes, capability tickets, and encoding/decoding logic

These modules ensure type-safe, versioned communication between heterogeneous host and guest runtimes.

Error API

The Error API standardizes failure propagation. When host-side operations fail, structured error codes and messages travel back through the protocol to provide actionable diagnostics to the guest.

• Core file: crates/protocol/lib/error.rs

Practical Usage Examples

The following Rust examples demonstrate how the SDK translates high-level calls into protocol messages. Equivalent patterns exist in sdk/python, sdk/node-ts, and sdk/go.

Running External Commands

let exec = msb::Exec::new();
let result = exec
    .run("curl", &["https://example.com"])
    .await
    .expect("exec failed");

println!("Exit: {}", result.status);
println!("Stdout: {}", String::from_utf8_lossy(&result.stdout));

Reading Sandbox Volumes

let fs = msb::Fs::new();
let data = fs.read_file("/my-volume/config.yaml")
    .await
    .expect("read failed");

println!("Config: {}", String::from_utf8_lossy(&data));

TCP Networking

let tcp = msb::Tcp::new();
let mut conn = tcp.connect("api.service.local:443")
    .await
    .expect("connect failed");

conn.write_all(b"GET / HTTP/1.1\r\n\r\n").await?;

let mut resp = vec![];
conn.read_to_end(&mut resp).await?;
println!("Response: {}", String::from_utf8_lossy(&resp));

Source File Map

Component	Implementation
Protocol entry point	crates/protocol/lib/lib.rs
Bootstrap handshake	crates/protocol/lib/bootstrap.rs
Process execution	crates/protocol/lib/exec.rs
File operations	crates/protocol/lib/fs.rs
Network sockets	crates/protocol/lib/tcp.rs
Liveness signals	crates/protocol/lib/heartbeat.rs
Message definitions	crates/protocol/lib/message.rs
CBOR encoding	crates/protocol/lib/codec.rs
Error handling	crates/protocol/lib/error.rs

Summary

• Microsandbox exposes seven modular APIs through a CBOR-based binary protocol in crates/protocol
• Exec, FS, and TCP provide the core capabilities for subprocesses, file access, and networking
• All operations are host-mediated and capability-checked, with no direct kernel or hardware access
• Guest SDKs in multiple languages wrap protocol messages into idiomatic interfaces
• The modular design allows safe, performant, language-agnostic sandboxed execution

Frequently Asked Questions

How does microsandbox prevent sandboxed code from accessing unauthorized resources?

Every API request is validated by the host against the sandbox's declared capabilities. Filesystem calls are restricted to explicitly mounted volumes, TCP connections respect network policies, and exec requests run under the sandbox's security profile. The host acts as a capability broker, rejecting any operation outside the granted scope.

Can I use these APIs from languages other than Rust?

Yes. Microsandbox provides official SDKs for Python, TypeScript/Node.js, and Go in the sdk/ directory. These SDKs implement the same protocol messages and expose equivalent high-level interfaces, ensuring consistent behavior across languages.

What happens if the guest misses heartbeat deadlines?

The host treats missed heartbeats as a potential hang or failure condition. Depending on configuration, the host may flag the sandbox for inspection, trigger automated recovery, or initiate a forced shutdown. This mechanism prevents zombie processes and enables reliable orchestration at scale.

Why CBOR instead of JSON or Protocol Buffers?

CBOR provides compact binary encoding without requiring external schema definitions or code generation tools. This keeps the protocol implementation lightweight and self-contained in Rust while remaining easy to parse in other languages. The format also handles binary data efficiently, which is critical for exec I/O and file transfers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}