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 tiny virtual machines.
• Fork & Snapshot: Fork live sandboxes¹. Save running sandbox state and restore later.
• Cross Platform: Runs on Linux, macOS, and Windows.
• 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.

  Getting Started

  Install the CLI

sh curl -fsSL https://install.microsandbox.dev | sh # 🍎 macOS / 🐧 Linux

powershell irm https://install.microsandbox.dev/windows | iex # 🪟 Windows

 We also support other package managers →

sh brew install superradcompany/tap/microsandbox

sh npm i -g microsandbox

sh uv tool install microsandbox

sh cargo install microsandbox

Start creating sandboxes once installed:

sh msb run ubuntu

  Install the SDK

sh npm i microsandbox # 🟦 TypeScript

sh cargo add microsandbox # 🦀 Rust

sh uv add microsandbox # 🐍 Python

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

Requirements:

• macOS: Apple Silicon.
• Linux: KVM enabled.
• Windows: WHP enabled.

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

  CLI

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

  Run a Command

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

  Named Sandboxes

```sh

Create and start a named sandbox

msb create --name app python ```

```sh

Execute commands

msb exec app -- python -c "import this" msb exec app -- curl https://example.com ```

```sh

Fork a running sandbox.

msb fork app --name app2 msb exec app2 -- python -c "print('An independent copy!')" ```

```sh

Snapshot now, resume later.

msb snap create --sandbox app --full -o snapshot.msb msb snap restore snapshot.msb --name app3 ```

Forking duplicates live execution. Restoring starts from saved state; add --cow-mem to share unchanged memory from a full snapshot. Snapshot generations describe progression, while branches describe distinct paths through snapshot history. The old --forked restore flag remains a deprecated alias. See forking and snapshots.

```sh

Lifecycle

msb stop app msb start app msb rm app ```

  Image Management

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

  Configuration File

sh msb run --conf sandbox.yaml -- octocat

```yaml

sandbox.yaml

image: python:3.12 memory: 64M network: allow: - api.github.com scripts: octocat: | python - <<'PY' import urllib.request

request = urllib.request.Request(
    "https://api.github.com/octocat",
    headers={"User-Agent": "microsandbox-example"},
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode())
PY

```

  Status & Inspection

sh msb ls # List all sandboxes msb ps app # Show sandbox status msb inspect app # Detailed sandbox info msb metrics 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.

  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

```typescript 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()); ```

 Rust Example →

```rust use microsandbox::Sandbox;

[tokio::main]

async fn main() -> Result<(), Box> { 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(())

} ```

 Python Example →

```python 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()) ```

 Ruby Example →

```ruby require "microsandbox"

sandbox = Microsandbox::Sandbox.create( "my-sandbox", image: "python", cpus: 1, memory: 512, network: { allowed_hosts: ["api.openai.com"], allowed_ports: [443] }, secrets: [{ env: "OPENAI_API_KEY", value: ENV.fetch("OPENAI_API_KEY"), allowed_host: "api.openai.com" }] )

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

sandbox.stop ```

See the Ruby SDK guide for installation, lifecycle, networking, and backend details.

 Go Example →

```go 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.EnsureRuntime(ctx, microsandbox.RuntimeConfig{}, microsandbox.InstallOptions{}); 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())

} ```

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.

  Guides

Practical ways to put microsandbox to work:

• Docker in a Sandbox: Run Docker without touching the host daemon.
• OpenCode: Give a coding agent an isolated project workspace.
• Browser Use: Run an AI browser agent inside a microVM.
• Playwright: Run headless browser jobs inside a microVM.
• Warm Workers: Snapshot a toolchain and launch clean workers.
• Migration Rehearsal: Test a database migration, then restore the baseline.
• GitHub Actions Runner: Run each self-hosted job in a disposable microVM.
• Documents to PDF: Convert untrusted documents in a fresh offline worker.

  Community Showcase

  Agent frameworks & runtimes

• Eve by Vercel: Agent framework that ships microsandbox as a sandbox backend.
• Agentic Coding Quickstart by U.S. GSA: From zero to a running AI coding agent with USAi in minutes.
• Condukt and Once by Tuist: Elixir agentic engine, and cacheable actions that run in fresh sandboxes.
• langchain-microsandbox by kenwoodjw: Microsandbox integration for LangChain Deep Agents.
• Smithers by Smithers: Agent workflows with full observability, rewind, fork, and replay.
• AgentConnect: Bring multiple AI agents into your team's chats, issues, and pull requests.
• wrap by Tobi Lütke: Run coding agents and project commands in isolated Arch Linux microVMs.
• Agent VM by Wiren Board: Run AI agents in safe VMs scoped to a local folder.

  Tools & infrastructure

• h5i by h5i: Secure, auditable browser for AI agents, written in pure Rust.
• Devsy by Devsy: Deploy devcontainers onto any cloud, Kubernetes cluster, or Docker host.
• OpenWork by Different AI: Open-source Claude Cowork alternative with a microsandbox image.

  Guides & showcases

• Awesome Microsandbox by ya-luotao: Curated list of SDKs, integrations, tools, and resources.
• msb-omarchy by ya-luotao: Omarchy desktop with graphics inside a microVM on Apple Silicon.

  AI Agents

  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.

sh 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.

```sh

Claude Code

claude mcp add --transport stdio microsandbox -- npx -y microsandbox-mcp ```

  Documentation

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

  Contributing

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

  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