How Microsandbox Organizes Its Rust Crates: A Complete Workspace Breakdown

The microsandbox repository uses a Cargo workspace with 15+ crates organized by functional domain, all sharing version 0.6.12 and unified dependencies under a single root Cargo.toml.

The microsandbox codebase from superradcompany/microsandbox is structured as a Rust workspace that splits the sandbox runtime, CLI tools, SDKs, and supporting libraries into independently versioned crates. This architecture enables parallel development while maintaining compatibility through workspace-wide dependency management.

Workspace Structure and Crate Organization

The top-level Cargo.toml declares all member crates and defines shared configuration. Each crate resides in its own subdirectory with a dedicated Cargo.toml, following Cargo's standard workspace pattern.

Core Runtime and Execution Crates

These crates form the foundation of sandbox execution:

• microsandbox-runtime (crates/runtime/) — Implements the guest VM runtime, handling sandbox lifecycle, policy enforcement, and I/O plumbing. This is the engine that actually runs sandboxed workloads.

• microsandbox-agentd (crates/agentd/) — The in-guest "agentd" binary that runs inside each sandbox and communicates with the host via the microsandbox protocol.

• microsandbox-vsock (crates/vsock/) — Platform-specific virtio vsock implementation for host-guest communication.

Data and Storage Crates

State management and persistence are handled by dedicated crates:

• microsandbox-db (crates/db/) — SQLite-backed persistence for sandbox metadata, snapshots, and volumes.

• microsandbox-migration (crates/migration/) — Database schema migrations powered by sea-orm-migration.

• microsandbox-filesystem (crates/filesystem/) — Helper APIs for layered OCI rootfs, volume handling, and overlay mounts.

• microsandbox-image (crates/image/) — OCI image reading, manifest validation, and layer extraction.

Networking and Protocol Crates

Communication layers are abstracted into focused crates:

• microsandbox-network (crates/network/) — High-level networking stack including port publishing and firewall policies, built on smoltcp and hickory-net.

• microsandbox-protocol (crates/protocol/) — Wire-format definitions and (de)serialization for host↔guest communication.

CLI and User Interface

• microsandbox-cli (crates/cli/) — The msb command-line interface for creating, running, and managing sandboxes. This crate produces both the binary and a reusable library for custom tooling.

Observability Crates

• microsandbox-metrics (crates/metrics/) — In-process metrics collection.

• microsandbox-metrics-collector (crates/metrics-collector/) — Optional exporter for OTLP-compatible backends.

SDK and Multi-Language Support

The microsandbox SDK is exposed through language-specific packages:

• sdk/rust/ — The primary Rust SDK crate (microsandbox) that re-exports the public API. Most internal crates depend on this via workspace path dependencies.

• sdk/python/, sdk/node-ts/, sdk/go/ — Language bindings for Python, TypeScript/Node.js, and Go.

Shared Packages and Utilities

• packages/agent-client/rust/ — Reusable client library (microsandbox-agent-client) compiled for Rust and other language bindings.

• packages/microsandbox-types/rust/ — Core type definitions shared across the codebase.

• crates/utils/ — Miscellaneous helpers including logging, secret handling, and TTL indexes.

• crates/testing/ — Test fixtures, procedural macros, and utilities for the workspace test suite.

Crate Dependencies and Relationships

The dependency graph follows clear architectural boundaries:

microsandbox-runtime pulls in microsandbox-protocol, microsandbox-network, and microsandbox-utils to assemble a complete execution environment.

microsandbox-cli orchestrates the runtime, database, and image crates to implement the msb command interface.

microsandbox-agentd imports microsandbox-protocol to maintain wire-format compatibility with the host.

microsandbox-db, filesystem, and image collaborate on persistent state and OCI image management.

microsandbox (the SDK in sdk/rust/) serves as the public API surface. Internal crates reference it via:

[dependencies]
microsandbox = { path = "../sdk/rust", version = "0.6.12" }

Working With the Crate Structure

Example: Using the SDK and Core Crates

// Launch a sandbox using the public SDK and internal crates
use microsandbox::SandboxBuilder;          // from sdk/rust
use microsandbox_image::Image;             // from crates/image
use microsandbox_network::NetworkConfig;   // from crates/network

fn main() -> anyhow::Result<()> {
    // Load an OCI image from a local path
    let image = Image::from_path("./example-image")?;

    // Configure port publishing: host 8080 → sandbox 80
    let net = NetworkConfig::new()
        .publish_port(8080, 80)?;

    // Build and start the sandbox
    let sandbox = SandboxBuilder::new()
        .image(image)
        .network(net)
        .run()?;

    println!("Sandbox PID: {}", sandbox.pid());
    Ok(())
}

The workspace enables this cross-crate usage without external registry dependencies—Cargo resolves paths automatically.

Example: Reusing CLI Logic Programmatically

// Leverage microsandbox-cli as a library
use microsandbox_cli::commands::run::RunOptions;
use microsandbox_cli::run_sandbox;

fn main() -> anyhow::Result<()> {
    let opts = RunOptions {
        image: "./example-image".into(),
        net: None,
        ..Default::default()
    };
    
    // Use the same implementation as the `msb` binary
    run_sandbox(&opts)
}

Key Configuration Files

Path	Purpose
Cargo.toml	Workspace manifest with members list and shared dependencies
crates/runtime/Cargo.toml	Core sandbox execution runtime
crates/cli/Cargo.toml	msb binary and CLI library
crates/agentd/Cargo.toml	In-guest agent binary
crates/protocol/Cargo.toml	Host-guest wire format
sdk/rust/Cargo.toml	Public Rust SDK
packages/agent-client/rust/Cargo.toml	Shared client for multi-language SDKs

Summary

• The microsandbox repository organizes 15+ crates into a Cargo workspace with unified version 0.6.12

• Crates are grouped by function: runtime, CLI, data layer, networking, protocol, observability, and SDKs

• The workspace configuration in root Cargo.toml ensures consistent dependencies across all crates

• Internal crates depend on the public SDK (sdk/rust/) via path dependencies

• Shared packages under packages/ enable code reuse across language bindings

• Testing utilities and examples are colocated under crates/testing/ and examples/

Frequently Asked Questions

What is the main entry point for using microsandbox as a library?

The microsandbox crate in sdk/rust/ serves as the primary library interface. It re-exports the public API and is what most application code should depend on. Internal crates like cli and runtime also use this crate to ensure API consistency.

How does the workspace handle dependency versions?

All crates share a single version (0.6.12) defined in the workspace root. The top-level Cargo.toml declares workspace-wide dependencies (e.g., tokio, serde, anyhow) with specific versions, and member crates reference these via workspace = true. This guarantees every crate builds against the same dependency graph.

What's the difference between crates/ and sdk/ directories?

The crates/ directory contains internal implementation crates that power the sandbox runtime, CLI, and infrastructure. The sdk/ directory contains public-facing language bindings that expose the microsandbox API to application developers. The Rust SDK in sdk/rust/ re-exports functionality from the internal crates while maintaining backward compatibility guarantees.

How is host-guest communication implemented across crates?

The microsandbox-protocol crate (crates/protocol/) defines the wire format and serialization. Both the host-side runtime and the guest-side agentd depend on this crate, ensuring protocol compatibility. The microsandbox-vsock crate provides the underlying transport mechanism.

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