—— every agent deserves its own computer ——

Microsandbox

Microsandbox spins up lightweight VMs in milliseconds from our SDKs. Runs locally on your machine. No server to set up. No lingering daemon. It is all embedded and rootless!

Today, AI agents operate with whatever permissions you give them, and that's usually too much. They can see API keys in the environment, reach the network without restriction, and a single prompt injection can execute destructive commands on your host. Containers help, but they share the host kernel, making namespace escapes a known risk. Microsandbox solves this with hardware-level VM isolation that boots in milliseconds.

Hardware Isolation: Hypervisor-level isolation with microVM technology.
Instant Startup: Boot times under 100 milliseconds.
Embeddable: Spawn VMs right within your code. No setup server. No long-running daemon.
Secrets That Can't Leak: Secret keys never enter the VM. The guest VM only sees placeholders.
Programmable Filesystem & Network Stack: Customizable filesystems and network operations.
OCI Compatible: Runs standard container images from Docker Hub, GHCR, or any OCI registry.
Long-Running: Sandboxes can run in detached mode. They are great for long-lived sessions.
Agent-Ready: Your agents can create their own sandboxes with our Agent Skills and MCP server.

Microsandbox is still beta software. Expect breaking changes, missing features, and rough edges.

Getting Started

Install the SDK

cargo add microsandbox    # Rust

npm i microsandbox        # TypeScript

Install the CLI

The msb CLI is useful for managing images, volumes, and sandboxes from the terminal:

curl -fsSL https://install.microsandbox.dev | sh

Requirements: Linux with KVM enabled, or macOS with Apple Silicon.

SDK

The SDK lets you create and control sandboxes directly from your application. Sandbox::builder("...").create() boots a microVM as a child process. No infrastructure required.

Run Code in a Sandbox

use microsandbox::Sandbox;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sandbox = Sandbox::builder("my-sandbox")
        .image("python")
        .cpus(1)
        .memory(512)
        .create()
        .await?;

    let output = sandbox.shell("print('Hello from a microVM!')").await?;
    println!("{}", output.stdout()?);

    sandbox.stop_and_wait().await?;
    Ok(())
}

Behind the scenes, create() pulls the image (if not cached), assembles the filesystem, boots a microVM. All in under a second.

Secrets That Never Enter the VM

Secrets are injected via placeholder substitution. The guest environment only ever sees a random placeholder. The real value is swapped in at the network level.

let sandbox = Sandbox::builder("api-client")
    .image("python")
    .secret_env("OPENAI_API_KEY", "sk-real-secret-123", "api.openai.com")
    .create()
    .await?;

// Inside the VM: $OPENAI_API_KEY = "$MSB_OPENAI_API_KEY" (placeholder)
// Requests to api.openai.com: placeholder is replaced with the real key
// Requests to any other host: placeholder stays, secret never leaks

Network Policy

Control exactly what the sandbox can reach. The in-process networking stack enforces policy at the IP, DNS, and HTTP level. There's no host network to bridge to, so guests can't bypass the filter.
use microsandbox::{NetworkPolicy, Sandbox};

let sandbox = Sandbox::builder("restricted")
    .image("alpine")
    .network(|n| {
        n.policy(NetworkPolicy::public_only())  // blocks private/loopback
         .block_domain_suffix(".evil.com")       // DNS-level blocking
    })
    .create()
    .await?;
Three built-in policies: NetworkPolicy::public_only() (default, blocks private IPs), NetworkPolicy::allow_all(), and NetworkPolicy::none() (fully airgapped).

Port Publishing

Expose guest services on host ports:

let sandbox = Sandbox::builder("web-server")
    .image("alpine")
    .port(8080, 80)  // host:8080 → guest:80
    .create()
    .await?;

Scripts & Patches

let sandbox = Sandbox::builder("worker")
    .image("ubuntu")
    .script("setup", "#!/bin/bash\napt-get update && apt-get install -y python3 curl")
    .script("start", "#!/bin/bash\nexec python3 /app/main.py")
    .create()
    .await?;

sandbox.shell("setup").await?;
let output = sandbox.shell("start").await?;

Patches modify the filesystem before the VM boots. Inject config files, create directories, append to existing files:

let sandbox = Sandbox::builder("configured")
    .image("alpine")
    .patch(|p| {
        p.text("/etc/app.conf", "key=value\n", None, false)
         .mkdir("/app", Some(0o755))
         .append("/etc/hosts", "127.0.0.1 myapp.local\n")
    })
    .create()
    .await?;

Flexible Rootfs Sources

Boot from an OCI image, a local directory, or a disk image:

// OCI image (default)
Sandbox::builder("oci").image("python")

// Local directory
Sandbox::builder("bind").image("./my-rootfs")

// QCOW2 disk image
Sandbox::builder("block").image_with(|img| img.disk("./disk.qcow2").fstype("ext4"))

Guest Filesystem Access

Read and write files inside the running sandbox from the host side:

// Write a file into the sandbox.
sandbox.fs().write("/tmp/input.txt", b"some data").await?;

// Read a file from the sandbox.
let content = sandbox.fs().read_to_string("/tmp/output.txt").await?;

// List directory contents.
let entries = sandbox.fs().list("/tmp").await?;

Streaming Execution

For long-running commands, stream stdout/stderr events in real time:

use microsandbox::ExecEvent;

let mut handle = sandbox.shell_stream("python train.py").await?;

while let Some(event) = handle.recv().await {
    match event {
        ExecEvent::Stdout(data) => print!("{}", String::from_utf8_lossy(&data)),
        ExecEvent::Stderr(data) => eprint!("{}", String::from_utf8_lossy(&data)),
        ExecEvent::Exited { code } => println!("Process exited: {code}"),
        _ => {}
    }
}

CLI

The msb CLI provides a complete interface for managing sandboxes, images, and volumes.

Run a Command

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

Named Sandboxes

# Create and run detached
msb run --name my-app -d python

# Execute commands
msb exec my-app -- pip install requests
msb exec my-app -- python3 main.py

# Interactive shell into a running sandbox
msb shell my-app

# Lifecycle
msb stop my-app
msb start my-app
msb rm my-app

Image Management

msb pull python           # Pull an image
msb image ls              # List cached images
msb image rm python       # Remove an image

Install & Uninstall Sandboxes

msb install ubuntu               # Install ubuntu sandbox as 'ubuntu' command
ubuntu                           # Opens Ubuntu in a microVM

msb install --name nodebox node  # Custom command name
msb install --tmp alpine         # Ephemeral: fresh sandbox every run
msb install --list               # List installed commands
msb uninstall nodebox            # Remove an installed command

Volume Management

msb volume create my-data      # Create a volume
msb volume ls                  # List volumes
msb volume rm my-data          # Remove a volume

Status & Inspection

msb ls                         # List all sandboxes
msb ps my-app                  # Show sandbox status
msb inspect my-app             # Detailed sandbox info
msb metrics my-app             # Live CPU/memory/network stats

[!TIP]

Run msb --tree to see all available commands and their options.

AI Agents

Give your AI agents the ability to create and manage their own sandboxes.

Agent Skills

Teach any AI coding agent how to use microsandbox by installing the Agent Skills. Works with Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and more.
npx skills add superradcompany/skills

MCP Server

Connect any MCP-compatible agent to microsandbox with the MCP server. Provides structured tool calls for sandbox lifecycle, command execution, filesystem access, volumes, and monitoring.
# Claude Code
claude mcp add --transport stdio microsandbox -- npx -y microsandbox-mcp

Contributing

Interested in contributing to microsandbox? Check out our Development Guide for instructions on setting up your development environment, building the project, running tests, and creating releases. For contribution guidelines, please refer to CONTRIBUTING.md.

License

This project is licensed under the Apache License 2.0.

Acknowledgements

Special thanks to all our contributors, testers, and community members who help make microsandbox better every day! We'd like to thank the following projects and communities that made microsandbox possible: libkrun and smoltcp

microsandbox