microsandbox Dependencies: Complete Guide to Internal Crates and External Libraries

The microsandbox project is a Cargo workspace with 14 internal crates and 40+ external dependencies for networking, serialization, async runtime, and cryptography, all defined in the root Cargo.toml.

The microsandbox repository by SuperRad Company provides a micro-VM sandbox platform built in Rust. Understanding its microsandbox dependencies reveals a carefully architected workspace that balances internal modularity with battle-tested external libraries. This guide breaks down every dependency category with source file references and practical code examples.

Workspace Structure: Internal vs. External Dependencies

The project uses a Cargo workspace pattern. All dependency declarations live in the workspace-wide Cargo.toml at the repository root, with individual crates referencing them via workspace = true.

Internal Crates (Workspace Members)

These 14 crates are defined under [workspace.dependencies] and version-pinned to =0.6.12:

Crate	Path	Purpose
microsandbox	sdk/rust	Public Rust SDK — primary API surface
microsandbox-agent-client	packages/agent-client/rust	Client for in-guest agentd process
microsandbox-db	crates/db	SQLite persistence for sandbox metadata
microsandbox-filesystem	crates/filesystem	Filesystem abstraction and overlay handling
microsandbox-image	crates/image	OCI image handling and unpacking
microsandbox-metrics	crates/metrics	Prometheus-compatible metrics export
microsandbox-types	packages/microsandbox-types/rust	Shared wire protocol types
microsandbox-migration	crates/migration	Database migration helpers
microsandbox-network	crates/network	Network stack (smoltcp-based) and port forwarding
microsandbox-protocol	crates/protocol	Host-agent control protocol definitions
microsandbox-runtime	crates/runtime	Core VM/runtime integration (Krun, vsock)
microsandbox-utils	crates/utils	Cross-crate utility functions
microsandbox-vsock	crates/vsock	vsock (virtio socket) host-guest communication
test-macros / test-utils	crates/testing/*	Internal test infrastructure

Each internal crate is declared with path and version pinning. From Cargo.toml lines 78-90:

microsandbox = { version = "=0.6.12", path = "sdk/rust", default-features = false }
microsandbox-agent-client = { version = "=0.6.12", path = "packages/agent-client/rust", default-features = false }
microsandbox-db = { version = "=0.6.12", path = "crates/db", default-features = false }

# ... additional crates follow same pattern

External Crate Dependencies

The microsandbox dependencies from crates.io span eight functional domains. These begin at line 96 in Cargo.toml.

Error Handling and Utilities

Crate	Purpose
anyhow	Flexible error handling with context
thiserror	Derive macro for custom error types
scopeguard	RAII scope guards
typed-builder	Compile-time verified builder patterns
typed-path	Type-safe filesystem paths
zeroize	Secure memory clearing for secrets
lru	LRU cache implementation
parking_lot	Efficient synchronization primitives

Async Runtime

Crate	Purpose
tokio (full features)	Async runtime with I/O, net, signal handling
tokio-util	Additional Tokio utilities
tokio-tungstenite	WebSocket support
tokio-rustls	TLS integration for Tokio

The Tokio configuration at lines 50-62 intentionally enables the full feature set. A comment documents special handling for parking_lot to avoid forking issues in the VM runtime.

Networking and Protocols

Crate	Purpose
smoltcp	no_std TCP/IP stack for guest networking
socket2	Advanced socket options
hickory-net / hickory-proto	DNS resolution
etherparse	Packet parsing
httlib-hpack	HPACK compression for HTTP/2
russh / russh-sftp	SSH client and SFTP implementation

Serialization and Data Formats

Crate	Purpose
serde / serde_json / serde_bytes	Core serialization
serde-saphyr	YAML support
ciborium	CBOR (Concise Binary Object Representation)
ts-rs	TypeScript type generation from Rust

OCI and Container Images

Crate	Purpose
oci-client	Pull and push OCI images
oci-spec	OCI specification types

Filesystem and Compression

Crate	Purpose
bytes	Efficient byte buffers
flate2	Gzip compression
tar	Archive handling
async-compression	Async compression streams
tempfile	Temporary file management
reflink-copy	Copy-on-write file cloning
xattr	Extended attribute handling

Cryptography and Security

Crate	Purpose
blake3 / sha2	Cryptographic hashing
base64	Base64 encoding
rustls / rustls-pki-types / rustls-native-certs / rustls-platform-verifier	Modern TLS stack
rcgen	Certificate generation

Database and ORM

Crate	Purpose
sea-orm / sea-orm-migration	Async ORM with migrations
sqlx	Async SQLite driver

CLI and Developer Experience

Crate	Purpose
clap / clap_complete	Command-line parsing and shell completions
console	Terminal colors and styling
crossterm	Cross-platform terminal control
indicatif	Progress bars and spinners

Additional Dependencies

• Time handling: chrono, time
• Randomness and parallelism: rand, rayon
• HTTP clients: reqwest, ureq
• System utilities: which, dirs, nix
• Capability-based security: cap-primitives, cap-std
• Filesystem watching: notify
• Networking types: ipnetwork
• Enum utilities: strum
• Hex encoding: hex
• Logging: tracing, tracing-subscriber

Practical Usage Examples

Creating a Sandbox with Core Dependencies

This example demonstrates how the SDK integrates tokio, anyhow, and OCI client functionality:

use microsandbox::Sandbox;
use microsandbox::runtime::NetworkPort;
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialize sandbox from OCI image (uses oci-client internally)
    let mut sandbox = Sandbox::builder()
        .image("docker.io/library/alpine:latest")
        .build()
        .await?;

    // Expose TCP port from sandbox to host
    let host_port = NetworkPort::new(8080, 80);
    sandbox.add_network_port(host_port).await?;

    // Spawn krun VM with tokio async I/O
    sandbox.start().await?;

    let listener = TcpListener::bind("127.0.0.1:8080").await?;
    println!("Sandbox listening on 0.0.0.0:8080 → container:80");
    Ok(())
}

Collecting Runtime Metrics

The microsandbox-metrics crate with reqwest and tokio:

use microsandbox_metrics::MetricsCollector;
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let collector = MetricsCollector::new("http://localhost:9090/metrics")?;
    loop {
        let cpu = collector.cpu_usage().await?;
        println!("Current CPU usage: {:.2}%", cpu * 100.0);
        sleep(Duration::from_secs(5)).await;
    }
}

Key Dependency Design Patterns

The microsandbox dependencies follow several architectural principles evident in the source:

• Exact version pinning (=0.6.12) for internal crates ensures reproducible builds across all workspace members
• Feature gating via default-features = false allows downstream users to minimize binary size
• Security-first selection with rustls (not OpenSSL), zeroize for secrets, and capability-based primitives from cap-std
• Async-native stack centered on Tokio for I/O, networking, and VM lifecycle management

Source Files Referenced

File	Significance
Cargo.toml (workspace root)	Central dependency declarations — lines 50-90 for internal crates, line 96+ for external
sdk/rust/lib.rs	Public SDK entry point consuming workspace dependencies
crates/runtime/lib.rs	krun VM integration and async execution environment
crates/network/lib.rs	smoltcp-based networking stack implementation
crates/protocol/lib.rs	Host-agent wire protocol definitions

Summary

• microsandbox dependencies are organized as a Cargo workspace with 14 internal crates and 40+ external libraries
• Internal crates are version-pinned to =0.6.12 and referenced via workspace = true
• External dependencies cover async runtime (Tokio), networking (smoltcp, rustls), OCI images (oci-client), databases (sea-orm), and cryptography (blake3, rustls)
• Feature gating and default-features = false enable lean binaries for embedded use cases
• All declarations are centralized in the root Cargo.toml for maintainability

Frequently Asked Questions

What is the main dependency file in microsandbox?

The workspace root Cargo.toml contains all dependency definitions. Internal crates are listed under [workspace.dependencies] starting at line 78, and external crates follow from line 96 onward.

Why does microsandbox use exact version pinning for internal crates?

The =0.6.12 constraint guarantees that every workspace member compiles against identical source code. This eliminates version drift and ensures reproducible builds across different machines and CI environments.

What async runtime does microsandbox use?

The project uses Tokio with full features enabled (lines 50-62 in Cargo.toml). This provides async I/O, networking, signal handling, and process management required by the krun-based VM runtime.

How does microsandbox handle TLS and cryptography?

The dependency stack uses rustls with platform-native certificate verification (rustls-native-certs, rustls-platform-verifier) instead of OpenSSL. Hashing is provided by blake3 and sha2, with zeroize for secure memory clearing of sensitive data.

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