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.