Microsandbox spins up lightweight VMs in milliseconds from our SDKs. Runs locally on your machine. No server to set up. No lingering daemon. It is all embedded and rootless!

Today, AI agents operate with whatever permissions you give them, and that's usually too much. They can see API keys in the environment, reach the network without restriction, and a single prompt injection can execute destructive commands on your host. Containers help, but they share the host kernel, making namespace escapes a known risk. Microsandbox solves this with hardware-level VM isolation that boots in milliseconds.

• Hardware Isolation: Hypervisor-level isolation with microVM technology.
• Instant Startup: Boot times under 100 milliseconds.
• Embeddable: Spawn VMs right within your code. No setup server. No long-running daemon.
• Secrets That Can't Leak: Secret keys never enter the VM. The guest VM only sees placeholders.
• Programmable Filesystem & Network Stack: Customizable filesystems and network operations.
• OCI Compatible: Runs standard container images from Docker Hub, GHCR, or any OCI registry.
• Long-Running: Sandboxes can run in detached mode. They are great for long-lived sessions.
• Agent-Ready: Your agents can create their own sandboxes with our [Agent Skills] and [MCP server].

Microsandbox is still beta software. Expect breaking changes, missing features, and rough edges.

npm i microsandbox        # TypeScript

cargo add microsandbox    # Rust

The msb CLI is useful for managing images, volumes, and sandboxes from the terminal:

curl -fsSL https://install.microsandbox.dev | sh

Requirements: Linux with KVM enabled, or macOS with Apple Silicon.

The SDK lets you create and control sandboxes directly from your application. Sandbox::builder(...) boots a microVM as a child process. No infrastructure required.

import { Sandbox } from "microsandbox";

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

const output = await sandbox.shell("print('Hello from a microVM!')");
console.log(output.stdout());

await sandbox.stopAndWait();

Behind the scenes, create() pulls the image (if not cached), assembles the filesystem, boots a microVM. All in under a second.

Secrets are injected via placeholder substitution. The guest environment only ever sees a random placeholder. The real value is swapped in at the network level.

const sandbox = await Sandbox.create({
  name: "api-client",
  image: "python",
  secretEnv: { OPENAI_API_KEY: { value: "sk-real-secret-123", domain: "api.openai.com" } },
});

// Inside the VM: $OPENAI_API_KEY = "$MSB_OPENAI_API_KEY" (placeholder)
// Requests to api.openai.com: placeholder is replaced with the real key
// Requests to any other host: placeholder stays, secret never leaks

Control exactly what the sandbox can reach. The in-process networking stack enforces policy at the IP, DNS, and HTTP level. There's no host network to bridge to, so guests can't bypass the filter.

import { Sandbox } from "microsandbox";

const sandbox = await Sandbox.create({
  name: "restricted",
  image: "alpine",
  network: {
    policy: "public-only",            // blocks private/loopback
    blockDomainSuffixes: [".evil.com"] // DNS-level blocking
  },
});

Three built-in policies: NetworkPolicy::public_only() (default, blocks private IPs), NetworkPolicy::allow_all(), and NetworkPolicy::none() (fully airgapped).

Expose guest services on host ports:

const sandbox = await Sandbox.create({
  name: "web-server",
  image: "alpine",
  ports: { 8080: 80 }, // host:8080 → guest:80
});

Persistent storage that survives sandbox restarts and can be shared across sandboxes:

import { Sandbox, Volume } from "microsandbox";

// Create a volume with a quota.
const data = await Volume.create({ name: "shared-data", quotaMib: 100 });

// Sandbox A writes to it.
const writer = await Sandbox.create({
  name: "writer",
  image: "alpine",
  volumes: { "/data": { named: data.name } },
});

await writer.shell("echo 'hello' > /data/message.txt");
await writer.stopAndWait();

// Sandbox B reads from it.
const reader = await Sandbox.create({
  name: "reader",
  image: "alpine",
  volumes: { "/data": { named: data.name, readonly: true } },
});

const output = await reader.shell("cat /data/message.txt");
console.log(output.stdout()); // hello

Register named scripts that get mounted at /.msb/scripts/ and added to PATH, so you can invoke them by name:

const sandbox = await Sandbox.create({
  name: "worker",
  image: "ubuntu",
  scripts: {
    setup: "#!/bin/bash\napt-get update && apt-get install -y python3 curl",
    start: "#!/bin/bash\nexec python3 /app/main.py",
  },
});

await sandbox.shell("setup");
const output = await sandbox.shell("start");

Patches modify the filesystem before the VM boots. Inject config files, create directories, append to existing files:

import { Patch, Sandbox } from "microsandbox";

const sandbox = await Sandbox.create({
  name: "configured",
  image: "alpine",
  patches: [
    Patch.text("/etc/app.conf", "key=value\n"),
    Patch.mkdir("/app", { mode: 0o755 }),
    Patch.append("/etc/hosts", "127.0.0.1 myapp.local\n"),
  ],
});

Boot from an OCI image, a local directory, or a disk image:

// OCI image (default)
await Sandbox.create({ name: "oci", image: "python:3.12" });

// Local directory
await Sandbox.create({ name: "bind", image: "./my-rootfs" });

Read and write files inside the running sandbox from the host side:

// Write a file into the sandbox.
await sandbox.fs().write("/tmp/input.txt", Buffer.from("some data"));

// Read a file from the sandbox.
const content = await sandbox.fs().readString("/tmp/output.txt");

// List directory contents.
const entries = await sandbox.fs().list("/tmp");

For long-running commands, stream stdout/stderr events in real time:

const handle = await sandbox.shellStream("python train.py");

let event;
while ((event = await handle.recv()) !== null) {
  if (event.eventType === "stdout") process.stdout.write(event.data);
  if (event.eventType === "stderr") process.stderr.write(event.data);
  if (event.eventType === "exited") console.log(`Process exited: ${event.code}`);
}

The msb CLI provides a complete interface for managing sandboxes, images, and volumes.

msb run python:3.12 -- python3 -c "print('Hello from a microVM!')"

# Create and run detached
msb run --name my-app -d python:3.12

# Execute commands
msb exec my-app -- pip install requests
msb exec my-app -- python3 main.py

# Interactive shell into a running sandbox
msb shell my-app

# Lifecycle
msb stop my-app
msb start my-app
msb rm my-app

msb pull python:3.12           # Pull an image
msb image ls                   # List cached images
msb image rm python:3.12       # Remove an image

msb install ubuntu               # Install ubuntu sandbox as 'ubuntu' command
ubuntu                           # Opens Ubuntu in a microVM

msb install --name nodebox node  # Custom command name
msb install --tmp alpine         # Ephemeral: fresh sandbox every run
msb install --list               # List installed commands
msb uninstall nodebox            # Remove an installed command

msb volume create my-data      # Create a volume
msb volume ls                  # List volumes
msb volume rm my-data          # Remove a volume

msb ls                         # List all sandboxes
msb ps my-app                  # Show sandbox status
msb inspect my-app             # Detailed sandbox info
msb metrics my-app             # Live CPU/memory/network stats

To uninstall microsandbox, run: msb self uninstall.

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.

This project is licensed under the Apache License 2.0.

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