How to Set Up Microsandbox Locally: Complete Development Environment Guide

Set up Microsandbox locally by installing prerequisites, cloning the repository, running just setup to build the tool chain, and adding ~/.microsandbox/bin to your PATH.

Microsandbox is an open-source framework that runs untrusted code inside fast, hardware-isolated microVMs. This guide walks through the complete local setup process for the superradcompany/microsandbox repository, from host preparation to running your first sandbox.

Prerequisites for Microsandbox Local Setup

Before building, ensure your host meets the platform-specific requirements. Microsandbox supports macOS, Linux with KVM, and Windows with Windows Hypervisor Platform (WHP).

Platform	Required Components
macOS	macOS 11+, just, git, pre-commit
Linux	KVM-enabled kernel, just, git, pre-commit
Windows	WHP enabled, just, git, pre-commit

Install these tools through your system package manager. On Ubuntu:

sudo apt update && sudo apt install -y just git pre-commit curl

The repository's README.md (lines 15-19) documents platform-specific requirements, while DEVELOPMENT.md (lines 9-16) expands on prerequisite details.

Step 1: Clone the Microsandbox Repository

Retrieve the source code including all submodules:

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

This clones the workspace containing Rust crates, SDKs, and the libkrun firmware submodule. The DEVELOPMENT.md "Initial Setup" section (lines 22-28) describes this step.

Step 2: Run the Bootstrap with just setup

Execute the one-time bootstrap command that automates the entire build process:

just setup

The just setup target—defined in the root justfile—performs these actions as documented in DEVELOPMENT.md (lines 30-36):

• Installs missing system dependencies
• Initializes the vendor/libkrunfw submodule
• Builds the guest agent (agentd)
• Compiles the libkrun firmware library
• Builds the msb CLI from crates/cli/
• Installs binaries to ~/.microsandbox/ (Unix) or %USERPROFILE%\.microsandbox\ (Windows)
• Installs pre-commit hooks

This bootstrap handles Rust toolchain installation if missing, so no prior Rust setup is required.

Step 3: Configure Your PATH for Microsandbox

After bootstrap completes, add the binary directory to your shell profile. In DEVELOPMENT.md (lines 41-45), this step is marked critical for Unix systems:

# Add to ~/.bashrc, ~/.zshrc, or equivalent

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

Reload your shell or source the profile:

source ~/.bashrc  # or ~/.zshrc

Windows installs typically prepend the path automatically during bootstrap.

Step 4: Verify Your Microsandbox Installation

Confirm the CLI is accessible:

msb --version

This should output the installed version. Per DEVELOPMENT.md (lines 49-53), successful verification means all components—runtime, agent, and CLI—built correctly.

Run a quick functional test:

msb run debian -- echo "Hello from microsandbox!"

This launches a Debian microVM and executes the echo command inside hardware isolation.

Understanding the Microsandbox Architecture

The local setup builds several interconnected components:

Core Runtime Components

• crates/runtime/src/lib.rs – MicroVM launcher using libkrun
• vendor/libkrunfw/ – Firmware library submodule for KVM/WHP virtualization
• crates/protocol/ – Wire protocol between host CLI and guest agent
• crates/cli/src/main.rs – Entry point for the msb binary
• packages/agent-client/ – Client library consumed by all SDKs

SDK Layer

After local setup, you can develop against Microsandbox using:

SDK	Location	Crate/Package Name
Rust	sdk/rust/	microsandbox
Python	sdk/python/	microsandbox
TypeScript/Node	sdk/node-ts/	@microsandbox/sdk
Go	sdk/go/	github.com/superradcompany/microsandbox/sdk/go

The Rust SDK surface is defined in sdk/rust/src/lib.rs, exposing the Sandbox builder pattern that mirrors CLI capabilities.

Rebuilding After Source Changes

During active development, use the build-install loop documented in DEVELOPMENT.md (lines 55-62):

just build && just install

This recompiles modified crates and reinstalls binaries to ~/.microsandbox/bin/ without repeating the full bootstrap.

Troubleshooting Common Microsandbox Setup Issues

Symptom	Resolution
msb: command not found	Verify PATH includes ~/.microsandbox/bin and shell was reloaded
just setup fails on libkrunfw	Ensure git submodules initialized: git submodule update --init
KVM errors on Linux	Check /dev/kvm exists and user has permissions: sudo usermod -aG kvm $USER
Windows WHP errors	Enable Windows Hypervisor Platform in "Turn Windows features on or off"

Summary

• Microsandbox local setup requires three phases: host preparation, repository bootstrap with just setup, and PATH configuration
• The bootstrap builds agentd, libkrunfw, and msb into ~/.microsandbox/bin/
• Key source files include crates/cli/src/main.rs for the CLI and sdk/rust/src/lib.rs for the Rust SDK
• Verify installation with msb --version and test with msb run debian -- echo "test"
• Rebuild changes using just build && just install without full re-bootstrap

Frequently Asked Questions

What operating systems support Microsandbox local setup?

Microsandbox runs on macOS 11+, Linux with KVM support, and Windows with Windows Hypervisor Platform. Each platform uses the same just setup bootstrap process, with the build system automatically selecting the appropriate virtualization backend. Linux requires /dev/kvm accessibility; Windows requires WHP feature enablement.

Do I need Rust installed before running just setup?

No. The just setup command installs Rust via rustup if not present on the system. You only need just, git, and pre-commit as prerequisites. The bootstrap script handles all toolchain dependencies including the correct Rust version specified in the repository's rust-toolchain.toml.

Where are Microsandbox binaries installed after setup?

Binaries install to ~/.microsandbox/bin/ on Unix systems and %USERPROFILE%\.microsandbox\bin\ on Windows. This location keeps system directories clean while allowing per-user version management. The installation path is printed during bootstrap completion, and you must manually add it to your shell PATH on Unix systems.

How do I use Microsandbox in my own Rust project after local setup?

Add the local SDK path or published crate to your Cargo.toml: microsandbox = "0.x" or microsandbox = { path = "../microsandbox/sdk/rust" }. The Sandbox builder in sdk/rust/src/lib.rs provides async methods for creating microVMs, executing commands, and managing sandbox lifecycle. All SDKs share the same packages/agent-client library for consistent behavior.

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