—— every agent deserves its own computer ——

GitHub release badge Discord badge Apache 2.0 License badge

Microsandbox spins up lightweight VMs in milliseconds from our SDKs. It runs locally on your machine. There is no server to set up, no lingering daemon, and everything is embedded and rootless. The core value proposition is a rapid, secure, and embeddable sandboxing experience that integrates directly into your development workflow.

• Hardware Isolation: Hardware-level isolation with microVM technology that keeps workloads separated at the strongest possible boundary, protecting both the host and the sandboxed code.
• Instant Startup: Average boot times under 100 milliseconds, so developers can iterate rapidly without waiting for virtual machines to come online.
• Embeddable: Spawn VMs directly inside your application code. There is no separate setup server and no long-running daemon to manage.
• Secrets That Can’t Leak: Unexploitable secret keys that never enter the VM, reducing the risk of key leakage and credential exposure.
• OCI Compatible: Runs standard container images from Docker Hub, GHCR, or any OCI registry, letting you reuse familiar images.
• Long-Running: Sandboxes can operate in detached mode, enabling long-lived sessions and processes that outlive short-lived tasks.
• Agent-Ready: Your AI agents can create and manage their own sandboxes using Agent Skills and the MCP server, enabling automated workflows and tool-use within sandboxed contexts.

1. Getting Started

• Getting Started

1. Install the SDK

   • Rust: Open your terminal and run the command
     • ```sh cargo add microsandbox ```
   • Python: Use your Python package manager
     • ```sh uv add microsandbox ```
   • TypeScript: Install via npm
     • ```sh npm i microsandbox ```
   • The SDKs provide a programmatic API to create, configure, and control sandboxes directly from your application. The primary pattern is to construct a sandbox, configure resources, and then boot it as a child process. The boot process is designed to be non-invasive: nothing external needs to be installed on the host beyond the SDK itself, and the sandbox runs in isolation without a persistent daemon on the host.

2. Install the CLI (Optional)

   • A single command can boot a microVM and run a task:
     • ```sh npx microsandbox run debian ```
   • Or install the msb command globally for convenience:
     • ```sh curl -fsSL https://install.microsandbox.dev | sh ```
     • Then:
     • ```sh msb run debian ```
   • The CLI provides a higher-level interface for operational tasks such as starting, stopping, inspecting, and scripting sandboxes. It complements the SDKs by offering an end-user focused workflow that requires minimal code to achieve common sandboxing scenarios.

3. Requirements

   • Microsandbox runs on Linux with KVM enabled or macOS on Apple Silicon. These requirements ensure the microVMs can be created with hardware-assisted virtualization for predictable performance and strong isolation.
   • Important caveat: Microsandbox is labeled as beta software. You should expect breaking changes, evolving features, and occasional rough edges as the project matures. The beta designation signals that you should plan for version updates and evolving APIs when integrating Microsandbox into your projects.

4. Visual and Documentation Cues

   • The project employs a wide range of visual affordances to communicate state and capability, including badges for releases, licenses, and integrations. These badges provide quick at-a-glance confidence about maturity, licensing, and community support.
   • The documentation is broadly accessible and linked through dedicated docs sites for the SDK, CLI, and developer guides, enabling a smooth learning curve for newcomers and a reference for advanced users alike.

5. SDK

• The SDK lets you create and control sandboxes directly from your application. A typical workflow is to construct a Sandbox, provide a configuration, and call create() to boot a microVM as a child process. No infrastructure, no external servers, just a self-contained sandbox that integrates with your program.

• Example patterns illustrate how to instantiate, configure, and run code inside a sandbox, and then to collect the results from the sandboxed process. The SDK emphasizes deterministic startup, controlled resource allocation, and clean teardown.

• Below is a representative sample for Rust, illustrating how you might build and execute code inside a sandbox:

  • ```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.stopandwait().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.stdouttext) await sandbox.stopand_wait()

    asyncio.run(main()) ```

• TypeScript example:

  • ```typescript import { Sandbox } from "microsandbox";

    const sandbox = await Sandbox.create({ name: "my-sandbox", image: "python", cpus: 1, memoryMib: 512, });

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

    await sandbox.stopAndWait(); ```

• First-create behavior: The initial create() call pulls the required image if it isn't cached locally. The image pull may incur network latency as the image is fetched. Subsequent runs reuse the cached image, enabling faster startup times after the initial download.

• SDK Docs: A dedicated SDK documentation resource is available, providing API references, usage patterns, and advanced configurations. This documentation is linked through an SDK overview page for quick access and onboarding.

• [SDK Docs badge and link] SDK Docs → https://docs.microsandbox.dev/sdk/overview

1. CLI

• The msb CLI provides a complete interface for managing sandboxes, images, and volumes. It is designed to complement the SDKs by offering a fast, scriptable, command-line experience for common operations.
• Run a Command
  • ```sh msb run python -- python3 -c "print('Hello from a microVM!')" ```
  • This example demonstrates running a simple command inside a sandboxed environment, leveraging the underlying microVM to isolate execution while providing a straightforward command interface.
• Named Sandboxes
  • Create and start a named sandbox to reuse across sessions or scripts:
  • ```sh msb create --name my-app python ```
  • Execute commands in a named sandbox:
  • ```sh msb exec my-app -- python -c "import this" msb exec my-app -- curl https://example.com ```
  • Lifecycle management commands:
  • ```sh msb stop my-app msb start my-app msb rm my-app ```
• Image Management
  • Pull an image to cache it locally:
  • ```sh msb pull python ```
  • List cached images:
  • ```sh msb image ls ```
  • Remove an image:
  • ```sh msb image rm python ```
• Install & Uninstall Sandboxes
  • Install a sandbox as a named command:
  • ```sh msb install ubuntu ubuntu ```
  • Uninstall the ubuntu sandbox:
  • ```sh msb uninstall ubuntu ```
• Status & Inspection
  • List sandboxes and check their status:
  • ```sh msb ls msb ps my-app msb inspect my-app msb metrics my-app ```
  • Live metrics give visibility into CPU, memory, and network usage for a running sandbox.
• Tip
  • Run msb --tree to see all available commands and their options, helping you discover features and automate workflows efficiently.
• [CLI Docs badge and link] CLI Docs → https://docs.microsandbox.dev/cli/overview

1. AI Agents and Automation

• Agents give AI systems the ability to create and manage their own sandboxes, enabling autonomous workflows and tool usage within a controlled environment.
• Agent Skills
  • Teach any AI coding agent how to use Microsandbox by installing the Agent Skills package:
  • \npx skills add superradcompany/skills
  • The skills layer enables agents (such as Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and others) to understand how to operate Microsandbox in a secure, auditable manner.
• MCP Server
  • Connect any MCP-compatible agent to Microsandbox via the MCP server. This integration provides structured tool calls for sandbox lifecycle management, command execution, filesystem access, volumes, and monitoring.
  • Example for Claude Code:
  • claude mcp add --transport stdio microsandbox -- npx -y microsandbox-mcp
• Together, Agent Skills and MCP empower automated, agent-driven sandbox orchestration, enabling complex workflows that blend AI-driven decisions with secure, sandboxed execution.

1. Documentation and Learning Resources

• Documentation Hub
  • A central microsandbox documentation site hosts guides, API references, and practical examples. This resource is designed to help developers of all levels onboard quickly and grow into advanced usage patterns.
  • Link: https://docs.microsandbox.dev
• SDK Documentation
  • Specific pages covering the Rust, Python, and TypeScript SDKs, including builder patterns, resource configuration, and sandbox lifecycle semantics.
• CLI Documentation
  • Guides for the msb CLI, common workflows, and command-specific options to help you script and automate sandbox management.

1. Contributing and Development

• Contribution Guide
  • If you are interested in contributing to microsandbox, start with the CONTRIBUTING.md file which outlines guidelines for contributing code, reporting issues, and proposing improvements.
• Development Guide
  • The DEVELOPMENT.md file provides build, test, and release instructions to help maintainers and contributors align on the project’s workflows and quality standards.
• Community and Process
  • Microsandbox welcomes community involvement. The project fosters collaboration through code reviews, issue discussions, and community-driven feature ideas.

1. License

• This project is licensed under the Apache License 2.0. The license text and details are available at the repository’s LICENSE file. The licensing model supports broad use, commercial and non-commercial alike, with standard open-source protections and obligations.

1. Acknowledgements

• Special thanks to all contributors, testers, and community members who help make microsandbox better every day. The project draws inspiration and foundational ideas from several related open-source projects and communities.
• Notable influences include libkrun (containers/libkrun) and smoltcp (smoltcp-rs/smoltcp), which helped shape the underlying concepts of lightweight, secure sandboxing and network stack behavior in constrained environments.

1. Backing and Community Support

• Backed by Y Combinator
  • The microsandbox project is backed by Y Combinator, a leading startup accelerator. This backing signals a strong commitment to innovation, user-centric design, and early-stage product viability.
  • Backed by Y Combinator badge

1. Visual Elements and Asset References

   • The project uses a rich set of visual elements to communicate state, capabilities, and status. These include header banners, release badges, license indicators, and a curated set of icons that depict features like security, speed, and embeddability.
   • Included illustrative assets from the input:
   • microsandbox banner assets for both dark and light mode
   • Various status and feature icons (shield-lock, zap, plug, lock, package, database, terminal)
   • Rocket icons for start-up guidance
   • SDK, CLI, and Agents badges
   • Documentation and contribution indicators
   • Acknowledgements, license, and backing badges
   • These assets, together with concise descriptive copy, equip the document with a visually cohesive narrative about Microsandbox's capabilities and ecosystem.

2. Summary and Vision

   • Microsandbox provides a compact, portable, and secure sandboxing solution that can be integrated directly into applications or driven through command-line interfaces. Its core strengths—hardware-level isolation, instant startup, embeddability, and secure secret handling—address common developer pain points when dealing with sandboxed workloads.
   • The OCI compatibility ensures compatibility with familiar container workflows, while the long-running capability enables persistent sessions for more complex development tasks. Agent-ready functionality further enables automation and AI-assisted workflows, making Microsandbox suitable for testing, experimentation, and production-like development environments.
   • By combining a developer-friendly SDK, a pragmatic CLI, and an extensible agent/MCP ecosystem, Microsandbox aims to become a foundational tool for building AI-powered, sandboxed software that runs locally with minimal friction and maximal security.

3. Images and Visual References (In Summary)

   • Banner graphics for branding (dark and light mode)
   • Feature icons highlighting hardware isolation, instant startup, embeddability, secret security, OCI compatibility, long-running sandboxes, and agent readiness
   • Action-oriented icons for Getting Started, SDK, CLI, and Documentation
   • Status and contribution indicators for licensing, docs, and acknowledgements

If you want, I can expand any of these sections with deeper explanations, additional practical examples, or a guided walkthrough for a particular language (Rust, Python, or TypeScript) showing how to initiate a sandbox, run a command, and tear down the sandbox in a real project scenario.