@sandboxrouter/sdk 0.1.0 → 0.3.0

package/dist/providers/exedev.js

@@ -0,0 +1,290 @@
+import { randomBytes } from "node:crypto";
+import { ProviderError } from "../types.js";
+import { dirname, killedByTimeout, shq, timeoutError, toBytes, wrapCommand } from "../util.js";
+/**
+ * exe.dev standalone VMs over the HTTPS API (no SDK needed).
+ * Everything is one endpoint: POST https://exe.dev/exec, Authorization: Bearer exe1..., body = the
+ * command you would type at `ssh exe.dev`. Lifecycle commands answer JSON; `ssh <vm> <cmd>` runs a
+ * command in the VM and, with Accept: application/x-ndjson, answers {"stdout":b64} / {"stderr":b64}
+ * lines then {"exit_code":N} (or {"error":...}).
+ *   new --standalone --name=N --cpu=C --memory=MGB [--image=I] --json   create (metered per second)
+ *   ls --json                                                           list ({vms:[{vm_name,status,...}]})
+ *   ssh <vm> '<cmd>'                                                    run a command
+ *   rm <vm>                                                             delete; billing stops
+ * Limits of /exec: 30 s per request (504), 64 KB request body, no stdin, no pty. So exec runs the
+ * command detached on the VM (setsid nohup, as the docs suggest) and polls its output files, and
+ * files move as base64 inside commands, in chunks.
+ * The token must allow `new`, `ls`, `ssh` and `rm` (`ssh` and `rm` are not in the default cmds):
+ *   ssh exe.dev ssh-key generate-api-key --cmds=new,ls,ssh,rm --exp=30d
+ * Docs: https://exe.dev/docs/https-api.md, https://exe.dev/docs/https-api-run-on-vm.md,
+ *       https://exe.dev/docs/standalone-vms.md, https://exe.dev/docs/api.md
+ */
+const ID = "exedev";
+/** Leave headroom under the 64 KB body cap. */
+const MAX_BODY = 60_000;
+/** Raw bytes per writeFile chunk: base64 twice (4/3 * 4/3) plus the script stays under MAX_BODY. */
+const WRITE_CHUNK = 30_000;
+const VM_NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+export class ExeDevProvider {
+    token;
+    baseUrl;
+    id = ID;
+    constructor(token = process.env.EXE_TOKEN, baseUrl = process.env.EXE_API_URL ?? "https://exe.dev") {
+        this.token = token;
+        this.baseUrl = baseUrl;
+    }
+    configured() {
+        return !!this.token;
+    }
+    /** @internal POST /exec with a command line. */
+    async request(command, accept = "application/json") {
+        if (!this.token)
+            throw new ProviderError(ID, "EXE_TOKEN is not set");
+        if (Buffer.byteLength(command) > MAX_BODY)
+            throw new ProviderError(ID, `request body over the 64 KB /exec limit (${Buffer.byteLength(command)} bytes)`);
+        const res = await fetch(`${this.baseUrl}/exec`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.token}`, "Content-Type": "text/plain", Accept: accept },
+            body: command,
+        });
+        // A VM command with a nonzero exit still streams its NDJSON result.
+        if (!res.ok && !(accept.includes("ndjson") && res.headers.get("content-type")?.includes("ndjson"))) {
+            const text = await res.text();
+            let detail = text.slice(0, 300);
+            try {
+                const j = JSON.parse(text);
+                if (typeof j?.error === "string")
+                    detail = j.error;
+            }
+            catch {
+                /* plain-text body */
+            }
+            const verb = command.split(" ", 1)[0];
+            throw new ProviderError(ID, `/exec ${verb} -> ${res.status} ${detail}`, res.status);
+        }
+        return res;
+    }
+    /** @internal Lobby command with JSON output. */
+    async lobby(command) {
+        const text = await (await this.request(`${command} --json`)).text();
+        const j = (text ? JSON.parse(text) : {});
+        if (typeof j.error === "string")
+            throw new ProviderError(ID, `${command.split(" ", 1)[0]}: ${j.error}`);
+        return j;
+    }
+    /**
+     * @internal Run a shell script on the VM. The script is base64-encoded so it survives both quoting
+     * layers (the lobby's shell lexer, then the VM's shell) untouched.
+     */
+    async ssh(vm, script) {
+        const b64 = Buffer.from(script).toString("base64");
+        const res = await this.request(`ssh ${vm} 'bash -c "$(echo ${b64} | base64 -d)"'`, "application/x-ndjson");
+        const out = [];
+        const err = [];
+        let exitCode;
+        for await (const line of readLines(res)) {
+            const j = JSON.parse(line);
+            if (j.stdout !== undefined)
+                out.push(Buffer.from(j.stdout, "base64"));
+            if (j.stderr !== undefined)
+                err.push(Buffer.from(j.stderr, "base64"));
+            if (j.exit_code !== undefined)
+                exitCode = j.exit_code;
+            if (j.error !== undefined)
+                throw new ProviderError(ID, `ssh ${vm}: ${j.error}`);
+        }
+        if (exitCode === undefined)
+            throw new ProviderError(ID, `ssh ${vm}: response ended without an exit code`);
+        return { exitCode, stdout: Buffer.concat(out), stderr: Buffer.concat(err) };
+    }
+    async create(spec) {
+        // Standalone VMs take up to 2 GiB per vCPU, so raise the vCPUs when the memory asks for more.
+        const memoryGb = Math.max(1, Math.ceil(spec.memoryGb ?? 4));
+        const cpu = Math.max(1, Math.ceil(spec.vcpu ?? 2), Math.ceil(memoryGb / 2));
+        const name = `sbr-${randomBytes(6).toString("hex")}`;
+        const flags = [`--standalone`, `--name=${name}`, `--cpu=${cpu}`, `--memory=${memoryGb}GB`];
+        const image = spec.image?.exedev;
+        if (image) {
+            if (!/^[A-Za-z0-9._/:@-]+$/.test(image))
+                throw new ProviderError(ID, `invalid image reference: ${image}`);
+            flags.push(`--image=${image}`);
+        }
+        const vm = await this.lobby(`new ${flags.join(" ")}`);
+        const vmName = vm.vm_name ?? name;
+        const box = new ExeDevSandbox(this, vmName, spec.env);
+        try {
+            await box.waitForSsh();
+        }
+        catch (err) {
+            await box.kill().catch(() => { });
+            throw err;
+        }
+        // exe.dev has no lifetime setting, so the VM powers itself off when spec.timeoutMinutes runs out
+        // (a stopped VM bills disk only; kill() or `sandboxrouter gc` deletes it). Best effort: it needs
+        // root or passwordless sudo in the image (not yet confirmed on a real exe.dev VM).
+        const secs = Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60));
+        await this.ssh(vmName, `setsid nohup sh -c 'sleep ${secs}; sudo -n poweroff || poweroff' > /dev/null 2>&1 < /dev/null &`).catch(() => { });
+        return box;
+    }
+    async connect(nativeId) {
+        if (!VM_NAME.test(nativeId))
+            throw new ProviderError(ID, `invalid VM name: ${nativeId}`);
+        const { vms = [] } = await this.lobby("ls");
+        if (!vms.some((v) => v.vm_name === nativeId))
+            throw new ProviderError(ID, `VM ${nativeId} not found`, 404);
+        return new ExeDevSandbox(this, nativeId);
+    }
+}
+class ExeDevSandbox {
+    p;
+    nativeId;
+    env;
+    constructor(p, nativeId, env) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.env = env;
+    }
+    /** `new` returns once the VM exists; retry a no-op until sshd answers. */
+    async waitForSsh(timeoutMs = 120_000) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            try {
+                if ((await this.p.ssh(this.nativeId, "true")).exitCode === 0)
+                    return;
+            }
+            catch (err) {
+                if (err instanceof ProviderError && (err.status === 401 || err.status === 403))
+                    throw err;
+                if (Date.now() > deadline)
+                    throw err;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError(ID, `VM ${this.nativeId} did not accept commands within ${timeoutMs / 1000}s`);
+            await sleep(1000);
+        }
+    }
+    /**
+     * One /exec request lasts at most 30 s, so the command runs detached on the VM, writing to
+     * /tmp/.sbr-<id>/{out,err,exit}. Each request waits up to `wait` for it to finish, sends the output
+     * written since the last request, and either exits with the command's code (done) or ends stderr
+     * with a random marker (still running).
+     */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const timeout = Math.max(1, Math.round(opts.timeoutSeconds ?? 60));
+        const job = randomBytes(8).toString("hex");
+        const dir = `/tmp/.sbr-${job}`;
+        const marker = `__sandboxrouter_running_${job}__`;
+        const streaming = !!(opts.onStdout || opts.onStderr);
+        const waitTenths = streaming ? 10 : 200; // 1 s or 20 s per request
+        const full = wrapCommand(cmd, { cwd: opts.cwd, env: { ...this.env, ...opts.env } });
+        const cmdB64 = Buffer.from(full).toString("base64");
+        const report = (outOff, errOff) => [
+            `d=${dir}; i=0`,
+            `while [ ! -f "$d/exit" ] && [ $i -lt ${waitTenths} ]; do sleep 0.1; i=$((i+1)); done`,
+            `f=0; [ -f "$d/exit" ] && f=1`,
+            `tail -c +${outOff + 1} "$d/out" 2>/dev/null`,
+            `tail -c +${errOff + 1} "$d/err" >&2 2>/dev/null`,
+            `if [ $f = 1 ]; then c=$(cat "$d/exit"); rm -rf "$d"; exit "$c"; fi`,
+            `printf %s ${marker} >&2`,
+        ].join("\n");
+        const start = [
+            `d=${dir}; mkdir -p "$d" && echo ${cmdB64} | base64 -d > "$d/cmd" || exit 1`,
+            `setsid nohup bash -c 'timeout -k 5 ${timeout} bash "$0/cmd" > "$0/out" 2> "$0/err" < /dev/null; echo $? > "$0/exit.tmp"; mv "$0/exit.tmp" "$0/exit"' "$d" > /dev/null 2>&1 < /dev/null &`,
+            report(0, 0),
+        ].join("\n");
+        const outDec = new TextDecoder();
+        const errDec = new TextDecoder();
+        let stdout = "";
+        let stderr = "";
+        let outOff = 0;
+        let errOff = 0;
+        const deadline = Date.now() + (timeout + 60) * 1000;
+        let script = start;
+        for (;;) {
+            const r = await this.p.ssh(this.nativeId, script);
+            let errBytes = r.stderr;
+            const m = Buffer.from(marker);
+            const running = errBytes.length >= m.length && Buffer.from(errBytes.subarray(errBytes.length - m.length)).equals(m);
+            if (running)
+                errBytes = errBytes.subarray(0, errBytes.length - m.length);
+            outOff += r.stdout.length;
+            errOff += errBytes.length;
+            const o = outDec.decode(r.stdout, { stream: running });
+            const e = errDec.decode(errBytes, { stream: running });
+            if (o) {
+                stdout += o;
+                opts.onStdout?.(o);
+            }
+            if (e) {
+                stderr += e;
+                opts.onStderr?.(e);
+            }
+            if (!running) {
+                const durationMs = Date.now() - t0;
+                // `timeout -k 5` on the VM leaves exit 124 (or 137 after SIGKILL) when it had to stop the command.
+                if (killedByTimeout(r.exitCode, durationMs, timeout))
+                    throw timeoutError(ID, timeout);
+                return { exitCode: r.exitCode, stdout, stderr, durationMs };
+            }
+            if (Date.now() > deadline) {
+                // The VM's own `timeout` should have ended it a minute ago: stop it from here as a last resort.
+                await this.p.ssh(this.nativeId, `pkill -f ${shq(`${dir}/cmd`)}; rm -rf ${dir}`).catch(() => { });
+                throw timeoutError(ID, timeout);
+            }
+            script = report(outOff, errOff);
+        }
+    }
+    async writeFile(path, content) {
+        const bytes = toBytes(content);
+        const tmp = `${path}.sbr-${randomBytes(4).toString("hex")}`;
+        let first = true;
+        for (let i = 0; first || i < bytes.length; i += WRITE_CHUNK) {
+            const b64 = Buffer.from(bytes.subarray(i, i + WRITE_CHUNK)).toString("base64");
+            const prefix = first ? `mkdir -p ${shq(dirname(path))} && ` : "";
+            const r = await this.p.ssh(this.nativeId, `${prefix}echo ${b64 || "''"} | base64 -d ${first ? ">" : ">>"} ${shq(tmp)}`);
+            if (r.exitCode !== 0)
+                throw new ProviderError(ID, `writeFile ${path}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`);
+            first = false;
+        }
+        const r = await this.p.ssh(this.nativeId, `mv -f ${shq(tmp)} ${shq(path)}`);
+        if (r.exitCode !== 0)
+            throw new ProviderError(ID, `writeFile ${path}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`);
+    }
+    async readFile(path) {
+        const r = await this.p.ssh(this.nativeId, `base64 -w0 ${shq(path)}`);
+        if (r.exitCode !== 0)
+            throw new ProviderError(ID, `readFile ${path}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`);
+        return new Uint8Array(Buffer.from(r.stdout.toString(), "base64"));
+    }
+    async kill() {
+        await this.p.lobby(`rm ${this.nativeId}`);
+    }
+}
+/** Newline-delimited JSON reader for a fetch Response. */
+async function* readLines(res) {
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (line)
+                yield line;
+        }
+        if (done) {
+            if (buffer.trim())
+                yield buffer.trim();
+            return;
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/providers/freestyle.d.ts

@@ -0,0 +1,49 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Freestyle's Ubuntu base snapshots (hardware is baked into each), from
+ * https://www.freestyle.sh/docs/vms/base-snapshots, priced at the list rates on
+ * https://www.freestyle.sh/docs/vms/pricing-and-limits ($0.04032/vCPU-h, $0.0129/GiB-h memory,
+ * $0.000086/GiB-h disk), checked 2026-11-04. Free tops out at `ubuntu`, Hobby at `ubuntu-lg`,
+ * Pro at `ubuntu-2xl`.
+ */
+export declare const FREESTYLE_SIZES: {
+    snapshot: string;
+    vcpu: number;
+    memoryGb: number;
+    diskGb: number;
+    usdHour: number;
+}[];
+/** Smallest Ubuntu base snapshot with at least the requested vCPU and memory, or undefined. */
+export declare function freestyleSize(vcpu: number, memoryGb: number): (typeof FREESTYLE_SIZES)[number] | undefined;
+export declare class FreestyleProvider implements Provider {
+    private apiKey;
+    private baseUrl;
+    /** How often to poll a backgrounded request or a booting VM. */
+    private pollMs;
+    readonly id: "freestyle";
+    constructor(apiKey?: string | undefined, baseUrl?: string, 
+    /** How often to poll a backgrounded request or a booting VM. */
+    pollMs?: number);
+    configured(): boolean;
+    /**
+     * @internal One API call. With `background`, a call still running after 5 s comes back as 202
+     * and is polled at /v5/background-requests/:id until its own response is ready.
+     */
+    request(method: string, path: string, init?: {
+        json?: unknown;
+        bytes?: Uint8Array;
+        background?: boolean;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /** @internal JSON call. */
+    json<T>(method: string, path: string, init?: {
+        json?: unknown;
+        background?: boolean;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach by VM id (or slug); a paused or stopped VM is started again. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+    /** @internal */
+    get poll(): number;
+}

package/dist/providers/freestyle.js

@@ -0,0 +1,261 @@
+import { createHash } from "node:crypto";
+import { ProviderError } from "../types.js";
+import { dirname, toBytes, wrapCommand } from "../util.js";
+/**
+ * Freestyle VMs over the public REST API (no SDK needed). Auth: Authorization: Bearer
+ * <FREESTYLE_API_KEY>, base https://api.freestyle.sh. Errors are {code, message}.
+ *   POST   /v5/vms                {snapshotId, firewall:{rules}, ttlSeconds, metadata}  -> Vm (201, booting)
+ *   GET    /v5/vms/:id            -> Vm {id, state: starting|running|pausing|paused|stopped, resources}
+ *   POST   /v5/vms/:id/exec-await {command, env, timeoutMs} -> {statusCode|null, stdout, stderr}
+ *   PUT    /v5/vms/:id/fs/write?path=P&sha256=H   raw bytes, atomic (204)
+ *   GET    /v5/vms/:id/fs/read?path=P             raw bytes (404 when missing; works while paused)
+ *   POST   /v5/vms/:id/fs/mkdir   {path}  (creates parents)
+ *   POST   /v5/vms/:id/pause, POST /v5/vms/:id/start, POST /v5/vms/:id/resize {cpu, memory(MiB)}
+ *   DELETE /v5/vms/:id
+ * Long calls: with `x-freestyle-background-after-secs: N` a request still running after N s
+ * answers 202 {requestId} and GET /v5/background-requests/:id replays its response once done (202
+ * while pending). That is what lets exec run past the 5-minute inline cap (up to 24 h).
+ * Sizes come from the base snapshot (FREESTYLE_SIZES): the adapter boots the smallest
+ * freestyle/ubuntu-* that fits. A custom image.freestyle (snapshot id/slug) boots at its own size
+ * and is grown with resize when the spec asks for more. A VM gets no network unless allowed, so the
+ * adapter opens outbound Internet, like other providers' defaults. exec has no streaming (output
+ * streams only over PTY WebSockets), so onStdout/onStderr get the whole output once it finishes.
+ * pause() keeps memory and disk; connect() and a paused exec start the VM again.
+ * Docs: https://www.freestyle.sh/docs/vms, https://www.freestyle.sh/docs/vms/lifecycle,
+ *       https://www.freestyle.sh/docs/vms/files, https://www.freestyle.sh/docs/vms/base-snapshots,
+ *       https://www.freestyle.sh/docs/vms/pricing-and-limits, https://www.freestyle.sh/openapi.json
+ */
+const ID = "freestyle";
+const BACKGROUND_AFTER_SECS = "5";
+const READY_TIMEOUT_MS = 3 * 60_000;
+const MAX_EXEC_MS = 86_400_000;
+const OUTBOUND_INTERNET = { rules: [{ action: "allow", source: {}, destination: { public: true } }] };
+/**
+ * Freestyle's Ubuntu base snapshots (hardware is baked into each), from
+ * https://www.freestyle.sh/docs/vms/base-snapshots, priced at the list rates on
+ * https://www.freestyle.sh/docs/vms/pricing-and-limits ($0.04032/vCPU-h, $0.0129/GiB-h memory,
+ * $0.000086/GiB-h disk), checked 2026-11-04. Free tops out at `ubuntu`, Hobby at `ubuntu-lg`,
+ * Pro at `ubuntu-2xl`.
+ */
+export const FREESTYLE_SIZES = [
+    { snapshot: "freestyle/ubuntu-sm", vcpu: 2, memoryGb: 4, diskGb: 16 },
+    { snapshot: "freestyle/ubuntu", vcpu: 4, memoryGb: 8, diskGb: 32 },
+    { snapshot: "freestyle/ubuntu-lg", vcpu: 8, memoryGb: 16, diskGb: 64 },
+    { snapshot: "freestyle/ubuntu-xl", vcpu: 16, memoryGb: 32, diskGb: 128 },
+    { snapshot: "freestyle/ubuntu-2xl", vcpu: 32, memoryGb: 64, diskGb: 128 },
+].map((s) => ({ ...s, usdHour: round(s.vcpu * 0.04032 + s.memoryGb * 0.0129 + s.diskGb * 0.000086) }));
+/** Smallest Ubuntu base snapshot with at least the requested vCPU and memory, or undefined. */
+export function freestyleSize(vcpu, memoryGb) {
+    return FREESTYLE_SIZES.find((s) => s.vcpu >= vcpu && s.memoryGb >= memoryGb);
+}
+export class FreestyleProvider {
+    apiKey;
+    baseUrl;
+    pollMs;
+    id = ID;
+    constructor(apiKey = process.env.FREESTYLE_API_KEY, baseUrl = process.env.FREESTYLE_API_URL ?? "https://api.freestyle.sh", 
+    /** How often to poll a backgrounded request or a booting VM. */
+    pollMs = 2000) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.pollMs = pollMs;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    /**
+     * @internal One API call. With `background`, a call still running after 5 s comes back as 202
+     * and is polled at /v5/background-requests/:id until its own response is ready.
+     */
+    async request(method, path, init = {}) {
+        if (!this.apiKey)
+            throw new ProviderError(ID, "FREESTYLE_API_KEY is not set");
+        const headers = { Authorization: `Bearer ${this.apiKey}` };
+        if (init.background)
+            headers["x-freestyle-background-after-secs"] = BACKGROUND_AFTER_SECS;
+        let body;
+        if (init.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(init.json);
+        }
+        else if (init.bytes) {
+            headers["Content-Type"] = "application/octet-stream";
+            body = init.bytes;
+        }
+        let res = await fetch(`${this.baseUrl}${path}`, { method, headers, body, signal: init.signal });
+        if (init.background && res.status === 202) {
+            const accepted = (await res.json().catch(() => ({})));
+            const requestId = res.headers.get("x-freestyle-background-request-id") ?? accepted.requestId;
+            const resultPath = accepted.resultUrl ?? (requestId ? `/v5/background-requests/${encodeURIComponent(requestId)}` : undefined);
+            if (!resultPath)
+                throw new ProviderError(ID, `${method} ${path.split("?")[0]} -> 202 without a background request id`, 202);
+            for (;;) {
+                await sleep(this.pollMs, init.signal);
+                res = await fetch(resultPath.startsWith("http") ? resultPath : `${this.baseUrl}${resultPath}`, {
+                    headers: { Authorization: `Bearer ${this.apiKey}` },
+                    signal: init.signal,
+                });
+                if (res.status !== 202)
+                    break;
+                await res.body?.cancel().catch(() => { });
+            }
+        }
+        if (!res.ok) {
+            const text = await res.text();
+            let detail = text.slice(0, 300);
+            try {
+                const j = JSON.parse(text);
+                if (j?.message)
+                    detail = `${j.code ? `${j.code}: ` : ""}${j.message}`;
+            }
+            catch {
+                /* plain-text body */
+            }
+            throw new ProviderError(ID, `${method} ${path.split("?")[0]} -> ${res.status} ${detail}`, res.status);
+        }
+        return res;
+    }
+    /** @internal JSON call. */
+    async json(method, path, init = {}) {
+        const text = await (await this.request(method, path, init)).text();
+        return (text ? JSON.parse(text) : {});
+    }
+    async create(spec) {
+        const vcpu = spec.vcpu ?? 2;
+        const memoryGb = spec.memoryGb ?? 4;
+        const custom = spec.image?.freestyle;
+        const size = freestyleSize(vcpu, memoryGb);
+        if (!custom && !size)
+            throw new ProviderError(ID, `no Freestyle size has ${vcpu} vCPU / ${memoryGb} GB (max ubuntu-2xl: 32 vCPU / 64 GiB)`);
+        const body = {
+            snapshotId: custom ?? size.snapshot,
+            firewall: OUTBOUND_INTERNET,
+            ttlSeconds: Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60)),
+        };
+        if (spec.metadata)
+            body.metadata = spec.metadata;
+        const vm = await this.json("POST", "/v5/vms", { json: body, background: true });
+        const box = new FreestyleBox(this, vm.id, spec.env);
+        try {
+            const ready = await box.waitRunning();
+            // A custom snapshot boots at its own size; grow it (resize is grow-only) when the spec wants more.
+            const res = ready.resources;
+            if (custom && res && (res.cpu < Math.ceil(vcpu) || res.memory < Math.ceil(memoryGb * 1024))) {
+                await this.json("POST", `/v5/vms/${encodeURIComponent(vm.id)}/resize`, {
+                    json: { cpu: Math.max(res.cpu, Math.ceil(vcpu)), memory: Math.max(res.memory, Math.ceil(memoryGb * 1024)) },
+                    background: true,
+                });
+            }
+        }
+        catch (err) {
+            await box.kill().catch(() => { });
+            throw err;
+        }
+        return box;
+    }
+    /** Reattach by VM id (or slug); a paused or stopped VM is started again. */
+    async connect(nativeId) {
+        const box = new FreestyleBox(this, nativeId);
+        await box.waitRunning();
+        return box;
+    }
+    /** @internal */
+    get poll() {
+        return this.pollMs;
+    }
+}
+class FreestyleBox {
+    p;
+    nativeId;
+    env;
+    constructor(p, nativeId, env) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.env = env;
+    }
+    get path() {
+        return `/v5/vms/${encodeURIComponent(this.nativeId)}`;
+    }
+    /** Wait until the VM runs, starting it when it is paused or stopped. */
+    async waitRunning() {
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        let started = false;
+        for (;;) {
+            const vm = await this.p.json("GET", this.path);
+            if (vm.state === "running")
+                return vm;
+            if ((vm.state === "paused" || vm.state === "stopped") && !started) {
+                await this.p.json("POST", `${this.path}/start`, { background: true });
+                started = true;
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError(ID, `VM ${this.nativeId} still ${vm.state} after ${READY_TIMEOUT_MS / 1000}s`);
+            await sleep(Math.min(this.p.poll, 500));
+        }
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const secs = opts.timeoutSeconds ?? 60;
+        const body = {
+            command: wrapCommand(cmd, { cwd: opts.cwd }),
+            timeoutMs: Math.min(MAX_EXEC_MS, Math.max(1, Math.round(secs * 1000))),
+        };
+        const env = { ...this.env, ...opts.env };
+        if (Object.keys(env).length)
+            body.env = env;
+        let r;
+        try {
+            r = await this.p.json("POST", `${this.path}/exec-await`, { json: body, background: true });
+        }
+        catch (err) {
+            // 409 also means "stopped responding mid-command" (VM_NON_RESPONSIVE): never re-run that one.
+            if (!(err instanceof ProviderError) || err.status !== 409 || /VM_NON_RESPONSIVE/.test(err.message))
+                throw err;
+            const vm = await this.p.json("GET", this.path);
+            if (vm.state === "running")
+                throw err;
+            await this.waitRunning();
+            r = await this.p.json("POST", `${this.path}/exec-await`, { json: body, background: true });
+        }
+        if (r.statusCode === null || r.statusCode === undefined)
+            throw new ProviderError(ID, `command timed out after ${secs}s`);
+        const stdout = r.stdout ?? "";
+        const stderr = r.stderr ?? "";
+        if (stdout)
+            opts.onStdout?.(stdout);
+        if (stderr)
+            opts.onStderr?.(stderr);
+        return { exitCode: r.statusCode, stdout, stderr, durationMs: Date.now() - t0 };
+    }
+    async writeFile(path, content) {
+        const bytes = toBytes(content);
+        // Best effort (whether mkdir of an existing directory errors is not documented); the write
+        // itself reports any real problem.
+        const dir = dirname(path);
+        if (dir !== "/")
+            await this.p.request("POST", `${this.path}/fs/mkdir`, { json: { path: dir }, background: true }).catch(() => { });
+        const q = new URLSearchParams({ path, sha256: createHash("sha256").update(bytes).digest("hex") });
+        await this.p.request("PUT", `${this.path}/fs/write?${q}`, { bytes, background: true });
+    }
+    async readFile(path) {
+        const res = await this.p.request("GET", `${this.path}/fs/read?${new URLSearchParams({ path })}`);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async pause() {
+        await this.p.request("POST", `${this.path}/pause`, { background: true });
+    }
+    async kill() {
+        await this.p.request("DELETE", this.path);
+    }
+}
+function round(n) {
+    return Math.round(n * 1e5) / 1e5;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        // Not unref'd: between polls nothing else may keep the process alive.
+        const t = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => (clearTimeout(t), reject(signal.reason)), { once: true });
+    });
+}

package/dist/providers/hopx.d.ts

@@ -0,0 +1,15 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * HOPX via `@hopx-ai/sdk`. Auth: HOPX_API_KEY. vCPU and memory come from the template, not the
+ * create call (HOPX does not take custom resources at create). Set image.hopx to a template name
+ * (or a numeric template id) to start from your own; default is the public "code-interpreter".
+ */
+export declare class HopxProvider implements Provider {
+    private apiKey;
+    readonly id: "hopx";
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach; the SDK resumes a paused sandbox. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}