README

</a>

</a>

Microsandbox runs untrusted workloads inside fast, local microVMs: AI agents, user code, plugins, CI jobs, dev environments, scrapers, and automation.

• Hardware Isolation: Hardware-level isolation with microVM technology.
• OCI Compatible: Runs standard container images from Docker Hub, GHCR, or any OCI registry.
• Docker-Like Workflows: Familiar image, command, shell, and volume workflows.
• Instant Startup: Average boot times under 100 milliseconds.
• Embeddable: Spawn VMs right within your code. No setup server. No long-running daemon.
• Secrets That Can't Leak: Unexploitable secret keys that never enter the VM.
• Long-Running: Sandboxes can run in detached mode. Great for long-lived sessions.
• Agent-Ready: Your agents can create their own sandboxes with our Agent Skills and MCP server.

<a href="./#gh-dark-mode-only" target="_blank"></a><a href="./#gh-light-mode-only" target="_blank"></a>  Getting Started

  Install the SDK

shCopy

cargo add microsandbox                                   # 🦀 Rust

shCopy

uv add microsandbox                                      # 🐍 Python

shCopy

npm i microsandbox                                       # 🟦 TypeScript

shCopy

go get github.com/superradcompany/microsandbox/sdk/go    # 🐹 Go

  Install the CLI (Optional)

Boot a microVM in a single command:

shCopy

npx microsandbox run debian

Or install the msb command globally:

shCopy

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

<details> <summary><em>&nbsp;We also support other package managers →</em></summary>

shCopy

brew install superradcompany/tap/microsandbox

shCopy

npm i -g microsandbox

shCopy

uv tool install microsandbox

shCopy

cargo install microsandbox

</details>

Then you can run msb directly:

shCopy

msb run debian

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

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

<a href="./#gh-dark-mode-only" target="_blank"></a><a href="./#gh-light-mode-only" target="_blank"></a>  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

rsCopy

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
        .exec("python", ["-c", "print('Hello from a microVM!')"])
        .await?;

    println!("{}", output.stdout()?);

    sandbox.stop().await?;

    Ok(())
}

<details> <summary><b>&nbsp;Python Example →</b></summary>

pythonCopy

import asyncio
from microsandbox import Sandbox

async def main():
    sandbox = await Sandbox.create(
        "my-sandbox",
        image="python",
        cpus=1,
        memory=512,
    )

    output = await sandbox.exec("python", ["-c", "print('Hello from a microVM!')"])

    print(output.stdout_text)

    await sandbox.stop()

asyncio.run(main())

</details> <details> <summary><b>&nbsp;TypeScript Example →</b></summary>

typescriptCopy

import { Sandbox } from "microsandbox";

await using sandbox = await Sandbox.builder("my-sandbox")
  .image("python")
  .cpus(1)
  .memory(512)
  .create();

const output = await sandbox.exec("python", [
  "-c",
  "print('Hello from a microVM!')",
]);

console.log(output.stdout());

</details> <details> <summary><b>&nbsp;Go Example →</b></summary>

goCopy

package main

import (
    "context"
    "fmt"
    "log"

    microsandbox "github.com/superradcompany/microsandbox/sdk/go"
)

func main() {
    ctx := context.Background()

    // Downloads the microsandbox runtime to ~/.microsandbox/ on first run.
    if err := microsandbox.EnsureInstalled(ctx); err != nil {
        log.Fatal(err)
    }

    sandbox, err := microsandbox.CreateSandbox(ctx, "my-sandbox",
        microsandbox.WithImage("python"),
        microsandbox.WithCPUs(1),
        microsandbox.WithMemory(512),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer sandbox.Stop(ctx)

    output, err := sandbox.Exec(ctx, "python", []string{"-c", "print('Hello from a microVM!')"})
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(output.Stdout())
}

</details>

The first call to create() pulls the image if it isn't cached locally, so it may take longer depending on your connection. Subsequent runs reuse the cache.

<a href="https://docs.microsandbox.dev/sdk/overview"></a>

<a href="./#gh-dark-mode-only" target="_blank"></a><a href="./#gh-light-mode-only" target="_blank"></a>  CLI

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

  Run a Command

shCopy

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

  Named Sandboxes

shCopy

# Create and start a named sandbox
msb create --name my-app python

shCopy

# Execute commands
msb exec my-app -- python -c "import this"
msb exec my-app -- curl https://example.com

shCopy

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

  Image Management

shCopy

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

  Install & Uninstall Sandboxes

shCopy

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

  Status & Inspection

shCopy

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 --help for quick help menu.

· msb --tree for complete command hierarchy and descriptions.

· msb <command> --tree for a specific command tree.

<a href="https://docs.microsandbox.dev/cli/overview"></a>

<a href="./#gh-dark-mode-only" target="_blank"></a><a href="./#gh-light-mode-only" target="_blank"></a>  AI Agents

AI agents are a natural fit for microsandbox. They run tools, inspect files, install packages, call APIs, and execute generated code, often with more ambient access than they should have.

microsandbox gives those actions a dedicated microVM instead of your host process. Agents can still work normally, but their filesystem, network, lifecycle, and secrets are controlled by the sandbox boundary.

  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.

shCopy

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.

shCopy

# Claude Code
claude mcp add --transport stdio microsandbox -- npx -y microsandbox-mcp

<a href="./#gh-dark-mode-only" target="_blank"></a><a href="./#gh-light-mode-only" target="_blank"></a>  Documentation

For guides, API references, and examples, visit the microsandbox documentation.

<a href="./#gh-dark-mode-only" target="_blank"></a><a href="./#gh-light-mode-only" target="_blank"></a>  Contributing

Interested in contributing to microsandbox? Check out our CONTRIBUTING.md for guidelines and DEVELOPMENT.md for build, test, and release instructions.

<a href="./#gh-dark-mode-only" target="_blank"></a><a href="./#gh-light-mode-only" target="_blank"></a>  License

This project is licensed under the Apache License 2.0.

<a href="./#gh-dark-mode-only" target="_blank"></a><a href="./#gh-light-mode-only" target="_blank"></a>  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