@sandboxrouter/sdk 0.0.0-stage → 0.1.0

package/dist/server.js

@@ -0,0 +1,257 @@
+import { createServer } from "node:http";
+import { CATALOG, hourlyCost } from "./catalog.js";
+import { Router } from "./router.js";
+import { ProviderError, RouterError } from "./types.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 function createApp(router = new Router(), token = process.env.SANDBOXROUTER_TOKEN, 
+/** Browser origins allowed to call this server (e.g. the website's Playground). Off by default. */
+corsOrigins = (process.env.SANDBOXROUTER_CORS ?? "").split(",").map((s) => s.trim()).filter(Boolean)) {
+    const live = new Map();
+    const cors = (req, res) => {
+        const origin = req.headers.origin;
+        if (!origin || !(corsOrigins.includes("*") || corsOrigins.includes(origin)))
+            return false;
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+        res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, Accept");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Max-Age", "600");
+        // Chrome asks before a public HTTPS page (the hosted Playground) may call a server on localhost.
+        if (req.headers["access-control-request-private-network"] === "true") {
+            res.setHeader("Access-Control-Allow-Private-Network", "true");
+        }
+        return true;
+    };
+    const handle = async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const parts = url.pathname.split("/").filter(Boolean);
+        const allowed = cors(req, res);
+        if (req.method === "OPTIONS") {
+            res.writeHead(allowed ? 204 : 403);
+            return res.end();
+        }
+        if (url.pathname === "/health")
+            return json(res, 200, { ok: true });
+        if (token && req.headers.authorization !== `Bearer ${token}`)
+            return json(res, 401, { error: "unauthorized" });
+        if (parts[0] !== "v1")
+            return json(res, 404, { error: "not found" });
+        const box = async (id) => live.get(id) ?? router.get(id);
+        // GET /v1/providers
+        if (req.method === "GET" && parts[1] === "providers" && parts.length === 2) {
+            return json(res, 200, {
+                providers: CATALOG.filter((c) => router.registered().includes(c.id)).map((c) => ({
+                    ...c,
+                    configured: router.isConfigured(c.id),
+                    estimatedHourlyUsd: hourlyCost(c.id),
+                })),
+            });
+        }
+        // POST /v1/route
+        if (req.method === "POST" && parts[1] === "route" && parts.length === 2) {
+            const { spec, route } = splitBody(await readJson(req));
+            return json(res, 200, { candidates: router.plan(spec, route) });
+        }
+        if (parts[1] === "computers")
+            return computers(req, res, url, parts);
+        if (parts[1] !== "sandboxes")
+            return json(res, 404, { error: "not found" });
+        // POST /v1/sandboxes
+        if (req.method === "POST" && parts.length === 2) {
+            const { spec, route } = splitBody(await readJson(req));
+            const sbx = await router.create(spec, route);
+            live.set(sbx.id, sbx);
+            return json(res, 201, {
+                id: sbx.id,
+                provider: sbx.provider,
+                estimatedHourlyUsd: sbx.estimatedHourlyUsd,
+                attempts: sbx.attempts,
+            });
+        }
+        const id = parts[2] ? decodeURIComponent(parts[2]) : "";
+        if (!id)
+            return json(res, 404, { error: "not found" });
+        // POST /v1/sandboxes/:id/exec
+        if (req.method === "POST" && parts[3] === "exec") {
+            const body = await readJson(req);
+            if (typeof body.cmd !== "string" || !body.cmd)
+                return json(res, 400, { error: "cmd (string) is required" });
+            const sbx = await box(id);
+            const opts = { cwd: body.cwd, env: body.env, timeoutSeconds: body.timeoutSeconds };
+            if (body.stream !== true)
+                return json(res, 200, await sbx.exec(body.cmd, opts));
+            res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" });
+            const emit = (event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+            try {
+                const r = await sbx.exec(body.cmd, { ...opts, onStdout: (c) => emit("stdout", c), onStderr: (c) => emit("stderr", c) });
+                emit("result", r);
+            }
+            catch (err) {
+                emit("error", { error: err.message });
+            }
+            return res.end();
+        }
+        // POST /v1/sandboxes/:id/pause
+        if (req.method === "POST" && parts[3] === "pause" && parts.length === 4) {
+            await (await box(id)).pause();
+            // Drop the cached handle so the next call reattaches through router.get(), which resumes.
+            live.delete(id);
+            return json(res, 200, { id, paused: true });
+        }
+        // /v1/sandboxes/:id/files?path=
+        if (parts[3] === "files") {
+            const path = url.searchParams.get("path");
+            if (!path)
+                return json(res, 400, { error: "path query parameter is required" });
+            if (req.method === "PUT") {
+                await (await box(id)).writeFile(path, await readRaw(req));
+                return json(res, 200, { ok: true, path });
+            }
+            if (req.method === "GET") {
+                const data = await (await box(id)).readFile(path);
+                res.writeHead(200, { "Content-Type": "application/octet-stream", "Content-Length": data.byteLength });
+                return res.end(Buffer.from(data));
+            }
+        }
+        // DELETE /v1/sandboxes/:id
+        if (req.method === "DELETE" && parts.length === 3) {
+            await (await box(id)).kill();
+            live.delete(id);
+            return json(res, 200, { id, killed: true });
+        }
+        return json(res, 404, { error: "not found" });
+    };
+    const computers = async (req, res, url, parts) => {
+        if (req.method === "POST" && parts.length === 2) {
+            const { provider, ...spec } = await readJson(req);
+            const c = await router.computer(spec, { provider });
+            return json(res, 201, { ...(await c.info()), id: c.id, nativeId: c.nativeId, provider: c.provider });
+        }
+        const id = parts[2] ? decodeURIComponent(parts[2]) : "";
+        if (!id)
+            return json(res, 404, { error: "not found" });
+        const c = await router.getComputer(id);
+        const sub = parts[3];
+        if (req.method === "GET" && !sub)
+            return json(res, 200, { ...(await c.info()), id, nativeId: c.nativeId });
+        if (req.method === "DELETE" && !sub) {
+            await c.delete();
+            return json(res, 200, { id, deleted: true });
+        }
+        if (req.method === "POST" && sub === "actions") {
+            const body = await readJson(req);
+            return json(res, 200, Array.isArray(body.actions) ? { results: await c.actBatch(body.actions) } : await c.act(body));
+        }
+        if (req.method === "GET" && sub === "screenshot") {
+            const format = url.searchParams.get("format") === "jpeg" ? "jpeg" : "png";
+            const img = await c.screenshot({ format, quality: Number(url.searchParams.get("quality")) || undefined });
+            res.writeHead(200, { "Content-Type": `image/${format}`, "Content-Length": img.byteLength });
+            return res.end(Buffer.from(img));
+        }
+        if (req.method === "POST" && sub === "exec") {
+            const body = await readJson(req);
+            if (typeof body.command !== "string" || !body.command)
+                return json(res, 400, { error: "command (string) is required" });
+            return json(res, 200, await c.exec(body.command, body.timeoutSeconds));
+        }
+        if (sub === "files") {
+            const path = url.searchParams.get("path");
+            if (!path)
+                return json(res, 400, { error: "path query parameter is required" });
+            if (req.method === "PUT") {
+                await c.writeFile(path, await readRaw(req));
+                return json(res, 200, { ok: true, path });
+            }
+            if (req.method === "GET") {
+                const data = await c.readFile(path);
+                res.writeHead(200, { "Content-Type": "application/octet-stream", "Content-Length": data.byteLength });
+                return res.end(Buffer.from(data));
+            }
+        }
+        if (req.method === "POST" && sub === "viewer") {
+            const body = await readJson(req);
+            return json(res, 200, await c.viewer(body.mode, { ttlSeconds: body.ttlSeconds, reason: body.reason }));
+        }
+        if (req.method === "POST" && sub === "sleep") {
+            await c.sleep();
+            return json(res, 200, { id, sleeping: true });
+        }
+        return json(res, 404, { error: "not found" });
+    };
+    return createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            const status = err instanceof HttpError ? err.status
+                : err instanceof RouterError ? 502
+                    : err instanceof ProviderError && err.status ? err.status
+                        : 500;
+            json(res, status, { error: err.message, attempts: err.attempts });
+        });
+    });
+}
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const ROUTE_KEYS = ["provider", "strategy", "fallback", "require"];
+function splitBody(body) {
+    const route = {};
+    const spec = {};
+    for (const [k, v] of Object.entries(body))
+        (ROUTE_KEYS.includes(k) ? route : spec)[k] = v;
+    return { spec: spec, route: route };
+}
+const MAX_BODY = 100 * 1024 * 1024;
+async function readRaw(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        size += c.length;
+        if (size > MAX_BODY)
+            throw new HttpError(413, "request body too large");
+        chunks.push(c);
+    }
+    return new Uint8Array(Buffer.concat(chunks));
+}
+async function readJson(req) {
+    const raw = Buffer.from(await readRaw(req)).toString("utf8");
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new HttpError(400, "invalid JSON body");
+    }
+}
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}

package/dist/sse.d.ts

@@ -0,0 +1,6 @@
+export interface SSEEvent {
+    event: string;
+    data: string;
+}
+/** Minimal text/event-stream reader for a fetch Response. */
+export declare function readSSE(res: Response): AsyncGenerator<SSEEvent>;

package/dist/sse.js

@@ -0,0 +1,33 @@
+/** Minimal text/event-stream reader for a fetch Response. */
+export async function* readSSE(res) {
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let event = "message";
+    let data = [];
+    for (;;) {
+        const { done, value } = await reader.read();
+        buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+        if (done)
+            buffer += "\n\n";
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, nl).replace(/\r$/, "");
+            buffer = buffer.slice(nl + 1);
+            if (line === "") {
+                if (data.length)
+                    yield { event, data: data.join("\n") };
+                event = "message";
+                data = [];
+            }
+            else if (line.startsWith("event:"))
+                event = line.slice(6).trim();
+            else if (line.startsWith("data:"))
+                data.push(line.slice(5).replace(/^ /, ""));
+        }
+        if (done)
+            return;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+export type ProviderId = "maritime" | "e2b" | "daytona" | "modal" | "vercel" | "morph" | "sprites" | "blaxel" | "tensorlake" | "runloop";
+/** Things a caller can require of a provider. The router skips providers that lack one. */
+export type Capability = "gpu" | "pause" | "custom-image";
+/** What the caller wants. Every field is optional; providers map it to their own knobs. */
+export interface SandboxSpec {
+    /** vCPUs (default 2). */
+    vcpu?: number;
+    /** Memory in GB (default 4). */
+    memoryGb?: number;
+    /** GPU type, e.g. "T4", "A100". Only providers with the "gpu" capability accept it. */
+    gpu?: string;
+    /** Env vars set for every command. */
+    env?: Record<string, string>;
+    /** Hard lifetime in minutes (default 30). */
+    timeoutMinutes?: number;
+    /**
+     * Provider-specific image/template, keyed by provider, e.g.
+     * { maritime: "python", e2b: "code-interpreter-v1", modal: "python:3.13-slim" }.
+     */
+    image?: Partial<Record<ProviderId, string>>;
+    /** Free-form tags stored on the sandbox where the provider supports it. */
+    metadata?: Record<string, string>;
+}
+export type Strategy = "default" | "cheapest" | "fastest";
+export interface RouteOptions {
+    /** Pin to one provider, or give an ordered list to try. Omit to let the router choose. */
+    provider?: ProviderId | ProviderId[];
+    /** How to order candidates when no explicit list is given. Default: "default" (catalog order). */
+    strategy?: Strategy;
+    /** Try the next candidate if a create fails (default true). */
+    fallback?: boolean;
+    /** Capabilities every candidate must have. */
+    require?: Capability[];
+}
+export interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Per-command timeout in seconds (default 60). */
+    timeoutSeconds?: number;
+    /** Called with each chunk of stdout as it arrives. The full output is still returned. */
+    onStdout?: (chunk: string) => void;
+    /** Called with each chunk of stderr as it arrives. */
+    onStderr?: (chunk: string) => void;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+}
+/** A live sandbox as one provider sees it. Adapters implement this. */
+export interface ProviderSandbox {
+    readonly nativeId: string;
+    exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    kill(): Promise<void>;
+    /** Present only on adapters with the "pause" capability. */
+    pause?(): Promise<void>;
+}
+export interface Provider {
+    readonly id: ProviderId;
+    /** True when the credentials this adapter needs are present. */
+    configured(): boolean;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}
+export interface Attempt {
+    provider: ProviderId;
+    ok: boolean;
+    ms: number;
+    error?: string;
+}
+export declare class RouterError extends Error {
+    readonly attempts: Attempt[];
+    constructor(message: string, attempts?: Attempt[]);
+}
+/** Thrown by adapters for HTTP failures so the router can report status codes. */
+export declare class ProviderError extends Error {
+    readonly provider: ProviderId;
+    readonly status?: number | undefined;
+    constructor(provider: ProviderId, message: string, status?: number | undefined);
+}

package/dist/types.js

@@ -0,0 +1,19 @@
+export class RouterError extends Error {
+    attempts;
+    constructor(message, attempts = []) {
+        super(message);
+        this.attempts = attempts;
+        this.name = "RouterError";
+    }
+}
+/** Thrown by adapters for HTTP failures so the router can report status codes. */
+export class ProviderError extends Error {
+    provider;
+    status;
+    constructor(provider, message, status) {
+        super(`${provider}: ${message}`);
+        this.provider = provider;
+        this.status = status;
+        this.name = "ProviderError";
+    }
+}

package/dist/util.d.ts

@@ -0,0 +1,11 @@
+/** Single-quote a string for POSIX sh. */
+export declare function shq(s: string): string;
+/** Build `cd dir && VAR=x cmd` for providers whose exec API lacks cwd/env. */
+export declare function wrapCommand(cmd: string, opts?: {
+    cwd?: string;
+    env?: Record<string, string>;
+}): string;
+export declare function toBytes(content: string | Uint8Array): Uint8Array;
+export declare function dirname(path: string): string;
+/** Load an optional peer dependency with a helpful error. */
+export declare function optionalImport<T>(pkg: string, provider: string): Promise<T>;

package/dist/util.js

@@ -0,0 +1,37 @@
+/** Single-quote a string for POSIX sh. */
+export function shq(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/** Build `cd dir && VAR=x cmd` for providers whose exec API lacks cwd/env. */
+export function wrapCommand(cmd, opts = {}) {
+    const parts = [];
+    if (opts.cwd)
+        parts.push(`cd ${shq(opts.cwd)} &&`);
+    for (const [k, v] of Object.entries(opts.env ?? {})) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k))
+            throw new Error(`invalid env var name: ${k}`);
+        parts.push(`export ${k}=${shq(v)};`);
+    }
+    parts.push(cmd);
+    return parts.join(" ");
+}
+export function toBytes(content) {
+    return typeof content === "string" ? new TextEncoder().encode(content) : content;
+}
+export function dirname(path) {
+    const i = path.lastIndexOf("/");
+    return i <= 0 ? "/" : path.slice(0, i);
+}
+/** Load an optional peer dependency with a helpful error. */
+export async function optionalImport(pkg, provider) {
+    try {
+        return (await import(pkg));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+            throw new Error(`${provider} needs the "${pkg}" package: npm i ${pkg}`);
+        }
+        throw err;
+    }
+}

package/package.json

@@ -1,6 +1,115 @@
 {
   "name": "@sandboxrouter/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "OpenRouter for sandboxes: one API for Maritime, E2B, Daytona, Modal, Vercel Sandbox, Morph, Fly Sprites, Blaxel, Tensorlake and Runloop, with price/latency routing and automatic fallback.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "sandboxrouter": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build && npm test",
+    "test:py": "python3 -m unittest discover -s python/tests -v",
+    "site:data": "node --import tsx scripts/site-data.ts"
+  },
+  "keywords": [
+    "sandbox",
+    "ai-agents",
+    "code-execution",
+    "router",
+    "maritime",
+    "e2b",
+    "daytona",
+    "modal",
+    "vercel-sandbox",
+    "openrouter",
+    "morph",
+    "fly-sprites",
+    "blaxel",
+    "tensorlake",
+    "runloop"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@daytonaio/sdk": ">=0.200",
+    "@vercel/sandbox": ">=3",
+    "e2b": ">=2",
+    "modal": ">=0.11",
+    "morphcloud": ">=0.0.20",
+    "@fly/sprites": ">=0.2",
+    "@blaxel/core": ">=0.3",
+    "@tensorlakeai/tensorlake": ">=0.5",
+    "@runloop/api-client": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "e2b": {
+      "optional": true
+    },
+    "@daytonaio/sdk": {
+      "optional": true
+    },
+    "modal": {
+      "optional": true
+    },
+    "@vercel/sandbox": {
+      "optional": true
+    },
+    "morphcloud": {
+      "optional": true
+    },
+    "@fly/sprites": {
+      "optional": true
+    },
+    "@blaxel/core": {
+      "optional": true
+    },
+    "@tensorlakeai/tensorlake": {
+      "optional": true
+    },
+    "@runloop/api-client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@blaxel/core": "^0.3.34",
+    "@daytonaio/sdk": "^0.227.3",
+    "@fly/sprites": "^0.2.4",
+    "@runloop/api-client": "^3.0.0",
+    "@tensorlakeai/tensorlake": "^0.5.161",
+    "@types/node": "^26.6.6",
+    "@vercel/sandbox": "^3.9.1",
+    "e2b": "^2.63.0",
+    "modal": "^0.11.1",
+    "morphcloud": "^0.0.20",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^5.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gigialc/sandboxrouter.git"
+  },
+  "homepage": "https://sandboxrouter.vercel.app"
+}