@sandboxrouter/sdk 0.1.0 → 0.2.0

package/dist/providers/northflank.js

@@ -0,0 +1,261 @@
+import { randomBytes } from "node:crypto";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { dirname, optionalImport, shq, toBytes, wrapCommand } from "../util.js";
+const DEFAULT_IMAGE = "ubuntu:22.04";
+/** Northflank's createOptions.expiryTime bounds: 5 minutes to 7 days. */
+const MIN_EXPIRY_SECONDS = 300;
+const MAX_EXPIRY_SECONDS = 604_800;
+const READY_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Northflank sandboxes via `@northflank/js-client`. Auth: NORTHFLANK_API_TOKEN plus
+ * NORTHFLANK_PROJECT_ID (the project every sandbox is created in; its region is fixed at
+ * project creation). A sandbox is a deployment service (microVM-isolated on Northflank cloud)
+ * kept alive by `tail -f /dev/null`; commands run over Northflank's exec API. Default image
+ * ubuntu:22.04; set image.northflank to any public image path (e.g. "python:3.13-slim"). The
+ * image's entrypoint is replaced, and it needs `sh` and `base64` on PATH for file transfer.
+ */
+export class NorthflankProvider {
+    token;
+    projectId;
+    id = "northflank";
+    client;
+    constructor(token = process.env.NORTHFLANK_API_TOKEN, projectId = process.env.NORTHFLANK_PROJECT_ID) {
+        this.token = token;
+        this.projectId = projectId;
+    }
+    configured() {
+        return !!this.token && !!this.projectId;
+    }
+    async northflank() {
+        if (!this.client) {
+            if (!this.token || !this.projectId) {
+                throw new ProviderError("northflank", "NORTHFLANK_API_TOKEN and NORTHFLANK_PROJECT_ID must both be set");
+            }
+            const { ApiClient, ApiClientInMemoryContextProvider } = await optionalImport("@northflank/js-client", "northflank");
+            const ctx = new ApiClientInMemoryContextProvider();
+            ctx.addContext({ name: "sandboxrouter", token: this.token, project: this.projectId });
+            this.client = new ApiClient(ctx);
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const nf = await this.northflank();
+        const projectId = this.projectId;
+        const name = `sbr-${randomBytes(5).toString("hex")}`;
+        const expiry = Math.round((spec.timeoutMinutes ?? 30) * 60);
+        const svc = await call(() => nf.create.service.deployment({
+            parameters: { projectId },
+            data: {
+                name,
+                description: "sandboxrouter sandbox",
+                billing: { deploymentPlan: plan(spec.vcpu ?? DEFAULT_VCPU, spec.memoryGb ?? DEFAULT_MEMORY_GB) },
+                deployment: {
+                    instances: 1,
+                    external: { imagePath: spec.image?.northflank ?? DEFAULT_IMAGE },
+                    docker: { configType: "customEntrypointCustomCommand", customEntrypoint: "/bin/sh", customCommand: "-c 'tail -f /dev/null'" },
+                },
+                runtimeEnvironment: spec.env,
+                // At expiry Northflank pauses the service (compute billing stops) and schedules its deletion.
+                createOptions: { expiryTime: Math.min(MAX_EXPIRY_SECONDS, Math.max(MIN_EXPIRY_SECONDS, expiry)) },
+            },
+        }));
+        const box = new NorthflankBox(nf, projectId, svc?.id ?? name);
+        try {
+            await box.waitReady();
+        }
+        catch (err) {
+            await box.kill().catch(() => { });
+            throw err;
+        }
+        return box;
+    }
+    /** Reattach to a running sandbox by service id. */
+    async connect(nativeId) {
+        const box = new NorthflankBox(await this.northflank(), this.projectId, nativeId);
+        const { expiredAt } = await box.info();
+        if (expiredAt)
+            throw new ProviderError("northflank", `sandbox ${nativeId} expired at ${expiredAt}`);
+        await box.waitReady();
+        return box;
+    }
+}
+class NorthflankBox {
+    nf;
+    projectId;
+    nativeId;
+    constructor(nf, projectId, nativeId) {
+        this.nf = nf;
+        this.projectId = projectId;
+        this.nativeId = nativeId;
+    }
+    get params() {
+        return { projectId: this.projectId, serviceId: this.nativeId };
+    }
+    /** The deployment-service fields this adapter reads (GetServiceResult is a union over service types). */
+    async info() {
+        return (await call(() => this.nf.get.service({ parameters: this.params })));
+    }
+    /**
+     * Poll until the deployment is COMPLETED (container running), then until exec is accepted:
+     * the exec endpoint can refuse briefly while the instance comes up.
+     */
+    async waitReady() {
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        for (;;) {
+            const status = (await this.info())?.status?.deployment?.status;
+            if (status === "FAILED")
+                throw new ProviderError("northflank", `sandbox ${this.nativeId} failed to deploy`);
+            if (status === "COMPLETED")
+                break;
+            if (Date.now() > deadline)
+                throw new ProviderError("northflank", `sandbox ${this.nativeId} not ready after ${READY_TIMEOUT_MS / 1000}s`);
+            await sleep(1000);
+        }
+        for (;;) {
+            try {
+                const r = await this.run(["/bin/sh", "-c", "true"], 30_000);
+                if (r.exitCode === 0)
+                    return;
+            }
+            catch (err) {
+                if (Date.now() > deadline)
+                    throw err;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError("northflank", `sandbox ${this.nativeId} not accepting exec`);
+            await sleep(1000);
+        }
+    }
+    /**
+     * Exec has no cwd/env/timeout, so cwd/env are wrapped into the command, the command runs
+     * under `timeout` when the image has it, and the deadline is also enforced here.
+     */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const secs = opts.timeoutSeconds ?? 60;
+        const script = shq(wrapCommand(cmd, { cwd: opts.cwd, env: opts.env }));
+        const guarded = `if command -v timeout >/dev/null 2>&1; then exec timeout ${secs} /bin/sh -c ${script}; else exec /bin/sh -c ${script}; fi`;
+        const r = await this.run(["/bin/sh", "-c", guarded], secs * 1000 + 10_000, opts);
+        const durationMs = Date.now() - t0;
+        if (durationMs >= secs * 1000 && [124, 137, 143].includes(r.exitCode)) {
+            throw new ProviderError("northflank", `command timed out after ${secs}s`);
+        }
+        return { ...r, durationMs };
+    }
+    /** Stream base64 over stdin and decode in the sandbox. */
+    async writeFile(path, content) {
+        const b64 = Buffer.from(toBytes(content)).toString("base64");
+        const r = await this.run(["/bin/sh", "-c", `mkdir -p ${shq(dirname(path))} && base64 -d > ${shq(path)}`], 120_000 + b64.length / 100, {}, b64);
+        if (r.exitCode !== 0)
+            throw new ProviderError("northflank", `write ${path} failed: ${r.stderr.trim() || `exit ${r.exitCode}`}`);
+    }
+    async readFile(path) {
+        const r = await this.run(["/bin/sh", "-c", `base64 < ${shq(path)}`], 120_000);
+        if (r.exitCode !== 0)
+            throw new ProviderError("northflank", `read ${path} failed: ${r.stderr.trim() || `exit ${r.exitCode}`}`);
+        return new Uint8Array(Buffer.from(r.stdout, "base64"));
+    }
+    async kill() {
+        await call(() => this.nf.delete.service({ parameters: this.params }));
+    }
+    /** One exec session: optional stdin, streamed stdout/stderr, exit code. */
+    async run(command, limitMs, opts = {}, stdin) {
+        const t0 = Date.now();
+        let session;
+        try {
+            session = await this.nf.exec.execServiceSession(this.params, { command, shell: "none", tty: false });
+        }
+        catch (err) {
+            throw new ProviderError("northflank", err?.message ?? String(err), err?.status);
+        }
+        let stdout = "";
+        let stderr = "";
+        session.stdOut.setEncoding("utf8");
+        session.stdErr.setEncoding("utf8");
+        session.stdOut.on("data", (c) => {
+            stdout += c;
+            opts.onStdout?.(c);
+        });
+        session.stdErr.on("data", (c) => {
+            stderr += c;
+            opts.onStderr?.(c);
+        });
+        const failed = new Promise((_, reject) => session.on("error", (e) => reject(e)));
+        failed.catch(() => { });
+        // Send stdin (if any) and close it so commands that read stdin don't hang.
+        const CHUNK = 64 * 1024;
+        if (stdin)
+            for (let i = 0; i < stdin.length; i += CHUNK)
+                session.stdIn.write(stdin.slice(i, i + CHUNK));
+        session.stdIn.end();
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("timeout"), limitMs);
+            timer.unref();
+        });
+        try {
+            const res = await Promise.race([session.waitForCommandResult(), failed, timedOut]);
+            if (res === "timeout")
+                throw new ProviderError("northflank", `command timed out after ${Math.round((Date.now() - t0) / 1000)}s`);
+            return { exitCode: typeof res.exitCode === "number" ? res.exitCode : -1, stdout, stderr };
+        }
+        catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            throw new ProviderError("northflank", err?.message ?? String(err), err?.status);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/** Unwrap a Northflank API response, turning an `error` body into a ProviderError with its HTTP status. */
+async function call(fn) {
+    let res;
+    try {
+        res = await fn();
+    }
+    catch (err) {
+        throw new ProviderError("northflank", err?.message ?? String(err), err?.status);
+    }
+    if (res.error)
+        throw new ProviderError("northflank", res.error.message || `HTTP ${res.error.status}`, res.error.status);
+    return res.data;
+}
+/**
+ * Northflank deployment plans (vCPU, GB), from
+ * https://northflank.com/docs/v1/application/billing/resource-plans-and-quotas. Northflank bills
+ * per vCPU-hour and GB-hour, so the cheapest plan that fits is the one with the least of both.
+ */
+const PLANS = [
+    ["nf-compute-10", 0.1, 0.25],
+    ["nf-compute-20", 0.2, 0.5],
+    ["nf-compute-50", 0.5, 1],
+    ["nf-compute-100-1", 1, 1],
+    ["nf-compute-100-2", 1, 2],
+    ["nf-compute-100-4", 1, 4],
+    ["nf-compute-200", 2, 4],
+    ["nf-compute-200-8", 2, 8],
+    ["nf-compute-200-16", 2, 16],
+    ["nf-compute-400", 4, 8],
+    ["nf-compute-400-16", 4, 16],
+    ["nf-compute-800-8", 8, 8],
+    ["nf-compute-800-16", 8, 16],
+    ["nf-compute-800-24", 8, 24],
+    ["nf-compute-800-32", 8, 32],
+    ["nf-compute-800-40", 8, 40],
+    ["nf-compute-1200-24", 12, 24],
+    ["nf-compute-1600-32", 16, 32],
+    ["nf-compute-2000-40", 20, 40],
+    ["nf-compute-32-131072", 32, 128],
+];
+/** Smallest plan with at least the requested vCPU and memory; the largest plan if none fits. */
+function plan(vcpu, memoryGb) {
+    const cost = ([, c, g]) => c * 0.01667 + g * 0.00833;
+    const fits = PLANS.filter(([, c, g]) => c >= vcpu && g >= memoryGb).sort((a, b) => cost(a) - cost(b));
+    return (fits[0] ?? PLANS[PLANS.length - 1])[0];
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms).unref());
+}

package/dist/router.js

@@ -11,6 +11,12 @@ 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 { DockerProvider } from "./providers/docker.js";
+import { HopxProvider } from "./providers/hopx.js";
+import { CloudflareProvider } from "./providers/cloudflare.js";
+import { NorthflankProvider } from "./providers/northflank.js";
+import { BoatProvider } from "./providers/boat.js";
+import { ExeDevProvider } from "./providers/exedev.js";
 import { RouterError, } from "./types.js";
 export function defaultProviders() {
     return [
@@ -24,6 +30,12 @@ export function defaultProviders() {
         new BlaxelProvider(),
         new TensorlakeProvider(),
         new RunloopProvider(),
+        new HopxProvider(),
+        new CloudflareProvider(),
+        new NorthflankProvider(),
+        new BoatProvider(),
+        new ExeDevProvider(),
+        new DockerProvider(),
     ];
 }
 export class Router {
@@ -50,7 +62,9 @@ export class Router {
     /** 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));
+        // Local providers (Docker) are never picked automatically: they always "cost" $0 and isolate
+        // less than a cloud micro-VM. Name them explicitly to use them.
+        const ids = explicit ?? CATALOG.filter((c) => !c.local && this.providers.has(c.id)).map((c) => c.id);
         const bench = route.strategy === "fastest" ? loadBench(this.benchFile) : {};
         const list = ids.map((id) => {
             const p = this.providers.get(id);
@@ -65,11 +79,16 @@ export class Router {
                 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));
+        // Neutral by construction: price (or measured speed) decides, ties break alphabetically by id.
+        // An explicit provider list keeps the caller's order.
+        if (!explicit) {
+            const byPrice = (a, b) => a.estimatedHourlyUsd - b.estimatedHourlyUsd || a.provider.localeCompare(b.provider);
+            if (route.strategy === "fastest") {
+                list.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity) || byPrice(a, b));
+            }
+            else {
+                list.sort(byPrice);
+            }
         }
         return list;
     }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type ProviderId = "maritime" | "e2b" | "daytona" | "modal" | "vercel" | "morph" | "sprites" | "blaxel" | "tensorlake" | "runloop";
+export type ProviderId = "maritime" | "e2b" | "daytona" | "modal" | "vercel" | "morph" | "sprites" | "blaxel" | "tensorlake" | "runloop" | "hopx" | "cloudflare" | "northflank" | "boat" | "exedev" | "docker";
 /** 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. */
@@ -21,11 +21,15 @@ export interface SandboxSpec {
     /** Free-form tags stored on the sandbox where the provider supports it. */
     metadata?: Record<string, string>;
 }
+/**
+ * "cheapest" (and "default", the same thing): lowest list price for the spec, ties alphabetical.
+ * "fastest": lowest median cold start you measured with `bench`, then cheapest.
+ */
 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). */
+    /** How to order candidates when no explicit list is given. Default: cheapest. */
     strategy?: Strategy;
     /** Try the next candidate if a create fails (default true). */
     fallback?: boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sandboxrouter/sdk",
-  "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.",
+  "version": "0.2.0",
+  "description": "One API for every sandbox provider: route AI agents' code by price, speed or capability, with automatic fallback. Free and open source.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,36 +29,42 @@
     "site:data": "node --import tsx scripts/site-data.ts"
   },
   "keywords": [
-    "sandbox",
     "ai-agents",
+    "blaxel",
+    "cloudflare",
     "code-execution",
-    "router",
-    "maritime",
-    "e2b",
     "daytona",
+    "docker",
+    "e2b",
+    "fly-sprites",
+    "hopx",
+    "maritime",
     "modal",
-    "vercel-sandbox",
-    "openrouter",
     "morph",
-    "fly-sprites",
-    "blaxel",
+    "northflank",
+    "openrouter",
+    "router",
+    "runloop",
+    "sandbox",
     "tensorlake",
-    "runloop"
+    "vercel-sandbox"
   ],
   "license": "MIT",
   "engines": {
     "node": ">=20"
   },
   "peerDependencies": {
+    "@blaxel/core": ">=0.3",
     "@daytonaio/sdk": ">=0.200",
+    "@fly/sprites": ">=0.2",
+    "@runloop/api-client": ">=3",
+    "@tensorlakeai/tensorlake": ">=0.5",
     "@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"
+    "@hopx-ai/sdk": ">=0.5",
+    "@northflank/js-client": ">=0.12"
   },
   "peerDependenciesMeta": {
     "e2b": {
@@ -87,12 +93,20 @@
     },
     "@runloop/api-client": {
       "optional": true
+    },
+    "@hopx-ai/sdk": {
+      "optional": true
+    },
+    "@northflank/js-client": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@blaxel/core": "^0.3.34",
     "@daytonaio/sdk": "^0.227.3",
     "@fly/sprites": "^0.2.4",
+    "@hopx-ai/sdk": "^0.5.1",
+    "@northflank/js-client": "^0.12.0",
     "@runloop/api-client": "^3.0.0",
     "@tensorlakeai/tensorlake": "^0.5.161",
     "@types/node": "^26.6.6",