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

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

Clone the Repository

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

The repository uses a Cargo workspace structure defined in the top-level Cargo.toml, which enumerates all workspace crates including microsandbox-utils, microsandbox-protocol, microsandbox-runtime, and the SDK crate under sdk/rust/.

Source: Cargo.toml

Run the One-Time Setup

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
5. Installs binaries to ~/.microsandbox/bin/ (Unix) or %USERPROFILE%\.microsandbox\bin\ (Windows)
6. Configures pre-commit hooks if available

Source: DEVELOPMENT.md – Initial Setup

Add Binaries to Your PATH

# Bash / Zsh

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

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

Verify the Installation

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:

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

just build release

Source: DEVELOPMENT.md – Build & Install Loop

Run the Test Suite

Execute workspace tests with standard Cargo commands:

cargo test --workspace          # Full test run

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

Source: DEVELOPMENT.md – Testing

Code Quality Checks

Run linting and formatting manually:

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

Rust Architecture Overview

Understanding the crate structure helps navigate the codebase:

Component	Location	Entry Point
CLI (msb)	crates/cli/	crates/cli/lib/lib.rs
Guest Agent (agentd)	crates/agentd/	crates/agentd/lib/lib.rs
Shared Types	packages/microsandbox-types/rust/	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, the musl-linked agentd guest agent from 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.

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