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

> Explore MicroSandbox's core components: host runtime, in-guest agent, transport protocols, and SDKs. Discover how this Rust-based MicroVM system delivers fast, isolated sandbox execution.

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

---

**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`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/lib.rs) — main runtime coordinator
- [`crates/runtime/lib/vm.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/vm.rs) — VM instance management
- [`crates/runtime/lib/network.rs`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/crates/image/Cargo.toml) with core logic in [`crates/image/lib/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/lib/main.rs), with its manifest at [`crates/agentd/Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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

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

```bash

# 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`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/src/main.rs).

### Python SDK Equivalent

```python
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`](https://github.com/superradcompany/microsandbox/blob/main/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.