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
Copy

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
Copy

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();
}
Copy

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

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
Copy

⚖️ License

This project is licensed under the Apache-2.0 license.