@sandboxrouter/sdk 0.5.0 → 0.7.0

package/README.md

@@ -44,8 +44,8 @@ List price while running, 2 vCPU / 4 GB, cheapest first; waitlisted sign-ups fol
 |---|---|---|---|---|
 | [Agent37](https://sandboxrouter.vercel.app/providers/agent37) | $0.007 | none | passed (2026-11-11) | [pricing](https://www.agent37.com/docs/agents-api/billing) |
 | [Boat](https://sandboxrouter.vercel.app/providers/boat) | $0.018 | $20/mo (credited) | not run yet | [pricing](https://docs.boat.dev/pricing.md) |
-| [Maritime](https://sandboxrouter.vercel.app/providers/maritime) | $0.022 | $20/mo (credited) | passed (2026-11-11) | [pricing](https://maritime.sh/pricing) |
-| [Sailboxes (Sail Research)](https://sandboxrouter.vercel.app/providers/sail) | up to $0.062 | none | passed (2026-11-11) | [pricing](https://docs.sailresearch.com/sailboxes-pricing.md) |
+| [Maritime](https://sandboxrouter.vercel.app/providers/maritime) | $0.022 | $20/mo (credited) | passed (2026-11-13) | [pricing](https://maritime.sh/pricing) |
+| [Sailboxes (Sail Research)](https://sandboxrouter.vercel.app/providers/sail) | up to $0.062 | none | passed (2026-11-13) | [pricing](https://docs.sailresearch.com/sailboxes-pricing.md) |
 | [Northflank](https://sandboxrouter.vercel.app/providers/northflank) | $0.067 | none | not run yet | [pricing](https://northflank.com/pricing) |
 | [Morph Cloud](https://sandboxrouter.vercel.app/providers/morph) | $0.100 | none | not run yet | [pricing](https://cloud.morph.so/web/pricing) |
 | [exe.dev](https://sandboxrouter.vercel.app/providers/exedev) | $0.105 | $15/mo | not run yet | [pricing](https://exe.dev/docs/standalone-vms.md) |
@@ -54,15 +54,15 @@ List price while running, 2 vCPU / 4 GB, cheapest first; waitlisted sign-ups fol
 | [Beam](https://sandboxrouter.vercel.app/providers/beam) | $0.140 | $20/mo (credited) | not run yet | [pricing](https://www.beam.cloud/pricing) |
 | [CodeSandbox SDK (Together)](https://sandboxrouter.vercel.app/providers/codesandbox) | $0.149 | none | not run yet | [pricing](https://docs.together.ai/docs/together-code-sandbox-legacy) |
 | [Fly.io Sprites](https://sandboxrouter.vercel.app/providers/sprites) | up to $0.164 | none | passed (2026-11-11) | [pricing](https://fly.io/sprites) |
-| [Blaxel](https://sandboxrouter.vercel.app/providers/blaxel) | $0.166 | none | passed (2026-11-11) | [pricing](https://blaxel.ai/pricing) |
+| [Blaxel](https://sandboxrouter.vercel.app/providers/blaxel) | $0.166 | none | passed (2026-11-13) | [pricing](https://blaxel.ai/pricing) |
 | [HOPX](https://sandboxrouter.vercel.app/providers/hopx) | $0.166 | none | not run yet | [pricing](https://hopx.ai/pricing) |
 | [Superserve](https://sandboxrouter.vercel.app/providers/superserve) | $0.166 | maybe $20/mo (credited) | passed (2026-11-11) | [pricing](https://superserve.ai/pricing) |
 | [Tensorlake](https://sandboxrouter.vercel.app/providers/tensorlake) | up to $0.200 | none | not run yet | [pricing](https://www.tensorlake.ai/pricing) |
 | [Upstash Box](https://sandboxrouter.vercel.app/providers/upstash) | up to $0.200 | none | not run yet | [pricing](https://upstash.com/pricing/box) |
 | [Cloudflare Sandbox](https://sandboxrouter.vercel.app/providers/cloudflare) | up to $0.216 | $5/mo | passed (2026-11-11) | [pricing](https://developers.cloudflare.com/containers/platform/pricing/) |
-| [Amazon Bedrock AgentCore Code Interpreter](https://sandboxrouter.vercel.app/providers/agentcore) | up to $0.217 | none | passed (2026-11-11) | [pricing](https://aws.amazon.com/bedrock/agentcore/pricing/) |
+| [Amazon Bedrock AgentCore Code Interpreter](https://sandboxrouter.vercel.app/providers/agentcore) | up to $0.217 | none | passed (2026-11-13) | [pricing](https://aws.amazon.com/bedrock/agentcore/pricing/) |
 | [Modal](https://sandboxrouter.vercel.app/providers/modal) | up to $0.238 | none | passed (2026-11-11) | [pricing](https://modal.com/pricing) |
-| [AWS Lambda MicroVMs](https://sandboxrouter.vercel.app/providers/lambda) | $0.252 | none | passed (2026-11-11) | [pricing](https://aws.amazon.com/lambda/pricing/) |
+| [AWS Lambda MicroVMs](https://sandboxrouter.vercel.app/providers/lambda) | $0.252 | none | passed (2026-11-13) | [pricing](https://aws.amazon.com/lambda/pricing/) |
 | [Deno Sandbox](https://sandboxrouter.vercel.app/providers/deno) | up to $0.300 | $20/mo | not run yet | [pricing](https://deno.com/sandbox) |
 | [Runloop](https://sandboxrouter.vercel.app/providers/runloop) | $0.317 | none | not run yet | [pricing](https://www.runloop.ai/pricing) |
 | [Vercel Sandbox](https://sandboxrouter.vercel.app/providers/vercel) | up to $0.341 | none | passed (2026-11-11) | [pricing](https://vercel.com/docs/vercel-sandbox/pricing) |
@@ -70,12 +70,12 @@ List price while running, 2 vCPU / 4 GB, cheapest first; waitlisted sign-ups fol
 | [Koyeb Sandboxes (not taking new accounts)](https://sandboxrouter.vercel.app/providers/koyeb) | $0.058 | $29/mo | not run yet | [pricing](https://www.koyeb.com/docs/reference/instances) |
 | [Dedalus Machines (sign-up waitlisted)](https://sandboxrouter.vercel.app/providers/dedalus) | $0.149 | none | not run yet | [pricing](https://docs.dedaluslabs.ai/dcs/dm/pricing) |
 | [LangSmith Sandboxes (sign-up waitlisted)](https://sandboxrouter.vercel.app/providers/langsmith) | $0.189 | none | not run yet | [pricing](https://www.langchain.com/pricing) |
-| [OpenScale Sandboxes](https://sandboxrouter.vercel.app/providers/openscale) | skipped (default image is 2 vCPU / 1 GB; a bigger size needs image.openscale) | none | passed (2026-11-11) | [pricing](https://openscale.so/sandboxes) |
+| [OpenScale Sandboxes](https://sandboxrouter.vercel.app/providers/openscale) | skipped (default image is 2 vCPU / 1 GB; a bigger size needs image.openscale) | none | passed (2026-11-13) | [pricing](https://openscale.so/sandboxes) |
 | [Azure Container Apps dynamic sessions](https://sandboxrouter.vercel.app/providers/azure) | skipped (max 1 vCPU) | none | not run yet | [pricing](https://learn.microsoft.com/en-us/azure/container-apps/billing#dynamic-sessions) |
-| [Daytona](https://sandboxrouter.vercel.app/providers/daytona) | skipped (default image is 1 vCPU / 1 GB; a bigger size needs image.daytona) | none | passed (2026-11-11) | [pricing](https://www.daytona.io/pricing) |
+| [Daytona](https://sandboxrouter.vercel.app/providers/daytona) | skipped (default image is 1 vCPU / 1 GB; a bigger size needs image.daytona) | none | passed (2026-11-13) | [pricing](https://www.daytona.io/pricing) |
 | [Alibaba Cloud Agent Sandbox](https://sandboxrouter.vercel.app/providers/alibaba) | skipped (max 2 GB memory) | none | not run yet | [pricing](https://www.alibabacloud.com/help/en/agent-sandbox/product-overview/billing-overview) |
-| [E2B](https://sandboxrouter.vercel.app/providers/e2b) | skipped (default image is 2 vCPU / 0.5 GB; a bigger size needs image.e2b) | none | passed (2026-11-11) | [pricing](https://e2b.dev/pricing) |
-| [Docker (local)](https://sandboxrouter.vercel.app/providers/docker) | free | none | passed (2026-11-09) | [pricing](https://docs.docker.com/engine/) |
+| [E2B](https://sandboxrouter.vercel.app/providers/e2b) | skipped (default image is 2 vCPU / 0.5 GB; a bigger size needs image.e2b) | none | passed (2026-11-13) | [pricing](https://e2b.dev/pricing) |
+| [Docker (local)](https://sandboxrouter.vercel.app/providers/docker) | free | none | passed (2026-11-13) | [pricing](https://docs.docker.com/engine/) |
 
 Checked 2026-11-04 to 2026-11-06.
 

package/dist/cli.js

@@ -18,10 +18,12 @@ 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]] [--by GITHUB_USER]
+  sandboxrouter check     --provider ID[,ID] | --all [--json] [--save [dir]] [--retry] [--out FILE] [--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
+                          --save writes results/conformance/<id>.json for the compatibility table;
+                          --retry runs a failed provider once more and keeps that result;
+                          --out writes every report as JSON (with the first try's failure, if retried)
   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
@@ -73,6 +75,7 @@ const { values, positionals } = parseArgs({
         label: { type: "string" },
         all: { type: "boolean" },
         save: { type: "boolean" },
+        retry: { type: "boolean" },
         "older-than": { type: "string" },
         "dry-run": { type: "boolean" },
         minutes: { type: "string" },
@@ -208,16 +211,23 @@ async function main() {
         const saveDir = values.save ? (rest[0] ?? "results/conformance") : undefined;
         const mark = { pass: "ok  ", fail: "FAIL", skip: "skip", info: "note" };
         const reports = [];
+        const run = (p) => checkProvider(router, p, {
+            spec,
+            onStep: (r) => {
+                if (!values.json)
+                    console.log(`  ${mark[r.status]}  ${r.step.padEnd(32)} ${String(r.ms).padStart(6)} ms  ${r.detail ?? ""}`);
+            },
+        });
         for (const p of ids) {
             if (!values.json)
                 console.log(`\n${p}`);
-            const report = await checkProvider(router, p, {
-                spec,
-                onStep: (r) => {
-                    if (!values.json)
-                        console.log(`  ${mark[r.status]}  ${r.step.padEnd(32)} ${String(r.ms).padStart(6)} ms  ${r.detail ?? ""}`);
-                },
-            });
+            let report = await run(p);
+            if (values.retry && !report.ok && !report.inconclusive) {
+                const failed = report.results.find((r) => r.status === "fail");
+                if (!values.json)
+                    console.log(`  failed; trying ${p} once more`);
+                report = { ...(await run(p)), firstTry: failed ? `${failed.step}: ${failed.detail ?? "failed"}` : "failed" };
+            }
             reports.push(report);
             if (report.inconclusive) {
                 if (!values.json)
@@ -226,10 +236,13 @@ async function main() {
             }
             if (saveDir) {
                 mkdirSync(saveDir, { recursive: true });
-                const saved = publishableCheck({ tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...(by ? { by } : {}), ...report });
+                const { firstTry: _, ...result } = report;
+                const saved = publishableCheck({ tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...(by ? { by } : {}), ...result });
                 writeFileSync(`${saveDir}/${p}.json`, JSON.stringify(saved, null, 2) + "\n");
             }
         }
+        if (values.out)
+            writeFileSync(values.out, JSON.stringify(reports, null, 2) + "\n");
         if (values.json)
             console.log(JSON.stringify(reports, null, 2));
         else {

package/dist/client.d.ts

@@ -19,7 +19,7 @@ export declare class Client {
         fetch?: typeof fetch;
     });
     /** @internal */
-    request(method: string, path: string, body?: unknown, accept?: string): Promise<Response>;
+    request(method: string, path: string, body?: unknown, accept?: string, headers?: Record<string, string>): Promise<Response>;
     private json;
     /** Providers this server can route to, with prices at the default size. */
     providers(): Promise<{
@@ -31,8 +31,14 @@ export declare class Client {
     }[]>;
     /** Dry run: which providers would be tried, in order, each with its price, size and any reason it's skipped. */
     route(spec?: SandboxSpec, route?: RouteOptions): Promise<Candidate[]>;
-    /** Start a sandbox on the first provider that works, as the server routes it. */
-    create(spec?: SandboxSpec, route?: RouteOptions): Promise<RemoteSandbox>;
+    /**
+     * Start a sandbox on the first provider that works, as the server routes it. With `idempotencyKey`,
+     * sending the same create again (say, after a timeout) returns the same sandbox instead of starting
+     * a second one; use a new key for each sandbox you mean to start.
+     */
+    create(spec?: SandboxSpec, route?: RouteOptions, opts?: {
+        idempotencyKey?: string;
+    }): Promise<RemoteSandbox>;
     /** A handle on a sandbox you created earlier. */
     sandbox(id: string): RemoteSandbox;
 }

package/dist/client.js

@@ -17,7 +17,7 @@ export class Client {
         this.fetch = opts.fetch ?? globalThis.fetch;
     }
     /** @internal */
-    async request(method, path, body, accept = "application/json") {
+    async request(method, path, body, accept = "application/json", headers = {}) {
         const raw = body instanceof Uint8Array;
         const res = await this.fetch(this.baseUrl + path, {
             method,
@@ -25,6 +25,7 @@ export class Client {
                 Accept: accept,
                 ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
                 ...(body === undefined ? {} : { "Content-Type": raw ? "application/octet-stream" : "application/json" }),
+                ...headers,
             },
             body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
         });
@@ -50,10 +51,16 @@ export class Client {
     async route(spec = {}, route = {}) {
         return (await this.json("POST", "/v1/route", { ...spec, ...route })).candidates;
     }
-    /** Start a sandbox on the first provider that works, as the server routes it. */
-    async create(spec = {}, route = {}) {
-        const r = await this.json("POST", "/v1/sandboxes", { ...spec, ...route });
-        return new RemoteSandbox(this, r.id, r.provider, r);
+    /**
+     * Start a sandbox on the first provider that works, as the server routes it. With `idempotencyKey`,
+     * sending the same create again (say, after a timeout) returns the same sandbox instead of starting
+     * a second one; use a new key for each sandbox you mean to start.
+     */
+    async create(spec = {}, route = {}, opts = {}) {
+        const headers = opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : {};
+        const res = await this.request("POST", "/v1/sandboxes", { ...spec, ...route }, "application/json", headers);
+        const r = (await res.json());
+        return new RemoteSandbox(this, r.id, r.provider, { ...r, replayed: res.headers.get("idempotent-replayed") === "true" });
     }
     /** A handle on a sandbox you created earlier. */
     sandbox(id) {

package/dist/computers.d.ts

@@ -1,3 +1,5 @@
+import type { Ledger } from "./ledger.js";
+import { type Attempt } from "./types.js";
 /**
  * Computers: machines with a screen that a model drives with clicks and keys (computer use).
  * Linux and Windows desktops, Android phones. Routed like sandboxes: cheapest published price for
@@ -99,8 +101,17 @@ export interface ComputerProvider {
 export declare class RoutedComputer {
     readonly provider: ComputerProviderId;
     private c;
+    /** Every create attempt, including failed fallbacks (empty for a handle from getComputer). */
+    readonly attempts: Attempt[];
+    /** List price per hour for this OS, where the provider publishes one. */
+    readonly estimatedHourlyUsd?: number | undefined;
+    private ledger?;
     readonly id: string;
-    constructor(provider: ComputerProviderId, c: ProviderComputer);
+    constructor(provider: ComputerProviderId, c: ProviderComputer, 
+    /** Every create attempt, including failed fallbacks (empty for a handle from getComputer). */
+    attempts?: Attempt[], 
+    /** List price per hour for this OS, where the provider publishes one. */
+    estimatedHourlyUsd?: number | undefined, ledger?: Ledger | undefined);
     get nativeId(): string;
     info(): Promise<ComputerInfo>;
     act(action: ComputerAction): Promise<ActionResult>;
@@ -109,7 +120,10 @@ export declare class RoutedComputer {
         format?: "png" | "jpeg";
         quality?: number;
     }): Promise<Uint8Array<ArrayBufferLike>>;
-    exec(command: string, timeoutSeconds?: number): Promise<{
+    /** Run a shell command (max 30 s). The second argument is `{ timeoutSeconds }`, or the number alone. */
+    exec(command: string, opts?: number | {
+        timeoutSeconds?: number;
+    }): Promise<{
         exitCode: number;
         stdout: string;
         stderr: string;
@@ -129,7 +143,12 @@ export declare class RoutedComputer {
         expiresAt: string | null;
     }>;
     sleep(): Promise<void>;
+    /** Delete the computer and everything on it (its files and logins). */
     delete(): Promise<void>;
+    /** Same as delete(), named like a sandbox's. */
+    kill(): Promise<void>;
+    /** `await using pc = await router.computer(...)` deletes it when the block ends. */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /** Published prices per OS for every computer provider. Same rules as the sandbox catalog. */
 export interface ComputerCatalogEntry {
@@ -159,8 +178,32 @@ export interface ComputerCandidate {
 }
 /** The order a computer create would try, with the reason any provider is skipped. */
 export declare function planComputer(providers: ComputerProvider[], os?: ComputerOs, prefer?: ComputerProviderId[]): ComputerCandidate[];
+/** How a computer create is routed: the same knobs and rules as a sandbox's (see RouteOptions). */
+export interface ComputerRoute {
+    provider?: ComputerProviderId | ComputerProviderId[];
+    /** true (default): move on when a provider is down or can't bill, stop on a setup error. "any": move on always. false: first only. */
+    fallback?: boolean | "any";
+    /** Seconds to wait for one provider before trying the next (default 120). */
+    createTimeoutSeconds?: number;
+    /** Seconds the whole create may take (default 240). */
+    deadlineSeconds?: number;
+}
+/** Split and check a POST /v1/computers body, like splitRequest does for sandboxes. */
+export declare function splitComputerRequest(body: Record<string, unknown>): {
+    spec: ComputerSpec;
+    route: ComputerRoute;
+};
 /**
  * Start a computer on the cheapest provider that offers this OS and has credentials (ties
- * alphabetical), falling back down the list. An explicit `prefer` list keeps its order.
+ * alphabetical), falling back down the list like a sandbox create: on to the next when a provider is
+ * down, slow or can't bill, but stopping on a setup error (a bad key or request). An explicit
+ * provider list keeps its order. Each computer goes in the ledger, so `ls` and `gc --all` find it;
+ * computers have no lifetime of their own, so plain `gc` leaves them.
  */
-export declare function createComputer(providers: ComputerProvider[], spec?: ComputerSpec, prefer?: ComputerProviderId[]): Promise<RoutedComputer>;
+export declare function createComputer(providers: ComputerProvider[], spec?: ComputerSpec, prefer?: ComputerProviderId[], route?: ComputerRoute & {
+    ledger?: Ledger;
+}): Promise<RoutedComputer>;
+/** Seconds to wait for one provider's computer before trying the next. */
+export declare const DEFAULT_COMPUTER_TIMEOUT_S = 120;
+/** Seconds a whole computer create may take. */
+export declare const DEFAULT_COMPUTER_DEADLINE_S = 240;

package/dist/computers.js

@@ -1,11 +1,22 @@
-import { RouterError } from "./types.js";
+import { ProviderError, RouterError, SetupError } from "./types.js";
+import { SETUP_ERRORS, errorStatus, withDeadline } from "./util.js";
 export class RoutedComputer {
     provider;
     c;
+    attempts;
+    estimatedHourlyUsd;
+    ledger;
     id;
-    constructor(provider, c) {
+    constructor(provider, c, 
+    /** Every create attempt, including failed fallbacks (empty for a handle from getComputer). */
+    attempts = [], 
+    /** List price per hour for this OS, where the provider publishes one. */
+    estimatedHourlyUsd, ledger) {
         this.provider = provider;
         this.c = c;
+        this.attempts = attempts;
+        this.estimatedHourlyUsd = estimatedHourlyUsd;
+        this.ledger = ledger;
         this.id = `${provider}:${c.nativeId}`;
     }
     get nativeId() {
@@ -25,8 +36,9 @@ export class RoutedComputer {
     screenshot(opts) {
         return this.c.screenshot(opts);
     }
-    exec(command, timeoutSeconds) {
-        return this.c.exec(command, timeoutSeconds);
+    /** Run a shell command (max 30 s). The second argument is `{ timeoutSeconds }`, or the number alone. */
+    exec(command, opts) {
+        return this.c.exec(command, typeof opts === "number" ? opts : opts?.timeoutSeconds);
     }
     readFile(path) {
         return this.c.readFile(path);
@@ -48,8 +60,18 @@ export class RoutedComputer {
             throw new RouterError(`${this.provider} can't sleep a computer; delete it instead`);
         await this.c.sleep();
     }
-    delete() {
-        return this.c.delete();
+    /** Delete the computer and everything on it (its files and logins). */
+    async delete() {
+        await this.c.delete();
+        this.ledger?.close(this.id, "deleted");
+    }
+    /** Same as delete(), named like a sandbox's. */
+    kill() {
+        return this.delete();
+    }
+    /** `await using pc = await router.computer(...)` deletes it when the block ends. */
+    async [Symbol.asyncDispose]() {
+        await this.delete();
     }
 }
 export const COMPUTER_ENTRIES = [
@@ -166,27 +188,118 @@ export function planComputer(providers, os = "linux", prefer) {
     }
     return list;
 }
+const OS_LIST = ["linux", "windows", "android", "ios"];
+const SPEC_FIELDS = ["os", "externalUserId", "name", "screen", "arch"];
+const ROUTE_FIELDS = ["provider", "fallback", "createTimeoutSeconds", "deadlineSeconds"];
+/** Split and check a POST /v1/computers body, like splitRequest does for sandboxes. */
+export function splitComputerRequest(body) {
+    const bad = (msg) => new RouterError(msg, [], "bad_request");
+    const spec = {};
+    const route = {};
+    const unknown = [];
+    for (const [k, v] of Object.entries(body ?? {})) {
+        if (SPEC_FIELDS.includes(k))
+            spec[k] = v;
+        else if (ROUTE_FIELDS.includes(k))
+            route[k] = v;
+        else
+            unknown.push(k);
+    }
+    if (unknown.length)
+        throw bad(`unknown field${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}: a computer takes ${[...SPEC_FIELDS, ...ROUTE_FIELDS].join(", ")}`);
+    if (spec.os !== undefined && !OS_LIST.includes(spec.os))
+        throw bad(`os must be one of ${OS_LIST.join(", ")}`);
+    for (const k of ["externalUserId", "name"])
+        if (spec[k] !== undefined && typeof spec[k] !== "string")
+            throw bad(`${k} must be a string`);
+    const screen = spec.screen;
+    if (screen !== undefined && !(typeof screen === "object" && [screen.width, screen.height].every((n) => typeof n === "number" && Number.isFinite(n) && n > 0))) {
+        throw bad("screen must be { width, height } in pixels");
+    }
+    if (spec.arch !== undefined && spec.arch !== "x86_64" && spec.arch !== "arm64")
+        throw bad('arch must be "x86_64" or "arm64"');
+    for (const k of ["createTimeoutSeconds", "deadlineSeconds"]) {
+        const v = route[k];
+        if (v !== undefined && !(typeof v === "number" && Number.isFinite(v) && v > 0))
+            throw bad(`${k} must be a positive number`);
+    }
+    if (route.fallback !== undefined && route.fallback !== true && route.fallback !== false && route.fallback !== "any")
+        throw bad('fallback must be true, false or "any"');
+    return { spec: spec, route: route };
+}
 /**
  * Start a computer on the cheapest provider that offers this OS and has credentials (ties
- * alphabetical), falling back down the list. An explicit `prefer` list keeps its order.
+ * alphabetical), falling back down the list like a sandbox create: on to the next when a provider is
+ * down, slow or can't bill, but stopping on a setup error (a bad key or request). An explicit
+ * provider list keeps its order. Each computer goes in the ledger, so `ls` and `gc --all` find it;
+ * computers have no lifetime of their own, so plain `gc` leaves them.
  */
-export async function createComputer(providers, spec = {}, prefer) {
+export async function createComputer(providers, spec = {}, prefer, route = {}) {
     const os = spec.os ?? "linux";
-    const usable = planComputer(providers, os, prefer)
-        .filter((c) => !c.skip)
-        .map((c) => providers.find((p) => p.id === c.provider));
+    const plan = planComputer(providers, os, prefer);
+    const usable = plan.filter((c) => !c.skip);
     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`);
+        throw new RouterError(offering.length ? `no configured provider for a ${os} computer (offered by: ${offering.join(", ")})` : `no provider offers a ${os} computer`, [], "no_provider");
+    }
+    if (prefer && route.fallback === false && plan[0].skip) {
+        throw new RouterError(`${plan[0].provider} can't start this computer: ${plan[0].skip}`, [], "no_provider");
     }
-    const errors = [];
-    for (const p of usable) {
+    const tries = route.fallback === false ? usable.slice(0, 1) : usable;
+    const limitS = route.createTimeoutSeconds ?? DEFAULT_COMPUTER_TIMEOUT_S;
+    const deadline = Date.now() + (route.deadlineSeconds ?? DEFAULT_COMPUTER_DEADLINE_S) * 1000;
+    const attempts = [];
+    for (const c of tries) {
+        const left = deadline - Date.now();
+        if (left <= 0)
+            throw new RouterError(`computer create ran out of time: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "timeout");
+        const p = providers.find((x) => x.id === c.provider);
+        const t0 = Date.now();
+        const pending = p.createComputer({ ...spec, os });
+        const waitS = Math.min(limitS, left / 1000);
+        let timedOut = false;
         try {
-            return new RoutedComputer(p.id, await p.createComputer({ ...spec, os }));
+            const made = await withDeadline(pending, waitS * 1000, () => {
+                timedOut = true;
+                return new ProviderError(p.id, `create timed out after ${Number(waitS.toFixed(1))}s`);
+            });
+            attempts.push({ provider: p.id, ok: true, ms: Date.now() - t0 });
+            const pc = new RoutedComputer(p.id, made, attempts, c.estimatedHourlyUsd, route.ledger);
+            record(route.ledger, pc);
+            return pc;
         }
         catch (err) {
-            errors.push(`${p.id}: ${err.message}`);
+            // One that turns up after we gave up is deleted, so it can't bill unseen (or left in the ledger for gc).
+            if (timedOut) {
+                pending.then((late) => {
+                    const pc = new RoutedComputer(p.id, late, [], c.estimatedHourlyUsd, route.ledger);
+                    record(route.ledger, pc);
+                    return pc.delete();
+                }).catch(() => { });
+            }
+            const status = errorStatus(err);
+            attempts.push({ provider: p.id, ok: false, ms: Date.now() - t0, error: err.message, ...(status ? { status } : {}) });
+            const setup = err instanceof SetupError || (status !== undefined && SETUP_ERRORS.has(status));
+            if (route.fallback !== "any" && setup) {
+                throw new RouterError(`${err.message.replace(/[.\s]+$/, "")}. This looks like a setup problem with ${p.id} (key or request), so the router stopped instead of moving to another provider; pass fallback: "any" to fall back on every error`, attempts, "setup");
+            }
         }
     }
-    throw new RouterError(`all computer providers failed: ${errors.join(" | ")}`);
+    throw new RouterError(`all computer providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "all_failed");
+}
+/** Computers keep running until deleted: the ledger gives them no lifetime, so only `gc --all` takes them. */
+const NO_LIFETIME = "9999-12-31T00:00:00.000Z";
+function record(ledger, pc) {
+    ledger?.open({
+        id: pc.id,
+        provider: pc.provider,
+        kind: "computer",
+        createdAt: new Date().toISOString(),
+        expiresAt: NO_LIFETIME,
+        usdHour: pc.estimatedHourlyUsd ?? 0,
+    });
 }
+/** Seconds to wait for one provider's computer before trying the next. */
+export const DEFAULT_COMPUTER_TIMEOUT_S = 120;
+/** Seconds a whole computer create may take. */
+export const DEFAULT_COMPUTER_DEADLINE_S = 240;

package/dist/gc.js

@@ -34,8 +34,11 @@ export async function gc(router, opts = {}) {
             continue;
         }
         try {
-            const box = await router.get(s.id);
-            await box.kill(); // closes the ledger entry
+            // Both close the ledger entry.
+            if (s.kind === "computer")
+                await (await router.getComputer(s.id)).delete();
+            else
+                await (await router.get(s.id)).kill();
             results.push({ id: s.id, action: "killed" });
         }
         catch (err) {

package/dist/index.d.ts

@@ -7,9 +7,9 @@ export { VERIFIED, FAILING } from "./verified.js";
 export { BILLED_VS_LIST } from "./billing.js";
 export { validate, splitRequest, SPEC_KEYS, ROUTE_KEYS, STRATEGIES } from "./validate.js";
 export { CATALOG, hourlyCost, unfit, info, type ProviderInfo } from "./catalog.js";
-export { createApp, HttpError, ERROR_STATUS, type ServerHooks } from "./server.js";
+export { createApp, HttpError, ERROR_STATUS, ORPHAN_GRACE_MS, type ServerHooks } from "./server.js";
 export { Client, ClientError, RemoteSandbox, type CreateResponse } from "./client.js";
-export { RoutedComputer, createComputer, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, type ComputerCatalogEntry, type ComputerCandidate, type ComputerProviderId, type ActionResult, type ComputerAction, type ComputerActionName, type ComputerInfo, type ComputerOs, type ComputerProvider, type ComputerSpec, type ProviderComputer, } from "./computers.js";
+export { RoutedComputer, createComputer, splitComputerRequest, DEFAULT_COMPUTER_TIMEOUT_S, DEFAULT_COMPUTER_DEADLINE_S, type ComputerRoute, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, type ComputerCatalogEntry, type ComputerCandidate, type ComputerProviderId, 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";

package/dist/index.js

@@ -7,9 +7,9 @@ export { VERIFIED, FAILING } from "./verified.js";
 export { BILLED_VS_LIST } from "./billing.js";
 export { validate, splitRequest, SPEC_KEYS, ROUTE_KEYS, STRATEGIES } from "./validate.js";
 export { CATALOG, hourlyCost, unfit, info } from "./catalog.js";
-export { createApp, HttpError, ERROR_STATUS } from "./server.js";
+export { createApp, HttpError, ERROR_STATUS, ORPHAN_GRACE_MS } from "./server.js";
 export { Client, ClientError, RemoteSandbox } from "./client.js";
-export { RoutedComputer, createComputer, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, } from "./computers.js";
+export { RoutedComputer, createComputer, splitComputerRequest, DEFAULT_COMPUTER_TIMEOUT_S, DEFAULT_COMPUTER_DEADLINE_S, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, } from "./computers.js";
 export { bench, benchMarkdown } from "./bench.js";
 export { aggregate, loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
 export { MaritimeProvider } from "./providers/maritime.js";

package/dist/ledger.d.ts

@@ -3,7 +3,9 @@ import type { ProviderId } from "./types.js";
 export interface LedgerEntry {
     /** Routed id, `provider:nativeId`. */
     id: string;
-    provider: ProviderId;
+    provider: ProviderId | (string & {});
+    /** "computer" for desktops and phones (deleted with getComputer); sandboxes leave it out. */
+    kind?: "computer";
     /** ISO time the create returned. */
     createdAt: string;
     /** ISO time its requested lifetime (spec.timeoutMinutes) runs out. */

package/dist/router.d.ts

@@ -1,4 +1,4 @@
-import { RoutedComputer, type ComputerOs, type ComputerProvider, type ComputerProviderId, type ComputerSpec } from "./computers.js";
+import { type ComputerRoute, RoutedComputer, type ComputerOs, type ComputerProvider, type ComputerProviderId, type ComputerSpec } from "./computers.js";
 import { Ledger } from "./ledger.js";
 import { type Attempt, type ExecOptions, type ExecResult, type Provider, type ProviderId, type ProviderSandbox, type RouteOptions, type SandboxSpec } from "./types.js";
 /** vCPUs and memory a sandbox gets. */
@@ -63,6 +63,18 @@ export interface RouterOptions {
     requireVerified?: boolean;
     /** Billed / list-price ratio per provider, behind `estimatedHourlyUsd`. Default: the ratios in `BILLED_VS_LIST`, from saved cost runs. */
     billedVsList?: Partial<Record<ProviderId, number>>;
+    /**
+     * When a create runs well past a provider's usual start time, try the next provider sooner than
+     * `createTimeoutSeconds`. The wait becomes `factor` x the provider's median start time (or 1.5x the
+     * slowest of its recent starts, if longer), at least `minSeconds`. It applies only when the caller
+     * didn't set `createTimeoutSeconds`, the router has a start time for the provider (3 of its own creates,
+     * or the bench file), and another provider is left to try. Default `{ factor: 5, minSeconds: 10 }`;
+     * `false` always waits the full `createTimeoutSeconds`.
+     */
+    quickFallback?: false | {
+        factor?: number;
+        minSeconds?: number;
+    };
 }
 /** Desktop-only providers. Filled in as adapters are added. */
 export declare function defaultComputerProviders(): ComputerProvider[];
@@ -77,6 +89,7 @@ export declare class Router {
     /** Create times this router measured, most recent last. */
     private readonly live;
     private computerOnly;
+    private readonly quick;
     /** The local record of sandboxes this router created, or undefined when turned off. */
     readonly ledger?: Ledger;
     constructor(opts?: RouterOptions);
@@ -94,6 +107,11 @@ export declare class Router {
     private whyNone;
     /** Start a sandbox on the best available provider, falling back down the list on failure. */
     create(spec?: SandboxSpec, route?: RouteOptions): Promise<RoutedSandbox>;
+    /**
+     * Seconds to wait for this provider's create: the caller's `createTimeoutSeconds`, or (see
+     * `quickFallback`) a few times its usual start time when another provider is left to try.
+     */
+    private waitFor;
     /** Remember a successful create's time, for the speed tie-break and strategy "fastest". */
     private observe;
     private record;
@@ -105,9 +123,8 @@ export declare class Router {
         provider?: ComputerProviderId | ComputerProviderId[];
     }): import("./computers.js").ComputerCandidate[];
     /** Start a desktop or phone on the cheapest provider for its OS (ties alphabetical), with fallback. */
-    computer(spec?: ComputerSpec, opts?: {
-        provider?: ComputerProviderId | ComputerProviderId[];
-    }): Promise<RoutedComputer>;
+    /** Start a desktop or phone, routed like a sandbox (see createComputer). */
+    computer(spec?: ComputerSpec, route?: ComputerRoute): Promise<RoutedComputer>;
     getComputer(id: string): Promise<RoutedComputer>;
     /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
     get(id: string): Promise<RoutedSandbox>;

package/dist/router.js

@@ -2,7 +2,7 @@ import { CATALOG, DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, fixedSize, hourl
 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, errorStatus, timeoutError } from "./util.js";
+import { DEFAULT_EXEC_TIMEOUT_S, SETUP_ERRORS, errorStatus, timeoutError, withDeadline } from "./util.js";
 import { BILLED_VS_LIST } from "./billing.js";
 import { FAILING, VERIFIED } from "./verified.js";
 import { validate } from "./validate.js";
@@ -103,6 +103,7 @@ export class Router {
     /** Create times this router measured, most recent last. */
     live = new Map();
     computerOnly;
+    quick;
     /** The local record of sandboxes this router created, or undefined when turned off. */
     ledger;
     constructor(opts = {}) {
@@ -117,6 +118,7 @@ export class Router {
         this.billed =
             opts.billedVsList ?? Object.fromEntries(Object.entries(BILLED_VS_LIST).map(([id, b]) => [id, b.ratio]));
         this.computerOnly = opts.computers ?? (opts.providers ? [] : defaultComputerProviders());
+        this.quick = opts.quickFallback === false ? false : { factor: 5, minSeconds: 10, ...opts.quickFallback };
     }
     /** Registered and has credentials. False for providers this router doesn't know. */
     isConfigured(id) {
@@ -233,22 +235,23 @@ export class Router {
         }
         const attempts = [];
         const tries = route.fallback === false ? usable.slice(0, 1) : usable;
-        const limitS = route.createTimeoutSeconds ?? DEFAULT_CREATE_TIMEOUT_S;
         const deadline = Date.now() + (route.deadlineSeconds ?? DEFAULT_CREATE_DEADLINE_S) * 1000;
-        for (const c of tries) {
+        for (const [i, c] of tries.entries()) {
             const left = deadline - Date.now();
             if (left <= 0) {
                 throw new RouterError(`create ran out of time (deadlineSeconds) after trying ${attempts.map((a) => a.provider).join(", ")}: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "timeout");
             }
             const t0 = Date.now();
             const pending = this.provider(c.provider).create(spec);
+            const { limitS, typicalMs } = this.waitFor(c.provider, route, i === tries.length - 1);
             const waitS = Math.min(limitS, left / 1000);
             const price = { estimatedHourlyUsd: c.estimatedHourlyUsd, listHourlyUsd: c.listHourlyUsd, size: c.size };
             let timedOut = false;
             try {
                 const box = await withDeadline(pending, waitS * 1000, () => {
                     timedOut = true;
-                    return new ProviderError(c.provider, `create timed out after ${Number(waitS.toFixed(1))}s`);
+                    const usual = typicalMs !== undefined && waitS < (route.createTimeoutSeconds ?? DEFAULT_CREATE_TIMEOUT_S) ? `; it usually starts in ${Number((typicalMs / 1000).toFixed(1))}s` : "";
+                    return new ProviderError(c.provider, `create timed out after ${Number(waitS.toFixed(1))}s${usual}`);
                 });
                 attempts.push({ provider: c.provider, ok: true, ms: Date.now() - t0 });
                 this.observe(c.provider, Date.now() - t0);
@@ -273,6 +276,22 @@ export class Router {
         }
         throw new RouterError(`all providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts, "all_failed");
     }
+    /**
+     * Seconds to wait for this provider's create: the caller's `createTimeoutSeconds`, or (see
+     * `quickFallback`) a few times its usual start time when another provider is left to try.
+     */
+    waitFor(id, route, last) {
+        const full = route.createTimeoutSeconds ?? DEFAULT_CREATE_TIMEOUT_S;
+        if (!this.quick || last || route.createTimeoutSeconds !== undefined)
+            return { limitS: full };
+        const live = this.live.get(id);
+        const samples = live && live.length >= LIVE_MIN_SAMPLES ? live : loadBench(this.benchFile)[id]?.createMs;
+        const typicalMs = median(samples);
+        if (typicalMs === undefined || !samples?.length)
+            return { limitS: full };
+        const s = Math.max(this.quick.factor * typicalMs, 1.5 * Math.max(...samples)) / 1000;
+        return { limitS: Math.min(full, Math.max(this.quick.minSeconds, s)), typicalMs };
+    }
     /** Remember a successful create's time, for the speed tie-break and strategy "fastest". */
     observe(id, ms) {
         const xs = this.live.get(id) ?? [];
@@ -309,19 +328,21 @@ export class Router {
         return planComputer(this.computerProviders(), os, prefer);
     }
     /** Start a desktop or phone on the cheapest provider for its OS (ties alphabetical), with fallback. */
-    computer(spec = {}, opts = {}) {
-        const prefer = opts.provider ? [].concat(opts.provider) : undefined;
-        return createComputer(this.computerProviders(), spec, prefer);
+    /** Start a desktop or phone, routed like a sandbox (see createComputer). */
+    computer(spec = {}, route = {}) {
+        const prefer = route.provider ? [].concat(route.provider) : undefined;
+        return createComputer(this.computerProviders(), spec, prefer, { ...route, ledger: this.ledger });
     }
     async getComputer(id) {
         const i = id.indexOf(":");
         if (i <= 0)
-            throw new RouterError(`bad computer id "${id}": expected provider:id`);
+            throw new RouterError(`bad computer id "${id}": expected provider:id`, [], "bad_request");
         const provider = id.slice(0, i);
         const p = this.computerProviders().find((c) => c.id === provider);
         if (!p)
-            throw new RouterError(`${provider} does not offer computers`);
-        return new RoutedComputer(provider, await p.connectComputer(id.slice(i + 1)));
+            throw new RouterError(`${provider} does not offer computers`, [], "bad_request");
+        const e = this.ledger?.list().find((x) => x.id === id);
+        return new RoutedComputer(provider, await p.connectComputer(id.slice(i + 1)), [], e?.usdHour, this.ledger);
     }
     /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
     async get(id) {
@@ -437,29 +458,8 @@ export function balanced(list) {
 export const DEFAULT_CREATE_TIMEOUT_S = 120;
 /** Seconds a whole create may take over every provider it tries (RouteOptions.deadlineSeconds). */
 export const DEFAULT_CREATE_DEADLINE_S = 240;
-/**
- * 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. */
-async function withDeadline(work, ms, onExpire) {
-    let timer;
-    const expired = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(onExpire()), ms);
-        timer.unref();
-    });
-    try {
-        return await Promise.race([work, expired]);
-    }
-    finally {
-        clearTimeout(timer);
-        work.catch(() => { });
-    }
-}
 /** The size a provider gives for a spec: its fixed default image size, else what was asked for. */
 export function sizeOf(id, spec = {}) {
     return fixedSize(id, spec) ?? { vcpu: spec.vcpu ?? DEFAULT_VCPU, memoryGb: spec.memoryGb ?? DEFAULT_MEMORY_GB };

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import { Router, type RoutedSandbox } from "./router.js";
+import { type ComputerSpec, type RoutedComputer } from "./computers.js";
 import { type RouteOptions, type RouterErrorCode, type SandboxSpec } from "./types.js";
 /**
  * Hooks for running this API for many users (accounts, billing, per-user sandboxes). With none set,
@@ -30,8 +31,21 @@ export interface ServerHooks {
     afterKill?(caller: unknown, id: string, outcome?: {
         error?: Error;
     }): Promise<void>;
-    /** /v1/computers. Default: on for a single-user server, off when `authorize` is set (computers don't go through these hooks). */
+    /**
+     * /v1/computers. Default: on for a single-user server, off when `authorize` is set. When on with
+     * `authorize`, `owns` guards computer ids too, and the computer hooks below run.
+     */
     computers?: boolean;
+    /** Before a computer starts. Throw HttpError to refuse; may edit spec. */
+    beforeCreateComputer?(caller: unknown, spec: ComputerSpec): Promise<void>;
+    /** After a computer started. Return fields to add to the answer. If this throws, the computer is deleted. */
+    afterCreateComputer?(caller: unknown, computer: RoutedComputer): Promise<Record<string, unknown> | void>;
+    /** After DELETE /v1/computers/:id; `error` is set when the provider's delete failed. */
+    afterDeleteComputer?(caller: unknown, id: string, outcome?: {
+        error?: Error;
+    }): Promise<void>;
+    /** Milliseconds a sandbox whose caller hung up (having sent an Idempotency-Key) waits for a retry to collect it. Default 120000. */
+    orphanGraceMs?: number;
     /** false turns off pause. */
     pause?: boolean;
 }
@@ -68,5 +82,7 @@ export declare class HttpError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/** How long a sandbox whose caller hung up (with an Idempotency-Key) waits for a retry to collect it. */
+export declare const ORPHAN_GRACE_MS = 120000;
 /** The HTTP status for each RouterError code (see RouterErrorCode). */
 export declare const ERROR_STATUS: Record<RouterErrorCode, number>;

package/dist/server.js

@@ -1,7 +1,8 @@
-import { timingSafeEqual } from "node:crypto";
+import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { CATALOG } from "./catalog.js";
 import { Router } from "./router.js";
+import { splitComputerRequest } from "./computers.js";
 import { ProviderError, RouterError } from "./types.js";
 import { errorStatus } from "./util.js";
 import { splitRequest } from "./validate.js";
@@ -49,6 +50,63 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
     };
     const live = new Map();
     const computersOn = hooks.computers ?? !hooks.authorize;
+    /**
+     * Idempotency-Key: a create retried with the same key (by the same caller, to the same path) gets the
+     * first create's answer instead of starting another sandbox, for 24 hours. A retry that arrives while
+     * the first is still starting waits for it. The same key with a different body is refused (422).
+     * Failed creates aren't remembered, so retrying one runs it again.
+     */
+    const replays = new Map();
+    const once = async (req, res, body, run) => {
+        const raw = req.headers["idempotency-key"];
+        if (raw === undefined) {
+            const r = await run(false);
+            return json(res, r.status, r.body);
+        }
+        const key = Array.isArray(raw) ? raw[0] : raw;
+        if (!key || key.length > 255)
+            throw new HttpError(400, "Idempotency-Key must be 1 to 255 characters");
+        const now = Date.now();
+        for (const [k, v] of replays)
+            if (now - v.at > IDEMPOTENCY_TTL_MS)
+                replays.delete(k);
+        while (replays.size >= IDEMPOTENCY_MAX)
+            replays.delete(replays.keys().next().value);
+        const scope = sha256(`${req.headers.authorization ?? ""}\n${req.url}\n${key}`);
+        const bodyHash = sha256(JSON.stringify(body ?? {}));
+        const hit = replays.get(scope);
+        if (hit) {
+            if (hit.bodyHash !== bodyHash)
+                throw new HttpError(422, "this Idempotency-Key was already used with a different request");
+            const r = await hit.result;
+            hit.claimed = true;
+            res.setHeader("Idempotent-Replayed", "true");
+            return json(res, r.status, r.body);
+        }
+        const entry = { bodyHash, result: run(true), at: now, claimed: false };
+        replays.set(scope, entry);
+        let r;
+        try {
+            r = await entry.result;
+        }
+        catch (err) {
+            replays.delete(scope);
+            throw err;
+        }
+        // The caller hung up but sent a key, so it means to retry: keep the sandbox for a retry to
+        // collect, and only then give up on it.
+        if (!res.writableEnded && (res.destroyed || !res.writable) && r.discard) {
+            setTimeout(() => {
+                if (!entry.claimed) {
+                    replays.delete(scope);
+                    r.discard().catch(() => { });
+                }
+            }, hooks.orphanGraceMs ?? ORPHAN_GRACE_MS).unref();
+        }
+        else
+            entry.claimed = true;
+        return json(res, r.status, r.body);
+    };
     const cors = (req, res) => {
         const origin = req.headers.origin;
         if (!origin || !(corsOrigins.includes("*") || corsOrigins.includes(origin)))
@@ -108,46 +166,59 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         if (parts[1] === "computers") {
             if (!computersOn)
                 return json(res, 404, { error: "computers aren't available on this server" });
-            return computers(req, res, url, parts);
+            return computers(req, res, url, parts, caller);
         }
         if (parts[1] !== "sandboxes")
             return json(res, 404, { error: "not found" });
         // POST /v1/sandboxes
         if (req.method === "POST" && parts.length === 2) {
-            const { spec, route } = splitRequest(await readJson(req));
-            await hooks.beforeCreate?.(caller, spec, route);
+            const body = await readJson(req);
+            const { spec, route } = splitRequest(body);
             // A caller that gives up (client timeout, closed connection) never learns the id: kill what
-            // starts after that rather than leave it running, and billing, unseen.
+            // starts after that rather than leave it running, and billing, unseen. With an Idempotency-Key
+            // it's kept for a retry instead (see once).
             let hungUp = false;
             res.on("close", () => (hungUp = !res.writableFinished));
-            let sbx;
-            let extra;
-            try {
-                sbx = await router.create(spec, route);
-            }
-            catch (err) {
-                await hooks.createFailed?.(caller);
-                throw err;
-            }
-            try {
-                if (hungUp)
-                    throw new HttpError(499, "the client closed the connection before the sandbox was ready; it was killed");
-                extra = await hooks.afterCreate?.(caller, sbx, spec);
-            }
-            catch (err) {
-                await sbx.kill().catch(() => { });
-                await hooks.createFailed?.(caller);
-                throw err;
-            }
-            live.set(sbx.id, sbx);
-            return json(res, 201, {
-                id: sbx.id,
-                provider: sbx.provider,
-                size: sbx.size,
-                estimatedHourlyUsd: sbx.estimatedHourlyUsd,
-                listHourlyUsd: sbx.listHourlyUsd,
-                attempts: sbx.attempts,
-                ...(extra ?? {}),
+            return once(req, res, body, async (keepIfHungUp) => {
+                await hooks.beforeCreate?.(caller, spec, route);
+                let sbx;
+                let extra;
+                try {
+                    sbx = await router.create(spec, route);
+                }
+                catch (err) {
+                    await hooks.createFailed?.(caller);
+                    throw err;
+                }
+                try {
+                    if (hungUp && !keepIfHungUp)
+                        throw new HttpError(499, "the client closed the connection before the sandbox was ready; it was killed");
+                    extra = await hooks.afterCreate?.(caller, sbx, spec);
+                }
+                catch (err) {
+                    await sbx.kill().catch(() => { });
+                    await hooks.createFailed?.(caller);
+                    throw err;
+                }
+                live.set(sbx.id, sbx);
+                const made = sbx;
+                return {
+                    status: 201,
+                    body: {
+                        id: sbx.id,
+                        provider: sbx.provider,
+                        size: sbx.size,
+                        estimatedHourlyUsd: sbx.estimatedHourlyUsd,
+                        listHourlyUsd: sbx.listHourlyUsd,
+                        attempts: sbx.attempts,
+                        ...(extra ?? {}),
+                    },
+                    discard: async () => {
+                        live.delete(made.id);
+                        await made.kill().catch(() => { });
+                        await hooks.afterKill?.(caller, made.id);
+                    },
+                };
             });
         }
         const id = parts[2] ? decodeURIComponent(parts[2]) : "";
@@ -220,21 +291,47 @@ corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.tri
         }
         return json(res, 404, { error: "not found" });
     };
-    const computers = async (req, res, url, parts) => {
+    const computers = async (req, res, url, parts, caller) => {
         if (req.method === "POST" && parts.length === 2) {
-            const { provider, ...spec } = await readJson(req);
-            const c = await router.computer(spec, { provider });
-            return json(res, 201, { ...(await c.info()), id: c.id, nativeId: c.nativeId, provider: c.provider });
+            const body = await readJson(req);
+            const { spec, route } = splitComputerRequest(body);
+            return once(req, res, body, async () => {
+                await hooks.beforeCreateComputer?.(caller, spec);
+                const c = await router.computer(spec, route);
+                let extra;
+                try {
+                    extra = await hooks.afterCreateComputer?.(caller, c);
+                }
+                catch (err) {
+                    await c.delete().catch(() => { });
+                    throw err;
+                }
+                return {
+                    status: 201,
+                    body: { ...(await c.info()), id: c.id, nativeId: c.nativeId, provider: c.provider, estimatedHourlyUsd: c.estimatedHourlyUsd, attempts: c.attempts, ...(extra ?? {}) },
+                };
+            });
         }
         const id = parts[2] ? decodeURIComponent(parts[2]) : "";
         if (!id)
             return json(res, 404, { error: "not found" });
+        if (hooks.owns && !(await hooks.owns(caller, id)))
+            throw new HttpError(404, "no such computer");
         const c = await router.getComputer(id);
         const sub = parts[3];
         if (req.method === "GET" && !sub)
             return json(res, 200, { ...(await c.info()), id, nativeId: c.nativeId });
         if (req.method === "DELETE" && !sub) {
-            await c.delete();
+            try {
+                await c.delete();
+            }
+            catch (err) {
+                if (errorStatus(err) !== 404) {
+                    await hooks.afterDeleteComputer?.(caller, id, { error: err });
+                    throw err;
+                }
+            }
+            await hooks.afterDeleteComputer?.(caller, id);
             return json(res, 200, { id, deleted: true });
         }
         if (req.method === "POST" && sub === "actions") {
@@ -306,6 +403,12 @@ function describeError(err) {
     const code = err instanceof RouterError ? err.code : undefined;
     return { status, body: { error: err?.message ?? String(err), ...(code ? { code } : {}), ...(err?.attempts?.length ? { attempts: err.attempts } : {}) } };
 }
+/** How long an Idempotency-Key is remembered, and how many at most. */
+const IDEMPOTENCY_TTL_MS = 24 * 3600_000;
+const IDEMPOTENCY_MAX = 10_000;
+/** How long a sandbox whose caller hung up (with an Idempotency-Key) waits for a retry to collect it. */
+export const ORPHAN_GRACE_MS = 120_000;
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
 /** The HTTP status for each RouterError code (see RouterErrorCode). */
 export const ERROR_STATUS = {
     bad_request: 400,

package/dist/types.d.ts

@@ -96,7 +96,8 @@ export interface Provider {
     connect(nativeId: string): Promise<ProviderSandbox>;
 }
 export interface Attempt {
-    provider: ProviderId;
+    /** A sandbox provider, or a computer provider (some sell only computers). */
+    provider: ProviderId | (string & {});
     ok: boolean;
     ms: number;
     error?: string;

package/dist/util.d.ts

@@ -43,3 +43,11 @@ export declare function optionalImport<T>(pkg: string, provider: string): Promis
  * (E2B's AuthenticationError, AWS's CredentialsProviderError). Undefined when there's none.
  */
 export declare function errorStatus(err: unknown, depth?: number): number | undefined;
+/**
+ * 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.
+ */
+export declare const SETUP_ERRORS: Set<number>;
+/** Resolve with `work`, or reject with `onExpire()` after `ms`. A late `work` rejection is swallowed. */
+export declare function withDeadline<T>(work: Promise<T>, ms: number, onExpire: () => Error): Promise<T>;

package/dist/util.js

@@ -111,3 +111,24 @@ export function errorStatus(err, depth = 0) {
         return 429;
     return errorStatus(e.cause, depth + 1);
 }
+/**
+ * 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.
+ */
+export const SETUP_ERRORS = new Set([400, 401, 403, 404, 422]);
+/** Resolve with `work`, or reject with `onExpire()` after `ms`. A late `work` rejection is swallowed. */
+export async function withDeadline(work, ms, onExpire) {
+    let timer;
+    const expired = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(onExpire()), ms);
+        timer.unref();
+    });
+    try {
+        return await Promise.race([work, expired]);
+    }
+    finally {
+        clearTimeout(timer);
+        work.catch(() => { });
+    }
+}

package/dist/verified.js

@@ -1,18 +1,18 @@
 export const VERIFIED = {
     agent37: "2026-11-11",
-    agentcore: "2026-11-11",
-    lambda: "2026-11-11",
-    blaxel: "2026-11-11",
+    agentcore: "2026-11-13",
+    lambda: "2026-11-13",
+    blaxel: "2026-11-13",
     cloudflare: "2026-11-11",
-    daytona: "2026-11-11",
-    e2b: "2026-11-11",
+    daytona: "2026-11-13",
+    e2b: "2026-11-13",
     sprites: "2026-11-11",
     freestyle: "2026-11-11",
-    maritime: "2026-11-11",
+    maritime: "2026-11-13",
     modal: "2026-11-11",
     novita: "2026-11-11",
-    openscale: "2026-11-11",
-    sail: "2026-11-11",
+    openscale: "2026-11-13",
+    sail: "2026-11-13",
     superserve: "2026-11-11",
     vercel: "2026-11-11",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxrouter/sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "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",
@@ -175,7 +175,7 @@
     "@aws-sdk/client-appstream": "^3.1162.0",
     "@aws-sdk/credential-provider-node": "^3.972.93",
     "@blaxel/core": "^0.3.34",
-    "@daytonaio/sdk": "^0.227.3",
+    "@daytonaio/sdk": "^0.230.0",
     "@e2b/desktop": "^2.5.0",
     "@fly/sprites": "^0.2.4",
     "@hopx-ai/sdk": "^0.5.1",