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

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, 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 – Entry point and supervisor loop.
• session.rs – Per‑sandbox session state and lifecycle.
• 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 – Command parsing with clap.
• src/commands/run.rs – End‑to‑end sandbox launch: validate image, configure runtime, spawn VM, connect to agent.

Quick example:

# 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 and sdk/rust/lib/sandbox.rs:

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:

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 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.

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.

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