How to Build Microsandbox from Source: Complete Guide for Linux, macOS, and Windows

Build microsandbox from source using the just task runner with just setup, which installs dependencies, compiles the agentd guest agent, builds libkrunfw, and installs the msb CLI to ~/.microsandbox/bin.

Microsandbox is a Rust-based microVM runtime developed by SuperRad Company that combines a lightweight virtualization layer with developer-friendly tooling. Building from source gives you access to the latest features, patches, and platform-specific optimizations. This guide walks through the complete build process using the official justfile recipes documented in DEVELOPMENT.md.

Repository Architecture

Microsandbox is organized as a Cargo workspace with several interconnected layers. Understanding this structure helps troubleshoot build issues and identify which components you need to modify.

Layer	Description	Key Path
Runtime	MicroVM runtime integrating libkrunfw kernel firmware	crates/runtime/
Guest Agent	Static musl-linked binary running inside VMs	crates/agentd/
CLI	User-facing msb command-line interface	crates/cli/
SDKs	Language bindings (Rust, Python, Node-TS, Go)	sdk/
Support Crates	Networking, filesystem, database, metrics utilities	crates/* per DEVELOPMENT.md【/cache/repos/github.com/superradcompany/microsandbox/main/DEVELOPMENT.md†L13-L33】

All build outputs land in the build/ directory before installation to ~/.microsandbox (Unix) or %USERPROFILE%\.microsandbox (Windows) per the install recipe.

Prerequisites

Install the required system dependencies before attempting to build. The justfile contains platform-specific check commands referenced in DEVELOPMENT.md.

Linux (Ubuntu/Debian)

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

Per justfile lines 45-53【/cache/repos/github.com/superradcompany/microsandbox/main/justfile†L45-L53】.

macOS

brew install just git pre-commit

Per justfile lines 62-66【/cache/repos/github.com/superradcompany/microsandbox/main/justfile†L62-L66】.

Windows

Install Visual Studio Build Tools with C++ workload. Cross-compilation requires Docker or WSL per DEVELOPMENT.md lines 16-18【/cache/repos/github.com/superradcompany/microsandbox/main/DEVELOPMENT.md†L16-L18】.

Build Microsandbox from Source: Step-by-Step

Step 1: Clone and Initialize

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

The vendor/libkrunfw submodule is pulled automatically by the setup recipe【/cache/repos/github.com/superradcompany/microsandbox/main/justfile†L26-L28】.

Step 2: Run Full Setup (Recommended)

just setup

This single command:

• Verifies prerequisites
• Builds static agentd binary (musl on Linux, Docker on macOS, or PowerShell scripts on Windows)【/cache/repos/github.com/superradcompany/microsandbox/main/justfile†L84-L100】
• Compiles libkrunfw from vendor/libkrunfw【/cache/repos/github.com/superradcompany/microsandbox/main/justfile†L56-L71】
• Builds the msb CLI with optional code signing on macOS【/cache/repos/github.com/superradcompany/microsandbox/main/justfile†L89-L104】
• Installs binaries to ~/.microsandbox

Step 3: Add to PATH

After just install completes, add the installation directory to your shell:

export PATH="$HOME/.microsandbox/bin:$PATH"

The installer prints this reminder automatically【/cache/repos/github.com/superradcompany/microsandbox/main/justfile†L21-L44】.

Step 4: Verify Installation

msb --version

Expected output shows version information confirming the build succeeded per DEVELOPMENT.md lines 49-53【/cache/repos/github.com/superradcompany/microsandbox/main/DEVELOPMENT.md†L49-L53】.

Common Build Scenarios

Rebuild After Code Changes

just build && just install

Compiles debug artifacts—faster iteration during development.

Build Release-Optimized Binaries

just build release && just install

Applies compiler optimizations for production deployments.

Clean Build Artifacts

just clean

Removes build/ directory and cached artifacts. Useful when switching branches or resolving linker issues.

Build Components Independently

Command	Purpose
just build-deps	Build agentd + libkrunfw only
just build-agentd	Rebuild guest agent binary
just build-libkrunfw	Recompile kernel firmware library
just build-msb	Compile CLI without dependencies

Full recipe list in DEVELOPMENT.md lines 55-94【/cache/repos/github.com/superradcompany/microsandbox/main/DEVELOPMENT.md†L55-L94】.

Test Your Build

Run a sandboxed Python execution:

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

This launches a microVM with the Python image, executes the command, and returns output.

Using the Rust SDK

After building from source, depend on the local 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(())
}

See sdk/rust/README.md for dependency configuration.

Troubleshooting Build Failures

Symptom	Cause	Solution
musl-gcc not found	Missing musl-tools	sudo apt install musl-tools
libelf.h: No such file	Missing libelf-dev	sudo apt install libelf-dev
libkrunfw build fails	Submodule not initialized	Run just setup or git submodule update --init
pre-commit not found	Missing git hooks tool	Install per platform prerequisites
Windows linker errors	MSVC not configured	Run from "Developer Command Prompt for VS"

Summary

• Microsandbox builds from source using just task runner recipes defined in justfile
• just setup automates the complete workflow: prerequisites, submodule initialization, agentd + libkrunfw compilation, and CLI installation
• Platform differences: Linux uses native musl toolchain; macOS uses Docker for cross-compilation; Windows requires MSVC build environment
• Installation target: ~/.microsandbox/bin (Unix) or %USERPROFILE%\.microsandbox (Windows)—add to PATH manually
• Verification: Run msb --version and msb run to confirm working build

Frequently Asked Questions

What is the fastest way to build microsandbox from source?

Run just setup after cloning. This single command handles prerequisites, submodule initialization, dependency builds (agentd, libkrunfw), CLI compilation, and installation to ~/.microsandbox. It typically takes 5-15 minutes depending on your machine and network speed.

Can I build microsandbox without Docker?

On Linux, yes—the build uses native musl-gcc and system toolchains directly. On macOS, Docker is currently required to cross-compile agentd and libkrunfw since the microVM components target Linux. Windows builds use native MSVC where possible but may need WSL for certain components.

Where are the build outputs located?

All compilation artifacts appear in repository-root/build/. The just install recipe then copies build/msb and the appropriate libkrunfw library into your user's sandbox directory (~/.microsandbox on Unix). The installer prints instructions for adding ~/.microsandbox/bin to your PATH.

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