microsandbox – superradcompany
🧱 简单、快速、本地优先的微虚拟机运行时与库
关键指标一览
主题标签
README 详细介绍
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.
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[^boot-time] 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 SDK
>
> cargo add microsandbox # 🦀 Rust
>>
>
> uv add microsandbox # 🐍 Python
>>
>
> npm i microsandbox # 🟦 TypeScript
>>
>
> go get github.com/superradcompany/microsandbox/sdk/go # 🐹 Go
>
Install the CLI
> Boot a microVM in a single command:
>
>
> npx microsandbox run debian
>>
> ##
>
> Or install the
msb command globally:>
>
> curl -fsSL https://install.microsandbox.dev | sh # 🍎 macOS / 🐧 Linux
>>
>
> irm https://install.microsandbox.dev/windows | iex # 🪟 Windows
>>
>
>
We also support other package managers →
>
> ##
>
>
> brew install superradcompany/tap/microsandbox
>>
>
> npm i -g microsandbox
>>
>
> uv tool install microsandbox
>>
>
> cargo install microsandbox
>>
>
>
> ##
>
> Then you can run
msb directly:>
>
> msb run debian
>##
> Requirements:
>
> - 
macOS: Apple Silicon.
> - 
Linux: KVM enabled.
> - 
Windows: WHP enabled.
>
> Warning: Microsandbox is still beta software. Expect breaking changes, missing features, and rough edges.
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
> .exec("python", ["-c", "print('Hello from a microVM!')"])
> .await?;
>
> println!("{}", output.stdout()?);
>
> sandbox.stop().await?;
>
> Ok(())
> }
>>
>
>
Python Example →
>
>
> 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())
>>
>
>
>
>
TypeScript Example →
>
>
> 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());
>>
>
>
>
>
Go Example →
>
>
> 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())
> }
>>
>
> 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.
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 start a named sandbox
> msb create --name app python
>>
>
> # Execute commands
> msb exec app -- python -c "import this"
> msb exec app -- curl https://example.com
>>
>
> # Lifecycle
> msb stop app
> msb start app
> msb rm 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 uninstall ubuntu # Uninstall the ubuntu sandbox
>
Status & Inspection
>
> 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 --tree for a specific command tree.
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.
>
>
> 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
>
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
[^boot-time]: Boot time refers to guest boot on an M1 machine.
