# What APIs Are Exposed by Microsandbox to the Sandboxed Environment?

> Explore the seven core APIs exposed by Microsandbox to sandboxed workloads. Learn about Bootstrap, Heartbeat, Exec, Filesystem, TCP, Message/Codec, and Error APIs.

- Repository: [Super Rad Company/microsandbox](https://github.com/superradcompany/microsandbox)
- Tags: api-reference
- Published: 2026-08-20

---

**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`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/message.rs) and [`crates/protocol/lib/codec.rs`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/message.rs), [`crates/protocol/lib/codec.rs`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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

```rust
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

```rust
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

```rust
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`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/lib.rs) |
| Bootstrap handshake | [`crates/protocol/lib/bootstrap.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/bootstrap.rs) |
| Process execution | [`crates/protocol/lib/exec.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/exec.rs) |
| File operations | [`crates/protocol/lib/fs.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/fs.rs) |
| Network sockets | [`crates/protocol/lib/tcp.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/tcp.rs) |
| Liveness signals | [`crates/protocol/lib/heartbeat.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/heartbeat.rs) |
| Message definitions | [`crates/protocol/lib/message.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/message.rs) |
| CBOR encoding | [`crates/protocol/lib/codec.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/codec.rs) |
| Error handling | [`crates/protocol/lib/error.rs`](https://github.com/superradcompany/microsandbox/blob/main/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.