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

> Learn to build microsandbox from source on Linux macOS and Windows. This guide covers dependency installation compilation and CLI setup for the superradcompany microsandbox project.

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

---

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

### Linux (Ubuntu/Debian)

```bash
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

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

```bash
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)

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

```bash
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

```bash
msb --version

```

Expected output shows version information confirming the build succeeded per [`DEVELOPMENT.md`](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md) lines 49-53【/cache/repos/github.com/superradcompany/microsandbox/main/DEVELOPMENT.md†L49-L53】.

## Common Build Scenarios

### Rebuild After Code Changes

```bash
just build && just install

```

Compiles debug artifacts—faster iteration during development.

### Build Release-Optimized Binaries

```bash
just build release && just install

```

Applies compiler optimizations for production deployments.

### Clean Build Artifacts

```bash
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`](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md) lines 55-94【/cache/repos/github.com/superradcompany/microsandbox/main/DEVELOPMENT.md†L55-L94】.

## Test Your Build

Run a sandboxed Python execution:

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

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