How to Build Microsandbox from Source: Complete Installation Guide

Clone the repository, run just setup, and the task runner automatically installs dependencies, builds the agentd guest agent, compiles libkrunfw, and installs the msb CLI to ~/.microsandbox/bin.

Microsandbox is a Rust‑centric workspace that combines a lightweight microVM runtime with a high‑level CLI and multi‑language SDKs. Building from source gives you full control over the compilation process and lets you modify the guest agent, runtime, or CLI components. This guide walks through the complete build process using the just task runner and the workspace structure defined in DEVELOPMENT.md.

Prerequisites for Building Microsandbox

You need the Rust toolchain, just, git, and platform‑specific development libraries. The repository supports Linux, macOS, and Windows builds with platform‑specific recipes in the justfile.

Linux Prerequisites

Install build tools, musl libc support, and kernel build dependencies:

sudo apt install build-essential musl-tools flex bison libelf-dev \
    python3-pyelftools pkg-config libcap-ng-dev pre-commit

macOS Prerequisites

Use Homebrew for the core toolchain:

brew install just git pre-commit

Windows Prerequisites

Install Visual Studio Build Tools and Docker or WSL for cross‑compilation. Refer to DEVELOPMENT.md lines 16‑18 for Windows‑specific guidance.

Repository Structure and Key Components

Microsandbox organizes code as a Cargo workspace with four architectural layers. Understanding these helps when you need to rebuild specific components.

Layer	Description	Key Paths
Runtime	MicroVM runtime integrating libkrunfw with the guest agent	crates/runtime/, vendor/libkrunfw/
Guest Agent	Static agentd binary that runs inside VMs	crates/agentd/, justfile build‑agentd rules
CLI	User‑facing msb command‑line interface	crates/cli/, justfile build‑msb rules
SDKs	Language bindings (Rust, Python, Node‑TS, Go)	sdk/ rust/, python/, node‑ts/, go/
Support Crates	Shared utilities: networking (smoltcp), filesystem, DB, metrics	crates/* per DEVELOPMENT.md lines 13‑33

Step‑by‑Step Build Instructions

1. Clone and Initialize Submodules

git clone https://github.com/superradcompany/microsandbox.git
cd microsandbox

The just setup recipe automatically pulls the vendor/libkrunfw submodule at lines 26‑28 of the justfile.

2. Run the Complete Setup

just setup

This single command executes the full pipeline:

• Installs system dependencies (platform‑specific)
• Builds agentd as a static musl binary (Linux) or via Docker (macOS) or PowerShell (Windows)
• Compiles libkrunfw from the vendor/libkrunfw submodule
• Builds the msb CLI with Cargo
• Installs all binaries to ~/.microsandbox (Unix) or %USERPROFILE%\.microsandbox (Windows)

3. Verify the Installation

msb --version

If the command is not found, add ~/.microsandbox/bin to your $PATH as shown by the install recipe at lines 21‑44 of the justfile.

Common Build Operations

After initial setup, use these recipes for iterative development:

# Debug rebuild after code changes

just build && just install

# Production‑optimized build

just build release && just install

# Full clean rebuild

just clean && just setup

# Build only specific components

just build-deps      # agentd + libkrunfw only

just build-agentd    # guest agent only

just build-libkrunfw # firmware library only

just build-msb       # CLI only

Running Your First Sandbox

Once built, launch a sandboxed Python environment:

msb run python -- python3 -c "print('Hello from a microVM!')"

For programmatic access, use the Rust SDK after building and linking the crate:

use microsandbox::Sandbox;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sandbox = Sandbox::builder("demo")
        .image("python")
        .cpus(1)
        .memory(512)
        .create()
        .await?;
    
    let out = sandbox
        .exec("python", ["-c", "print('Hello from Rust!')"])
        .await?;
    
    println!("{}", out.stdout()?);
    sandbox.stop().await?;
    Ok(())
}

Key Source Files Reference

File	Purpose
justfile	Central task definitions for all build, test, and install operations
DEVELOPMENT.md	Human‑readable build guide with prerequisite lists
crates/agentd/Cargo.toml	Guest agent package manifest and dependencies
vendor/libkrunfw/	Git submodule containing kernel firmware sources
crates/cli/src/lib.rs	msb CLI implementation entry point
crates/runtime/	MicroVM orchestration and libkrunfw integration

Summary

• Microsandbox builds from source using just as the task runner, not raw cargo commands.
• The just setup recipe handles prerequisites, submodule initialization, and full compilation in one step.
• Three core artifacts are produced: agentd (static guest agent), libkrunfw (kernel firmware), and msb (CLI binary).
• All binaries install to ~/.microsandbox/bin, requiring manual $PATH configuration.
• Platform‑specific build logic lives in the justfile at lines 56‑100, handling musl linking on Linux, Docker on macOS, and MSVC on Windows.

Frequently Asked Questions

What is the fastest way to build microsandbox from source?

Run just setup after cloning. This single command triggers the complete pipeline defined in the justfile: dependency checks, submodule initialization, agentd compilation, libkrunfw building, and CLI installation.

Can I build microsandbox without the just task runner?

You can invoke cargo directly, but you must manually replicate the justfile logic. This includes building agentd with musl target flags, compiling libkrunfw from vendor/libkrunfw, and ensuring the runtime links against the correct firmware library. The just recipes encode these dependencies explicitly.

Why does my build fail on libkrunfw compilation?

The vendor/libkrunfw directory is a Git submodule. If you skipped just setup, run git submodule update --init --recursive first. On Linux, verify you installed flex, bison, libelf-dev, and python3-pyelftools per the justfile prerequisites at lines 45‑53.

How do I rebuild only the CLI after making changes?

Use just build-msb && just install. This skips the lengthy agentd and libkrunfw compilation when you have only modified code in crates/cli/ or its dependencies.

Where are the compiled binaries installed?

The just install recipe copies artifacts to ~/.microsandbox on Unix or %USERPROFILE%\.microsandbox on Windows, placing executables in the bin/ subdirectory. The recipe prints a reminder to add this directory to your $PATH at lines 21‑44 of the justfile.

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