Microsandbox Modules and Components: Complete Architecture Guide

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 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, provides a builder-pattern API for sandbox configuration.

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.

Python SDK

Located in sdk/python/, with core implementation in sdk/python/microsandbox/_sandbox.py:

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:

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.

---

CLI (msb)

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

Key source: crates/cli/lib/lib.rs with argument parsing in crates/cli/bin/main.rs.

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

Command parsing for run specifically lives in 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 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
image	OCI image pulling, caching, layer extraction	crates/image/lib/lib.rs
network	Virtual networking, port forwarding, firewall rules	crates/network/lib/lib.rs
db	Persistent metadata for sandboxes, volumes, snapshots	crates/db/lib/lib.rs
migration	Database schema migrations	crates/migration/lib/lib.rs
metrics / metrics-collector	Real-time resource usage collection	crates/metrics/lib/lib.rs
protocol	Wire protocol between host and guest	crates/protocol/lib/lib.rs
utils	Cross-cutting helper utilities	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

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

---

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.

---

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

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