@sandboxrouter/sdk 0.1.0 → 0.3.0

package/dist/providers/dedalus.js

@@ -0,0 +1,244 @@
+import { ProviderError } from "../types.js";
+import { dirname, shq, toBytes } from "../util.js";
+/**
+ * Dedalus Machines (Dedalus Labs, YC S25) over plain REST. Persistent Linux microVMs that sleep
+ * when idle and bill compute only while awake. The Machines API was in private beta when this was
+ * written: an org that has not been admitted gets a 403.
+ *
+ * https://dcs.dedaluslabs.ai, Authorization: Bearer <DEDALUS_API_KEY> (dsk_...):
+ *   POST   /v1/machines {vcpu, memory_mib, storage_gib, autosleep}   -> {machine_id, phase, ...}
+ *   GET    /v1/machines/:id         -> {machine_id, desired_state, status:{phase, reason, last_error}}
+ *   POST   /v1/machines/:id/sleep, POST /v1/machines/:id/wake, DELETE /v1/machines/:id
+ *   POST   /v1/machines/:id/executions {command:[argv], cwd, env, stdin, timeout_ms}
+ *                                   -> {execution_id, status}
+ *   GET    /v1/machines/:id/executions/:eid          -> {status, exit_code, signal, error_code, error_message}
+ *   GET    /v1/machines/:id/executions/:eid/events?cursor=  -> {items:[{type, chunk, status, exit_code}], next_cursor}
+ *   GET    /v1/machines/:id/executions/:eid/output   -> {stdout, stderr, stdout_truncated, stderr_truncated}
+ * Execution status: wake_in_progress, queued, running, succeeded, failed, cancelled, expired.
+ * Machine phase: accepted, placement_pending, starting, running, stopping, sleeping, destroying,
+ * destroyed, failed. Errors are {error_code, message, retryable} or problem+json {title, detail}.
+ * There is no file API, so files move through an execution's stdin and stdout as base64.
+ * There is no image choice: every machine is the same Linux base.
+ * Docs: https://docs.dedaluslabs.ai/dcs/dm/quickstart, https://docs.dedaluslabs.ai/dcs/dm/lifecycle,
+ *       https://docs.dedaluslabs.ai/dcs/dm/executions, https://docs.dedaluslabs.ai/dcs/dm/pricing,
+ *       https://docs.dedaluslabs.ai/dcs-openapi.json
+ */
+const ID = "dedalus";
+const READY_TIMEOUT_MS = 5 * 60_000;
+const POLL_MS = 250;
+const TERMINAL = new Set(["succeeded", "failed", "cancelled", "expired"]);
+/** The API returns at most this much of each stream inline from /output; longer output is flagged truncated. */
+const OUTPUT_CAP = 64 * 1024;
+/** Raw bytes per readFile chunk: base64 with line breaks (45 KiB -> about 61 KiB) stays under OUTPUT_CAP. */
+const READ_CHUNK = 45 * 1024;
+export class DedalusProvider {
+    apiKey;
+    baseUrl;
+    id = ID;
+    constructor(apiKey = process.env.DEDALUS_API_KEY, baseUrl = process.env.DEDALUS_MACHINES_URL ?? "https://dcs.dedaluslabs.ai") {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    /** @internal */
+    async api(method, path, json) {
+        if (!this.apiKey)
+            throw new ProviderError(ID, "DEDALUS_API_KEY is not set");
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${this.apiKey}`, ...(json !== undefined ? { "Content-Type": "application/json" } : {}) },
+            body: json !== undefined ? JSON.stringify(json) : undefined,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            let detail = text.slice(0, 300);
+            try {
+                const j = JSON.parse(text);
+                detail = j?.message ? `${j.error_code ? `${j.error_code}: ` : ""}${j.message}` : (j?.detail ?? j?.title ?? detail);
+            }
+            catch {
+                /* plain-text body */
+            }
+            throw new ProviderError(ID, `${method} ${path.split("?")[0]} -> ${res.status} ${detail}`, res.status);
+        }
+        return (text ? JSON.parse(text) : {});
+    }
+    async create(spec) {
+        const minutes = spec.timeoutMinutes ?? 30;
+        const m = await this.api("POST", "/v1/machines", {
+            vcpu: spec.vcpu ?? 2,
+            memory_mib: Math.round((spec.memoryGb ?? 4) * 1024),
+            storage_gib: 10,
+            // Sleep (compute billing stops, disk kept) once idle for the requested lifetime.
+            autosleep: `${Math.max(60, Math.round(minutes * 60))}s`,
+        });
+        if (!m.machine_id)
+            throw new ProviderError(ID, "create returned no machine_id");
+        const box = new DedalusBox(this, m.machine_id, spec.env ?? {});
+        try {
+            await box.waitRunning();
+        }
+        catch (err) {
+            await box.kill().catch(() => { });
+            throw err;
+        }
+        return box;
+    }
+    async connect(nativeId) {
+        const box = new DedalusBox(this, nativeId, {});
+        await box.waitRunning();
+        return box;
+    }
+}
+class DedalusBox {
+    p;
+    nativeId;
+    env;
+    constructor(p, nativeId, env) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.env = env;
+    }
+    get path() {
+        return `/v1/machines/${encodeURIComponent(this.nativeId)}`;
+    }
+    /** Poll until the machine runs, waking it if it sleeps. */
+    async waitRunning() {
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        let woke = false;
+        for (;;) {
+            const m = await this.p.api("GET", this.path);
+            const phase = m.status?.phase ?? m.phase ?? "";
+            if (phase === "running")
+                return;
+            if (phase === "failed" || phase === "destroyed" || phase === "destroying") {
+                const why = m.status?.last_error || m.status?.reason;
+                throw new ProviderError(ID, `machine ${this.nativeId} is ${phase}${why ? `: ${why}` : ""}`, phase === "failed" ? undefined : 404);
+            }
+            if (phase === "sleeping" && !woke) {
+                await this.p.api("POST", `${this.path}/wake`);
+                woke = true;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError(ID, `machine ${this.nativeId} not running after ${READY_TIMEOUT_MS / 1000}s (${phase || "unknown"})`);
+            await sleep(POLL_MS);
+        }
+    }
+    /** Run argv to completion, streaming stdout/stderr from the events feed. */
+    async run(command, opts) {
+        const t0 = Date.now();
+        const secs = opts.timeoutSeconds ?? 60;
+        const env = { ...this.env, ...opts.env };
+        const created = await this.p.api("POST", `${this.path}/executions`, {
+            command,
+            ...(opts.cwd ? { cwd: opts.cwd } : {}),
+            ...(Object.keys(env).length ? { env } : {}),
+            ...(opts.stdin !== undefined ? { stdin: opts.stdin } : {}),
+            timeout_ms: secs * 1000,
+        });
+        const eid = created.execution_id;
+        if (!eid)
+            throw new ProviderError(ID, "create execution returned no execution_id");
+        const ex = `${this.path}/executions/${encodeURIComponent(eid)}`;
+        // A wake can sit in front of the command, so allow extra time before giving up locally.
+        const deadline = t0 + secs * 1000 + 30_000;
+        let status = created.status ?? "";
+        const streaming = !!(opts.onStdout || opts.onStderr);
+        // Everything the events feed delivered so far, kept so output past the /output cap is still complete.
+        let eventsOut = "";
+        let eventsErr = "";
+        let cursor;
+        // A page may come back without next_cursor (it is optional); the next drain then re-reads the
+        // same page, so remember how many of its items were already consumed.
+        let consumedAtCursor = 0;
+        /** Read every events page from the cursor on, passing output chunks to the callbacks. */
+        const drain = async () => {
+            for (;;) {
+                const q = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
+                const page = await this.p.api("GET", `${ex}/events${q}`);
+                const items = (page.items ?? []).slice(consumedAtCursor);
+                for (const e of items) {
+                    if (e.type === "stdout" && e.chunk)
+                        (eventsOut += e.chunk), opts.onStdout?.(e.chunk);
+                    else if (e.type === "stderr" && e.chunk)
+                        (eventsErr += e.chunk), opts.onStderr?.(e.chunk);
+                    else if (e.type === "lifecycle" && e.status)
+                        status = e.status;
+                }
+                const next = page.next_cursor;
+                if (!next || next === cursor) {
+                    consumedAtCursor += items.length;
+                    return;
+                }
+                cursor = next;
+                consumedAtCursor = 0;
+                if (!items.length)
+                    return;
+            }
+        };
+        while (!TERMINAL.has(status)) {
+            if (Date.now() > deadline) {
+                await this.p.api("DELETE", ex).catch(() => { });
+                throw new ProviderError(ID, `command timed out after ${secs}s`);
+            }
+            await sleep(POLL_MS);
+            if (streaming)
+                await drain();
+            if (!TERMINAL.has(status))
+                status = (await this.p.api("GET", ex)).status ?? status;
+        }
+        const final = await this.p.api("GET", ex);
+        // Deliver anything written between the last events page and the end.
+        if (streaming)
+            await drain();
+        const durationMs = Date.now() - t0;
+        const why = `${final.error_code ?? ""} ${final.error_message ?? ""}`;
+        if (final.status === "expired" || /timeout|timed out|deadline/i.test(why) || (final.signal && durationMs >= secs * 1000)) {
+            throw new ProviderError(ID, `command timed out after ${secs}s`);
+        }
+        if (final.exit_code === undefined || final.exit_code === null) {
+            throw new ProviderError(ID, `command ${final.status ?? "ended"} without an exit code${why.trim() ? `: ${why.trim()}` : ""}`);
+        }
+        const out = await this.p.api("GET", `${ex}/output`);
+        if (!out.stdout_truncated && !out.stderr_truncated)
+            return { exitCode: final.exit_code, stdout: out.stdout ?? "", stderr: out.stderr ?? "", durationMs };
+        // /output cut a stream at OUTPUT_CAP: the events feed has all of it.
+        if (!streaming)
+            await drain();
+        return { exitCode: final.exit_code, stdout: eventsOut, stderr: eventsErr, durationMs };
+    }
+    exec(cmd, opts = {}) {
+        return this.run(["/bin/sh", "-c", cmd], opts);
+    }
+    async writeFile(path, content) {
+        const b64 = Buffer.from(toBytes(content)).toString("base64");
+        const r = await this.run(["/bin/sh", "-c", `mkdir -p ${shq(dirname(path))} && base64 -d > ${shq(path)}`], { stdin: b64, timeoutSeconds: 120 });
+        if (r.exitCode !== 0)
+            throw new ProviderError(ID, `write ${path}: ${r.stderr.trim() || `exit ${r.exitCode}`}`);
+    }
+    async readFile(path) {
+        const size = await this.run(["/bin/sh", "-c", `wc -c < ${shq(path)}`], {});
+        if (size.exitCode !== 0)
+            throw new ProviderError(ID, `read ${path}: ${size.stderr.trim() || "no such file"}`, 404);
+        const total = Number(size.stdout.trim());
+        const parts = [];
+        for (let off = 0; off < total; off += READ_CHUNK) {
+            const r = await this.run(["/bin/sh", "-c", `tail -c +${off + 1} ${shq(path)} | head -c ${READ_CHUNK} | base64`], { timeoutSeconds: 120 });
+            if (r.exitCode !== 0)
+                throw new ProviderError(ID, `read ${path}: ${r.stderr.trim() || `exit ${r.exitCode}`}`);
+            parts.push(Buffer.from(r.stdout.replace(/\s+/g, ""), "base64"));
+        }
+        return new Uint8Array(Buffer.concat(parts));
+    }
+    async pause() {
+        await this.p.api("POST", `${this.path}/sleep`);
+    }
+    async kill() {
+        await this.p.api("DELETE", `${this.path}?force=true`);
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/providers/deno.d.ts

@@ -0,0 +1,50 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+export declare const DENO_VCPU = 2;
+/** The parts of `@deno/sandbox` this adapter uses (local types: the package is optional). */
+interface DenoChild {
+    stdout: ReadableStream<Uint8Array> | null;
+    stderr: ReadableStream<Uint8Array> | null;
+    status: Promise<{
+        code: number;
+        signal: string | null;
+        success: boolean;
+    }>;
+    kill(signal?: string): Promise<void>;
+}
+interface DenoSdkSandbox {
+    readonly id: string;
+    spawn(command: string, options?: Record<string, unknown>): Promise<DenoChild>;
+    fs: {
+        writeFile(path: string, data: Uint8Array): Promise<void>;
+        readFile(path: string): Promise<Uint8Array>;
+        mkdir(path: string, options?: {
+            recursive?: boolean;
+        }): Promise<void>;
+    };
+    kill(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface DenoSdk {
+    Sandbox: {
+        create(options?: Record<string, unknown>): Promise<DenoSdkSandbox>;
+        connect(options: Record<string, unknown> & {
+            id: string;
+        }): Promise<DenoSdkSandbox>;
+    };
+}
+export declare class DenoProvider implements Provider {
+    private token;
+    private org;
+    private region;
+    /** @internal Loads the SDK; tests pass a fake. */
+    private load;
+    readonly id: "deno";
+    constructor(token?: string | undefined, org?: string | undefined, region?: string | undefined, 
+    /** @internal Loads the SDK; tests pass a fake. */
+    load?: () => Promise<DenoSdk>);
+    configured(): boolean;
+    private auth;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}
+export {};

package/dist/providers/deno.js

@@ -0,0 +1,170 @@
+import { ProviderError } from "../types.js";
+import { dirname, optionalImport, toBytes } from "../util.js";
+/**
+ * Deno Sandbox (Linux microVMs on Deno Deploy) via the official `@deno/sandbox` SDK. The SDK is
+ * required: sandboxes are driven over an SDK-private WebSocket RPC protocol that Deno does not
+ * document, so there is no plain REST path. Optional peer dependency: `@deno/sandbox` (>=0.13 <0.14,
+ * a 0.x API; verified against 0.13.2).
+ * Auth: DENO_DEPLOY_TOKEN, an organization token (ddo_...), or a personal token (ddp_...) plus
+ * DENO_DEPLOY_ORG. Sandboxes need a paid Deploy plan (Pro or Builder).
+ * Fixed limits (https://docs.deno.com/sandbox/#limits): 2 vCPU, 768-4096 MB memory (default
+ * 1280), 10 GB disk, lifetime up to 30 minutes, regions `ord` and `ams`. Outbound network is open
+ * unless allowNet is set. image.deno is a snapshot or volume id/slug used as the root filesystem.
+ * The default timeout ("session") would end the VM when this process disconnects, so the adapter
+ * always passes a duration, which is what lets connect() reattach. exec streams stdout/stderr from
+ * a spawned `/bin/sh -c`. No pause.
+ * Docs: https://docs.deno.com/sandbox/, https://docs.deno.com/sandbox/create/,
+ *       https://docs.deno.com/sandbox/timeouts/, https://docs.deno.com/sandbox/security/,
+ *       https://deno.com/sandbox (pricing), https://jsr.io/@deno/sandbox
+ */
+const ID = "deno";
+const MIN_MEMORY_MB = 768;
+const MAX_MEMORY_MB = 4096;
+const MAX_LIFETIME_MIN = 30;
+export const DENO_VCPU = 2;
+export class DenoProvider {
+    token;
+    org;
+    region;
+    load;
+    id = ID;
+    constructor(token = process.env.DENO_DEPLOY_TOKEN, org = process.env.DENO_DEPLOY_ORG, region = process.env.DENO_SANDBOX_REGION, 
+    /** @internal Loads the SDK; tests pass a fake. */
+    load = () => optionalImport("@deno/sandbox", "deno")) {
+        this.token = token;
+        this.org = org;
+        this.region = region;
+        this.load = load;
+    }
+    configured() {
+        return !!this.token && (this.token.startsWith("ddo_") || !!this.org);
+    }
+    auth() {
+        if (!this.token)
+            throw new ProviderError(ID, "DENO_DEPLOY_TOKEN is not set");
+        if (!this.token.startsWith("ddo_") && !this.org)
+            throw new ProviderError(ID, "a personal DENO_DEPLOY_TOKEN needs DENO_DEPLOY_ORG");
+        return { token: this.token, ...(this.org ? { org: this.org } : {}) };
+    }
+    async create(spec) {
+        const vcpu = spec.vcpu ?? 2;
+        if (vcpu > DENO_VCPU)
+            throw new ProviderError(ID, `Deno Sandbox has ${DENO_VCPU} vCPU, not ${vcpu}`);
+        const memoryMb = Math.ceil((spec.memoryGb ?? 4) * 1024);
+        if (memoryMb > MAX_MEMORY_MB)
+            throw new ProviderError(ID, `Deno Sandbox memory is at most ${MAX_MEMORY_MB} MB, not ${memoryMb}`);
+        const minutes = Math.min(MAX_LIFETIME_MIN, Math.max(1, Math.ceil(spec.timeoutMinutes ?? 30)));
+        const options = {
+            ...this.auth(),
+            memory: `${Math.max(MIN_MEMORY_MB, memoryMb)}MiB`,
+            timeout: `${minutes}m`,
+        };
+        if (this.region)
+            options.region = this.region;
+        if (spec.env)
+            options.env = spec.env;
+        if (spec.metadata)
+            options.labels = spec.metadata;
+        if (spec.image?.deno)
+            options.root = spec.image.deno;
+        const { Sandbox } = await this.load();
+        return new DenoBox(await sdk(() => Sandbox.create(options)));
+    }
+    async connect(nativeId) {
+        const { Sandbox } = await this.load();
+        return new DenoBox(await sdk(() => Sandbox.connect({ ...this.auth(), id: nativeId })));
+    }
+}
+class DenoBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.id;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const secs = opts.timeoutSeconds ?? 60;
+        const child = await sdk(() => this.sbx.spawn("/bin/sh", {
+            args: ["-c", cmd],
+            ...(opts.cwd ? { cwd: opts.cwd } : {}),
+            ...(opts.env ? { env: opts.env } : {}),
+            stdin: "null",
+            stdout: "piped",
+            stderr: "piped",
+        }));
+        let timedOut = false;
+        let giveUp;
+        // Killing the shell can leave its children holding stdout open, so stop waiting for the
+        // streams shortly after the kill instead of hanging until those children exit.
+        const abandoned = new Promise((_, reject) => {
+            giveUp = setTimeout(() => reject(new ProviderError(ID, `command timed out after ${secs}s`)), secs * 1000 + 1000);
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL").catch(() => { });
+        }, secs * 1000);
+        try {
+            const [stdout, stderr, status] = await Promise.race([
+                Promise.all([drain(child.stdout, opts.onStdout), drain(child.stderr, opts.onStderr), sdk(() => child.status)]),
+                abandoned,
+            ]);
+            if (timedOut)
+                throw new ProviderError(ID, `command timed out after ${secs}s`);
+            // Deno reports a signal death as the signal's name plus a negative code (minus its number);
+            // shells report 128 + n, so callers see the same code they would from any other provider.
+            const exitCode = status.signal ? 128 + (SIGNALS[status.signal] ?? Math.max(0, -status.code)) : status.code;
+            return { exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+        }
+        finally {
+            clearTimeout(timer);
+            clearTimeout(giveUp);
+        }
+    }
+    async writeFile(path, content) {
+        const dir = dirname(path);
+        if (dir !== "/" && dir !== path)
+            await sdk(() => this.sbx.fs.mkdir(dir, { recursive: true }));
+        await sdk(() => this.sbx.fs.writeFile(path, toBytes(content)));
+    }
+    async readFile(path) {
+        return new Uint8Array(await sdk(() => this.sbx.fs.readFile(path)));
+    }
+    async kill() {
+        await sdk(() => this.sbx.kill());
+    }
+}
+/** Read a byte stream to a string, passing each decoded chunk on as it arrives. */
+async function drain(stream, on) {
+    if (!stream)
+        return "";
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let out = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        const text = done ? decoder.decode() : decoder.decode(value, { stream: true });
+        if (text) {
+            out += text;
+            on?.(text);
+        }
+        if (done)
+            return out;
+    }
+}
+/** Run an SDK call, turning its errors into ProviderErrors with an HTTP-like status where known. */
+async function sdk(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof ProviderError)
+            throw err;
+        const msg = err?.message ?? String(err);
+        let status = typeof err?.status === "number" ? err.status : undefined;
+        if (status === undefined && (err?.name === "NotFound" || err?.code === "ENOENT" || /not found|no such file/i.test(msg)))
+            status = 404;
+        throw new ProviderError(ID, `${err?.name && err.name !== "Error" ? `${err.name}: ` : ""}${msg}`, status);
+    }
+}
+const SIGNALS = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6, SIGKILL: 9, SIGSEGV: 11, SIGPIPE: 13, SIGALRM: 14, SIGTERM: 15 };

package/dist/providers/docker.d.ts

@@ -0,0 +1,17 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Local sandboxes in Docker containers, through the `docker` CLI. Free and needs no account, so it
+ * is good for development and tests. A container shares your machine's kernel: it is weaker
+ * isolation than a cloud micro-VM, so don't point untrusted code at it with secrets mounted.
+ * Never chosen automatically; route to it with { provider: "docker" }.
+ */
+export declare class DockerProvider implements Provider {
+    private bin;
+    readonly id: "docker";
+    private available?;
+    constructor(bin?: string);
+    /** The docker CLI exists and its daemon answers. Cached for the life of the process. */
+    configured(): boolean;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/docker.js

@@ -0,0 +1,154 @@
+import { spawn, spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { DEFAULT_EXEC_TIMEOUT_S, dirname, guardTimeout, killedByTimeout, shq, timeoutError, toBytes } from "../util.js";
+/**
+ * Local sandboxes in Docker containers, through the `docker` CLI. Free and needs no account, so it
+ * is good for development and tests. A container shares your machine's kernel: it is weaker
+ * isolation than a cloud micro-VM, so don't point untrusted code at it with secrets mounted.
+ * Never chosen automatically; route to it with { provider: "docker" }.
+ */
+export class DockerProvider {
+    bin;
+    id = "docker";
+    available;
+    constructor(bin = process.env.SANDBOXROUTER_DOCKER_BIN ?? "docker") {
+        this.bin = bin;
+    }
+    /** The docker CLI exists and its daemon answers. Cached for the life of the process. */
+    configured() {
+        if (this.available === undefined) {
+            const r = spawnSync(this.bin, ["info", "--format", "{{.ServerVersion}}"], { timeout: 4000, encoding: "utf8" });
+            this.available = r.status === 0 && !!r.stdout.trim();
+        }
+        return this.available;
+    }
+    async create(spec) {
+        const name = `sbr-${randomUUID().slice(0, 12)}`;
+        const lifetime = Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60));
+        const args = [
+            "run",
+            "-d",
+            "--rm",
+            "--name",
+            name,
+            "--label",
+            "sandboxrouter=1",
+            "--cpus",
+            String(spec.vcpu ?? DEFAULT_VCPU),
+            "--memory",
+            `${Math.round((spec.memoryGb ?? DEFAULT_MEMORY_GB) * 1024)}m`,
+        ];
+        for (const [k, v] of Object.entries(spec.env ?? {}))
+            args.push("-e", `${k}=${v}`);
+        for (const [k, v] of Object.entries(spec.metadata ?? {}))
+            args.push("--label", `${k}=${v}`);
+        // The container's main process is a timer: it exits at the lifetime and --rm removes it.
+        args.push(spec.image?.docker ?? "python:3.12-slim", "sleep", String(lifetime));
+        const r = await run(this.bin, args);
+        if (r.code !== 0)
+            throw new ProviderError("docker", `docker run failed: ${r.stderr.trim().slice(0, 300)}`);
+        return new DockerBox(this.bin, name);
+    }
+    async connect(nativeId) {
+        const r = await run(this.bin, ["inspect", "-f", "{{.State.Status}}", nativeId]);
+        if (r.code !== 0)
+            throw new ProviderError("docker", `no container ${nativeId}`, 404);
+        if (r.stdout.trim() === "paused")
+            await run(this.bin, ["unpause", nativeId]);
+        return new DockerBox(this.bin, nativeId);
+    }
+}
+class DockerBox {
+    bin;
+    nativeId;
+    constructor(bin, nativeId) {
+        this.bin = bin;
+        this.nativeId = nativeId;
+    }
+    exec(cmd, opts = {}) {
+        const seconds = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
+        const args = ["exec", "-i"];
+        if (opts.cwd)
+            args.push("-w", opts.cwd);
+        for (const [k, v] of Object.entries(opts.env ?? {}))
+            args.push("-e", `${k}=${v}`);
+        // The command is killed inside the container: Docker does not stop an exec'd process when its
+        // client dies, so killing `docker exec` alone would leave it running. The client-side limit
+        // only covers a container that stops answering.
+        args.push(this.nativeId, "sh", "-c", guardTimeout(cmd, seconds));
+        return run(this.bin, args, { timeoutMs: (seconds + 10) * 1000, onStdout: opts.onStdout, onStderr: opts.onStderr }).then((r) => {
+            if (r.timedOut || killedByTimeout(r.code ?? -1, r.ms, seconds))
+                throw timeoutError("docker", seconds);
+            return { exitCode: r.code ?? -1, stdout: r.stdout, stderr: r.stderr, durationMs: r.ms };
+        });
+    }
+    async writeFile(path, content) {
+        const r = await run(this.bin, ["exec", "-i", this.nativeId, "sh", "-c", `mkdir -p ${shq(dirname(path))} && cat > ${shq(path)}`], {
+            stdin: toBytes(content),
+        });
+        if (r.code !== 0)
+            throw new ProviderError("docker", `write ${path} failed: ${r.stderr.trim().slice(0, 300)}`);
+    }
+    async readFile(path) {
+        const r = await run(this.bin, ["exec", this.nativeId, "cat", path], { binary: true });
+        if (r.code !== 0)
+            throw new ProviderError("docker", `read ${path} failed: ${r.stderr.trim().slice(0, 300)}`, 404);
+        return r.bytes;
+    }
+    async pause() {
+        const r = await run(this.bin, ["pause", this.nativeId]);
+        if (r.code !== 0)
+            throw new ProviderError("docker", `pause failed: ${r.stderr.trim()}`);
+    }
+    async kill() {
+        await run(this.bin, ["rm", "-f", this.nativeId]);
+    }
+}
+function run(bin, args, opts = {}) {
+    const t0 = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] });
+        const out = [];
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const dec = new TextDecoder();
+        const decErr = new TextDecoder();
+        child.stdout.on("data", (b) => {
+            if (opts.binary)
+                return void out.push(b);
+            const c = dec.decode(b, { stream: true });
+            stdout += c;
+            if (c)
+                opts.onStdout?.(c);
+        });
+        child.stderr.on("data", (b) => {
+            const c = decErr.decode(b, { stream: true });
+            stderr += c;
+            if (c)
+                opts.onStderr?.(c);
+        });
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, opts.timeoutMs)
+            : undefined;
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(new ProviderError("docker", `could not run ${bin}: ${e.message}`));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr, bytes: opts.binary ? new Uint8Array(Buffer.concat(out)) : undefined, ms: Date.now() - t0, timedOut });
+        });
+        // A command that exits before reading its stdin makes the pipe raise EPIPE; the exit code already tells the story.
+        child.stdin.on("error", () => { });
+        if (opts.stdin)
+            child.stdin.end(Buffer.from(opts.stdin));
+        else
+            child.stdin.end();
+    });
+}