Introduction

microsandbox is a local microVM runtime for untrusted workloads: AI agents, user code, plugins, package installs, CI jobs, dev environments, scrapers, and automation.

Each sandbox is a lightweight VM with its own Linux kernel, filesystem, and network boundary. Your app or the msb CLI starts it locally, talks to it through a host-guest command channel, and controls what it can access.

It keeps the familiar workflow of OCI images and command execution, while moving risky work out of the host process.

npx microsandbox run debian

Why microsandbox

• Hardware isolation. Each sandbox is a VM, not a container namespace on the host kernel.
• Local runtime. The SDK starts the sandbox process directly. No daemon, remote service, or infrastructure setup.
• Fast startup. Sandboxes are lightweight enough to create from application code.
• Docker-like inputs. Use familiar OCI images from Docker Hub, GHCR, ECR, GCR, or another registry.
• Programmable controls. Configure resources, volumes, secrets, networking, and lifecycle from the CLI or SDK.
• Multi-language SDKs. Rust, TypeScript, Python, and Go expose the same core model.

Common workloads

• AI agents. Give coding agents and tool-using assistants a dedicated machine for commands, files, package installs, and generated code.
• User code execution. Run submitted scripts, notebooks, plugins, and extensions away from the host.
• CI/CD and builds. Isolate test jobs, compilers, package managers, and build tools.
• Dev environments. Create disposable Linux machines without touching your laptop or host Docker daemon.
• Scrapers and automation. Allow internet access while blocking private networks and metadata services.
• Secure tool execution. Run CLIs and dependencies that should not see host secrets or ambient credentials.

What makes it different

Secrets stay on the host

Instead of putting real credentials inside the VM, microsandbox injects placeholders and swaps them for real values only when traffic goes to an allowed host. Code inside the sandbox can run freely without ever receiving the secret value itself.

Network policy is host-controlled

All sandbox traffic flows through a host-side network stack. You can allow public internet access, block private networks, publish ports, deny by default, pin DNS behavior, or inspect TLS traffic without relying on guest cooperation.

Filesystems are disposable or persistent by choice

Use OCI images for disposable roots, bind mounts for host data, named volumes for persistent state, tmpfs for scratch space, and snapshots when you want to reuse prepared sandbox state.

Minimal example

let sb = Sandbox::builder("hello") .image("python") .create() .await?;

let output = sb.exec("python", ["-c", "print('Hello from a microVM!')"]).await?; println!("{}", output.stdout()?);

sb.stop().await?;

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

await using sb = await Sandbox.builder("hello")
    .image("python")
    .create();

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

from microsandbox import Sandbox

sb = await Sandbox.create("hello", image="python")

output = await sb.exec("python", ["-c", "print('Hello from a microVM!')"])
print(output.stdout_text)

await sb.stop()

sb, err := m.CreateSandbox(ctx, "hello", m.WithImage("python"))
if err != nil {
    return err
}
defer sb.Stop(ctx)

out, err := sb.Exec(ctx, "python", []string{"-c", "print('Hello from a microVM!')"})
if err != nil {
    return err
}
fmt.Println(out.Stdout())

Next steps