@sandboxrouter/sdk 0.1.0 → 0.3.0

package/dist/check.d.ts

@@ -0,0 +1,28 @@
+import type { Router } from "./router.js";
+import type { ProviderId, SandboxSpec } from "./types.js";
+/** Every step `check` runs, in order. Each provider's saved report is scored against this list. */
+export declare const CHECK_STEPS: readonly ["create", "exec: stdout, stderr, exit code", "exec: env and cwd", "exec: UTF-8 output", "exec: streaming", "files: binary round-trip", "files: 1 MB round-trip", "files: missing file is an error", "files: visible to commands", "exec: command timeout", "exec: timed-out command was stopped", "pause and resume", "kill", "killed sandbox is gone"];
+export type CheckStatus = "pass" | "fail" | "skip" | "info";
+export interface CheckResult {
+    step: string;
+    status: CheckStatus;
+    ms: number;
+    detail?: string;
+}
+export interface CheckReport {
+    provider: ProviderId;
+    sandboxId?: string;
+    results: CheckResult[];
+    /** True when no step failed. */
+    ok: boolean;
+}
+/**
+ * One real pass over a provider: create, exec (stdout, stderr, exit code, env, cwd), streaming,
+ * a binary file round-trip, pause and resume where supported, and kill. Meant for testing an
+ * adapter against a real account; every step is recorded, and later steps still run after a
+ * failure when they can.
+ */
+export declare function checkProvider(router: Router, provider: ProviderId, opts?: {
+    spec?: SandboxSpec;
+    onStep?: (r: CheckResult) => void;
+}): Promise<CheckReport>;

package/dist/check.js

@@ -0,0 +1,185 @@
+import { fixedSize } from "./catalog.js";
+/** Every step `check` runs, in order. Each provider's saved report is scored against this list. */
+export const CHECK_STEPS = [
+    "create",
+    "exec: stdout, stderr, exit code",
+    "exec: env and cwd",
+    "exec: UTF-8 output",
+    "exec: streaming",
+    "files: binary round-trip",
+    "files: 1 MB round-trip",
+    "files: missing file is an error",
+    "files: visible to commands",
+    "exec: command timeout",
+    "exec: timed-out command was stopped",
+    "pause and resume",
+    "kill",
+    "killed sandbox is gone",
+];
+/**
+ * One real pass over a provider: create, exec (stdout, stderr, exit code, env, cwd), streaming,
+ * a binary file round-trip, pause and resume where supported, and kill. Meant for testing an
+ * adapter against a real account; every step is recorded, and later steps still run after a
+ * failure when they can.
+ */
+export async function checkProvider(router, provider, opts = {}) {
+    const results = [];
+    const record = (r) => {
+        results.push(r);
+        opts.onStep?.(r);
+    };
+    const step = async (name, fn) => {
+        const t0 = Date.now();
+        try {
+            const out = await fn();
+            const r = typeof out === "object" && out ? out : { status: "pass", detail: out || undefined };
+            record({ step: name, ms: Date.now() - t0, ...r });
+            return r.status !== "fail";
+        }
+        catch (err) {
+            record({ step: name, status: "fail", ms: Date.now() - t0, detail: err?.message ?? String(err) });
+            return false;
+        }
+    };
+    let sbx;
+    await step("create", async () => {
+        sbx = await router.create({ timeoutMinutes: 10, ...fixedSize(provider), ...opts.spec }, { provider, fallback: false });
+        return `${sbx.id}, ~$${sbx.estimatedHourlyUsd}/hr`;
+    });
+    if (!sbx)
+        return { provider, results, ok: false };
+    const box = sbx;
+    try {
+        await step("exec: stdout, stderr, exit code", async () => {
+            const r = await box.exec("printf hi; printf err >&2; exit 3");
+            const bad = [];
+            if (r.stdout !== "hi")
+                bad.push(`stdout ${JSON.stringify(r.stdout)}`);
+            if (r.stderr !== "err")
+                bad.push(`stderr ${JSON.stringify(r.stderr)}`);
+            if (r.exitCode !== 3)
+                bad.push(`exit ${r.exitCode}`);
+            if (bad.length)
+                throw new Error(`expected "hi" / "err" / 3, got ${bad.join(", ")}`);
+        });
+        await step("exec: env and cwd", async () => {
+            const r = await box.exec('printf "%s %s" "$SBR_CHECK" "$(pwd)"', { env: { SBR_CHECK: "v1" }, cwd: "/tmp" });
+            if (r.stdout.trim() !== "v1 /tmp")
+                throw new Error(`expected "v1 /tmp", got ${JSON.stringify(r.stdout)}`);
+        });
+        await step("exec: UTF-8 output", async () => {
+            // "café ✓" as octal escapes, so the command itself is plain ASCII.
+            const r = await box.exec("printf 'caf\\303\\251 \\342\\234\\223'");
+            if (r.stdout !== "café ✓")
+                throw new Error(`expected "café ✓", got ${JSON.stringify(r.stdout)}`);
+        });
+        await step("exec: streaming", async () => {
+            const t0 = Date.now();
+            let first = -1;
+            let chunks = 0;
+            const r = await box.exec("for i in 1 2 3; do echo $i; sleep 1; done", {
+                onStdout: () => {
+                    chunks++;
+                    if (first < 0)
+                        first = Date.now() - t0;
+                },
+            });
+            const total = Date.now() - t0;
+            if (r.stdout.replace(/\s+/g, "") !== "123")
+                throw new Error(`expected 1 2 3, got ${JSON.stringify(r.stdout)}`);
+            if (chunks === 0)
+                throw new Error("onStdout was never called");
+            const live = first >= 0 && first < total - 1500;
+            return { status: live ? "pass" : "info", detail: live ? `first output after ${first} ms` : "output arrived only at the end (no live streaming)" };
+        });
+        const bytes = new Uint8Array(256 * 4).map((_, i) => i % 256);
+        const path = "/tmp/sbr-check/nested/bin.dat";
+        await step("files: binary round-trip", async () => {
+            await box.writeFile(path, bytes);
+            const back = await box.readFile(path);
+            if (back.length !== bytes.length || back.some((b, i) => b !== bytes[i]))
+                throw new Error(`read back ${back.length} bytes, content differs`);
+        });
+        await step("files: 1 MB round-trip", async () => {
+            // Big enough to cross every adapter's chunking; a pattern that isn't all one repeating byte.
+            const big = new Uint8Array(1024 * 1024).map((_, i) => (i * 31 + (i >> 10)) % 256);
+            await box.writeFile("/tmp/sbr-check/big.bin", big);
+            const back = await box.readFile("/tmp/sbr-check/big.bin");
+            if (back.length !== big.length)
+                throw new Error(`read back ${back.length} of ${big.length} bytes`);
+            const at = back.findIndex((b, i) => b !== big[i]);
+            if (at >= 0)
+                throw new Error(`content differs from byte ${at}`);
+        });
+        await step("files: missing file is an error", async () => {
+            let got;
+            try {
+                got = await box.readFile("/tmp/sbr-check/does-not-exist");
+            }
+            catch {
+                return;
+            }
+            throw new Error(`readFile of a missing file returned ${got.length} bytes instead of throwing`);
+        });
+        await step("files: visible to commands", async () => {
+            await box.writeFile("/tmp/sbr-check/hello.txt", "hello from writeFile\n");
+            const r = await box.exec("cat /tmp/sbr-check/hello.txt && printf made > /tmp/sbr-check/made.txt");
+            if (r.stdout.trim() !== "hello from writeFile")
+                throw new Error(`cat printed ${JSON.stringify(r.stdout)}`);
+            const made = await box.readText("/tmp/sbr-check/made.txt");
+            if (made !== "made")
+                throw new Error(`readFile of a command's file gave ${JSON.stringify(made)}`);
+        });
+        await step("exec: command timeout", async () => {
+            // The contract: the command is stopped and exec rejects with "command timed out after Ns".
+            const seconds = 3;
+            const t0 = Date.now();
+            let outcome;
+            try {
+                const r = await box.exec(`sleep 30; echo late`, { timeoutSeconds: seconds });
+                outcome = `returned exit ${r.exitCode}${r.stdout.includes("late") ? " and ran to completion" : ""}`;
+            }
+            catch (err) {
+                const message = err.message;
+                if (message.endsWith(`command timed out after ${seconds}s`))
+                    return `threw after ${Date.now() - t0} ms`;
+                outcome = `threw "${message}"`;
+            }
+            throw new Error(`expected a "command timed out after ${seconds}s" error, ${outcome} after ${Date.now() - t0} ms`);
+        });
+        await step("exec: timed-out command was stopped", async () => {
+            // A command killed by its timeout must not finish on its own later.
+            await box.exec("rm -f /tmp/sbr-check/late; sleep 4 && echo late > /tmp/sbr-check/late", { timeoutSeconds: 1 }).catch(() => { });
+            await new Promise((r) => setTimeout(r, 5000));
+            const r = await box.exec("cat /tmp/sbr-check/late 2>/dev/null || echo stopped");
+            if (r.stdout.includes("late"))
+                throw new Error("the command kept running after its timeout");
+        });
+        if (box.canPause) {
+            await step("pause and resume", async () => {
+                await box.pause();
+                const again = await router.get(box.id);
+                const r = await again.exec("cat /tmp/sbr-check/hello.txt");
+                if (r.stdout.trim() !== "hello from writeFile")
+                    throw new Error(`after resume, file read ${JSON.stringify(r.stdout)}`);
+            });
+        }
+        else {
+            record({ step: "pause and resume", status: "skip", ms: 0, detail: "adapter has no pause" });
+        }
+    }
+    finally {
+        await step("kill", () => box.kill());
+    }
+    await step("killed sandbox is gone", async () => {
+        try {
+            const again = await router.get(box.id);
+            await again.exec("echo still-here", { timeoutSeconds: 10 });
+        }
+        catch {
+            return;
+        }
+        return { status: "fail", detail: "the sandbox still ran a command after kill(): check the dashboard, it may still bill" };
+    });
+    return { provider, sandboxId: box.id, results, ok: !results.some((r) => r.status === "fail") };
+}

package/dist/cli.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
-import { readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { platform, arch } from "node:os";
 import { bench, benchMarkdown } from "./bench.js";
+import { costMarkdown, costRun, settle } from "./cost.js";
+import { checkProvider } from "./check.js";
+import { gc, listOpen } from "./gc.js";
 import { loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
-import { CATALOG, hourlyCost } from "./catalog.js";
+import { accessLabel, hourlyCost, listingOrder, planLabel, unfit } from "./catalog.js";
 import { Router } from "./router.js";
 import { createApp } from "./server.js";
 import { RouterError } from "./types.js";
@@ -13,19 +17,32 @@ 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]]
+                          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
+  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
   sandboxrouter bench     [--runs 3] [--provider a,b] [--json] [--share [--label "where you ran it"]]
+  sandboxrouter cost run  [--provider a,b] [--minutes 10] [--vcpu 2 --memory 4] [--no-load] [--out FILE]
+                          start one sandbox per provider for a fixed time with every core busy, record
+                          the size it really got and the list-price prediction
+  sandboxrouter cost settle FILE
+                          read what each provider actually billed for those sandboxes (rerun until all
+                          bills have posted) and print predicted vs billed
   sandboxrouter leaderboard [results-dir] [--out leaderboard.html]
-  sandboxrouter desktop   [--os linux|windows|android] [--user ID] [--control]
+  sandboxrouter desktop   [--os linux|windows|android|ios] [--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
+Route flags:  --provider e2b[,modal,...]  --strategy cheapest|fastest
+              --no-fallback  --fallback-any (also on setup errors like a bad key)
+              --create-timeout SEC (per provider, default 120)  --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)`;
+Keys: one env var group per provider; "sandboxrouter providers" lists them and shows which are set.`;
 const { values, positionals } = parseArgs({
     allowPositionals: true,
     options: {
@@ -36,6 +53,8 @@ const { values, positionals } = parseArgs({
         provider: { type: "string" },
         strategy: { type: "string" },
         "no-fallback": { type: "boolean" },
+        "fallback-any": { type: "boolean" },
+        "create-timeout": { type: "string" },
         require: { type: "string" },
         keep: { type: "boolean" },
         runs: { type: "string" },
@@ -50,6 +69,12 @@ const { values, positionals } = parseArgs({
         share: { type: "boolean" },
         cors: { type: "string" },
         label: { type: "string" },
+        all: { type: "boolean" },
+        save: { type: "boolean" },
+        "older-than": { type: "string" },
+        "dry-run": { type: "boolean" },
+        minutes: { type: "string" },
+        "no-load": { type: "boolean" },
     },
 });
 const list = (s) => (s ? s.split(",").map((x) => x.trim()).filter(Boolean) : undefined);
@@ -64,7 +89,8 @@ const providers = list(values.provider);
 const route = {
     provider: providers,
     strategy: values.strategy,
-    fallback: values["no-fallback"] ? false : undefined,
+    fallback: values["no-fallback"] ? false : values["fallback-any"] ? "any" : undefined,
+    createTimeoutSeconds: num(values["create-timeout"]),
     require: list(values.require),
 };
 async function main() {
@@ -73,16 +99,19 @@ async function main() {
     if (!cmd || values.help)
         return console.log(HELP);
     if (cmd === "providers") {
-        const rows = CATALOG.map((c) => ({
+        const rows = listingOrder(spec).map((c) => ({
             provider: c.name,
             id: c.id,
-            "$/hr": `$${hourlyCost(c.id, spec).toFixed(4)}`,
+            "$/hr": unfit(c.id, spec) ?? `${c.billing === "active-cpu" ? "up to " : ""}$${hourlyCost(c.id, spec).toFixed(4)}`,
+            plan: c.local ? "none" : planLabel(c.id),
             configured: router.isConfigured(c.id) ? "yes" : "no",
             capabilities: c.capabilities.join(", ") || "-",
+            "sign-up": accessLabel(c.id) ?? "open",
         }));
         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.log(`Estimated list price for ${spec.vcpu ?? 2} vCPU, ${spec.memoryGb ?? 4} GB while running, cheapest first.`);
+        console.log(`"up to" = billed on active CPU only, shown with every core busy. plan = monthly plan needed to use the API.\n`);
         console.table(rows);
         return;
     }
@@ -102,6 +131,13 @@ async function main() {
         if (!command)
             throw new RouterError('usage: sandboxrouter run "<cmd>"');
         const sbx = await router.create(spec, route);
+        // Ctrl-C: kill the sandbox before exiting instead of leaving it billing.
+        const stop = () => {
+            console.error(`\n> interrupted, killing ${sbx.id}`);
+            sbx.kill().finally(() => process.exit(130));
+        };
+        if (!values.keep)
+            process.once("SIGINT", stop);
         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)`);
@@ -121,6 +157,73 @@ async function main() {
         }
         return;
     }
+    if (cmd === "check") {
+        const ids = values.all ? router.registered().filter((id) => router.isConfigured(id)) : providers;
+        if (!ids?.length) {
+            if (values.all)
+                return console.log("No providers configured: set at least one provider's keys (sandboxrouter providers lists them).");
+            throw new RouterError("usage: sandboxrouter check --provider <id>[,<id>...] | --all");
+        }
+        const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+        const saveDir = values.save ? (rest[0] ?? "results/conformance") : undefined;
+        const mark = { pass: "ok  ", fail: "FAIL", skip: "skip", info: "note" };
+        const reports = [];
+        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 ?? ""}`);
+                },
+            });
+            reports.push(report);
+            if (saveDir) {
+                mkdirSync(saveDir, { recursive: true });
+                const saved = { tool: "sandboxrouter-check", version, date: new Date().toISOString(), platform: `${platform()}-${arch()}`, ...report };
+                writeFileSync(`${saveDir}/${p}.json`, JSON.stringify(saved, null, 2) + "\n");
+            }
+        }
+        if (values.json)
+            console.log(JSON.stringify(reports, null, 2));
+        else
+            console.log(`\n${reports.filter((r) => r.ok).length}/${reports.length} passed`);
+        if (reports.some((r) => !r.ok))
+            process.exitCode = 1;
+        return;
+    }
+    if (cmd === "ls") {
+        if (!router.ledger)
+            return console.log("The sandbox ledger is off (SANDBOXROUTER_LEDGER=off), so there is nothing to list.");
+        const open = listOpen(router);
+        if (values.json)
+            return console.log(JSON.stringify(open, null, 2));
+        if (!open.length)
+            return console.log(`No open sandboxes in ${router.ledger.file}.`);
+        for (const s of open) {
+            const left = Math.round((Date.parse(s.expiresAt) - Date.now()) / 60_000);
+            const when = s.expired ? `past its lifetime by ${-left} min` : `${left} min of lifetime left`;
+            console.log(`${s.id.padEnd(40)} up ${String(s.ageMinutes).padStart(5)} min  ${when.padEnd(28)} ~$${s.estimatedUsdSoFar.toFixed(4)} so far`);
+        }
+        const expired = open.filter((s) => s.expired).length;
+        console.log(`\n${open.length} open, ${expired} past their lifetime. "sandboxrouter gc" kills those; "gc --all" kills every one.`);
+        return;
+    }
+    if (cmd === "gc") {
+        if (!router.ledger)
+            return console.log("The sandbox ledger is off (SANDBOXROUTER_LEDGER=off), so there is nothing to clean up.");
+        const results = await gc(router, { all: values.all, olderThanMinutes: num(values["older-than"]), dryRun: values["dry-run"] });
+        if (values.json)
+            return console.log(JSON.stringify(results, null, 2));
+        if (!results.length)
+            return console.log("Nothing to clean up.");
+        for (const r of results)
+            console.log(`${r.action.padEnd(10)} ${r.id}${r.detail ? `  (${r.detail})` : ""}`);
+        if (results.some((r) => r.action === "failed"))
+            process.exitCode = 1;
+        return;
+    }
     if (cmd === "bench") {
         const rows = await bench({
             router,
@@ -146,6 +249,36 @@ async function main() {
         }
         return;
     }
+    if (cmd === "cost") {
+        const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+        if (rest[0] === "run") {
+            const ids = providers ?? router.registered().filter((id) => router.isConfigured(id) && id !== "docker");
+            if (!ids.length)
+                return console.error("No providers configured. Set at least one API key (see --help).");
+            const run = await costRun({
+                router,
+                providers: ids,
+                minutes: num(values.minutes) ?? 10,
+                spec,
+                load: !values["no-load"],
+                version,
+                onProgress: (m) => console.error(m),
+            });
+            const file = values.out ?? `results/cost/cost-${run.date.slice(0, 16).replace(/[:T]/g, "-")}.json`;
+            mkdirSync(file.replace(/\/[^/]*$/, "") || ".", { recursive: true });
+            writeFileSync(file, JSON.stringify(await settle(run), null, 2) + "\n");
+            console.log(costMarkdown(run));
+            console.log(`\nwrote ${file}. Bills post late on some providers: run "sandboxrouter cost settle ${file}" again later.`);
+            return;
+        }
+        if (rest[0] === "settle" && rest[1]) {
+            const run = (await settle(JSON.parse(readFileSync(rest[1], "utf8"))));
+            writeFileSync(rest[1], JSON.stringify(run, null, 2) + "\n");
+            console.log(costMarkdown(run));
+            return;
+        }
+        return console.error('Usage: sandboxrouter cost run [...] | sandboxrouter cost settle FILE');
+    }
     if (cmd === "leaderboard") {
         const dir = rest[0] ?? "results";
         const reports = loadReports(dir);
@@ -177,12 +310,16 @@ async function main() {
         const port = num(values.port) ?? Number(process.env.PORT ?? 8787);
         const host = values.host ?? "127.0.0.1";
         const origins = list(values.cors);
+        const loopback = /^(127\.\d+\.\d+\.\d+|::1|localhost)$/.test(host);
+        if (!process.env.SANDBOXROUTER_TOKEN && !loopback) {
+            throw new RouterError(`refusing to listen on ${host} without SANDBOXROUTER_TOKEN: anyone who can reach it could start sandboxes on your keys`);
+        }
         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");
+                console.log("note: SANDBOXROUTER_TOKEN is not set; any program on this machine can use the API");
         });
         return;
     }

package/dist/computers.d.ts

@@ -1,9 +1,11 @@
-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.
+ * Linux and Windows desktops, Android phones. Routed like sandboxes: cheapest published price for
+ * the requested OS first, ties alphabetical.
  */
-export type ComputerOs = "linux" | "windows" | "android";
+/** Computer providers include sandbox providers (maritime, e2b, daytona) and desktop-only ones. */
+export type ComputerProviderId = string;
+export type ComputerOs = "linux" | "windows" | "android" | "ios";
 export interface ComputerSpec {
     os?: ComputerOs;
     /** Your user's id. The same id returns the same computer (files and logins kept). */
@@ -72,29 +74,33 @@ export interface ProviderComputer {
     }>;
     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?: {
+    /**
+     * A link for a person: `watch` is view-only, `control` hands them the desktop (logins, CAPTCHAs).
+     * Optional: only on providers that offer a shareable live view. `expiresAt` may be null.
+     */
+    viewer?(mode?: "watch" | "control", opts?: {
         ttlSeconds?: number;
         reason?: string;
     }): Promise<{
         url: string;
-        expiresAt: string;
+        expiresAt: string | null;
     }>;
-    sleep(): Promise<void>;
+    /** Optional: stop billing while keeping the computer, where the provider supports it. */
+    sleep?(): Promise<void>;
     delete(): Promise<void>;
 }
 export interface ComputerProvider {
-    readonly id: ProviderId;
+    readonly id: ComputerProviderId;
     readonly computerOs: ComputerOs[];
     configured(): boolean;
     createComputer(spec: ComputerSpec): Promise<ProviderComputer>;
     connectComputer(nativeId: string): Promise<ProviderComputer>;
 }
 export declare class RoutedComputer {
-    readonly provider: ProviderId;
+    readonly provider: ComputerProviderId;
     private c;
     readonly id: string;
-    constructor(provider: ProviderId, c: ProviderComputer);
+    constructor(provider: ComputerProviderId, c: ProviderComputer);
     get nativeId(): string;
     info(): Promise<ComputerInfo>;
     act(action: ComputerAction): Promise<ActionResult>;
@@ -110,15 +116,51 @@ export declare class RoutedComputer {
     }>;
     readFile(path: string): Promise<Uint8Array<ArrayBufferLike>>;
     writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    /** What this computer's provider supports beyond the core actions. */
+    get supports(): {
+        viewer: boolean;
+        sleep: boolean;
+    };
     viewer(mode?: "watch" | "control", opts?: {
         ttlSeconds?: number;
         reason?: string;
     }): Promise<{
         url: string;
-        expiresAt: string;
+        expiresAt: string | null;
     }>;
     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>;
+/** Published prices per OS for every computer provider. Same rules as the sandbox catalog. */
+export interface ComputerCatalogEntry {
+    id: ComputerProviderId;
+    name: string;
+    /** USD per hour while awake, per OS offered. */
+    os: Partial<Record<ComputerOs, number>>;
+    note?: string;
+    source: string;
+    checked: string;
+    /** A person can watch or take over the screen through a link. */
+    takeover: boolean;
+    /** The machine you get by default, so prices compare like for like, e.g. "2 vCPU · 4 GB". */
+    size: string;
+    /** OSes offered only on a monthly plan, with no hourly price. Routed last for that OS. */
+    planOnly?: ComputerOs[];
+    credentials: string[][];
+    docs: string;
+}
+export declare const COMPUTER_ENTRIES: ComputerCatalogEntry[];
+export declare function computerCatalog(): ComputerCatalogEntry[];
+export declare function computerHourly(id: ComputerProviderId, os: ComputerOs): number | undefined;
+export interface ComputerCandidate {
+    provider: ComputerProviderId;
+    estimatedHourlyUsd?: number;
+    skip?: string;
+}
+/** 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[];
+/**
+ * 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.
+ */
+export declare function createComputer(providers: ComputerProvider[], spec?: ComputerSpec, prefer?: ComputerProviderId[]): Promise<RoutedComputer>;