Key Source Files in microsandbox: Complete Architecture Guide

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 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 — msb run for creating and starting sandboxes
• snapshot.rs — msb snapshot for checkpoint/restore operations
• ssh.rs — msb ssh for shell access
• metrics.rs — msb metrics for telemetry retrieval

# 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, 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 defines the core VM abstraction. It wrapslightweight hypervisor primitives and exposes methods for start, stop, pause, and resume operations.

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 handles policy parsing and enforcement. It validates security rules before the VM receives execution privileges.

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 contains generic helpers including:

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

crates/metrics-collector/lib/lib.rs implements metrics collection and export. It interfaces with the in-guest agent over Unix domain sockets.

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 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 exposes the public Rust SDK for programmatic sandbox control:

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 implements the host-side client that speaks to the guest agentd. It serializes requests using types from 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 enumerates all workspace members, validating the logical split:

[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	CLI binary entry point
crates/cli/lib/commands/run.rs	msb run implementation
crates/runtime/lib/vm.rs	Core VM abstraction
crates/runtime/lib/startup.rs	Sandbox startup sequence
crates/runtime/lib/policy.rs	Security policy handling
crates/runtime/lib/relay.rs	I/O relay between host/guest
crates/utils/lib/lib.rs	General utilities
crates/metrics-collector/lib/lib.rs	Metrics collection
crates/image/lib/mod.rs	OCI image operations
sdk/rust/lib/sandbox/mod.rs	Public Rust SDK
packages/agent-client/rust/lib/client.rs	Host agent client
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 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 builds configuration objects and delegates to the runtime through the agent protocol defined in packages/agent-client/rust/lib/client.rs.

Where are security policies enforced in microsandbox?

Policy parsing occurs in crates/runtime/lib/policy.rs, with enforcement happening during the startup sequence in crates/runtime/lib/startup.rs before the VM gains execution privileges.

What crate handles OCI image operations?

crates/image/lib/mod.rs provides image loading, layer fetching, and rootfs preparation for sandbox initialization.

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