@sandboxrouter/sdk 0.0.0-stage → 0.1.0

package/dist/providers/tensorlake.js

@@ -0,0 +1,192 @@
+import { randomUUID } from "node:crypto";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { optionalImport, shq, toBytes, wrapCommand } from "../util.js";
+/** Tensorlake has no sandbox-level env, so spec.env lives in this file and every exec sources it. */
+const ENV_FILE = "/tmp/.sandboxrouter.env";
+/**
+ * Tensorlake sandboxes via `@tensorlakeai/tensorlake`. Auth: TENSORLAKE_API_KEY.
+ * Set image.tensorlake to start from your own sandbox image; spec.gpu maps to a GPU model.
+ */
+export class TensorlakeProvider {
+    apiKey;
+    id = "tensorlake";
+    constructor(apiKey = process.env.TENSORLAKE_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async create(spec) {
+        const { Sandbox } = await optionalImport("@tensorlakeai/tensorlake", "tensorlake");
+        const image = spec.image?.tensorlake;
+        let sbx;
+        try {
+            sbx = await Sandbox.create({
+                apiKey: this.apiKey,
+                image,
+                cpus: spec.vcpu ?? DEFAULT_VCPU,
+                memoryMb: Math.round((spec.memoryGb ?? DEFAULT_MEMORY_GB) * 1024),
+                timeoutSecs: Math.round((spec.timeoutMinutes ?? 30) * 60),
+                ...(spec.gpu ? { gpuModel: spec.gpu } : {}),
+            });
+        }
+        catch (err) {
+            throw fail(err);
+        }
+        const box = new TensorlakeBox(sbx);
+        if (spec.env && Object.keys(spec.env).length > 0) {
+            try {
+                await box.writeFile(ENV_FILE, wrapCommand(":", { env: spec.env }) + "\n");
+            }
+            catch (err) {
+                await sbx.terminate().catch(() => { });
+                throw err;
+            }
+        }
+        return box;
+    }
+    /** Reattach; a suspended sandbox is resumed. */
+    async connect(nativeId) {
+        const { Sandbox } = await optionalImport("@tensorlakeai/tensorlake", "tensorlake");
+        try {
+            const sbx = await Sandbox.connect({ sandboxId: nativeId, apiKey: this.apiKey });
+            let status = await sbx.status();
+            // resume() is rejected while a suspend is still in flight.
+            for (let i = 0; status === "suspending" && i < 300; i++) {
+                await sleep(1000);
+                status = await sbx.status();
+            }
+            if (status === "suspended")
+                await sbx.resume();
+            return new TensorlakeBox(sbx);
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+}
+class TensorlakeBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.sandboxId;
+    }
+    /** `sh -c` so cmd is a shell line; spec.env is sourced first so per-call env wins. */
+    shellLine(cmd, opts) {
+        return `[ -f ${shq(ENV_FILE)} ] && . ${shq(ENV_FILE)}; ${wrapCommand(cmd, { cwd: opts.cwd, env: opts.env })}`;
+    }
+    async exec(cmd, opts = {}) {
+        if (opts.onStdout || opts.onStderr)
+            return this.execStreaming(cmd, opts);
+        const t0 = Date.now();
+        const limit = opts.timeoutSeconds ?? 60;
+        try {
+            const r = await this.sbx.run("/bin/sh", { args: ["-c", this.shellLine(cmd, opts)], timeout: limit });
+            if (r.timedOut)
+                throw new ProviderError("tensorlake", `command timed out after ${limit}s`);
+            // A nonzero exit is a result; the SDK only throws for transport/API failures.
+            return { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    /** Start the process, then follow its combined output stream until it exits. */
+    async execStreaming(cmd, opts) {
+        const t0 = Date.now();
+        const limit = (opts.timeoutSeconds ?? 60) * 1000;
+        const abort = new AbortController();
+        const stdout = [];
+        const stderr = [];
+        let pid;
+        const timer = setTimeout(() => abort.abort(), limit);
+        timer.unref();
+        try {
+            ({ pid } = await this.sbx.startProcess("/bin/sh", { args: ["-c", this.shellLine(cmd, opts)] }));
+            try {
+                for await (const ev of this.sbx.followOutput(pid, { signal: abort.signal })) {
+                    if (ev.stream === "stderr") {
+                        stderr.push(ev.line);
+                        opts.onStderr?.(ev.line + "\n");
+                    }
+                    else {
+                        stdout.push(ev.line);
+                        opts.onStdout?.(ev.line + "\n");
+                    }
+                }
+            }
+            catch (err) {
+                if (!abort.signal.aborted)
+                    throw err;
+            }
+            if (abort.signal.aborted) {
+                await this.sbx.killProcess(pid).catch(() => { });
+                throw new ProviderError("tensorlake", `command timed out after ${limit / 1000}s`);
+            }
+            // The stream can close a moment before the daemon records the exit.
+            let info = await this.sbx.getProcess(pid);
+            for (let i = 0; info.status === "running" && i < 20; i++) {
+                await sleep(250);
+                info = await this.sbx.getProcess(pid);
+            }
+            const exitCode = info.exitCode ?? (info.signal != null ? -info.signal : -1);
+            return { exitCode, stdout: stdout.join("\n"), stderr: stderr.join("\n"), durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw fail(err);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async writeFile(path, content) {
+        try {
+            await this.sbx.writeFile(path, toBytes(content));
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    async readFile(path) {
+        try {
+            return new Uint8Array(await this.sbx.readFile(path));
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+    /**
+     * Suspend, keeping memory and disk. Only named sandboxes can suspend, so an unnamed one is
+     * named first. router.get() resumes it.
+     */
+    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) {
+            throw fail(err);
+        }
+    }
+    async kill() {
+        try {
+            await this.sbx.terminate();
+        }
+        catch (err) {
+            throw fail(err);
+        }
+    }
+}
+function fail(err) {
+    if (err instanceof ProviderError)
+        return err;
+    const status = typeof err?.statusCode === "number" ? err.statusCode : undefined;
+    return new ProviderError("tensorlake", err?.message ?? String(err), status);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms).unref());
+}

package/dist/providers/vercel.d.ts

@@ -0,0 +1,12 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Vercel Sandbox via `@vercel/sandbox`. Auth: VERCEL_OIDC_TOKEN (from `vercel env pull`), or
+ * VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID. Memory is fixed at 2 GB per vCPU.
+ */
+export declare class VercelProvider implements Provider {
+    readonly id: "vercel";
+    configured(): boolean;
+    private creds;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/vercel.js

@@ -0,0 +1,87 @@
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes, wrapCommand } from "../util.js";
+/**
+ * Vercel Sandbox via `@vercel/sandbox`. Auth: VERCEL_OIDC_TOKEN (from `vercel env pull`), or
+ * VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID. Memory is fixed at 2 GB per vCPU.
+ */
+export class VercelProvider {
+    id = "vercel";
+    configured() {
+        const e = process.env;
+        return !!e.VERCEL_OIDC_TOKEN || (!!e.VERCEL_TOKEN && !!e.VERCEL_TEAM_ID && !!e.VERCEL_PROJECT_ID);
+    }
+    creds() {
+        const e = process.env;
+        return e.VERCEL_TOKEN && e.VERCEL_TEAM_ID && e.VERCEL_PROJECT_ID
+            ? { token: e.VERCEL_TOKEN, teamId: e.VERCEL_TEAM_ID, projectId: e.VERCEL_PROJECT_ID }
+            : {};
+    }
+    async create(spec) {
+        const { Sandbox } = await optionalImport("@vercel/sandbox", "vercel");
+        const vcpus = Math.min(8, Math.max(spec.vcpu ?? DEFAULT_VCPU, Math.ceil((spec.memoryGb ?? DEFAULT_MEMORY_GB) / 2)));
+        const sbx = await Sandbox.create({
+            ...this.creds(),
+            runtime: spec.image?.vercel ?? "node22",
+            timeout: (spec.timeoutMinutes ?? 30) * 60_000,
+            resources: { vcpus },
+            env: spec.env,
+            tags: spec.metadata,
+        });
+        return new VercelBox(sbx);
+    }
+    async connect(nativeId) {
+        const { Sandbox } = await optionalImport("@vercel/sandbox", "vercel");
+        return new VercelBox(await Sandbox.get({ ...this.creds(), name: nativeId }));
+    }
+}
+class VercelBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.name;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const signal = AbortSignal.timeout((opts.timeoutSeconds ?? 60) * 1000);
+        try {
+            const params = { cmd: "sh", args: ["-c", wrapCommand(cmd)], cwd: opts.cwd, env: opts.env, signal };
+            if (opts.onStdout || opts.onStderr) {
+                const running = await this.sbx.runCommand({ ...params, detached: true });
+                let stdout = "";
+                let stderr = "";
+                for await (const line of running.logs({ signal })) {
+                    if (line.stream === "stdout") {
+                        stdout += line.data;
+                        opts.onStdout?.(line.data);
+                    }
+                    else {
+                        stderr += line.data;
+                        opts.onStderr?.(line.data);
+                    }
+                }
+                const done = await running.wait({ signal });
+                return { exitCode: done.exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+            }
+            const r = await this.sbx.runCommand(params);
+            const [stdout, stderr] = await Promise.all([r.stdout(), r.stderr()]);
+            return { exitCode: r.exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw new ProviderError("vercel", err?.message ?? String(err));
+        }
+    }
+    async writeFile(path, content) {
+        await this.sbx.writeFiles([{ path, content: Buffer.from(toBytes(content)) }]);
+    }
+    async readFile(path) {
+        const buf = await this.sbx.readFileToBuffer({ path });
+        if (!buf)
+            throw new ProviderError("vercel", `no such file: ${path}`);
+        return new Uint8Array(buf);
+    }
+    async kill() {
+        await this.sbx.stop();
+    }
+}

package/dist/router.d.ts

@@ -0,0 +1,65 @@
+import { RoutedComputer, type ComputerProvider, type ComputerSpec } from "./computers.js";
+import { type Attempt, type ExecOptions, type ExecResult, type Provider, type ProviderId, type ProviderSandbox, type RouteOptions, type SandboxSpec } from "./types.js";
+export interface Candidate {
+    provider: ProviderId;
+    estimatedHourlyUsd: number;
+    medianCreateMs?: number;
+    /** Why this provider won't be tried, if it won't. */
+    skip?: string;
+}
+export interface RouterOptions {
+    /** Replace the built-in adapters (tests, custom providers). */
+    providers?: Provider[];
+    /** Path of the bench results file used by strategy "fastest". */
+    benchFile?: string;
+}
+export declare function defaultProviders(): Provider[];
+export declare class Router {
+    private providers;
+    private benchFile?;
+    constructor(opts?: RouterOptions);
+    /** Registered and has credentials. False for providers this router doesn't know. */
+    isConfigured(id: ProviderId): boolean;
+    /** Catalog ids this router has an adapter for, in catalog order. */
+    registered(): ProviderId[];
+    provider(id: ProviderId): Provider;
+    /** The ordered list of providers a create would try, with the reason any are skipped. */
+    plan(spec?: SandboxSpec, route?: RouteOptions): Candidate[];
+    /** Start a sandbox on the best available provider, falling back down the list on failure. */
+    create(spec?: SandboxSpec, route?: RouteOptions): Promise<RoutedSandbox>;
+    /** Providers that also sell computers (desktops/phones). */
+    computerProviders(): ComputerProvider[];
+    /** Get or create a desktop/phone. With `externalUserId`, the same id returns the same computer. */
+    computer(spec?: ComputerSpec, opts?: {
+        provider?: ProviderId | ProviderId[];
+    }): Promise<RoutedComputer>;
+    getComputer(id: string): Promise<RoutedComputer>;
+    /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
+    get(id: string): Promise<RoutedSandbox>;
+}
+export declare class RoutedSandbox {
+    readonly provider: ProviderId;
+    private box;
+    /** Every create attempt, including failed fallbacks. */
+    readonly attempts: Attempt[];
+    readonly estimatedHourlyUsd: number;
+    /** Stable id across processes: `provider:nativeId`. */
+    readonly id: string;
+    constructor(provider: ProviderId, box: ProviderSandbox, 
+    /** Every create attempt, including failed fallbacks. */
+    attempts: Attempt[], estimatedHourlyUsd: number);
+    get nativeId(): string;
+    exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    readText(path: string): Promise<string>;
+    kill(): Promise<void>;
+    /** Pause, keeping the disk. Resume with router.get(id) or, on Maritime, any call. */
+    pause(): Promise<void>;
+    get canPause(): boolean;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare function parseId(id: string): {
+    provider: ProviderId;
+    nativeId: string;
+};

package/dist/router.js

@@ -0,0 +1,180 @@
+import { CATALOG, hourlyCost, unfit } from "./catalog.js";
+import { RoutedComputer, createComputer } from "./computers.js";
+import { loadBench, median } from "./bench-store.js";
+import { DaytonaProvider } from "./providers/daytona.js";
+import { E2BProvider } from "./providers/e2b.js";
+import { MaritimeProvider } from "./providers/maritime.js";
+import { ModalProvider } from "./providers/modal.js";
+import { VercelProvider } from "./providers/vercel.js";
+import { MorphProvider } from "./providers/morph.js";
+import { SpritesProvider } from "./providers/sprites.js";
+import { BlaxelProvider } from "./providers/blaxel.js";
+import { TensorlakeProvider } from "./providers/tensorlake.js";
+import { RunloopProvider } from "./providers/runloop.js";
+import { RouterError, } from "./types.js";
+export function defaultProviders() {
+    return [
+        new MaritimeProvider(),
+        new E2BProvider(),
+        new DaytonaProvider(),
+        new ModalProvider(),
+        new VercelProvider(),
+        new MorphProvider(),
+        new SpritesProvider(),
+        new BlaxelProvider(),
+        new TensorlakeProvider(),
+        new RunloopProvider(),
+    ];
+}
+export class Router {
+    providers;
+    benchFile;
+    constructor(opts = {}) {
+        this.providers = new Map((opts.providers ?? defaultProviders()).map((p) => [p.id, p]));
+        this.benchFile = opts.benchFile;
+    }
+    /** Registered and has credentials. False for providers this router doesn't know. */
+    isConfigured(id) {
+        return this.providers.get(id)?.configured() ?? false;
+    }
+    /** Catalog ids this router has an adapter for, in catalog order. */
+    registered() {
+        return CATALOG.map((c) => c.id).filter((id) => this.providers.has(id));
+    }
+    provider(id) {
+        const p = this.providers.get(id);
+        if (!p)
+            throw new RouterError(`unknown provider: ${id}`);
+        return p;
+    }
+    /** The ordered list of providers a create would try, with the reason any are skipped. */
+    plan(spec = {}, route = {}) {
+        const explicit = route.provider ? [].concat(route.provider) : null;
+        const ids = explicit ?? CATALOG.map((c) => c.id).filter((id) => this.providers.has(id));
+        const bench = route.strategy === "fastest" ? loadBench(this.benchFile) : {};
+        const list = ids.map((id) => {
+            const p = this.providers.get(id);
+            const c = {
+                provider: id,
+                estimatedHourlyUsd: round(hourlyCost(id, spec)),
+                medianCreateMs: median(bench[id]?.createMs),
+            };
+            if (!p)
+                c.skip = "unknown provider";
+            else
+                c.skip = unfit(id, spec, route.require) ?? (p.configured() ? undefined : "not configured");
+            return c;
+        });
+        if (!explicit && route.strategy === "cheapest") {
+            list.sort((a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd);
+        }
+        else if (!explicit && route.strategy === "fastest") {
+            list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity));
+        }
+        return list;
+    }
+    /** Start a sandbox on the best available provider, falling back down the list on failure. */
+    async create(spec = {}, route = {}) {
+        const plan = this.plan(spec, route);
+        const usable = plan.filter((c) => !c.skip);
+        if (usable.length === 0) {
+            const why = plan.map((c) => `${c.provider} (${c.skip})`).join(", ");
+            throw new RouterError(`no provider can take this sandbox: ${why || "none registered"}`);
+        }
+        const attempts = [];
+        const tries = route.fallback === false ? usable.slice(0, 1) : usable;
+        for (const c of tries) {
+            const t0 = Date.now();
+            try {
+                const box = await this.provider(c.provider).create(spec);
+                attempts.push({ provider: c.provider, ok: true, ms: Date.now() - t0 });
+                return new RoutedSandbox(c.provider, box, attempts, c.estimatedHourlyUsd);
+            }
+            catch (err) {
+                attempts.push({ provider: c.provider, ok: false, ms: Date.now() - t0, error: err.message });
+            }
+        }
+        throw new RouterError(`all providers failed: ${attempts.map((a) => `${a.provider}: ${a.error}`).join(" | ")}`, attempts);
+    }
+    /** Providers that also sell computers (desktops/phones). */
+    computerProviders() {
+        return [...this.providers.values()].filter((p) => "createComputer" in p);
+    }
+    /** Get or create a desktop/phone. With `externalUserId`, the same id returns the same computer. */
+    computer(spec = {}, opts = {}) {
+        const prefer = opts.provider ? [].concat(opts.provider) : undefined;
+        return createComputer(this.computerProviders(), spec, prefer);
+    }
+    async getComputer(id) {
+        const { provider, nativeId } = parseId(id);
+        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(nativeId));
+    }
+    /** Reattach to a sandbox by its routed id (`provider:nativeId`). */
+    async get(id) {
+        const { provider, nativeId } = parseId(id);
+        const box = await this.provider(provider).connect(nativeId);
+        return new RoutedSandbox(provider, box, [], round(hourlyCost(provider)));
+    }
+}
+export class RoutedSandbox {
+    provider;
+    box;
+    attempts;
+    estimatedHourlyUsd;
+    /** Stable id across processes: `provider:nativeId`. */
+    id;
+    constructor(provider, box, 
+    /** Every create attempt, including failed fallbacks. */
+    attempts, estimatedHourlyUsd) {
+        this.provider = provider;
+        this.box = box;
+        this.attempts = attempts;
+        this.estimatedHourlyUsd = estimatedHourlyUsd;
+        this.id = `${provider}:${box.nativeId}`;
+    }
+    get nativeId() {
+        return this.box.nativeId;
+    }
+    exec(cmd, opts) {
+        return this.box.exec(cmd, opts);
+    }
+    writeFile(path, content) {
+        return this.box.writeFile(path, content);
+    }
+    readFile(path) {
+        return this.box.readFile(path);
+    }
+    async readText(path) {
+        return new TextDecoder().decode(await this.box.readFile(path));
+    }
+    kill() {
+        return this.box.kill();
+    }
+    /** Pause, keeping the disk. Resume with router.get(id) or, on Maritime, any call. */
+    async pause() {
+        if (!this.box.pause)
+            throw new RouterError(`${this.provider} does not support pause; create with require: ["pause"]`);
+        await this.box.pause();
+    }
+    get canPause() {
+        return typeof this.box.pause === "function";
+    }
+    async [Symbol.asyncDispose]() {
+        await this.kill();
+    }
+}
+export function parseId(id) {
+    const i = id.indexOf(":");
+    if (i <= 0)
+        throw new RouterError(`bad sandbox id "${id}": expected provider:id`);
+    const provider = id.slice(0, i);
+    if (!CATALOG.some((c) => c.id === provider))
+        throw new RouterError(`unknown provider in id: ${provider}`);
+    return { provider, nativeId: id.slice(i + 1) };
+}
+function round(n) {
+    return Math.round(n * 10000) / 10000;
+}

package/dist/server.d.ts

@@ -0,0 +1,31 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { Router } from "./router.js";
+/**
+ * OpenRouter-style HTTP API in front of every provider. One token for your clients; provider keys
+ * stay on this host.
+ *
+ *   GET    /v1/providers
+ *   POST   /v1/route                      dry run: which providers would be tried, in order
+ *   POST   /v1/sandboxes                  { vcpu, memoryGb, ..., provider, strategy, fallback, require }
+ *   POST   /v1/sandboxes/:id/exec         { cmd, cwd, env, timeoutSeconds, stream }
+ *          stream: true answers text/event-stream: `stdout`/`stderr` events (JSON string chunks),
+ *          then one `result` event (the ExecResult), or an `error` event
+ *   POST   /v1/sandboxes/:id/pause        keeps the disk; the next call resumes it
+ *   PUT    /v1/sandboxes/:id/files?path=  raw body
+ *   GET    /v1/sandboxes/:id/files?path=  raw body
+ *   DELETE /v1/sandboxes/:id
+ *
+ *   POST   /v1/computers                  { os, externalUserId, name, screen, arch, provider }
+ *   GET    /v1/computers/:id
+ *   POST   /v1/computers/:id/actions      one action, or { actions: [...] }
+ *   GET    /v1/computers/:id/screenshot   image bytes
+ *   POST   /v1/computers/:id/exec         { command, timeoutSeconds }
+ *   PUT    /v1/computers/:id/files?path=  raw body
+ *   GET    /v1/computers/:id/files?path=  raw body
+ *   POST   /v1/computers/:id/viewer       { mode: "watch" | "control", ttlSeconds, reason }
+ *   POST   /v1/computers/:id/sleep
+ *   DELETE /v1/computers/:id
+ */
+export declare function createApp(router?: Router, token?: string | undefined, 
+/** Browser origins allowed to call this server (e.g. the website's Playground). Off by default. */
+corsOrigins?: string[]): import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;