@sandboxrouter/sdk 0.2.0 → 0.3.1

package/dist/providers/northflank.js

@@ -1,7 +1,7 @@
 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";
+import { DEFAULT_EXEC_TIMEOUT_S, dirname, guardTimeout, killedByTimeout, optionalImport, shq, timeoutError, 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;
@@ -128,19 +128,17 @@ class NorthflankBox {
         }
     }
     /**
-     * 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.
+     * Exec has no cwd/env/timeout, so cwd/env are wrapped into the command, the sandbox kills the
+     * command at the deadline (`guardTimeout`), and this side gives up a little later as a fallback.
      */
     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 secs = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
+        const guarded = guardTimeout(wrapCommand(cmd, { cwd: opts.cwd, env: opts.env }), secs);
+        const r = await this.run(["/bin/sh", "-c", guarded], secs * 1000 + 10_000, opts, undefined, () => timeoutError("northflank", secs));
         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`);
-        }
+        if (killedByTimeout(r.exitCode, durationMs, secs))
+            throw timeoutError("northflank", secs);
         return { ...r, durationMs };
     }
     /** Stream base64 over stdin and decode in the sandbox. */
@@ -159,8 +157,8 @@ class NorthflankBox {
     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) {
+    /** One exec session: optional stdin, streamed stdout/stderr, exit code. `expired` is thrown when limitMs passes. */
+    async run(command, limitMs, opts = {}, stdin, expired = () => timeoutError("northflank", Math.round(limitMs / 1000))) {
         const t0 = Date.now();
         let session;
         try {
@@ -197,7 +195,7 @@ class NorthflankBox {
         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`);
+                throw expired();
             return { exitCode: typeof res.exitCode === "number" ? res.exitCode : -1, stdout, stderr };
         }
         catch (err) {

package/dist/providers/novita.d.ts

@@ -0,0 +1,12 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+export declare class NovitaProvider implements Provider {
+    private apiKey;
+    private domain;
+    readonly id: "novita";
+    constructor(apiKey?: string | undefined, domain?: string | undefined);
+    configured(): boolean;
+    private conn;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach by sandbox id; a paused sandbox is resumed. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/novita.js

@@ -0,0 +1,81 @@
+import { ProviderError } from "../types.js";
+import { optionalImport } from "../util.js";
+import { E2BBox } from "./e2b.js";
+/**
+ * Novita AI Agent Sandbox via the official `novita-sandbox` SDK (2.x), a fork of E2B's SDK with
+ * the same surface (Sandbox.create/connect, commands.run with onStdout/onStderr, files.read/write,
+ * pause, kill), so the E2B box wrapper is reused as-is.
+ *
+ * Why not the `e2b` SDK with Novita's domain: that was Novita's documented route for its v1
+ * cluster (sandbox.novita.ai), but since the 2026-06-08 SDK 2.0 release the E2B-compatible page
+ * is a "Legacy SDKs & CLI" page for the 1.x line, the default cluster moved to
+ * us-phx-1.sandbox.novita.ai, and the docs only describe `novita-sandbox` for it.
+ *
+ * Auth: NOVITA_API_KEY (sent as X-API-KEY by the SDK). NOVITA_DOMAIN optionally picks the cluster
+ * (default us-phx-1.sandbox.novita.ai; sandbox.novita.ai is the legacy v1 cluster). Resources are
+ * not shared between clusters.
+ * Size: vCPU and memory come from the template (set at template build time: cpuCount/memoryMB),
+ * not from the create call, exactly like E2B. image.novita = template name or ID (default "base").
+ * Pause keeps memory and disk; Sandbox.connect resumes it. Billing is per second for CPU and RAM
+ * while running; paused sandboxes pay only persistent storage beyond 60 GB free.
+ *
+ * Docs: https://docs.novita.ai/guides/sandbox-overview.md (regions/domains)
+ *       https://docs.novita.ai/guides/sandbox-your-first-agent-sandbox.md (NOVITA_API_KEY, SDK)
+ *       https://docs.novita.ai/guides/sandbox-metadata.md (create: template, timeoutMs, envs, metadata)
+ *       https://docs.novita.ai/guides/sandbox-persistence.md (pause / connect resumes)
+ *       https://docs.novita.ai/guides/sandbox-quota-limit.md (vCPU/memory/session limits)
+ *       https://docs.novita.ai/guides/sandbox-pricing.md
+ *       https://docs.novita.ai/changelog/08-06-26 (SDK 2.0, new default cluster)
+ *       https://docs.novita.ai/guides/sandbox-legacy-e2b-compatible (legacy 1.x / E2B route)
+ */
+const ID = "novita";
+export class NovitaProvider {
+    apiKey;
+    domain;
+    id = ID;
+    constructor(apiKey = process.env.NOVITA_API_KEY, domain = process.env.NOVITA_DOMAIN) {
+        this.apiKey = apiKey;
+        this.domain = domain;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    conn() {
+        if (!this.apiKey)
+            throw new ProviderError(ID, "NOVITA_API_KEY is not set");
+        return { apiKey: this.apiKey, ...(this.domain ? { domain: this.domain } : {}) };
+    }
+    async create(spec) {
+        const { Sandbox } = await optionalImport("novita-sandbox", "novita");
+        const opts = {
+            ...this.conn(),
+            timeoutMs: (spec.timeoutMinutes ?? 30) * 60_000,
+            envs: spec.env,
+            metadata: spec.metadata,
+        };
+        const template = spec.image?.novita;
+        try {
+            const sbx = template ? await Sandbox.create(template, opts) : await Sandbox.create(opts);
+            return new E2BBox(sbx, ID);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Reattach by sandbox id; a paused sandbox is resumed. */
+    async connect(nativeId) {
+        const { Sandbox } = await optionalImport("novita-sandbox", "novita");
+        try {
+            return new E2BBox(await Sandbox.connect(nativeId, this.conn()), ID);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+}
+function wrap(err) {
+    if (err instanceof ProviderError)
+        return err;
+    const status = err?.name === "SandboxNotFoundError" || err?.name === "NotFoundError" ? 404 : err?.name === "AuthenticationError" ? 401 : undefined;
+    return new ProviderError(ID, err?.message ?? String(err), status);
+}

package/dist/providers/openscale.d.ts

@@ -0,0 +1,17 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+export declare const OPENSCALE_DOMAIN = "sandbox.openscale.so";
+export declare class OpenScaleProvider implements Provider {
+    private apiKey;
+    readonly id: "openscale";
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    /** @internal Connection options for the e2b SDK. */
+    conn(): {
+        apiKey: string;
+        domain: string;
+        apiUrl: string;
+    };
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach by sandbox id; a paused sandbox is resumed. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/openscale.js

@@ -0,0 +1,87 @@
+import { ProviderError } from "../types.js";
+import { optionalImport } from "../util.js";
+import { E2BBox } from "./e2b.js";
+/**
+ * OpenScale Sandboxes (YC S22) through their E2B-compatible API, driven with the official `e2b`
+ * SDK pointed at OpenScale's domain:
+ *   API URL  https://api.sandbox.openscale.so   (the SDK's https://api.<domain> default)
+ *   domain   sandbox.openscale.so                (data plane: <port>-<sandboxId>.<domain>)
+ * OpenScale's own instructions are E2B_DOMAIN=sandbox.openscale.so plus the OpenScale key as
+ * E2B_API_KEY. This adapter does not read E2B_API_KEY, so a real E2B key is never sent to
+ * OpenScale (and an OpenScale key never to E2B): it reads OPENSCALE_API_KEY (the name OpenScale's
+ * model docs use) and passes key, domain and apiUrl explicitly, so a stray E2B_DOMAIN or
+ * E2B_API_URL can't redirect calls. E2B_SANDBOX_URL would still override the data plane, so don't
+ * set it alongside this adapter.
+ *
+ * Auth: a pay-as-you-go OpenScale key (sk-openscale-...), the same account and credits as their
+ * model API. Plan (subscription) keys are refused: the API answers 401 "Use a pay-as-you-go
+ * OpenScale API key; plan keys don't run sandboxes". A new key can take ~30 s to start working.
+ * Region: Singapore only for now.
+ *
+ * Size: vCPU and memory come from the template, as with E2B (1-8 vCPU, up to 16 GB, 25 GB disk
+ * included, no GPU). image.openscale = template name or ID; default "base", the template the
+ * quick start says a sandbox starts from. Custom templates are built with the E2B template
+ * builder or CLI (Dockerfile) against the same domain.
+ * Lifetime: timeoutMs as given; OpenScale advertises no session time limit or 24 h cap, so no cap
+ * is applied here.
+ * Pause/resume is advertised as built in (memory and files kept, paused sandboxes are free), so
+ * the box offers pause(); Sandbox.connect resumes. Not supported yet per OpenScale: volumes,
+ * secrets, fork, snapshots API.
+ *
+ * Docs: https://openscale.so/sandboxes (setup, limits, pricing, FAQ)
+ *       https://openscale.so/app/sandboxes (keys and quick start, signed in)
+ *       https://openscale.so/docs (API keys: pay-as-you-go vs plan keys)
+ */
+const ID = "openscale";
+export const OPENSCALE_DOMAIN = "sandbox.openscale.so";
+const DEFAULT_TEMPLATE = "base";
+export class OpenScaleProvider {
+    apiKey;
+    id = ID;
+    constructor(apiKey = process.env.OPENSCALE_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    /** @internal Connection options for the e2b SDK. */
+    conn() {
+        if (!this.apiKey)
+            throw new ProviderError(ID, "OPENSCALE_API_KEY is not set");
+        return { apiKey: this.apiKey, domain: OPENSCALE_DOMAIN, apiUrl: `https://api.${OPENSCALE_DOMAIN}` };
+    }
+    async create(spec) {
+        const conn = this.conn();
+        const { Sandbox } = await optionalImport("e2b", "openscale");
+        const timeoutMs = Math.max(1, spec.timeoutMinutes ?? 30) * 60_000;
+        try {
+            const sbx = await Sandbox.create(spec.image?.openscale ?? DEFAULT_TEMPLATE, {
+                ...conn,
+                timeoutMs,
+                envs: spec.env,
+                metadata: spec.metadata,
+            });
+            return new E2BBox(sbx, ID);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Reattach by sandbox id; a paused sandbox is resumed. */
+    async connect(nativeId) {
+        const conn = this.conn();
+        const { Sandbox } = await optionalImport("e2b", "openscale");
+        try {
+            return new E2BBox((await Sandbox.connect(nativeId, conn)), ID);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+}
+function wrap(err) {
+    if (err instanceof ProviderError)
+        return err;
+    const status = err?.name === "SandboxNotFoundError" || err?.name === "NotFoundError" ? 404 : err?.name === "AuthenticationError" ? 401 : undefined;
+    return new ProviderError(ID, err?.message ?? String(err), status);
+}

package/dist/providers/orgo.d.ts

@@ -0,0 +1,45 @@
+import type { ComputerOs, ComputerProvider, ComputerSpec, ProviderComputer } from "../computers.js";
+type Json = Record<string, any>;
+export declare class OrgoProvider implements ComputerProvider {
+    private apiKey;
+    private baseUrl;
+    /** Workspace to create computers in. Unset: the first workspace this key can write to. */
+    private workspaceId;
+    readonly id: "orgo";
+    /**
+     * Linux on every account. Windows is created with `os: "windows"` but needs a Scale plan or a
+     * purchased Windows licence (else 403 WINDOWS_REQUIRES_SCALE) and is never offered by the hour.
+     * Android, macOS and iPhone are devices set up on request, not self-serve.
+     */
+    readonly computerOs: ComputerOs[];
+    private workspace?;
+    constructor(apiKey?: string | undefined, baseUrl?: string, 
+    /** Workspace to create computers in. Unset: the first workspace this key can write to. */
+    workspaceId?: string | undefined);
+    configured(): boolean;
+    /** @internal Authenticated call to the Orgo API. Throws ProviderError with the HTTP status. */
+    request(method: string, path: string, init?: {
+        json?: unknown;
+        form?: FormData;
+        query?: Record<string, string>;
+    }): Promise<Response>;
+    /** @internal */
+    json<T = Json>(method: string, path: string, init?: {
+        json?: unknown;
+        form?: FormData;
+        query?: Record<string, string>;
+    }): Promise<T>;
+    /** @internal The workspace new computers go in: ORGO_WORKSPACE_ID, else the first one the key can write to. */
+    resolveWorkspace(): Promise<string>;
+    createComputer(spec: ComputerSpec): Promise<ProviderComputer>;
+    /**
+     * Reattach to a computer. A stopped (frozen) one is started, a suspended one resumed. Both answer
+     * 202 while the computer comes back, so it is polled until it reports running.
+     */
+    connectComputer(nativeId: string): Promise<ProviderComputer>;
+    /** Poll a computer until it is running; a computer that errored or was deleted meanwhile is reported. */
+    private waitRunning;
+    /** @internal wss:// origin for the computer's VNC WebSocket (same host as the API). */
+    wsOrigin(): string;
+}
+export {};