# How to Set Up Microsandbox Locally: Complete Development Environment Guide

> Learn how to set up Microsandbox locally. Follow our guide to install prerequisites clone the repository and configure your development environment for seamless local testing.

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

---

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

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

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

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

```bash

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

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

```

Reload your shell or source the profile:

```bash
source ~/.bashrc  # or ~/.zshrc

```

Windows installs typically prepend the path automatically during bootstrap.

## Step 4: Verify Your Microsandbox Installation

Confirm the CLI is accessible:

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

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

```bash
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`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/src/main.rs) for the CLI and [`sdk/rust/src/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml): `microsandbox = "0.x"` or `microsandbox = { path = "../microsandbox/sdk/rust" }`. The `Sandbox` builder in [`sdk/rust/src/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/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.