@sandboxrouter/sdk 0.8.1 → 0.8.2

package/README.md

@@ -43,7 +43,7 @@ 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-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) |

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/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",

package/package.json

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