@vm0/runner 3.11.3 → 3.12.0

package/index.js

@@ -44,7 +44,7 @@ var runnerPaths = {
   /** Runner status file */
   statusFile: (baseDir) => path.join(baseDir, "status.json"),
   /** Snapshot generation work directory */
-  snapshotWorkDir: (baseDir) => path.join(baseDir, "workspaces", ".snapshot-work"),
+  snapshotWorkDir: (baseDir) => path.join(baseDir, "workspaces", "snapshot"),
   /** Check if a directory name is a VM workspace */
   isVmWorkspace: (dirname) => dirname.startsWith(VM_WORKSPACE_PREFIX),
   /** Extract vmId from workspace directory name */
@@ -62,6 +62,14 @@ var vmPaths = {
   /** Overlay filesystem for VM writes */
   overlay: (workDir) => path.join(workDir, "overlay.ext4")
 };
+var snapshotOutputPaths = {
+  /** VM state snapshot */
+  snapshot: (outputDir) => path.join(outputDir, "snapshot.bin"),
+  /** VM memory snapshot */
+  memory: (outputDir) => path.join(outputDir, "memory.bin"),
+  /** Golden overlay with guest state */
+  overlay: (outputDir) => path.join(outputDir, "overlay.ext4")
+};
 var tempPaths = {
   /** Default proxy CA directory */
   proxyDir: `${VM0_TMP_PREFIX}-proxy`,
@@ -102,7 +110,12 @@ var runnerConfigSchema = z.object({
   firecracker: z.object({
     binary: z.string().min(1, "Firecracker binary path is required"),
     kernel: z.string().min(1, "Kernel path is required"),
-    rootfs: z.string().min(1, "Rootfs path is required")
+    rootfs: z.string().min(1, "Rootfs path is required"),
+    snapshot: z.object({
+      snapshot: z.string().min(1, "Snapshot state file path is required"),
+      memory: z.string().min(1, "Snapshot memory file path is required"),
+      overlay: z.string().min(1, "Snapshot overlay file path is required")
+    }).optional()
   }),
   proxy: z.object({
     // TODO: Allow 0 to auto-find available port
@@ -131,7 +144,12 @@ var debugConfigSchema = z.object({
   firecracker: z.object({
     binary: z.string().min(1, "Firecracker binary path is required"),
     kernel: z.string().min(1, "Kernel path is required"),
-    rootfs: z.string().min(1, "Rootfs path is required")
+    rootfs: z.string().min(1, "Rootfs path is required"),
+    snapshot: z.object({
+      snapshot: z.string().min(1, "Snapshot state file path is required"),
+      memory: z.string().min(1, "Snapshot memory file path is required"),
+      overlay: z.string().min(1, "Snapshot overlay file path is required")
+    }).optional()
   }),
   proxy: z.object({
     port: z.number().int().min(1024).max(65535).default(PROXY_DEFAULTS.port),
@@ -172,6 +190,13 @@ function validateFirecrackerPaths(config) {
     { path: config.kernel, name: "Kernel" },
     { path: config.rootfs, name: "Rootfs" }
   ];
+  if (config.snapshot) {
+    checks.push(
+      { path: config.snapshot.snapshot, name: "Snapshot state file" },
+      { path: config.snapshot.memory, name: "Snapshot memory file" },
+      { path: config.snapshot.overlay, name: "Snapshot overlay file" }
+    );
+  }
   for (const check of checks) {
     if (!fs.existsSync(check.path)) {
       throw new Error(`${check.name} not found: ${check.path}`);
@@ -337,10 +362,13 @@ async function subscribeToJobs(server, group, onJob, onConnectionChange) {
 
 // src/lib/executor.ts
 import fs9 from "fs";
+import path6 from "path";
 
 // src/lib/firecracker/vm.ts
 import { spawn } from "child_process";
 import fs4 from "fs";
+import os from "os";
+import path4 from "path";
 import readline from "readline";
 
 // src/lib/firecracker/netns-pool.ts
@@ -379,8 +407,8 @@ var DEFAULT_OPTIONS = {
     maxTimeout: 1e3
   }
 };
-async function withFileLock(path7, fn, options) {
-  const release = await lockfile.lock(path7, { ...DEFAULT_OPTIONS, ...options });
+async function withFileLock(path9, fn, options) {
+  const release = await lockfile.lock(path9, { ...DEFAULT_OPTIONS, ...options });
   try {
     return await fn();
   } finally {
@@ -436,6 +464,10 @@ async function createNetnsWithTap(nsName, tap) {
   await execCommand(`ip netns exec ${nsName} ip link set ${tap.tapName} up`);
   await execCommand(`ip netns exec ${nsName} ip link set lo up`);
 }
+async function deleteNetns(nsName) {
+  await execCommand(`ip netns del ${nsName}`).catch(() => {
+  });
+}
 
 // src/lib/firecracker/netns-pool.ts
 var logger = createLogger("NetnsPool");
@@ -1077,10 +1109,10 @@ import * as http from "http";
 import * as fs3 from "fs";
 var logger3 = createLogger("FirecrackerClient");
 var FirecrackerApiError = class extends Error {
-  constructor(statusCode, path7, faultMessage) {
-    super(`Firecracker API error ${statusCode} on ${path7}: ${faultMessage}`);
+  constructor(statusCode, path9, faultMessage) {
+    super(`Firecracker API error ${statusCode} on ${path9}: ${faultMessage}`);
     this.statusCode = statusCode;
-    this.path = path7;
+    this.path = path9;
     this.faultMessage = faultMessage;
     this.name = "FirecrackerApiError";
   }
@@ -1193,27 +1225,27 @@ var FirecrackerClient = class {
   /**
    * GET request
    */
-  async get(path7) {
-    return this.request("GET", path7);
+  async get(path9) {
+    return this.request("GET", path9);
   }
   /**
    * PATCH request
    */
-  async patch(path7, body) {
-    return this.request("PATCH", path7, body);
+  async patch(path9, body) {
+    return this.request("PATCH", path9, body);
   }
   /**
    * PUT request
    */
-  async put(path7, body) {
-    return this.request("PUT", path7, body);
+  async put(path9, body) {
+    return this.request("PUT", path9, body);
   }
   /**
    * Make an HTTP request to Firecracker API
    *
    * @param timeoutMs Request timeout in milliseconds (default: 30000ms)
    */
-  request(method, path7, body, timeoutMs = 3e4) {
+  request(method, path9, body, timeoutMs = 3e4) {
     return new Promise((resolve, reject) => {
       const bodyStr = body !== void 0 ? JSON.stringify(body) : void 0;
       const headers = {
@@ -1227,7 +1259,7 @@ var FirecrackerClient = class {
       }
       const options = {
         socketPath: this.socketPath,
-        path: path7,
+        path: path9,
         method,
         headers,
         timeout: timeoutMs,
@@ -1235,7 +1267,7 @@ var FirecrackerClient = class {
         // Firecracker's single-threaded API can have issues with pipelined requests
         agent: false
       };
-      logger3.log(`${method} ${path7}${bodyStr ? " " + bodyStr : ""}`);
+      logger3.log(`${method} ${path9}${bodyStr ? " " + bodyStr : ""}`);
       const req = http.request(options, (res) => {
         let data = "";
         res.on("data", (chunk) => {
@@ -1252,14 +1284,14 @@ var FirecrackerClient = class {
               faultMessage = errorBody.fault_message || data;
             } catch {
             }
-            reject(new FirecrackerApiError(statusCode, path7, faultMessage));
+            reject(new FirecrackerApiError(statusCode, path9, faultMessage));
           }
         });
       });
       req.on("timeout", () => {
         req.destroy();
         reject(
-          new Error(`Request timeout after ${timeoutMs}ms: ${method} ${path7}`)
+          new Error(`Request timeout after ${timeoutMs}ms: ${method} ${path9}`)
         );
       });
       req.on("error", (err) => {
@@ -1352,7 +1384,7 @@ var FirecrackerVM = class {
     this.workDir = config.workDir;
     this.vsockPath = vmPaths.vsock(this.workDir);
     this.configPath = vmPaths.config(this.workDir);
-    this.apiSocketPath = `${this.workDir}/api.sock`;
+    this.apiSocketPath = vmPaths.apiSock(this.workDir);
   }
   /**
    * Get current VM state
@@ -1451,6 +1483,7 @@ var FirecrackerVM = class {
     const config = this.buildConfig();
     fs4.writeFileSync(this.configPath, JSON.stringify(config, null, 2));
     logger4.log(`[VM ${this.config.vmId}] Starting Firecracker (fresh boot)...`);
+    const currentUser = os.userInfo().username;
     this.process = spawn(
       "sudo",
       [
@@ -1458,6 +1491,9 @@ var FirecrackerVM = class {
         "netns",
         "exec",
         this.netns.name,
+        "sudo",
+        "-u",
+        currentUser,
         this.config.firecrackerBinary,
         "--config-file",
         this.configPath,
@@ -1475,25 +1511,58 @@ var FirecrackerVM = class {
    * Start VM from snapshot
    * Uses --api-sock to load snapshot via API
    *
-   * Drive configuration must be done before loading snapshot
-   * because our overlay path differs from the snapshot's original path.
+   * Snapshot contains original absolute paths for drives. We use mount namespace
+   * isolation to bind mount our actual overlay file to the path expected by the snapshot.
+   * This allows concurrent VMs to each have their own overlay while restoring from
+   * the same snapshot.
    */
   async startFromSnapshot(snapshot) {
     logger4.log(
       `[VM ${this.config.vmId}] Starting Firecracker (snapshot restore)...`
     );
-    logger4.log(`[VM ${this.config.vmId}] Snapshot: ${snapshot.snapshotPath}`);
-    logger4.log(`[VM ${this.config.vmId}] Memory: ${snapshot.memoryPath}`);
+    logger4.log(`[VM ${this.config.vmId}] Snapshot: ${snapshot.snapshot}`);
+    logger4.log(`[VM ${this.config.vmId}] Memory: ${snapshot.memory}`);
+    const actualVsockDir = vmPaths.vsockDir(this.workDir);
+    logger4.log(
+      `[VM ${this.config.vmId}] Snapshot vsock: ${snapshot.snapshotVsockDir}`
+    );
+    logger4.log(
+      `[VM ${this.config.vmId}] Snapshot overlay: ${snapshot.snapshotOverlay}`
+    );
+    logger4.log(`[VM ${this.config.vmId}] Actual vsock: ${actualVsockDir}`);
+    logger4.log(
+      `[VM ${this.config.vmId}] Actual overlay: ${this.vmOverlayPath}`
+    );
+    fs4.mkdirSync(snapshot.snapshotVsockDir, { recursive: true });
+    fs4.mkdirSync(path4.dirname(snapshot.snapshotOverlay), {
+      recursive: true
+    });
+    if (!fs4.existsSync(snapshot.snapshotOverlay)) {
+      fs4.writeFileSync(snapshot.snapshotOverlay, "");
+    }
+    const currentUser = os.userInfo().username;
+    const bindMountVsock = `mount --bind "${actualVsockDir}" "${snapshot.snapshotVsockDir}"`;
+    const bindMountOverlay = `mount --bind "${this.vmOverlayPath}" "${snapshot.snapshotOverlay}"`;
+    const firecrackerCmd = [
+      "ip",
+      "netns",
+      "exec",
+      this.netns.name,
+      "sudo",
+      "-u",
+      currentUser,
+      this.config.firecrackerBinary,
+      "--api-sock",
+      this.apiSocketPath
+    ].join(" ");
     this.process = spawn(
       "sudo",
       [
-        "ip",
-        "netns",
-        "exec",
-        this.netns.name,
-        this.config.firecrackerBinary,
-        "--api-sock",
-        this.apiSocketPath
+        "unshare",
+        "--mount",
+        "bash",
+        "-c",
+        `${bindMountVsock} && ${bindMountOverlay} && ${firecrackerCmd}`
       ],
       {
         cwd: this.workDir,
@@ -1504,26 +1573,11 @@ var FirecrackerVM = class {
     this.setupProcessHandlers();
     const client = new FirecrackerClient(this.apiSocketPath);
     await this.waitForApiReady(client);
-    logger4.log(`[VM ${this.config.vmId}] Configuring drives...`);
-    await Promise.all([
-      client.configureDrive({
-        drive_id: "rootfs",
-        path_on_host: this.config.rootfsPath,
-        is_root_device: true,
-        is_read_only: true
-      }),
-      client.configureDrive({
-        drive_id: "overlay",
-        path_on_host: this.vmOverlayPath,
-        is_root_device: false,
-        is_read_only: false
-      })
-    ]);
     logger4.log(`[VM ${this.config.vmId}] Loading snapshot...`);
     await client.loadSnapshot({
-      snapshot_path: snapshot.snapshotPath,
+      snapshot_path: snapshot.snapshot,
       mem_backend: {
-        backend_path: snapshot.memoryPath,
+        backend_path: snapshot.memory,
         backend_type: "File"
       },
       resume_vm: true
@@ -1756,8 +1810,8 @@ function encodeExecPayload(command, timeoutMs) {
   cmdBuf.copy(payload, 8);
   return payload;
 }
-function encodeWriteFilePayload(path7, content, sudo) {
-  const pathBuf = Buffer.from(path7, "utf-8");
+function encodeWriteFilePayload(path9, content, sudo) {
+  const pathBuf = Buffer.from(path9, "utf-8");
   if (pathBuf.length > 65535) {
     throw new Error(`Path too long: ${pathBuf.length} bytes (max 65535)`);
   }
@@ -2652,8 +2706,8 @@ function getErrorMap() {
   return overrideErrorMap;
 }
 var makeIssue = (params) => {
-  const { data, path: path7, errorMaps, issueData } = params;
-  const fullPath = [...path7, ...issueData.path || []];
+  const { data, path: path9, errorMaps, issueData } = params;
+  const fullPath = [...path9, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -2752,11 +2806,11 @@ var errorUtil;
   errorUtil2.toString = (message) => typeof message === "string" ? message : message === null || message === void 0 ? void 0 : message.message;
 })(errorUtil || (errorUtil = {}));
 var ParseInputLazyPath = class {
-  constructor(parent, value, path7, key) {
+  constructor(parent, value, path9, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path7;
+    this._path = path9;
     this._key = key;
   }
   get path() {
@@ -9220,7 +9274,7 @@ function initVMRegistry(registryPath) {
 // src/lib/proxy/proxy-manager.ts
 import { spawn as spawn2 } from "child_process";
 import fs7 from "fs";
-import path4 from "path";
+import path5 from "path";
 
 // src/lib/proxy/mitm-addon-script.ts
 var RUNNER_MITM_ADDON_SCRIPT = `#!/usr/bin/env python3
@@ -9716,7 +9770,7 @@ var ProxyManager = class {
   process = null;
   isRunning = false;
   constructor(config) {
-    const addonPath = path4.join(config.caDir, "mitm_addon.py");
+    const addonPath = path5.join(config.caDir, "mitm_addon.py");
     this.config = {
       ...DEFAULT_PROXY_OPTIONS,
       ...config,
@@ -9743,7 +9797,7 @@ var ProxyManager = class {
    * Ensure the addon script exists at the configured path
    */
   ensureAddonScript() {
-    const addonDir = path4.dirname(this.config.addonPath);
+    const addonDir = path5.dirname(this.config.addonPath);
     if (!fs7.existsSync(addonDir)) {
       fs7.mkdirSync(addonDir, { recursive: true });
     }
@@ -9759,7 +9813,7 @@ var ProxyManager = class {
     if (!fs7.existsSync(this.config.caDir)) {
       throw new Error(`Proxy CA directory not found: ${this.config.caDir}`);
     }
-    const caCertPath = path4.join(this.config.caDir, "mitmproxy-ca.pem");
+    const caCertPath = path5.join(this.config.caDir, "mitmproxy-ca.pem");
     if (!fs7.existsSync(caCertPath)) {
       throw new Error(`Proxy CA certificate not found: ${caCertPath}`);
     }
@@ -10212,7 +10266,21 @@ async function executeJob(context, config, options = {}) {
     const guestConnectionPromise = guest.waitForGuestConnection(3e4);
     logger9.log(`Creating VM ${vmId}...`);
     vm = new FirecrackerVM(vmConfig);
-    await withSandboxTiming("vm_create", () => vm.start());
+    const snapshotConfig = config.firecracker.snapshot;
+    let snapshotPaths;
+    if (snapshotConfig) {
+      const snapshotDir = path6.dirname(snapshotConfig.snapshot);
+      const originalBaseDir = path6.dirname(snapshotDir);
+      const snapshotBaseDir = runnerPaths.snapshotBaseDir(originalBaseDir);
+      const snapshotWorkDir = runnerPaths.snapshotWorkDir(snapshotBaseDir);
+      snapshotPaths = {
+        snapshot: snapshotConfig.snapshot,
+        memory: snapshotConfig.memory,
+        snapshotOverlay: vmPaths.overlay(snapshotWorkDir),
+        snapshotVsockDir: vmPaths.vsockDir(snapshotWorkDir)
+      };
+    }
+    await withSandboxTiming("vm_create", () => vm.start(snapshotPaths));
     guestIp = vm.getGuestIp();
     vethNsIp = vm.getNetns()?.vethNsIp ?? null;
     if (!guestIp || !vethNsIp) {
@@ -10240,6 +10308,10 @@ async function executeJob(context, config, options = {}) {
     logger9.log(`Waiting for guest connection...`);
     await withSandboxTiming("guest_wait", () => guestConnectionPromise);
     logger9.log(`Guest client ready`);
+    if (config.firecracker.snapshot) {
+      const timestamp = (Date.now() / 1e3).toFixed(3);
+      await guest.exec(`date -s "@${timestamp}"`);
+    }
     if (context.storageManifest) {
       await withSandboxTiming(
         "storage_download",
@@ -10442,7 +10514,7 @@ async function isPortInUse(port) {
 
 // src/lib/runner/runner-lock.ts
 import fs10 from "fs";
-import path5 from "path";
+import path7 from "path";
 var logger11 = createLogger("RunnerLock");
 var DEFAULT_PID_FILE = runtimePaths.runnerPid;
 var currentPidFile = null;
@@ -10459,7 +10531,7 @@ function isProcessRunning(pid) {
 }
 function acquireRunnerLock(options = {}) {
   const pidFile = options.pidFile ?? DEFAULT_PID_FILE;
-  const runDir = path5.dirname(pidFile);
+  const runDir = path7.dirname(pidFile);
   fs10.mkdirSync(runDir, { recursive: true });
   if (fs10.existsSync(pidFile)) {
     const pidStr = fs10.readFileSync(pidFile, "utf-8").trim();
@@ -10493,7 +10565,7 @@ function releaseRunnerLock() {
 var logger12 = createLogger("Runner");
 async function setupEnvironment(options) {
   const { config } = options;
-  await acquireRunnerLock();
+  acquireRunnerLock();
   const networkCheck = checkNetworkPrerequisites();
   if (!networkCheck.ok) {
     logger12.error("Network prerequisites not met:");
@@ -10523,10 +10595,16 @@ async function setupEnvironment(options) {
     );
   }
   logger12.log("Initializing overlay pool...");
+  const snapshotConfig = config.firecracker.snapshot;
   await initOverlayPool({
     size: config.sandbox.max_concurrent + 2,
     replenishThreshold: config.sandbox.max_concurrent,
-    poolDir: runnerPaths.overlayPool(config.base_dir)
+    poolDir: runnerPaths.overlayPool(config.base_dir),
+    createFile: snapshotConfig ? (filePath) => execCommand(
+      `cp --sparse=always "${snapshotConfig.overlay}" "${filePath}"`,
+      false
+    ).then(() => {
+    }) : void 0
   });
   logger12.log("Initializing namespace pool...");
   await initNetnsPool({
@@ -10834,7 +10912,7 @@ import { existsSync as existsSync5, readFileSync as readFileSync3, readdirSync a
 
 // src/lib/firecracker/process.ts
 import { readdirSync, readFileSync as readFileSync2, existsSync as existsSync4 } from "fs";
-import path6 from "path";
+import path8 from "path";
 function parseFirecrackerCmdline(cmdline) {
   const args = cmdline.split("\0");
   if (!args[0]?.includes("firecracker")) return null;
@@ -10867,7 +10945,7 @@ function findFirecrackerProcesses() {
   for (const entry of entries) {
     if (!/^\d+$/.test(entry)) continue;
     const pid = parseInt(entry, 10);
-    const cmdlinePath = path6.join(procDir, entry, "cmdline");
+    const cmdlinePath = path8.join(procDir, entry, "cmdline");
     if (!existsSync4(cmdlinePath)) continue;
     try {
       const cmdline = readFileSync2(cmdlinePath, "utf-8");
@@ -10925,7 +11003,7 @@ function findMitmproxyProcess() {
   for (const entry of entries) {
     if (!/^\d+$/.test(entry)) continue;
     const pid = parseInt(entry, 10);
-    const cmdlinePath = path6.join(procDir, entry, "cmdline");
+    const cmdlinePath = path8.join(procDir, entry, "cmdline");
     if (!existsSync4(cmdlinePath)) continue;
     try {
       const cmdline = readFileSync2(cmdlinePath, "utf-8");
@@ -10941,142 +11019,127 @@ function findMitmproxyProcess() {
 }
 
 // src/commands/doctor.ts
-var doctorCommand = new Command2("doctor").description("Diagnose runner health, check network, and detect issues").option("--config <path>", "Config file path", "./runner.yaml").action(
-  // eslint-disable-next-line complexity -- TODO: refactor complex function
-  async (options) => {
-    try {
-      const config = loadConfig(options.config);
-      const statusFilePath = runnerPaths.statusFile(config.base_dir);
-      const workspacesDir = runnerPaths.workspacesDir(config.base_dir);
-      console.log(`Runner: ${config.name}`);
-      let status = null;
-      if (existsSync5(statusFilePath)) {
-        try {
-          status = JSON.parse(
-            readFileSync3(statusFilePath, "utf-8")
-          );
-          console.log(`Mode: ${status.mode}`);
-          if (status.started_at) {
-            const started = new Date(status.started_at);
-            const uptime = formatUptime(Date.now() - started.getTime());
-            console.log(
-              `Started: ${started.toLocaleString()} (uptime: ${uptime})`
-            );
-          }
-        } catch {
-          console.log("Mode: unknown (status.json unreadable)");
-        }
-      } else {
-        console.log("Mode: unknown (no status.json)");
-      }
-      console.log("");
-      console.log("API Connectivity:");
-      try {
-        await pollForJob(config.server, config.group);
-        console.log(`  \u2713 Connected to ${config.server.url}`);
-        console.log("  \u2713 Authentication: OK");
-      } catch (error) {
-        console.log(`  \u2717 Cannot connect to ${config.server.url}`);
-        console.log(
-          `    Error: ${error instanceof Error ? error.message : "Unknown error"}`
-        );
-      }
-      console.log("");
-      console.log("Network:");
-      const warnings = [];
-      const proxyPort = config.proxy.port;
-      const mitmProc = findMitmproxyProcess();
-      const portInUse = await isPortInUse(proxyPort);
-      if (mitmProc) {
-        console.log(
-          `  \u2713 Proxy mitmproxy (PID ${mitmProc.pid}) on :${proxyPort}`
-        );
-      } else if (portInUse) {
-        console.log(
-          `  \u26A0\uFE0F Proxy port :${proxyPort} in use but mitmproxy process not found`
-        );
-        warnings.push({
-          message: `Port ${proxyPort} is in use but mitmproxy process not detected`
-        });
-      } else {
-        console.log(`  \u2717 Proxy mitmproxy not running`);
-        warnings.push({ message: "Proxy mitmproxy is not running" });
-      }
-      console.log(
-        `  \u2139 Namespaces: each VM runs in isolated namespace with IP ${SNAPSHOT_NETWORK.guestIp}`
-      );
-      console.log("");
-      const processes = findFirecrackerProcesses();
-      const workspaces = existsSync5(workspacesDir) ? readdirSync2(workspacesDir).filter(runnerPaths.isVmWorkspace) : [];
-      const jobs = [];
-      const statusVmIds = /* @__PURE__ */ new Set();
-      if (status?.active_run_ids) {
-        for (const runId of status.active_run_ids) {
-          const vmId = createVmId(runId);
-          statusVmIds.add(vmId);
-          const proc = processes.find((p) => p.vmId === vmId);
-          jobs.push({
-            runId,
-            vmId,
-            hasProcess: !!proc,
-            pid: proc?.pid
-          });
-        }
-      }
-      const maxConcurrent = config.sandbox.max_concurrent;
-      console.log(`Runs (${jobs.length} active, max ${maxConcurrent}):`);
-      if (jobs.length === 0) {
-        console.log("  No active runs");
-      } else {
-        console.log(
-          "  Run ID                                VM ID       Status"
-        );
-        for (const job of jobs) {
-          const statusText = job.hasProcess ? `\u2713 Running (PID ${job.pid})` : "\u26A0\uFE0F No process";
-          console.log(`  ${job.runId}  ${job.vmId}    ${statusText}`);
-        }
-      }
-      console.log("");
-      for (const job of jobs) {
-        if (!job.hasProcess) {
-          warnings.push({
-            message: `Run ${job.vmId} in status.json but no Firecracker process running`
-          });
-        }
-      }
-      const processVmIds = new Set(processes.map((p) => p.vmId));
-      for (const proc of processes) {
-        if (!statusVmIds.has(proc.vmId)) {
-          warnings.push({
-            message: `Orphan process: PID ${proc.pid} (vmId ${proc.vmId}) not in status.json`
-          });
-        }
-      }
-      for (const ws of workspaces) {
-        const vmId = runnerPaths.extractVmId(ws);
-        if (!processVmIds.has(vmId) && !statusVmIds.has(vmId)) {
-          warnings.push({
-            message: `Orphan workspace: ${ws} (no matching job or process)`
-          });
-        }
-      }
-      console.log("Warnings:");
-      if (warnings.length === 0) {
-        console.log("  None");
-      } else {
-        for (const w of warnings) {
-          console.log(`  - ${w.message}`);
-        }
-      }
-      process.exit(warnings.length > 0 ? 1 : 0);
-    } catch (error) {
-      console.error(
-        `Error: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-      process.exit(1);
+function displayRunnerStatus(statusFilePath) {
+  if (!existsSync5(statusFilePath)) {
+    console.log("Mode: unknown (no status.json)");
+    return null;
+  }
+  try {
+    const status = JSON.parse(
+      readFileSync3(statusFilePath, "utf-8")
+    );
+    console.log(`Mode: ${status.mode}`);
+    if (status.started_at) {
+      const started = new Date(status.started_at);
+      const uptime = formatUptime(Date.now() - started.getTime());
+      console.log(`Started: ${started.toLocaleString()} (uptime: ${uptime})`);
     }
+    return status;
+  } catch {
+    console.log("Mode: unknown (status.json unreadable)");
+    return null;
   }
-);
+}
+async function checkApiConnectivity(config) {
+  console.log("API Connectivity:");
+  try {
+    await pollForJob(config.server, config.group);
+    console.log(`  \u2713 Connected to ${config.server.url}`);
+    console.log("  \u2713 Authentication: OK");
+  } catch (error) {
+    console.log(`  \u2717 Cannot connect to ${config.server.url}`);
+    console.log(
+      `    Error: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+  }
+}
+async function checkNetwork(config, warnings) {
+  console.log("Network:");
+  const proxyPort = config.proxy.port;
+  const mitmProc = findMitmproxyProcess();
+  const portInUse = await isPortInUse(proxyPort);
+  if (mitmProc) {
+    console.log(`  \u2713 Proxy mitmproxy (PID ${mitmProc.pid}) on :${proxyPort}`);
+  } else if (portInUse) {
+    console.log(
+      `  \u26A0\uFE0F Proxy port :${proxyPort} in use but mitmproxy process not found`
+    );
+    warnings.push({
+      message: `Port ${proxyPort} is in use but mitmproxy process not detected`
+    });
+  } else {
+    console.log(`  \u2717 Proxy mitmproxy not running`);
+    warnings.push({ message: "Proxy mitmproxy is not running" });
+  }
+  console.log(
+    `  \u2139 Namespaces: each VM runs in isolated namespace with IP ${SNAPSHOT_NETWORK.guestIp}`
+  );
+}
+function buildJobInfo(status, processes) {
+  const jobs = [];
+  const statusVmIds = /* @__PURE__ */ new Set();
+  if (status?.active_run_ids) {
+    for (const runId of status.active_run_ids) {
+      const vmId = createVmId(runId);
+      statusVmIds.add(vmId);
+      const proc = processes.find((p) => p.vmId === vmId);
+      jobs.push({
+        runId,
+        vmId,
+        hasProcess: !!proc,
+        pid: proc?.pid
+      });
+    }
+  }
+  return { jobs, statusVmIds };
+}
+function displayRuns(jobs, maxConcurrent) {
+  console.log(`Runs (${jobs.length} active, max ${maxConcurrent}):`);
+  if (jobs.length === 0) {
+    console.log("  No active runs");
+    return;
+  }
+  console.log("  Run ID                                VM ID       Status");
+  for (const job of jobs) {
+    const statusText = job.hasProcess ? `\u2713 Running (PID ${job.pid})` : "\u26A0\uFE0F No process";
+    console.log(`  ${job.runId}  ${job.vmId}    ${statusText}`);
+  }
+}
+function detectOrphanResources(jobs, processes, workspaces, statusVmIds, warnings) {
+  for (const job of jobs) {
+    if (!job.hasProcess) {
+      warnings.push({
+        message: `Run ${job.vmId} in status.json but no Firecracker process running`
+      });
+    }
+  }
+  const processVmIds = new Set(processes.map((p) => p.vmId));
+  for (const proc of processes) {
+    if (!statusVmIds.has(proc.vmId)) {
+      warnings.push({
+        message: `Orphan process: PID ${proc.pid} (vmId ${proc.vmId}) not in status.json`
+      });
+    }
+  }
+  for (const ws of workspaces) {
+    const vmId = runnerPaths.extractVmId(ws);
+    if (!processVmIds.has(vmId) && !statusVmIds.has(vmId)) {
+      warnings.push({
+        message: `Orphan workspace: ${ws} (no matching job or process)`
+      });
+    }
+  }
+}
+function displayWarnings(warnings) {
+  console.log("Warnings:");
+  if (warnings.length === 0) {
+    console.log("  None");
+  } else {
+    for (const w of warnings) {
+      console.log(`  - ${w.message}`);
+    }
+  }
+}
 function formatUptime(ms) {
   const seconds = Math.floor(ms / 1e3);
   const minutes = Math.floor(seconds / 60);
@@ -11087,6 +11150,34 @@ function formatUptime(ms) {
   if (minutes > 0) return `${minutes}m`;
   return `${seconds}s`;
 }
+var doctorCommand = new Command2("doctor").description("Diagnose runner health, check network, and detect issues").option("--config <path>", "Config file path", "./runner.yaml").action(async (options) => {
+  try {
+    const config = loadConfig(options.config);
+    const statusFilePath = runnerPaths.statusFile(config.base_dir);
+    const workspacesDir = runnerPaths.workspacesDir(config.base_dir);
+    const warnings = [];
+    console.log(`Runner: ${config.name}`);
+    const status = displayRunnerStatus(statusFilePath);
+    console.log("");
+    await checkApiConnectivity(config);
+    console.log("");
+    await checkNetwork(config, warnings);
+    console.log("");
+    const processes = findFirecrackerProcesses();
+    const workspaces = existsSync5(workspacesDir) ? readdirSync2(workspacesDir).filter(runnerPaths.isVmWorkspace) : [];
+    const { jobs, statusVmIds } = buildJobInfo(status, processes);
+    displayRuns(jobs, config.sandbox.max_concurrent);
+    console.log("");
+    detectOrphanResources(jobs, processes, workspaces, statusVmIds, warnings);
+    displayWarnings(warnings);
+    process.exit(warnings.length > 0 ? 1 : 0);
+  } catch (error) {
+    console.error(
+      `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+    process.exit(1);
+  }
+});
 
 // src/commands/kill.ts
 import { Command as Command3 } from "commander";
@@ -11323,10 +11414,16 @@ var benchmarkCommand = new Command4("benchmark").description(
       process.exit(1);
     }
     timer.log("Initializing pools...");
+    const snapshotConfig = config.firecracker.snapshot;
     await initOverlayPool({
       size: 2,
       replenishThreshold: 1,
-      poolDir: runnerPaths.overlayPool(config.base_dir)
+      poolDir: runnerPaths.overlayPool(config.base_dir),
+      createFile: snapshotConfig ? (filePath) => execCommand(
+        `cp --sparse=always "${snapshotConfig.overlay}" "${filePath}"`,
+        false
+      ).then(() => {
+      }) : void 0
     });
     await initNetnsPool({ name: config.name, size: 2 });
     poolsInitialized = true;
@@ -11354,12 +11451,219 @@ var benchmarkCommand = new Command4("benchmark").description(
   process.exit(exitCode);
 });
 
+// src/commands/snapshot.ts
+import { Command as Command5 } from "commander";
+import { spawn as spawn3 } from "child_process";
+import fs11 from "fs";
+import os2 from "os";
+import readline3 from "readline";
+var logger15 = createLogger("Snapshot");
+function startFirecracker(nsName, firecrackerBinary, apiSocketPath, workDir) {
+  logger15.log("Starting Firecracker with API socket...");
+  const currentUser = os2.userInfo().username;
+  const fcProcess = spawn3(
+    "sudo",
+    [
+      "ip",
+      "netns",
+      "exec",
+      nsName,
+      "sudo",
+      "-u",
+      currentUser,
+      firecrackerBinary,
+      "--api-sock",
+      apiSocketPath
+    ],
+    {
+      cwd: workDir,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false
+    }
+  );
+  if (fcProcess.stdout) {
+    const stdoutRL = readline3.createInterface({ input: fcProcess.stdout });
+    stdoutRL.on("line", (line) => {
+      if (line.trim()) logger15.log(`[FC] ${line}`);
+    });
+  }
+  if (fcProcess.stderr) {
+    const stderrRL = readline3.createInterface({ input: fcProcess.stderr });
+    stderrRL.on("line", (line) => {
+      if (line.trim()) logger15.log(`[FC stderr] ${line}`);
+    });
+  }
+  fcProcess.on("error", (err) => logger15.log(`Firecracker error: ${err}`));
+  fcProcess.on(
+    "exit",
+    (code, signal) => logger15.log(`Firecracker exited: code=${code}, signal=${signal}`)
+  );
+  return fcProcess;
+}
+var snapshotCommand = new Command5("snapshot").description("Generate a Firecracker snapshot for fast VM startup").argument("<output-dir>", "Output directory for snapshot files").option("--config <path>", "Config file path", "./runner.yaml").action(
+  async (outputDir, opts) => {
+    const options = {
+      config: opts.config ?? "./runner.yaml",
+      output: outputDir
+    };
+    const timer = new Timer();
+    setGlobalLogger(timer.log.bind(timer));
+    logger15.log("Loading configuration...");
+    const config = loadDebugConfig(options.config);
+    validateFirecrackerPaths(config.firecracker);
+    const nsName = "vm0-snapshot";
+    const workDir = runnerPaths.snapshotWorkDir(config.base_dir);
+    const overlayPath = vmPaths.overlay(workDir);
+    const vsockPath = vmPaths.vsock(workDir);
+    const apiSocketPath = vmPaths.apiSock(workDir);
+    const outputSnapshot = snapshotOutputPaths.snapshot(options.output);
+    const outputMemory = snapshotOutputPaths.memory(options.output);
+    const outputOverlay = snapshotOutputPaths.overlay(options.output);
+    let fcProcess = null;
+    let vsockClient = null;
+    let exitCode = 0;
+    try {
+      if (fs11.existsSync(workDir)) {
+        logger15.log("Cleaning up stale work directory...");
+        fs11.rmSync(workDir, { recursive: true, force: true });
+      }
+      logger15.log(`Creating directories...`);
+      fs11.mkdirSync(options.output, { recursive: true });
+      fs11.mkdirSync(workDir, { recursive: true });
+      fs11.mkdirSync(vmPaths.vsockDir(workDir), { recursive: true });
+      logger15.log("Creating overlay filesystem...");
+      await createOverlayFile(overlayPath);
+      logger15.log(`Overlay created: ${overlayPath}`);
+      logger15.log(`Creating network namespace: ${nsName}`);
+      await deleteNetns(nsName);
+      await createNetnsWithTap(nsName, {
+        tapName: SNAPSHOT_NETWORK.tapName,
+        gatewayIpWithPrefix: `${SNAPSHOT_NETWORK.gatewayIp}/${SNAPSHOT_NETWORK.prefixLen}`
+      });
+      logger15.log("Network namespace created");
+      fcProcess = startFirecracker(
+        nsName,
+        config.firecracker.binary,
+        apiSocketPath,
+        workDir
+      );
+      const apiClient = new FirecrackerClient(apiSocketPath);
+      logger15.log("Waiting for API to be ready...");
+      await apiClient.waitForReady();
+      logger15.log("API ready");
+      logger15.log("Configuring VM via API...");
+      await Promise.all([
+        apiClient.configureMachine({
+          vcpu_count: config.sandbox.vcpu,
+          mem_size_mib: config.sandbox.memory_mb
+        }),
+        apiClient.configureBootSource({
+          kernel_image_path: config.firecracker.kernel,
+          boot_args: buildBootArgs()
+        }),
+        apiClient.configureDrive({
+          drive_id: "rootfs",
+          path_on_host: config.firecracker.rootfs,
+          is_root_device: true,
+          is_read_only: true
+        }),
+        apiClient.configureDrive({
+          drive_id: "overlay",
+          path_on_host: overlayPath,
+          is_root_device: false,
+          is_read_only: false
+        }),
+        apiClient.configureNetworkInterface({
+          iface_id: "eth0",
+          guest_mac: SNAPSHOT_NETWORK.guestMac,
+          host_dev_name: SNAPSHOT_NETWORK.tapName
+        }),
+        apiClient.configureVsock({
+          guest_cid: 3,
+          uds_path: vsockPath
+        })
+      ]);
+      logger15.log("VM configured");
+      logger15.log("Starting vsock listener...");
+      vsockClient = new VsockClient(vsockPath);
+      const guestConnectionPromise = vsockClient.waitForGuestConnection(6e4);
+      logger15.log("Starting VM...");
+      await apiClient.startInstance();
+      logger15.log("VM started");
+      logger15.log("Waiting for guest connection...");
+      await guestConnectionPromise;
+      logger15.log("Guest connected");
+      logger15.log("Verifying guest is responsive...");
+      const reachable = await vsockClient.isReachable();
+      if (!reachable) {
+        throw new Error("Guest is not responsive");
+      }
+      logger15.log("Guest is responsive");
+      logger15.log("Pausing VM...");
+      await apiClient.pause();
+      logger15.log("VM paused");
+      logger15.log("Creating snapshot...");
+      await apiClient.createSnapshot({
+        snapshot_type: "Full",
+        snapshot_path: outputSnapshot,
+        mem_file_path: outputMemory
+      });
+      logger15.log("Snapshot created");
+      logger15.log("Copying overlay as golden overlay...");
+      await execCommand(
+        `cp --sparse=always "${overlayPath}" "${outputOverlay}"`,
+        false
+      );
+      logger15.log("Golden overlay created");
+      logger15.log("=".repeat(40));
+      logger15.log("Snapshot generation complete!");
+      logger15.log("Files (logical size):");
+      const lsOutput = await execCommand(`ls -lh "${options.output}"`, false);
+      logger15.log(lsOutput);
+      logger15.log("Actual disk usage:");
+      const duOutput = await execCommand(
+        `du -h "${options.output}"/*`,
+        false
+      );
+      logger15.log(duOutput);
+      logger15.log("=".repeat(40));
+    } catch (error) {
+      logger15.error(
+        `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+      exitCode = 1;
+    } finally {
+      logger15.log("Cleaning up...");
+      if (vsockClient) {
+        vsockClient.close();
+      }
+      if (fcProcess && !fcProcess.killed) {
+        fcProcess.kill("SIGKILL");
+      }
+      await execCommand(
+        `pkill -9 -f "firecracker.*${apiSocketPath}"`,
+        true
+      ).catch(() => {
+      });
+      await deleteNetns(nsName);
+      if (fs11.existsSync(workDir)) {
+        fs11.rmSync(workDir, { recursive: true, force: true });
+      }
+      logger15.log("Cleanup complete");
+    }
+    if (exitCode !== 0) {
+      process.exit(exitCode);
+    }
+  }
+);
+
 // src/index.ts
-var version = true ? "3.11.3" : "0.1.0";
+var version = true ? "3.12.0" : "0.1.0";
 program.name("vm0-runner").version(version).description("Self-hosted runner for VM0 agents");
 program.addCommand(startCommand);
 program.addCommand(doctorCommand);
 program.addCommand(killCommand);
 program.addCommand(benchmarkCommand);
+program.addCommand(snapshotCommand);
 program.parse();
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vm0/runner",
-  "version": "3.11.3",
+  "version": "3.12.0",
   "description": "Self-hosted runner for VM0 agents",
   "repository": {
     "type": "git",