@sandboxrouter/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gigi Alcaraz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,294 @@
-# Temporary Holding Version
+# sandboxrouter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**One API for every sandbox.** A free, open-source router for the places an AI agent can run code: Blaxel, Boat, Cloudflare, Daytona, E2B, exe.dev, Fly.io Sprites, HOPX, Maritime, Modal, Morph, Northflank, Runloop, Tensorlake and Vercel, plus Docker on your own machine. It picks a provider by price, speed or capability, and falls back to the next one when a provider is down or rate-limited.
+
+```ts
+import { Router } from "@sandboxrouter/sdk";
+
+const router = new Router();                       // uses whichever provider keys you've set
+await using sbx = await router.create({ vcpu: 2, memoryGb: 4 });
+
+const r = await sbx.exec("python3 -c 'print(6*7)'");
+console.log(r.stdout, "ran on", sbx.provider);
+```
+
+Change providers without changing code. 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)
+
+## Why
+
+Agents need a disposable computer: to run code a model wrote, install packages, run tests, scrape, or do an RL rollout. There are more than a dozen sandbox providers, each with its own SDK, auth, lifecycle and price, and the same 2 vCPU / 4 GB box costs anywhere from a few cents to over thirty cents an hour.
+
+So every agent team either locks into one provider or writes its own adapter layer. sandboxrouter is that adapter layer, done once, in the open:
+
+- **One interface.** `create`, `exec`, `writeFile`, `readFile`, `pause`, `kill`, the same on every provider. `exec` streams stdout and stderr as they happen.
+- **Routing.** `cheapest` (the default: lowest list price for your size) or `fastest` (lowest cold start you measured with `bench`), or name providers yourself.
+- **Fallback.** A failed create moves to the next candidate, and every attempt is recorded on `sbx.attempts`.
+- **Capability filters.** Ask for a GPU and only GPU-capable providers are tried. Ask for 32 vCPU and providers that can't do it are skipped, with the reason.
+- **Your keys.** Your accounts, your bills. Nothing is proxied through a third party.
+- **HTTP server and Python client.** Run `sandboxrouter serve` and any language gets the same API.
+- **Computers.** Desktops and phones for computer-use models (Maritime today): actions, screenshots, and a takeover link for a person when the model hits a login.
+- **Open benchmark.** `bench --share` produces a report; cold starts on the site come from reports submitted to [`results/`](results/).
+
+## Fair by construction
+
+No provider gets a better slot, and none pays for placement.
+
+- With no strategy, a sandbox goes to the **lowest list price for the size you asked for**, among providers you have keys for. Ties break **alphabetically**.
+- `fastest` uses only cold starts **you** measured with `bench`, then price.
+- Prices are each provider's public rate, with a source link, in [`src/catalog.ts`](src/catalog.ts). There's a test that the catalog has no privileged ordering.
+- Docker is never picked automatically, because it always "costs" $0 and isolates less than a cloud micro-VM. Name it to use it.
+
+If a price is wrong, open a PR with the source link.
+
+## Prices
+
+Estimated list price while running, 2 vCPU / 4 GB (`npx @sandboxrouter/sdk providers --vcpu 2 --memory 4`), in the order the router would try them:
+
+| Provider | $/hr | Notes | Source |
+|---|---|---|---|
+| Boat | $0.018 | 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 | Per second, disk included | [pricing](https://maritime.sh/pricing) |
+| Northflank | $0.067 | Per second on Northflank Cloud, ephemeral disk included; sandboxes run as deployment services (microVMs) | [pricing](https://northflank.com/pricing) |
+| Morph Cloud | $0.100 | $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 | $0.105/h per 2 vCPU + 4 GiB, per second, up to 2 GiB per vCPU; needs an exe.dev subscription | [pricing](https://exe.dev/docs/standalone-vms.md) |
+| Fly.io Sprites | $0.164 | Bills actual CPU and memory use; this is the full-use price; storage extra | [pricing](https://fly.io/sprites) |
+| Blaxel | $0.166 | Billed on memory only ($0.0000115/GB-s), CPU scales with memory (~2 GB per core) | [pricing](https://blaxel.ai/pricing) |
+| Daytona | $0.166 | Per second, plus disk above 5 GiB | [pricing](https://www.daytona.io/pricing) |
+| E2B | $0.166 | Per second; Pro plan $150/mo | [pricing](https://e2b.dev/pricing) |
+| HOPX | $0.166 | Per second, plus storage; size comes from the template, not the request | [pricing](https://hopx.ai/pricing) |
+| Tensorlake | $0.200 | Bills active CPU (floor 20% of allocation); this is the full-use price; Pro plan is lower | [pricing](https://www.tensorlake.ai/pricing) |
+| Cloudflare Sandbox | $0.216 | Bills active CPU and provisioned memory of the instance type; this is the full-CPU price; needs Workers Paid ($5/mo) and the bridge Worker in bridges/cloudflare | [pricing](https://developers.cloudflare.com/containers/platform/pricing/) |
+| Modal | $0.239 | Sandbox rates, GPUs extra; region pinning x1.15-1.75 | [pricing](https://modal.com/pricing) |
+| Runloop | $0.317 | Per second, plus disk; pause (suspend) is a Pro-plan feature | [pricing](https://www.runloop.ai/pricing) |
+| Vercel Sandbox | $0.341 | Bills active CPU only; this is the 100%-CPU price, idle work costs less | [pricing](https://vercel.com/docs/vercel-sandbox/pricing) |
+| Docker (local) | free | 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.
+
+## Install
+
+```bash
+npm i @sandboxrouter/sdk
+# then the SDK of each provider you use (Boat, Cloudflare, exe.dev, Maritime and Docker need none):
+npm i e2b                       # E2B
+npm i @daytonaio/sdk            # Daytona
+npm i modal                     # Modal
+npm i @vercel/sandbox           # Vercel Sandbox
+npm i morphcloud                # Morph Cloud
+npm i @fly/sprites              # Fly.io Sprites (its package asks for Node 24+)
+npm i @blaxel/core              # Blaxel
+npm i @tensorlakeai/tensorlake  # Tensorlake
+npm i @runloop/api-client       # Runloop
+npm i @hopx-ai/sdk              # HOPX
+npm i @northflank/js-client     # Northflank
+```
+
+Cloudflare sandboxes only run inside a Cloudflare Worker, so you deploy a small bridge Worker to your own account first: see [`bridges/cloudflare`](bridges/cloudflare).
+
+Set the keys for the providers you want. Providers without keys are skipped.
+
+| Provider | Env |
+|---|---|
+| Blaxel | `BL_API_KEY` + `BL_WORKSPACE` |
+| Boat | `BOAT_API_KEY` |
+| Cloudflare Sandbox | `CLOUDFLARE_SANDBOX_URL` + `CLOUDFLARE_SANDBOX_TOKEN` |
+| Daytona | `DAYTONA_API_KEY` |
+| Docker (local) | none: Docker running locally |
+| E2B | `E2B_API_KEY` |
+| exe.dev | `EXE_TOKEN` |
+| Fly.io Sprites | `SPRITES_TOKEN` |
+| HOPX | `HOPX_API_KEY` |
+| Maritime | `MARITIME_API_KEY` |
+| Modal | `MODAL_TOKEN_ID` + `MODAL_TOKEN_SECRET` |
+| Morph Cloud | `MORPH_API_KEY` |
+| Northflank | `NORTHFLANK_API_TOKEN` + `NORTHFLANK_PROJECT_ID` |
+| Runloop | `RUNLOOP_API_KEY` |
+| Tensorlake | `TENSORLAKE_API_KEY` |
+| Vercel Sandbox | `VERCEL_OIDC_TOKEN`, or `VERCEL_TOKEN` + `VERCEL_TEAM_ID` + `VERCEL_PROJECT_ID` |
+
+## Library
+
+```ts
+const router = new Router();
+
+// Cheapest provider that can do 8 vCPU / 16 GB, falling back on failure
+const a = await router.create({ vcpu: 8, memoryGb: 16 }, { strategy: "cheapest" });
+
+// GPU: only GPU-capable providers are tried (Modal today)
+const b = await router.create({ gpu: "A10G", image: { modal: "pytorch/pytorch:latest" } });
+
+// Pin providers in order and turn fallback off
+const c = await router.create({}, { provider: ["maritime", "e2b"], fallback: false });
+
+// Per-provider images: each provider names its templates differently
+const d = await router.create({ image: { maritime: "python", e2b: "code-interpreter-v1", modal: "python:3.13-slim" } });
+
+// Files
+await a.writeFile("/tmp/data.csv", "x,y\n1,2\n");
+console.log(await a.readText("/tmp/data.csv"));
+
+// Stream output as it happens (the full output is still returned)
+await a.exec("npm test", { onStdout: (c) => process.stdout.write(c), onStderr: (c) => process.stderr.write(c) });
+
+// Pause keeps the disk (and memory, where the provider snapshots it); router.get() resumes
+const p = await router.create({}, { require: ["pause"] });
+await p.pause();
+
+// Ids are portable across processes: "provider:nativeId"
+const again = await router.get(a.id);
+
+// Dry run: who would be tried, in what order, and why anything is skipped
+console.table(router.plan({ vcpu: 32 }));
+
+await a.kill();
+```
+
+`create` throws a `RouterError` whose `attempts` lists every provider it tried and why each failed.
+
+## Computers (desktops and phones)
+
+For computer-use agents: a machine with a screen that your model drives with clicks and keys. Maritime provides Linux desktops, Windows desktops and Android phones on the same key. Actions use the Anthropic computer-use shape.
+
+```ts
+const desk = await router.computer({ os: "linux", externalUserId: "user_42" }); // same id, same desktop
+const shot = await desk.act({ action: "screenshot" });            // { frameId, width, height, imageB64 }
+await desk.act({ action: "left_click", coordinate: [412, 230] });
+await desk.actBatch([{ action: "type", text: "hello" }, { action: "key", text: "Return" }]);
+await desk.exec("ls /data");
+
+// Hit a login or CAPTCHA? Hand the desktop to a person, then carry on.
+const { url } = await desk.viewer("control", { reason: "Please sign in" });
+```
+
+```bash
+npx @sandboxrouter/sdk desktop --os linux --user user_42 --control   # prints a takeover link
+npx @sandboxrouter/sdk screenshot maritime:<id> --out screen.png
+```
+
+## CLI
+
+```bash
+npx @sandboxrouter/sdk providers                    # price table + which keys are set
+npx @sandboxrouter/sdk route --gpu T4               # dry run
+npx @sandboxrouter/sdk run "uname -a && nproc"      # start, run, print, kill
+npx @sandboxrouter/sdk run "pytest -q" --provider e2b,maritime --keep
+npx @sandboxrouter/sdk bench --runs 5               # cold start + exec latency table
+npx @sandboxrouter/sdk bench --share --label "us-east-1"   # also write a report for results/
+npx @sandboxrouter/sdk leaderboard results --out leaderboard.html
+npx @sandboxrouter/sdk serve --port 8787            # HTTP API
+```
+
+### Bench
+
+`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.
+
+## HTTP API
+
+```bash
+SANDBOXROUTER_TOKEN=secret npx @sandboxrouter/sdk serve
+```
+
+| Method | Path | Body |
+|---|---|---|
+| `GET` | `/v1/providers` | |
+| `POST` | `/v1/route` | same as create; returns the candidate order |
+| `POST` | `/v1/sandboxes` | `{ vcpu, memoryGb, gpu, env, timeoutMinutes, image, metadata, provider, strategy, fallback, require }` |
+| `POST` | `/v1/sandboxes/:id/exec` | `{ cmd, cwd, env, timeoutSeconds, stream }`. With `stream: true` the answer is `text/event-stream`: `stdout` and `stderr` events, then `result` |
+| `POST` | `/v1/sandboxes/:id/pause` | |
+| `PUT` | `/v1/sandboxes/:id/files?path=` | raw bytes |
+| `GET` | `/v1/sandboxes/:id/files?path=` | |
+| `DELETE` | `/v1/sandboxes/:id` | |
+| `POST` | `/v1/computers` | `{ os, externalUserId, name, screen, arch, provider }` |
+| `POST` | `/v1/computers/:id/actions` | one action, or `{ actions: [...] }` (up to 50) |
+| `GET` | `/v1/computers/:id/screenshot` | image bytes (`?format=jpeg&quality=80`) |
+| `POST` | `/v1/computers/:id/exec` | `{ command, timeoutSeconds }` (max 30 s) |
+| `PUT` / `GET` | `/v1/computers/:id/files?path=` | raw bytes |
+| `POST` | `/v1/computers/:id/viewer` | `{ mode: "watch" \| "control", ttlSeconds, reason }` |
+| `POST` | `/v1/computers/:id/sleep` | |
+| `DELETE` | `/v1/computers/:id` | |
+
+```bash
+curl -s localhost:8787/v1/sandboxes -H "Authorization: Bearer secret" \
+  -d '{"vcpu":2,"strategy":"cheapest"}'
+# {"id":"maritime:sbx-k3m7q2ab","provider":"maritime","estimatedHourlyUsd":0.022,"attempts":[...]}
+```
+
+Provider keys stay on the server. Clients only hold `SANDBOXROUTER_TOKEN`. It binds to `127.0.0.1` by default.
+
+### Python
+
+A standard-library client for the HTTP API lives in [`python/`](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:
+    sbx.exec("pip install rich && python -c 'import rich'", on_stdout=lambda c: print(c, end=""))
+```
+
+## How each adapter maps the spec
+
+| | vCPU / memory | Lifetime | Image | Pause | Notes |
+|---|---|---|---|---|---|
+| Maritime | `vcpu`, `memoryMib` | `timeLimitMinutes` (5 to 1,440) | `from` | yes | Plain REST, no SDK. Streams over SSE. Any data-plane call resumes a paused sandbox. |
+| E2B | set by the template | `timeoutMs` | template | yes (memory + disk) | Nonzero exits are returned as results, not thrown. |
+| Daytona | only with `image.daytona` | `autoStopInterval` | `image` | yes (stop/start, disk only) | Non-streaming exec merges stdout and stderr; streaming uses a session and keeps them apart. |
+| Modal | `cpu`, `memoryMiB`, `gpu` | `timeoutMs` | registry tag | no | Uses Modal app `sandboxrouter` (override with `SANDBOXROUTER_MODAL_APP`). |
+| Vercel | `vcpus` (2 GB each) | `timeout` | `runtime` | no | Max 8 vCPU. |
+| Morph | via a cached base snapshot per shape | `ttlSeconds` | snapshot id | yes (memory + disk) | First create of a new shape builds a snapshot. Files over SSH. |
+| Fly.io Sprites | `cpus`, `ramMB` (may be ignored) | none: `kill()` deletes | no | no | Sprites idle for free on their own. |
+| Blaxel | memory (CPU follows) | `ttl` | image | yes (archive, disk only) | Idle sandboxes go to free standby on their own. |
+| Tensorlake | `cpus`, `memoryMb` | idle timeout | image | yes (memory + disk) | Output is line-based. |
+| Runloop | snapped to Runloop's custom sizes | `keep_alive_time_seconds` (max 48 h) | blueprint | yes (Pro plan) | Commands start in the home directory. |
+| HOPX | set by the template | timeout | template | yes (memory + disk) | Size requests aren't applied, so the router only sends default-size work. |
+| Northflank | cheapest `nf-compute` plan that fits | `expiryTime` (5 min to 7 days) | any public image | no | Runs as a deployment service; files move as base64 over exec. |
+| Cloudflare | smallest instance type that fits | alarm in the bridge Worker | Dockerfile in the bridge | no | Through the bridge Worker you deploy ([`bridges/cloudflare`](bridges/cloudflare)). |
+| Boat | smallest of 4 fixed sizes that fits | auto-stop timer | saved snapshot | yes (stop: disk kept, processes end) | Plain REST. Commands that wait are capped at 600 s; files API up to 5 MiB. |
+| exe.dev | `--cpu`, `--memory` (2 GiB per vCPU max) | none: `kill()` deletes | `--image` | no | Plain REST over exe.dev's `/exec`; long commands run detached and are polled. |
+| Docker (local) | `--cpus`, `--memory` | container exits at the lifetime | any image | yes (`docker pause`) | Your machine, shared kernel. Never auto-routed; use `{ provider: "docker" }`. |
+
+Capabilities in the catalog describe what each **adapter** implements, not everything a provider sells. Size limits are self-serve defaults and may be higher on your plan.
+
+## Roadmap
+
+- [x] More providers: Morph, Fly.io Sprites, Blaxel, Tensorlake, Runloop, HOPX, Northflank, Boat, exe.dev, Cloudflare (via a bridge Worker), Docker (local)
+- [x] Neutral routing: price decides, ties alphabetical, no privileged slot
+- [x] Desktops and phones (Maritime: Linux, Windows, Android)
+- [x] Streaming exec output
+- [x] Pause/resume where providers support it
+- [x] Python client
+- [x] Leaderboard built from `bench --share` reports
+- [ ] Computers on more providers (E2B Desktop, Daytona computer use)
+- [ ] Snapshots and forks as a routed operation
+- [ ] A hosted copy of the leaderboard page
+
+## Website
+
+[`web/`](web/) is the project site: home, a browsable Sandboxes list with live price-per-size, a page per provider, Rankings, Docs, and a Playground that drives your own `sandboxrouter serve` from the browser. Its data is generated from the library (`npm run site:data`), so prices never drift from the code.
+
+```bash
+cd web && npm i && npm run dev          # http://localhost:3000
+# Playground without any provider keys (in-memory providers, nothing real starts):
+node --import tsx test/demo-server.ts   # token: demo
+# Playground against real providers:
+SANDBOXROUTER_TOKEN=secret npx @sandboxrouter/sdk serve --cors http://localhost:3000
+```
+
+## Development
+
+```bash
+npm i
+npm test          # router, HTTP server, leaderboard, Maritime sandboxes + computers against contract mocks
+npm run test:py   # Python client against the real HTTP server
+npm run build
+npm run dev -- providers
+```
+
+Adding a provider means implementing `Provider` from [`src/types.ts`](src/types.ts) and adding a catalog entry with a pricing source link.
+
+MIT

package/dist/bench-store.d.ts

@@ -0,0 +1,12 @@
+import type { ProviderId } from "./types.js";
+export interface BenchSample {
+    createMs: number[];
+    execMs: number[];
+    failures: number;
+    at: string;
+}
+export type BenchData = Partial<Record<ProviderId, BenchSample>>;
+export declare const DEFAULT_BENCH_FILE: string;
+export declare function loadBench(file?: string): BenchData;
+export declare function saveBench(data: BenchData, file?: string): void;
+export declare function median(xs?: number[]): number | undefined;

package/dist/bench-store.js

@@ -0,0 +1,23 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const DEFAULT_BENCH_FILE = process.env.SANDBOXROUTER_BENCH_FILE ?? join(homedir(), ".sandboxrouter", "bench.json");
+export function loadBench(file = DEFAULT_BENCH_FILE) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveBench(data, file = DEFAULT_BENCH_FILE) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(data, null, 2));
+}
+export function median(xs) {
+    if (!xs || xs.length === 0)
+        return undefined;
+    const s = [...xs].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}

package/dist/bench.d.ts

@@ -0,0 +1,24 @@
+import { Router } from "./router.js";
+import type { ProviderId, SandboxSpec } from "./types.js";
+export interface BenchRow {
+    provider: ProviderId;
+    runs: number;
+    failures: number;
+    medianCreateMs?: number;
+    medianExecMs?: number;
+    hourlyUsd: number;
+    lastError?: string;
+}
+/**
+ * Cold start = time from create() call to a usable sandbox. Exec = round trip of `echo ok`.
+ * Measured from wherever you run it, so network distance to each provider counts.
+ */
+export declare function bench(opts: {
+    router?: Router;
+    providers?: ProviderId[];
+    runs?: number;
+    spec?: SandboxSpec;
+    benchFile?: string;
+    onProgress?: (msg: string) => void;
+}): Promise<BenchRow[]>;
+export declare function benchMarkdown(rows: BenchRow[]): string;

package/dist/bench.js

@@ -0,0 +1,65 @@
+import { CATALOG, hourlyCost } from "./catalog.js";
+import { loadBench, median, saveBench } from "./bench-store.js";
+import { Router } from "./router.js";
+/**
+ * Cold start = time from create() call to a usable sandbox. Exec = round trip of `echo ok`.
+ * Measured from wherever you run it, so network distance to each provider counts.
+ */
+export async function bench(opts) {
+    const router = opts.router ?? new Router();
+    const runs = opts.runs ?? 3;
+    const spec = opts.spec ?? { timeoutMinutes: 5 };
+    const ids = opts.providers ?? router.registered().filter((id) => router.isConfigured(id));
+    const log = opts.onProgress ?? (() => { });
+    const stored = loadBench(opts.benchFile);
+    const rows = [];
+    for (const id of ids) {
+        const createMs = [];
+        const execMs = [];
+        let failures = 0;
+        let lastError;
+        for (let i = 0; i < runs; i++) {
+            log(`${id} run ${i + 1}/${runs}`);
+            let box;
+            try {
+                const t0 = performance.now();
+                box = await router.create(spec, { provider: id, fallback: false });
+                createMs.push(Math.round(performance.now() - t0));
+                const t1 = performance.now();
+                const r = await box.exec("echo ok");
+                if (r.exitCode !== 0 || r.stdout.trim() !== "ok")
+                    throw new Error(`echo returned ${r.exitCode}: ${r.stdout}${r.stderr}`);
+                execMs.push(Math.round(performance.now() - t1));
+            }
+            catch (err) {
+                failures++;
+                lastError = err.message.slice(0, 200);
+            }
+            finally {
+                await box?.kill().catch(() => { });
+            }
+        }
+        stored[id] = { createMs, execMs, failures, at: new Date().toISOString() };
+        rows.push({
+            provider: id,
+            runs,
+            failures,
+            medianCreateMs: median(createMs),
+            medianExecMs: median(execMs),
+            hourlyUsd: hourlyCost(id, spec),
+            lastError,
+        });
+    }
+    saveBench(stored, opts.benchFile);
+    return rows.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity));
+}
+export function benchMarkdown(rows) {
+    const name = (id) => CATALOG.find((c) => c.id === id).name;
+    const ms = (n) => (n === undefined ? "n/a" : `${n} ms`);
+    const lines = [
+        "| # | Provider | Cold start (median) | Exec round trip | $/hr (2 vCPU, 4 GB) | Success |",
+        "|---|---|---|---|---|---|",
+        ...rows.map((r, i) => `| ${i + 1} | ${name(r.provider)} | ${ms(r.medianCreateMs)} | ${ms(r.medianExecMs)} | $${r.hourlyUsd.toFixed(3)} | ${r.runs - r.failures}/${r.runs} |`),
+    ];
+    return lines.join("\n");
+}

package/dist/catalog.d.ts

@@ -0,0 +1,105 @@
+import type { Capability, ProviderId, SandboxSpec } from "./types.js";
+export interface ProviderInfo {
+    id: ProviderId;
+    name: string;
+    /** List price while running, USD. */
+    pricing: {
+        vcpuHour: number;
+        gbHour: number;
+        note?: string;
+        source: string;
+        checked: string;
+    };
+    /** Capabilities this adapter actually implements, not everything the provider markets. */
+    capabilities: Capability[];
+    limits: {
+        maxVcpu: number;
+        maxMemoryGb: number;
+    };
+    /** Runs on your own machine (Docker). Never chosen automatically; name it to use it. */
+    local?: boolean;
+    /** Env vars the adapter reads. Any one group being fully set means "configured". */
+    credentials: string[][];
+    docs: string;
+}
+export declare const CATALOG: ProviderInfo[];
+/** Cloudflare only rents fixed instance types: https://developers.cloudflare.com/containers/platform/limits/ */
+export declare const CLOUDFLARE_INSTANCES: readonly [{
+    readonly name: "lite";
+    readonly vcpu: number;
+    readonly memoryGb: 0.25;
+}, {
+    readonly name: "basic";
+    readonly vcpu: number;
+    readonly memoryGb: 1;
+}, {
+    readonly name: "standard-1";
+    readonly vcpu: number;
+    readonly memoryGb: 4;
+}, {
+    readonly name: "standard-2";
+    readonly vcpu: 1;
+    readonly memoryGb: 6;
+}, {
+    readonly name: "standard-3";
+    readonly vcpu: 2;
+    readonly memoryGb: 8;
+}, {
+    readonly name: "standard-4";
+    readonly vcpu: 4;
+    readonly memoryGb: 12;
+}];
+/** Boat's fixed machine sizes and hourly prices: https://docs.boat.dev/machines.md */
+export declare const BOAT_SIZES: readonly [{
+    readonly type: "small";
+    readonly vcpu: 2;
+    readonly memoryGb: 4;
+    readonly usdHour: 0.018;
+}, {
+    readonly type: "default";
+    readonly vcpu: 4;
+    readonly memoryGb: 8;
+    readonly usdHour: 0.036;
+}, {
+    readonly type: "large";
+    readonly vcpu: 8;
+    readonly memoryGb: 16;
+    readonly usdHour: 0.072;
+}, {
+    readonly type: "xlarge";
+    readonly vcpu: 16;
+    readonly memoryGb: 32;
+    readonly usdHour: 0.2;
+}];
+export declare function cloudflareInstance(vcpu: number, memoryGb: number): {
+    readonly name: "lite";
+    readonly vcpu: number;
+    readonly memoryGb: 0.25;
+} | {
+    readonly name: "basic";
+    readonly vcpu: number;
+    readonly memoryGb: 1;
+} | {
+    readonly name: "standard-1";
+    readonly vcpu: number;
+    readonly memoryGb: 4;
+} | {
+    readonly name: "standard-2";
+    readonly vcpu: 1;
+    readonly memoryGb: 6;
+} | {
+    readonly name: "standard-3";
+    readonly vcpu: 2;
+    readonly memoryGb: 8;
+} | {
+    readonly name: "standard-4";
+    readonly vcpu: 4;
+    readonly memoryGb: 12;
+};
+export declare function info(id: ProviderId): ProviderInfo;
+export declare const DEFAULT_VCPU = 2;
+export declare const DEFAULT_MEMORY_GB = 4;
+/** Estimated USD per hour for this spec on this provider (list price, while running). */
+export declare function hourlyCost(id: ProviderId, spec?: SandboxSpec): number;
+/** Why a provider can't take this spec, or null if it can. */
+export declare function unfit(id: ProviderId, spec: SandboxSpec, require?: Capability[]): string | null;