@sandboxrouter/sdk 0.3.1 → 0.3.3

package/README.md

@@ -66,8 +66,8 @@ How to read it:
 |---|---|---|---|---|---|
 | Agent37 | $0.007 | none | not run yet | Whole-minute billing: monthly shape total / 730 / 60; running estimate includes default disk (2 vCPU / 4 GB / 4 GB disk = $4.76/mo); sleeping/stopped disk $0.09/GB-mo; gVisor; $5 minimum top-up, wallet must hold one running day | [pricing](https://www.agent37.com/docs/agents-api/billing) |
 | Boat | $0.018 | $20/mo (credited) | not run yet | Fixed sizes billed per second ($0.018/h for 2 vCPU / 4 GB up to $0.20/h for 16 / 32); needs a plan from $20/mo, paid back as VM time | [pricing](https://docs.boat.dev/pricing.md) |
-| Maritime | $0.022 | $20/mo (credited) | passed (2026-11-06) | Per second, no minimum runtime; running disk included; Starter $20/mo incl. $20 usage; paused disk $0.08/GB-month (default idle action deletes sandbox) | [pricing](https://maritime.sh/pricing) |
-| Sailboxes (Sail Research) | up to $0.062 | none | passed (2026-11-06) | Per second on what the box uses (CPU time, RAM it holds, disk $0.0007/GiB-h), billed per minute; RAM counts the VM's file cache, up to the 16 GiB minimum limit, so file-heavy work can hold more than you asked for; paused/sleeping free; creation $0.01 at 2-4 vCPU on the free plan ($5/mo credit with a card), waived on Pro $250/mo | [pricing](https://docs.sailresearch.com/sailboxes-pricing.md) |
+| Maritime | $0.022 | $20/mo (credited) | passed (2026-11-07) | Per second, no minimum runtime; running disk included; Starter $20/mo incl. $20 usage; paused disk $0.08/GB-month (default idle action deletes sandbox) | [pricing](https://maritime.sh/pricing) |
+| Sailboxes (Sail Research) | up to $0.062 | none | passed (2026-11-07) | Per second on what the box uses (CPU time, RAM it holds, disk $0.0007/GiB-h), billed per minute; RAM counts the VM's file cache, up to the 16 GiB minimum limit, so file-heavy work can hold more than you asked for; paused/sleeping free; creation $0.01 at 2-4 vCPU on the free plan ($5/mo credit with a card), waived on Pro $250/mo | [pricing](https://docs.sailresearch.com/sailboxes-pricing.md) |
 | Northflank | $0.067 | none | not run yet | Per second on Northflank Cloud, ephemeral disk included; sandboxes run as deployment services (microVMs) | [pricing](https://northflank.com/pricing) |
 | Morph Cloud | $0.100 | none | not run yet | $0.05/MCU; MCU-hours = max(vCPU, RAM/4 GB, disk/16 GB); snapshots extra | [pricing](https://cloud.morph.so/web/pricing) |
 | exe.dev | $0.105 | $15/mo | not run yet | Standalone reserved size, per second: $0.105/h per 2 vCPU / 4 GiB unit; stopped CPU/RAM free, retained disk separate; Personal from $15/mo (up to 16 vCPU / 32 GiB), Work $75/mo (32 / 64 without approval) | [pricing](https://exe.dev/docs/standalone-vms.md) |
@@ -76,10 +76,9 @@ How to read it:
 | Beam | $0.140 | $20/mo (credited) | not run yet | Per second, Performance tier (sandbox default); Developer plan $20/mo incl. $20 credits; GPUs billed separately | [pricing](https://www.beam.cloud/pricing) |
 | CodeSandbox SDK (Together) | $0.149 | none | not run yet | Fixed tiers: Pico 2 vCPU / 1 GB $0.0743/h, Nano 2 / 4 $0.1486/h, up to 64 / 128 $4.7552/h; credits $0.01486, billed per started minute; Build free, 10 concurrent; Scale $170/mo incl. 1,100 credits | [pricing](https://docs.together.ai/docs/together-code-sandbox-legacy) |
 | Fly.io Sprites | up to $0.164 | none | not run yet | Bills actual CPU and memory use; this is the full-use price; storage extra | [pricing](https://fly.io/sprites) |
-| Blaxel | $0.166 | none | passed (2026-11-06) | Billed on memory only ($0.0000115/GB-s), CPU scales with memory (~2 GB per core) | [pricing](https://blaxel.ai/pricing) |
+| Blaxel | $0.166 | none | passed (2026-11-07) | Billed on memory only ($0.0000115/GB-s), CPU scales with memory (~2 GB per core) | [pricing](https://blaxel.ai/pricing) |
 | HOPX | $0.166 | none | not run yet | Per second, plus storage; size comes from the template, not the request | [pricing](https://hopx.ai/pricing) |
 | Superserve | $0.166 | maybe $20/mo (credited) | not run yet | Per second active; superserve/base fixed at 2 vCPU / 4 GiB / 8 GiB disk; retained storage $0.000108/GiB-h (shared template plus changed blocks); Developer $20/mo incl. $20, max 4/16 with team templates; recurring Free allowance not published on pricing page | [pricing](https://superserve.ai/pricing) |
-| LangSmith Sandboxes | $0.189 | none | not run yet | Per second; memory must be 2 to 6 GiB per vCPU; storage $0.000123/GiB-h; 8 LSU ($8) of sandbox usage a month included; Developer plan max 10 sandboxes | [pricing](https://www.langchain.com/pricing) |
 | Tensorlake | up to $0.200 | none | not run yet | Bills active CPU (floor 20% of allocation); this is the full-use price; Pro plan is lower | [pricing](https://www.tensorlake.ai/pricing) |
 | Upstash Box | up to $0.200 | none | not run yet | Billed per active CPU core-hour only (memory and idle time free); estimate assumes every core of the box busy; fixed sizes 2/4, 4/8, 8/16 | [pricing](https://upstash.com/pricing/box) |
 | Cloudflare Sandbox | up to $0.216 | $5/mo | not run yet | 10 ms billing on active CPU and allocated instance memory; full-CPU estimate excludes allocated disk ($0.000252/GB-h), Worker and Durable Objects charges; needs Workers Paid ($5/mo) and bridges/cloudflare | [pricing](https://developers.cloudflare.com/containers/platform/pricing/) |
@@ -92,12 +91,13 @@ 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 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) |
+| LangSmith Sandboxes (sign-up waitlisted) | $0.189 | none | not run yet | Per second; memory must be 2 to 6 GiB per vCPU; storage $0.000123/GiB-h; 8 LSU ($8) of sandbox usage a month included; Developer plan max 10 sandboxes | [pricing](https://www.langchain.com/pricing) |
+| OpenScale Sandboxes | skipped (default image is 2 vCPU / 1 GB; a bigger size needs image.openscale) | none | passed (2026-11-07) | 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 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) |
+| Daytona | skipped (default image is 1 vCPU / 1 GB; a bigger size needs image.daytona) | none | passed (2026-11-07) | 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 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/) |
+| E2B | skipped (default image is 2 vCPU / 0.5 GB; a bigger size needs image.e2b) | none | passed (2026-11-07) | 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-07) | 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.
 
@@ -185,8 +185,9 @@ const c = await router.create({}, { provider: ["e2b", "daytona"], fallback: fals
 
 // Fallback moves on when a provider is down: a timeout, a network error, 429 or 5xx, and a create
 // that takes longer than createTimeoutSeconds (default 120; a sandbox that turns up later is
-// killed, or left in the ledger for `gc`). A setup error (400, 401, 402, 403, 404, 422: a bad key,
-// no billing, a bad image) stops instead, so a mistake isn't hidden by a pricier provider.
+// killed, or left in the ledger for `gc`), and when an account can't pay (402: no balance, plan
+// needed). A setup error (400, 401, 403, 404, 422: a bad key, a bad image or request) stops instead,
+// so a mistake isn't hidden by a pricier provider. Every failed attempt is on sbx.attempts.
 // fallback: "any" falls back on every error.
 const e = await router.create({}, { fallback: "any", createTimeoutSeconds: 300 });
 
@@ -306,8 +307,8 @@ It prints one line per step and exits 1 if any fails. `checkProvider(router, id)
 |---|---|---|
 | Agent37 | not run yet | |
 | Boat | not run yet | |
-| Maritime | 14/14 passed | 2026-11-06, v0.2.0 |
-| Sailboxes (Sail Research) | 14/14 passed | 2026-11-06, v0.3.0 |
+| Maritime | 14/14 passed | 2026-11-07, v0.3.2 |
+| Sailboxes (Sail Research) | 14/14 passed | 2026-11-07, v0.3.2 |
 | Northflank | not run yet | |
 | Morph Cloud | not run yet | |
 | exe.dev | not run yet | |
@@ -316,10 +317,9 @@ It prints one line per step and exits 1 if any fails. `checkProvider(router, id)
 | Beam | not run yet | |
 | CodeSandbox SDK (Together) | not run yet | |
 | Fly.io Sprites | not run yet | |
-| Blaxel | 13/13 passed; n/a: pause and resume | 2026-11-06, v0.2.0 |
+| Blaxel | 13/13 passed; n/a: pause and resume | 2026-11-07, v0.3.2 |
 | HOPX | not run yet | |
 | Superserve | not run yet | |
-| LangSmith Sandboxes | not run yet | |
 | Tensorlake | not run yet | |
 | Upstash Box | not run yet | |
 | Cloudflare Sandbox | not run yet | |
@@ -332,12 +332,13 @@ It prints one line per step and exits 1 if any fails. `checkProvider(router, id)
 | InstaBox | not run yet | |
 | Koyeb Sandboxes | not run yet | |
 | Dedalus Machines | not run yet | |
-| OpenScale Sandboxes | 14/14 passed | 2026-11-06, v0.2.0 |
+| LangSmith Sandboxes | not run yet | |
+| OpenScale Sandboxes | 14/14 passed | 2026-11-07, v0.3.2 |
 | Azure Container Apps dynamic sessions | not run yet | |
-| Daytona | 0/14 passed; failed: create | 2026-11-06, v0.2.0 |
+| Daytona | 14/14 passed | 2026-11-07, v0.3.2 |
 | Alibaba Cloud Agent Sandbox | not run yet | |
-| E2B | 14/14 passed | 2026-11-06, v0.2.0 |
-| Docker (local) | 14/14 passed | 2026-11-06, v0.2.0 |
+| E2B | 14/14 passed | 2026-11-07, v0.3.2 |
+| Docker (local) | 14/14 passed | 2026-11-07, v0.3.2 |
 
 ## HTTP API
 

package/dist/catalog.d.ts

@@ -58,7 +58,20 @@ export interface ProviderInfo {
         note: string;
         checked: string;
     };
+    /**
+     * Set when the provider's terms forbid publishing benchmarks or performance information about it.
+     * Its cold starts, success rate, measured size and real bills are then left out of shared reports,
+     * results/ and the website, and saved checks keep pass/fail without timings. List prices (public
+     * pricing pages) and the adapter itself are unaffected.
+     */
+    noBenchmarks?: {
+        clause: string;
+        source: string;
+        checked: string;
+    };
 }
+/** False when the provider's terms forbid publishing its benchmarks (see `noBenchmarks`). */
+export declare function benchmarksPublishable(id: string): boolean;
 /** Short label for a gated provider's sign-up status, or null when anyone can sign up. */
 export declare function accessLabel(id: ProviderId): string | null;
 /** Short label for the plan a provider needs before you can use it: "none", "$20/mo (credited)", "$5/mo". */

package/dist/catalog.js

@@ -3,6 +3,10 @@ import { AGENT37_SHAPES, agent37Shape } from "./providers/agent37.js";
 import { INSTABOX_SIZES, instaboxSize } from "./providers/instabox.js";
 import { FREESTYLE_SIZES, freestyleSize } from "./providers/freestyle.js";
 import { langsmithSize } from "./providers/langsmith.js";
+/** False when the provider's terms forbid publishing its benchmarks (see `noBenchmarks`). */
+export function benchmarksPublishable(id) {
+    return !CATALOG.find((c) => c.id === id)?.noBenchmarks;
+}
 /** Short label for a gated provider's sign-up status, or null when anyone can sign up. */
 export function accessLabel(id) {
     const a = CATALOG.find((c) => c.id === id)?.access;
@@ -172,6 +176,11 @@ const ENTRIES = [
         limits: { maxVcpu: 8, maxMemoryGb: 16 },
         credentials: [["BL_API_KEY", "BL_WORKSPACE"]],
         docs: "https://docs.blaxel.ai/Sandboxes/Overview",
+        noBenchmarks: {
+            clause: "Blaxel's terms (§2.6(f)) don't allow publishing benchmarks or performance information about it",
+            source: "https://blaxel.ai/legal/terms/2025-12-10-blaxel-terms-and-conditions.pdf",
+            checked: "2026-11-07",
+        },
     },
     {
         id: "tensorlake",
@@ -524,6 +533,11 @@ ENTRIES.push({
     limits: { maxVcpu: 16, maxMemoryGb: 96 },
     credentials: [["LANGSMITH_API_KEY"]],
     docs: "https://docs.langchain.com/langsmith/sandboxes",
+    access: {
+        status: "waitlist",
+        note: "Sandboxes are a private preview: until LangChain enables them for your organization, the API answers \"Sandbox feature is not enabled for this organization\"",
+        checked: "2026-11-07",
+    },
 }, {
     id: "novita",
     name: "Novita AI Agent Sandbox",

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, publishableCheck } from "./results.js";
 import { loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
-import { DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, hourlyCost, listingOrder, planLabel, unfit } from "./catalog.js";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, benchmarksPublishable, 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,6 +77,7 @@ 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);
@@ -92,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,
@@ -203,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 = publishableCheck({ tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...(by ? { by } : {}), ...report });
                 writeFileSync(`${saveDir}/${p}.json`, JSON.stringify(saved, null, 2) + "\n");
             }
         }
@@ -264,7 +276,10 @@ 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 left = rows.filter((r) => !benchmarksPublishable(r.provider)).map((r) => r.provider);
+            if (left.length)
+                console.log(`\nleft out of the shared report: ${left.join(", ")} (their terms don't allow publishing benchmarks)`);
             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.`);
@@ -284,11 +299,16 @@ 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`;
             mkdirSync(file.replace(/\/[^/]*$/, "") || ".", { recursive: true });
-            writeFileSync(file, JSON.stringify(await settle(run), null, 2) + "\n");
+            const settled = await settle(run);
+            const left = settled.entries.filter((e) => !benchmarksPublishable(e.provider)).map((e) => e.provider);
+            writeFileSync(file, JSON.stringify({ ...settled, entries: settled.entries.filter((e) => benchmarksPublishable(e.provider)) }, null, 2) + "\n");
+            if (left.length)
+                console.log(`left out of ${file}: ${left.join(", ")} (their terms don't allow publishing benchmarks; the table above is the only copy)`);
             console.log(costMarkdown(run));
             console.log(`\nwrote ${file}. Bills post late on some providers: run "sandboxrouter cost settle ${file}" again later.`);
             return;

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,8 +48,17 @@ export interface CostRun {
     date: string;
     minutes: number;
     load: boolean;
+    /** GitHub username of whoever ran it, from `--by`. */
+    by?: string;
     entries: CostEntry[];
 }
+/**
+ * The size the sandbox really has, as "<vcpus> <memoryMb>". nproc and MemTotal can show the whole host
+ * (Daytona's containers report 64 CPUs and 755 GB while limited to 1 vCPU and 1 GB), so the cgroup limits
+ * win when they're set: cgroup v2 cpu.max / memory.max, or v1 cfs quota / memory limit. vCPUs can be
+ * fractional (a 50% quota is 0.5).
+ */
+export declare const PROBE: string;
 export declare function costRun(opts: {
     providers: ProviderId[];
     minutes: number;
@@ -57,6 +66,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

@@ -1,6 +1,18 @@
 import { fittingSpec, hourlyCost } from "./catalog.js";
 import { Router } from "./router.js";
-const PROBE = `echo "$(nproc) $(awk '/MemTotal/{printf "%d", $2/1024}' /proc/meminfo)"`;
+/**
+ * The size the sandbox really has, as "<vcpus> <memoryMb>". nproc and MemTotal can show the whole host
+ * (Daytona's containers report 64 CPUs and 755 GB while limited to 1 vCPU and 1 GB), so the cgroup limits
+ * win when they're set: cgroup v2 cpu.max / memory.max, or v1 cfs quota / memory limit. vCPUs can be
+ * fractional (a 50% quota is 0.5).
+ */
+export const PROBE = [
+    `n=$(nproc); m=$(awk '/MemTotal/{printf "%d", $2/1024}' /proc/meminfo)`,
+    `q=; p=; l=`,
+    `if [ -r /sys/fs/cgroup/cpu.max ]; then read q p < /sys/fs/cgroup/cpu.max; elif [ -r /sys/fs/cgroup/cpu/cpu.cfs_quota_us ]; then q=$(cat /sys/fs/cgroup/cpu/cpu.cfs_quota_us); p=$(cat /sys/fs/cgroup/cpu/cpu.cfs_period_us); fi`,
+    `if [ -r /sys/fs/cgroup/memory.max ]; then l=$(cat /sys/fs/cgroup/memory.max); elif [ -r /sys/fs/cgroup/memory/memory.limit_in_bytes ]; then l=$(cat /sys/fs/cgroup/memory/memory.limit_in_bytes); fi`,
+    `awk -v n="$n" -v m="$m" -v q="$q" -v p="$p" -v l="$l" 'BEGIN { c = n; if (q ~ /^[0-9]+$/ && p ~ /^[0-9]+$/ && p > 0 && q / p < c) c = q / p; if (l ~ /^[0-9]+$/ && l / 1048576 < m) m = int(l / 1048576); printf "%s %d\\n", (c == int(c) ? c : sprintf("%.2f", c)), m }'`,
+].join("; ");
 // One `yes` per core, detached so the exec returns; they die with the sandbox.
 const LOAD = `nohup sh -c 'for i in $(seq $(nproc)); do yes > /dev/null & done; wait' > /dev/null 2>&1 &`;
 const round = (n, d = 6) => Math.round(n * 10 ** d) / 10 ** d;
@@ -46,7 +58,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

@@ -1,6 +1,6 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { CATALOG, fittingSpec, hourlyCost } from "./catalog.js";
+import { benchmarksPublishable, CATALOG, fittingSpec, hourlyCost } from "./catalog.js";
 import { median } from "./bench-store.js";
 export function makeReport(rows, opts) {
     return {
@@ -8,12 +8,14 @@ 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 },
         node: process.version,
         platform: `${process.platform}-${process.arch}`,
-        rows: rows.map(({ lastError: _drop, ...r }) => r),
+        // Providers whose terms forbid publishing benchmarks stay out of anything meant to be shared.
+        rows: rows.filter((r) => benchmarksPublishable(r.provider)).map(({ lastError: _drop, ...r }) => r),
     };
 }
 export function loadReports(dir) {

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,45 @@
+/**
+ * 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;
+/**
+ * A saved check as it may be published: for a provider whose terms forbid publishing benchmarks,
+ * pass/fail stays and every timing goes (the per-step `ms`, and notes that quote a duration).
+ */
+export declare function publishableCheck<T extends {
+    provider: string;
+    results: {
+        ms?: number;
+        detail?: string;
+    }[];
+}>(saved: T): T;
+/** 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;
+    }[];
+    previous?: (path: string) => string | undefined;
+    now?: number;
+}): Issue[];

package/dist/results.js

@@ -0,0 +1,260 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { benchmarksPublishable, 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));
+/** A timing in a check step's note, e.g. "first output after 100 ms" or "threw after 3.0 s". */
+const TIMING = /\d[\d,.]*\s?(?:ms|s|sec|seconds?)\b/i;
+/**
+ * A saved check as it may be published: for a provider whose terms forbid publishing benchmarks,
+ * pass/fail stays and every timing goes (the per-step `ms`, and notes that quote a duration).
+ */
+export function publishableCheck(saved) {
+    if (benchmarksPublishable(saved.provider))
+        return saved;
+    return {
+        ...saved,
+        results: saved.results.map(({ ms: _ms, detail, ...r }) => ({ ...r, ...(detail && !TIMING.test(detail) ? { detail } : {}) })),
+    };
+}
+const noBench = (id) => typeof id === "string" && IDS.has(id) && !benchmarksPublishable(id);
+const NO_BENCH = "its terms don't allow publishing benchmarks (noBenchmarks in src/catalog.ts); leave it out of shared results";
+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 (noBench(r?.provider))
+                out.push(`${r.provider}: ${NO_BENCH}`);
+            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 (r?.ms !== undefined && !isNum(r.ms, 0, MAX_MS))
+                out.push(`${r?.step}: ms must be between 0 and 15 min`);
+            if (noBench(j.provider) && (r?.ms !== undefined || (typeof r?.detail === "string" && TIMING.test(r.detail)))) {
+                out.push(`${r?.step}: has timings, but ${j.provider}'s terms don't allow publishing performance information; save with check --save`);
+            }
+        }
+    }
+    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 (noBench(e?.provider))
+                out.push(`${e.provider}: ${NO_BENCH}`);
+            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) && !onlyDropsUnpublishable(opts.previous?.(p), p)) {
+            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;
+}
+/**
+ * True when a bench report's only change is removing rows for providers whose terms forbid publishing
+ * benchmarks: the one edit to someone's report that's allowed, so those numbers can be taken down.
+ */
+function onlyDropsUnpublishable(before, path) {
+    if (before === undefined || !existsSync(path))
+        return false;
+    try {
+        const a = JSON.parse(before);
+        const b = JSON.parse(readFileSync(path, "utf8"));
+        const { rows: ra, ...restA } = a;
+        const { rows: rb, ...restB } = b;
+        if (JSON.stringify(restA) !== JSON.stringify(restB))
+            return false;
+        const kept = ra.filter((r) => benchmarksPublishable(r.provider));
+        return JSON.stringify(kept) === JSON.stringify(rb);
+    }
+    catch {
+        return false;
+    }
+}

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()];
@@ -207,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, 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);
                 }
             }
@@ -334,8 +336,12 @@ function round(n) {
 }
 /** Seconds to wait for one provider's create before trying the next (RouteOptions.createTimeoutSeconds). */
 export const DEFAULT_CREATE_TIMEOUT_S = 120;
-/** HTTP statuses that mean the request or the account is wrong, not that the provider is down. */
-const SETUP_ERRORS = new Set([400, 401, 402, 403, 404, 422]);
+/**
+ * HTTP statuses that mean the request or the key is wrong, not that the provider is down. 402 (out of
+ * balance, plan needed) isn't one: an unfunded account is exactly when the next provider should take the
+ * sandbox, and the failed attempt stays on `attempts` (the CLI prints it), so it isn't hidden.
+ */
+const SETUP_ERRORS = new Set([400, 401, 403, 404, 422]);
 /** Seconds past a command's timeout before the router stops waiting for the adapter. */
 export const EXEC_GRACE_S = 30;
 /** Resolve with `work`, or reject with `onExpire()` after `ms`. A late `work` rejection is swallowed. */

package/dist/types.d.ts

@@ -33,9 +33,10 @@ export interface RouteOptions {
     strategy?: Strategy;
     /**
      * What to do when a create fails. `true` (default): try the next candidate when the provider
-     * looks unavailable (timeout, network error, 429, 5xx, or an error without a status), but stop on
-     * a setup error (400, 401, 402, 403, 404, 422: a bad key, no billing, a bad image or request), so
-     * a mistake isn't hidden by quietly moving the work to another, maybe pricier, provider.
+     * looks unavailable (timeout, network error, 429, 5xx, or an error without a status) or can't bill
+     * (402: no balance, plan needed), but stop on a setup error (400, 401, 403, 404, 422: a bad key, a
+     * bad image or request), so a mistake isn't hidden by quietly moving the work to another, maybe
+     * pricier, provider. Every failed attempt is on `sandbox.attempts`.
      * `"any"`: try the next candidate on every error. `false`: only the first candidate.
      */
     fallback?: boolean | "any";
@@ -93,3 +94,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.1",
+  "version": "0.3.3",
   "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",