# microsandbox Dependencies: Complete Guide to Internal Crates and External Libraries

> Explore microsandbox dependencies, including 14 internal crates and 40+ external libraries for networking, async, and crypto. Understand the project's core components.

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

---

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

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

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

```rust
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`](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml) (workspace root) | Central dependency declarations — lines 50-90 for internal crates, line 96+ for external |
| [`sdk/rust/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib.rs) | Public SDK entry point consuming workspace dependencies |
| [`crates/runtime/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib.rs) | krun VM integration and async execution environment |
| [`crates/network/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/network/lib.rs) | smoltcp-based networking stack implementation |
| [`crates/protocol/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml) for maintainability

## Frequently Asked Questions

### What is the main dependency file in microsandbox?

The workspace root [`Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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.