# How to Build Microsandbox from Source: Complete Installation Guide

> Build microsandbox from source with this complete installation guide. Clone the repo, run just setup, and automatically install dependencies and build the agent, libkrunfw, and CLI.

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

---

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

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

```bash
brew install just git pre-commit

```

### Windows Prerequisites

Install Visual Studio Build Tools and Docker or WSL for cross‑compilation. Refer to [`DEVELOPMENT.md`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md) lines 13‑33 |

## Step‑by‑Step Build Instructions

### 1. Clone and Initialize Submodules

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

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

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

```bash

# 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:

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

```

For programmatic access, use the Rust SDK after building and linking the 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(())
}

```

## Key Source Files Reference

| File | Purpose |
|------|---------|
| `justfile` | Central task definitions for all build, test, and install operations |
| [`DEVELOPMENT.md`](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md) | Human‑readable build guide with prerequisite lists |
| [`crates/agentd/Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/Cargo.toml) | Guest agent package manifest and dependencies |
| `vendor/libkrunfw/` | Git submodule containing kernel firmware sources |
| [`crates/cli/src/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/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`.