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.

Example use cases

• 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.

Storage is private by default

For the normal OCI image workflow, each sandbox gets its own writable root filesystem on top of the image. Writes there do not change the cached image. Data reaches the host or another sandbox only when you choose a sharing mechanism, such as a bind mount, named volume, disk image, or snapshot.

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