mirab 0.2.0 → 0.2.1-canary-b0b093c

package/README.md

@@ -25,7 +25,18 @@ It installs mirab into `~/.mirab` (the release in `~/.mirab/releases/`, the
 release's manifest, with no sudo. It brings its own Bun, and on Linux its own
 Firecracker. The VM image is downloaded on first use. Builds: macOS (Apple
 silicon and Intel) and Linux x86_64. `sh -s -- --canary` installs the newest
-build of `main`.
+nightly build of `main`.
+
+### Releases
+
+- **Canary, nightly.** If `main` changed, a nightly build publishes
+  `X.Y.Z-canary-<sha>` to mirab-releases (binaries and VM image), then the
+  library to npm as `mirab@X.Y.Z-canary-<sha>` on the `canary` tag.
+- **Stable, promoted.** Actions → Promote → Run workflow with a canary tag
+  copies the same bytes to `X.Y.Z`, tags `vX.Y.Z`, and publishes
+  `mirab@X.Y.Z` on `latest`. The next canary needs a version bump.
+- An npm version is always the name of a release on mirab-releases, so the
+  library finds its own VM image by its version.
 
 ## Make an agent
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirab",
-  "version": "0.2.0",
+  "version": "0.2.1-canary-b0b093c",
   "type": "module",
   "scripts": {
     "dev": "bun run src/mirab.ts",
@@ -54,6 +54,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.e2e.test.ts",
     "types",
+    "scripts/firecracker.json",
     "README.md",
     "LICENSE"
   ]

package/scripts/firecracker.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.17.0",
+  "tarball": "https://github.com/firecracker-microvm/firecracker/releases/download/v1.17.0/firecracker-v1.17.0-x86_64.tgz",
+  "sha256": "06094a1108ae9e82aa4c23a775aa92758f53f1175d422270d9d6162cb9ade558",
+  "files": {
+    "firecracker-v1.17.0-x86_64": "99ad0f5cd0514a88aad0e9ae8cfdb3cc3b4ab9d190e1194602406c786b5de7a5",
+    "LICENSE": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30",
+    "NOTICE": "0f443af83ca8226c7ec44e2ade3a09fa3eed8c9b923b6c014b6d439816b6f1c2",
+    "THIRD-PARTY": "a6d3ebd1c2f37d4fd83d0676621f695fc0cc2d8c6e646cdbb831b46e0650c208"
+  }
+}

package/src/index.ts

@@ -5,9 +5,13 @@ export { loadManifest, manifestSchema, parseManifest } from './agent/manifest'
 export type { Manifest } from './agent/manifest'
 export {
   defineRunner,
+  dropToRunner,
+  isDarwin,
   RUNNER_PLATFORMS,
   RUNNER_SETPRIV,
   RUNNER_USER,
+  runnerUser,
+  secretDir,
   TOOLSETS,
 } from './runner/define'
 export type {

package/src/isolation/colima.ts

@@ -95,7 +95,7 @@ export function detectColima(p: ColimaProbe): ColimaState {
     return {
       running: false,
       reason: 'Colima is not installed',
-      fix: `Needs Sami: ${COLIMA_INSTALL}`,
+      fix: `To fix: ${COLIMA_INSTALL}`,
     }
   const out = p.status()
   let s: Record<string, unknown> | undefined

package/src/isolation/container.ts

@@ -57,13 +57,13 @@ export function containerNetwork(
   if (mode === 'block' || (!ready && mode === 'auto')) return 'none'
   if (!ready)
     throw new Error(
-      `egress is set to allow but the ${EGRESS_NETWORK} network is not set up. Needs Sami: ${setup}`,
+      `egress is set to allow but the ${EGRESS_NETWORK} network is not set up. To fix: ${setup}`,
     )
   return EGRESS_NETWORK
 }
 
 export const GUEST_WORK = '/workspace'
-export const NETWORK_SETUP = 'sudo scripts/vm-network-setup.sh'
+export const NETWORK_SETUP = `sudo mirab vm network setup --user ${process.env.USER ?? '<name>'}`
 /** The same script, run inside Colima's VM, where the containers' network lives. */
 export const COLIMA_NETWORK_SETUP =
   'colima ssh -- sudo sh -s up < scripts/vm-network-setup.sh'

package/src/isolation/firecracker-install.ts

@@ -0,0 +1,72 @@
+// Installs the Firecracker release mirab is pinned to (scripts/firecracker.json)
+// for a host that runs VMs without the npm package next to it: woreda's Linux
+// service install calls this. The tarball and the binary are both checked
+// against the pinned sha256 before the binary is put in place.
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { chmodSync, existsSync, readFileSync, renameSync } from 'node:fs'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import pin from '../../scripts/firecracker.json'
+
+export const FIRECRACKER_PIN = pin as {
+  version: string
+  tarball: string
+  sha256: string
+  files: Record<string, string>
+}
+
+const sha = (b: Uint8Array) => createHash('sha256').update(b).digest('hex')
+
+/** `<dir>/firecracker`, the pinned release; a matching one already there is kept. */
+export async function installFirecracker(
+  dir: string,
+  o: { fetcher?: typeof fetch; log?: (line: string) => void } = {},
+): Promise<string> {
+  const log = o.log ?? (() => {})
+  const name = `firecracker-v${FIRECRACKER_PIN.version}-x86_64`
+  const want = FIRECRACKER_PIN.files[name]
+  if (!want) throw new Error(`scripts/firecracker.json names no ${name}`)
+  const dest = join(dir, 'firecracker')
+  if (existsSync(dest) && sha(readFileSync(dest)) === want) return dest
+  if (process.arch !== 'x64')
+    throw new Error(
+      `Firecracker ${FIRECRACKER_PIN.version} is pinned for x86_64 hosts; this one is ${process.arch}`,
+    )
+  log(`downloading Firecracker ${FIRECRACKER_PIN.version}`)
+  const res = await (o.fetcher ?? fetch)(FIRECRACKER_PIN.tarball)
+  if (!res.ok)
+    throw new Error(
+      `could not fetch ${FIRECRACKER_PIN.tarball}: HTTP ${res.status}`,
+    )
+  const tgz = new Uint8Array(await res.arrayBuffer())
+  if (sha(tgz) !== FIRECRACKER_PIN.sha256)
+    throw new Error(
+      `refusing ${FIRECRACKER_PIN.tarball}: its sha256 is not the pinned ${FIRECRACKER_PIN.sha256}`,
+    )
+  await mkdir(dir, { recursive: true, mode: 0o755 })
+  const work = await mkdtemp(join(dir, '.firecracker-'))
+  try {
+    await writeFile(join(work, 'fc.tgz'), tgz)
+    const member = `release-v${FIRECRACKER_PIN.version}-x86_64/${name}`
+    const r = spawnSync('tar', [
+      '-xzf',
+      join(work, 'fc.tgz'),
+      '-C',
+      work,
+      member,
+    ])
+    if (r.status !== 0)
+      throw new Error(`could not unpack ${member}: ${String(r.stderr).trim()}`)
+    const bin = join(work, member)
+    if (sha(readFileSync(bin)) !== want)
+      throw new Error(
+        `refusing ${member}: its sha256 is not the pinned ${want}`,
+      )
+    chmodSync(bin, 0o755)
+    renameSync(bin, dest)
+    return dest
+  } finally {
+    await rm(work, { recursive: true, force: true })
+  }
+}

package/src/isolation/firecracker.ts

@@ -224,6 +224,10 @@ export interface VmStartOptions {
    *  [] for a VM that must not reach the host at all. Firecracker forwards a
    *  port only when someone serves it (onGuestConnect), so it needs no list. */
   listen?: number[]
+  /** vz on Apple silicon: boot this VM as macOS from a provisioned base
+   *  directory (its disk is `<macos>/disk.img`). Only for this VM: a host's
+   *  `vm.macos` never turns its other VMs into macOS. */
+  macos?: string
 }
 
 /** Sparse-grows a disk image file to `gib` GiB; refuses to shrink one. */

package/src/isolation/host-user.ts

@@ -99,7 +99,7 @@ export const setupCommand = (user: string, owner: string) =>
 
 /** Is the host tier for `user` set up, and set up safely? Never runs sudo. */
 export function hostUserState(user: string, probe: HostProbe): HostUserState {
-  const fix = `Needs Sami: ${setupCommand(user, probe.me.name)}`
+  const fix = `To fix: ${setupCommand(user, probe.me.name)}`
   const no = (reason: string): HostUserState => ({ ok: false, reason, fix })
   const raw = probe.marker(user)
   if (!raw) return no(`${user} is not set up (no ${MARKER_DIR}/${user}.json)`)
@@ -215,7 +215,7 @@ export async function startHostUser(
       await guestPing(open)
     } catch (e) {
       throw new Error(
-        `cannot run the agent as ${marker.user}: ${(e as Error).message}. Needs Sami: ${setupCommand(marker.user, marker.owner)}`,
+        `cannot run the agent as ${marker.user}: ${(e as Error).message}. To fix: ${setupCommand(marker.user, marker.owner)}`,
       )
     }
     log(`steps run as OS user ${marker.user} in ${staged}`)

package/src/isolation/image.ts

@@ -40,7 +40,7 @@ export const MIRAB_RELEASE: string = (() => {
   }
 })()
 
-/** Where the guest kernel, rootfs and (macOS) vz helper live, published or
+/** Where the guest kernel, rootfs, (macOS) vz helper and macOS guest agent live, published or
  *  built by `bun run vm:image`; `vm` uses them when isolation.json names no
  *  other files. */
 export function vmImagePaths(configDir: string) {
@@ -50,6 +50,8 @@ export function vmImagePaths(configDir: string) {
     kernel: join(dir, 'vmlinux'),
     rootfs: join(dir, 'rootfs.ext4'),
     vz: join(dir, 'mirab-vz'),
+    /** The guest agent macOS guests run (mirab image pull macos installs it). */
+    agent: join(dir, 'mirab-guest-agent-macos'),
     record: join(dir, 'image.json'),
   }
 }
@@ -58,10 +60,15 @@ export function vmImagePaths(configDir: string) {
 export const VM_PLATFORMS = {
   'linux-x64': { kernel: 'vmlinux', rootfs: 'rootfs.ext4' },
   'darwin-x64': { kernel: 'bzImage', rootfs: 'rootfs.ext4', vz: 'mirab-vz' },
-  'darwin-arm64': { kernel: 'Image', rootfs: 'rootfs.ext4', vz: 'mirab-vz' },
+  'darwin-arm64': {
+    kernel: 'Image',
+    rootfs: 'rootfs.ext4',
+    vz: 'mirab-vz',
+    agent: 'mirab-guest-agent',
+  },
 } as const
 export type VmPlatform = keyof typeof VM_PLATFORMS
-export type VmRole = 'kernel' | 'rootfs' | 'vz'
+export type VmRole = 'kernel' | 'rootfs' | 'vz' | 'agent'
 
 export const vmPlatform = (
   platform: string = process.platform,
@@ -93,7 +100,12 @@ export const vmManifestSchema = z.object({
       .object({ kernel: entry, rootfs: entry, vz: entry })
       .optional(),
     'darwin-arm64': z
-      .object({ kernel: entry, rootfs: entry, vz: entry })
+      .object({
+        kernel: entry,
+        rootfs: entry,
+        vz: entry,
+        agent: entry.optional(),
+      })
       .optional(),
   }),
 })
@@ -131,6 +143,12 @@ function readRecord(configDir: string): ImageRecord | 'local' | undefined {
 
 const rolesOf = (platform: VmPlatform) =>
   Object.keys(VM_PLATFORMS[platform]) as VmRole[]
+/** Roles a release may lack: releases before macOS guests have no agent,
+ *  and their image still runs Linux VMs (`mirab image pull macos` says why it
+ *  can't go on). */
+const OPTIONAL_ROLES: VmRole[] = ['agent']
+const requiredRoles = (platform: VmPlatform) =>
+  rolesOf(platform).filter((r) => !OPTIONAL_ROLES.includes(r))
 
 /** The published image for this CLI version and platform is installed and intact (cheap: sizes). */
 export function releaseImageInstalled(
@@ -147,7 +165,7 @@ export function releaseImageInstalled(
   )
     return false
   const paths = vmImagePaths(configDir)
-  return rolesOf(platform).every((role) => {
+  return requiredRoles(platform).every((role) => {
     try {
       return statSync(paths[role]).size === record.files[role]?.size
     } catch {
@@ -224,12 +242,12 @@ export async function ensureVmImage(
     )
   const files = manifest.platforms[platform] as
     Partial<Record<VmRole, VmFileEntry>> | undefined
-  const roles = rolesOf(platform)
-  if (!files || roles.some((r) => !files[r]))
+  if (!files || requiredRoles(platform).some((r) => !files[r]))
     throw new VmImageError(
       `the VM image manifest ${url} has no complete ${platform} image`,
     )
 
+  const roles = rolesOf(platform).filter((r) => files[r])
   const paths = vmImagePaths(o.configDir)
   await mkdir(paths.dir, { recursive: true, mode: 0o700 })
   const stage = await mkdtemp(join(paths.dir, '.download-'))
@@ -247,7 +265,10 @@ export async function ensureVmImage(
         log,
       )
     for (const role of roles) {
-      await chmod(join(stage, role), role === 'vz' ? 0o755 : 0o644)
+      await chmod(
+        join(stage, role),
+        role === 'vz' || role === 'agent' ? 0o755 : 0o644,
+      )
       await rename(join(stage, role), paths[role])
     }
     const record: ImageRecord = {

package/src/isolation/index.ts

@@ -79,6 +79,9 @@ export const hostConfigSchema = (configDir: string) =>
         memoryMiB: z.number().int().min(128).default(1024),
         vcpus: z.number().int().min(1).default(2),
         egress: z.enum(['auto', 'block', 'allow']).default('auto'),
+        /** macOS guests (Apple silicon): a provisioned base directory;
+         *  by default the newest one `mirab image pull macos` made. */
+        macos: z.string().optional(),
       })
       .optional(),
     container: z
@@ -127,16 +130,29 @@ export function startVm(
   platform: NodeJS.Platform = process.platform,
   opts: VmStartOptions = {},
 ): Promise<Isolation> {
+  // `vm.macos` names where the host's macOS base is; a VM boots macOS only
+  // when its caller asks for it (opts.macos).
+  const { macos: _base, ...linux } = vm
   if (vmBackend(platform) === 'vz')
     return startVz(
-      { ...vm, helper: vm.vz, port: 9002 },
+      opts.macos
+        ? {
+            ...linux,
+            helper: vm.vz,
+            port: 9002,
+            macos: opts.macos,
+            rootfs: join(opts.macos, 'disk.img'),
+          }
+        : { ...linux, helper: vm.vz, port: 9002 },
       work,
       vmDir,
       log,
       undefined,
       opts,
     )
-  const cfg: FirecrackerConfig = { ...vm, port: 9002 }
+  if (opts.macos)
+    throw new Error('macOS guests need a Mac with Apple silicon (vz)')
+  const cfg: FirecrackerConfig = { ...linux, port: 9002 }
   return startFirecracker(cfg, work, vmDir, log, opts)
 }
 
@@ -381,7 +397,7 @@ export async function startIsolation(
     if (!colimaMountFor(work, colima.mounts, true))
       throw new Error(
         `container: ${work} is not inside a writable Colima mount (${colima.mounts.map((m) => m.location).join(', ')}). ` +
-          `Needs Sami: add it under mounts in ~/.colima/default/colima.yaml, then colima restart`,
+          `To fix: add it under mounts in ~/.colima/default/colima.yaml, then colima restart`,
       )
     return startOci(
       { ...c, host: colima.socket, where: `Colima ${colima.vmType} VM` },

package/src/isolation/linux-network-setup.ts

@@ -0,0 +1,335 @@
+// `sudo mirab vm network setup --user <name>` on Linux: the one-time owner
+// step that gives Firecracker guests filtered egress, from the released binary
+// instead of a loose script (the macOS twin is vz-network-setup.ts).
+//
+// Setup writes three root-owned files whose content this binary generates
+// (nothing comes from a user-writable checkout), then runs them:
+//   1. /etc/mirab/vm-network.nft: table `inet mirab_vm`. Guests reach the
+//      internet; never the host, 10/8, 172.16/12, 192.168/16, the tailnet
+//      (100.64/10), link-local (169.254/16, the metadata address), 127/8,
+//      multicast, IPv6, or each other. Loaded before any bridge or tap exists,
+//      so a broken rule set never leaves a device to leak through.
+//   2. /usr/local/libexec/mirab-vm-network: `up` / `down` with plain ip, nft
+//      and sysctl calls: bridge mirabbr0 (172.31.250.1/24), N isolated taps
+//      owned by <user>, and Docker's mirab-egress network when Docker is there.
+//   3. /etc/systemd/system/mirab-vm-network.service: runs `up` at boot.
+// The taps belong to one user: the one whose VMs use them (woreda's service
+// user, or a person running `mirab spawn --vm`). networkState reads them.
+import { execFileSync } from 'node:child_process'
+import {
+  chmodSync,
+  chownSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname } from 'node:path'
+import { BRIDGE } from './network'
+
+export const NFT_FILE = '/etc/mirab/vm-network.nft'
+export const UP_SCRIPT = '/usr/local/libexec/mirab-vm-network'
+export const UNIT_NAME = 'mirab-vm-network.service'
+export const UNIT_FILE = `/etc/systemd/system/${UNIT_NAME}`
+export const SYSCTL_FILE = '/etc/sysctl.d/90-mirab-vm.conf'
+export const DEFAULT_SLOTS = 16
+
+/** Everything a guest must never reach. */
+export const DENIED4 = [
+  '0.0.0.0/8',
+  '10.0.0.0/8',
+  '100.64.0.0/10', // the tailnet
+  '127.0.0.0/8',
+  '169.254.0.0/16', // link-local, the cloud metadata address
+  '172.16.0.0/12',
+  '192.168.0.0/16',
+  '224.0.0.0/4',
+  '240.0.0.0/4',
+]
+
+export interface LinuxNetworkFile {
+  path: string
+  mode: number
+  content: string
+}
+
+export interface LinuxNetworkPlan {
+  user: string
+  slots: number
+}
+
+/** A user name the generated script can carry without quoting games. */
+const USER = /^[a-z_][a-z0-9_-]{0,31}$/
+
+export function checkPlan(p: LinuxNetworkPlan) {
+  if (!USER.test(p.user) || p.user === 'root')
+    throw new Error(
+      `--user ${p.user}: give the (non-root) user whose VMs use the network, e.g. --user woreda`,
+    )
+  if (!Number.isInteger(p.slots) || p.slots < 1 || p.slots > 256)
+    throw new Error(`--slots ${p.slots}: a whole number from 1 to 256`)
+}
+
+/** The files setup writes, in the order it writes them. */
+export function linuxNetworkFiles(p: LinuxNetworkPlan): LinuxNetworkFile[] {
+  checkPlan(p)
+  const bridges = `{ "${BRIDGE}", "mirabbr1" }`
+  return [
+    {
+      path: SYSCTL_FILE,
+      mode: 0o644,
+      content: 'net.ipv4.ip_forward=1\n',
+    },
+    {
+      path: NFT_FILE,
+      mode: 0o644,
+      content: `# mirab microVMs and containers: internet yes; host, LAN, tailnet, metadata and each other no.
+table inet mirab_vm {
+  set denied4 {
+    type ipv4_addr
+    flags interval
+    elements = { ${DENIED4.join(', ')} }
+  }
+  # Guests never reach the host itself (no DNS, no services, no ICMP).
+  chain input {
+    type filter hook input priority -10; policy accept;
+    iifname ${bridges} drop
+  }
+  chain forward {
+    type filter hook forward priority -10; policy accept;
+    iifname ${bridges} meta nfproto ipv6 drop
+    iifname ${bridges} ip daddr @denied4 drop
+    oifname ${bridges} ct state established,related accept
+    oifname ${bridges} drop
+  }
+  chain postrouting {
+    type nat hook postrouting priority 100; policy accept;
+    iifname ${bridges} oifname != ${bridges} masquerade
+  }
+}
+`,
+    },
+    {
+      path: UP_SCRIPT,
+      mode: 0o755,
+      content: `#!/bin/sh
+# Written by \`mirab vm network setup\` (do not edit; rerun setup instead).
+# up: rules first, then mirabbr0 and ${p.slots} isolated taps owned by ${p.user}. down: all of it gone.
+set -eu
+PATH=/usr/sbin:/usr/bin:/sbin:/bin
+case "\${1:-up}" in
+up)
+  sysctl -qw net.ipv4.ip_forward=1
+  nft delete table inet mirab_vm 2>/dev/null || true
+  nft -f ${NFT_FILE}
+  ip link show ${BRIDGE} >/dev/null 2>&1 || ip link add ${BRIDGE} type bridge
+  ip addr replace 172.31.250.1/24 dev ${BRIDGE}
+  ip link set ${BRIDGE} up
+  i=0
+  while [ $i -lt ${p.slots} ]; do
+    t=mirabtap$i
+    # A tap left by another owner is recreated for ${p.user}.
+    if ip link show "$t" >/dev/null 2>&1 && [ "$(cat /sys/class/net/$t/owner 2>/dev/null)" != "$(id -u ${p.user})" ]; then ip link del "$t"; fi
+    ip link show "$t" >/dev/null 2>&1 || ip tuntap add dev "$t" mode tap user ${p.user}
+    ip link set "$t" master ${BRIDGE}
+    bridge link set dev "$t" isolated on
+    ip link set "$t" up
+    i=$((i + 1))
+  done
+  if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+    docker network inspect mirab-egress >/dev/null 2>&1 || docker network create --driver bridge \\
+      --subnet 172.31.249.0/24 -o com.docker.network.bridge.name=mirabbr1 \\
+      -o com.docker.network.bridge.enable_icc=false mirab-egress >/dev/null
+  fi
+  # Docker's FORWARD policy is DROP: let the VM bridge through (the nft drops
+  # above still win; they run first and a drop is final).
+  if command -v iptables >/dev/null 2>&1 && iptables -n -L DOCKER-USER >/dev/null 2>&1; then
+    iptables -C DOCKER-USER -i ${BRIDGE} -j ACCEPT 2>/dev/null || iptables -I DOCKER-USER -i ${BRIDGE} -j ACCEPT
+    iptables -C DOCKER-USER -o ${BRIDGE} -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT 2>/dev/null ||
+      iptables -I DOCKER-USER -o ${BRIDGE} -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
+  fi
+  ;;
+down)
+  nft delete table inet mirab_vm 2>/dev/null || true
+  if command -v iptables >/dev/null 2>&1; then
+    iptables -D DOCKER-USER -i ${BRIDGE} -j ACCEPT 2>/dev/null || true
+    iptables -D DOCKER-USER -o ${BRIDGE} -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT 2>/dev/null || true
+  fi
+  for t in /sys/class/net/mirabtap*; do [ -e "$t" ] && ip link del "\${t##*/}"; done
+  ip link del ${BRIDGE} 2>/dev/null || true
+  if command -v docker >/dev/null 2>&1; then docker network rm mirab-egress >/dev/null 2>&1 || true; fi
+  ;;
+*) echo "usage: $0 up|down" >&2; exit 2 ;;
+esac
+`,
+    },
+    {
+      path: UNIT_FILE,
+      mode: 0o644,
+      content: `[Unit]
+Description=mirab microVM network (bridge ${BRIDGE}, ${p.slots} taps for ${p.user}, filtered egress)
+After=network-online.target docker.service
+Wants=network-online.target
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=${UP_SCRIPT} up
+ExecStop=${UP_SCRIPT} down
+[Install]
+WantedBy=multi-user.target
+`,
+    },
+  ]
+}
+
+/** What setup and remove touch on the machine; tests pass their own. */
+export interface LinuxSetupSystem {
+  isRoot(): boolean
+  platform: NodeJS.Platform
+  /** NixOS: /etc is generated from the system configuration (read-only). */
+  nixos: boolean
+  /** Whether a user exists (setup refuses a typo). */
+  userExists(name: string): boolean
+  /** A command on PATH, for the prerequisites check. */
+  has(command: string): boolean
+  /** Runs a command; throws when it fails. */
+  run(argv: string[]): void
+  /** Atomically installs a root:root file with this mode. */
+  install(file: LinuxNetworkFile): void
+  remove(path: string): void
+}
+
+export const realLinuxSystem: LinuxSetupSystem = {
+  isRoot: () => process.getuid?.() === 0,
+  platform: process.platform,
+  nixos: existsSync('/etc/NIXOS'),
+  userExists(name) {
+    try {
+      execFileSync('id', ['-u', name], { stdio: 'ignore' })
+      return true
+    } catch {
+      return false
+    }
+  },
+  has(command) {
+    try {
+      execFileSync('sh', ['-c', `command -v ${command}`], { stdio: 'ignore' })
+      return true
+    } catch {
+      return false
+    }
+  },
+  run(argv) {
+    execFileSync(argv[0]!, argv.slice(1), { stdio: 'inherit' })
+  },
+  install({ path, mode, content }) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o755 })
+    const tmp = `${path}.new`
+    writeFileSync(tmp, content, { mode })
+    chmodSync(tmp, mode)
+    chownSync(tmp, 0, 0)
+    renameSync(tmp, path)
+  },
+  remove(path) {
+    rmSync(path, { force: true })
+  },
+}
+
+function precheck(sys: LinuxSetupSystem, dryRun: boolean, verb: string) {
+  if (sys.platform !== 'linux')
+    throw new Error('this is the Linux (Firecracker) network setup')
+  if (sys.nixos)
+    throw new Error(
+      'on NixOS, /etc comes from your configuration: enable the network declaratively with the mirab NixOS module (services.mirab-vm-network) instead',
+    )
+  if (!dryRun && !sys.isRoot())
+    throw new Error(
+      `run with sudo: sudo mirab vm network ${verb}${verb === 'setup' ? ' --user <name>' : ''} (or add --dry-run to see what it does)`,
+    )
+}
+
+/** Installs the network for `user`'s VMs, or prints what it would do. Safe to run again. */
+export function setupLinuxNetwork(
+  opts: {
+    user?: string
+    slots?: number
+    dryRun?: boolean
+    log?: (line: string) => void
+  },
+  sys: LinuxSetupSystem = realLinuxSystem,
+) {
+  const dryRun = !!opts.dryRun
+  const log = opts.log ?? console.log
+  precheck(sys, dryRun, 'setup')
+  const user = opts.user ?? process.env.SUDO_USER
+  if (!user)
+    throw new Error(
+      'give the user whose VMs use the network: sudo mirab vm network setup --user <name>',
+    )
+  const plan = { user, slots: opts.slots ?? DEFAULT_SLOTS }
+  checkPlan(plan)
+  if (!sys.userExists(user))
+    throw new Error(`no user ${user} on this machine (create it first)`)
+  const missing = ['ip', 'nft', 'bridge', 'systemctl'].filter(
+    (c) => !sys.has(c),
+  )
+  if (missing.length)
+    throw new Error(
+      `missing ${missing.join(', ')}: install iproute2 and nftables (systemd is required)`,
+    )
+  const files = linuxNetworkFiles(plan)
+  const step = (what: string, act: () => void) =>
+    dryRun ? log(`+ ${what}`) : act()
+  for (const f of files) {
+    if (dryRun) log(`--- ${f.path} (${f.mode.toString(8)})\n${f.content}`)
+    else sys.install(f)
+  }
+  // A broken rule set must never be half-applied: check it before `up` loads it.
+  step(`nft -c -f ${NFT_FILE}`, () => sys.run(['nft', '-c', '-f', NFT_FILE]))
+  step('systemctl daemon-reload', () => sys.run(['systemctl', 'daemon-reload']))
+  // restart, not start: a rerun (new user, more slots) applies now.
+  step(
+    `systemctl enable ${UNIT_NAME} && systemctl restart ${UNIT_NAME}`,
+    () => {
+      sys.run(['systemctl', 'enable', UNIT_NAME])
+      sys.run(['systemctl', 'restart', UNIT_NAME])
+    },
+  )
+  log(
+    `${dryRun ? 'would install' : 'installed'}: mirab VM network (${plan.slots} taps for ${user}, filtered egress), kept across reboots by ${UNIT_NAME}. Check with: mirab vm network status`,
+  )
+}
+
+/** Undoes setup: the devices and rules first, then the files. */
+export function removeLinuxNetwork(
+  opts: { dryRun?: boolean; log?: (line: string) => void },
+  sys: LinuxSetupSystem = realLinuxSystem,
+) {
+  const dryRun = !!opts.dryRun
+  const log = opts.log ?? console.log
+  precheck(sys, dryRun, 'remove')
+  const step = (what: string, act: () => void) =>
+    dryRun ? log(`+ ${what}`) : act()
+  step(`systemctl disable --now ${UNIT_NAME}`, () => {
+    try {
+      sys.run(['systemctl', 'disable', '--now', UNIT_NAME])
+    } catch {
+      // never installed, or already stopped
+    }
+  })
+  step(`${UP_SCRIPT} down`, () => {
+    try {
+      sys.run([UP_SCRIPT, 'down'])
+    } catch {
+      // the script is gone already
+    }
+  })
+  step(`rm ${UNIT_FILE} ${UP_SCRIPT} ${NFT_FILE} ${SYSCTL_FILE}`, () => {
+    for (const f of [UNIT_FILE, UP_SCRIPT, NFT_FILE, SYSCTL_FILE]) sys.remove(f)
+  })
+  step('systemctl daemon-reload', () => sys.run(['systemctl', 'daemon-reload']))
+  log(
+    `${dryRun ? 'would remove' : 'removed'}: mirab VM network; VMs get no network until setup runs again`,
+  )
+}