@sandboxrouter/sdk 0.3.0 → 0.3.2

package/README.md

@@ -8,7 +8,7 @@ Not every adapter has run against a real account yet. The [Prices](#prices) tabl
 import { Router } from "@sandboxrouter/sdk";
 
 const router = new Router();                       // uses whichever provider keys you've set
-const sbx = await router.create({ vcpu: 2, memoryGb: 4 });
+const sbx = await router.create();                 // or create({ vcpu: 2, memoryGb: 4 }) for a size
 try {
   const r = await sbx.exec("python3 -c 'print(6*7)'");
   console.log(r.stdout, "ran on", sbx.provider);
@@ -19,6 +19,8 @@ try {
 
 Runs as plain JavaScript on Node 20+. (In TypeScript 5.2+, or Node 24+, `await using sbx = ...` kills the sandbox for you.)
 
+With no size you get 2 vCPU / 4 GB, except on providers whose default image has a fixed size (Daytona 1 vCPU / 1 GB, E2B 2 vCPU / 0.5 GB, OpenScale 2 vCPU / 1 GB), where you get that. Ask for more than that and those providers are skipped unless you pass a custom `image` built at the size you need.
+
 Switch providers by changing which keys are set, not your code (custom images are the exception: each provider names its own). If one returns a 429, the next one takes the sandbox.
 
 Site: [sandboxrouter.vercel.app](https://sandboxrouter.vercel.app) · npm: [`@sandboxrouter/sdk`](https://www.npmjs.com/package/@sandboxrouter/sdk)
@@ -58,6 +60,7 @@ How to read it:
 - **Up to $X** means the provider bills CPU only while it's busy, so this is the price with every core busy. An agent that mostly waits on its model pays less.
 - **Plan needed** is the monthly plan you must be on before the API will create sandboxes. "Credited" means the fee comes back as usage. "None" means a free tier or plain pay-as-you-go works. For a small project, the plan can cost more than the usage.
 - **Real-account check** is the last time the 14-step [`check`](#compatibility) passed against a real account. "Not run yet" means the adapter is built from the provider's docs and tested against mocks only.
+- **Skipped** means the provider can't take 2 vCPU / 4 GB. One skipped for its default image's size is still used by a `create()` that names no size, at that image's size.
 
 | Provider | $/hr | Plan needed | Real-account check | Notes | Source |
 |---|---|---|---|---|---|
@@ -89,11 +92,11 @@ How to read it:
 | InstaBox (sign-up waitlisted) | $0.017 | none | not run yet | Per second while running on fixed sizes (2/4, 4/8, 8/16); paused or stopped boxes bill only /data beyond the included disk ($0.00011/GiB-h); Pro $20/mo includes $20 credits; free plan: 1 box at 4/8 | [pricing](https://instabox.sh/docs/pricing.md) |
 | Koyeb Sandboxes (not taking new accounts) | $0.058 | $29/mo | not run yet | Per second; fixed Standard instance sizes (1 vCPU + 1 GB = $0.0144/h); sandboxes need a paid plan (Pro $29/mo); public preview | [pricing](https://www.koyeb.com/docs/reference/instances) |
 | Dedalus Machines (sign-up waitlisted) | $0.149 | none | not run yet | Per second while awake; sleeping machines bill storage only (10 GiB included on Hobby, 20 on Pro); Hobby plan max 4 vCPU / 16 GiB; private beta | [pricing](https://docs.dedaluslabs.ai/dcs/dm/pricing) |
-| OpenScale Sandboxes | skipped (default size 2 vCPU / 1 GB; more needs image.openscale) | none | passed (2026-11-06) | Per second on allocated size; no platform fee or minimum; paused = free; size comes from the template (E2B-compatible API); Singapore only; needs a pay-as-you-go key | [pricing](https://openscale.so/sandboxes) |
+| OpenScale Sandboxes | skipped (default image is 2 vCPU / 1 GB; a bigger size needs image.openscale) | none | passed (2026-11-06) | Per second on allocated size; no platform fee or minimum; paused = free; size comes from the template (E2B-compatible API); Singapore only; needs a pay-as-you-go key | [pricing](https://openscale.so/sandboxes) |
 | Azure Container Apps dynamic sessions | skipped (max 1 vCPU) | none | not run yet | Flat $0.03 per session-hour (built-in Shell pools), billed per allocated session in 1-hour increments, East US; needs a session pool you create once | [pricing](https://learn.microsoft.com/en-us/azure/container-apps/billing#dynamic-sessions) |
-| Daytona | skipped (default size 1 vCPU / 1 GB; more needs image.daytona) | none | failed 1 step (2026-11-06) | Per second, plus disk above 5 GiB | [pricing](https://www.daytona.io/pricing) |
+| Daytona | skipped (default image is 1 vCPU / 1 GB; a bigger size needs image.daytona) | none | failed 1 step (2026-11-06) | Per second, plus disk above 5 GiB | [pricing](https://www.daytona.io/pricing) |
 | Alibaba Cloud Agent Sandbox | skipped (max 2 GB memory) | none | not run yet | Per second; Default QoS, Hong Kong and regions outside mainland China; disk separately $0.00025308/GiB-h; code-interpreter-v1 template is 2 vCPU / 2 GiB with 10 GiB disk (E2B-compatible API) | [pricing](https://www.alibabacloud.com/help/en/agent-sandbox/product-overview/billing-overview) |
-| E2B | skipped (default size 2 vCPU / 0.5 GB; more needs image.e2b) | none | passed (2026-11-06) | Per second; free Hobby tier ($100 one-time credit, 1-hour sessions, 20 at once); Pro $150/mo for longer sessions | [pricing](https://e2b.dev/pricing) |
+| E2B | skipped (default image is 2 vCPU / 0.5 GB; a bigger size needs image.e2b) | none | passed (2026-11-06) | Per second; free Hobby tier ($100 one-time credit, 1-hour sessions, 20 at once); Pro $150/mo for longer sessions | [pricing](https://e2b.dev/pricing) |
 | Docker (local) | free | none | passed (2026-11-06) | Runs on your own machine; free, but shares your kernel, so weaker isolation than a cloud micro-VM | [pricing](https://docs.docker.com/engine/) |
 
 Checked 2026-11-04 to 2026-11-06.
@@ -277,11 +280,11 @@ A sandbox the provider already stopped is just dropped from the ledger. `sandbox
 
 `bench` starts real sandboxes on every configured provider, measures time to a usable sandbox and the round trip of `echo ok`, kills them, and prints a markdown leaderboard. Results are saved to `~/.sandboxrouter/bench.json`, which is what `strategy: "fastest"` routes on. Latency is measured from wherever you run it, so network distance counts.
 
-`--share` writes a JSON report (timings, your label, Node version and platform; never keys, env or error text). Open a PR adding it to [`results/`](results/). `sandboxrouter leaderboard` builds one static HTML page from every report there, taking the median of each submission's medians so one submitter can't dominate. Host the page anywhere static files go.
+`--share` writes a JSON report (timings, your label, Node version and platform; never keys, env or error text), and `--by` adds your GitHub username so the website can credit you. Open a PR adding it to [`results/`](results/); CI checks every result file for keys, addresses and impossible numbers (`npm run results:check`), see [Sending results](CONTRIBUTING.md#sending-results). `sandboxrouter leaderboard` builds one static HTML page from every report there, taking the median of each submission's medians so one submitter can't dominate. Host the page anywhere static files go.
 
 ### Real cost
 
-Prices in the catalog are list prices. `cost` checks them against real bills: it starts one sandbox per provider at a known size, records the size the sandbox really has (`nproc` and `MemTotal`), keeps every core busy for a fixed time (some providers bill active CPU only), kills it, and predicts the cost from list price × wall time. `cost settle` then reads what the provider charged for that sandbox, from Daytona's usage analytics, Blaxel's metrics API and Maritime's metered usage. E2B and OpenScale have no billing API, so their bill is read from the dashboard. Bills post late on some providers (Daytona can take up to 48 h), so rerun `settle` until every row has one.
+Prices in the catalog are list prices. `cost` checks them against real bills: it starts one sandbox per provider at a known size, records the size the sandbox really has (`nproc` and `MemTotal`), keeps every core busy for a fixed time (some providers bill active CPU only), kills it, and predicts the cost from list price × wall time. `cost settle` then reads what the provider charged for that sandbox, from Daytona's usage analytics, Blaxel's metrics API, Maritime's metered usage and Sail's spend API. E2B and OpenScale have no billing API, so their bill is read from the dashboard. Bills post late on some providers (Daytona can take up to 48 h), so rerun `settle` until every row has one.
 
 ```bash
 sandboxrouter cost run --minutes 10           # every configured cloud provider, 2 vCPU / 4 GB
@@ -377,7 +380,7 @@ A standard-library client for the HTTP API lives in [`python/`](python/):
 from sandboxrouter import Client
 
 sr = Client("http://127.0.0.1:8787", token="secret")
-with sr.create(vcpu=2, memory_gb=4, strategy="cheapest") as sbx:
+with sr.create(strategy="cheapest") as sbx:
     sbx.exec("pip install rich && python -c 'import rich'", on_stdout=lambda c: print(c, end=""))
 ```
 

package/dist/catalog.js

@@ -21,7 +21,7 @@ export function planLabel(id) {
  * that can't take the size; then Docker. The router uses the same price order, but only among providers
  * you have keys for, so a gated provider only gets work if you already have an account there.
  */
-export function listingOrder(spec = {}) {
+export function listingOrder(spec = { vcpu: DEFAULT_VCPU, memoryGb: DEFAULT_MEMORY_GB }) {
     const rank = (c) => (c.local ? 3 : unfit(c.id, spec) ? 2 : c.access ? 1 : 0);
     return [...CATALOG].sort((a, b) => rank(a) - rank(b) || hourlyCost(a.id, spec) - hourlyCost(b.id, spec) || a.id.localeCompare(b.id));
 }
@@ -746,8 +746,10 @@ export function unfit(id, spec, require = []) {
         return `max ${p.limits.maxVcpu} vCPU`;
     if ((spec.memoryGb ?? DEFAULT_MEMORY_GB) > p.limits.maxMemoryGb)
         return `max ${p.limits.maxMemoryGb} GB memory`;
+    // A default image's size is fixed. With no size asked for you get that size, so only a size you
+    // name can be too big for it.
     const fixed = fixedSize(id, spec);
-    if (fixed && ((spec.vcpu ?? DEFAULT_VCPU) > fixed.vcpu || (spec.memoryGb ?? DEFAULT_MEMORY_GB) > fixed.memoryGb))
-        return `default size ${fixed.vcpu} vCPU / ${fixed.memoryGb} GB; more needs image.${id}`;
+    if (fixed && ((spec.vcpu ?? 0) > fixed.vcpu || (spec.memoryGb ?? 0) > fixed.memoryGb))
+        return `default image is ${fixed.vcpu} vCPU / ${fixed.memoryGb} GB; a bigger size needs image.${id}`;
     return null;
 }

package/dist/cli.js

@@ -6,8 +6,9 @@ import { bench, benchMarkdown } from "./bench.js";
 import { costMarkdown, costRun, settle } from "./cost.js";
 import { checkProvider } from "./check.js";
 import { gc, listOpen } from "./gc.js";
+import { contributor } from "./results.js";
 import { loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
-import { accessLabel, hourlyCost, listingOrder, planLabel, unfit } from "./catalog.js";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, hourlyCost, listingOrder, planLabel, unfit } from "./catalog.js";
 import { Router } from "./router.js";
 import { createApp } from "./server.js";
 import { RouterError } from "./types.js";
@@ -17,15 +18,15 @@ Usage:
   sandboxrouter providers [--vcpu N] [--memory GB]   price table + which keys are set
   sandboxrouter route     [spec flags] [route flags] dry run: the order providers would be tried
   sandboxrouter run "<cmd>" [spec flags] [route flags] [--keep]
-  sandboxrouter check     --provider ID[,ID] | --all [--json] [--save [dir]]
+  sandboxrouter check     --provider ID[,ID] | --all [--json] [--save [dir]] [--by GITHUB_USER]
                           test providers for real: exec, env, UTF-8, streaming, files, timeout, pause,
                           kill; exits 1 if any step fails. --all = every configured provider;
                           --save writes results/conformance/<id>.json for the compatibility table
   sandboxrouter ls        [--json]                       sandboxes this machine started that weren't killed
   sandboxrouter gc        [--all | --older-than MIN] [--dry-run]
                           kill leaked sandboxes: by default those past their lifetime
-  sandboxrouter bench     [--runs 3] [--provider a,b] [--json] [--share [--label "where you ran it"]]
-  sandboxrouter cost run  [--provider a,b] [--minutes 10] [--vcpu 2 --memory 4] [--no-load] [--out FILE]
+  sandboxrouter bench     [--runs 3] [--provider a,b] [--json] [--share [--label "where you ran it"] [--by GITHUB_USER]]
+  sandboxrouter cost run  [--provider a,b] [--minutes 10] [--vcpu 2 --memory 4] [--no-load] [--out FILE] [--by GITHUB_USER]
                           start one sandbox per provider for a fixed time with every core busy, record
                           the size it really got and the list-price prediction
   sandboxrouter cost settle FILE
@@ -42,7 +43,8 @@ Route flags:  --provider e2b[,modal,...]  --strategy cheapest|fastest
               --no-fallback  --fallback-any (also on setup errors like a bad key)
               --create-timeout SEC (per provider, default 120)  --require gpu,custom-image
 
-Keys: one env var group per provider; "sandboxrouter providers" lists them and shows which are set.`;
+Keys: one env var group per provider; "sandboxrouter providers" lists them and shows which are set.
+--by puts your GitHub username on a saved result, so the website can credit it.`;
 const { values, positionals } = parseArgs({
     allowPositionals: true,
     options: {
@@ -75,9 +77,16 @@ const { values, positionals } = parseArgs({
         "dry-run": { type: "boolean" },
         minutes: { type: "string" },
         "no-load": { type: "boolean" },
+        by: { type: "string" },
     },
 });
 const list = (s) => (s ? s.split(",").map((x) => x.trim()).filter(Boolean) : undefined);
+/** Plain left-aligned columns, two spaces apart; the last column isn't padded. */
+function textTable(head, rows) {
+    const width = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const line = (r) => r.map((v, i) => (i === r.length - 1 ? v : v.padEnd(width[i]))).join("  ").trimEnd();
+    return [line(head), ...rows.map(line)].join("\n");
+}
 const num = (s) => (s === undefined ? undefined : Number(s));
 const spec = {
     vcpu: num(values.vcpu),
@@ -86,6 +95,15 @@ const spec = {
     timeoutMinutes: num(values.timeout),
 };
 const providers = list(values.provider);
+const by = (() => {
+    try {
+        return contributor(values.by);
+    }
+    catch (e) {
+        console.error(`error: ${e.message}`);
+        process.exit(2);
+    }
+})();
 const route = {
     provider: providers,
     strategy: values.strategy,
@@ -99,10 +117,12 @@ async function main() {
     if (!cmd || values.help)
         return console.log(HELP);
     if (cmd === "providers") {
-        const rows = listingOrder(spec).map((c) => ({
+        // The table is for a size, so ask for the default one explicitly when no flags are given.
+        const size = { ...spec, vcpu: spec.vcpu ?? DEFAULT_VCPU, memoryGb: spec.memoryGb ?? DEFAULT_MEMORY_GB };
+        const rows = listingOrder(size).map((c) => ({
             provider: c.name,
             id: c.id,
-            "$/hr": unfit(c.id, spec) ?? `${c.billing === "active-cpu" ? "up to " : ""}$${hourlyCost(c.id, spec).toFixed(4)}`,
+            "$/hr": unfit(c.id, size) ?? `${c.billing === "active-cpu" ? "up to " : ""}$${hourlyCost(c.id, size).toFixed(4)}`,
             plan: c.local ? "none" : planLabel(c.id),
             configured: router.isConfigured(c.id) ? "yes" : "no",
             capabilities: c.capabilities.join(", ") || "-",
@@ -110,9 +130,23 @@ async function main() {
         }));
         if (values.json)
             return console.log(JSON.stringify(rows, null, 2));
-        console.log(`Estimated list price for ${spec.vcpu ?? 2} vCPU, ${spec.memoryGb ?? 4} GB while running, cheapest first.`);
-        console.log(`"up to" = billed on active CPU only, shown with every core busy. plan = monthly plan needed to use the API.\n`);
-        console.table(rows);
+        console.log(`${size.vcpu} vCPU / ${size.memoryGb} GB: estimated list price while running, cheapest first.\n`);
+        const cells = listingOrder(size).map((c) => {
+            const why = unfit(c.id, size);
+            const usd = c.local ? "free" : why ? "skipped" : `${c.billing === "active-cpu" ? "≤ " : ""}$${hourlyCost(c.id, size).toFixed(4)}`;
+            const note = [why, accessLabel(c.id), c.local ? "local; only used when named" : null].filter(Boolean).join("; ");
+            const name = c.name.length > 30 ? `${c.name.slice(0, 29)}…` : c.name;
+            return [c.id, name, usd, c.local ? "none" : planLabel(c.id), router.isConfigured(c.id) ? "set" : "-", c.capabilities.join(", ") || "-", note];
+        });
+        console.log(textTable(["ID", "PROVIDER", "$/HR", "PLAN", "KEY", "SUPPORTS", "NOTE"], cells));
+        console.log([
+            "",
+            "≤        billed on busy CPU only; the price with every core busy",
+            "PLAN     monthly plan the API needs before it creates sandboxes (credited = paid back as usage)",
+            "KEY      set = this provider's env vars are set here",
+            "skipped  can't take this size. A provider skipped for its default image's size still takes",
+            "         a create() that names no size, at that image's size.",
+        ].join("\n"));
         return;
     }
     if (cmd === "route") {
@@ -181,7 +215,7 @@ async function main() {
             reports.push(report);
             if (saveDir) {
                 mkdirSync(saveDir, { recursive: true });
-                const saved = { tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...report };
+                const saved = { tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...(by ? { by } : {}), ...report };
                 writeFileSync(`${saveDir}/${p}.json`, JSON.stringify(saved, null, 2) + "\n");
             }
         }
@@ -242,7 +276,7 @@ async function main() {
             console.error(`\n${r.provider} last error: ${r.lastError}`);
         if (values.share) {
             const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-            const report = makeReport(rows, { version, runs: rows[0].runs, spec, label: values.label });
+            const report = makeReport(rows, { version, runs: rows[0].runs, spec, label: values.label, by });
             const file = values.out ?? `sandboxrouter-bench-${report.date.slice(0, 10)}-${Math.random().toString(36).slice(2, 8)}.json`;
             writeFileSync(file, JSON.stringify(report, null, 2) + "\n");
             console.log(`\nwrote ${file}. Add it to results/ in a PR to github.com/gigialc/sandboxrouter to put it on the leaderboard.`);
@@ -262,6 +296,7 @@ async function main() {
                 spec,
                 load: !values["no-load"],
                 version,
+                by,
                 onProgress: (m) => console.error(m),
             });
             const file = values.out ?? `results/cost/cost-${run.date.slice(0, 16).replace(/[:T]/g, "-")}.json`;

package/dist/conformance.d.ts

@@ -6,6 +6,8 @@ export interface SavedCheck extends CheckReport {
     version: string;
     date: string;
     platform: string;
+    /** GitHub username of whoever ran it, from `--by`. */
+    by?: string;
 }
 export interface ConformanceRow {
     provider: ProviderId;
@@ -14,6 +16,8 @@ export interface ConformanceRow {
     run: null | {
         date: string;
         version: string;
+        /** GitHub username of whoever ran it, when they gave one. */
+        by: string | null;
         passed: number;
         /** Steps that ran and failed, with why. */
         failed: {

package/dist/conformance.js

@@ -52,6 +52,7 @@ export function conformanceTable(saved = loadConformance()) {
             run: {
                 date: r.date,
                 version: r.version,
+                by: r.by ?? null,
                 passed: pick("pass").length + pick("info").length,
                 failed: pick("fail").map((x) => ({ step: x.step, detail: x.detail })),
                 skipped: pick("skip").map((x) => x.step),

package/dist/cost.d.ts

@@ -48,6 +48,8 @@ export interface CostRun {
     date: string;
     minutes: number;
     load: boolean;
+    /** GitHub username of whoever ran it, from `--by`. */
+    by?: string;
     entries: CostEntry[];
 }
 export declare function costRun(opts: {
@@ -57,6 +59,7 @@ export declare function costRun(opts: {
     load?: boolean;
     router?: Router;
     version: string;
+    by?: string;
     onProgress?: (msg: string) => void;
 }): Promise<CostRun>;
 type Reader = (e: CostEntry) => Promise<Omit<Bill, "at">>;

package/dist/cost.js

@@ -46,7 +46,7 @@ export async function costRun(opts) {
         return entry;
     };
     const entries = await Promise.all(opts.providers.map(one));
-    return { tool: "sandboxrouter-cost", version: opts.version, date: new Date().toISOString(), minutes: opts.minutes, load, entries };
+    return { tool: "sandboxrouter-cost", version: opts.version, date: new Date().toISOString(), minutes: opts.minutes, load, ...(opts.by ? { by: opts.by } : {}), entries };
 }
 async function getJson(url, headers) {
     const r = await fetch(url, { headers, signal: AbortSignal.timeout(30_000) });

package/dist/leaderboard.d.ts

@@ -11,6 +11,8 @@ export interface BenchReport {
     date: string;
     /** Free text from the submitter, e.g. "us-east-1 c7g.large" or "Berlin, home fiber". */
     label?: string;
+    /** GitHub username of whoever ran it, from `--by`. */
+    by?: string;
     runs: number;
     spec: SandboxSpec;
     node: string;
@@ -22,6 +24,7 @@ export declare function makeReport(rows: BenchRow[], opts: {
     runs: number;
     spec: SandboxSpec;
     label?: string;
+    by?: string;
 }): BenchReport;
 export declare function loadReports(dir: string): BenchReport[];
 export interface LeaderRow {

package/dist/leaderboard.js

@@ -8,6 +8,7 @@ export function makeReport(rows, opts) {
         version: opts.version,
         date: new Date().toISOString(),
         label: opts.label,
+        ...(opts.by ? { by: opts.by } : {}),
         runs: opts.runs,
         // Only the shape matters for comparison; never ship env or metadata.
         spec: { vcpu: opts.spec.vcpu, memoryGb: opts.spec.memoryGb },

package/dist/providers/blaxel.js

@@ -1,6 +1,6 @@
 import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
 import { ProviderError } from "../types.js";
-import { DEFAULT_EXEC_TIMEOUT_S, optionalImport, timeoutError, toBytes } from "../util.js";
+import { DEFAULT_EXEC_TIMEOUT_S, errorStatus, optionalImport, timeoutError, toBytes } from "../util.js";
 /** Blaxel's public base image (the SDK's own default). Set image.blaxel for another image or a `bl deploy` template. */
 const DEFAULT_IMAGE = "blaxel/base-image:latest";
 /** Blaxel rejects a max-age ttl under 5 minutes. */
@@ -155,7 +155,7 @@ class BlaxelBox {
 function wrap(err) {
     if (err instanceof ProviderError)
         return err;
-    const status = typeof err?.status === "number" ? err.status : typeof err?.code === "number" ? err.code : err?.response?.status;
+    const status = errorStatus(err) ?? (typeof err?.code === "number" ? err.code : undefined);
     // The SDK sometimes throws the plain API body ({ code, error }), not an Error.
     const message = err?.message ?? err?.error ?? (typeof err === "object" ? JSON.stringify(err) : String(err));
     return new ProviderError("blaxel", message, status);

package/dist/providers/deno.js

@@ -1,4 +1,4 @@
-import { ProviderError } from "../types.js";
+import { ProviderError, SetupError } 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
@@ -43,7 +43,7 @@ export class DenoProvider {
         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");
+            throw new SetupError(`${ID}: a personal DENO_DEPLOY_TOKEN needs DENO_DEPLOY_ORG`);
         return { token: this.token, ...(this.org ? { org: this.org } : {}) };
     }
     async create(spec) {

package/dist/results.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Checks for the files people submit to results/: bench reports, saved `check` runs and `cost` runs.
+ *
+ * Submissions are self-reported, so nothing here can prove a number is real. What it can do is keep
+ * the obvious problems out before a maintainer reviews the PR: files that aren't one of the three
+ * formats, unknown providers, impossible numbers, anything that looks like a key, and labels that
+ * look like a home address or an email. CI runs it on every push and pull request
+ * (`npm run results:check`), and on a pull request it also refuses edits to someone else's bench
+ * report: a new run is a new file.
+ */
+export interface Issue {
+    file: string;
+    problem: string;
+}
+/** A GitHub handle, without the "@": what `--by` accepts and what reports store. */
+export declare function contributor(by?: string): string | undefined;
+/** Problems with one parsed result file. `now` is injectable for tests. */
+export declare function validateResult(j: any, now?: number): string[];
+/** Problems found anywhere in a file's raw text: secrets, emails, IP addresses. */
+export declare function scanText(text: string): string[];
+/**
+ * Every problem in a results directory. `changed` is the PR's `git diff --name-status` against its
+ * base, when there is one: a modified bench report means someone edited a run, which is refused.
+ * Saved checks (one per provider, replaced by each new run) and cost runs (`cost settle` fills in the
+ * bill later) may change.
+ */
+export declare function validateResults(dir?: string, opts?: {
+    changed?: {
+        status: string;
+        path: string;
+    }[];
+    now?: number;
+}): Issue[];

package/dist/results.js

@@ -0,0 +1,215 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { CATALOG } from "./catalog.js";
+import { CHECK_STEPS } from "./check.js";
+/** A GitHub handle, without the "@": what `--by` accepts and what reports store. */
+export function contributor(by) {
+    if (by === undefined)
+        return undefined;
+    const h = by.trim().replace(/^@/, "");
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/.test(h)) {
+        throw new Error(`--by takes a GitHub username, e.g. --by octocat (got "${by}")`);
+    }
+    return h;
+}
+const IDS = new Set(CATALOG.map((c) => c.id));
+const STEPS = new Set(CHECK_STEPS);
+const MAX_MS = 15 * 60_000;
+/** Key and token shapes from the providers here and the usual suspects. Matches print as a prefix only. */
+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,}/],
+    ["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,}/],
+    ["AWS access key", /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/],
+    ["GitHub token", /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,})/],
+    ["Slack token", /\bxox[abprs]-[A-Za-z0-9-]{10,}/],
+    ["JWT", /\beyJ[A-Za-z0-9_-]{15,}\.eyJ[A-Za-z0-9_-]{15,}\./],
+    ["bearer token", /\bBearer\s+[A-Za-z0-9._~+/-]{20,}/],
+    ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+    ["key=value secret", /\b[A-Z][A-Z0-9_]*(?:API_KEY|TOKEN|SECRET)["']?\s*[:=]\s*["']?[A-Za-z0-9_\-./+]{16,}/],
+];
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/;
+const IPV4 = /\b(?:25[0-5]|2[0-4]\d|1?\d?\d)(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}\b/;
+/** "12 Main Street", "Calle Mayor 5", "Apt 4B": a street or a flat, which a label never needs. */
+const ADDRESS = /\b\d+[A-Za-z]?\s+(?:[A-Za-zÀ-ÿ'.-]+\s+){0,3}(?:street|st|road|rd|avenue|ave|lane|ln|drive|dr|way|court|ct|place|pl|boulevard|blvd|terrace|close)\b\.?|\b(?:calle|carrer|rue|via|avenida|straße|strasse|str)\.?\s+[A-Za-zÀ-ÿ'.-]+(?:\s+[A-Za-zÀ-ÿ'.-]+){0,3}\s+\d+|\b(?:apt|apartment|flat|suite|unit|piso|puerta)\.?\s*#?\d+/i;
+const isNum = (n, min = 0, max = Infinity) => typeof n === "number" && Number.isFinite(n) && n >= min && n <= max;
+function checkDate(iso, now) {
+    if (typeof iso !== "string" || Number.isNaN(Date.parse(iso)))
+        return "date is missing or not an ISO date";
+    if (Date.parse(iso) > now + 86_400_000)
+        return "date is in the future";
+    if (Date.parse(iso) < Date.parse("2026-01-01"))
+        return "date is before sandboxrouter existed";
+}
+function checkLabel(label) {
+    if (label === undefined || label === null)
+        return;
+    if (typeof label !== "string")
+        return "label must be text";
+    if (label.length > 80)
+        return "label is longer than 80 characters";
+    if (EMAIL.test(label))
+        return "label contains an email address";
+    if (IPV4.test(label))
+        return "label contains an IP address";
+    if (ADDRESS.test(label))
+        return 'label looks like a street address; use a city or cloud region, e.g. "Berlin" or "us-east-1"';
+}
+function checkBy(by) {
+    if (by === undefined)
+        return;
+    try {
+        if (typeof by !== "string" || contributor(by) !== by)
+            return 'by must be a GitHub username without the "@"';
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+/** Problems with one parsed result file. `now` is injectable for tests. */
+export function validateResult(j, now = Date.now()) {
+    const out = [];
+    const add = (p) => p && out.push(p);
+    const provider = (id, where = "provider") => {
+        if (typeof id !== "string" || !IDS.has(id))
+            out.push(`${where} "${String(id)}" is not in the catalog`);
+    };
+    if (!j || typeof j !== "object" || Array.isArray(j))
+        return ["not a result file: expected a JSON object with a \"tool\" field"];
+    if (j.tool === "sandboxrouter") {
+        add(checkDate(j.date, now));
+        add(checkLabel(j.label));
+        add(checkBy(j.by));
+        if (!isNum(j.runs, 3, 1000))
+            out.push("runs must be at least 3");
+        if (!Array.isArray(j.rows) || !j.rows.length)
+            out.push("rows is empty");
+        for (const r of Array.isArray(j.rows) ? j.rows : []) {
+            provider(r?.provider, "row provider");
+            if (!isNum(r?.runs, 1, 1000))
+                out.push(`${r?.provider}: runs is not a positive number`);
+            if (!isNum(r?.failures, 0, r?.runs ?? 0))
+                out.push(`${r?.provider}: failures must be between 0 and runs`);
+            for (const k of ["medianCreateMs", "medianExecMs"]) {
+                if (r?.[k] !== undefined && !isNum(r[k], 1, MAX_MS))
+                    out.push(`${r?.provider}: ${k} must be between 1 ms and 15 min`);
+            }
+            if (r?.failures < r?.runs && r?.medianCreateMs === undefined)
+                out.push(`${r?.provider}: successful runs but no medianCreateMs`);
+            if ("lastError" in (r ?? {}))
+                out.push(`${r?.provider}: lastError must not be shared (it can hold account details)`);
+        }
+    }
+    else if (j.tool === "sandboxrouter-check") {
+        add(checkDate(j.date, now));
+        add(checkBy(j.by));
+        provider(j.provider);
+        if (!Array.isArray(j.results) || !j.results.length)
+            out.push("results is empty");
+        for (const r of Array.isArray(j.results) ? j.results : []) {
+            if (!STEPS.has(r?.step))
+                out.push(`unknown check step "${r?.step}"`);
+            if (!["pass", "fail", "skip", "info"].includes(r?.status))
+                out.push(`${r?.step}: unknown status "${r?.status}"`);
+            if (!isNum(r?.ms, 0, MAX_MS))
+                out.push(`${r?.step}: ms must be between 0 and 15 min`);
+        }
+    }
+    else if (j.tool === "sandboxrouter-cost") {
+        add(checkDate(j.date, now));
+        add(checkBy(j.by));
+        if (!isNum(j.minutes, 1, 24 * 60))
+            out.push("minutes must be between 1 and 1440");
+        if (!Array.isArray(j.entries) || !j.entries.length)
+            out.push("entries is empty");
+        for (const e of Array.isArray(j.entries) ? j.entries : []) {
+            provider(e?.provider, "entry provider");
+            if (e?.seconds !== undefined && !isNum(e.seconds, 0, 2 * 24 * 3600))
+                out.push(`${e?.provider}: seconds is out of range`);
+            if (e?.predictedUsd !== undefined && !isNum(e.predictedUsd, 0, 1000))
+                out.push(`${e?.provider}: predictedUsd is out of range`);
+            if (e?.bill?.usd !== undefined && !isNum(e.bill.usd, 0, 1000))
+                out.push(`${e?.provider}: bill.usd is out of range`);
+            if (e?.delivered && !(isNum(e.delivered.vcpu, 0.1, 1024) && isNum(e.delivered.memoryMb, 64, 4_194_304))) {
+                out.push(`${e?.provider}: delivered size is out of range`);
+            }
+        }
+    }
+    else {
+        out.push(`unknown tool "${String(j.tool)}": expected a bench report, a saved check or a cost run`);
+    }
+    return out;
+}
+/** Problems found anywhere in a file's raw text: secrets, emails, IP addresses. */
+export function scanText(text) {
+    const out = [];
+    for (const [what, re] of SECRET_SHAPES) {
+        const m = text.match(re);
+        if (m)
+            out.push(`looks like a ${what} ("${m[0].slice(0, 6)}…"); never commit keys`);
+    }
+    const email = text.match(EMAIL);
+    if (email)
+        out.push(`contains an email address ("${email[0].replace(/^(.).*@/, "$1…@")}")`);
+    const ip = text.match(IPV4);
+    if (ip && !/^0\.|^127\./.test(ip[0]))
+        out.push(`contains an IP address ("${ip[0]}")`);
+    return out;
+}
+/** Files in results/ that aren't submissions: notes and the maintainers' price audits. */
+const NOT_A_SUBMISSION = (rel) => /(^|\/)README\.md$/.test(rel) || /(^|\/)price-audit-[^/]+$/.test(rel);
+function walk(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).flatMap((f) => {
+        const p = join(dir, f);
+        return statSync(p).isDirectory() ? walk(p) : [p];
+    });
+}
+/**
+ * Every problem in a results directory. `changed` is the PR's `git diff --name-status` against its
+ * base, when there is one: a modified bench report means someone edited a run, which is refused.
+ * Saved checks (one per provider, replaced by each new run) and cost runs (`cost settle` fills in the
+ * bill later) may change.
+ */
+export function validateResults(dir = "results", opts = {}) {
+    const issues = [];
+    for (const path of walk(dir)) {
+        const rel = relative(".", path);
+        if (NOT_A_SUBMISSION(relative(dir, path)))
+            continue;
+        if (path.endsWith(".DS_Store"))
+            continue;
+        if (!path.endsWith(".json")) {
+            issues.push({ file: rel, problem: "only .json result files belong here" });
+            continue;
+        }
+        const text = readFileSync(path, "utf8");
+        for (const problem of scanText(text))
+            issues.push({ file: rel, problem });
+        let j;
+        try {
+            j = JSON.parse(text);
+        }
+        catch {
+            issues.push({ file: rel, problem: "is not valid JSON" });
+            continue;
+        }
+        for (const problem of validateResult(j, opts.now))
+            issues.push({ file: rel, problem });
+    }
+    for (const c of opts.changed ?? []) {
+        const p = c.path;
+        if (!p.startsWith(`${dir}/`) || NOT_A_SUBMISSION(p.slice(dir.length + 1)))
+            continue;
+        if (p.startsWith(`${dir}/conformance/`) || p.startsWith(`${dir}/cost/`))
+            continue;
+        if (/^[MR]/.test(c.status))
+            issues.push({ file: p, problem: "edits an existing bench report; add your run as a new file instead" });
+        if (c.status.startsWith("D"))
+            issues.push({ file: p, problem: "deletes a bench report; reports are only removed by a maintainer" });
+    }
+    return issues;
+}

package/dist/router.d.ts

@@ -39,6 +39,11 @@ export declare class Router {
     provider(id: ProviderId): Provider;
     /** The ordered list of providers a create would try, with the reason any are skipped. */
     plan(spec?: SandboxSpec, route?: RouteOptions): Candidate[];
+    /**
+     * Why a create has nowhere to go, leading with what the caller can fix: no keys at all, or why the
+     * providers they do have keys for were skipped.
+     */
+    private whyNone;
     /** Start a sandbox on the best available provider, falling back down the list on failure. */
     create(spec?: SandboxSpec, route?: RouteOptions): Promise<RoutedSandbox>;
     private record;

package/dist/router.js

@@ -2,7 +2,7 @@ import { CATALOG, accessLabel, hourlyCost, unfit } from "./catalog.js";
 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, timeoutError } from "./util.js";
+import { DEFAULT_EXEC_TIMEOUT_S, errorStatus, timeoutError } from "./util.js";
 import { DaytonaProvider } from "./providers/daytona.js";
 import { E2BProvider } from "./providers/e2b.js";
 import { MaritimeProvider } from "./providers/maritime.js";
@@ -41,7 +41,7 @@ import { OrgoProvider } from "./providers/orgo.js";
 import { MobilerunProvider } from "./providers/mobilerun.js";
 import { LimrunProvider } from "./providers/limrun.js";
 import { WorkspacesAgentProvider } from "./providers/workspaces.js";
-import { ProviderError, RouterError, } from "./types.js";
+import { ProviderError, SetupError, RouterError, } from "./types.js";
 /** Desktop-only providers. Filled in as adapters are added. */
 export function defaultComputerProviders() {
     return [new OrgoProvider(), new MobilerunProvider(), new LimrunProvider(), new WorkspacesAgentProvider()];
@@ -150,14 +150,40 @@ export class Router {
         }
         return list;
     }
+    /**
+     * Why a create has nowhere to go, leading with what the caller can fix: no keys at all, or why the
+     * providers they do have keys for were skipped.
+     */
+    whyNone(plan, explicit) {
+        if (plan.length === 0)
+            return "no provider can take this sandbox: none registered";
+        // Providers the caller named: say what each one needs.
+        if (explicit) {
+            const why = plan.map((c) => {
+                const vars = CATALOG.find((x) => x.id === c.provider)?.credentials.map((g) => g.join(" + ")).join(" or ");
+                return `${c.provider} (${c.skip}${vars && c.skip?.startsWith("not configured") ? `: set ${vars}` : ""})`;
+            });
+            return `no provider can take this sandbox: ${why.join(", ")}`;
+        }
+        const keyed = plan.filter((c) => this.isConfigured(c.provider));
+        if (keyed.length === 0)
+            return ("no provider keys found: set the API key for at least one provider (the README's Env table lists each provider's variables); " +
+                "`npx @sandboxrouter/sdk providers` shows which are set");
+        const rest = plan.length - keyed.length;
+        const small = keyed.filter((c) => c.skip?.startsWith("default image"));
+        return (`none of the providers you have keys for can take this sandbox: ${keyed.map((c) => `${c.provider} (${c.skip})`).join(", ")}` +
+            (rest ? `; ${rest} other provider${rest === 1 ? " has" : "s have"} no key set` : "") +
+            (small.length
+                ? `. To use ${small.map((c) => c.provider).join(" or ")}, leave out vcpu and memoryGb to get the default image's size, ` +
+                    `or pass image: { ${small[0].provider}: "<template>" } with a template built at the size you need`
+                : ""));
+    }
     /** Start a sandbox on the best available provider, falling back down the list on failure. */
     async create(spec = {}, route = {}) {
         const plan = this.plan(spec, route);
         const usable = plan.filter((c) => !c.skip);
-        if (usable.length === 0) {
-            const why = plan.map((c) => `${c.provider} (${c.skip})`).join(", ");
-            throw new RouterError(`no provider can take this sandbox: ${why || "none registered"}`);
-        }
+        if (usable.length === 0)
+            throw new RouterError(this.whyNone(plan, !!route.provider));
         const attempts = [];
         const tries = route.fallback === false ? usable.slice(0, 1) : usable;
         const limitS = route.createTimeoutSeconds ?? DEFAULT_CREATE_TIMEOUT_S;
@@ -181,9 +207,11 @@ export class Router {
                 if (timedOut)
                     pending.then((late) => this.discard(c.provider, late, c.estimatedHourlyUsd, spec.timeoutMinutes), () => { });
                 attempts.push({ provider: c.provider, ok: false, ms: Date.now() - t0, error: err.message });
-                const status = err instanceof ProviderError ? err.status : undefined;
-                if (route.fallback !== "any" && status !== undefined && SETUP_ERRORS.has(status)) {
-                    throw new RouterError(`${err.message.replace(/[.\s]+$/, "")}. This looks like a setup problem with ${c.provider} (key, billing, image or request), ` +
+                const status = errorStatus(err);
+                const setup = err instanceof SetupError || (status !== undefined && SETUP_ERRORS.has(status));
+                if (route.fallback !== "any" && setup) {
+                    const msg = err.message.replace(/[.\s]+$/, "");
+                    throw new RouterError(`${msg.startsWith(c.provider) ? msg : `${c.provider}: ${msg}`}. This looks like a setup problem with ${c.provider} (key, billing, image, request or a missing package), ` +
                         `so the router stopped instead of moving the work to another provider; pass fallback: "any" to fall back on every error`, attempts);
                 }
             }

package/dist/types.d.ts

@@ -93,3 +93,10 @@ export declare class ProviderError extends Error {
     readonly status?: number | undefined;
     constructor(provider: ProviderId | (string & {}), message: string, status?: number | undefined);
 }
+/**
+ * A problem with local setup, such as a provider SDK that isn't installed or a missing setting:
+ * something to fix here, not a provider being down. The router stops on it instead of falling back.
+ */
+export declare class SetupError extends Error {
+    constructor(message: string);
+}

package/dist/types.js

@@ -17,3 +17,13 @@ export class ProviderError extends Error {
         this.name = "ProviderError";
     }
 }
+/**
+ * A problem with local setup, such as a provider SDK that isn't installed or a missing setting:
+ * something to fix here, not a provider being down. The router stops on it instead of falling back.
+ */
+export class SetupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SetupError";
+    }
+}

package/dist/util.d.ts

@@ -36,3 +36,10 @@ export declare function toBytes(content: string | Uint8Array): Uint8Array;
 export declare function dirname(path: string): string;
 /** Load an optional peer dependency with a helpful error. */
 export declare function optionalImport<T>(pkg: string, provider: string): Promise<T>;
+/**
+ * The HTTP status an error stands for, read from the shapes provider SDKs use: `status`,
+ * `statusCode` (Daytona), `status_code` (Blaxel), `response.status` (Vercel), AWS's
+ * `$metadata.httpStatusCode`, gRPC codes (Modal), and error classes that only say it by name
+ * (E2B's AuthenticationError, AWS's CredentialsProviderError). Undefined when there's none.
+ */
+export declare function errorStatus(err: unknown, depth?: number): number | undefined;

package/dist/util.js

@@ -1,4 +1,4 @@
-import { ProviderError } from "./types.js";
+import { ProviderError, SetupError } from "./types.js";
 /** Per-command timeout when ExecOptions.timeoutSeconds is not given. */
 export const DEFAULT_EXEC_TIMEOUT_S = 60;
 /** Single-quote a string for POSIX sh. */
@@ -79,8 +79,34 @@ export async function optionalImport(pkg, provider) {
         // Bundlers and test runners (Vite, esbuild) report a missing package without Node's error code.
         const missing = /Cannot find (module|package)|Could not resolve|Failed to (resolve|load url)/.test(String(err?.message));
         if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || missing) {
-            throw new Error(`${provider} needs the "${pkg}" package: npm i ${pkg}`);
+            throw new SetupError(`${provider} needs the "${pkg}" package: npm i ${pkg}`);
         }
         throw err;
     }
 }
+/** gRPC status codes (Modal's SDK) as the HTTP status they correspond to. */
+const GRPC_TO_HTTP = { 3: 400, 5: 404, 7: 403, 8: 429, 14: 503, 16: 401 };
+/**
+ * The HTTP status an error stands for, read from the shapes provider SDKs use: `status`,
+ * `statusCode` (Daytona), `status_code` (Blaxel), `response.status` (Vercel), AWS's
+ * `$metadata.httpStatusCode`, gRPC codes (Modal), and error classes that only say it by name
+ * (E2B's AuthenticationError, AWS's CredentialsProviderError). Undefined when there's none.
+ */
+export function errorStatus(err, depth = 0) {
+    if (!err || typeof err !== "object" || depth > 3)
+        return undefined;
+    const e = err;
+    for (const v of [e.status, e.statusCode, e.status_code, e.response?.status, e.$metadata?.httpStatusCode])
+        if (typeof v === "number" && v >= 100 && v < 600)
+            return v;
+    if (e.name === "ClientError" && typeof e.code === "number" && GRPC_TO_HTTP[e.code])
+        return GRPC_TO_HTTP[e.code];
+    const name = String(e.name && e.name !== "Error" ? e.name : (e.constructor?.name ?? ""));
+    if (/AuthenticationError$/.test(name) || name === "CredentialsProviderError")
+        return 401;
+    if (/PermissionDenied|ForbiddenError$/.test(name))
+        return 403;
+    if (/RateLimitError$/.test(name))
+        return 429;
+    return errorStatus(e.cause, depth + 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxrouter/sdk",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "One API for every sandbox provider: route AI agents' code by price, speed or capability, with automatic fallback. Free and open source.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,8 @@
     "test:py": "python3 -m unittest discover -s python/tests -v",
     "site:data": "node --import tsx scripts/site-data.ts",
     "price:check": "node --import tsx scripts/price-watch.ts",
-    "secrets:push": "node --import tsx scripts/push-secrets.ts"
+    "secrets:push": "node --import tsx scripts/push-secrets.ts",
+    "results:check": "node --import tsx scripts/validate-results.ts"
   },
   "keywords": [
     "ai-agents",