# How Microsandbox Organizes Its Rust Crates: A Complete Workspace Breakdown

> Discover how Microsandbox organizes its Rust crates. Explore a Cargo workspace breakdown with 15+ crates organized by functional domain for efficient development.

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

---

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

The **microsandbox** codebase from [superradcompany/microsandbox](https://github.com/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`](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml) declares all member crates and defines shared configuration. Each crate resides in its own subdirectory with a dedicated [`Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/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:

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

```

## Working With the Crate Structure

### Example: Using the SDK and Core Crates

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

```rust
// 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`](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml) | Workspace manifest with members list and shared dependencies |
| [`crates/runtime/Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/Cargo.toml) | Core sandbox execution runtime |
| [`crates/cli/Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/Cargo.toml) | `msb` binary and CLI library |
| [`crates/agentd/Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/Cargo.toml) | In-guest agent binary |
| [`crates/protocol/Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/crates/protocol/Cargo.toml) | Host-guest wire format |
| [`sdk/rust/Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/Cargo.toml) | Public Rust SDK |
| [`packages/agent-client/rust/Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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.