What Are the Core Components of MicroSandbox? A Deep Dive into the Rust-Based MicroVM System

MicroSandbox is built as a modular Rust workspace with four architectural layers: a host runtime, an in-guest agent, transport protocols, and multilingual SDKs that together provide fast, isolated sandbox execution.

This guide explores the core components of MicroSandbox, an open-source microVM-based sandboxing system developed by SuperRad Company. Each component lives in its own crate within the workspace, enabling clean separation of concerns and selective dependency management.

The Host Layer: Runtime and Infrastructure

The host layer manages microVM lifecycle, networking, storage, and resource monitoring from the host operating system.

Runtime (crates/runtime)

The runtime is the central host-side VM manager. It boots microVMs, handles I/O forwarding, configures networking, manages volumes, and orchestrates lifecycle events.

Key source files:

• crates/runtime/lib/lib.rs — main runtime coordinator
• crates/runtime/lib/vm.rs — VM instance management
• crates/runtime/lib/network.rs — delegates to the network crate

The runtime implements the Sandbox::builder API that SDKs expose to users.

Network (crates/network)

The network component implements virtual networking, host-to-guest port forwarding, DNS resolution, and network policy enforcement. See crates/network/lib/mod.rs for the NAT and forwarding implementation.

Filesystem (crates/filesystem)

The filesystem crate provides read-only root filesystem handling, writable overlay support, and volume management. The crates/filesystem/lib/mod.rs module coordinates overlay mounts and ephemeral disk allocation.

Image (crates/image)

The image component pulls OCI/container images, caches layers efficiently, and prepares bootable root filesystems for microVMs. Configuration lives in crates/image/Cargo.toml with core logic in crates/image/lib/mod.rs.

Metrics (crates/metrics)

The metrics crate collects CPU, memory, and network statistics from running microVMs and streams them to the host. The collector runs in both host and guest contexts.

Migration (crates/migration)

The migration component enables snapshotting a running sandbox and restoring it later—critical for warm-worker scenarios where startup latency must be minimized.

The Guest Layer: In-VM Execution

AgentD (crates/agentd)

AgentD is the in-guest sidecar process that exposes the sandbox API to the host. It receives commands through a vsock channel and executes them inside the microVM environment.

Capabilities include:

• Process execution (exec)
• File read/write operations
• Metrics collection forwarding
• Lifecycle signal handling

The agent entry point is crates/agentd/lib/main.rs, with its manifest at crates/agentd/Cargo.toml. AgentD runs with minimal privileges and communicates exclusively through the vsocket interface.

The Transport Layer: Communication Fabric

VSock (crates/vsock)

VSock provides the low-latency socket abstraction that connects host runtime to in-guest agent. Firecracker's vsock implementation offers stream semantics with host-enforced isolation.

Protocol (crates/protocol)

The protocol crate defines the wire format—all message structs, request types, response envelopes, and serialization logic shared between runtime and agent. This ensures version compatibility across host/guest boundaries. Definitions live in crates/protocol/lib/mod.rs.

Higher-Level APIs: SDKs and Clients

MicroSandbox provides language bindings that let applications programmatically control sandboxes without managing low-level details.

SDK	Location	Implementation
Rust SDK	sdk/rust/	Native Rust, re-exports runtime APIs
Python SDK	sdk/python/	pyo3 bindings to Rust core
TypeScript SDK	sdk/node-ts/	Rust native module with TS wrappers
Go SDK	sdk/go/native/	FFI bindings to Rust library

Each SDK implements the Sandbox class with methods like create(), exec(), and stop().

Supporting Libraries and Packages

Agent-Client and Types (packages/)

The agent-client package (packages/agent-client/rust/) provides a language-agnostic client library for agent communication. The microsandbox-types package (packages/microsandbox-types/rust/) defines data contracts shared by host SDKs and the MCP server.

Utilities (crates/utils)

Shared helpers for logging, error handling, async runtime utilities, and configuration parsing used across the entire workspace.

Architecture Summary

┌─────────────────────────────────────────┐
│           SDKs (Rust/Python/TS/Go)      │
│         packages/agent-client           │
├─────────────────────────────────────────┤
│  Host Layer: runtime, network, image,   │
│  filesystem, metrics, migration, vsock  │
├─────────────────────────────────────────┤
│  Transport: protocol (messages) + vsock │
├─────────────────────────────────────────┤
│  Guest Layer: agentd (in-microVM)       │
└─────────────────────────────────────────┘

Practical Examples

Rust SDK: Creating and Running a Sandbox

use microsandbox::Sandbox;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let sandbox = Sandbox::builder("demo")
        .image("python")
        .cpus(1)
        .memory(512)
        .create()
        .await?;

    let out = sandbox
        .exec("python", ["-c", "print('hello from microVM')"])
        .await?;
    println!("{}", out.stdout()?);

    sandbox.stop().await?;
    Ok(())
}

This exercises the runtime, agentd, protocol, network, and filesystem layers.

CLI Workflow

# Create and start a sandbox

msb create --name myapp python

# Execute inside the microVM

msb exec myapp -- python -c "print('hello from microVM')"

# Clean up

msb stop myapp
msb rm myapp

The msb binary is defined in crates/cli/src/main.rs.

Python SDK Equivalent

import asyncio
from microsandbox import Sandbox

async def main():
    sb = await Sandbox.create(
        "py-demo",
        image="python",
        cpus=1,
        memory=512,
    )
    out = await sb.exec("python", ["-c", "print('hello from microVM')"])
    print(out.stdout_text)
    await sb.stop()

asyncio.run(main())

Summary

• Runtime (crates/runtime/) — host-side VM orchestration and lifecycle management
• AgentD (crates/agentd/) — in-guest sidecar exposing sandbox API over vsock
• Protocol + VSock (crates/protocol/, crates/vsock/) — wire format and transport between host and guest
• Infrastructure crates — network, filesystem, image, metrics, migration for sandbox environment management
• SDKs — Rust, Python, TypeScript, and Go bindings for programmatic control
• Agent-client + types packages — shared libraries for tool integration

Frequently Asked Questions

What is the difference between the runtime and agentd?

The runtime runs on the host and manages microVM lifecycle from the outside. AgentD runs inside the microVM and receives commands from the runtime to execute processes and handle file operations. They communicate through vsock using the protocol-defined message format.

How does MicroSandbox handle networking between host and guest?

The network crate (crates/network/) implements virtual networking with NAT, host-to-guest port forwarding, and DNS resolution. The runtime configures network interfaces during VM boot, and policies enforce isolation rules per sandbox.

Can I use MicroSandbox without the CLI?

Yes. The SDKs expose the full API programmatically. The Rust SDK in sdk/rust/lib.rs provides Sandbox::builder(), while Python, TypeScript, and Go SDKs wrap this core functionality for their respective ecosystems.

What enables fast sandbox startup in MicroSandbox?

The image crate caches OCI layers to avoid repeated pulls, and the migration crate supports snapshot/restore for warm workers—allowing sandbox restoration from a frozen state rather than cold boot.

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