# Microsandbox Modules and Components: Complete Architecture Guide

> Explore the Microsandbox architecture. Understand its monorepo structure, SDKs, CLI, microVM runtime, shared crates, and AI agent integrations from the superradcompany/microsandbox repo.

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

---

**Microsandbox is organized as a monorepo with SDKs in multiple languages, a CLI, a microVM runtime, internal shared crates, and optional AI agent integrations.**

This guide breaks down every module in the [superradcompany/microsandbox](https://github.com/superradcompany/microsandbox) repository, explaining their purpose, key source locations, and how they compose into a complete sandboxing system.

---

## Language SDKs

Microsandbox provides **idiomatic SDKs** that let applications create and control sandboxes programmatically. Each SDK wraps the same underlying runtime but exposes language-native APIs.

### Rust SDK

The primary implementation, located in [`sdk/rust/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/lib.rs), provides a builder-pattern API for sandbox configuration.

```rust
use microsandbox::Sandbox;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sb = Sandbox::builder("demo")
        .image("python")
        .cpus(1)
        .memory(512)
        .create()
        .await?;

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

```

The builder logic lives in [`sdk/rust/lib/sandbox/builder.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/builder.rs).

### Python SDK

Located in `sdk/python/`, with core implementation in [`sdk/python/microsandbox/_sandbox.py`](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/microsandbox/_sandbox.py):

```python
import asyncio
from microsandbox import Sandbox

async def main():
    sb = await Sandbox.create(
        "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())

```

### Node-TypeScript SDK

Found in `sdk/node-ts/`, with the builder pattern implemented in [`sdk/node-ts/src/sandbox.ts`](https://github.com/superradcompany/microsandbox/blob/main/sdk/node-ts/src/sandbox.ts):

```typescript
import { Sandbox } from "microsandbox";

await using sb = await Sandbox.builder("demo")
  .image("python")
  .cpus(1)
  .memory(512)
  .create();

const out = await sb.exec("python", ["-c", "print('Hello from microVM!')"]);
console.log(out.stdout());

```

### Go SDK

Basic bindings available in [`sdk/go/README.md`](https://github.com/superradcompany/microsandbox/blob/main/sdk/go/README.md).

---

## CLI (`msb`)

The **command-line interface** provides a thin wrapper around SDK/runtime APIs for interactive use.

Key source: [`crates/cli/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/lib/lib.rs) with argument parsing in [`crates/cli/bin/main.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/bin/main.rs).

```bash
msb run python -- python -c "print('Hello from a microVM!')"

```

Command parsing for `run` specifically lives in [`crates/cli/lib/commands/run.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/lib/commands/run.rs).

---

## Core Runtime

The **microVM runtime** in `crates/runtime/` orchestrates VM lifecycle, I/O forwarding, and agent communication.

- **Entry**: [`crates/runtime/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/lib.rs) coordinates VM launch and protocol handling
- **Firmware**: Uses `vendor/libkrunfw` (submodded libkrun firmware) to boot guests

The runtime spawns microVMs, establishes channels to the in-guest agent, and exposes sandbox operations to higher layers.

---

## Internal Shared Crates

These **subsystem crates** isolate concerns used across runtime, SDKs, and CLI:

| Crate | Purpose | Key File |
|-------|---------|----------|
| `filesystem` | Volume handling, bind-mounts, filesystem abstractions | [`crates/filesystem/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/lib.rs) |
| `image` | OCI image pulling, caching, layer extraction | [`crates/image/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/image/lib/lib.rs) |
| `network` | Virtual networking, port forwarding, firewall rules | [`crates/network/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/network/lib/lib.rs) |
| `db` | Persistent metadata for sandboxes, volumes, snapshots | [`crates/db/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/db/lib/lib.rs) |
| `migration` | Database schema migrations | [`crates/migration/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/migration/lib/lib.rs) |
| `metrics` / `metrics-collector` | Real-time resource usage collection | [`crates/metrics/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/metrics/lib/lib.rs) |
| `protocol` | Wire protocol between host and guest | [`crates/protocol/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/lib/lib.rs) |
| `utils` | Cross-cutting helper utilities | [`crates/utils/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/utils/lib/lib.rs) |

---

## Agent and Protocol Stack

### In-Guest Agent (`agentd`)

A **musl-linked binary** that runs inside every microVM to expose a stable API.

- Location: `crates/agentd/`
- Entry: [`crates/agentd/src/main.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/src/main.rs)

Implements the guest side of the protocol defined in `crates/protocol`.

### Agent Client

TypeScript (and Rust) client implementing the **host side** of the sandbox protocol.

- TypeScript: [`packages/agent-client/typescript/src/client.ts`](https://github.com/superradcompany/microsandbox/blob/main/packages/agent-client/typescript/src/client.ts)
- Used by agents and tools to communicate with running sandboxes

### Shared Types

Cross-language type definitions ensuring ABI compatibility:

- TypeScript: [`packages/microsandbox-types/typescript/src/index.ts`](https://github.com/superradcompany/microsandbox/blob/main/packages/microsandbox-types/typescript/src/index.ts)
- Used by agent client and runtime

---

## AI Agent Integrations

### MCP Server

Optional server translating **agent-tool calls** into sandbox lifecycle actions.

- Location: [`mcp/src/main.rs`](https://github.com/superradcompany/microsandbox/blob/main/mcp/src/main.rs)
- Enables structured RPC interface for AI systems

### Skills

Repository of **agent capabilities** teaching AI systems to drive Microsandbox.

- Location: `skills/microsandbox/`
- Contains prompt engineering and tool definitions

---

## Documentation and Examples

| Component | Location | Contents |
|-----------|----------|----------|
| Documentation site | `docs/` | Docusaurus-generated SDK guides, CLI reference, security model |
| Code examples | `examples/` | Runnable projects in Python, Rust, TypeScript (e.g., [`examples/typescript/volume-named/main.ts`](https://github.com/superradcompany/microsandbox/blob/main/examples/typescript/volume-named/main.ts) for volume usage) |

---

## How Microsandbox Components Work Together

1. **User code** calls an SDK (Rust, Python, Node-TS, or Go)
2. The SDK invokes the **runtime** (`crates/runtime`) to spawn a microVM via **libkrun** (`vendor/libkrunfw`)
3. The **in-guest agent** (`crates/agentd`) boots and opens a protocol channel
4. The **agent client** (`packages/agent-client`) implements the host-side transport
5. **Internal crates** handle filesystem mounts, networking, image pulls, and metadata persistence
6. The **CLI** (`msb`) exposes the same APIs for shell-based workflows
7. **MCP server** and **Skills** enable autonomous AI agent operation

This architecture is documented in the **Project Map** section of [`AGENTS.md`](https://github.com/superradcompany/microsandbox/blob/main/AGENTS.md).

---

## Summary

- **SDKs** in four languages provide idiomatic APIs atop the core runtime
- **CLI (`msb`)** offers shell-accessible sandbox management
- **Runtime** orchestrates microVM lifecycle using libkrun firmware
- **Internal crates** (`filesystem`, `image`, `network`, `db`, `protocol`, etc.) isolate reusable subsystems
- **Agent stack** (`agentd`, agent client, shared types) implements the host-guest protocol
- **AI integrations** (MCP server, Skills) expose sandbox operations to language models
- **Docs and examples** lower the barrier to adoption

All components are versioned together in the monorepo according to the project structure defined in [`AGENTS.md`](https://github.com/superradcompany/microsandbox/blob/main/AGENTS.md).

---

## Frequently Asked Questions

### What is the difference between the Microsandbox SDKs and the CLI?

The **SDKs** (`sdk/rust/`, `sdk/python/`, etc.) are libraries for embedding sandbox control directly into applications. The **CLI** (`crates/cli/`) is a standalone binary wrapping the same functionality for terminal use. Both ultimately call into `crates/runtime`.

### How does the in-guest agent communicate with the host?

The **agent** (`crates/agentd`) implements the **guest side** of a wire protocol defined in `crates/protocol`. The host side is handled by the **agent client** ([`packages/agent-client/typescript/src/client.ts`](https://github.com/superradcompany/microsandbox/blob/main/packages/agent-client/typescript/src/client.ts)), which SDKs and the runtime use to send commands and receive output.

### Why does Microsandbox use internal crates instead of a single runtime crate?

The **shared crate architecture** (`filesystem`, `image`, `network`, `db`, etc.) enables independent testing, versioning, and reuse. For example, `crates/image` handles OCI operations without depending on VM specifics, while `crates/network` configures virtual interfaces for any consumer.

### What is libkrunfw and why is it vendored?

**libkrunfw** is the firmware library that boots microVMs. It lives in `vendor/libkrunfw` as a Git submodule to pin a compatible version and apply any necessary patches while tracking upstream development.