# How to Set Up a Rust Development Environment for Microsandbox: Complete Step-by-Step Guide

> Easily set up your Rust development environment for Microsandbox. Follow our step-by-step guide to install Rust, clone the repo, and build the CLI, guest agent, and kernel firmware.

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

---

**To set up a Rust development environment for Microsandbox, install Rust and `just`, clone the repository, and run `just setup` to build the CLI, guest agent, and kernel firmware library.**

Microsandbox is a multi-language project organized as a **Cargo workspace** that ships a Rust SDK, the `msb` CLI, and several internal crates for runtime, networking, and filesystem functionality. This guide walks you through configuring your system to build, test, and contribute to the Rust components of the project.

## Install System Prerequisites

Before building, ensure you have the following tools installed:

- **Rust** (via `rustup`): Install with `curl https://sh.rustup.rs -sSf | sh` or let `just setup` install it automatically
- **just** (task runner): `brew install just` (macOS), `sudo apt install just` (Linux), or Chocolatey (Windows)
- **Git**: Standard system package manager
- **pre-commit** (optional): `pip install pre-commit` or `brew install pre-commit` for lint hooks
- **Linux build backend**: Required for the guest `agentd` binary and `libkrunfw`—use Docker Desktop with Linux containers or WSL Ubuntu on Windows

> **Platform-specific notes:** On macOS, install Xcode command-line tools. On Windows, install Visual Studio Build Tools and the Windows SDK.

Source: [DEVELOPMENT.md – Prerequisites](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md#prerequisites)

## Clone the Repository

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

```

The repository uses a Cargo workspace structure defined in the top-level [`Cargo.toml`](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml), which enumerates all workspace crates including `microsandbox-utils`, `microsandbox-protocol`, `microsandbox-runtime`, and the SDK crate under `sdk/rust/`.

Source: [Cargo.toml](https://github.com/superradcompany/microsandbox/blob/main/Cargo.toml)

## Run the One-Time Setup

```bash
just setup

```

This command automates environment initialization:

1. Installs or verifies system dependencies (musl toolchain, Visual Studio tools, etc.)
2. Initializes Git submodules (`vendor/libkrunfw`)
3. Builds the Linux guest **agentd** binary and **libkrunfw** shared library
4. Compiles the `msb` CLI from [`crates/cli/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/lib/lib.rs)
5. Installs binaries to `~/.microsandbox/bin/` (Unix) or `%USERPROFILE%\.microsandbox\bin\` (Windows)
6. Configures pre-commit hooks if available

Source: [DEVELOPMENT.md – Initial Setup](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md#initial-setup)

## Add Binaries to Your PATH

```bash

# Bash / Zsh

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

```

On Windows, `just install` automatically prepends the path for the current user.

## Verify the Installation

```bash
msb --version

```

This confirms the CLI built correctly and is accessible from your shell.

## Development Workflow

### Incremental Builds

During active development, rebuild only what changed:

```bash
just build && just install      # Rebuild everything (debug) and reinstall

just build-msb                  # Rebuild only the CLI

just build-agentd               # Rebuild only the guest agent binary

just build-libkrunfw            # Rebuild only the kernel firmware library

```

### Release Builds

```bash
just build release

```

Source: [DEVELOPMENT.md – Build & Install Loop](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md#build--install-loop)

## Run the Test Suite

Execute workspace tests with standard Cargo commands:

```bash
cargo test --workspace          # Full test run

cargo test -p microsandbox-cli  # Test a single crate

```

Source: [DEVELOPMENT.md – Testing](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md#testing)

## Code Quality Checks

Run linting and formatting manually:

```bash
pre-commit run --all-files      # Runs cargo fmt, clippy, docs, etc.

cargo fmt --all                 # Code formatting

cargo clippy --workspace        # Linting

```

These checks are enforced in CI via the GitHub Actions workflow.

Source: [DEVELOPMENT.md – Code Quality](https://github.com/superradcompany/microsandbox/blob/main/DEVELOPMENT.md#code-quality)

## Rust Architecture Overview

Understanding the crate structure helps navigate the codebase:

| Component | Location | Entry Point |
|-----------|----------|-------------|
| **CLI** (`msb`) | `crates/cli/` | [`crates/cli/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/lib/lib.rs) |
| **Guest Agent** (`agentd`) | `crates/agentd/` | [`crates/agentd/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/lib/lib.rs) |
| **Shared Types** | `packages/microsandbox-types/rust/` | [`packages/microsandbox-types/rust/src/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/microsandbox-types/rust/src/lib.rs) |
| **SDK** | `sdk/rust/` | Published as `microsandbox` crate |

The `justfile` orchestrates cross-platform builds, ensuring correct toolchains and placing artifacts in `build/`.

## Summary

- **Install** Rust, `just`, and Git; optionally `pre-commit` for hooks
- **Clone** the repository and run `just setup` to build all components
- **Add** `~/.microsandbox/bin` to your PATH
- **Develop** with `just build`/`just install` and `cargo test` for verification
- **Quality-check** with `cargo clippy`, `cargo fmt`, or `pre-commit`

## Frequently Asked Questions

### Does Microsandbox require Docker or WSL?

Yes, if you're on macOS or Windows. The guest `agentd` binary and `libkrunfw` require a Linux build backend. Use Docker Desktop with Linux containers or WSL Ubuntu on Windows Server. Linux users can build natively.

### What does `just setup` actually build?

`just setup` compiles three key artifacts: the `msb` CLI from [`crates/cli/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/lib/lib.rs), the musl-linked `agentd` guest agent from [`crates/agentd/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/lib/lib.rs), and the `libkrunfw` kernel firmware library from the `vendor/libkrunfw` submodule.

### How do I run tests for a specific crate only?

Use Cargo's `-p` flag: `cargo test -p microsandbox-cli` runs only the CLI crate tests. This is faster than `cargo test --workspace` when working on isolated changes.

### Can I develop on Windows without WSL?

Partially. Native Windows builds work for some components, but the `agentd` binary and `libkrunfw` require Linux tooling. The recommended path is WSL Ubuntu or Docker Desktop with Linux containers.