virrun

virrun

An ephemeral, in-memory virtual runner: boot a repo into a RAM-backed filesystem, run its real toolchain (pnpm/npm, native addons, scripts) fast and isolated, then snapshot and fork the warm state so repeated runs are near-instant.

Table of Contents

• Getting Started
• Documentation
• License

---

Getting Started

Prerequisites

The os backend runs every command inside a bubblewrap RAM-overlay. bwrap is a system-level namespace tool — it is not an npm dependency and is intentionally not bundled (a prebuilt binary would bypass the distro's setuid/AppArmor integration and the kernel's unprivileged-userns config it relies on). Install it from your package manager:

# Debian / Ubuntu / WSL2
sudo apt install bubblewrap

# Fedora / RHEL
sudo dnf install bubblewrap

# Arch
sudo pacman -S bubblewrap

bwrap --version   # verify it is on PATH

The os backend is Linux-only and opt-in. On any other host — or with bwrap absent — Auto resolves to the native backend, so the package is usable everywhere; only BackendType.Os requires bwrap. isOsBackendSupported() reports whether the current host qualifies.

CLI

The lowest rung of adoption — wrap any single command, output streams live, the child's exit code is propagated:

virrun -- pnpm install
virrun -- pnpm test

Programmatic

import { BackendType, createVirrun } from "virrun";

const virrun = await createVirrun({ backend: BackendType.Auto });
try {
  const { exitCode, stdout } = await virrun.exec("pnpm build");
} finally {
  await virrun.dispose();
}

createVirrun accepts a source (directory, in-memory file map, or git remote) and a backend; it returns a handle with exec and dispose. See VirrunOptions.

Documentation

We highly recommend you take a look at the documentation to level up.

Design docs incubate in features/virrun — start with the architecture overview and the exec-isolation spec.

Backends

Backend	Isolation	Selected by Auto	Notes
native	none	✓ (today)	Runs the command directly on the host.
vfs	none (in-process, no spawn)	—	Recognised pure-JS node invocations in-process; falls back to native.
os	bubblewrap RAM-overlay + namespaces	—	Linux + bwrap only. Never falls back — an un-isolated run would be wrong.
auto	resolves to the best gate-proven	—	Resolves to native until an isolating backend beats the gates.

Commands

Run from packages/virrun/:

pnpm build        # export:gen + rolldown bundle to dist/
pnpm bench        # vitest bench (colocated *.bench.{json,md})
pnpm test         # vitest watch mode
pnpm lint:fix     # auto-fix lint
pnpm typecheck    # type check

License

This project is licensed under the Apache-2.0 license.