@sandboxrouter/sdk 0.3.3 → 0.3.5

package/dist/client.d.ts

@@ -0,0 +1,58 @@
+import type { Attempt, ExecOptions, ExecResult, RouteOptions, SandboxSpec } from "./types.js";
+/**
+ * Client for the sandboxrouter HTTP API: the hosted service (one key, prepaid credits) or your own
+ * `sandboxrouter serve`. Provider keys live on the server; this side only needs the one key.
+ *
+ *   const sr = new Client({ apiKey: process.env.SANDBOXROUTER_API_KEY });
+ *   const sbx = await sr.create({ vcpu: 2, memoryGb: 4 });
+ *   console.log(sbx.provider, (await sbx.exec("python3 -c 'print(6*7)'")).stdout);
+ *   await sbx.kill();
+ */
+export declare class Client {
+    readonly baseUrl: string;
+    private readonly apiKey?;
+    private readonly fetch;
+    constructor(opts?: {
+        apiKey?: string;
+        baseUrl?: string;
+        fetch?: typeof fetch;
+    });
+    /** @internal */
+    request(method: string, path: string, body?: unknown, accept?: string): Promise<Response>;
+    private json;
+    /** Providers this server can route to, with list prices. */
+    providers(): Promise<{
+        id: string;
+        configured: boolean;
+        estimatedHourlyUsd: number;
+    }[]>;
+    /** Dry run: which providers would be tried, in order. */
+    route(spec?: SandboxSpec, route?: RouteOptions): Promise<{
+        provider: string;
+        estimatedHourlyUsd: number;
+        skip?: string;
+    }[]>;
+    /** Start a sandbox on the first provider that works, as the server routes it. */
+    create(spec?: SandboxSpec, route?: RouteOptions): Promise<RemoteSandbox>;
+    /** A handle on a sandbox you created earlier. */
+    sandbox(id: string): RemoteSandbox;
+}
+export declare class ClientError extends Error {
+    readonly status: number;
+    readonly attempts: Attempt[];
+    constructor(status: number, message: string, attempts?: Attempt[]);
+}
+export declare class RemoteSandbox {
+    private readonly client;
+    readonly id: string;
+    readonly provider: string;
+    readonly estimatedHourlyUsd?: number | undefined;
+    readonly attempts: Attempt[];
+    constructor(client: Client, id: string, provider: string, estimatedHourlyUsd?: number | undefined, attempts?: Attempt[]);
+    private path;
+    exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    pause(): Promise<void>;
+    kill(): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,140 @@
+/**
+ * Client for the sandboxrouter HTTP API: the hosted service (one key, prepaid credits) or your own
+ * `sandboxrouter serve`. Provider keys live on the server; this side only needs the one key.
+ *
+ *   const sr = new Client({ apiKey: process.env.SANDBOXROUTER_API_KEY });
+ *   const sbx = await sr.create({ vcpu: 2, memoryGb: 4 });
+ *   console.log(sbx.provider, (await sbx.exec("python3 -c 'print(6*7)'")).stdout);
+ *   await sbx.kill();
+ */
+export class Client {
+    baseUrl;
+    apiKey;
+    fetch;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? process.env.SANDBOXROUTER_URL ?? DEFAULT_URL).replace(/\/+$/, "");
+        this.apiKey = opts.apiKey ?? process.env.SANDBOXROUTER_API_KEY ?? process.env.SANDBOXROUTER_TOKEN;
+        this.fetch = opts.fetch ?? globalThis.fetch;
+    }
+    /** @internal */
+    async request(method, path, body, accept = "application/json") {
+        const raw = body instanceof Uint8Array;
+        const res = await this.fetch(this.baseUrl + path, {
+            method,
+            headers: {
+                Accept: accept,
+                ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+                ...(body === undefined ? {} : { "Content-Type": raw ? "application/octet-stream" : "application/json" }),
+            },
+            body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            let parsed = {};
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch { }
+            throw new ClientError(res.status, parsed.error ?? (text || res.statusText), parsed.attempts ?? []);
+        }
+        return res;
+    }
+    async json(method, path, body) {
+        return (await this.request(method, path, body)).json();
+    }
+    /** Providers this server can route to, with list prices. */
+    async providers() {
+        return (await this.json("GET", "/v1/providers")).providers;
+    }
+    /** Dry run: which providers would be tried, in order. */
+    async route(spec = {}, route = {}) {
+        return (await this.json("POST", "/v1/route", { ...spec, ...route })).candidates;
+    }
+    /** Start a sandbox on the first provider that works, as the server routes it. */
+    async create(spec = {}, route = {}) {
+        const r = await this.json("POST", "/v1/sandboxes", {
+            ...spec,
+            ...route,
+        });
+        return new RemoteSandbox(this, r.id, r.provider, r.estimatedHourlyUsd, r.attempts);
+    }
+    /** A handle on a sandbox you created earlier. */
+    sandbox(id) {
+        return new RemoteSandbox(this, id, id.split(":")[0]);
+    }
+}
+const DEFAULT_URL = "http://127.0.0.1:8787";
+export class ClientError extends Error {
+    status;
+    attempts;
+    constructor(status, message, attempts = []) {
+        super(`${status}: ${message}`);
+        this.status = status;
+        this.attempts = attempts;
+        this.name = "ClientError";
+    }
+}
+export class RemoteSandbox {
+    client;
+    id;
+    provider;
+    estimatedHourlyUsd;
+    attempts;
+    constructor(client, id, provider, estimatedHourlyUsd, attempts = []) {
+        this.client = client;
+        this.id = id;
+        this.provider = provider;
+        this.estimatedHourlyUsd = estimatedHourlyUsd;
+        this.attempts = attempts;
+    }
+    path(suffix = "") {
+        return `/v1/sandboxes/${encodeURIComponent(this.id)}${suffix}`;
+    }
+    async exec(cmd, opts = {}) {
+        const { onStdout, onStderr, ...rest } = opts;
+        const body = { cmd, ...rest };
+        if (!onStdout && !onStderr)
+            return (await this.client.request("POST", this.path("/exec"), body)).json();
+        const res = await this.client.request("POST", this.path("/exec"), { ...body, stream: true }, "text/event-stream");
+        const decoder = new TextDecoder();
+        let buf = "";
+        for await (const chunk of res.body) {
+            buf += decoder.decode(chunk, { stream: true });
+            let end;
+            while ((end = buf.indexOf("\n\n")) >= 0) {
+                const block = buf.slice(0, end);
+                buf = buf.slice(end + 2);
+                const event = /^event: ?(.*)$/m.exec(block)?.[1] ?? "message";
+                const data = block
+                    .split("\n")
+                    .filter((l) => l.startsWith("data:"))
+                    .map((l) => l.slice(l[5] === " " ? 6 : 5))
+                    .join("\n");
+                const payload = JSON.parse(data);
+                if (event === "stdout")
+                    onStdout?.(payload);
+                else if (event === "stderr")
+                    onStderr?.(payload);
+                else if (event === "result")
+                    return payload;
+                else if (event === "error")
+                    throw new ClientError(502, payload.error ?? data);
+            }
+        }
+        throw new ClientError(502, "stream ended before the command finished");
+    }
+    async writeFile(path, content) {
+        const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        await this.client.request("PUT", this.path(`/files?path=${encodeURIComponent(path)}`), data);
+    }
+    async readFile(path) {
+        const res = await this.client.request("GET", this.path(`/files?path=${encodeURIComponent(path)}`), undefined, "application/octet-stream");
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async pause() {
+        await this.client.request("POST", this.path("/pause"));
+    }
+    async kill() {
+        await this.client.request("DELETE", this.path());
+    }
+}

package/dist/index.d.ts

@@ -4,7 +4,8 @@ export { conformanceTable, loadConformance, type ConformanceRow, type SavedCheck
 export { gc, listOpen, isGone, type GcResult, type OpenSandbox } from "./gc.js";
 export { Router, RoutedSandbox, defaultProviders, defaultComputerProviders, parseId, type Candidate, type RouterOptions } from "./router.js";
 export { CATALOG, hourlyCost, unfit, info, type ProviderInfo } from "./catalog.js";
-export { createApp } from "./server.js";
+export { createApp, HttpError, type ServerHooks } from "./server.js";
+export { Client, ClientError, RemoteSandbox } from "./client.js";
 export { RoutedComputer, createComputer, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, type ComputerCatalogEntry, type ComputerCandidate, type ComputerProviderId, type ActionResult, type ComputerAction, type ComputerActionName, type ComputerInfo, type ComputerOs, type ComputerProvider, type ComputerSpec, type ProviderComputer, } from "./computers.js";
 export { bench, benchMarkdown, type BenchRow } from "./bench.js";
 export { aggregate, loadReports, makeReport, renderLeaderboard, type BenchReport, type LeaderRow } from "./leaderboard.js";

package/dist/index.js

@@ -4,7 +4,8 @@ export { conformanceTable, loadConformance } from "./conformance.js";
 export { gc, listOpen, isGone } from "./gc.js";
 export { Router, RoutedSandbox, defaultProviders, defaultComputerProviders, parseId } from "./router.js";
 export { CATALOG, hourlyCost, unfit, info } from "./catalog.js";
-export { createApp } from "./server.js";
+export { createApp, HttpError } from "./server.js";
+export { Client, ClientError, RemoteSandbox } from "./client.js";
 export { RoutedComputer, createComputer, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, } from "./computers.js";
 export { bench, benchMarkdown } from "./bench.js";
 export { aggregate, loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";

package/dist/providers/agentcore.d.ts

@@ -69,3 +69,12 @@ export declare class AgentCoreProvider implements Provider {
     create(spec: SandboxSpec): Promise<ProviderSandbox>;
     connect(nativeId: string): Promise<ProviderSandbox>;
 }
+/**
+ * Splits exec's combined terminal output at the stderr marker: the command's stdout comes before
+ * it, its stderr (base64) after. If the terminal still translated newlines (stty unavailable), the
+ * marker is preceded by \r\n and stdout's \r\n are turned back into \n.
+ */
+export declare function splitOutput(combined: string, marker: string): {
+    stdout: string;
+    stderr: string;
+};

package/dist/providers/agentcore.js

@@ -386,14 +386,39 @@ class AgentCoreSandbox {
         const timeout = Math.max(1, Math.round(opts.timeoutSeconds ?? 60));
         const full = wrapCommand(cmd, { cwd: opts.cwd, env: { ...this.env, ...opts.env } });
         const b64 = Buffer.from(full).toString("base64");
+        // The service runs commands in a terminal: stdout and stderr come back as one stream (labelled
+        // "stdout" on exit 0 and "stderr" otherwise), with \n turned into \r\n. So stderr goes to a file
+        // and is printed base64-encoded after a marker, and `stty -onlcr` keeps newlines as they are.
+        const nonce = randomBytes(6).toString("hex");
+        const errFile = `/tmp/.sbr-stderr-${nonce}`;
+        const marker = `__SBR_STDERR_${nonce}__`;
         // base64 keeps the user's command intact through whatever quoting the service applies.
-        const command = `timeout -k 5 ${timeout} bash -c "$(echo ${b64} | base64 -d)"`;
-        const r = await this.command(command, { onStdout: opts.onStdout, onStderr: opts.onStderr, timeoutMs: (timeout + 60) * 1000 });
+        const command = `stty -onlcr 2>/dev/null; timeout -k 5 ${timeout} bash -c "$(echo ${b64} | base64 -d)" 2>${errFile}; c=$?; ` +
+            `printf '\\n${marker}\\n'; base64 < ${errFile} | tr -d '\\r\\n'; rm -f ${errFile}; exit $c`;
+        // Stream stdout as it arrives, holding back only what could be the start of the marker.
+        let combined = "";
+        let sent = 0;
+        const feed = (chunk) => {
+            combined += chunk;
+            if (!opts.onStdout)
+                return;
+            const at = combined.indexOf(`\n${marker}`);
+            const safe = at >= 0 ? at : Math.max(sent, combined.length - marker.length - 2);
+            if (safe > sent)
+                opts.onStdout(combined.slice(sent, safe));
+            sent = Math.max(sent, safe);
+        };
+        const r = await this.command(command, { onStdout: feed, onStderr: feed, timeoutMs: (timeout + 60) * 1000 });
         const durationMs = Date.now() - t0;
+        const { stdout, stderr } = splitOutput(combined || r.stdout + r.stderr, marker);
+        if (opts.onStdout && stdout.length > sent)
+            opts.onStdout(stdout.slice(sent));
+        if (stderr)
+            opts.onStderr?.(stderr);
         // `timeout` 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 { ...r, durationMs };
+        return { stdout, stderr, exitCode: r.exitCode, durationMs };
     }
     async writeFile(path, content) {
         const bytes = toBytes(content);
@@ -426,6 +451,22 @@ class AgentCoreSandbox {
         }
     }
 }
+/**
+ * Splits exec's combined terminal output at the stderr marker: the command's stdout comes before
+ * it, its stderr (base64) after. If the terminal still translated newlines (stty unavailable), the
+ * marker is preceded by \r\n and stdout's \r\n are turned back into \n.
+ */
+export function splitOutput(combined, marker) {
+    const at = combined.lastIndexOf(`\n${marker}`);
+    if (at < 0)
+        return { stdout: combined, stderr: "" };
+    const translated = combined[at - 1] === "\r";
+    let stdout = combined.slice(0, translated ? at - 1 : at);
+    if (translated)
+        stdout = stdout.replace(/\r\n/g, "\n");
+    const b64 = combined.slice(at + marker.length + 1).replace(/\s/g, "");
+    return { stdout, stderr: Buffer.from(b64, "base64").toString("utf8") };
+}
 function exceptionStatus(name) {
     const n = name.toLowerCase();
     if (n.startsWith("accessdenied"))

package/dist/providers/freestyle.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { ProviderError } from "../types.js";
-import { dirname, toBytes, wrapCommand } from "../util.js";
+import { dirname, shq, 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}.
@@ -230,11 +230,18 @@ class FreestyleBox {
     }
     async writeFile(path, content) {
         const bytes = toBytes(content);
-        // Best effort (whether mkdir of an existing directory errors is not documented); the write
+        // The file API runs as root, so a folder it creates belongs to root and commands (which run as
+        // the image's user) can't write in it. Make the folder with a command instead, as that user;
+        // fall back to the file API where the user can't (e.g. under /root). Best effort: 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(() => { });
+        if (dir !== "/") {
+            const r = await this.p
+                .json("POST", `${this.path}/exec-await`, { json: { command: `mkdir -p ${shq(dir)}`, timeoutMs: 30_000 }, background: true })
+                .catch(() => undefined);
+            if (r?.statusCode !== 0)
+                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 });
     }

package/dist/providers/modal.js

@@ -75,7 +75,11 @@ class ModalBox {
         catch (err) {
             if (err instanceof ProviderError)
                 throw err;
-            throw new ProviderError("modal", err?.message ?? String(err));
+            const message = err?.message ?? String(err);
+            // Newer SDKs end the output streams with "Deadline exceeded" at timeoutMs instead of a signal exit.
+            if (/deadline exceeded/i.test(message) && killedByTimeout(-1, Date.now() - t0, seconds))
+                throw timeoutError("modal", seconds);
+            throw new ProviderError("modal", message);
         }
     }
     async writeFile(path, content) {

package/dist/providers/sprites.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { StringDecoder } from "node:string_decoder";
 import { ProviderError } from "../types.js";
-import { optionalImport, toBytes } from "../util.js";
+import { optionalImport, timeoutError, toBytes } from "../util.js";
 /**
  * Fly.io Sprites via `@fly/sprites`. A sprite is a persistent machine named by the caller, so the
  * name is the native id. Sprites idle on their own and have no lifetime knob: kill() deletes it.
@@ -78,9 +78,10 @@ class SpritesBox {
         try {
             const exitCode = await new Promise((resolve, reject) => {
                 const timer = setTimeout(() => {
+                    // Reject first: killing can report an exit (-1) right away, and that must not count as the result.
+                    reject(timeoutError("sprites", limit / 1000));
                     proc.kill("SIGKILL");
                     proc.close();
-                    reject(new ProviderError("sprites", `command timed out after ${limit / 1000}s`));
                 }, limit);
                 timer.unref();
                 proc.on("exit", (code) => {
@@ -89,8 +90,8 @@ class SpritesBox {
                 });
                 proc.on("error", (e) => {
                     clearTimeout(timer);
-                    proc.close();
                     reject(e);
+                    proc.close();
                 });
             });
             const so = out.end();

package/dist/providers/vercel.js

@@ -27,6 +27,9 @@ export class VercelProvider {
             resources: { vcpus },
             env: spec.env,
             tags: spec.metadata,
+            // v3 keeps sandboxes by default and restarts a stopped one on the next command; a router
+            // sandbox is single-use, so nothing should outlive kill().
+            persistent: false,
         });
         return new VercelBox(sbx);
     }
@@ -93,6 +96,7 @@ class VercelBox {
         return new Uint8Array(buf);
     }
     async kill() {
-        await this.sbx.stop();
+        // stop() only ends the session: the next SDK call would start it again. delete() makes it inert.
+        await this.sbx.delete({ deleteOrphanSnapshots: true });
     }
 }

package/dist/results.js

@@ -35,6 +35,7 @@ const MAX_MS = 15 * 60_000;
 const SECRET_SHAPES = [
     ["Stripe-style or Sail key", /\bsk_(?:live_|test_)?[A-Za-z0-9]{16,}/],
     ["OpenAI-style key", /\bsk-[A-Za-z0-9_-]{20,}/],
+    ["sandboxrouter key", /\bsr_live_[A-Za-z0-9_-]{20,}/],
     ["E2B key", /\be2b_[A-Za-z0-9]{20,}/],
     ["Daytona key", /\bdtn_[A-Za-z0-9]{20,}/],
     ["LangSmith key", /\blsv2_(?:sk|pt)_[A-Za-z0-9_]{20,}/],

package/dist/router.d.ts

@@ -5,6 +5,8 @@ export interface Candidate {
     provider: ProviderId;
     estimatedHourlyUsd: number;
     medianCreateMs?: number;
+    /** Passed the real-account check (as of this release, or `RouterOptions.verified`). */
+    verified: boolean;
     /** Why this provider won't be tried, if it won't. */
     skip?: string;
 }
@@ -21,6 +23,11 @@ export interface RouterOptions {
      * false to keep no record. SANDBOXROUTER_LEDGER=off also turns it off.
      */
     ledger?: string | false;
+    /**
+     * Providers the default "verified" strategy tries first. Default: those whose last real-account check
+     * passed as of this release (`VERIFIED`). Pass your own list, e.g. after running `check` yourself.
+     */
+    verified?: ProviderId[];
 }
 /** Desktop-only providers. Filled in as adapters are added. */
 export declare function defaultComputerProviders(): ComputerProvider[];
@@ -28,6 +35,7 @@ export declare function defaultProviders(): Provider[];
 export declare class Router {
     private providers;
     private benchFile?;
+    private readonly verified;
     private computerOnly;
     /** The local record of sandboxes this router created, or undefined when turned off. */
     readonly ledger?: Ledger;

package/dist/router.js

@@ -3,6 +3,7 @@ import { RoutedComputer, createComputer, planComputer, } from "./computers.js";
 import { loadBench, median } from "./bench-store.js";
 import { Ledger, defaultLedgerFile } from "./ledger.js";
 import { DEFAULT_EXEC_TIMEOUT_S, errorStatus, timeoutError } from "./util.js";
+import { VERIFIED } from "./verified.js";
 import { DaytonaProvider } from "./providers/daytona.js";
 import { E2BProvider } from "./providers/e2b.js";
 import { MaritimeProvider } from "./providers/maritime.js";
@@ -87,6 +88,7 @@ export function defaultProviders() {
 export class Router {
     providers;
     benchFile;
+    verified;
     computerOnly;
     /** The local record of sandboxes this router created, or undefined when turned off. */
     ledger;
@@ -96,6 +98,7 @@ export class Router {
             this.ledger = new Ledger(file);
         this.providers = new Map((opts.providers ?? defaultProviders()).map((p) => [p.id, p]));
         this.benchFile = opts.benchFile;
+        this.verified = new Set(opts.verified ?? Object.keys(VERIFIED));
         this.computerOnly = opts.computers ?? (opts.providers ? [] : defaultComputerProviders());
     }
     /** Registered and has credentials. False for providers this router doesn't know. */
@@ -122,12 +125,13 @@ export class Router {
         const list = ids.map((id) => {
             // An id the catalog has never heard of (a typo in an explicit list) has no price to look up.
             if (!CATALOG.some((c) => c.id === id))
-                return { provider: id, estimatedHourlyUsd: 0, skip: "unknown provider" };
+                return { provider: id, estimatedHourlyUsd: 0, verified: false, skip: "unknown provider" };
             const p = this.providers.get(id);
             const c = {
                 provider: id,
                 estimatedHourlyUsd: round(hourlyCost(id, spec)),
                 medianCreateMs: median(bench[id]?.createMs),
+                verified: this.verified.has(id),
             };
             if (!p)
                 c.skip = "no adapter registered";
@@ -137,16 +141,20 @@ export class Router {
             }
             return c;
         });
-        // Neutral by construction: price (or measured speed) decides, ties break alphabetically by id.
+        // Neutral by construction: the same rule for every provider, ties alphabetical by id. The default
+        // puts providers that passed the real-account check first; any provider gets there by passing it.
         // An explicit provider list keeps the caller's order.
         if (!explicit) {
             const byPrice = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
             if (route.strategy === "fastest") {
                 list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byPrice(a, b));
             }
-            else {
+            else if (route.strategy === "cheapest") {
                 list.sort(byPrice);
             }
+            else {
+                list.sort((a, b) => Number(b.verified) - Number(a.verified) || byPrice(a, b));
+            }
         }
         return list;
     }

package/dist/server.d.ts

@@ -1,5 +1,28 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
-import { Router } from "./router.js";
+import { Router, type RoutedSandbox } from "./router.js";
+import { type RouteOptions, type SandboxSpec } from "./types.js";
+/**
+ * Hooks for running this API for many users (accounts, billing, per-user sandboxes). With none set,
+ * the server is single-user: one SANDBOXROUTER_TOKEN, every sandbox reachable by anyone holding it.
+ */
+export interface ServerHooks {
+    /** Who is calling, or null for 401. Replaces the single-token check. */
+    authorize?(req: IncomingMessage): Promise<unknown | null>;
+    /** Routes outside /v1 (sign-in, billing webhooks, pages), checked before auth. Return true if handled. */
+    extra?(req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;
+    /** Before a sandbox starts. Throw HttpError to refuse (402 out of credit, 429 too many); may edit spec. */
+    beforeCreate?(caller: unknown, spec: SandboxSpec, route: RouteOptions): Promise<void>;
+    /** After it started. If this throws, the sandbox is killed and the error returned. */
+    afterCreate?(caller: unknown, sbx: RoutedSandbox, spec: SandboxSpec): Promise<void>;
+    /** May this caller use this sandbox? No means 404. */
+    owns?(caller: unknown, id: string): Promise<boolean>;
+    /** After DELETE killed it. */
+    afterKill?(caller: unknown, id: string): Promise<void>;
+    /** false turns off /v1/computers. */
+    computers?: boolean;
+    /** false turns off pause. */
+    pause?: boolean;
+}
 /**
  * OpenRouter-style HTTP API in front of every provider. One token for your clients; provider keys
  * stay on this host.
@@ -28,4 +51,8 @@ import { Router } from "./router.js";
  */
 export declare function createApp(router?: Router, token?: string | undefined, 
 /** Browser origins allowed to call this server (e.g. the website's Playground). Off by default. */
-corsOrigins?: string[]): import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;
+corsOrigins?: string[], hooks?: ServerHooks): import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}

package/dist/server.js

@@ -31,11 +31,11 @@ import { ProviderError, RouterError } from "./types.js";
  */
 export function createApp(router = new Router(), token = process.env.SANDBOXROUTER_TOKEN, 
 /** Browser origins allowed to call this server (e.g. the website's Playground). Off by default. */
-corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.trim()).filter(Boolean)) {
+corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.trim()).filter(Boolean), hooks = {}) {
     // With CORS on, any page open in a browser on this machine can call the server (Chrome even
     // lets a public page reach localhost, which the Private-Network header below allows), so it
     // would start sandboxes on these provider keys. A token is required for that.
-    if (corsOrigins.length && !token) {
+    if (corsOrigins.length && !token && !hooks.authorize) {
         throw new Error("CORS is on but SANDBOXROUTER_TOKEN is not set: browser pages could start sandboxes on your keys. Set a token, or turn CORS off.");
     }
     const expected = token ? Buffer.from(`Bearer ${token}`) : undefined;
@@ -71,11 +71,23 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         }
         if (url.pathname === "/health")
             return json(res, 200, { ok: true });
-        if (!authorized(req))
+        if (hooks.extra && (await hooks.extra(req, res, url)))
+            return;
+        let caller = null;
+        if (hooks.authorize) {
+            caller = await hooks.authorize(req);
+            if (caller === null)
+                return json(res, 401, { error: "unauthorized" });
+        }
+        else if (!authorized(req))
             return json(res, 401, { error: "unauthorized" });
         if (parts[0] !== "v1")
             return json(res, 404, { error: "not found" });
-        const box = async (id) => live.get(id) ?? router.get(id);
+        const box = async (id) => {
+            if (hooks.owns && !(await hooks.owns(caller, id)))
+                throw new HttpError(404, "no such sandbox");
+            return live.get(id) ?? router.get(id);
+        };
         // GET /v1/providers
         if (req.method === "GET" && parts[1] === "providers" && parts.length === 2) {
             return json(res, 200, {
@@ -91,14 +103,25 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
             const { spec, route } = splitBody(await readJson(req));
             return json(res, 200, { candidates: router.plan(spec, route) });
         }
-        if (parts[1] === "computers")
+        if (parts[1] === "computers") {
+            if (hooks.computers === false)
+                return json(res, 404, { error: "computers aren't available on this server" });
             return computers(req, res, url, parts);
+        }
         if (parts[1] !== "sandboxes")
             return json(res, 404, { error: "not found" });
         // POST /v1/sandboxes
         if (req.method === "POST" && parts.length === 2) {
             const { spec, route } = splitBody(await readJson(req));
+            await hooks.beforeCreate?.(caller, spec, route);
             const sbx = await router.create(spec, route);
+            try {
+                await hooks.afterCreate?.(caller, sbx, spec);
+            }
+            catch (err) {
+                await sbx.kill().catch(() => { });
+                throw err;
+            }
             live.set(sbx.id, sbx);
             return json(res, 201, {
                 id: sbx.id,
@@ -132,6 +155,8 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         }
         // POST /v1/sandboxes/:id/pause
         if (req.method === "POST" && parts[3] === "pause" && parts.length === 4) {
+            if (hooks.pause === false)
+                return json(res, 400, { error: "pause isn't available on this server" });
             await (await box(id)).pause();
             // Drop the cached handle so the next call reattaches through router.get(), which resumes.
             live.delete(id);
@@ -156,6 +181,7 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         if (req.method === "DELETE" && parts.length === 3) {
             await (await box(id)).kill();
             live.delete(id);
+            await hooks.afterKill?.(caller, id);
             return json(res, 200, { id, killed: true });
         }
         return json(res, 404, { error: "not found" });
@@ -227,7 +253,7 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         });
     });
 }
-class HttpError extends Error {
+export class HttpError extends Error {
     status;
     constructor(status, message) {
         super(message);

package/dist/types.d.ts

@@ -22,14 +22,17 @@ export interface SandboxSpec {
     metadata?: Record<string, string>;
 }
 /**
- * "cheapest" (and "default", the same thing): lowest list price for the spec, ties alphabetical.
+ * "verified" (and "default", the same thing): providers that passed the real-account check first
+ * (as of this release; `VERIFIED` in src/verified.ts), then the rest; cheapest first within each,
+ * ties alphabetical.
+ * "cheapest": lowest list price for the spec, tested or not, ties alphabetical.
  * "fastest": lowest median cold start you measured with `bench`, then cheapest.
  */
-export type Strategy = "default" | "cheapest" | "fastest";
+export type Strategy = "default" | "verified" | "cheapest" | "fastest";
 export interface RouteOptions {
     /** Pin to one provider, or give an ordered list to try. Omit to let the router choose. */
     provider?: ProviderId | ProviderId[];
-    /** How to order candidates when no explicit list is given. Default: cheapest. */
+    /** How to order candidates when no explicit list is given. Default: "verified" (tested providers first, then cheapest). */
     strategy?: Strategy;
     /**
      * What to do when a create fails. `true` (default): try the next candidate when the provider

package/dist/verified.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderId } from "./types.js";
+export declare const VERIFIED: Partial<Record<ProviderId, string>>;