@sandboxrouter/sdk 0.0.0-stage → 0.2.0

package/dist/catalog.js

@@ -0,0 +1,320 @@
+/**
+ * Every provider is treated the same: the router orders candidates by list price for the requested
+ * size (or by your measured cold starts), ties broken alphabetically. Nobody gets a better slot.
+ * Prices come from each provider's public pricing page; PRs that correct one are welcome.
+ */
+const ENTRIES = [
+    {
+        id: "docker",
+        name: "Docker (local)",
+        pricing: {
+            vcpuHour: 0,
+            gbHour: 0,
+            note: "runs on your own machine; free, but shares your kernel, so weaker isolation than a cloud micro-VM",
+            source: "https://docs.docker.com/engine/",
+            checked: "2026-11-04",
+        },
+        capabilities: ["pause", "custom-image"],
+        limits: { maxVcpu: 64, maxMemoryGb: 256 },
+        local: true,
+        credentials: [],
+        docs: "https://docs.docker.com/engine/",
+    },
+    {
+        id: "maritime",
+        name: "Maritime",
+        pricing: {
+            vcpuHour: 0.0055,
+            gbHour: 0.00275,
+            note: "per second, disk included",
+            source: "https://maritime.sh/pricing",
+            checked: "2026-11-04",
+        },
+        capabilities: ["pause", "custom-image"],
+        limits: { maxVcpu: 16, maxMemoryGb: 64 },
+        credentials: [["MARITIME_API_KEY"]],
+        docs: "https://maritime.sh/docs/ephemeral-sandboxes",
+    },
+    {
+        id: "e2b",
+        name: "E2B",
+        pricing: {
+            vcpuHour: 0.0504,
+            gbHour: 0.0162,
+            note: "per second; Pro plan $150/mo",
+            source: "https://e2b.dev/pricing",
+            checked: "2026-11-04",
+        },
+        capabilities: ["pause", "custom-image"],
+        limits: { maxVcpu: 8, maxMemoryGb: 8 },
+        credentials: [["E2B_API_KEY"]],
+        docs: "https://e2b.dev/docs",
+    },
+    {
+        id: "daytona",
+        name: "Daytona",
+        pricing: {
+            vcpuHour: 0.0504,
+            gbHour: 0.0162,
+            note: "per second, plus disk above 5 GiB",
+            source: "https://www.daytona.io/pricing",
+            checked: "2026-11-04",
+        },
+        capabilities: ["pause", "custom-image"],
+        limits: { maxVcpu: 4, maxMemoryGb: 8 },
+        credentials: [["DAYTONA_API_KEY"]],
+        docs: "https://www.daytona.io/docs",
+    },
+    {
+        id: "modal",
+        name: "Modal",
+        pricing: {
+            vcpuHour: 0.07096,
+            gbHour: 0.0242,
+            note: "sandbox rates, GPUs extra; region pinning x1.15-1.75",
+            source: "https://modal.com/pricing",
+            checked: "2026-11-04",
+        },
+        capabilities: ["gpu", "custom-image"],
+        limits: { maxVcpu: 64, maxMemoryGb: 256 },
+        credentials: [["MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET"]],
+        docs: "https://modal.com/docs/guide/sandbox",
+    },
+    {
+        id: "vercel",
+        name: "Vercel Sandbox",
+        pricing: {
+            vcpuHour: 0.128,
+            gbHour: 0.0212,
+            note: "bills active CPU only; this is the 100%-CPU price, idle work costs less",
+            source: "https://vercel.com/docs/vercel-sandbox/pricing",
+            checked: "2026-11-04",
+        },
+        capabilities: [],
+        limits: { maxVcpu: 8, maxMemoryGb: 16 },
+        credentials: [["VERCEL_OIDC_TOKEN"], ["VERCEL_TOKEN", "VERCEL_TEAM_ID", "VERCEL_PROJECT_ID"]],
+        docs: "https://vercel.com/docs/vercel-sandbox",
+    },
+    {
+        id: "morph",
+        name: "Morph Cloud",
+        pricing: {
+            vcpuHour: 0.05,
+            gbHour: 0,
+            note: "$0.05/MCU; MCU-hours = max(vCPU, RAM/4 GB, disk/16 GB); snapshots extra",
+            source: "https://cloud.morph.so/web/pricing",
+            checked: "2026-11-04",
+        },
+        capabilities: ["pause", "custom-image"],
+        limits: { maxVcpu: 64, maxMemoryGb: 256 },
+        credentials: [["MORPH_API_KEY"]],
+        docs: "https://cloud.morph.so/docs/developers",
+    },
+    {
+        id: "sprites",
+        name: "Fly.io Sprites",
+        pricing: {
+            vcpuHour: 0.0385,
+            gbHour: 0.021875,
+            note: "bills actual CPU and memory use; this is the full-use price; storage extra",
+            source: "https://fly.io/sprites",
+            checked: "2026-11-04",
+        },
+        capabilities: [],
+        // Not published per sprite; 8 GB is what accounts report getting by default.
+        limits: { maxVcpu: 8, maxMemoryGb: 8 },
+        credentials: [["SPRITES_TOKEN"]],
+        docs: "https://fly.io/sprites",
+    },
+    {
+        id: "blaxel",
+        name: "Blaxel",
+        pricing: {
+            vcpuHour: 0,
+            gbHour: 0.0414,
+            note: "billed on memory only ($0.0000115/GB-s), CPU scales with memory (~2 GB per core)",
+            source: "https://blaxel.ai/pricing",
+            checked: "2026-11-04",
+        },
+        capabilities: ["pause", "custom-image"],
+        // Self-serve caps are per-tier and not published; these are conservative.
+        limits: { maxVcpu: 8, maxMemoryGb: 16 },
+        credentials: [["BL_API_KEY", "BL_WORKSPACE"]],
+        docs: "https://docs.blaxel.ai/Sandboxes/Overview",
+    },
+    {
+        id: "tensorlake",
+        name: "Tensorlake",
+        pricing: {
+            vcpuHour: 0.07,
+            gbHour: 0.015,
+            note: "bills active CPU (floor 20% of allocation); this is the full-use price; Pro plan is lower",
+            source: "https://www.tensorlake.ai/pricing",
+            checked: "2026-11-04",
+        },
+        capabilities: ["pause", "custom-image"],
+        limits: { maxVcpu: 4, maxMemoryGb: 16 },
+        credentials: [["TENSORLAKE_API_KEY"]],
+        docs: "https://docs.tensorlake.ai/sandboxes",
+    },
+    {
+        id: "runloop",
+        name: "Runloop",
+        pricing: {
+            vcpuHour: 0.108,
+            gbHour: 0.0252,
+            note: "per second, plus disk; pause (suspend) is a Pro-plan feature",
+            source: "https://www.runloop.ai/pricing",
+            checked: "2026-11-04",
+        },
+        capabilities: ["pause", "custom-image"],
+        limits: { maxVcpu: 16, maxMemoryGb: 64 },
+        credentials: [["RUNLOOP_API_KEY"]],
+        docs: "https://docs.runloop.ai",
+    },
+];
+ENTRIES.push({
+    id: "boat",
+    name: "Boat",
+    pricing: {
+        vcpuHour: 0.009,
+        gbHour: 0,
+        note: "fixed sizes billed per second ($0.018/h for 2 vCPU / 4 GB up to $0.20/h for 16 / 32); needs a plan from $20/mo, paid back as VM time",
+        source: "https://docs.boat.dev/pricing.md",
+        checked: "2026-11-04",
+    },
+    // "pause" here is Boat's stop: the disk is kept, running processes end.
+    capabilities: ["pause", "custom-image"],
+    limits: { maxVcpu: 16, maxMemoryGb: 32 },
+    credentials: [["BOAT_API_KEY"]],
+    docs: "https://docs.boat.dev",
+}, {
+    id: "exedev",
+    name: "exe.dev",
+    pricing: {
+        vcpuHour: 0.0525,
+        gbHour: 0,
+        note: "$0.105/h per 2 vCPU + 4 GiB, per second, up to 2 GiB per vCPU; needs an exe.dev subscription",
+        source: "https://exe.dev/docs/standalone-vms.md",
+        checked: "2026-11-04",
+    },
+    capabilities: ["custom-image"],
+    limits: { maxVcpu: 16, maxMemoryGb: 32 },
+    credentials: [["EXE_TOKEN"]],
+    docs: "https://exe.dev/docs/https-api.md",
+}, {
+    id: "northflank",
+    name: "Northflank",
+    pricing: {
+        vcpuHour: 0.01667,
+        gbHour: 0.00833,
+        note: "per second on Northflank Cloud, ephemeral disk included; sandboxes run as deployment services (microVMs)",
+        source: "https://northflank.com/pricing",
+        checked: "2026-11-04",
+    },
+    capabilities: ["custom-image"],
+    limits: { maxVcpu: 8, maxMemoryGb: 16 },
+    credentials: [["NORTHFLANK_API_TOKEN", "NORTHFLANK_PROJECT_ID"]],
+    docs: "https://northflank.com/docs/v1/application/overview",
+}, {
+    id: "hopx",
+    name: "HOPX",
+    pricing: {
+        vcpuHour: 0.0504,
+        gbHour: 0.0162,
+        note: "per second, plus storage; size comes from the template, not the request",
+        source: "https://hopx.ai/pricing",
+        checked: "2026-11-04",
+    },
+    capabilities: ["pause", "custom-image"],
+    // HOPX takes no size at create; capped at the default size so bigger requests go elsewhere.
+    limits: { maxVcpu: 2, maxMemoryGb: 4 },
+    credentials: [["HOPX_API_KEY"]],
+    docs: "https://docs.hopx.ai",
+}, {
+    id: "cloudflare",
+    name: "Cloudflare Sandbox",
+    pricing: {
+        vcpuHour: 0.072,
+        gbHour: 0.009,
+        note: "bills active CPU and provisioned memory of the instance type; this is the full-CPU price; needs Workers Paid ($5/mo) and the bridge Worker in bridges/cloudflare",
+        source: "https://developers.cloudflare.com/containers/platform/pricing/",
+        checked: "2026-11-04",
+    },
+    capabilities: [],
+    limits: { maxVcpu: 4, maxMemoryGb: 12 },
+    credentials: [["CLOUDFLARE_SANDBOX_URL", "CLOUDFLARE_SANDBOX_TOKEN"]],
+    docs: "https://developers.cloudflare.com/sandbox/",
+});
+export const CATALOG = [...ENTRIES].sort((a, b) => a.name.localeCompare(b.name));
+/** Cloudflare only rents fixed instance types: https://developers.cloudflare.com/containers/platform/limits/ */
+export const CLOUDFLARE_INSTANCES = [
+    { name: "lite", vcpu: 1 / 16, memoryGb: 0.25 },
+    { name: "basic", vcpu: 1 / 4, memoryGb: 1 },
+    { name: "standard-1", vcpu: 1 / 2, memoryGb: 4 },
+    { name: "standard-2", vcpu: 1, memoryGb: 6 },
+    { name: "standard-3", vcpu: 2, memoryGb: 8 },
+    { name: "standard-4", vcpu: 4, memoryGb: 12 },
+];
+/** Boat's fixed machine sizes and hourly prices: https://docs.boat.dev/machines.md */
+export const BOAT_SIZES = [
+    { type: "small", vcpu: 2, memoryGb: 4, usdHour: 0.018 },
+    { type: "default", vcpu: 4, memoryGb: 8, usdHour: 0.036 },
+    { type: "large", vcpu: 8, memoryGb: 16, usdHour: 0.072 },
+    { type: "xlarge", vcpu: 16, memoryGb: 32, usdHour: 0.2 },
+];
+export function cloudflareInstance(vcpu, memoryGb) {
+    return CLOUDFLARE_INSTANCES.find((t) => t.vcpu >= vcpu && t.memoryGb >= memoryGb) ?? CLOUDFLARE_INSTANCES[CLOUDFLARE_INSTANCES.length - 1];
+}
+export function info(id) {
+    const p = CATALOG.find((c) => c.id === id);
+    if (!p)
+        throw new Error(`unknown provider: ${id}`);
+    return p;
+}
+export const DEFAULT_VCPU = 2;
+export const DEFAULT_MEMORY_GB = 4;
+/** Estimated USD per hour for this spec on this provider (list price, while running). */
+export function hourlyCost(id, spec = {}) {
+    const { pricing } = info(id);
+    const vcpu = spec.vcpu ?? DEFAULT_VCPU;
+    let mem = spec.memoryGb ?? DEFAULT_MEMORY_GB;
+    // Vercel fixes memory at 2 GB per vCPU.
+    if (id === "vercel")
+        mem = Math.max(mem, vcpu * 2);
+    // Blaxel sizes by memory, about 2 GB per core.
+    if (id === "blaxel")
+        mem = Math.max(mem, vcpu * 2);
+    // Boat rents the smallest fixed size that fits.
+    if (id === "boat") {
+        const s = BOAT_SIZES.find((b) => b.vcpu >= vcpu && b.memoryGb >= mem) ?? BOAT_SIZES[BOAT_SIZES.length - 1];
+        return s.usdHour;
+    }
+    // exe.dev bills per vCPU with up to 2 GiB each, so memory beyond that adds vCPUs.
+    if (id === "exedev")
+        return Math.max(Math.ceil(vcpu), Math.ceil(mem / 2)) * pricing.vcpuHour;
+    // Cloudflare bills the instance type that fits, not the exact request.
+    if (id === "cloudflare") {
+        const t = cloudflareInstance(vcpu, mem);
+        return t.vcpu * pricing.vcpuHour + t.memoryGb * pricing.gbHour;
+    }
+    // Morph bills whole MCUs: the larger of vCPUs and 4 GB blocks of memory.
+    if (id === "morph")
+        return Math.max(vcpu, Math.ceil(mem / 4)) * pricing.vcpuHour;
+    return vcpu * pricing.vcpuHour + mem * pricing.gbHour;
+}
+/** Why a provider can't take this spec, or null if it can. */
+export function unfit(id, spec, require = []) {
+    const p = info(id);
+    const needs = new Set(require);
+    if (spec.gpu)
+        needs.add("gpu");
+    for (const c of needs)
+        if (!p.capabilities.includes(c))
+            return `no ${c} support`;
+    if ((spec.vcpu ?? DEFAULT_VCPU) > p.limits.maxVcpu)
+        return `max ${p.limits.maxVcpu} vCPU`;
+    if ((spec.memoryGb ?? DEFAULT_MEMORY_GB) > p.limits.maxMemoryGb)
+        return `max ${p.limits.maxMemoryGb} GB memory`;
+    return null;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

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

package/dist/computers.d.ts

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