# Microsandbox Architecture Explained: A Deep Dive Into Its Rust‑Centric, Modular Design

> Explore microsandbox architecture, a modular Rust-centric platform for multi-language sandboxing. Discover its crate design, SDKs, and CLI orchestration for VM isolation.

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

---

**Microsandbox is a modular, multi‑language sandbox platform built around a Rust‑centric core with loosely coupled crates, language SDKs, and a CLI that orchestrates VM‑based isolation through an in‑guest agent protocol.**

This article breaks down how the `superradcompany/microsandbox` repository is structured, tracing the flow from user command to sandbox execution. Understanding this architecture helps developers extend the platform, debug issues, or integrate sandboxes into their own applications.

## Core Runtime Layer

The **Core Runtime** provides VM integration, filesystem handling, networking, metrics, and database persistence. It lives in the `crates/` directory as a collection of specialized internal crates.

- **`crates/runtime`** – Orchestrates the VM lifecycle, managing KVM on Linux and Apple Silicon virtualization on macOS.
- **`crates/filesystem`** – Handles sandbox rootfs setup, overlay mounts, and volume management.
- **`crates/network`** – Configures host‑side networking, including vsock endpoints and port forwarding.
- **`crates/db`** – Persists sandbox state, configuration, and metadata.

In [`crates/runtime/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/lib.rs), the runtime initializes the hypervisor backend, loads the guest kernel, and establishes the vsock connection that the agent will use.

## The Agent (Guest Side)

Inside every sandbox VM runs **`agentd`**, a lightweight daemon written in Rust. This **in‑guest agent** handles I/O forwarding, process management, and telemetry collection.

Key source files in `crates/agentd/lib/`:

- [`lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/lib.rs) – Entry point and supervisor loop.
- [`session.rs`](https://github.com/superradcompany/microsandbox/blob/main/session.rs) – Per‑sandbox session state and lifecycle.
- [`network.rs`](https://github.com/superradcompany/microsandbox/blob/main/network.rs) – vsock server implementation for host communication.

The agent exposes a **bi‑directional protocol** over vsock. When the host runtime connects, `agentd` spawns the requested process and streams stdout, stderr, and exit status back to the caller.

## CLI (`msb`): The User Interface

The **`msb` command‑line interface** lets users create, start, stop, and inspect sandboxes without writing code. It orchestrates the host side of the runtime and speaks to `agentd` via the custom protocol.

Implementation lives in `crates/cli/`:

- [`src/main.rs`](https://github.com/superradcompany/microsandbox/blob/main/src/main.rs) – Command parsing with `clap`.
- [`src/commands/run.rs`](https://github.com/superradcompany/microsandbox/blob/main/src/commands/run.rs) – End‑to‑end sandbox launch: validate image, configure runtime, spawn VM, connect to agent.

Quick example:

```bash

# Create a sandbox from a Docker image and run `uname -a`

msb run --image docker.io/library/alpine:latest -- /bin/uname -a

```

## Language SDKs

Microsandbox exposes its functionality through **public SDKs** in multiple languages. Each SDK either wraps the CLI or communicates directly with the agent protocol for lower latency.

| SDK | Location | Integration Pattern |
|-----|----------|-------------------|
| Rust | `sdk/rust/` | Native crate using `packages/agent-client` |
| Go | `sdk/go/` | CGO + protocol bindings |
| Python | `sdk/python/` | CLI wrapper with optional native extension |
| Node‑TypeScript | `sdk/node-ts/` | N‑API or subprocess fallback |

### Rust SDK Example

From [`sdk/rust/lib/client.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/client.rs) and [`sdk/rust/lib/sandbox.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox.rs):

```rust
use microsandbox::client::Client;
use microsandbox::sandbox::SandboxSpec;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Connect to the local agent daemon
    let client = Client::new().await?;

    // Define a minimal sandbox
    let spec = SandboxSpec::builder()
        .image("docker.io/library/alpine:latest")
        .cmd(vec!["/bin/sh".into(), "-c".into(), "echo hello"])
        .build();

    // Create and start the sandbox
    let sandbox = client.create_sandbox(spec).await?;
    let output = sandbox.wait_and_collect_stdout().await?;
    println!("Sandbox output: {}", output);
    Ok(())
}

```

### Python SDK Example

From [`sdk/python/microsandbox/__init__.py`](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/microsandbox/__init__.py):

```python
from microsandbox import MicrosandboxClient

client = MicrosandboxClient()
sandbox = client.create_sandbox(
    image="docker.io/library/alpine:latest",
    command=["/bin/sh", "-c", "date"]
)
print("Sandbox output:", sandbox.wait_output())

```

## Protocol and Shared Types

The **`packages/`** directory houses **shared type definitions and the wire protocol**, ensuring consistency across Rust and TypeScript implementations.

- `packages/microsandbox-types/` – Core structs (sandbox spec, process state, metrics) in both Rust and TypeScript.
- `packages/agent-client/` – Reusable client library for the agent protocol.

This dual‑language packaging prevents drift between the runtime and SDK consumers.

## Metrics and Observability

The **`metrics-collector`** crate aggregates telemetry from both the runtime and `agentd`. It supports multiple export targets:

- stdout (for local debugging)
- OpenTelemetry (for production observability)

Key file: [`crates/metrics-collector/lib/exporters/otel.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/metrics-collector/lib/exporters/otel.rs) implements the OpenTelemetry exporter, batching metrics before flush.

## Utilities and Supporting Crates

Common functionality lives in `crates/utils/`:

- Secret sealing and key derivation
- Cross‑platform process locking
- TTL‑aware indexing for cached artifacts

These utilities are shared across the runtime, CLI, and agent to avoid code duplication.

## End‑to‑End Execution Flow

Understanding the **Microsandbox architecture** is easier by tracing a single request:

1. **User** invokes `msb` or an SDK method.
2. **CLI/SDK** creates a `SandboxSpec` and calls into the **runtime**.
3. **Runtime** boots a VM (KVM or Apple Silicon), injecting the `agentd` initramfs.
4. Inside the VM, **agentd** starts and listens on a vsock address.
5. **Host runtime** connects to agentd, forwarding the command to execute.
6. **Agentd** spawns the process, streams I/O back, and reports exit status.
7. **Metrics‑collector** gathers telemetry throughout, exporting if configured.

This separation allows each component—runtime, agent, CLI, SDK—to evolve independently while presenting a unified interface.

## Summary

- **Microsandbox** is organized as a Rust workspace with internal crates (`crates/`), public SDKs (`sdk/`), and shared packages (`packages/`).
- The **Core Runtime** manages VM lifecycle, filesystem, and networking through modular crates.
- **Agentd** runs inside each sandbox, bridging guest processes to the host via a custom vsock protocol.
- The **`msb` CLI** and **language SDKs** provide ergonomic entry points, with SDKs available for Rust, Go, Python, and Node‑TypeScript.
- **Protocol types** are co‑located in `packages/` to maintain cross‑language consistency.
- **Metrics and observability** are first‑class, with OpenTelemetry support built into the collector.

## Frequently Asked Questions

### What virtualization backends does Microsandbox support?

Microsandbox uses KVM on Linux and Apple Silicon virtualization (`Virtualization.framework`) on macOS. The runtime abstracts these in `crates/runtime`, selecting the appropriate backend at compile time or runtime based on host capabilities.

### Can I run Microsandbox without the CLI?

Yes. The language SDKs—particularly the Rust SDK with its native `agent-client` integration—allow programmatic sandbox management without shelling out to `msb`. The Python and Node SDKs currently wrap the CLI for simplicity but can be extended to use direct protocol communication.

### How does the host communicate with the sandbox guest?

Communication flows over **vsock**, a socket family designed for host‑guest VM communication. The runtime opens a vsock listener port, passes the address to the guest at boot, and `agentd` connects back to establish a persistent bi‑directional channel defined in [`crates/agentd/lib/network.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/lib/network.rs).

### Where is sandbox state persisted?

State lives in the **database layer** (`crates/db`) on the host, tracking sandbox configurations, running instances, and historical execution records. The guest filesystem uses an ephemeral overlay by default, with optional persistent volume mounts specified in `SandboxSpec`.