sbox-sdk 0.0.2

package/dist/vercel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vercel/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAchE,OAAO,KAAK,EAYV,eAAe,EAGhB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BU,CAAC;AAEnC,MAAM,MAAM,UAAU,GAAG,OAAO,WAAW,CAAC;AAgE5C,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6MlB,CAAC"}

package/dist/vercel/index.js

@@ -0,0 +1,241 @@
+/**
+ * `sbox-sdk/vercel` — adapter for `@vercel/sandbox` (ephemeral microVMs).
+ * Exercises the exec-emulation surface: no PTY, no fs watch, no code interpreter.
+ * Node-only (uses Buffer for binary fs). Requires the optional peer dependency
+ * `@vercel/sandbox`; auth via a Vercel token + team/project ids (OIDC or PAT).
+ */
+import { AsyncQueue, defineProvider, numExit, SandboxError, } from "../adapter/index.js";
+export const VERCEL_CAPS = {
+    background: "native",
+    codeInterpreter: "unsupported",
+    egressControl: "unsupported",
+    exposePort: "native",
+    filesUpload: "native",
+    filesWatch: "unsupported",
+    fork: "unsupported",
+    gpu: "unsupported",
+    killProcess: "unsupported",
+    list: "unsupported",
+    metrics: "unsupported",
+    pause: "unsupported",
+    privatePreview: "unsupported",
+    proxiedFetch: "unsupported",
+    pty: "unsupported",
+    region: "unsupported",
+    secretsVault: "unsupported",
+    setTimeout: "unsupported",
+    snapshot: "unsupported",
+    ssh: "unsupported",
+    statefulKernel: "unsupported",
+    stdin: "unsupported",
+    stop: "unsupported",
+    streaming: "native",
+    volumes: "unsupported",
+};
+const VERCEL_FLAGS = {
+    exitCodeNative: true,
+    perCommandEnvCwd: true,
+    preservesDiskOnStop: true, // stop() auto-snapshots the filesystem
+    preservesMemoryOnPause: false,
+    previewModel: "declaredPorts",
+};
+let cached = null;
+async function loadVercel() {
+    if (!cached) {
+        cached = (await import("@vercel/sandbox"));
+    }
+    return cached;
+}
+function mapState(status) {
+    switch (status) {
+        case "running": {
+            return "running";
+        }
+        case "stopped":
+        case "stopping": {
+            return "stopped";
+        }
+        case "pending":
+        case "initializing": {
+            return "creating";
+        }
+        case "failed": {
+            return "error";
+        }
+        default: {
+            return "unknown";
+        }
+    }
+}
+function mapVercelError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (/not ?found/i.test(msg)) {
+        return new SandboxError("NotFound", msg, { cause: e, provider: "vercel" });
+    }
+    if (/unauthor|forbidden|token/i.test(msg)) {
+        return new SandboxError("Unauthorized", msg, {
+            cause: e,
+            provider: "vercel",
+        });
+    }
+    if (/timeout|timed out/i.test(msg)) {
+        return new SandboxError("Timeout", msg, { cause: e, provider: "vercel" });
+    }
+    return undefined;
+}
+export const vercel = defineProvider((opts) => {
+    const creds = {
+        projectId: opts.projectId,
+        teamId: opts.teamId,
+        token: opts.token,
+    };
+    const makeHandle = (sb) => {
+        const v = sb;
+        const drive = (queue, cmdP) => {
+            void (async () => {
+                let cmd;
+                try {
+                    cmd = await cmdP;
+                }
+                catch (error) {
+                    queue.fail(mapVercelError(error) ?? SandboxError.wrap(error, "vercel"));
+                    return;
+                }
+                try {
+                    for await (const log of cmd.logs()) {
+                        queue.push({
+                            data: log.data,
+                            type: log.stream === "stderr" ? "stderr" : "stdout",
+                        });
+                    }
+                    const fin = await cmd.wait();
+                    queue.push({ exitCode: fin.exitCode, type: "exit" });
+                }
+                catch (error) {
+                    queue.push({ exitCode: numExit(error), type: "exit" });
+                }
+                queue.close();
+            })();
+        };
+        return {
+            id: v.sandboxId,
+            raw: sb,
+            getInfo() {
+                return {
+                    id: v.sandboxId,
+                    metadata: {},
+                    provider: "vercel",
+                    raw: sb,
+                    state: mapState(v.status),
+                };
+            },
+            async destroy() {
+                await v.stop();
+            },
+            exec(cmd, options) {
+                const queue = new AsyncQueue();
+                const cmdP = v.runCommand({
+                    args: ["-c", cmd],
+                    cmd: "sh",
+                    cwd: options.cwd,
+                    detached: true,
+                    env: options.env,
+                });
+                drive(queue, cmdP);
+                return {
+                    pid: cmdP.then((c) => c.cmdId).catch(() => ""),
+                    async kill() {
+                        /* no kill handle exposed by the SDK */
+                    },
+                    [Symbol.asyncIterator]: () => queue.iterator(),
+                };
+            },
+            async spawn(cmd, options) {
+                const c = await v.runCommand({
+                    args: ["-c", cmd],
+                    cmd: "sh",
+                    cwd: options.cwd,
+                    detached: true,
+                    env: options.env,
+                });
+                const queue = new AsyncQueue();
+                drive(queue, Promise.resolve(c));
+                return {
+                    id: c.cmdId,
+                    pid: Promise.resolve(c.cmdId),
+                    async kill() {
+                        /* no kill handle exposed by the SDK */
+                    },
+                    [Symbol.asyncIterator]: () => queue.iterator(),
+                };
+            },
+            async readFile(path) {
+                const buf = await v.fs.readFileToBuffer({ path });
+                if (!buf) {
+                    throw new SandboxError("NotFound", `no such file: '${path}'`, {
+                        provider: "vercel",
+                    });
+                }
+                return new Uint8Array(buf);
+            },
+            async writeFile(path, data) {
+                await v.fs.writeFiles([{ content: data, path }]);
+            },
+            async listDir(path) {
+                const entries = await v.fs.readdir(path, { withFileTypes: true });
+                return entries.map((d) => ({
+                    name: d.name,
+                    path: `${path.replace(/\/$/, "")}/${d.name}`,
+                    type: d.isDirectory() ? "dir" : "file",
+                }));
+            },
+            async mkdir(path, recursive) {
+                await v.fs.mkdir(path, { recursive });
+            },
+            async remove(path, recursive) {
+                await v.fs.rm(path, { force: true, recursive });
+            },
+            async stat(path) {
+                const s = await v.fs.stat(path);
+                return {
+                    mtime: s.mtime,
+                    path,
+                    size: s.size,
+                    type: s.isDirectory() ? "dir" : "file",
+                };
+            },
+            exposePort(port) {
+                return { port, url: v.domain(port) };
+            },
+            // NOTE: rename is omitted -> the core polyfills it via exec(`mv`).
+        };
+    };
+    const provider = {
+        capabilities: VERCEL_CAPS,
+        async connect(id) {
+            const { Sandbox } = await loadVercel();
+            const sb = await Sandbox.get({ ...creds, sandboxId: id });
+            return makeHandle(sb);
+        },
+        async create(spec) {
+            const { Sandbox } = await loadVercel();
+            const sb = await Sandbox.create({
+                ...creds,
+                env: spec.env,
+                name: spec.name,
+                ports: spec.ports,
+                resources: spec.resources?.vcpus
+                    ? { vcpus: spec.resources.vcpus }
+                    : undefined,
+                runtime: spec.template,
+                signal: spec.signal,
+                timeout: spec.ttlMs,
+            });
+            return makeHandle(sb);
+        },
+        flags: VERCEL_FLAGS,
+        mapError: mapVercelError,
+        name: "vercel",
+    };
+    return provider;
+});

package/package.json

@@ -0,0 +1,252 @@
+{
+  "name": "sbox-sdk",
+  "version": "0.0.2",
+  "description": "One unified SDK for agent sandbox providers (E2B, Vercel, Cloudflare, Daytona, Modal, and more) — swap the adapter import, keep your code.",
+  "keywords": [
+    "agent",
+    "ai",
+    "cloudflare-sandbox",
+    "code-interpreter",
+    "daytona",
+    "e2b",
+    "sandbox",
+    "vercel-sandbox"
+  ],
+  "license": "MIT",
+  "bin": {
+    "sbox": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/aws-lambda/runner",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapter": {
+      "types": "./dist/adapter/index.d.ts",
+      "import": "./dist/adapter/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance/index.d.ts",
+      "import": "./dist/conformance/index.js"
+    },
+    "./memory": {
+      "types": "./dist/memory/index.d.ts",
+      "import": "./dist/memory/index.js"
+    },
+    "./agent-tools": {
+      "types": "./dist/agent-tools/index.d.ts",
+      "import": "./dist/agent-tools/index.js"
+    },
+    "./ai": {
+      "types": "./dist/ai/index.d.ts",
+      "import": "./dist/ai/index.js"
+    },
+    "./ai-sdk": {
+      "types": "./dist/ai-sdk/index.d.ts",
+      "import": "./dist/ai-sdk/index.js"
+    },
+    "./mastra": {
+      "types": "./dist/mastra/index.d.ts",
+      "import": "./dist/mastra/index.js"
+    },
+    "./openai": {
+      "types": "./dist/openai/index.d.ts",
+      "import": "./dist/openai/index.js"
+    },
+    "./anthropic": {
+      "types": "./dist/anthropic/index.d.ts",
+      "import": "./dist/anthropic/index.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain/index.d.ts",
+      "import": "./dist/langchain/index.js"
+    },
+    "./e2b": {
+      "types": "./dist/e2b/index.d.ts",
+      "import": "./dist/e2b/index.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare/index.d.ts",
+      "import": "./dist/cloudflare/index.js"
+    },
+    "./vercel": {
+      "types": "./dist/vercel/index.d.ts",
+      "import": "./dist/vercel/index.js"
+    },
+    "./daytona": {
+      "types": "./dist/daytona/index.d.ts",
+      "import": "./dist/daytona/index.js"
+    },
+    "./modal": {
+      "types": "./dist/modal/index.d.ts",
+      "import": "./dist/modal/index.js"
+    },
+    "./fly": {
+      "types": "./dist/fly/index.d.ts",
+      "import": "./dist/fly/index.js"
+    },
+    "./aws-lambda": {
+      "types": "./dist/aws-lambda/index.d.ts",
+      "import": "./dist/aws-lambda/index.js"
+    },
+    "./northflank": {
+      "types": "./dist/northflank/index.d.ts",
+      "import": "./dist/northflank/index.js"
+    },
+    "./runloop": {
+      "types": "./dist/runloop/index.d.ts",
+      "import": "./dist/runloop/index.js"
+    },
+    "./codesandbox": {
+      "types": "./dist/codesandbox/index.d.ts",
+      "import": "./dist/codesandbox/index.js"
+    },
+    "./morph": {
+      "types": "./dist/morph/index.d.ts",
+      "import": "./dist/morph/index.js"
+    },
+    "./blaxel": {
+      "types": "./dist/blaxel/index.d.ts",
+      "import": "./dist/blaxel/index.js"
+    },
+    "./beam": {
+      "types": "./dist/beam/index.d.ts",
+      "import": "./dist/beam/index.js"
+    },
+    "./railway": {
+      "types": "./dist/railway/index.d.ts",
+      "import": "./dist/railway/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "check-types": "tsgo -p tsconfig.json --noEmit",
+    "types": "tsgo -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "pnpm run build"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.69.0",
+    "@aws-sdk/client-lambda": "^3.1075.0",
+    "@aws-sdk/client-lambda-microvms": "^3.1075.0",
+    "@aws-sdk/client-s3": "^3.1075.0",
+    "@beamcloud/beam-js": "*",
+    "@blaxel/core": "*",
+    "@cloudflare/sandbox": "^0.12.1",
+    "@codesandbox/sdk": "*",
+    "@daytonaio/sdk": "^0.191.0",
+    "@e2b/code-interpreter": "^2.6.1",
+    "@langchain/core": "^0.3.0",
+    "@mastra/core": "^1.46.0",
+    "@northflank/js-client": "*",
+    "@openai/agents": "^0.12.0",
+    "@runloop/api-client": "*",
+    "@sbox-sdk/config": "workspace:*",
+    "@types/node": "^25.9.1",
+    "@typescript/native-preview": "7.0.0-dev.20260624.1",
+    "@vercel/sandbox": "^2.2.1",
+    "ai": "^5.0.0",
+    "modal": "^0.8.1",
+    "morphcloud": "*",
+    "railway": "*",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.40.0",
+    "@aws-sdk/client-lambda-microvms": "*",
+    "@beamcloud/beam-js": "*",
+    "@blaxel/core": "*",
+    "@cloudflare/sandbox": "*",
+    "@codesandbox/sdk": "*",
+    "@daytonaio/sdk": "*",
+    "@e2b/code-interpreter": "*",
+    "@langchain/core": ">=0.3.0",
+    "@mastra/core": "^1.0.0",
+    "@northflank/js-client": "*",
+    "@openai/agents": ">=0.12.0",
+    "@runloop/api-client": "*",
+    "@vercel/sandbox": "*",
+    "ai": "^5.0.0 || ^6.0.0",
+    "modal": "*",
+    "morphcloud": "*",
+    "railway": "*",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-lambda-microvms": {
+      "optional": true
+    },
+    "@beamcloud/beam-js": {
+      "optional": true
+    },
+    "@blaxel/core": {
+      "optional": true
+    },
+    "@cloudflare/sandbox": {
+      "optional": true
+    },
+    "@codesandbox/sdk": {
+      "optional": true
+    },
+    "@northflank/js-client": {
+      "optional": true
+    },
+    "@runloop/api-client": {
+      "optional": true
+    },
+    "morphcloud": {
+      "optional": true
+    },
+    "railway": {
+      "optional": true
+    },
+    "@daytonaio/sdk": {
+      "optional": true
+    },
+    "@e2b/code-interpreter": {
+      "optional": true
+    },
+    "modal": {
+      "optional": true
+    },
+    "@vercel/sandbox": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "@mastra/core": {
+      "optional": true
+    },
+    "@openai/agents": {
+      "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/aws-lambda/runner/Dockerfile

@@ -0,0 +1,15 @@
+# Reference MicroVM image for the sbox-sdk AWS Lambda MicroVMs adapter.
+# Build -> zip with this Dockerfile + server.mjs -> upload to S3 ->
+# CreateMicrovmImage (see ./README.md). The runner runs INSIDE the isolated
+# MicroVM; executing arbitrary commands is its purpose (that is what the sandbox
+# is for), and it is never exposed on the host.
+FROM public.ecr.aws/docker/library/node:22-slim
+
+WORKDIR /opt/sbox
+COPY server.mjs .
+
+# The MicroVM endpoint routes to port 8080 by default.
+ENV PORT=8080
+EXPOSE 8080
+
+CMD ["node", "/opt/sbox/server.mjs"]

package/src/aws-lambda/runner/README.md

@@ -0,0 +1,59 @@
+# sbox-sdk runner for AWS Lambda MicroVMs
+
+AWS Lambda MicroVMs give you isolation + lifecycle + a dedicated HTTPS endpoint,
+but **the exec/filesystem protocol is defined by your image** — AWS only defines
+lifecycle hooks. This folder is a reference "runner" the `sbox-sdk/aws-lambda`
+adapter talks to. Bake it into your MicroVM image once.
+
+## Protocol the adapter expects
+
+Served on port `8080` (override with the adapter's `port` option):
+
+| Method & path                                                         | Body                              | Response                             |
+| --------------------------------------------------------------------- | --------------------------------- | ------------------------------------ |
+| `POST /sbox/exec`                                                     | `{ cmd, cwd?, env?, timeoutMs? }` | `{ stdout, stderr, exitCode }`       |
+| `POST /sbox/fs/read`                                                  | `{ path }`                        | `{ contentBase64 }` (404 if missing) |
+| `POST /sbox/fs/write`                                                 | `{ path, contentBase64 }`         | `{ ok: true }`                       |
+| `GET /sbox/health`                                                    | —                                 | `200`                                |
+| `POST /aws/lambda-microvms/runtime/v1/{run,resume,suspend,terminate}` | —                                 | `200`                                |
+
+The `/run` hook must return `200` before traffic flows — the reference
+`server.mjs` does this. Directory ops (`ls`, `mkdir`, `mv`, `stat`) are not
+separate routes: the core polyfills them through `/sbox/exec`.
+
+> Security: the runner runs **inside the isolated MicroVM** and executes
+> arbitrary commands on purpose — that is the sandbox. Never run it on a host.
+
+## Build & register the image
+
+```bash
+zip -j runner.zip Dockerfile server.mjs
+aws s3 cp runner.zip s3://YOUR_BUCKET/runner.zip
+
+aws lambda-microvms create-microvm-image \
+  --image-name sbox-runner \
+  --source '{"s3":{"bucket":"YOUR_BUCKET","key":"runner.zip"}}'
+# -> note the returned image ARN
+```
+
+## Use it
+
+```ts
+import { createSandboxClient } from "sbox-sdk";
+import { awsLambda } from "sbox-sdk/aws-lambda";
+
+const client = createSandboxClient({
+  provider: awsLambda({
+    imageIdentifier:
+      "arn:aws:lambda:us-east-1:123456789012:microvm-image:sbox-runner",
+    region: "us-east-1",
+  }),
+});
+
+const sandbox = await client.create();
+const res = await sandbox.commands.run("echo hello"); // res.stdout === "hello\n"
+await sandbox.files.write("/tmp/data.txt", "hi");
+await sandbox.pause(); // SuspendMicrovm (memory + disk preserved up to 8h)
+await sandbox.resume(); // ResumeMicrovm
+await sandbox.destroy(); // TerminateMicrovm
+```

package/src/aws-lambda/runner/server.mjs

@@ -0,0 +1,91 @@
+// Reference "runner" for sbox-sdk's AWS Lambda MicroVMs adapter.
+// Bake this into your MicroVM image (see Dockerfile). It exposes the small HTTP
+// protocol the adapter calls over the microVM's dedicated endpoint, plus the
+// required AWS lifecycle hooks. No external deps — Node stdlib only.
+//
+// Protocol (POST JSON unless noted), served on PORT (default 8080):
+//   POST /sbox/exec      { cmd, cwd?, env?, timeoutMs? } -> { stdout, stderr, exitCode }
+//   POST /sbox/fs/read   { path }                        -> { contentBase64 }   (404 if missing)
+//   POST /sbox/fs/write  { path, contentBase64 }         -> { ok: true }
+//   GET  /sbox/health                                    -> 200
+//   POST /aws/lambda-microvms/runtime/v1/{run,resume,suspend,terminate} -> 200
+
+import { exec } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { createServer } from "node:http";
+import { dirname } from "node:path";
+
+const PORT = Number(process.env.PORT ?? 8080);
+
+const readJson = (req) =>
+  new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      try {
+        resolve(body ? JSON.parse(body) : {});
+      } catch (error) {
+        reject(error);
+      }
+    });
+    req.on("error", reject);
+  });
+
+const send = (res, status, obj) => {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(obj === undefined ? "" : JSON.stringify(obj));
+};
+
+const runCmd = (cmd, cwd, env, timeoutMs) =>
+  new Promise((resolve) => {
+    exec(
+      cmd,
+      {
+        cwd,
+        env: { ...process.env, ...env },
+        maxBuffer: 64 * 1024 * 1024,
+        timeout: timeoutMs ?? 0,
+      },
+      (err, stdout, stderr) => {
+        const exitCode =
+          err && typeof err.code === "number" ? err.code : err ? 1 : 0;
+        resolve({ exitCode, stderr: String(stderr), stdout: String(stdout) });
+      }
+    );
+  });
+
+createServer(async (req, res) => {
+  try {
+    const url = req.url ?? "/";
+    if (req.method === "GET" && url === "/sbox/health") {
+      return send(res, 200, { ok: true });
+    }
+
+    if (url.startsWith("/aws/lambda-microvms/runtime/v1/")) {
+      return send(res, 200, { ok: true });
+    }
+
+    if (req.method === "POST" && url === "/sbox/exec") {
+      const { cmd, cwd, env, timeoutMs } = await readJson(req);
+      return send(res, 200, await runCmd(cmd, cwd, env, timeoutMs));
+    }
+    if (req.method === "POST" && url === "/sbox/fs/read") {
+      const { path } = await readJson(req);
+      try {
+        const buf = await readFile(path);
+        return send(res, 200, { contentBase64: buf.toString("base64") });
+      } catch {
+        return send(res, 404, { error: "not found" });
+      }
+    }
+    if (req.method === "POST" && url === "/sbox/fs/write") {
+      const { path, contentBase64 } = await readJson(req);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, Buffer.from(contentBase64, "base64"));
+      return send(res, 200, { ok: true });
+    }
+    return send(res, 404, { error: "unknown route" });
+  } catch (error) {
+    return send(res, 500, { error: String(error?.message ?? error) });
+  }
+}).listen(PORT, () => console.log(`[sbox-runner] listening on :${PORT}`));