# Microsandbox microVM sandboxes: child processes, snapshots, and hard hardware floors

> A Rust microVM runtime that boots untrusted code as a child process, with a CLI, SDKs in four languages, OCI images, and fork plus snapshot support. The isolation story is coherent; the hardware requirements, the missing daemon, and the beta label are what to plan around.

**superradcompany/microsandbox** — 🧱 easy fast local-first microVM runtime and library

- Repository: https://github.com/superradcompany/microsandbox
- Website: https://docs.microsandbox.dev
- Stars: 8,757 · Forks: 483
- Language: Rust
- License: Apache-2.0
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/superradcompany-microsandbox

## Sandboxes are child processes, so the VM dies with the parent

Embeddability is the decision that shapes the rest. There is no setup server and no long running daemon: `Sandbox.builder("...").create()` in the SDK boots a microVM as a child process of the program that asked for it, and `msb run ubuntu` does the same from a shell. When the parent exits, the guest exits with it. That inverts the container habit, where a detached container outlives the terminal that created it, and it hands three jobs back to you: keeping a guest alive, restarting it after a crash, and finding it again later. Detached mode is the stated answer for long lived sessions, and snapshot files are the answer for surviving a restart, but neither is a supervisor. For a CI job that means the job has to outlive the work. For an agent that means writing a snapshot to disk between turns. The TypeScript SDK entry point looks like any async resource manager:

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

await using sandbox = await Sandbox.builder("my-sandbox")
  .image("python")
  .cpus(1)
  .memory(512)
  .create();

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

console.log(output.stdout());
```

The SDK packages install the same way any library does, one line per language:

```sh
npm i microsandbox
cargo add microsandbox
uv add microsandbox
go get github.com/superradcompany/microsandbox/sdk/go
```

## Fork gives you a twin, a snapshot gives you a time machine

Two verbs, and picking the wrong one wastes a copy of your state. `msb fork app --name experiment` duplicates live execution, so the new sandbox starts where the parent is right now and the two diverge from that moment. A snapshot travels through a file instead: `msb snap create --sandbox app --full -o saved.msb` writes `saved.msb`, and `msb snap restore saved.msb --name restored` builds a new sandbox from what landed on disk. The `--full` flag captures memory as well as filesystem state, and adding `--cow-mem` to the restore shares unchanged memory from that full snapshot rather than reading all of it back. History has two vocabularies: generations describe progression, branches describe distinct paths through it. One rough edge remains, the old `--forked` restore flag still works as a deprecated alias, so scripts written against it keep running while the docs point you at the current spelling.

```sh
# Fork a running sandbox.
msb fork app --name experiment
msb exec experiment -- python -c "print('An independent copy!')"
```

```sh
# Save now, resume later
msb snap create --sandbox app --full -o saved.msb
msb snap restore saved.msb --name restored
```

## sandbox.yaml ties the egress allow list to the script it guards

Configuration is one YAML file, and the published sample packs four keys doing four unrelated jobs. `image: python:3.12` selects the OCI image with a tag attached, `memory: 64M` caps guest memory, `network.allow` is a hostname list that acts as the egress policy, and `scripts` maps a name to a shell body. You invoke it with `msb run --conf sandbox.yaml -- octocat`, which means `octocat` is simultaneously the key under `scripts` and the argument after `--`. Binding the two means one file carries a whole reviewable task. It also means the sandbox definition and the command get edited in the same place, and a shell script embedded in YAML is subject to the indentation rules of the file it lives in. Keys the sample leaves out keep whatever default the runtime already had, so behaviour you did not write down is behaviour you did not choose.

```sh
msb run --conf sandbox.yaml -- octocat
```

```yaml
# sandbox.yaml
image: python:3.12
memory: 64M
network:
  allow:
    - api.github.com
scripts:
  octocat: |
    python - <<'PY'
    import urllib.request

    request = urllib.request.Request(
        "https://api.github.com/octocat",
        headers={"User-Agent": "microsandbox-example"},
    )
    with urllib.request.urlopen(request) as response:
        print(response.read().decode())
    PY
```

## msb install puts a sandbox on your PATH under its own name

`msb install ubuntu` installs a sandbox and binds it to the name `ubuntu`, so the next thing you type is `ubuntu` and it opens Ubuntu in a microVM. `msb uninstall ubuntu` takes the binding back out. This is the shortest route from install to an interactive session, and it is the only place in the CLI where the sandbox identity is the command name, which is precisely why it bites. A command called `ubuntu` on your PATH carries no hint that a microVM is behind it, and nothing in the name separates it from a container. For anything scripted, use the explicit `msb run ubuntu` instead. The rest of the command surface is plain enough: `msb pull python`, `msb image ls`, and `msb image rm python` manage cached images, while `msb ls`, `msb ps app`, `msb inspect app`, and `msb metrics app` list, check, describe, and stream live CPU, memory, and network numbers for a sandbox.

```sh
msb install ubuntu               # Install ubuntu sandbox as 'ubuntu' command
ubuntu                           # Opens Ubuntu in a microVM
msb uninstall ubuntu             # Uninstall the ubuntu sandbox
```

## Apple Silicon, KVM, and WHP are floors with no soft landing

The requirements are three lines and each one is a gate rather than a suggestion. macOS needs Apple Silicon, so an Intel Mac is out and no emulation path is offered. Linux needs KVM enabled, which is a kernel facility rather than a package you can install, so a host that is itself a VM or a container without the device passed through will not expose it. Windows needs WHP enabled. The Linux failure is the annoying one: nothing objects during installation and the missing capability surfaces the first time you try to boot a guest. Installing is one of five routes, and on macOS and Linux the short one is a curl pipe. Whatever you pick, the first real action is the same, `msb run ubuntu`, which pulls the image and opens a session.

```sh
curl -fsSL https://install.microsandbox.dev | sh        # 🍎 macOS / 🐧 Linux
```

```powershell
irm https://install.microsandbox.dev/windows | iex      # 🪟 Windows
```

```sh
brew install superradcompany/tap/microsandbox
```

```sh
npm i -g microsandbox
```

```sh
uv tool install microsandbox
```

```sh
cargo install microsandbox
```

```sh
msb run ubuntu
```

## Weekly tags, a beta label, and panic abort in the runtime binary

The project calls itself beta software and asks readers to expect breaking changes, missing features, and rough edges. The tag history supports that rather than softening it: v0.7.4 shipped on 2026-09-29, v0.7.5 on 2026-09-30, and v0.7.6 on 2026-10-01, with the last commit landing on 2026-10-03. Cargo.toml pins the entire workspace at 0.7.6 on edition 2024, and the release profile is tuned for shipped binaries with `codegen-units = 1`, `lto = true`, `strip = true`, and `panic = "abort"`, alongside a comment noting that CI artifacts exercise optimized code without paying the full release and LTO cost. The build recipe pins its firmware dependency explicitly at libkrunfw ABI 5, version 5.6.1, with a comment telling contributors to keep that constant in sync with the utils crate. Two consequences. Tags moving that fast mean a lockfile pin is the only thing holding a build still. And `panic = "abort"` applies to the runtime binary the CLI and SDK are made of, not to code inside a sandbox, so a Rust panic in the tooling ends that process instead of unwinding.

## Secrets stay outside the guest, so the guest cannot show them to you

One promise is that secret keys never enter the VM and cannot leak from it. The cost is a hard limit on debugging. If the key is not in the guest, the guest cannot echo it, cannot write it to a file, cannot hand it to a subprocess, and cannot reveal it through `msb exec` when a request fails. Injection happens at the point of use instead. The workspace is organised around that surface, with `examples/rust/net-secrets` and `examples/rust/net-secrets-body` sitting next to `net-policy`, `net-dns`, `net-ports`, and `net-tls`, and further examples for root binds, root block devices, OCI roots, rootfs patches, and disk and named volumes. Networking is the part with named example coverage, which makes it the part worth reading before you depend on it. The gap sits on the guest side: a program expecting a value in an environment variable, a config file, or an interactive prompt finds nothing there, and there is no supported way to hand the key in yourself.

## Conclusion

Adopt Microsandbox if you sit on Apple Silicon, a KVM host, or a Windows machine with WHP and you need to run code you would rather not trust, and you can tolerate pinning a version that moves weekly. Pass on it if you need one runtime across mixed hardware, a daemon that outlives your process, or guest side access to a secret. Verify first that your host exposes KVM or WHP, since nothing fails at install time when it is missing, then pin the CLI with `cargo install microsandbox --version 0.7.6` or the matching npm and uv releases before writing anything that depends on it.

## FAQ

### How does Microsandbox differ from Docker?

Microsandbox boots hardware isolated microVMs with average boot times under 100 milliseconds and spawns them as child processes, with no setup server and no long running daemon. It still reads standard container images from Docker Hub, GHCR, or any OCI registry and keeps Docker style image, command, shell, and volume workflows, so the difference is the isolation boundary and the lifecycle, not the image format.

### Does Microsandbox delete everything when a sandbox closes?

Nothing is removed automatically. `msb stop app` halts a sandbox, `msb start app` brings the same one back, and `msb rm app` is the command that deletes it. State worth keeping is written out deliberately with `msb snap create --sandbox app --full -o saved.msb` and returns with `msb snap restore saved.msb --name restored`.

### What hardware does Microsandbox need to run a sandbox?

Three requirements are listed: Apple Silicon for macOS, KVM enabled for Linux, and WHP enabled for Windows. No emulation path is offered for an Intel Mac or a Linux host without KVM exposed.

### Can code running inside a Microsandbox microVM read a secret key?

The design states that secret keys never enter the VM, so a guest cannot print the key or write it to a file, and there is no supported way to pass it in yourself. Injection happens at the point of use, with examples under `examples/rust/net-secrets` and `examples/rust/net-secrets-body`.

### Which Microsandbox SDK packages exist?

Four languages are published: TypeScript via `npm i microsandbox`, Rust via `cargo add microsandbox`, Python via `uv add microsandbox`, and Go via `go get github.com/superradcompany/microsandbox/sdk/go`. The workspace also carries `sdk/node-ts`, `sdk/python`, and `sdk/go/native` crates.

## Sources

- [Official documentation](https://docs.microsandbox.dev)
- [Official README](https://github.com/superradcompany/microsandbox#readme)
- [Project repository](https://github.com/superradcompany/microsandbox)
- [Release notes](https://github.com/superradcompany/microsandbox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/superradcompany-microsandbox