@sandboxrouter/sdk 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFileSync, writeFileSync } from "node:fs";
+import { bench, benchMarkdown } from "./bench.js";
+import { loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
+import { CATALOG, hourlyCost } from "./catalog.js";
+import { Router } from "./router.js";
+import { createApp } from "./server.js";
+import { RouterError } from "./types.js";
+const HELP = `sandboxrouter: one API for every sandbox provider
+
+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 bench     [--runs 3] [--provider a,b] [--json] [--share [--label "where you ran it"]]
+  sandboxrouter leaderboard [results-dir] [--out leaderboard.html]
+  sandboxrouter desktop   [--os linux|windows|android] [--user ID] [--control]
+                          get or create a computer and print a link to watch (or take over) its screen
+  sandboxrouter screenshot <provider:id> [--out screen.png]
+  sandboxrouter serve     [--port 8787] [--host 127.0.0.1] [--cors https://site.example,http://localhost:3000]
+
+Spec flags:   --vcpu N  --memory GB  --gpu T4  --timeout MIN
+Route flags:  --provider maritime[,e2b,...]  --strategy default|cheapest|fastest
+              --no-fallback  --require gpu,custom-image
+
+Keys: MARITIME_API_KEY, E2B_API_KEY, DAYTONA_API_KEY, MODAL_TOKEN_ID+MODAL_TOKEN_SECRET,
+      VERCEL_OIDC_TOKEN (or VERCEL_TOKEN+VERCEL_TEAM_ID+VERCEL_PROJECT_ID)`;
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        vcpu: { type: "string" },
+        memory: { type: "string" },
+        gpu: { type: "string" },
+        timeout: { type: "string" },
+        provider: { type: "string" },
+        strategy: { type: "string" },
+        "no-fallback": { type: "boolean" },
+        require: { type: "string" },
+        keep: { type: "boolean" },
+        runs: { type: "string" },
+        json: { type: "boolean" },
+        port: { type: "string" },
+        host: { type: "string" },
+        help: { type: "boolean", short: "h" },
+        os: { type: "string" },
+        user: { type: "string" },
+        control: { type: "boolean" },
+        out: { type: "string" },
+        share: { type: "boolean" },
+        cors: { type: "string" },
+        label: { type: "string" },
+    },
+});
+const list = (s) => (s ? s.split(",").map((x) => x.trim()).filter(Boolean) : undefined);
+const num = (s) => (s === undefined ? undefined : Number(s));
+const spec = {
+    vcpu: num(values.vcpu),
+    memoryGb: num(values.memory),
+    gpu: values.gpu,
+    timeoutMinutes: num(values.timeout),
+};
+const providers = list(values.provider);
+const route = {
+    provider: providers,
+    strategy: values.strategy,
+    fallback: values["no-fallback"] ? false : undefined,
+    require: list(values.require),
+};
+async function main() {
+    const [cmd, ...rest] = positionals;
+    const router = new Router();
+    if (!cmd || values.help)
+        return console.log(HELP);
+    if (cmd === "providers") {
+        const rows = CATALOG.map((c) => ({
+            provider: c.name,
+            id: c.id,
+            "$/hr": `$${hourlyCost(c.id, spec).toFixed(4)}`,
+            configured: router.isConfigured(c.id) ? "yes" : "no",
+            capabilities: c.capabilities.join(", ") || "-",
+        }));
+        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:\n`);
+        console.table(rows);
+        return;
+    }
+    if (cmd === "route") {
+        const plan = router.plan(spec, route);
+        if (values.json)
+            return console.log(JSON.stringify(plan, null, 2));
+        let n = 0;
+        for (const c of plan) {
+            const mark = c.skip ? "  -" : `${++n}.`.padStart(3);
+            console.log(`${mark} ${c.provider.padEnd(11)} $${c.estimatedHourlyUsd.toFixed(4)}/hr${c.skip ? `  (skipped: ${c.skip})` : ""}`);
+        }
+        return;
+    }
+    if (cmd === "run") {
+        const command = rest.join(" ");
+        if (!command)
+            throw new RouterError('usage: sandboxrouter run "<cmd>"');
+        const sbx = await router.create(spec, route);
+        for (const a of sbx.attempts.filter((a) => !a.ok))
+            console.error(`! ${a.provider} failed, fell back: ${a.error}`);
+        console.error(`> ${sbx.id} on ${sbx.provider} (~$${sbx.estimatedHourlyUsd}/hr, started in ${sbx.attempts.at(-1)?.ms} ms)`);
+        try {
+            const r = await sbx.exec(command, {
+                timeoutSeconds: 600,
+                onStdout: (c) => process.stdout.write(c),
+                onStderr: (c) => process.stderr.write(c),
+            });
+            process.exitCode = r.exitCode;
+        }
+        finally {
+            if (values.keep)
+                console.error(`> kept alive: ${sbx.id}`);
+            else
+                await sbx.kill();
+        }
+        return;
+    }
+    if (cmd === "bench") {
+        const rows = await bench({
+            router,
+            providers,
+            runs: num(values.runs) ?? 3,
+            spec: { ...spec, timeoutMinutes: spec.timeoutMinutes ?? 5 },
+            onProgress: (m) => console.error(m),
+        });
+        if (rows.length === 0)
+            return console.error("No providers configured. Set at least one API key (see --help).");
+        if (values.json)
+            return console.log(JSON.stringify(rows, null, 2));
+        console.log(`\nsandboxrouter bench: ${new Date().toISOString().slice(0, 10)}, ${rows[0].runs} runs each\n`);
+        console.log(benchMarkdown(rows));
+        for (const r of rows.filter((r) => r.lastError))
+            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 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.`);
+        }
+        return;
+    }
+    if (cmd === "leaderboard") {
+        const dir = rest[0] ?? "results";
+        const reports = loadReports(dir);
+        const out = values.out ?? "leaderboard.html";
+        writeFileSync(out, renderLeaderboard(reports));
+        console.log(`wrote ${out} from ${reports.length} report${reports.length === 1 ? "" : "s"} in ${dir}/`);
+        return;
+    }
+    if (cmd === "desktop") {
+        const os = (values.os ?? "linux");
+        const c = await router.computer({ os, externalUserId: values.user }, { provider: providers });
+        const info = await c.info();
+        const link = await c.viewer(values.control ? "control" : "watch");
+        console.log(`${c.id}  ${info.os}  ${info.status}${info.screen ? `  ${info.screen.width}x${info.screen.height}` : ""}`);
+        console.log(`${values.control ? "take over" : "watch"}: ${link.url}  (expires ${link.expiresAt})`);
+        return;
+    }
+    if (cmd === "screenshot") {
+        const id = rest[0];
+        if (!id)
+            throw new RouterError("usage: sandboxrouter screenshot <provider:id> [--out screen.png]");
+        const img = await (await router.getComputer(id)).screenshot();
+        const out = values.out ?? "screen.png";
+        (await import("node:fs")).writeFileSync(out, img);
+        console.log(`wrote ${out} (${img.byteLength} bytes)`);
+        return;
+    }
+    if (cmd === "serve") {
+        const port = num(values.port) ?? Number(process.env.PORT ?? 8787);
+        const host = values.host ?? "127.0.0.1";
+        const origins = list(values.cors);
+        createApp(router, undefined, origins).listen(port, host, () => {
+            console.log(`sandboxrouter listening on http://${host}:${port}`);
+            if (origins?.length)
+                console.log(`browser access allowed from: ${origins.join(", ")}`);
+            if (!process.env.SANDBOXROUTER_TOKEN)
+                console.log("warning: SANDBOXROUTER_TOKEN is not set, so the API is unauthenticated");
+        });
+        return;
+    }
+    console.error(`unknown command: ${cmd}\n\n${HELP}`);
+    process.exitCode = 2;
+}
+main().catch((err) => {
+    console.error(`error: ${err.message}`);
+    process.exitCode = 1;
+});

package/dist/computers.d.ts

@@ -0,0 +1,124 @@
+import { type ProviderId } from "./types.js";
+/**
+ * Computers: machines with a screen that a model drives with clicks and keys (computer use).
+ * Linux and Windows desktops, Android phones. Maritime is the first implementation.
+ */
+export type ComputerOs = "linux" | "windows" | "android";
+export interface ComputerSpec {
+    os?: ComputerOs;
+    /** Your user's id. The same id returns the same computer (files and logins kept). */
+    externalUserId?: string;
+    name?: string;
+    /** Linux only, each side 640 to 1920. */
+    screen?: {
+        width: number;
+        height: number;
+    };
+    /** Android only. */
+    arch?: "x86_64" | "arm64";
+}
+export type ComputerActionName = "screenshot" | "left_click" | "right_click" | "middle_click" | "double_click" | "triple_click" | "mouse_move" | "left_click_drag" | "left_mouse_down" | "left_mouse_up" | "scroll" | "type" | "key" | "hold_key" | "wait" | "zoom" | "cursor_position";
+/** The canonical action (Anthropic computer-use shaped). Coordinates are in the last screenshot's frame. */
+export interface ComputerAction {
+    action: ComputerActionName;
+    coordinate?: [number, number];
+    startCoordinate?: [number, number];
+    /** `type`: text to type. `key` / `hold_key`: an xdotool key name like "Return" or "ctrl+s". */
+    text?: string;
+    modifier?: string;
+    repeat?: number;
+    scrollDirection?: "up" | "down" | "left" | "right";
+    scrollAmount?: number;
+    duration?: number;
+    region?: [number, number, number, number];
+    noScreenshot?: boolean;
+}
+export interface ActionResult {
+    action?: string;
+    ok?: boolean;
+    error?: string;
+    frameId?: number;
+    /** Post-action screenshot, base64. */
+    imageB64?: string;
+    mime?: string;
+    width?: number;
+    height?: number;
+    [key: string]: unknown;
+}
+export interface ComputerInfo {
+    id: string;
+    os: ComputerOs;
+    status: string;
+    screen?: {
+        width: number;
+        height: number;
+        modelWidth?: number;
+    };
+    externalUserId?: string | null;
+}
+export interface ProviderComputer {
+    readonly nativeId: string;
+    info(): Promise<ComputerInfo>;
+    act(action: ComputerAction): Promise<ActionResult>;
+    actBatch(actions: ComputerAction[]): Promise<ActionResult[]>;
+    screenshot(opts?: {
+        format?: "png" | "jpeg";
+        quality?: number;
+    }): Promise<Uint8Array>;
+    exec(command: string, timeoutSeconds?: number): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    /** A link for a person: `watch` is view-only, `control` hands them the desktop (logins, CAPTCHAs). */
+    viewer(mode?: "watch" | "control", opts?: {
+        ttlSeconds?: number;
+        reason?: string;
+    }): Promise<{
+        url: string;
+        expiresAt: string;
+    }>;
+    sleep(): Promise<void>;
+    delete(): Promise<void>;
+}
+export interface ComputerProvider {
+    readonly id: ProviderId;
+    readonly computerOs: ComputerOs[];
+    configured(): boolean;
+    createComputer(spec: ComputerSpec): Promise<ProviderComputer>;
+    connectComputer(nativeId: string): Promise<ProviderComputer>;
+}
+export declare class RoutedComputer {
+    readonly provider: ProviderId;
+    private c;
+    readonly id: string;
+    constructor(provider: ProviderId, c: ProviderComputer);
+    get nativeId(): string;
+    info(): Promise<ComputerInfo>;
+    act(action: ComputerAction): Promise<ActionResult>;
+    actBatch(actions: ComputerAction[]): Promise<ActionResult[]>;
+    screenshot(opts?: {
+        format?: "png" | "jpeg";
+        quality?: number;
+    }): Promise<Uint8Array<ArrayBufferLike>>;
+    exec(command: string, timeoutSeconds?: number): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    readFile(path: string): Promise<Uint8Array<ArrayBufferLike>>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    viewer(mode?: "watch" | "control", opts?: {
+        ttlSeconds?: number;
+        reason?: string;
+    }): Promise<{
+        url: string;
+        expiresAt: string;
+    }>;
+    sleep(): Promise<void>;
+    delete(): Promise<void>;
+}
+/** Pick a computer provider that offers this OS and has credentials, in the given order. */
+export declare function createComputer(providers: ComputerProvider[], spec?: ComputerSpec, prefer?: ProviderId[]): Promise<RoutedComputer>;

package/dist/computers.js

@@ -0,0 +1,66 @@
+import { RouterError } from "./types.js";
+export class RoutedComputer {
+    provider;
+    c;
+    id;
+    constructor(provider, c) {
+        this.provider = provider;
+        this.c = c;
+        this.id = `${provider}:${c.nativeId}`;
+    }
+    get nativeId() {
+        return this.c.nativeId;
+    }
+    info() {
+        return this.c.info();
+    }
+    act(action) {
+        return this.c.act(action);
+    }
+    actBatch(actions) {
+        if (actions.length > 50)
+            throw new RouterError("at most 50 actions per batch");
+        return this.c.actBatch(actions);
+    }
+    screenshot(opts) {
+        return this.c.screenshot(opts);
+    }
+    exec(command, timeoutSeconds) {
+        return this.c.exec(command, timeoutSeconds);
+    }
+    readFile(path) {
+        return this.c.readFile(path);
+    }
+    writeFile(path, content) {
+        return this.c.writeFile(path, content);
+    }
+    viewer(mode, opts) {
+        return this.c.viewer(mode, opts);
+    }
+    sleep() {
+        return this.c.sleep();
+    }
+    delete() {
+        return this.c.delete();
+    }
+}
+/** Pick a computer provider that offers this OS and has credentials, in the given order. */
+export async function createComputer(providers, spec = {}, prefer) {
+    const os = spec.os ?? "linux";
+    const ordered = prefer ? prefer.map((id) => providers.find((p) => p.id === id)).filter((p) => !!p) : providers;
+    const usable = ordered.filter((p) => p.computerOs.includes(os) && p.configured());
+    if (usable.length === 0) {
+        const offering = providers.filter((p) => p.computerOs.includes(os)).map((p) => p.id);
+        throw new RouterError(offering.length ? `no configured provider for a ${os} computer (offered by: ${offering.join(", ")})` : `no provider offers a ${os} computer`);
+    }
+    const errors = [];
+    for (const p of usable) {
+        try {
+            return new RoutedComputer(p.id, await p.createComputer({ ...spec, os }));
+        }
+        catch (err) {
+            errors.push(`${p.id}: ${err.message}`);
+        }
+    }
+    throw new RouterError(`all computer providers failed: ${errors.join(" | ")}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { Router, RoutedSandbox, defaultProviders, parseId, type Candidate, type RouterOptions } from "./router.js";
+export { CATALOG, hourlyCost, unfit, info, type ProviderInfo } from "./catalog.js";
+export { createApp } from "./server.js";
+export { RoutedComputer, createComputer, type ActionResult, type ComputerAction, type ComputerActionName, type ComputerInfo, type ComputerOs, type ComputerProvider, type ComputerSpec, type ProviderComputer, } from "./computers.js";
+export { bench, benchMarkdown, type BenchRow } from "./bench.js";
+export { aggregate, loadReports, makeReport, renderLeaderboard, type BenchReport, type LeaderRow } from "./leaderboard.js";
+export { MaritimeProvider } from "./providers/maritime.js";
+export { E2BProvider } from "./providers/e2b.js";
+export { DaytonaProvider } from "./providers/daytona.js";
+export { ModalProvider } from "./providers/modal.js";
+export { VercelProvider } from "./providers/vercel.js";
+export { MorphProvider } from "./providers/morph.js";
+export { SpritesProvider } from "./providers/sprites.js";
+export { BlaxelProvider } from "./providers/blaxel.js";
+export { TensorlakeProvider } from "./providers/tensorlake.js";
+export { RunloopProvider } from "./providers/runloop.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+export { Router, RoutedSandbox, defaultProviders, parseId } from "./router.js";
+export { CATALOG, hourlyCost, unfit, info } from "./catalog.js";
+export { createApp } from "./server.js";
+export { RoutedComputer, createComputer, } from "./computers.js";
+export { bench, benchMarkdown } from "./bench.js";
+export { aggregate, loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
+export { MaritimeProvider } from "./providers/maritime.js";
+export { E2BProvider } from "./providers/e2b.js";
+export { DaytonaProvider } from "./providers/daytona.js";
+export { ModalProvider } from "./providers/modal.js";
+export { VercelProvider } from "./providers/vercel.js";
+export { MorphProvider } from "./providers/morph.js";
+export { SpritesProvider } from "./providers/sprites.js";
+export { BlaxelProvider } from "./providers/blaxel.js";
+export { TensorlakeProvider } from "./providers/tensorlake.js";
+export { RunloopProvider } from "./providers/runloop.js";
+export * from "./types.js";

package/dist/leaderboard.d.ts

@@ -0,0 +1,39 @@
+import type { BenchRow } from "./bench.js";
+import type { ProviderId, SandboxSpec } from "./types.js";
+/**
+ * A shareable bench result. People submit these as PRs to results/, and `sandboxrouter
+ * leaderboard` renders every submission into one static page. No server, nothing to trust but
+ * the files in the repo.
+ */
+export interface BenchReport {
+    tool: "sandboxrouter";
+    version: string;
+    date: string;
+    /** Free text from the submitter, e.g. "us-east-1 c7g.large" or "Berlin, home fiber". */
+    label?: string;
+    runs: number;
+    spec: SandboxSpec;
+    node: string;
+    platform: string;
+    rows: BenchRow[];
+}
+export declare function makeReport(rows: BenchRow[], opts: {
+    version: string;
+    runs: number;
+    spec: SandboxSpec;
+    label?: string;
+}): BenchReport;
+export declare function loadReports(dir: string): BenchReport[];
+export interface LeaderRow {
+    provider: ProviderId;
+    name: string;
+    submissions: number;
+    medianCreateMs?: number;
+    medianExecMs?: number;
+    successRate: number;
+    hourlyUsd: number;
+}
+/** Median of each submission's medians, so one heavy submitter can't skew a provider. */
+export declare function aggregate(reports: BenchReport[]): LeaderRow[];
+/** One self-contained HTML page: a sorted table with an inline bar per measure, each on its own scale. */
+export declare function renderLeaderboard(reports: BenchReport[]): string;

package/dist/leaderboard.js

@@ -0,0 +1,184 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CATALOG, hourlyCost } from "./catalog.js";
+import { median } from "./bench-store.js";
+export function makeReport(rows, opts) {
+    return {
+        tool: "sandboxrouter",
+        version: opts.version,
+        date: new Date().toISOString(),
+        label: opts.label,
+        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),
+    };
+}
+export function loadReports(dir) {
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files.sort()) {
+        try {
+            const r = JSON.parse(readFileSync(join(dir, f), "utf8"));
+            if (r?.tool === "sandboxrouter" && Array.isArray(r.rows))
+                out.push(r);
+        }
+        catch {
+            /* skip unreadable files */
+        }
+    }
+    return out;
+}
+const KNOWN = new Set(CATALOG.map((c) => c.id));
+/** Median of each submission's medians, so one heavy submitter can't skew a provider. */
+export function aggregate(reports) {
+    const by = new Map();
+    for (const rep of reports)
+        for (const r of rep.rows)
+            if (KNOWN.has(r.provider))
+                by.set(r.provider, [...(by.get(r.provider) ?? []), r]);
+    const rows = [...by.entries()].map(([id, rs]) => {
+        const runs = rs.reduce((n, r) => n + r.runs, 0);
+        const ok = rs.reduce((n, r) => n + (r.runs - r.failures), 0);
+        return {
+            provider: id,
+            name: CATALOG.find((c) => c.id === id).name,
+            submissions: rs.length,
+            medianCreateMs: median(rs.map((r) => r.medianCreateMs).filter((n) => typeof n === "number")),
+            medianExecMs: median(rs.map((r) => r.medianExecMs).filter((n) => typeof n === "number")),
+            successRate: runs ? ok / runs : 0,
+            hourlyUsd: hourlyCost(id),
+        };
+    });
+    return rows.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity));
+}
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+function bar(value, max, text, tip) {
+    if (value === undefined)
+        return `<td class="num muted">n/a</td>`;
+    const pct = max > 0 ? Math.max(1.5, (value / max) * 100) : 0;
+    return `<td class="barcell" tabindex="0" data-tip="${esc(tip)}" aria-label="${esc(tip)}">
+    <div class="track"><div class="bar" style="width:${pct.toFixed(1)}%"></div></div><span class="val">${esc(text)}</span></td>`;
+}
+/** One self-contained HTML page: a sorted table with an inline bar per measure, each on its own scale. */
+export function renderLeaderboard(reports) {
+    const rows = aggregate(reports);
+    const maxCreate = Math.max(0, ...rows.map((r) => r.medianCreateMs ?? 0));
+    const maxPrice = Math.max(0, ...rows.map((r) => r.hourlyUsd));
+    const dates = reports.map((r) => r.date).sort();
+    const span = dates.length ? `${dates[0].slice(0, 10)} to ${dates.at(-1).slice(0, 10)}` : "no submissions yet";
+    const body = rows
+        .map((r, i) => `<tr>
+  <td class="num rank">${i + 1}</td>
+  <th scope="row">${esc(r.name)}</th>
+  ${bar(r.medianCreateMs, maxCreate, r.medianCreateMs === undefined ? "" : `${r.medianCreateMs.toLocaleString("en-US")} ms`, `${r.name}: median cold start ${r.medianCreateMs} ms across ${r.submissions} submission${r.submissions === 1 ? "" : "s"}`)}
+  <td class="num">${r.medianExecMs === undefined ? "n/a" : `${r.medianExecMs} ms`}</td>
+  ${bar(r.hourlyUsd, maxPrice, `$${r.hourlyUsd.toFixed(3)}`, `${r.name}: $${r.hourlyUsd.toFixed(4)} per hour at list price, 2 vCPU / 4 GB`)}
+  <td class="num">${(r.successRate * 100).toFixed(0)}%</td>
+  <td class="num muted">${r.submissions}</td>
+</tr>`)
+        .join("\n");
+    const subs = reports
+        .map((r) => `<li>${esc(r.date.slice(0, 10))} · ${esc(r.label ?? "unlabeled")} · ${esc(r.platform)} · ${r.runs} runs · ${r.rows.length} providers</li>`)
+        .join("\n");
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>sandboxrouter leaderboard</title>
+<style>
+.viz-root {
+  color-scheme: light;
+  --page: #f9f9f7; --surface-1: #fcfcfb; --text-primary: #0b0b0b; --text-secondary: #52514e;
+  --text-muted: #898781; --grid: #e1e0d9; --baseline: #c3c2b7; --border: rgba(11,11,11,0.10);
+  --series-1: #2a78d6;
+}
+@media (prefers-color-scheme: dark) {
+  :root:where(:not([data-theme="light"])) .viz-root {
+    color-scheme: dark;
+    --page: #0d0d0d; --surface-1: #1a1a19; --text-primary: #f0efec; --text-secondary: #c3c2b7;
+    --text-muted: #898781; --grid: #2c2c2a; --baseline: #383835; --border: rgba(255,255,255,0.10);
+    --series-1: #3987e5;
+  }
+}
+:root[data-theme="dark"] .viz-root {
+  color-scheme: dark;
+  --page: #0d0d0d; --surface-1: #1a1a19; --text-primary: #f0efec; --text-secondary: #c3c2b7;
+  --text-muted: #898781; --grid: #2c2c2a; --baseline: #383835; --border: rgba(255,255,255,0.10);
+  --series-1: #3987e5;
+}
+* { box-sizing: border-box; }
+body { margin: 0; }
+.viz-root { background: var(--page); color: var(--text-primary); min-height: 100vh;
+  font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; padding: 48px 24px; }
+main { max-width: 1040px; margin: 0 auto; }
+h1 { font-size: 28px; margin: 0 0 4px; letter-spacing: -0.01em; }
+.sub { color: var(--text-secondary); margin: 0 0 24px; }
+.card { background: var(--surface-1); border: 1px solid var(--border); border-radius: 12px; padding: 8px 16px; overflow-x: auto; }
+table { width: 100%; border-collapse: collapse; }
+caption { text-align: left; color: var(--text-muted); font-size: 13px; padding: 12px 0 4px; caption-side: bottom; }
+th, td { padding: 10px 8px; border-bottom: 1px solid var(--grid); text-align: left; white-space: nowrap; }
+thead th { color: var(--text-muted); font-weight: 500; font-size: 13px; border-bottom-color: var(--baseline); }
+tbody tr:last-child > * { border-bottom: 0; }
+tbody th { font-weight: 600; }
+.num { font-variant-numeric: tabular-nums; }
+.rank, .muted { color: var(--text-muted); }
+.barcell { min-width: 220px; position: relative; outline: none; }
+.barcell { display: table-cell; }
+.track { display: inline-block; vertical-align: middle; width: 140px; height: 12px; border-left: 1px solid var(--baseline); }
+.bar { height: 12px; background: var(--series-1); border-radius: 0 4px 4px 0; }
+.val { display: inline-block; vertical-align: middle; margin-left: 8px; color: var(--text-primary); font-variant-numeric: tabular-nums; }
+.barcell:hover .bar, .barcell:focus .bar { filter: brightness(1.12); }
+#tip { position: fixed; pointer-events: none; background: var(--surface-1); color: var(--text-primary);
+  border: 1px solid var(--border); border-radius: 8px; padding: 6px 10px; font-size: 13px;
+  box-shadow: 0 4px 16px rgba(0,0,0,0.12); opacity: 0; transition: opacity 80ms; max-width: 320px; white-space: normal; }
+.notes { color: var(--text-secondary); font-size: 14px; margin-top: 24px; }
+.notes ul { padding-left: 18px; color: var(--text-muted); }
+a { color: inherit; }
+</style>
+</head>
+<body class="viz-root">
+<main>
+  <h1>Sandbox cold starts</h1>
+  <p class="sub">Time from <code>create()</code> to a usable sandbox, measured by <a href="https://github.com/gigialc/sandboxrouter">sandboxrouter bench</a>. ${reports.length} submission${reports.length === 1 ? "" : "s"}, ${esc(span)}.</p>
+  <div class="card">
+    <table>
+      <thead><tr>
+        <th>#</th><th>Provider</th><th>Cold start (median)</th><th>Exec round trip</th>
+        <th>List price, 2 vCPU / 4 GB</th><th>Success</th><th>Submissions</th>
+      </tr></thead>
+      <tbody>
+${body || `<tr><td colspan="7" class="muted">No results yet. Run <code>npx @sandboxrouter/sdk bench --share</code> and open a PR.</td></tr>`}
+      </tbody>
+    </table>
+  </div>
+  <div class="notes">
+    <p>Sorted by cold start. Each bar column has its own scale. Cold start and exec are the median of each submission's medians, so one submitter can't dominate a provider. Latency includes the network between the submitter and each provider. Prices are list prices from each provider's pricing page (sources in <code>src/catalog.ts</code>); some bill active CPU only, so idle work costs less.</p>
+    <p>Submissions:</p>
+    <ul>${subs}</ul>
+  </div>
+</main>
+<div id="tip" role="tooltip"></div>
+<script>
+  const tip = document.getElementById("tip");
+  const show = (el, x, y) => { tip.textContent = el.dataset.tip; tip.style.left = (x + 14) + "px"; tip.style.top = (y + 14) + "px"; tip.style.opacity = 1; };
+  for (const el of document.querySelectorAll("[data-tip]")) {
+    el.addEventListener("mousemove", (e) => show(el, e.clientX, e.clientY));
+    el.addEventListener("mouseleave", () => (tip.style.opacity = 0));
+    el.addEventListener("focus", () => { const r = el.getBoundingClientRect(); show(el, r.left, r.bottom - 8); });
+    el.addEventListener("blur", () => (tip.style.opacity = 0));
+  }
+</script>
+</body>
+</html>
+`;
+}

package/dist/providers/blaxel.d.ts

@@ -0,0 +1,21 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Blaxel sandboxes via `@blaxel/core`. Auth: BL_API_KEY + BL_WORKSPACE (or `bl login`).
+ * Region: BL_REGION, else us-pdx-1. Blaxel sizes by memory only and gives 1 vCPU per 2 GB,
+ * so memory is max(memoryGb, 2 × vcpu) GB. Idle sandboxes drop to standby on their own and
+ * wake on the next call; pause() archives explicitly.
+ */
+export declare class BlaxelProvider implements Provider {
+    private apiKey;
+    private workspace;
+    private region;
+    readonly id: "blaxel";
+    private ready?;
+    constructor(apiKey?: string | undefined, workspace?: string | undefined, region?: string);
+    configured(): boolean;
+    /** Load the SDK once and point its (global) settings at our credentials. */
+    private sdk;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach by sandbox name; an archived (paused) sandbox is unarchived first. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}