โโ easy, fast, local microVMs for untrusted workloads โโ
**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](https://github.com/superradcompany/skills) and [MCP server](https://github.com/superradcompany/microsandbox-mcp).
## 
Getting Started
#### 
Install the SDK
> ```sh
> cargo add microsandbox # ๐ฆ Rust
> ```
>
> ```sh
> uv add microsandbox # ๐ Python
> ```
>
> ```sh
> npm i microsandbox # ๐ฆ TypeScript
> ```
>
> ```sh
> go get github.com/superradcompany/microsandbox/sdk/go # ๐น Go
> ```
#### 
Install the CLI
> Boot a microVM in a single command:
>
> ```sh
> npx microsandbox run debian
> ```
>
> ##
>
> Or install the `msb` command globally:
>
> ```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
> ```
>
>
>
> ##
>
> Then you can run `msb` directly:
>
> ```sh
> 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
> ```rs
> 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())
> ```
>
>
>
>
> TypeScript Example โ
>
> ```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());
> ```
>
>
>
>
> 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.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
> ```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
> # 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
> ```
#### Install & Uninstall Sandboxes
> ```sh
> msb install ubuntu # Install ubuntu sandbox as 'ubuntu' command
> ubuntu # Opens Ubuntu in a microVM
> msb uninstall ubuntu # Uninstall the ubuntu sandbox
> ```
#### 
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 --tree` for a specific command tree.
## 
AI Agents
#### 
Agent Skills
> Teach any AI coding agent how to use microsandbox by installing the [Agent Skills](https://github.com/superradcompany/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](https://github.com/superradcompany/microsandbox-mcp). 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](https://docs.microsandbox.dev).
## 
Contributing
Interested in contributing to `microsandbox`? Check out our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines and [DEVELOPMENT.md](./DEVELOPMENT.md) for build, test, and release instructions.
## 
License
This project is licensed under the [Apache License 2.0](./LICENSE).
## 
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](https://github.com/containers/libkrun) and [smoltcp](https://github.com/smoltcp-rs/smoltcp)
[^boot-time]: Boot time refers to guest boot on an M1 machine.
