@sandboxrouter/sdk 0.3.0 → 0.3.1

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

@@ -7,7 +7,7 @@ import { costMarkdown, costRun, settle } from "./cost.js";
 import { checkProvider } from "./check.js";
 import { gc, listOpen } from "./gc.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";
@@ -78,6 +78,12 @@ const { values, positionals } = parseArgs({
     },
 });
 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),
@@ -99,10 +105,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 +118,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") {

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

@@ -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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxrouter/sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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",