@cruxy/cli 0.12.0 → 0.13.0

package/dist/cli/commands/run.js

@@ -5,6 +5,7 @@ import { authMissingKey, shouldUseColor, usageError, } from "../../errors/index.
 import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { CheckpointService } from "../../checkpoint/index.js";
+import { SandboxService } from "../../sandbox/index.js";
 import { runInteractive } from "../repl.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
@@ -13,6 +14,7 @@ export function runCommand() {
         .description("run cruxy on a prompt (one-shot), or with no prompt for an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
         .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
+        .option("--sandbox", "run shell + test commands inside an isolated container (fails loud if no runtime)")
         .action(async (promptParts, opts) => {
         const prompt = promptParts.join(" ").trim();
         const t = themeForColor(shouldUseColor(process.stdout));
@@ -61,7 +63,23 @@ export function runCommand() {
         const checkpoints = config.checkpoint.enabled
             ? new CheckpointService({ root: process.cwd(), config })
             : undefined;
-        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints);
+        // Sandbox (C.16): opt-in via --sandbox or sandbox.enabled. Resolving the
+        // service probes the runtime and THROWS CRUXY_E_SANDBOX_UNAVAILABLE if it
+        // is missing — fail loud here, before the agent starts, rather than
+        // silently running un-sandboxed. When off, ctx.sandbox stays undefined and
+        // execution runs on the host, unchanged.
+        const sandboxEnabled = opts.sandbox ?? config.sandbox.enabled;
+        const sandbox = sandboxEnabled
+            ? await SandboxService.create({
+                config,
+                cwd: process.cwd(),
+                reporter: renderer,
+            })
+            : undefined;
+        if (sandbox) {
+            logger.info(t.muted(`sandbox: ${sandbox.runtimeName} (network ${config.sandbox.network})`));
+        }
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox);
         if (interactive) {
             await runInteractive(session, undefined, renderer, checkpoints);
             return;

package/dist/cli/session-factory.d.ts

@@ -1,6 +1,7 @@
 import type { CruxyConfig } from "../config/index.js";
 import type { ApprovalDecision } from "../approval/index.js";
 import type { CheckpointService } from "../checkpoint/index.js";
+import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
 import { type ApproveAction } from "../tools/index.js";
 import { Session } from "../agent/index.js";
@@ -23,4 +24,4 @@ export declare function withCheckpointGate(requestApproval: (action: ApproveActi
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService): Session;

package/dist/cli/session-factory.js

@@ -87,7 +87,7 @@ export function withCheckpointGate(requestApproval, checkpoints, cwd) {
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints) {
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints, sandbox) {
     const provider = createProvider({
         provider: config.model.provider,
         apiKey,
@@ -120,6 +120,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         git,
         projectInstructions,
         renderer,
+        sandbox,
         makeChildApproval: () => gate(new ApprovalService({ cwd, interactive: ttyInteractive, io })),
     });
     if (config.subagent.maxDepth > 0) {
@@ -136,7 +137,13 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             policy: planPolicy,
             io,
         });
-        const ctx = { cwd, config, logger, requestApproval: gate(approval) };
+        const ctx = {
+            cwd,
+            config,
+            logger,
+            requestApproval: gate(approval),
+            sandbox,
+        };
         const planRunner = ({ messages, projectInstructions, renderer: turnRenderer, }) => runPlanSession({
             provider,
             config,
@@ -166,7 +173,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         interactive: ttyInteractive,
         io,
     });
-    const ctx = { cwd, config, logger, requestApproval: gate(approval) };
+    const ctx = { cwd, config, logger, requestApproval: gate(approval), sandbox };
     return new Session({
         provider,
         registry: execRegistry,

package/dist/config/schema.d.ts

@@ -283,6 +283,62 @@ export declare const SubagentConfigSchema: z.ZodObject<{
         timeoutMs?: number | undefined;
     } | undefined;
 }>;
+/**
+ * Sandbox / container execution (C.16): defense-in-depth beneath the U.3 gate.
+ * When enabled, `run_command` and `run_tests` execute inside an isolated,
+ * network-denied, resource-capped, non-root container with only the project
+ * workdir mounted — never on the host directly. OFF by default (a container
+ * runtime isn't universal); turning it on is a hard promise, so if the runtime
+ * is missing execution FAILS LOUD rather than silently falling back to the host.
+ */
+export declare const SandboxConfigSchema: z.ZodObject<{
+    /** Master switch. When true, shell + test commands run in the sandbox. */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Base image the container runs. Must ship a POSIX `sh`. Pin by digest
+     * (`name@sha256:…`) where possible; cruxy never builds or substitutes one.
+     */
+    image: z.ZodDefault<z.ZodString>;
+    /**
+     * Egress policy. `none` denies all network (default deny); `host-loopback`
+     * permits reaching services on the host; `full` allows outbound. Anything
+     * other than `none` is a deliberate widening the user must opt into.
+     */
+    network: z.ZodDefault<z.ZodEnum<["none", "host-loopback", "full"]>>;
+    /** Memory cap (docker `--memory` syntax, e.g. `512m`, `2g`). */
+    memory: z.ZodDefault<z.ZodString>;
+    /** Process/thread cap (`--pids-limit`) — a fork-bomb guard. */
+    pids: z.ZodDefault<z.ZodNumber>;
+    /** CPU cap (docker `--cpus`, fractional allowed). */
+    cpus: z.ZodDefault<z.ZodNumber>;
+    /** Wall-clock timeout in ms; falls back to `shell.timeoutMs` when unset. */
+    timeout: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Extra bind mounts beyond the workdir + tmp, each `src:dst[:ro|:rw]`.
+     * Explicit by construction — the default exposes ONLY the workdir. The
+     * docker socket and the cruxy home are rejected here (see policy.ts).
+     */
+    mounts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    image: string;
+    enabled: boolean;
+    memory: string;
+    network: "none" | "host-loopback" | "full";
+    pids: number;
+    cpus: number;
+    mounts: string[];
+    timeout?: number | undefined;
+}, {
+    image?: string | undefined;
+    enabled?: boolean | undefined;
+    memory?: string | undefined;
+    network?: "none" | "host-loopback" | "full" | undefined;
+    pids?: number | undefined;
+    cpus?: number | undefined;
+    timeout?: number | undefined;
+    mounts?: string[] | undefined;
+}>;
+export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -551,6 +607,53 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         command?: string | undefined;
         captureBytes?: number | undefined;
     }>>;
+    sandbox: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When true, shell + test commands run in the sandbox. */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Base image the container runs. Must ship a POSIX `sh`. Pin by digest
+         * (`name@sha256:…`) where possible; cruxy never builds or substitutes one.
+         */
+        image: z.ZodDefault<z.ZodString>;
+        /**
+         * Egress policy. `none` denies all network (default deny); `host-loopback`
+         * permits reaching services on the host; `full` allows outbound. Anything
+         * other than `none` is a deliberate widening the user must opt into.
+         */
+        network: z.ZodDefault<z.ZodEnum<["none", "host-loopback", "full"]>>;
+        /** Memory cap (docker `--memory` syntax, e.g. `512m`, `2g`). */
+        memory: z.ZodDefault<z.ZodString>;
+        /** Process/thread cap (`--pids-limit`) — a fork-bomb guard. */
+        pids: z.ZodDefault<z.ZodNumber>;
+        /** CPU cap (docker `--cpus`, fractional allowed). */
+        cpus: z.ZodDefault<z.ZodNumber>;
+        /** Wall-clock timeout in ms; falls back to `shell.timeoutMs` when unset. */
+        timeout: z.ZodOptional<z.ZodNumber>;
+        /**
+         * Extra bind mounts beyond the workdir + tmp, each `src:dst[:ro|:rw]`.
+         * Explicit by construction — the default exposes ONLY the workdir. The
+         * docker socket and the cruxy home are rejected here (see policy.ts).
+         */
+        mounts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        image: string;
+        enabled: boolean;
+        memory: string;
+        network: "none" | "host-loopback" | "full";
+        pids: number;
+        cpus: number;
+        mounts: string[];
+        timeout?: number | undefined;
+    }, {
+        image?: string | undefined;
+        enabled?: boolean | undefined;
+        memory?: string | undefined;
+        network?: "none" | "host-loopback" | "full" | undefined;
+        pids?: number | undefined;
+        cpus?: number | undefined;
+        timeout?: number | undefined;
+        mounts?: string[] | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -634,6 +737,16 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         captureBytes: number;
         command?: string | undefined;
     };
+    sandbox: {
+        image: string;
+        enabled: boolean;
+        memory: string;
+        network: "none" | "host-loopback" | "full";
+        pids: number;
+        cpus: number;
+        mounts: string[];
+        timeout?: number | undefined;
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -709,6 +822,16 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         command?: string | undefined;
         captureBytes?: number | undefined;
     } | undefined;
+    sandbox?: {
+        image?: string | undefined;
+        enabled?: boolean | undefined;
+        memory?: string | undefined;
+        network?: "none" | "host-loopback" | "full" | undefined;
+        pids?: number | undefined;
+        cpus?: number | undefined;
+        timeout?: number | undefined;
+        mounts?: string[] | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -194,6 +194,45 @@ export const SubagentConfigSchema = z
         .default({}),
 })
     .strict();
+/**
+ * Sandbox / container execution (C.16): defense-in-depth beneath the U.3 gate.
+ * When enabled, `run_command` and `run_tests` execute inside an isolated,
+ * network-denied, resource-capped, non-root container with only the project
+ * workdir mounted — never on the host directly. OFF by default (a container
+ * runtime isn't universal); turning it on is a hard promise, so if the runtime
+ * is missing execution FAILS LOUD rather than silently falling back to the host.
+ */
+export const SandboxConfigSchema = z
+    .object({
+    /** Master switch. When true, shell + test commands run in the sandbox. */
+    enabled: z.boolean().default(false),
+    /**
+     * Base image the container runs. Must ship a POSIX `sh`. Pin by digest
+     * (`name@sha256:…`) where possible; cruxy never builds or substitutes one.
+     */
+    image: z.string().min(1).default("node:20-bookworm-slim"),
+    /**
+     * Egress policy. `none` denies all network (default deny); `host-loopback`
+     * permits reaching services on the host; `full` allows outbound. Anything
+     * other than `none` is a deliberate widening the user must opt into.
+     */
+    network: z.enum(["none", "host-loopback", "full"]).default("none"),
+    /** Memory cap (docker `--memory` syntax, e.g. `512m`, `2g`). */
+    memory: z.string().min(1).default("512m"),
+    /** Process/thread cap (`--pids-limit`) — a fork-bomb guard. */
+    pids: z.number().int().positive().default(512),
+    /** CPU cap (docker `--cpus`, fractional allowed). */
+    cpus: z.number().positive().default(1),
+    /** Wall-clock timeout in ms; falls back to `shell.timeoutMs` when unset. */
+    timeout: z.number().int().positive().optional(),
+    /**
+     * Extra bind mounts beyond the workdir + tmp, each `src:dst[:ro|:rw]`.
+     * Explicit by construction — the default exposes ONLY the workdir. The
+     * docker socket and the cruxy home are rejected here (see policy.ts).
+     */
+    mounts: z.array(z.string().min(1)).default([]),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -216,6 +255,7 @@ export const CruxyConfigSchema = z
     checkpoint: CheckpointConfigSchema.default({}),
     subagent: SubagentConfigSchema.default({}),
     test: TestConfigSchema.default({}),
+    sandbox: SandboxConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/errors/constructors.d.ts

@@ -25,6 +25,27 @@ export declare function permissionDenied(path: string, underlying?: unknown): Cr
 export declare function indexEmbedderUnavailable(underlying?: unknown): CruxyError;
 export declare function indexStoreUnavailable(underlying?: unknown): CruxyError;
 export declare function indexFailed(underlying?: unknown): CruxyError;
+/**
+ * Sandboxing was requested (`--sandbox` / `sandbox.enabled`) but no container
+ * runtime is available — docker isn't installed, or its daemon isn't running.
+ * THE CRITICAL RULE: this is fatal. A user who turned on the sandbox must never
+ * be silently dropped back onto un-sandboxed host execution, so we fail loud
+ * here rather than run the command anyway.
+ */
+export declare function sandboxUnavailable(runtime?: string, underlying?: unknown): CruxyError;
+/**
+ * The pinned sandbox base image could not be made available (the first-run
+ * pull failed, or the image does not exist). Fatal — without the image there
+ * is nothing to execute inside, and we never substitute another image.
+ */
+export declare function sandboxImage(image: string, underlying?: unknown): CruxyError;
+/**
+ * The container itself failed to start or run (a docker-level failure — bad
+ * flags, daemon error, `docker run` exit 125), as opposed to the command
+ * inside exiting non-zero (which is an ordinary result). Fatal: a sandbox that
+ * can't launch is never papered over with a host run.
+ */
+export declare function sandboxExec(underlying?: unknown): CruxyError;
 /**
  * A side-effecting action needs approval but cruxy can't ask (non-interactive,
  * no policy). Default-deny — never auto-approve. A distinct exit code (10) so CI

package/dist/errors/constructors.js

@@ -224,6 +224,64 @@ export function indexFailed(underlying) {
         underlying,
     });
 }
+// ── sandbox (exit 12) ─────────────────────────────────────────────────────────
+/**
+ * Sandboxing was requested (`--sandbox` / `sandbox.enabled`) but no container
+ * runtime is available — docker isn't installed, or its daemon isn't running.
+ * THE CRITICAL RULE: this is fatal. A user who turned on the sandbox must never
+ * be silently dropped back onto un-sandboxed host execution, so we fail loud
+ * here rather than run the command anyway.
+ */
+export function sandboxUnavailable(runtime = "docker", underlying) {
+    return new CruxyError({
+        code: ErrorCode.SandboxUnavailable,
+        title: `sandbox is enabled but the ${runtime} runtime is unavailable`,
+        cause: messageOf(underlying) ??
+            `${runtime} is not installed or its daemon is not reachable`,
+        nextSteps: [
+            `install ${runtime} and make sure its daemon is running`,
+            "or disable the sandbox: `cruxy config set sandbox.enabled false` (or drop --sandbox)",
+        ],
+        underlying,
+        meta: { runtime },
+    });
+}
+/**
+ * The pinned sandbox base image could not be made available (the first-run
+ * pull failed, or the image does not exist). Fatal — without the image there
+ * is nothing to execute inside, and we never substitute another image.
+ */
+export function sandboxImage(image, underlying) {
+    return new CruxyError({
+        code: ErrorCode.SandboxImage,
+        title: `could not pull the sandbox image "${image}"`,
+        cause: messageOf(underlying),
+        nextSteps: [
+            "check the image name/tag and your network access to the registry",
+            'set a reachable image, e.g. `cruxy config set sandbox.image "node:20-bookworm-slim"`',
+        ],
+        underlying,
+        meta: { image },
+    });
+}
+/**
+ * The container itself failed to start or run (a docker-level failure — bad
+ * flags, daemon error, `docker run` exit 125), as opposed to the command
+ * inside exiting non-zero (which is an ordinary result). Fatal: a sandbox that
+ * can't launch is never papered over with a host run.
+ */
+export function sandboxExec(underlying) {
+    return new CruxyError({
+        code: ErrorCode.SandboxExec,
+        title: "the sandbox container failed to start",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "re-run with --verbose for the underlying docker error",
+            "verify the docker daemon is healthy (`docker info`)",
+        ],
+        underlying,
+    });
+}
 // ── approval (exit 10) ────────────────────────────────────────────────────────
 /**
  * A side-effecting action needs approval but cruxy can't ask (non-interactive,

package/dist/errors/types.d.ts

@@ -52,6 +52,11 @@ export declare const ErrorCode: {
     readonly TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND";
     /** Carried inside a run_tests result (informational) — never fatal by itself. */
     readonly TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT";
+    /** Sandbox was enabled but no container runtime is available — fail loud,
+     * NEVER fall back to un-sandboxed host execution. */
+    readonly SandboxUnavailable: "CRUXY_E_SANDBOX_UNAVAILABLE";
+    readonly SandboxImage: "CRUXY_E_SANDBOX_IMAGE";
+    readonly SandboxExec: "CRUXY_E_SANDBOX_EXEC";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -64,6 +64,12 @@ export const ErrorCode = {
     TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND",
     /** Carried inside a run_tests result (informational) — never fatal by itself. */
     TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT",
+    // sandbox (exit 12)
+    /** Sandbox was enabled but no container runtime is available — fail loud,
+     * NEVER fall back to un-sandboxed host execution. */
+    SandboxUnavailable: "CRUXY_E_SANDBOX_UNAVAILABLE",
+    SandboxImage: "CRUXY_E_SANDBOX_IMAGE",
+    SandboxExec: "CRUXY_E_SANDBOX_EXEC",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -112,6 +118,11 @@ const EXIT_CODES = {
     // surfaces inside a run_tests result and is never fatal by itself.
     [ErrorCode.TestCommandNotFound]: 2,
     [ErrorCode.TestIterationLimit]: 11,
+    // A requested sandbox that can't be honored is fatal (fail loud, no host
+    // fallback) — its own exit code so CI/scripts can tell it apart.
+    [ErrorCode.SandboxUnavailable]: 12,
+    [ErrorCode.SandboxImage]: 12,
+    [ErrorCode.SandboxExec]: 12,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/sandbox/detect.d.ts

@@ -0,0 +1,22 @@
+import type { SandboxCapability } from "./types.js";
+/**
+ * Runtime detection (C.16): a container runtime is a *capability*, not an
+ * assumption. Presence means both that the binary exists AND its daemon
+ * answers — `docker` installed with a dead daemon is NOT available, and the
+ * caller must fail loud rather than pretend a box exists.
+ */
+/** Injectable probe seam — spawns a short command and reports how it exited. */
+export type RuntimeProbe = (bin: string, args: string[]) => Promise<{
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Detect the Docker runtime. `docker version --format {{.Server.Version}}`
+ * exits non-zero when the daemon is unreachable (even though the client is
+ * installed), so a zero exit with a server version is the honest "available"
+ * signal. Memoized for the process; pass a probe (tests) to bypass the cache.
+ */
+export declare function detectDocker(probe?: RuntimeProbe): Promise<SandboxCapability>;
+/** Clear the memoized capability (tests). */
+export declare function resetDetectionCache(): void;

package/dist/sandbox/detect.js

@@ -0,0 +1,67 @@
+import { spawn } from "node:child_process";
+/** Default probe: spawn the binary, capture output, treat a spawn error (e.g.
+ * ENOENT — binary missing) as a non-zero exit rather than a throw. */
+const spawnProbe = (bin, args) => new Promise((resolve) => {
+    let child;
+    try {
+        child = spawn(bin, args);
+    }
+    catch (err) {
+        resolve({ code: null, stdout: "", stderr: err.message });
+        return;
+    }
+    let out = "";
+    let errText = "";
+    let settled = false;
+    const done = (code, stderr = errText) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve({ code, stdout: out, stderr });
+    };
+    // The daemon can hang; a probe must never wedge startup.
+    const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        done(null, "timed out probing the runtime");
+    }, PROBE_TIMEOUT_MS);
+    timer.unref?.();
+    child.stdout?.on("data", (b) => (out += b.toString("utf8")));
+    child.stderr?.on("data", (b) => (errText += b.toString("utf8")));
+    child.on("error", (err) => done(null, err.message));
+    child.on("close", (code) => {
+        clearTimeout(timer);
+        done(code);
+    });
+});
+const PROBE_TIMEOUT_MS = 5000;
+let cached;
+/**
+ * Detect the Docker runtime. `docker version --format {{.Server.Version}}`
+ * exits non-zero when the daemon is unreachable (even though the client is
+ * installed), so a zero exit with a server version is the honest "available"
+ * signal. Memoized for the process; pass a probe (tests) to bypass the cache.
+ */
+export function detectDocker(probe) {
+    if (probe)
+        return probeDocker(probe);
+    cached ??= probeDocker(spawnProbe);
+    return cached;
+}
+/** Clear the memoized capability (tests). */
+export function resetDetectionCache() {
+    cached = undefined;
+}
+async function probeDocker(probe) {
+    const { code, stdout, stderr } = await probe("docker", [
+        "version",
+        "--format",
+        "{{.Server.Version}}",
+    ]);
+    if (code === 0 && stdout.trim().length > 0) {
+        return { available: true, runtime: "docker" };
+    }
+    const detail = code === null
+        ? "the docker binary is not installed or not on PATH"
+        : (stderr.trim().split("\n")[0] ?? "docker daemon is not reachable");
+    return { available: false, runtime: "docker", detail };
+}

package/dist/sandbox/docker-runtime.d.ts

@@ -0,0 +1,32 @@
+import type { ExecOptions, ExecResult, IsolationPolicy, SandboxRuntime } from "./types.js";
+/**
+ * The shipped {@link SandboxRuntime}: shells out to the `docker` CLI (no SDK —
+ * matches the no-vendor-client ethos). {@link buildRunArgs} is a pure function
+ * so the entire isolation posture can be asserted from the argv without a live
+ * daemon; `exec` spawns docker, captures bias-capped output, enforces the
+ * wall-clock timeout by force-killing the container, and maps the result.
+ *
+ * The exit code from `docker run` is the command's own — EXCEPT `125`, which
+ * docker reserves for "the run itself failed" (bad flags, daemon error): that,
+ * and a spawn failure, are the only container-start failures, surfaced as a
+ * coded {@link sandboxExec} error. An ordinary non-zero command exit is a
+ * normal result (exit code is truth), never a thrown error and never a host run.
+ */
+export declare class DockerRuntime implements SandboxRuntime {
+    private readonly bin;
+    readonly name = "docker";
+    constructor(bin?: string);
+    ensureImage(image: string, onPull?: () => void): Promise<void>;
+    /** Run a non-container docker subcommand to completion, capturing output. */
+    private simpleRun;
+    exec(command: string, policy: IsolationPolicy, opts: ExecOptions): Promise<ExecResult>;
+    private run;
+    /** Best-effort container teardown after a timeout kill. */
+    private forceRemove;
+}
+/**
+ * Build the `docker run` argv from a resolved policy. Pure and total — the
+ * single source of truth for the isolation boundary, asserted directly in
+ * tests. Order is stable for readability; docker is order-insensitive for flags.
+ */
+export declare function buildRunArgs(policy: IsolationPolicy, container: string, command: string): string[];