# Key Source Files in microsandbox: Complete Architecture Guide

> Explore the key source files in microsandbox. Understand the CLI front-end, sandbox runtime, and shared libraries within this Rust workspace architecture.

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

---

**The microsandbox repository is organized as a multi-crate Rust workspace with three core layers: CLI front-end (`crates/cli`), sandbox runtime (`crates/runtime`), and shared libraries including SDK bindings and protocol definitions.**

The **microsandbox** project, maintained by superradcompany, provides a lightweight, container-like sandbox runtime with language SDKs and a command-line interface. Understanding its source file organization is essential for contributors, integrators, and anyone extending the platform. This guide breaks down the key files across each architectural layer with concrete examples from the codebase.

## CLI Front-End Layer

The CLI layer parses user commands and translates them into protocol messages for the in-guest agent.

### Entry Point and Command Dispatch

[`crates/cli/bin/main.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/bin/main.rs) serves as the executable entry point. It initializes logging, parses global flags, and delegates to subcommand implementations.

Command handlers live in `crates/cli/lib/commands/*`, with each file implementing a specific `msb` subcommand:

- [`run.rs`](https://github.com/superradcompany/microsandbox/blob/main/run.rs) — `msb run` for creating and starting sandboxes
- [`snapshot.rs`](https://github.com/superradcompany/microsandbox/blob/main/snapshot.rs) — `msb snapshot` for checkpoint/restore operations
- [`ssh.rs`](https://github.com/superradcompany/microsandbox/blob/main/ssh.rs) — `msb ssh` for shell access
- [`metrics.rs`](https://github.com/superradcompany/microsandbox/blob/main/metrics.rs) — `msb metrics` for telemetry retrieval

```bash

# Example: Create and start a sandbox from a local OCI image

msb run \
  --image ./examples/rust/rootfs-patch/oci-image \
  --cmd "/bin/sh" \
  --mount /host/path:/sandbox/path:ro

```

This command dispatches to [`crates/cli/lib/commands/run.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/lib/commands/run.rs), which constructs a `SandboxConfig` via the SDK and transmits it through the agent protocol.

## Runtime Core Layer

The runtime spins up sandbox VMs, manages filesystem mounts, enforces security policies, and handles bidirectional I/O.

### VM Abstraction and Lifecycle

[`crates/runtime/lib/vm.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/vm.rs) defines the core **VM abstraction**. It wrapslightweight hypervisor primitives and exposes methods for start, stop, pause, and resume operations.

[`crates/runtime/lib/startup.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/startup.rs) orchestrates the **sandbox initialization sequence**:

1. Network namespace setup
2. Root filesystem mounting
3. Secret injection
4. Guest agent socket preparation

### Security and Communication

[`crates/runtime/lib/policy.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/policy.rs) handles **policy parsing and enforcement**. It validates security rules before the VM receives execution privileges.

[`crates/runtime/lib/relay.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/relay.rs) implements **bidirectional data relay** for console streams, log forwarding, and network tunneling between host and guest.

## Shared Libraries Layer

These crates provide reusable building blocks that keep the CLI, runtime, and SDK decoupled.

### Utilities and Infrastructure

[`crates/utils/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/utils/lib/lib.rs) contains generic helpers including:

- `process_lock` — cross-process synchronization primitives
- `secret` — secure credential handling

[`crates/metrics-collector/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/metrics-collector/lib/lib.rs) implements **metrics collection and export**. It interfaces with the in-guest agent over Unix domain sockets.

```rust
use microsandbox::metrics::MetricsCollector;

fn main() -> anyhow::Result<()> {
    let mut collector = MetricsCollector::new();
    // Pull metrics from the agent over a Unix domain socket
    let metrics = collector.fetch("msb.sock")?;
    println!("CPU usage: {}%", metrics.cpu_percent);
    Ok(())
}

```

### Image Handling

[`crates/image/lib/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/image/lib/mod.rs) provides **OCI image loading and inspection**. It resolves image references, fetches layers, and prepares rootfs mounts for the runtime.

### SDK and Protocol Bindings

[`sdk/rust/lib/sandbox/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/mod.rs) exposes the **public Rust SDK** for programmatic sandbox control:

```rust
use microsandbox::sandbox::{SandboxBuilder, SandboxConfig};

fn main() -> anyhow::Result<()> {
    // Build a sandbox configuration
    let cfg = SandboxConfig::default()
        .with_image("docker.io/library/alpine:latest")
        .with_cmd(vec!["/bin/sh".into()]);

    // Launch the sandbox
    let sandbox = SandboxBuilder::new().config(cfg).build()?;
    println!("Sandbox started with ID {}", sandbox.id());

    // Execute a command inside the sandbox
    let exec = sandbox.exec().cmd("/usr/bin/env").run()?;
    println!("Exec output: {}", exec.stdout());
    Ok(())
}

```

[`packages/agent-client/rust/lib/client.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/agent-client/rust/lib/client.rs) implements the **host-side client** that speaks to the guest `agentd`. It serializes requests using types from [`packages/microsandbox-types/rust/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/microsandbox-types/rust/lib/lib.rs), which contains **shared type definitions and validation logic** used across all workspace members.

## Workspace Structure Confirmation

The repository root [`Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml) enumerates all workspace members, validating the logical split:

```toml
[workspace]
members = [
    "crates/cli",
    "crates/runtime",
    "crates/utils",
    "crates/metrics-collector",
    "crates/image",
    "packages/agent-client/rust",
    "packages/microsandbox-types/rust",
    "sdk/rust",
    # ...

]

```

## Key Files Reference

| File | Role |
|------|------|
| [`crates/cli/bin/main.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/bin/main.rs) | CLI binary entry point |
| [`crates/cli/lib/commands/run.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/lib/commands/run.rs) | `msb run` implementation |
| [`crates/runtime/lib/vm.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/vm.rs) | Core VM abstraction |
| [`crates/runtime/lib/startup.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/startup.rs) | Sandbox startup sequence |
| [`crates/runtime/lib/policy.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/policy.rs) | Security policy handling |
| [`crates/runtime/lib/relay.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/relay.rs) | I/O relay between host/guest |
| [`crates/utils/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/utils/lib/lib.rs) | General utilities |
| [`crates/metrics-collector/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/metrics-collector/lib/lib.rs) | Metrics collection |
| [`crates/image/lib/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/image/lib/mod.rs) | OCI image operations |
| [`sdk/rust/lib/sandbox/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/mod.rs) | Public Rust SDK |
| [`packages/agent-client/rust/lib/client.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/agent-client/rust/lib/client.rs) | Host agent client |
| [`packages/microsandbox-types/rust/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/microsandbox-types/rust/lib/lib.rs) | Shared type definitions |

## Summary

- **CLI layer** (`crates/cli`) — parses commands and builds `SandboxConfig` instances
- **Runtime layer** (`crates/runtime`) — constructs VMs, applies policies, and manages guest lifecycles
- **Shared libraries** — provide utilities, metrics, image handling, SDK bindings, and protocol types
- **Agent protocol** — unifies communication between CLI, SDK, and runtime through `microsandbox-types` and `agent-client`

## Frequently Asked Questions

### What is the main entry point for the microsandbox CLI?

[`crates/cli/bin/main.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/bin/main.rs) is the executable entry point. It handles global argument parsing and routes to subcommand implementations in `crates/cli/lib/commands/`.

### How does the Rust SDK interact with the sandbox runtime?

The SDK in [`sdk/rust/lib/sandbox/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/mod.rs) builds configuration objects and delegates to the runtime through the agent protocol defined in [`packages/agent-client/rust/lib/client.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/agent-client/rust/lib/client.rs).

### Where are security policies enforced in microsandbox?

Policy parsing occurs in [`crates/runtime/lib/policy.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/policy.rs), with enforcement happening during the startup sequence in [`crates/runtime/lib/startup.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/runtime/lib/startup.rs) before the VM gains execution privileges.

### What crate handles OCI image operations?

[`crates/image/lib/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/image/lib/mod.rs) provides image loading, layer fetching, and rootfs preparation for sandbox initialization.