@sandboxrouter/sdk 0.0.0-stage → 0.1.0

package/dist/providers/modal.js

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes } from "../util.js";
+const APP_NAME = process.env.SANDBOXROUTER_MODAL_APP ?? "sandboxrouter";
+/** Modal via the `modal` JS SDK. The only adapter here that takes `gpu`. */
+export class ModalProvider {
+    id = "modal";
+    client;
+    configured() {
+        return (!!process.env.MODAL_TOKEN_ID && !!process.env.MODAL_TOKEN_SECRET) || existsSync(join(homedir(), ".modal.toml"));
+    }
+    async modal() {
+        if (!this.client) {
+            const { ModalClient } = await optionalImport("modal", "modal");
+            this.client = new ModalClient();
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const modal = await this.modal();
+        const app = await modal.apps.fromName(APP_NAME, { createIfMissing: true });
+        const image = modal.images.fromRegistry(spec.image?.modal ?? "python:3.13-slim");
+        const sb = await modal.sandboxes.create(app, image, {
+            cpu: spec.vcpu ?? DEFAULT_VCPU,
+            memoryMiB: Math.round((spec.memoryGb ?? DEFAULT_MEMORY_GB) * 1024),
+            gpu: spec.gpu,
+            timeoutMs: (spec.timeoutMinutes ?? 30) * 60_000,
+            env: spec.env,
+        });
+        return new ModalBox(sb);
+    }
+    async connect(nativeId) {
+        return new ModalBox(await (await this.modal()).sandboxes.fromId(nativeId));
+    }
+}
+/** Read a text stream to the end, passing each chunk to `on`. */
+async function drain(stream, on) {
+    const reader = stream.getReader();
+    let out = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            return out;
+        out += value;
+        on?.(value);
+    }
+}
+class ModalBox {
+    sb;
+    nativeId;
+    constructor(sb) {
+        this.sb = sb;
+        this.nativeId = sb.sandboxId;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        try {
+            const p = await this.sb.exec(["sh", "-c", cmd], {
+                workdir: opts.cwd,
+                env: opts.env,
+                timeoutMs: (opts.timeoutSeconds ?? 60) * 1000,
+            });
+            const [stdout, stderr, exitCode] = await Promise.all([drain(p.stdout, opts.onStdout), drain(p.stderr, opts.onStderr), p.wait()]);
+            return { exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw new ProviderError("modal", err?.message ?? String(err));
+        }
+    }
+    async writeFile(path, content) {
+        await this.sb.filesystem.writeBytes(toBytes(content), path);
+    }
+    async readFile(path) {
+        return await this.sb.filesystem.readBytes(path);
+    }
+    async kill() {
+        await this.sb.terminate();
+    }
+}

package/dist/providers/morph.d.ts

@@ -0,0 +1,19 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Morph Cloud via `morphcloud`. Instances start from snapshots: by default a cached snapshot of
+ * morphvm-minimal sized to spec.vcpu / spec.memoryGb; set image.morph to a snapshot id to start
+ * from your own (its resources come from the snapshot).
+ */
+export declare class MorphProvider implements Provider {
+    private apiKey;
+    readonly id: "morph";
+    private client?;
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    private morph;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach; a paused instance is resumed. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+    /** Reuse (or create once) a morphvm-minimal snapshot with this shape, keyed by digest. */
+    private baseSnapshot;
+}

package/dist/providers/morph.js

@@ -0,0 +1,181 @@
+import { ProviderError } from "../types.js";
+import { dirname, optionalImport, shq, toBytes, wrapCommand } from "../util.js";
+/** Base image for the default snapshot (Morph's minimal Ubuntu VM). */
+const BASE_IMAGE = "morphvm-minimal";
+const DISK_MB = 8192;
+/** spec.env lives here inside the VM so it survives connect(); every exec sources it. */
+const ENV_FILE = "/etc/sandboxrouter.env";
+const READY_TIMEOUT_S = 300;
+/**
+ * Morph Cloud via `morphcloud`. Instances start from snapshots: by default a cached snapshot of
+ * morphvm-minimal sized to spec.vcpu / spec.memoryGb; set image.morph to a snapshot id to start
+ * from your own (its resources come from the snapshot).
+ */
+export class MorphProvider {
+    apiKey;
+    id = "morph";
+    client;
+    constructor(apiKey = process.env.MORPH_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async morph() {
+        if (!this.client) {
+            const { MorphCloudClient } = await optionalImport("morphcloud", "morph");
+            this.client = new MorphCloudClient({ apiKey: this.apiKey });
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const m = await this.morph();
+        try {
+            const snapshotId = spec.image?.morph ?? (await this.baseSnapshot(m, spec));
+            const inst = await m.instances.start({
+                snapshotId,
+                metadata: spec.metadata,
+                ttlSeconds: Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60)),
+                ttlAction: "stop",
+                timeout: READY_TIMEOUT_S,
+            });
+            const box = new MorphBox(inst);
+            if (spec.env && Object.keys(spec.env).length) {
+                try {
+                    await box.writeFile(ENV_FILE, envFile(spec.env));
+                }
+                catch (err) {
+                    await inst.stop().catch(() => { });
+                    throw err;
+                }
+            }
+            return box;
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Reattach; a paused instance is resumed. */
+    async connect(nativeId) {
+        const m = await this.morph();
+        try {
+            const inst = await m.instances.get({ instanceId: nativeId });
+            if (String(inst.status) === "paused")
+                await inst.resume();
+            if (String(inst.status) !== "ready")
+                await inst.waitUntilReady(READY_TIMEOUT_S);
+            return new MorphBox(inst);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Reuse (or create once) a morphvm-minimal snapshot with this shape, keyed by digest. */
+    async baseSnapshot(m, spec) {
+        const vcpus = spec.vcpu ?? 2;
+        const memory = Math.round((spec.memoryGb ?? 4) * 1024);
+        const digest = `sandboxrouter-${BASE_IMAGE}-${vcpus}c-${memory}m-${DISK_MB}d`;
+        const existing = (await m.snapshots.list({ digest })).find((s) => String(s.status) === "ready");
+        if (existing)
+            return existing.id;
+        let snap = await m.snapshots.create({ imageId: BASE_IMAGE, vcpus, memory, diskSize: DISK_MB, digest });
+        const t0 = Date.now();
+        while (String(snap.status) === "pending") {
+            if (Date.now() - t0 > READY_TIMEOUT_S * 1000)
+                throw new ProviderError("morph", `snapshot ${snap.id} not ready`);
+            await sleep(1000);
+            snap = await m.snapshots.get({ snapshotId: snap.id });
+        }
+        if (String(snap.status) !== "ready")
+            throw new ProviderError("morph", `snapshot ${snap.id} is ${snap.status}`);
+        return snap.id;
+    }
+}
+class MorphBox {
+    inst;
+    nativeId;
+    constructor(inst) {
+        this.inst = inst;
+        this.nativeId = inst.id;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const script = `[ -r ${ENV_FILE} ] && . ${ENV_FILE}; ${wrapCommand(cmd, { cwd: opts.cwd, env: opts.env })}`;
+        try {
+            // With callbacks the SDK switches to its SSE endpoint and streams; otherwise one request.
+            const r = await this.inst.exec(["sh", "-c", script], {
+                timeout: opts.timeoutSeconds ?? 60,
+                onStdout: opts.onStdout,
+                onStderr: opts.onStderr,
+            });
+            return { exitCode: r.exit_code, stdout: r.stdout ?? "", stderr: r.stderr ?? "", durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Over SSH: base64 on stdin, decoded in the VM (parent dirs created). */
+    async writeFile(path, content) {
+        const b64 = Buffer.from(toBytes(content)).toString("base64");
+        const r = await this.ssh((s) => s.execCommand(`mkdir -p ${shq(dirname(path))} && base64 -d > ${shq(path)}${path === ENV_FILE ? ` && chmod 600 ${ENV_FILE}` : ""}`, { stdin: b64 }));
+        if (r.code !== 0)
+            throw new ProviderError("morph", `writeFile ${path}: ${r.stderr || `exit ${r.code}`}`);
+    }
+    async readFile(path) {
+        const r = await this.ssh((s) => s.execCommand(`base64 < ${shq(path)}`));
+        if (r.code !== 0)
+            throw new ProviderError("morph", `readFile ${path}: ${r.stderr || `exit ${r.code}`}`);
+        return new Uint8Array(Buffer.from(r.stdout, "base64"));
+    }
+    /** Snapshot memory and disk. router.get() resumes it. */
+    async pause() {
+        try {
+            await this.inst.pause();
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    async kill() {
+        try {
+            await this.inst.stop();
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** One SSH connection per call so no socket keeps the process alive. */
+    async ssh(fn) {
+        let s;
+        try {
+            s = await this.inst.ssh();
+            return await fn(s);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+        finally {
+            s?.dispose();
+        }
+    }
+}
+function envFile(env) {
+    return Object.entries(env)
+        .map(([k, v]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k))
+            throw new Error(`invalid env var name: ${k}`);
+        return `export ${k}=${shq(v)}\n`;
+    })
+        .join("");
+}
+/** The SDK throws plain Errors whose message starts "HTTP <status> ...". */
+function wrap(err) {
+    if (err instanceof ProviderError)
+        return err;
+    const msg = err?.message ?? String(err);
+    const status = /^HTTP (\d{3})/.exec(msg)?.[1];
+    return new ProviderError("morph", msg, status ? Number(status) : undefined);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms).unref());
+}

package/dist/providers/runloop.d.ts

@@ -0,0 +1,16 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Runloop devboxes via `@runloop/api-client`. Auth: RUNLOOP_API_KEY. Default Runloop image;
+ * set image.runloop to a blueprint name (or a `bpt_` blueprint id) to start from your own.
+ */
+export declare class RunloopProvider implements Provider {
+    private apiKey;
+    readonly id: "runloop";
+    private client?;
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    private runloop;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach; a suspended devbox is resumed. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/runloop.js

@@ -0,0 +1,145 @@
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes, wrapCommand } from "../util.js";
+/** Longest lifetime Runloop accepts for keep_alive_time_seconds (48 h). */
+const MAX_KEEP_ALIVE_SECONDS = 172_800;
+/**
+ * Runloop devboxes via `@runloop/api-client`. Auth: RUNLOOP_API_KEY. Default Runloop image;
+ * set image.runloop to a blueprint name (or a `bpt_` blueprint id) to start from your own.
+ */
+export class RunloopProvider {
+    apiKey;
+    id = "runloop";
+    client;
+    constructor(apiKey = process.env.RUNLOOP_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async runloop() {
+        if (!this.client) {
+            const { RunloopSDK } = await optionalImport("@runloop/api-client", "runloop");
+            this.client = new RunloopSDK({ bearerToken: this.apiKey });
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const rl = await this.runloop();
+        const { cpu, memory } = size(spec.vcpu ?? DEFAULT_VCPU, spec.memoryGb ?? DEFAULT_MEMORY_GB);
+        const image = spec.image?.runloop;
+        try {
+            const box = await rl.devbox.create({
+                ...(image ? (image.startsWith("bpt_") ? { blueprint_id: image } : { blueprint_name: image }) : {}),
+                environment_variables: spec.env,
+                metadata: spec.metadata,
+                launch_parameters: {
+                    resource_size_request: "CUSTOM_SIZE",
+                    custom_cpu_cores: cpu,
+                    custom_gb_memory: memory,
+                    keep_alive_time_seconds: Math.min(MAX_KEEP_ALIVE_SECONDS, Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60))),
+                },
+            });
+            return new RunloopBox(box);
+        }
+        catch (err) {
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+    /** Reattach; a suspended devbox is resumed. */
+    async connect(nativeId) {
+        const box = (await this.runloop()).devbox.fromId(nativeId);
+        try {
+            const { status } = await box.getInfo();
+            if (status === "suspending")
+                await box.awaitSuspended();
+            if (status === "suspending" || status === "suspended")
+                await box.resume();
+            else if (status === "resuming" || status === "provisioning" || status === "initializing" || status === "queued" || status === "scheduled") {
+                await box.awaitRunning();
+            }
+            else if (status === "shutdown" || status === "failure") {
+                throw new ProviderError("runloop", `devbox ${nativeId} is ${status}`);
+            }
+            return new RunloopBox(box);
+        }
+        catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+}
+class RunloopBox {
+    box;
+    nativeId;
+    constructor(box) {
+        this.box = box;
+        this.nativeId = box.id;
+    }
+    /** Runloop's exec has no cwd/env/timeout, so cwd/env are wrapped into the command and the timeout is enforced here. */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const limit = (opts.timeoutSeconds ?? 60) * 1000;
+        let execution;
+        try {
+            execution = await this.box.cmd.execAsync(wrapCommand(cmd, { cwd: opts.cwd, env: opts.env }), {
+                stdout: opts.onStdout,
+                stderr: opts.onStderr,
+            });
+        }
+        catch (err) {
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+        try {
+            const r = await execution.result({ longPoll: { timeoutMs: limit } });
+            // Read the output from the result, not the stream, so a dropped stream can't lose output.
+            const [stdout, stderr] = await Promise.all([r.stdout(), r.stderr()]);
+            return { exitCode: r.exitCode ?? -1, stdout, stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            if (Date.now() - t0 >= limit) {
+                await execution.kill().catch(() => { });
+                throw new ProviderError("runloop", `command timed out after ${limit / 1000}s`);
+            }
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+    async writeFile(path, content) {
+        const { toFile } = await optionalImport("@runloop/api-client", "runloop");
+        const name = path.slice(path.lastIndexOf("/") + 1) || "file";
+        try {
+            await this.box.file.upload({ path, file: await toFile(Buffer.from(toBytes(content)), name) });
+        }
+        catch (err) {
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+    async readFile(path) {
+        try {
+            const res = await this.box.file.download({ path });
+            return new Uint8Array(await res.arrayBuffer());
+        }
+        catch (err) {
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+    /** Suspend and snapshot the disk. router.get() resumes it. */
+    async pause() {
+        await this.box.suspend();
+        await this.box.awaitSuspended();
+    }
+    async kill() {
+        await this.box.shutdown();
+    }
+}
+/**
+ * Snap a request to Runloop's CUSTOM_SIZE grid: CPU 0.5, 1 or a multiple of 2 (max 16);
+ * memory 1 or a multiple of 2 GiB (max 64); memory between 2x and 8x the CPU count.
+ */
+function size(vcpu, memoryGb) {
+    const cpu = vcpu <= 0.5 ? 0.5 : vcpu <= 1 ? 1 : Math.min(16, 2 * Math.ceil(vcpu / 2));
+    const m = Math.min(8 * cpu, Math.max(2 * cpu, memoryGb));
+    const memory = Math.min(64, m <= 1 ? 1 : 2 * Math.ceil(m / 2));
+    return { cpu, memory };
+}

package/dist/providers/sprites.d.ts

@@ -0,0 +1,15 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Fly.io Sprites via `@fly/sprites`. A sprite is a persistent machine named by the caller, so the
+ * name is the native id. Sprites idle on their own and have no lifetime knob: kill() deletes it.
+ */
+export declare class SpritesProvider implements Provider {
+    private token;
+    readonly id: "sprites";
+    private client?;
+    constructor(token?: string | undefined);
+    configured(): boolean;
+    private sprites;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/sprites.js

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import { StringDecoder } from "node:string_decoder";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes } from "../util.js";
+/**
+ * Fly.io Sprites via `@fly/sprites`. A sprite is a persistent machine named by the caller, so the
+ * name is the native id. Sprites idle on their own and have no lifetime knob: kill() deletes it.
+ */
+export class SpritesProvider {
+    token;
+    id = "sprites";
+    client;
+    constructor(token = process.env.SPRITES_TOKEN) {
+        this.token = token;
+    }
+    configured() {
+        return !!this.token;
+    }
+    async sprites() {
+        if (!this.client) {
+            const { SpritesClient } = await optionalImport("@fly/sprites", "sprites");
+            this.client = new SpritesClient(this.token);
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const client = await this.sprites();
+        const name = `sbr-${randomUUID().slice(0, 12)}`;
+        try {
+            const sprite = await client.createSprite(name, {
+                config: { cpus: spec.vcpu, ramMB: spec.memoryGb ? Math.round(spec.memoryGb * 1024) : undefined },
+                environment: spec.env,
+            });
+            return new SpritesBox(sprite);
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err), err?.statusCode);
+        }
+    }
+    async connect(nativeId) {
+        const client = await this.sprites();
+        try {
+            return new SpritesBox(await client.getSprite(nativeId));
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err), err?.statusCode);
+        }
+    }
+}
+class SpritesBox {
+    sprite;
+    nativeId;
+    constructor(sprite) {
+        this.sprite = sprite;
+        this.nativeId = sprite.name;
+    }
+    /** `sprite.exec` splits on whitespace without a shell, so spawn `sh -c` and stream its output. */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const limit = (opts.timeoutSeconds ?? 60) * 1000;
+        const proc = this.sprite.spawn("sh", ["-c", cmd], { cwd: opts.cwd, env: opts.env });
+        const out = new StringDecoder("utf8");
+        const errd = new StringDecoder("utf8");
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (b) => {
+            const c = out.write(b);
+            stdout += c;
+            if (c)
+                opts.onStdout?.(c);
+        });
+        proc.stderr.on("data", (b) => {
+            const c = errd.write(b);
+            stderr += c;
+            if (c)
+                opts.onStderr?.(c);
+        });
+        try {
+            const exitCode = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    proc.kill("SIGKILL");
+                    proc.close();
+                    reject(new ProviderError("sprites", `command timed out after ${limit / 1000}s`));
+                }, limit);
+                timer.unref();
+                proc.on("exit", (code) => {
+                    clearTimeout(timer);
+                    resolve(code);
+                });
+                proc.on("error", (e) => {
+                    clearTimeout(timer);
+                    proc.close();
+                    reject(e);
+                });
+            });
+            const so = out.end();
+            const se = errd.end();
+            if (so)
+                opts.onStdout?.(so);
+            if (se)
+                opts.onStderr?.(se);
+            return { exitCode, stdout: stdout + so, stderr: stderr + se, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            throw new ProviderError("sprites", err?.message ?? String(err));
+        }
+    }
+    async writeFile(path, content) {
+        try {
+            await this.sprite.filesystem().writeFile(path, Buffer.from(toBytes(content)));
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err));
+        }
+    }
+    async readFile(path) {
+        try {
+            return new Uint8Array(await this.sprite.filesystem().readFile(path, null));
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err));
+        }
+    }
+    /** Sprites are persistent; delete so the router's disposable sandboxes don't linger. */
+    async kill() {
+        try {
+            await this.sprite.delete();
+        }
+        catch (err) {
+            throw new ProviderError("sprites", err?.message ?? String(err), err?.statusCode);
+        }
+    }
+}

package/dist/providers/tensorlake.d.ts

@@ -0,0 +1,14 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * 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 declare class TensorlakeProvider implements Provider {
+    private apiKey;
+    readonly id: "tensorlake";
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach; a suspended sandbox is resumed. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}