<div align="center"> <a href="./#gh-dark-mode-only" target="_blank" align="center"> <img width="35%" src="./assets/microsandbox-gh-banner-dark.png" alt="microsandbox-banner-xl-dark"> </a> </div> <div align="center"> <a href="./#gh-light-mode-only" target="_blank"> <img width="35%" src="./assets/microsandbox-gh-banner-light.png" alt="microsandbox-banner-xl"> </a> </div> <br /> <div align="center"><b>——   every agent deserves its own computer   ——</b></div> <br /> <br /> <div align='center'> <a href="https://github.com/superradcompany/microsandbox/releases"><img src="https://img.shields.io/github/v/release/superradcompany/microsandbox?include_prereleases&style=for-the-badge" alt="GitHub release"></a> <a href="https://discord.gg/T95Y3XnEAK"><img src="https://img.shields.io/discord/1315784565562019870?label=Discord&logo=discord&logoColor=white&color=5865F2&style=for-the-badge" alt="Discord"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache 2.0-blue.svg?style=for-the-badge" alt="Apache 2.0 License"></a> </div> <br />

<a href="./#gh-dark-mode-only" target="_blank"><img height="18" src="https://octicons-col.vercel.app/package/ffffff" alt="package-dark"></a><a href="./#gh-light-mode-only" target="_blank"><img height="18" src="https://octicons-col.vercel.app/package/000000" alt="package"></a> Microsandbox

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.

<img height="15" src="https://octicons-col.vercel.app/shield-lock/A770EF"> Hardware Isolation: Hypervisor-level isolation with microVM technology.
<img height="15" src="https://octicons-col.vercel.app/zap/A770EF"> Instant Startup: Boot times under 100 milliseconds.
<img height="15" src="https://octicons-col.vercel.app/plug/A770EF"> Embeddable: Spawn VMs right within your code. No setup server. No long-running daemon.
<img height="15" src="https://octicons-col.vercel.app/lock/A770EF"> Secrets That Can't Leak: Secret keys never enter the VM. The guest VM only sees placeholders.
<img height="15" src="https://octicons-col.vercel.app/globe/A770EF"> Programmable Filesystem & Network Stack: Customizable filesystems and network operations.
<img height="15" src="https://octicons-col.vercel.app/package/A770EF"> OCI Compatible: Runs standard container images from Docker Hub, GHCR, or any OCI registry.
<img height="15" src="https://octicons-col.vercel.app/database/A770EF"> Long-Running: Sandboxes can run in detached mode. They are great for long-lived sessions.
<img height="15" src="https://octicons-col.vercel.app/terminal/A770EF"> 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.

<br />

<a href="./#gh-dark-mode-only" target="_blank"><img height="13" src="https://octicons-col.vercel.app/rocket/ffffff" alt="rocket-dark"></a><a href="./#gh-light-mode-only" target="_blank"><img height="13" src="https://octicons-col.vercel.app/rocket/000000" alt="rocket"></a> Getting Started

<img height="14" src="https://octicons-col.vercel.app/move-to-bottom/A770EF"> Install the SDK

npm i microsandbox        # TypeScript

cargo add microsandbox    # Rust

<img height="14" src="https://octicons-col.vercel.app/download/A770EF"> Install the CLI

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.

<br />

<a href="./#gh-dark-mode-only" target="_blank"><img height="18" src="https://octicons-col.vercel.app/package-dependencies/ffffff" alt="sdk-dark"></a><a href="./#gh-light-mode-only" target="_blank"><img height="18" src="https://octicons-col.vercel.app/package-dependencies/000000" alt="sdk"></a> SDK

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

<img height="14" src="https://octicons-col.vercel.app/play/A770EF"> Run Code in a Sandbox

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();
<div align="left"> <a href="./rust_examples.md#run-code-in-a-sandbox"><img src="https://img.shields.io/badge/-→ Rust Example-D34516?style=flat-square&logo=rust&logoColor=white" alt="Rust"></a> </div>
Behind the scenes, create() pulls the image (if not cached), assembles the filesystem, boots a microVM. All in under a second.

<img height="14" src="https://octicons-col.vercel.app/lock/A770EF"> Secrets That Never Enter the VM

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
<div align="left"> <a href="./rust_examples.md#secrets-that-never-enter-the-vm"><img src="https://img.shields.io/badge/-→ Rust Example-D34516?style=flat-square&logo=rust&logoColor=white" alt="Rust"></a> </div>

<img height="14" src="https://octicons-col.vercel.app/globe/A770EF"> Network Policy

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
  },
});
<div align="left"> <a href="./rust_examples.md#network-policy"><img src="https://img.shields.io/badge/-→ Rust Example-D34516?style=flat-square&logo=rust&logoColor=white" alt="Rust"></a> </div>
Three built-in policies: NetworkPolicy::public_only() (default, blocks private IPs), NetworkPolicy::allow_all(), and NetworkPolicy::none() (fully airgapped).

<img height="14" src="https://octicons-col.vercel.app/upload/A770EF"> Port Publishing

Expose guest services on host ports:
const sandbox = await Sandbox.create({
  name: "web-server",
  image: "alpine",
  ports: { 8080: 80 }, // host:8080 → guest:80
});
<div align="left"> <a href="./rust_examples.md#port-publishing"><img src="https://img.shields.io/badge/-→ Rust Example-D34516?style=flat-square&logo=rust&logoColor=white" alt="Rust"></a> </div>

<img height="14" src="https://octicons-col.vercel.app/database/A770EF"> Named Volumes

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

<img height="14" src="https://octicons-col.vercel.app/pencil/A770EF"> Scripts & Patches

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");
<div align="left"> <a href="./rust_examples.md#scripts"><img src="https://img.shields.io/badge/-→ Rust Example-D34516?style=flat-square&logo=rust&logoColor=white" alt="Rust"></a> </div>
Patches modify the filesystem before the VM boots. Inject config files, create directories, append to e

Microsandbox

Install / Use

README