@boardwalk-labs/runner 0.1.8 → 0.1.10

package/dist/bin.d.ts

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-export {};
+import { type IsolationConfig } from "./daemon/index.js";
+/** Build the isolation config from CLI flags: containerized by default; `--host` is the escape hatch. */
+export declare function isolationFromFlags(): IsolationConfig;

package/dist/bin.js

@@ -14,14 +14,12 @@
 //
 // Corporate proxies: launch with NODE_USE_ENV_PROXY=1 and HTTPS_PROXY set — Node's fetch (the
 // daemon) and the spawned run processes both honor it.
-import { spawn as nodeSpawn } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import * as os from "node:os";
 import { createLogger } from "./runtime/support/index.js";
 import { runnerOsSchema, runnerArchSchema } from "./contract.js";
-import { PoolClient, defaultIdentityDir, loadIdentity, removeIdentity, saveIdentity, startDaemon, } from "./daemon/index.js";
+import { PoolClient, defaultIdentityDir, loadIdentity, removeIdentity, saveIdentity, startRunner, } from "./daemon/index.js";
 const log = createLogger("boardwalk-runner");
 function flag(name) {
     const i = process.argv.indexOf(`--${name}`);
@@ -48,47 +46,6 @@ function machineArch() {
     const parsed = runnerArchSchema.safeParse(process.arch);
     return parsed.success ? parsed.data : undefined;
 }
-/** Real spawner: one Node process per run, executing the SAME runtime a hosted worker boots.
- *  Env is exactly the platform contract + the claim's resolved vars, over a minimal base
- *  (PATH + proxy knobs from the daemon's own environment; HOME = the run's workspace). */
-function realSpawn(opts) {
-    const base = {};
-    for (const key of [
-        "PATH",
-        "LANG",
-        "NODE_USE_ENV_PROXY",
-        "HTTPS_PROXY",
-        "https_proxy",
-        "HTTP_PROXY",
-        "http_proxy",
-        "NO_PROXY",
-        "no_proxy",
-        "BOARDWALK_RUNNER_DEBUG",
-    ]) {
-        const v = process.env[key];
-        if (v !== undefined)
-            base[key] = v;
-    }
-    const child = nodeSpawn(process.execPath, [opts.entry], {
-        cwd: opts.cwd,
-        env: { ...base, HOME: opts.cwd, TMPDIR: path.join(opts.cwd, "..", "tmp"), ...opts.env },
-        stdio: "inherit",
-    });
-    const exit = new Promise((resolve) => {
-        child.on("exit", (code, signal) => {
-            resolve(code ?? (signal !== null ? 143 : 1));
-        });
-        child.on("error", () => {
-            resolve(1);
-        });
-    });
-    return {
-        wait: () => exit,
-        kill: () => {
-            child.kill("SIGTERM");
-        },
-    };
-}
 async function cmdRegister() {
     const baseUrl = requireFlag("url");
     const token = requireFlag("token");
@@ -114,6 +71,23 @@ async function cmdRegister() {
     log.info("registered", { runnerId: res.runner_id, pool: res.pool, identity: file });
     process.stdout.write(`Registered runner ${res.runner_id} in pool '${res.pool}'.\nStart it with: boardwalk-runner start --url ${baseUrl} --pool ${res.pool}\n`);
 }
+/** Build the isolation config from CLI flags: containerized by default; `--host` is the escape hatch. */
+export function isolationFromFlags() {
+    if (hasFlag("host"))
+        return { mode: "host" };
+    const image = flag("image");
+    const network = flag("network");
+    const mounts = (flag("mount") ?? "")
+        .split(",")
+        .map((m) => m.trim())
+        .filter((m) => m.length > 0);
+    return {
+        mode: "container",
+        ...(image !== undefined ? { image } : {}),
+        ...(network !== undefined ? { network } : {}),
+        ...(mounts.length > 0 ? { mounts } : {}),
+    };
+}
 async function cmdStart() {
     const baseUrl = requireFlag("url");
     const pool = flag("pool") ?? "default";
@@ -123,32 +97,15 @@ async function cmdStart() {
         process.stderr.write(`No saved identity for ${baseUrl} pool '${pool}'. Run boardwalk-runner register first.\n`);
         process.exit(1);
     }
-    const workDir = flag("work-dir") ?? path.join(identityDir, "work");
-    const runtimeEntry = fileURLToPath(new URL("./runtime/main.js", import.meta.url));
-    const client = new PoolClient({ baseUrl, runnerToken: identity.runner_token });
-    const daemon = startDaemon({
-        client,
-        runtimeEntry,
-        workDir,
-        runnerId: identity.runner_id,
-        spawn: realSpawn,
+    // The daemon lifecycle + isolation decision live in the shared startRunner — this binary and the
+    // main CLI both call it, so their behavior can't drift.
+    await startRunner({
+        baseUrl,
+        identity,
+        isolation: isolationFromFlags(),
+        workDir: flag("work-dir") ?? path.join(identityDir, "work"),
         ...(hasFlag("once") ? { once: true } : {}),
     });
-    let interrupts = 0;
-    for (const signal of ["SIGINT", "SIGTERM"]) {
-        process.on(signal, () => {
-            interrupts += 1;
-            if (interrupts === 1) {
-                process.stderr.write("\nDraining: finishing the current run, claiming nothing new. Ctrl-C again to force-quit.\n");
-                daemon.drain();
-            }
-            else {
-                process.exit(130);
-            }
-        });
-    }
-    process.stdout.write(`Runner ${identity.name} online in pool '${pool}'. Waiting for runs...\n`);
-    await daemon.done;
 }
 async function cmdDeregister() {
     const baseUrl = requireFlag("url");
@@ -183,8 +140,16 @@ const USAGE = `boardwalk-runner <register|start|deregister> [flags]
 
   register    --url <control-plane> --token <bwkreg_…> [--name] [--labels a,b] [--identity-dir]
   start       --url <control-plane> [--pool default] [--work-dir] [--once] [--identity-dir]
+              [--host] [--image <ref>] [--network <mode>] [--mount host:container[:ro],…]
   deregister  --url <control-plane> [--pool default] [--identity-dir]
 
+  Isolation (start): runs are CONTAINERIZED by default (docker/podman) — each run sees only its
+  workspace + the machine's network, not your home dir, creds, or the rest of the machine.
+    --host              raw process mode: full machine access (trusted workflows only / no runtime)
+    --image <ref>       runner image to run (default: the version-pinned ghcr.io image)
+    --network <mode>    container network (default: host — preserves LAN/VPN/localhost reach)
+    --mount a:b[:ro]    extra host paths to expose to the run (comma-separated)
+
   --verbose   debug-level daemon logs (poll cycles, heartbeats)
   --debug     --verbose, plus debug logging inside each spawned run process
 `;

package/dist/daemon/container.d.ts

@@ -0,0 +1,46 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import type { RunProcessHandle } from "./daemon.js";
+export interface ContainerSpawnConfig {
+    /** Container runtime binary: `docker` or `podman`. */
+    runtime: string;
+    /** Fully-qualified runner image ref (e.g. `ghcr.io/boardwalk-labs/runner:0.1.9`). */
+    image: string;
+    /** Docker network mode. Default `host` — preserves the machine's LAN/VPN/localhost reach. */
+    network?: string;
+    /** Extra host bind mounts (`hostPath:containerPath[:ro]`) the user opted into for this fleet. */
+    mounts?: readonly string[];
+    /** Run the container as this `uid:gid` — the invoking host user — so writes to the bind-mounted
+     *  workspace match host ownership instead of the image's `node` (uid 1000). Set on Linux; omit on
+     *  Docker Desktop (macOS/Windows), which maps ownership through its file sharing. */
+    user?: string;
+    /** Test seam. */
+    spawn?: typeof nodeSpawn;
+}
+/** The env the container receives: the claim's env + platform contract, with the in-container
+ *  filesystem coordinates overridden (the host paths are meaningless inside the container). */
+export declare function containerEnv(runEnv: Record<string, string>): Record<string, string>;
+/** Derive the run id from the per-run workspace path (`<workDir>/runs/<runId>/workspace`). Used only
+ *  for a human-readable container name; a fallback keeps a non-standard cwd from throwing. */
+export declare function runIdFromCwd(cwd: string): string;
+/**
+ * Build the `docker run` argv. PURE + exported so the isolation guarantees are unit-asserted:
+ *  - the ONLY bind mount is the per-run workspace (+ any explicit user mounts) — the identity dir,
+ *    the user's home, and the rest of the host FS are never mounted;
+ *  - per-run credentials are passed by NAME (`-e BOARDWALK_RUN_TOKEN`), so their VALUES come from the
+ *    docker client's env and never appear in the argv (which `ps` exposes);
+ *  - `--rm` (no leftover container), `--init` (proper signal handling / zombie reaping).
+ */
+export declare function buildContainerArgs(cfg: ContainerSpawnConfig, opts: {
+    env: Record<string, string>;
+    cwd: string;
+}): string[];
+/** A `RunSpawner` that runs each run in a throwaway container. */
+export declare function createContainerSpawner(cfg: ContainerSpawnConfig): (opts: {
+    entry: string;
+    env: Record<string, string>;
+    cwd: string;
+}) => RunProcessHandle;
+/** Probe that a container runtime is installed AND its daemon is reachable. Returns the runtime
+ *  binary name on success, or null (so `start` can hard-fail with a clear message rather than
+ *  failing every run later). `docker info` / `podman info` exits non-zero when the daemon is down. */
+export declare function detectContainerRuntime(candidates?: readonly string[], run?: (bin: string) => Promise<void>): Promise<string | null>;

package/dist/daemon/container.js

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: Apache-2.0
+// Container run spawner — the DEFAULT isolation model for a self-hosted runner. Each run executes
+// inside a throwaway container (Docker/Podman) instead of as a same-UID child process, so the run
+// (and the LLM-decided `agent()` tool calls inside it) sees ONLY its own workspace, never the
+// user's home dir, the runner's identity file, SSH/cloud creds, or the rest of the machine. The
+// machine's network IS preserved (`--network host`) so a run still reaches the org's LAN, VPN, and
+// localhost services — the reason to self-host. Full host access stays possible, but only as an
+// EXPLICIT mount, never the silent default. `--host` (a separate spawner) is the escape hatch.
+//
+// Security-critical surface: `buildContainerArgs` is a pure function so the argv can be asserted
+// exhaustively — the identity dir is NEVER bind-mounted, and per-run credentials ride the docker
+// client's ENV (name-only `-e KEY`), never the argv (which `ps` would expose).
+import { spawn as nodeSpawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import * as path from "node:path";
+const exec = promisify(execFile);
+/** Env keys forwarded from the daemon's OWN environment into the container (proxy + locale only —
+ *  NOT the machine's PATH/HOME, which would leak host layout; the image provides its own). */
+const FORWARDED_ENV_KEYS = [
+    "LANG",
+    "NODE_USE_ENV_PROXY",
+    "HTTPS_PROXY",
+    "https_proxy",
+    "HTTP_PROXY",
+    "http_proxy",
+    "NO_PROXY",
+    "no_proxy",
+    "BOARDWALK_RUNNER_DEBUG",
+];
+/** The env the container receives: the claim's env + platform contract, with the in-container
+ *  filesystem coordinates overridden (the host paths are meaningless inside the container). */
+export function containerEnv(runEnv) {
+    const env = {
+        // Forward the daemon's proxy/locale knobs so egress + a corporate proxy still work.
+        ...forwardedEnv(),
+        // The claim's resolved non-secret vars + platform contract (RUN_ID, BOARDWALK_RUN_TOKEN, …).
+        ...runEnv,
+        // In-container coordinates — the bind mount lands the workspace at /workspace.
+        WORKSPACE_ROOT: "/workspace",
+        HOME: "/workspace",
+        TMPDIR: "/tmp",
+    };
+    return env;
+}
+function forwardedEnv() {
+    const out = {};
+    for (const key of FORWARDED_ENV_KEYS) {
+        const v = process.env[key];
+        if (v !== undefined)
+            out[key] = v;
+    }
+    return out;
+}
+/** Derive the run id from the per-run workspace path (`<workDir>/runs/<runId>/workspace`). Used only
+ *  for a human-readable container name; a fallback keeps a non-standard cwd from throwing. */
+export function runIdFromCwd(cwd) {
+    const runId = path.basename(path.dirname(cwd));
+    return /^[A-Za-z0-9_-]{1,64}$/.test(runId) ? runId : "run";
+}
+/**
+ * Build the `docker run` argv. PURE + exported so the isolation guarantees are unit-asserted:
+ *  - the ONLY bind mount is the per-run workspace (+ any explicit user mounts) — the identity dir,
+ *    the user's home, and the rest of the host FS are never mounted;
+ *  - per-run credentials are passed by NAME (`-e BOARDWALK_RUN_TOKEN`), so their VALUES come from the
+ *    docker client's env and never appear in the argv (which `ps` exposes);
+ *  - `--rm` (no leftover container), `--init` (proper signal handling / zombie reaping).
+ */
+export function buildContainerArgs(cfg, opts) {
+    const args = [
+        "run",
+        "--rm",
+        "--init",
+        "--name",
+        `bw-run-${runIdFromCwd(opts.cwd)}`,
+        "--network",
+        cfg.network ?? "host",
+        // The per-run workspace — the ONLY host path the run can see by default.
+        "-v",
+        `${opts.cwd}:/workspace`,
+        "-w",
+        "/workspace",
+    ];
+    // Run as the invoking host user (Linux) so the bind-mounted workspace is writable — the image's
+    // `node` (uid 1000) otherwise can't write a host dir it doesn't own.
+    if (cfg.user !== undefined) {
+        args.push("--user", cfg.user);
+    }
+    // Explicit, user-opted-in host mounts (fleet config) — the honest way to say "I grant this path".
+    for (const m of cfg.mounts ?? []) {
+        args.push("-v", m);
+    }
+    // Env by NAME only — values are read from the docker client's environment, never the argv.
+    for (const key of Object.keys(containerEnv(opts.env))) {
+        args.push("-e", key);
+    }
+    args.push(cfg.image);
+    return args;
+}
+/** A `RunSpawner` that runs each run in a throwaway container. */
+export function createContainerSpawner(cfg) {
+    const spawnImpl = cfg.spawn ?? nodeSpawn;
+    return (opts) => {
+        const args = buildContainerArgs(cfg, opts);
+        const child = spawnImpl(cfg.runtime, args, {
+            // The docker client reads the name-only `-e KEY` values from ITS environment — set them here so
+            // they never touch the argv. The daemon's own secrets are NOT here (only forwarded + claim env).
+            env: { ...process.env, ...containerEnv(opts.env) },
+            stdio: "inherit",
+        });
+        const exit = new Promise((resolve) => {
+            child.on("exit", (code, signal) => {
+                resolve(code ?? (signal !== null ? 143 : 1));
+            });
+            child.on("error", () => {
+                resolve(1);
+            });
+        });
+        return {
+            wait: () => exit,
+            kill: () => {
+                // `docker run` proxies SIGTERM to the container; also best-effort `docker kill` by name in
+                // case signal proxying is off, so a lost lease / drain actually stops the container.
+                child.kill("SIGTERM");
+                void exec(cfg.runtime, ["kill", `bw-run-${runIdFromCwd(opts.cwd)}`]).catch(() => undefined);
+            },
+        };
+    };
+}
+/** Probe that a container runtime is installed AND its daemon is reachable. Returns the runtime
+ *  binary name on success, or null (so `start` can hard-fail with a clear message rather than
+ *  failing every run later). `docker info` / `podman info` exits non-zero when the daemon is down. */
+export async function detectContainerRuntime(candidates = ["docker", "podman"], run = async (bin) => {
+    await exec(bin, ["info"], { timeout: 10_000 });
+}) {
+    for (const bin of candidates) {
+        try {
+            await run(bin);
+            return bin;
+        }
+        catch {
+            // not installed, or the daemon isn't running — try the next candidate
+        }
+    }
+    return null;
+}

package/dist/daemon/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./pool_client.js";
 export * from "./identity.js";
 export * from "./daemon.js";
+export * from "./container.js";
+export * from "./start.js";

package/dist/daemon/index.js

@@ -2,3 +2,5 @@
 export * from "./pool_client.js";
 export * from "./identity.js";
 export * from "./daemon.js";
+export * from "./container.js";
+export * from "./start.js";

package/dist/daemon/start.d.ts

@@ -0,0 +1,52 @@
+import { type RunProcessHandle, type RunSpawner } from "./daemon.js";
+import { detectContainerRuntime } from "./container.js";
+import type { RunnerIdentity } from "./identity.js";
+export type IsolationMode = "container" | "host";
+export interface IsolationConfig {
+    /** `container` (default) = throwaway container per run; `host` = raw process, full machine access. */
+    mode: IsolationMode;
+    /** Container image ref (container mode). Defaults to the version-pinned ghcr.io/boardwalk-labs image. */
+    image?: string;
+    /** Container network mode (container mode). Defaults to `host` — preserves LAN/VPN/localhost reach. */
+    network?: string;
+    /** Extra host bind mounts to expose to the run (container mode). */
+    mounts?: readonly string[];
+}
+/** This package's version (the runner image tag is pinned to it). Read from package.json so a
+ *  release bump is one file. */
+export declare function packageVersion(): string;
+/** Default runner image ref — the version-pinned public image (base + this runtime). */
+export declare function defaultImage(): string;
+/** Raw-process spawner (the `--host` escape hatch): one Node process per run, full machine access.
+ *  Env = the platform contract + the claim's resolved vars over a minimal base (PATH + proxy knobs;
+ *  HOME = the run's workspace). */
+export declare function processSpawn(opts: {
+    entry: string;
+    env: Record<string, string>;
+    cwd: string;
+}): RunProcessHandle;
+/** Error thrown when container isolation is requested but no runtime is available — the caller
+ *  surfaces the message and exits (never silently drop to the unisolated path). */
+export declare class NoContainerRuntimeError extends Error {
+    constructor();
+}
+/** Pick the run spawner from the isolation config. Container is default; `host` is the escape hatch;
+ *  container-with-no-runtime throws {@link NoContainerRuntimeError}. */
+export declare function resolveSpawner(iso: IsolationConfig, log: (line: string) => void, detect?: typeof detectContainerRuntime): Promise<RunSpawner>;
+export interface StartRunnerOptions {
+    baseUrl: string;
+    identity: RunnerIdentity;
+    isolation: IsolationConfig;
+    workDir: string;
+    once?: boolean;
+    /** Progress line sink (stdout by default). */
+    log?: (line: string) => void;
+    /** Wire SIGINT/SIGTERM → drain (Ctrl-C finishes the current run; a second forces quit). Default on. */
+    handleSignals?: boolean;
+}
+/**
+ * Run the daemon to completion: resolve the spawner (isolation), poll → claim → execute → heartbeat,
+ * and drain cleanly on Ctrl-C. Both entry points call this after obtaining an identity, so there is
+ * exactly one implementation of the run loop + isolation decision.
+ */
+export declare function startRunner(opts: StartRunnerOptions): Promise<void>;

package/dist/daemon/start.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: Apache-2.0
+// startRunner — the ONE implementation of "run this machine as a runner". Both entry points
+// (`boardwalk-runner start` and the CLI's `boardwalk runner start`) obtain an identity their own
+// way (two-step token vs one-step management-API enrollment) and then call THIS. There is no second
+// copy of the daemon lifecycle, the isolation decision, or the drain handling to drift out of sync.
+//
+// Isolation is a `RunSpawner` choice: `container` (default) runs each run in a throwaway container;
+// `host` (the `--host` escape hatch) runs it as a raw child process with full machine access. A
+// future macOS/Windows native sandbox is simply a third RunSpawner behind this same seam.
+import { spawn as nodeSpawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+import { PoolClient } from "./pool_client.js";
+import { startDaemon } from "./daemon.js";
+import { createContainerSpawner, detectContainerRuntime } from "./container.js";
+/** This package's version (the runner image tag is pinned to it). Read from package.json so a
+ *  release bump is one file. */
+export function packageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+        if (typeof pkg === "object" && pkg !== null && "version" in pkg) {
+            const v = pkg.version;
+            if (typeof v === "string")
+                return v;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0";
+}
+/** Default runner image ref — the version-pinned public image (base + this runtime). */
+export function defaultImage() {
+    return `ghcr.io/boardwalk-labs/runner:${packageVersion()}`;
+}
+/** Raw-process spawner (the `--host` escape hatch): one Node process per run, full machine access.
+ *  Env = the platform contract + the claim's resolved vars over a minimal base (PATH + proxy knobs;
+ *  HOME = the run's workspace). */
+export function processSpawn(opts) {
+    const base = {};
+    for (const key of [
+        "PATH",
+        "LANG",
+        "NODE_USE_ENV_PROXY",
+        "HTTPS_PROXY",
+        "https_proxy",
+        "HTTP_PROXY",
+        "http_proxy",
+        "NO_PROXY",
+        "no_proxy",
+        "BOARDWALK_RUNNER_DEBUG",
+    ]) {
+        const v = process.env[key];
+        if (v !== undefined)
+            base[key] = v;
+    }
+    const child = nodeSpawn(process.execPath, [opts.entry], {
+        cwd: opts.cwd,
+        env: { ...base, HOME: opts.cwd, TMPDIR: path.join(opts.cwd, "..", "tmp"), ...opts.env },
+        stdio: "inherit",
+    });
+    const exit = new Promise((resolve) => {
+        child.on("exit", (code, signal) => {
+            resolve(code ?? (signal !== null ? 143 : 1));
+        });
+        child.on("error", () => {
+            resolve(1);
+        });
+    });
+    return {
+        wait: () => exit,
+        kill: () => {
+            child.kill("SIGTERM");
+        },
+    };
+}
+/** Error thrown when container isolation is requested but no runtime is available — the caller
+ *  surfaces the message and exits (never silently drop to the unisolated path). */
+export class NoContainerRuntimeError extends Error {
+    constructor() {
+        super("No container runtime found (looked for docker, podman). Self-hosted runs are containerized " +
+            "by default for isolation.\n" +
+            "  • Install Docker or Podman and make sure it's running, or\n" +
+            "  • pass --host to run without isolation (full machine access; trusted workflows only).");
+        this.name = "NoContainerRuntimeError";
+    }
+}
+/** Pick the run spawner from the isolation config. Container is default; `host` is the escape hatch;
+ *  container-with-no-runtime throws {@link NoContainerRuntimeError}. */
+export async function resolveSpawner(iso, log, detect = detectContainerRuntime) {
+    if (iso.mode === "host") {
+        log("Running WITHOUT isolation (--host): runs get full access to this machine as your user. " +
+            "Only run workflows you trust.\n");
+        return processSpawn;
+    }
+    const runtime = await detect();
+    if (runtime === null)
+        throw new NoContainerRuntimeError();
+    const image = iso.image ?? defaultImage();
+    // Linux: run as the invoking user so the bind-mounted workspace is writable. Docker Desktop
+    // (macOS/Windows) maps ownership via file sharing, so leave the image's user in place there.
+    const user = process.platform === "linux" && process.getuid !== undefined && process.getgid !== undefined
+        ? `${String(process.getuid())}:${String(process.getgid())}`
+        : undefined;
+    log(`Isolation: ${runtime} container (${image}); workspace-only + ${iso.network ?? "host"} network.\n`);
+    return createContainerSpawner({
+        runtime,
+        image,
+        ...(iso.network !== undefined ? { network: iso.network } : {}),
+        ...(iso.mounts !== undefined && iso.mounts.length > 0 ? { mounts: iso.mounts } : {}),
+        ...(user !== undefined ? { user } : {}),
+    });
+}
+/**
+ * Run the daemon to completion: resolve the spawner (isolation), poll → claim → execute → heartbeat,
+ * and drain cleanly on Ctrl-C. Both entry points call this after obtaining an identity, so there is
+ * exactly one implementation of the run loop + isolation decision.
+ */
+export async function startRunner(opts) {
+    const log = opts.log ?? ((line) => void process.stdout.write(line));
+    const spawn = await resolveSpawner(opts.isolation, log);
+    // Process mode imports this entry directly; container mode ignores it (the image's entrypoint runs
+    // the runtime), but the daemon still passes it through the spawner interface.
+    const runtimeEntry = fileURLToPath(new URL("../runtime/main.js", import.meta.url));
+    const client = new PoolClient({ baseUrl: opts.baseUrl, runnerToken: opts.identity.runner_token });
+    const daemon = startDaemon({
+        client,
+        runtimeEntry,
+        workDir: opts.workDir,
+        runnerId: opts.identity.runner_id,
+        spawn,
+        ...(opts.once === true ? { once: true } : {}),
+    });
+    if (opts.handleSignals !== false) {
+        let interrupts = 0;
+        for (const signal of ["SIGINT", "SIGTERM"]) {
+            process.on(signal, () => {
+                interrupts += 1;
+                if (interrupts === 1) {
+                    log("\nDraining: finishing the current run, claiming nothing new. Ctrl-C again to force-quit.\n");
+                    daemon.drain();
+                }
+                else {
+                    process.exit(130);
+                }
+            });
+        }
+    }
+    log(`Runner ${opts.identity.name} online in pool '${opts.identity.pool}'. Waiting for runs...\n`);
+    await daemon.done;
+}

package/dist/runtime/identity_relay.d.ts

@@ -0,0 +1,54 @@
+import type { Duplex } from "node:stream";
+import { z } from "zod";
+/** Env var naming the inherited relay fd. Set by the guest init; absent everywhere else
+ *  (Fargate, self-hosted daemon), where the worker env-boots as always. */
+export declare const RELAY_FD_ENV = "BOARDWALK_IDENTITY_RELAY_FD";
+/** The identity payload — the env contract's fields, as JSON instead of env vars. */
+export declare const relayIdentitySchema: z.ZodObject<{
+    run_id: z.ZodString;
+    control_plane_url: z.ZodString;
+    run_token: z.ZodString;
+    api_token: z.ZodOptional<z.ZodString>;
+    task_cpu_units: z.ZodOptional<z.ZodNumber>;
+    byo_providers: z.ZodOptional<z.ZodUnknown>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type RelayIdentity = z.infer<typeof relayIdentitySchema>;
+/**
+ * Read the relay fd from `env`, deleting the key (bootstrap-only plumbing; run code has no
+ * business seeing it). Returns null when unset — the normal env-boot path.
+ */
+export declare function relayFdFromEnv(env: NodeJS.ProcessEnv): number | null;
+/**
+ * Map a relayed identity onto `env` for `capturePlatformContext`. User env lands FIRST and
+ * the platform keys LAST, so nothing user-supplied can shadow a platform value.
+ */
+export declare function applyIdentityToEnv(identity: RelayIdentity, env: NodeJS.ProcessEnv): void;
+/** One end of the init↔worker relay. Wraps any Duplex so tests run over in-memory streams. */
+export declare class IdentityRelay {
+    private readonly stream;
+    private buffer;
+    private closed;
+    private wake;
+    constructor(stream: Duplex);
+    /** Announce the pre-identity park. Init forwards this as the base-snapshot gate. */
+    announceReady(): void;
+    /**
+     * Block until init relays the run identity. THIS is the point the base snapshot freezes:
+     * everything before it is generic warm-up shared by every run; everything after belongs
+     * to one run. Unknown message types are ignored (forward-compatible), malformed lines are
+     * logged and skipped (init is trusted; a torn line must not kill PID 1's only worker), but
+     * a malformed IDENTITY payload is a hard error — same as a missing env var today.
+     */
+    awaitIdentity(): Promise<RelayIdentity>;
+    /** Confirm capture. Init acks its host only after this arrives. */
+    acceptIdentity(): void;
+    private writeLine;
+    private readLine;
+}
+/**
+ * Open the relay over the inherited fd. Wrapping the fd in a net.Socket also marks it
+ * close-on-exec (libuv does this on adoption), so subprocesses the run later spawns cannot
+ * inherit the relay and speak to init.
+ */
+export declare function connectIdentityRelayFd(fd: number): IdentityRelay;

package/dist/runtime/identity_relay.js

@@ -0,0 +1,168 @@
+// Identity relay — the microVM bootstrap boundary.
+//
+// On Boardwalk's snapshot-based microVM substrate the worker starts BEFORE it has a run: the
+// guest init (PID 1) spawns it warm (Node up, this code loaded, parked pre-identity), the
+// platform snapshots the whole VM, and every run restores from that snapshot and INJECTS the
+// run identity over an in-guest relay instead of container env. The relay is an inherited
+// AF_UNIX socketpair; init tells us its fd via `BOARDWALK_IDENTITY_RELAY_FD`. Wire: one JSON
+// object per LF-terminated line —
+//
+//	{"type":"worker_ready"}                    worker → init   the pre-identity park is reached
+//	{"type":"identity","payload":{...}}        init → worker   the run identity (see schema below)
+//	{"type":"identity_accepted"}               worker → init   captured; init acks its host
+//
+// The payload carries exactly the platform env contract (snake_case) plus the resolved user
+// env; `applyIdentityToEnv` maps it onto `process.env` so `capturePlatformContext` runs
+// UNCHANGED afterward — same fields, same capture-and-delete discipline, two transports.
+// The stream stays open after identity: later platform phases speak suspend/wake over it.
+import { Socket } from "node:net";
+import { z } from "zod";
+import { createLogger } from "./support/index.js";
+const log = createLogger("identity_relay");
+/** Env var naming the inherited relay fd. Set by the guest init; absent everywhere else
+ *  (Fargate, self-hosted daemon), where the worker env-boots as always. */
+export const RELAY_FD_ENV = "BOARDWALK_IDENTITY_RELAY_FD";
+/** The identity payload — the env contract's fields, as JSON instead of env vars. */
+export const relayIdentitySchema = z.object({
+    run_id: z.string().min(1),
+    control_plane_url: z.string().min(1),
+    run_token: z.string().min(1),
+    api_token: z.string().optional(),
+    task_cpu_units: z.number().int().positive().optional(),
+    /** The BYO inference provider registry, verbatim (stringified into BOARDWALK_BYO_PROVIDERS). */
+    byo_providers: z.unknown().optional(),
+    /** Resolved NON-secret user env. Platform keys always win over these (applied last). */
+    env: z.record(z.string(), z.string()).optional(),
+});
+const relayMessageSchema = z.object({
+    type: z.string(),
+    payload: z.unknown().optional(),
+});
+/**
+ * Read the relay fd from `env`, deleting the key (bootstrap-only plumbing; run code has no
+ * business seeing it). Returns null when unset — the normal env-boot path.
+ */
+export function relayFdFromEnv(env) {
+    const raw = env[RELAY_FD_ENV];
+    Reflect.deleteProperty(env, RELAY_FD_ENV);
+    if (raw === undefined || raw.trim().length === 0)
+        return null;
+    const fd = Number(raw);
+    if (!Number.isInteger(fd) || fd < 3) {
+        throw new Error(`${RELAY_FD_ENV} must name an inherited fd (>= 3), got ${raw}`);
+    }
+    return fd;
+}
+/**
+ * Map a relayed identity onto `env` for `capturePlatformContext`. User env lands FIRST and
+ * the platform keys LAST, so nothing user-supplied can shadow a platform value.
+ */
+export function applyIdentityToEnv(identity, env) {
+    for (const [key, value] of Object.entries(identity.env ?? {})) {
+        env[key] = value;
+    }
+    env.RUN_ID = identity.run_id;
+    env.BOARDWALK_CONTROL_PLANE_URL = identity.control_plane_url;
+    env.BOARDWALK_RUN_TOKEN = identity.run_token;
+    if (identity.api_token !== undefined && identity.api_token.length > 0) {
+        env.BOARDWALK_API_KEY = identity.api_token;
+    }
+    if (identity.task_cpu_units !== undefined) {
+        env.BOARDWALK_TASK_CPU_UNITS = String(identity.task_cpu_units);
+    }
+    if (identity.byo_providers !== undefined) {
+        env.BOARDWALK_BYO_PROVIDERS = JSON.stringify(identity.byo_providers);
+    }
+}
+/** One end of the init↔worker relay. Wraps any Duplex so tests run over in-memory streams. */
+export class IdentityRelay {
+    stream;
+    buffer = "";
+    closed = false;
+    wake = null;
+    constructor(stream) {
+        this.stream = stream;
+        // One persistent listener for the relay's lifetime: a flowing stream DROPS chunks
+        // emitted while nobody listens, so attach-per-read would lose lines between reads.
+        stream.on("data", (chunk) => {
+            this.buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            this.wake?.();
+        });
+        const onClose = () => {
+            this.closed = true;
+            this.wake?.();
+        };
+        stream.on("end", onClose);
+        stream.on("error", onClose);
+    }
+    /** Announce the pre-identity park. Init forwards this as the base-snapshot gate. */
+    announceReady() {
+        this.writeLine({ type: "worker_ready" });
+    }
+    /**
+     * Block until init relays the run identity. THIS is the point the base snapshot freezes:
+     * everything before it is generic warm-up shared by every run; everything after belongs
+     * to one run. Unknown message types are ignored (forward-compatible), malformed lines are
+     * logged and skipped (init is trusted; a torn line must not kill PID 1's only worker), but
+     * a malformed IDENTITY payload is a hard error — same as a missing env var today.
+     */
+    async awaitIdentity() {
+        for (;;) {
+            const line = await this.readLine();
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                log.warn("relay_malformed_line_skipped", { length: line.length });
+                continue;
+            }
+            const message = relayMessageSchema.safeParse(parsed);
+            if (!message.success) {
+                log.warn("relay_malformed_message_skipped", {});
+                continue;
+            }
+            if (message.data.type !== "identity") {
+                log.warn("relay_unexpected_type_ignored", { type: message.data.type });
+                continue;
+            }
+            const identity = relayIdentitySchema.safeParse(message.data.payload);
+            if (!identity.success) {
+                throw new Error(`Relayed identity payload is invalid: ${identity.error.message}`);
+            }
+            return identity.data;
+        }
+    }
+    /** Confirm capture. Init acks its host only after this arrives. */
+    acceptIdentity() {
+        this.writeLine({ type: "identity_accepted" });
+    }
+    writeLine(message) {
+        this.stream.write(JSON.stringify(message) + "\n");
+    }
+    async readLine() {
+        for (;;) {
+            const newline = this.buffer.indexOf("\n");
+            if (newline >= 0) {
+                const line = this.buffer.slice(0, newline);
+                this.buffer = this.buffer.slice(newline + 1);
+                return line;
+            }
+            if (this.closed) {
+                throw new Error("identity relay closed before the run identity arrived");
+            }
+            await new Promise((resolve) => {
+                this.wake = resolve;
+            });
+            this.wake = null;
+        }
+    }
+}
+/**
+ * Open the relay over the inherited fd. Wrapping the fd in a net.Socket also marks it
+ * close-on-exec (libuv does this on adoption), so subprocesses the run later spawns cannot
+ * inherit the relay and speak to init.
+ */
+export function connectIdentityRelayFd(fd) {
+    return new IdentityRelay(new Socket({ fd, readable: true, writable: true }));
+}

package/dist/runtime/index.js

@@ -35,6 +35,7 @@ import { SecretRedactor } from "./agent/secret_redactor.js";
 import { RecordingSecretResolver } from "./recording_secret_resolver.js";
 import { EngineLeafExecutor } from "./leaf_executor.js";
 import { parseByoProviders } from "./direct_inference.js";
+import { applyIdentityToEnv, connectIdentityRelayFd, relayFdFromEnv } from "./identity_relay.js";
 import { WorkerWorkflowHost } from "./workflow_host.js";
 import { runProgramWorker, } from "./program_worker.js";
 import { RunnerControlClient } from "./runner_control_client.js";
@@ -484,6 +485,20 @@ export function capturePlatformContext(env) {
     return { runId, controlPlane, vcpus };
 }
 export async function main() {
+    // Relay-mode bootstrap (the snapshot-based microVM substrate): when the guest init handed
+    // us an identity relay fd, park here — warm, generic, pre-identity; this await is what the
+    // base snapshot freezes — until the run's identity arrives, then map it onto process.env
+    // so the capture below is transport-agnostic. Everywhere else (Fargate, self-hosted
+    // daemon) the fd is absent and the worker env-boots exactly as before. The post-restore
+    // uniqueness reseed will hook in at this boundary, before any run code executes.
+    const relayFd = relayFdFromEnv(process.env);
+    if (relayFd !== null) {
+        const relay = connectIdentityRelayFd(relayFd);
+        relay.announceReady();
+        const identity = await relay.awaitIdentity();
+        applyIdentityToEnv(identity, process.env);
+        relay.acceptIdentity();
+    }
     // Capture the platform context into private state and remove it from process.env BEFORE anything
     // else — so no user program / agent tool / subprocess we later spawn can read the run token or
     // API token (the run env/credential rules). WORKER_ID / WORKSPACE_ROOT are non-secret infra knobs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {