microsandbox

 Microsandbox

Microsandbox makes it easy to run untrusted workloads within a hardware-isolated and fast startup execution environment.

Running untrusted code securely is hard. Traditional solutions—containers, VMs, or cloud sandboxes—each trade off speed, isolation, or control. Microsandbox aims to give the best of all worlds.

[!WARNING] Microsandbox is still experimental software. Expect breaking changes, missing features, and rough edges.

  Key Features

• Strong Isolation: Hardware-level VM isolation with microVMs.
• Instant Startup: Boot times under 200 ms.
• OCI Compatible: Runs standard container images.
• Self-Hosted: Deploy within your infrastructure with autonomy.
• AI-Ready: Integrates seamlessly with agent and AI workflows via MCP.

Microsandbox is designed to be the execution backbone of the agentic web—fast, secure, and flexible.

  Demo

With Claude

  Getting Started

PREREQUISITE

  1. Download microsandbox

curl -sSL https://get.microsandbox.dev | sh

  2. Start the server

msb server start --dev

  3. Pull the environment image [Optional]

msb pull microsandbox/python

BASICS

microsandbox ships with a bunch of flexible commands to make it easy to manage and access sandboxes which are highlighted below

  Temporary Sandbox

For experimentation or one-off tasks, temporary sandboxes provide a clean environment that leaves no trace on exit. For example, create a sandbox based on the microsandbox/python image by running:

msx python # or `msb exe --image python`

  System-wide Sandboxes

This provides the option to run long-lived sandboxes which are automatically setup as a system-wide executable. This also makes frequently used sandboxes incredibly convenient to access — no need to navigate to specific directories or remember complex commands.

msi python py-data # or `msb install --image alpine py-data`

py-data # From any directory, run the sandbox

If no alias is specified, the image name is used as the default. In the example above, this will be python. If a sandbox with similar name exists, an error will be returned.

[!TIP]

Run msb <subcommand> --help to see all the options available for a subcommand.

For example, msb add --help.

  SDK  ^BETA

  1. Install the SDK

See open issues for future language support.

  2. Execute the Code

The first run pulls the environment image, so it’ll take a bit longer. You can pre-pull an image it to make runs instant. For more information on how to use the SDK, refer to the SDK Readme.

Python

import asyncio
from microsandbox import PythonSandbox

async def main():
    async with PythonSandbox.create(name="test") as sb:
        exec = await sb.run("name = 'Python'")
        exec = await sb.run("print(f'Hello {name}!')")

    print(await exec.output()) # prints Hello Python!

asyncio.run(main())

JavaScript

import { NodeSandbox } from "microsandbox";

async function main() {
  const sb = await NodeSandbox.create({ name: "test" });

  try {
    let exec = await sb.run("var name = 'JavaScript'");
    exec = await sb.run("console.log(`Hello ${name}!`)");

    console.log(await exec.output()); // prints Hello JavaScript!
  } finally {
    await sb.stop();
  }
}

main().catch(console.error);

Rust

use microsandbox::{SandboxOptions, PythonSandbox};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = SandboxOptions::builder().name("test").build();
    let mut sb = PythonSandbox::create(options).await?;

    let exec = sb.run(r#"name = "Python""#).await?;
    let exec = sb.run(r#"print(f"Hello {name}!")"#).await?;

    println!("{}", exec.output().await?); // prints Hello Python!

    sb.stop().await?;

    Ok(())
}

  Project Sandbox  ^BETA

Beyond the SDK, microsandbox supports project-based development with the familiar package-manager workflow devs are used to. Think of it like npm or cargo, but for sandboxes!

QUICK DEMO

SETUP GUIDE

  1. Create a Sandbox Project

Each sandbox project needs a file, Sandboxfile at the root of the project directory, which serves as the configuration manifest for your sandbox environments. To initialize one, run:

msb init

  2. Add a Sandbox to the Project

Proceed to register a new python sandbox named app in your Sandboxfile.

msb add app \
    --image python \
    --cpus 1 \
    --memory 1024 \
    --start 'python -c "print(\"hello\")"'

  3. Inspect Sandboxfile

The newly created sandbox, app should be registered in your Sandboxfile. If there was a pre-existing Sandboxfile, it'd be appended to it. It should be similar to this:

sandboxes:
  app:
    image: python
    memory: 1024
    cpus: 1
    scripts:
      start: python -c "print(\"hello\")"

  4. Running a Project-Defined Sandbox

Next is to run a sandbox defined in your project. This would execute the default start script of your sandbox. For more control, you can directly specify which script to run e.g. msr app~start.

msr app # or `msb run --sandbox app`

When running project sandboxes, all file changes and installations made inside the sandbox are automatically persisted to the ./menv directory. This means you can stop and restart your sandbox any time without losing your work. Your development environment will be exactly as you left it.

  Uninstall

To uninstall microsandbox, run: msb self uninstall. Use the --force flag. This removes the $HOME/.microsandbox directory and all its content, effectively cleaning up all cached microsandbox data such as images, layers, and databases.

Refer to the maintenance docs for other types of cleanups.

  Use Cases

Wondering how you can use microsandbox in your next project, see our sample use cases.

  Contributing

Interested in contributing to microsandbox? Check out our Development Guide for instructions on setting up your development environment, building the project, running tests, and creating releases. For contribution guidelines, please refer to CONTRIBUTING.md.

  License

This project is licensed under the Apache License 2.0.

  Ackowledgements

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: The lightweight virtualization library that powers our secure microVM isolation