@sandboxrouter/sdk 0.8.0 → 0.8.2

package/README.md

@@ -1,4 +1,4 @@
-# sandboxrouter
+# sandboxRouter
 
 **One API for every sandbox.** A free, open-source router for the places an AI agent can run code: Agent37, Alibaba Cloud, AWS (Bedrock AgentCore and Lambda MicroVMs), Azure Container Apps, Beam, Blaxel, Boat, Cloudflare, CodeSandbox, Daytona, Dedalus Machines, Deno, E2B, exe.dev, Fly.io Sprites, Freestyle, HOPX, InstaBox, Koyeb, Maritime, Modal, Morph, Northflank, Novita, OpenScale, Runloop, Sail, Superserve, Tensorlake, Upstash Box 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.
 
@@ -27,7 +27,7 @@ Site and docs: [sandboxrouter.ai](https://sandboxrouter.ai) · npm: [`@sandboxro
 
 ## Why
 
-AI agents need a disposable computer to run code a model wrote: install packages, run tests, do an RL rollout. Dozens of providers sell one, each with its own SDK and auth, and the same 2 vCPU / 4 GB sandbox costs from under a cent to over thirty cents an hour. sandboxrouter is one interface over all of them:
+AI agents need a disposable computer to run code a model wrote: install packages, run tests, do an RL rollout. Dozens of providers sell one, each with its own SDK and auth, and the same 2 vCPU / 4 GB sandbox costs from under a cent to over thirty cents an hour. sandboxRouter is one interface over all of them:
 
 - **Same code everywhere.** `create`, `exec` (streamed), `writeFile`, `readFile`, `pause`, `kill`. Switch providers by changing which keys are set.
 - **Cheapest real cost, then speed, with fallback.** Or `cheapest` for list price alone, `fastest` by start times, `verified` for tested providers first, or a list of providers you name. `requireVerified` limits a router to providers that passed the real-account check.
@@ -43,9 +43,9 @@ List price while running, 2 vCPU / 4 GB, cheapest first; waitlisted sign-ups fol
 | Provider | $/hr | Plan needed | Real-account check | Source |
 |---|---|---|---|---|
 | [Agent37](https://sandboxrouter.ai/providers/agent37) | $0.007 | none | passed (2026-11-13) | [pricing](https://www.agent37.com/docs/agents-api/billing) |
-| [Boat](https://sandboxrouter.ai/providers/boat) | $0.018 | $20/mo (credited) | not run yet | [pricing](https://docs.boat.dev/pricing.md) |
+| [Boat](https://sandboxrouter.ai/providers/boat) | $0.018 | $20/mo (credited) | passed (2026-11-14) | [pricing](https://docs.boat.dev/pricing.md) |
 | [Maritime](https://sandboxrouter.ai/providers/maritime) | $0.022 | $20/mo (credited) | passed (2026-11-13) | [pricing](https://maritime.sh/pricing) |
-| [Sailboxes (Sail Research)](https://sandboxrouter.ai/providers/sail) | up to $0.062 | none | passed (2026-11-13) | [pricing](https://docs.sailresearch.com/sailboxes-pricing.md) |
+| [Sailboxes (Sail Research)](https://sandboxrouter.ai/providers/sail) | up to $0.062 | none | passed (2026-11-14) | [pricing](https://docs.sailresearch.com/sailboxes-pricing.md) |
 | [Northflank](https://sandboxrouter.ai/providers/northflank) | $0.067 | none | not run yet | [pricing](https://northflank.com/pricing) |
 | [Morph Cloud](https://sandboxrouter.ai/providers/morph) | $0.100 | none | not run yet | [pricing](https://cloud.morph.so/web/pricing) |
 | [exe.dev](https://sandboxrouter.ai/providers/exedev) | $0.105 | $15/mo | not run yet | [pricing](https://exe.dev/docs/standalone-vms.md) |
@@ -57,7 +57,7 @@ List price while running, 2 vCPU / 4 GB, cheapest first; waitlisted sign-ups fol
 | [Blaxel](https://sandboxrouter.ai/providers/blaxel) | $0.166 | none | passed (2026-11-13) | [pricing](https://blaxel.ai/pricing) |
 | [HOPX](https://sandboxrouter.ai/providers/hopx) | $0.166 | none | not run yet | [pricing](https://hopx.ai/pricing) |
 | [Superserve](https://sandboxrouter.ai/providers/superserve) | $0.166 | maybe $20/mo (credited) | passed (2026-11-13) | [pricing](https://superserve.ai/pricing) |
-| [Tensorlake](https://sandboxrouter.ai/providers/tensorlake) | up to $0.200 | none | not run yet | [pricing](https://www.tensorlake.ai/pricing) |
+| [Tensorlake](https://sandboxrouter.ai/providers/tensorlake) | up to $0.200 | none | passed (2026-11-14) | [pricing](https://www.tensorlake.ai/pricing) |
 | [Upstash Box](https://sandboxrouter.ai/providers/upstash) | up to $0.200 | none | not run yet | [pricing](https://upstash.com/pricing/box) |
 | [Cloudflare Sandbox](https://sandboxrouter.ai/providers/cloudflare) | up to $0.216 | $5/mo | passed (2026-11-13) | [pricing](https://developers.cloudflare.com/containers/platform/pricing/) |
 | [Amazon Bedrock AgentCore Code Interpreter](https://sandboxrouter.ai/providers/agentcore) | up to $0.217 | none | passed (2026-11-13) | [pricing](https://aws.amazon.com/bedrock/agentcore/pricing/) |

package/dist/cli.js

@@ -9,7 +9,7 @@ import { gc, listOpen } from "./gc.js";
 import { contributor, publishableCheck } from "./results.js";
 import { loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
 import { DEFAULT_MEMORY_GB, DEFAULT_VCPU, accessLabel, benchmarksPublishable, hourlyCost, listingOrder, planLabel, unfit } from "./catalog.js";
-import { Router } from "./router.js";
+import { Router, rankUsd, runHours } from "./router.js";
 import { createApp } from "./server.js";
 import { RouterError } from "./types.js";
 const HELP = `sandboxrouter: one API for every sandbox provider
@@ -40,7 +40,7 @@ Usage:
   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
+Spec flags:   --vcpu N  --memory GB  --gpu T4  --timeout MIN  --expect SEC (how long you'll use it; ranks by the real bill)
 Route flags:  --provider e2b[,modal,...]  --strategy balanced|verified|cheapest|fastest (default balanced: cheapest real cost, speed breaks near-ties)
               --no-fallback  --fallback-any (also on setup errors like a bad key)
               --create-timeout SEC (per provider, default 120)  --require gpu,custom-image
@@ -54,6 +54,7 @@ const { values, positionals } = parseArgs({
         memory: { type: "string" },
         gpu: { type: "string" },
         timeout: { type: "string" },
+        expect: { type: "string" },
         provider: { type: "string" },
         strategy: { type: "string" },
         "no-fallback": { type: "boolean" },
@@ -96,6 +97,7 @@ const spec = {
     memoryGb: num(values.memory),
     gpu: values.gpu,
     timeoutMinutes: num(values.timeout),
+    expectedSeconds: num(values.expect),
 };
 const providers = list(values.provider);
 const by = (() => {
@@ -165,7 +167,10 @@ async function main() {
             const size = `${c.size.vcpu} vCPU / ${c.size.memoryGb} GB`;
             const speed = c.medianCreateMs !== undefined ? `${c.medianCreateMs} ms` : "";
             const fee = c.perSandboxUsd ? ` + $${c.perSandboxUsd}/sandbox` : "";
-            const cols = [`$${c.estimatedHourlyUsd.toFixed(4)}/hr${list}${fee}`, size, speed, tested].filter(Boolean).join("  ");
+            // With --expect, what that run would be billed (minimum charge and fee included): what it's ranked by.
+            const hours = runHours(spec);
+            const run = spec.expectedSeconds ? `  ≈ $${(rankUsd(c, hours) * hours).toFixed(6)} for ${Math.round(hours * 3600)} s` : "";
+            const cols = [`$${c.estimatedHourlyUsd.toFixed(4)}/hr${list}${fee}${run}`, size, speed, tested].filter(Boolean).join("  ");
             console.log(`${mark} ${c.provider.padEnd(11)} ${cols}${c.skip ? `  (skipped: ${c.skip})` : ""}`);
         }
         return;

package/dist/providers/tensorlake.js

@@ -24,6 +24,7 @@ export class TensorlakeProvider {
         try {
             sbx = await Sandbox.create({
                 apiKey: this.apiKey,
+                name: `sbr-${randomUUID()}`,
                 image,
                 cpus: spec.vcpu ?? DEFAULT_VCPU,
                 memoryMb: Math.round((spec.memoryGb ?? DEFAULT_MEMORY_GB) * 1024),
@@ -160,15 +161,9 @@ class TensorlakeBox {
             throw fail(err);
         }
     }
-    /**
-     * Suspend, keeping memory and disk. Only named sandboxes can suspend, so an unnamed one is
-     * named first. router.get() resumes it.
-     */
+    /** Suspend, keeping memory and disk. Names are assigned at creation and are immutable. */
     async pause() {
         try {
-            const info = await this.sbx.info();
-            if (!info.name)
-                await this.sbx.update({ name: `sbr-${randomUUID()}` });
             await this.sbx.suspend();
         }
         catch (err) {

package/dist/router.d.ts

@@ -31,7 +31,7 @@ export interface Candidate {
     failing: boolean;
     /**
      * A fixed charge per sandbox, USD, on top of `estimatedHourlyUsd` (Sail's free plan: $0.01). Ranking
-     * spreads it over the sandbox's lifetime (`timeoutMinutes`, default 30), so it weighs more on short ones.
+     * spreads it over the run (`expectedSeconds`, else `timeoutMinutes`, default 30), so it weighs more on short ones.
      */
     perSandboxUsd?: number;
     /** Why this provider won't be tried, if it won't. */
@@ -184,10 +184,18 @@ export declare function parseId(id: string): {
  * The default order. Providers whose last real-account check failed go last. The rest go cheapest
  * first by effective price (list price x what the provider really billed, where measured), except that
  * providers within PRICE_TIE of the cheapest remaining one count as a tie and go fastest first (by
- * median create time; unknown speed after known), then cheapest, then alphabetical. A fixed
- * per-sandbox charge counts as spread over `lifetimeHours` (the sandbox's timeoutMinutes).
+ * median create time; unknown speed after known), then cheapest, then alphabetical. Price is what a run
+ * of `lifetimeHours` would be billed (`rankUsd`), as USD per hour.
  */
 export declare function balanced(list: Candidate[], lifetimeHours?: number): Candidate[];
+/** Hours ranking assumes a sandbox runs: `expectedSeconds` (no longer than the lifetime), else `timeoutMinutes` (default 30). */
+export declare function runHours(spec: SandboxSpec): number;
+/**
+ * USD per hour a candidate is ranked by: what a run of `hours` would be billed, divided by `hours`. The
+ * run is rounded up to the provider's minimum and billing increment (`billingRules`), and its
+ * per-sandbox charge is added, so short runs favor providers that bill by the second without a fee.
+ */
+export declare function rankUsd(c: Candidate, hours: number): number;
 /** Seconds to wait for one provider's create before trying the next (RouteOptions.createTimeoutSeconds). */
 export declare const DEFAULT_CREATE_TIMEOUT_S = 120;
 /** Seconds a whole create may take over every provider it tries (RouteOptions.deadlineSeconds). */

package/dist/router.js

@@ -181,7 +181,7 @@ export class Router {
         // depends on who the provider is, only on its price, what it really billed, how fast it started for
         // this router and whether its last real-account check failed. An explicit list keeps the caller's order.
         if (!explicit) {
-            const hours = (spec.timeoutMinutes ?? 30) / 60;
+            const hours = runHours(spec);
             const byCost = (a, b) => rankUsd(a, hours) - rankUsd(b, hours) || a.provider.localeCompare(b.provider);
             const byList = (a, b) => a.listHourlyUsd - b.listHourlyUsd || a.provider.localeCompare(b.provider);
             if (strategy === "fastest") {
@@ -439,8 +439,8 @@ function round(n) {
  * The default order. Providers whose last real-account check failed go last. The rest go cheapest
  * first by effective price (list price x what the provider really billed, where measured), except that
  * providers within PRICE_TIE of the cheapest remaining one count as a tie and go fastest first (by
- * median create time; unknown speed after known), then cheapest, then alphabetical. A fixed
- * per-sandbox charge counts as spread over `lifetimeHours` (the sandbox's timeoutMinutes).
+ * median create time; unknown speed after known), then cheapest, then alphabetical. Price is what a run
+ * of `lifetimeHours` would be billed (`rankUsd`), as USD per hour.
  */
 export function balanced(list, lifetimeHours = 0.5) {
     const cost = (c) => rankUsd(c, lifetimeHours);
@@ -460,9 +460,21 @@ export function balanced(list, lifetimeHours = 0.5) {
     };
     return [...order(list.filter((c) => !c.failing)), ...order(list.filter((c) => c.failing))];
 }
-/** USD per hour a candidate is ranked by: its hourly estimate plus any per-sandbox charge spread over the lifetime. */
-function rankUsd(c, lifetimeHours) {
-    return c.estimatedHourlyUsd + (c.perSandboxUsd ?? 0) / Math.max(lifetimeHours, 1 / 60);
+/** Hours ranking assumes a sandbox runs: `expectedSeconds` (no longer than the lifetime), else `timeoutMinutes` (default 30). */
+export function runHours(spec) {
+    const lifetime = (spec.timeoutMinutes ?? 30) * 60;
+    return Math.min(spec.expectedSeconds ?? lifetime, lifetime) / 3600;
+}
+/**
+ * USD per hour a candidate is ranked by: what a run of `hours` would be billed, divided by `hours`. The
+ * run is rounded up to the provider's minimum and billing increment (`billingRules`), and its
+ * per-sandbox charge is added, so short runs favor providers that bill by the second without a fee.
+ */
+export function rankUsd(c, hours) {
+    const { minSeconds, incrementSeconds } = billingRules(c.provider);
+    const seconds = hours * 3600;
+    const billed = Math.max(minSeconds, Math.ceil(seconds / incrementSeconds - 1e-9) * incrementSeconds);
+    return (c.estimatedHourlyUsd * billed) / Math.max(seconds, 1) + (c.perSandboxUsd ?? 0) / Math.max(hours, 1 / 3600);
 }
 /** Seconds to wait for one provider's create before trying the next (RouteOptions.createTimeoutSeconds). */
 export const DEFAULT_CREATE_TIMEOUT_S = 120;

package/dist/types.d.ts

@@ -18,6 +18,14 @@ export interface SandboxSpec {
     env?: Record<string, string>;
     /** Hard lifetime in minutes (default 30). */
     timeoutMinutes?: number;
+    /**
+     * How long you expect to use the sandbox, in seconds. Only a ranking hint: the sandbox still lives
+     * until you kill it or `timeoutMinutes` runs out. Without it, ranking assumes the whole lifetime.
+     * With it, providers are ranked by what that run would really be billed, minimum charge, billing
+     * increment and per-sandbox fee included, so a provider that bills per second can beat one that is
+     * cheaper per hour but charges a full minute.
+     */
+    expectedSeconds?: number;
     /**
      * Provider-specific image/template, keyed by provider, e.g.
      * { maritime: "python", e2b: "code-interpreter-v1", modal: "python:3.13-slim" }.

package/dist/validate.d.ts

@@ -1,6 +1,6 @@
 import { type RouteOptions, type SandboxSpec, type Strategy } from "./types.js";
 /** Every key a SandboxSpec can have. Anything else in a request is a mistake (e.g. "memory" for "memoryGb"). */
-export declare const SPEC_KEYS: readonly ["vcpu", "memoryGb", "gpu", "env", "timeoutMinutes", "image", "metadata"];
+export declare const SPEC_KEYS: readonly ["vcpu", "memoryGb", "gpu", "env", "timeoutMinutes", "expectedSeconds", "image", "metadata"];
 /** Every key RouteOptions can have. */
 export declare const ROUTE_KEYS: readonly ["provider", "strategy", "fallback", "require", "createTimeoutSeconds", "deadlineSeconds"];
 export declare const STRATEGIES: readonly Strategy[];

package/dist/validate.js

@@ -1,7 +1,7 @@
 import { CATALOG } from "./catalog.js";
 import { RouterError } from "./types.js";
 /** Every key a SandboxSpec can have. Anything else in a request is a mistake (e.g. "memory" for "memoryGb"). */
-export const SPEC_KEYS = ["vcpu", "memoryGb", "gpu", "env", "timeoutMinutes", "image", "metadata"];
+export const SPEC_KEYS = ["vcpu", "memoryGb", "gpu", "env", "timeoutMinutes", "expectedSeconds", "image", "metadata"];
 /** Every key RouteOptions can have. */
 export const ROUTE_KEYS = ["provider", "strategy", "fallback", "require", "createTimeoutSeconds", "deadlineSeconds"];
 export const STRATEGIES = ["default", "balanced", "verified", "cheapest", "fastest"];
@@ -16,7 +16,7 @@ const stringMap = (v) => typeof v === "object" && v !== null && !Array.isArray(v
  * Called by `plan()`, so every create, route and CLI command goes through it.
  */
 export function validate(spec = {}, route = {}) {
-    for (const k of ["vcpu", "memoryGb", "timeoutMinutes"]) {
+    for (const k of ["vcpu", "memoryGb", "timeoutMinutes", "expectedSeconds"]) {
         if (spec[k] !== undefined && !positive(spec[k]))
             throw bad(`${k} must be a positive number, got ${show(spec[k])}`);
     }

package/dist/verified.js

@@ -3,6 +3,7 @@ export const VERIFIED = {
     agentcore: "2026-11-13",
     lambda: "2026-11-13",
     blaxel: "2026-11-13",
+    boat: "2026-11-14",
     cloudflare: "2026-11-13",
     daytona: "2026-11-13",
     e2b: "2026-11-13",
@@ -12,8 +13,9 @@ export const VERIFIED = {
     modal: "2026-11-13",
     novita: "2026-11-13",
     openscale: "2026-11-13",
-    sail: "2026-11-13",
+    sail: "2026-11-14",
     superserve: "2026-11-13",
+    tensorlake: "2026-11-14",
     vercel: "2026-11-13",
 };
 /** Providers whose last saved real-account check failed a step. The default strategy tries them last. */

package/package.json

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