microsandbox-banner-xl-dark
microsandbox-banner-xl

——   easy, fast, local microVMs for untrusted workloads   ——


GitHub release Discord Apache 2.0 License

**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).
## rocket-darkrocket  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 **macOS**: Apple Silicon. > - Linux **Linux**: KVM enabled. > - Windows **Windows**: Windows 10+ (x64 or ARM64) with WHP enabled. > > **Warning**: Microsandbox is still **beta software**. Expect breaking changes, missing features, and rough edges.
## sdk-darksdk  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()) > ``` > >
>
>  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](./sdk/ruby/README.md) for installation, lifecycle, > networking, and backend details. > >
> >
>  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.
SDK Docs
## cli-darkcli  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 > ``` ####   Configuration File > ```sh > msb run --conf sandbox.yaml -- octocat > ``` > > ```yaml > # sandbox.yaml > image: python:3.12 > 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 > ``` ####   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.
CLI Docs
## beaker-darkbeaker  Examples Practical ways to put microsandbox to work: > • **[Docker in a Sandbox](https://docs.microsandbox.dev/examples/docker/docker-in-sandbox)**: Run Docker without touching the host daemon.
> • **[OpenCode](https://docs.microsandbox.dev/examples/agents/opencode)**: Give a coding agent an isolated project workspace.
> • **[Playwright](https://docs.microsandbox.dev/examples/browser-automation/playwright)**: Run headless browser jobs inside a microVM.
> • **[Warm Workers](https://docs.microsandbox.dev/examples/sandboxing/warm-workers)**: Snapshot a toolchain and launch clean workers.
> • **[Migration Rehearsal](https://docs.microsandbox.dev/examples/data/migration-rehearsal)**: Test a database migration, then restore the baseline.
> • **[GitHub Actions Runner](https://docs.microsandbox.dev/examples/ci-cd/github-actions-runner)**: Run each self-hosted job in a disposable microVM.
> • **[Documents to PDF](https://docs.microsandbox.dev/examples/file-processing/libreoffice-pdf)**: Convert untrusted documents in a fresh offline worker.
Browse Examples
## agents-darkagents  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 > ```
## people-darkpeople  Projects using microsandbox > ⏵ **[Eve by Vercel](https://eve.dev/docs/sandbox#microsandbox)**
> ⏵ **[GSA TTS Agentic Coding Quickstart](https://github.com/GSA-TTS/agentic-coding-quickstart)**
> ⏵ **[agent-compose by Chaitin](https://github.com/chaitin/agent-compose)**
> ⏵ **[Condukt](https://github.com/tuist/condukt) and [Once](https://github.com/tuist/once) by Tuist**
> ⏵ **[h5i](https://github.com/h5i-dev/h5i)**
> ⏵ **[Smithers](https://github.com/smithersai/smithers)**
> ⏵ **[sandboxed-lit by LlamaIndex](https://github.com/run-llama/sandboxed-lit)**
> ⏵ **[Agentic Usability by PSPDFKit Labs](https://github.com/PSPDFKit-labs/agentic-usability)**
> ⏵ **[Agent VM by Wiren Board](https://github.com/wirenboard/agent-vm)**
> ⏵ **[Devsy](https://github.com/devsy-org/devsy)** > Built something with microsandbox? [Share it with us on Discord](https://discord.gg/T95Y3XnEAK). We’d love to feature it here.
## docs-darkdocs  Documentation For guides, API references, and examples, visit the [microsandbox documentation](https://docs.microsandbox.dev).
## contributing-darkcontributing  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-darklicense  License This project is licensed under the [Apache License 2.0](./LICENSE).
## acknowledgements-darkacknowledgements  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)
Backed by Y Combinator


[^boot-time]: Boot time refers to guest boot on an M1 machine.