openlattice-e2b 0.0.3

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export interface E2BProviderConfig {
+    /** E2B API key. Default: reads E2B_API_KEY env var. */
+    apiKey?: string;
+    /** Default template ID. Used when spec.runtime.image matches no known template. */
+    defaultTemplate?: string;
+    /** Map of image strings to E2B template IDs. */
+    templateMap?: Record<string, string>;
+    /** Default sandbox timeout in ms. Default: 300_000 (5 min). */
+    defaultTimeoutMs?: number;
+}

package/dist/config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/e2b-provider.d.ts

@@ -0,0 +1,20 @@
+import type { ComputeProvider, ComputeSpec, ExecOpts, ExecResult, ExtensionMap, HealthStatus, ProviderCapabilities, ProviderNode, ProviderNodeStatus } from "openlattice";
+import type { E2BProviderConfig } from "./config";
+export declare class E2BProvider implements ComputeProvider {
+    readonly name = "e2b";
+    readonly capabilities: ProviderCapabilities;
+    private readonly config;
+    constructor(config?: E2BProviderConfig);
+    provision(spec: ComputeSpec): Promise<ProviderNode>;
+    exec(externalId: string, command: string[], opts?: ExecOpts): Promise<ExecResult>;
+    destroy(externalId: string): Promise<void>;
+    inspect(externalId: string): Promise<ProviderNodeStatus>;
+    pause(externalId: string): Promise<void>;
+    resume(externalId: string): Promise<void>;
+    healthCheck(): Promise<HealthStatus>;
+    getExtension<K extends keyof ExtensionMap>(externalId: string, extension: K): ExtensionMap[K] | undefined;
+    private tailscaleUp;
+    private resolveTemplate;
+    private createFileExtension;
+    private createNetworkExtension;
+}

package/dist/e2b-provider.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.E2BProvider = void 0;
+const e2b_1 = require("e2b");
+const MAX_LIFETIME_SECONDS = 86400; // 24h Pro tier
+const E2B_API_DOMAIN = "api.e2b.dev";
+class E2BProvider {
+    constructor(config = {}) {
+        this.name = "e2b";
+        this.config = config;
+        this.capabilities = {
+            restart: false,
+            pause: true, // via REST API
+            snapshot: false,
+            gpu: false, // Firecracker lacks PCIe passthrough
+            logs: false, // per-command only
+            tailscale: true, // microVM has its own kernel with TUN support
+            coldStartMs: 150,
+            maxConcurrent: 100, // Pro tier
+            architectures: ["x86_64"],
+            persistentStorage: false,
+            constraints: {
+                maxLifetimeSeconds: MAX_LIFETIME_SECONDS,
+            },
+        };
+    }
+    // ── Required methods ────────────────────────────────────────────
+    async provision(spec) {
+        if (spec.gpu && spec.gpu.count > 0) {
+            throw new Error("[e2b] GPU is not supported (Firecracker limitation)");
+        }
+        if (spec.duration?.maxSeconds && spec.duration.maxSeconds > MAX_LIFETIME_SECONDS) {
+            throw new Error(`[e2b] max lifetime is ${MAX_LIFETIME_SECONDS}s (24h), ` +
+                `requested ${spec.duration.maxSeconds}s`);
+        }
+        const template = this.resolveTemplate(spec.runtime.image);
+        const timeoutMs = spec.duration?.maxSeconds != null
+            ? spec.duration.maxSeconds * 1000
+            : this.config.defaultTimeoutMs ?? 300000;
+        const sandbox = await e2b_1.Sandbox.create(template, {
+            apiKey: this.config.apiKey,
+            timeoutMs,
+            envs: spec.runtime.env,
+            metadata: spec.labels,
+        });
+        // Run initial command if specified
+        if (spec.runtime.command && spec.runtime.command.length > 0) {
+            const cmd = spec.runtime.command.join(" ");
+            await sandbox.commands.run(cmd, { background: true });
+        }
+        // Join Tailscale network if auth key provided
+        if (spec.network?.tailscaleAuthKey) {
+            await this.tailscaleUp(sandbox, spec.network.tailscaleAuthKey);
+        }
+        return {
+            externalId: sandbox.sandboxId,
+            endpoints: [],
+            metadata: { templateId: template },
+        };
+    }
+    async exec(externalId, command, opts) {
+        const sandbox = await e2b_1.Sandbox.connect(externalId, {
+            apiKey: this.config.apiKey,
+        });
+        const cmd = command.join(" ");
+        const result = await sandbox.commands.run(cmd, {
+            cwd: opts?.cwd,
+            envs: opts?.env,
+            timeoutMs: opts?.timeoutMs ?? 0,
+            onStdout: opts?.onStdout
+                ? (data) => opts.onStdout(data)
+                : undefined,
+            onStderr: opts?.onStderr
+                ? (data) => opts.onStderr(data)
+                : undefined,
+        });
+        return {
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    }
+    async destroy(externalId) {
+        try {
+            await e2b_1.Sandbox.kill(externalId, {
+                apiKey: this.config.apiKey,
+            });
+        }
+        catch (err) {
+            // If the sandbox is already gone, treat as idempotent
+            if (isNotFoundError(err))
+                return;
+            throw new Error(`[e2b] destroy failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async inspect(externalId) {
+        try {
+            const sandboxes = await e2b_1.Sandbox.list({
+                apiKey: this.config.apiKey,
+            });
+            const match = sandboxes.find((s) => s.sandboxId === externalId);
+            if (!match) {
+                return { status: "terminated" };
+            }
+            const status = match.state === "paused" ? "paused" : "running";
+            return {
+                status,
+                startedAt: match.startedAt ? new Date(match.startedAt) : undefined,
+                resources: {
+                    cpuPercent: undefined,
+                    memoryUsedMiB: match.memoryMB,
+                },
+            };
+        }
+        catch (err) {
+            if (isNotFoundError(err)) {
+                return { status: "terminated" };
+            }
+            throw err;
+        }
+    }
+    // ── Optional: pause / resume ────────────────────────────────────
+    async pause(externalId) {
+        // The e2b SDK v1.13 doesn't expose pause() on Sandbox instances,
+        // so we call the REST API directly.
+        const apiKey = this.config.apiKey ?? process.env.E2B_API_KEY;
+        if (!apiKey) {
+            throw new Error("[e2b] API key required for pause");
+        }
+        const response = await fetch(`https://${E2B_API_DOMAIN}/sandboxes/${externalId}/pause`, {
+            method: "POST",
+            headers: {
+                "X-API-Key": apiKey,
+            },
+        });
+        if (!response.ok && response.status !== 204) {
+            throw new Error(`[e2b] pause failed: ${response.status} ${response.statusText}`);
+        }
+    }
+    async resume(externalId) {
+        // Connecting to a paused sandbox auto-resumes it
+        await e2b_1.Sandbox.connect(externalId, {
+            apiKey: this.config.apiKey,
+        });
+    }
+    // ── Optional: healthCheck ───────────────────────────────────────
+    async healthCheck() {
+        const start = Date.now();
+        try {
+            await e2b_1.Sandbox.list({ apiKey: this.config.apiKey });
+            return {
+                healthy: true,
+                latencyMs: Date.now() - start,
+            };
+        }
+        catch (err) {
+            return {
+                healthy: false,
+                message: err instanceof Error ? err.message : String(err),
+                latencyMs: Date.now() - start,
+            };
+        }
+    }
+    // ── Optional: extensions ────────────────────────────────────────
+    getExtension(externalId, extension) {
+        if (extension === "files") {
+            return this.createFileExtension(externalId);
+        }
+        if (extension === "network") {
+            return this.createNetworkExtension(externalId);
+        }
+        return undefined;
+    }
+    // ── Private helpers ─────────────────────────────────────────────
+    async tailscaleUp(sandbox, authKey) {
+        const result = await sandbox.commands.run(`pgrep tailscaled >/dev/null 2>&1 || tailscaled --state=/var/lib/tailscale/tailscaled.state & sleep 1 && tailscale up --authkey=${authKey}`, { timeoutMs: 30000 });
+        if (result.exitCode !== 0) {
+            throw new Error(`[e2b] tailscale up failed: ${result.stderr.trim()}`);
+        }
+    }
+    resolveTemplate(image) {
+        // 1. Check explicit template map
+        if (this.config.templateMap && image in this.config.templateMap) {
+            return this.config.templateMap[image];
+        }
+        // 2. If it looks like an E2B template ID (no / or :), use directly
+        if (!image.includes("/") && !image.includes(":")) {
+            return image;
+        }
+        // 3. Fall back to default template
+        if (this.config.defaultTemplate) {
+            return this.config.defaultTemplate;
+        }
+        throw new Error(`[e2b] cannot resolve template for image "${image}". ` +
+            "Provide a templateMap entry, a valid E2B template ID, or set defaultTemplate.");
+    }
+    createFileExtension(externalId) {
+        const apiKey = this.config.apiKey;
+        return {
+            async read(path) {
+                const sandbox = await e2b_1.Sandbox.connect(externalId, { apiKey });
+                return await sandbox.files.read(path, { format: "text" });
+            },
+            async write(path, content) {
+                const sandbox = await e2b_1.Sandbox.connect(externalId, { apiKey });
+                await sandbox.files.write(path, content.toString());
+            },
+            async list(dirPath) {
+                const sandbox = await e2b_1.Sandbox.connect(externalId, { apiKey });
+                const entries = await sandbox.files.list(dirPath);
+                return entries.map((e) => ({
+                    name: e.name,
+                    path: e.path ?? `${dirPath}/${e.name}`,
+                    type: e.type === "dir" ? "directory" : "file",
+                    size: e.size,
+                }));
+            },
+            async remove(path) {
+                const sandbox = await e2b_1.Sandbox.connect(externalId, { apiKey });
+                await sandbox.files.remove(path);
+            },
+            async mkdir(path) {
+                const sandbox = await e2b_1.Sandbox.connect(externalId, { apiKey });
+                await sandbox.files.makeDir(path);
+            },
+        };
+    }
+    createNetworkExtension(externalId) {
+        const apiKey = this.config.apiKey;
+        return {
+            async getUrl(port) {
+                const sandbox = await e2b_1.Sandbox.connect(externalId, { apiKey });
+                const host = sandbox.getHost(port);
+                return `https://${host}`;
+            },
+        };
+    }
+}
+exports.E2BProvider = E2BProvider;
+// ── Utility functions ───────────────────────────────────────────────
+function isNotFoundError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    // E2B SDK throws NotFoundError for missing sandboxes
+    if ("statusCode" in err && err.statusCode === 404) {
+        return true;
+    }
+    if (err instanceof Error && err.constructor.name === "NotFoundError") {
+        return true;
+    }
+    if (err instanceof Error && /not found|does not exist/i.test(err.message)) {
+        return true;
+    }
+    return false;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { E2BProvider } from "./e2b-provider";
+export type { E2BProviderConfig } from "./config";

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.E2BProvider = void 0;
+var e2b_provider_1 = require("./e2b-provider");
+Object.defineProperty(exports, "E2BProvider", { enumerable: true, get: function () { return e2b_provider_1.E2BProvider; } });

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "openlattice-e2b",
+  "version": "0.0.3",
+  "description": "E2B compute provider for OpenLattice",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:integration": "E2B_API_KEY=$E2B_API_KEY vitest run tests/integration.test.ts tests/conformance.test.ts"
+  },
+  "keywords": [
+    "compute",
+    "e2b",
+    "openlattice",
+    "provider",
+    "sandbox"
+  ],
+  "license": "ISC",
+  "peerDependencies": {
+    "openlattice": "^0.0.3"
+  },
+  "dependencies": {
+    "e2b": "^1.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "openlattice": "^0.0.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/config.ts

@@ -0,0 +1,13 @@
+export interface E2BProviderConfig {
+  /** E2B API key. Default: reads E2B_API_KEY env var. */
+  apiKey?: string;
+
+  /** Default template ID. Used when spec.runtime.image matches no known template. */
+  defaultTemplate?: string;
+
+  /** Map of image strings to E2B template IDs. */
+  templateMap?: Record<string, string>;
+
+  /** Default sandbox timeout in ms. Default: 300_000 (5 min). */
+  defaultTimeoutMs?: number;
+}

package/src/e2b-provider.ts

@@ -0,0 +1,332 @@
+import { Sandbox } from "e2b";
+import type {
+  ComputeProvider,
+  ComputeSpec,
+  ExecOpts,
+  ExecResult,
+  ExtensionMap,
+  FileEntry,
+  FileExtension,
+  HealthStatus,
+  NetworkExtension,
+  ProviderCapabilities,
+  ProviderNode,
+  ProviderNodeStatus,
+} from "openlattice";
+import type { E2BProviderConfig } from "./config";
+
+const MAX_LIFETIME_SECONDS = 86_400; // 24h Pro tier
+const E2B_API_DOMAIN = "api.e2b.dev";
+
+export class E2BProvider implements ComputeProvider {
+  readonly name = "e2b";
+  readonly capabilities: ProviderCapabilities;
+  private readonly config: E2BProviderConfig;
+
+  constructor(config: E2BProviderConfig = {}) {
+    this.config = config;
+    this.capabilities = {
+      restart: false,
+      pause: true, // via REST API
+      snapshot: false,
+      gpu: false, // Firecracker lacks PCIe passthrough
+      logs: false, // per-command only
+      tailscale: true, // microVM has its own kernel with TUN support
+      coldStartMs: 150,
+      maxConcurrent: 100, // Pro tier
+      architectures: ["x86_64"],
+      persistentStorage: false,
+      constraints: {
+        maxLifetimeSeconds: MAX_LIFETIME_SECONDS,
+      },
+    };
+  }
+
+  // ── Required methods ────────────────────────────────────────────
+
+  async provision(spec: ComputeSpec): Promise<ProviderNode> {
+    if (spec.gpu && spec.gpu.count > 0) {
+      throw new Error("[e2b] GPU is not supported (Firecracker limitation)");
+    }
+
+    if (spec.duration?.maxSeconds && spec.duration.maxSeconds > MAX_LIFETIME_SECONDS) {
+      throw new Error(
+        `[e2b] max lifetime is ${MAX_LIFETIME_SECONDS}s (24h), ` +
+          `requested ${spec.duration.maxSeconds}s`
+      );
+    }
+
+    const template = this.resolveTemplate(spec.runtime.image);
+    const timeoutMs =
+      spec.duration?.maxSeconds != null
+        ? spec.duration.maxSeconds * 1000
+        : this.config.defaultTimeoutMs ?? 300_000;
+
+    const sandbox = await Sandbox.create(template, {
+      apiKey: this.config.apiKey,
+      timeoutMs,
+      envs: spec.runtime.env,
+      metadata: spec.labels,
+    });
+
+    // Run initial command if specified
+    if (spec.runtime.command && spec.runtime.command.length > 0) {
+      const cmd = spec.runtime.command.join(" ");
+      await sandbox.commands.run(cmd, { background: true });
+    }
+
+    // Join Tailscale network if auth key provided
+    if (spec.network?.tailscaleAuthKey) {
+      await this.tailscaleUp(sandbox, spec.network.tailscaleAuthKey);
+    }
+
+    return {
+      externalId: sandbox.sandboxId,
+      endpoints: [],
+      metadata: { templateId: template },
+    };
+  }
+
+  async exec(
+    externalId: string,
+    command: string[],
+    opts?: ExecOpts
+  ): Promise<ExecResult> {
+    const sandbox = await Sandbox.connect(externalId, {
+      apiKey: this.config.apiKey,
+    });
+
+    const cmd = command.join(" ");
+
+    const result = await sandbox.commands.run(cmd, {
+      cwd: opts?.cwd,
+      envs: opts?.env,
+      timeoutMs: opts?.timeoutMs ?? 0,
+      onStdout: opts?.onStdout
+        ? (data: string) => opts.onStdout!(data)
+        : undefined,
+      onStderr: opts?.onStderr
+        ? (data: string) => opts.onStderr!(data)
+        : undefined,
+    });
+
+    return {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  }
+
+  async destroy(externalId: string): Promise<void> {
+    try {
+      await Sandbox.kill(externalId, {
+        apiKey: this.config.apiKey,
+      });
+    } catch (err: unknown) {
+      // If the sandbox is already gone, treat as idempotent
+      if (isNotFoundError(err)) return;
+      throw new Error(
+        `[e2b] destroy failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
+  async inspect(externalId: string): Promise<ProviderNodeStatus> {
+    try {
+      const sandboxes = await Sandbox.list({
+        apiKey: this.config.apiKey,
+      });
+
+      const match = sandboxes.find(
+        (s) => s.sandboxId === externalId
+      );
+
+      if (!match) {
+        return { status: "terminated" };
+      }
+
+      const status = match.state === "paused" ? "paused" : "running";
+
+      return {
+        status,
+        startedAt: match.startedAt ? new Date(match.startedAt) : undefined,
+        resources: {
+          cpuPercent: undefined,
+          memoryUsedMiB: match.memoryMB,
+        },
+      };
+    } catch (err: unknown) {
+      if (isNotFoundError(err)) {
+        return { status: "terminated" };
+      }
+      throw err;
+    }
+  }
+
+  // ── Optional: pause / resume ────────────────────────────────────
+
+  async pause(externalId: string): Promise<void> {
+    // The e2b SDK v1.13 doesn't expose pause() on Sandbox instances,
+    // so we call the REST API directly.
+    const apiKey = this.config.apiKey ?? process.env.E2B_API_KEY;
+    if (!apiKey) {
+      throw new Error("[e2b] API key required for pause");
+    }
+
+    const response = await fetch(
+      `https://${E2B_API_DOMAIN}/sandboxes/${externalId}/pause`,
+      {
+        method: "POST",
+        headers: {
+          "X-API-Key": apiKey,
+        },
+      }
+    );
+
+    if (!response.ok && response.status !== 204) {
+      throw new Error(
+        `[e2b] pause failed: ${response.status} ${response.statusText}`
+      );
+    }
+  }
+
+  async resume(externalId: string): Promise<void> {
+    // Connecting to a paused sandbox auto-resumes it
+    await Sandbox.connect(externalId, {
+      apiKey: this.config.apiKey,
+    });
+  }
+
+  // ── Optional: healthCheck ───────────────────────────────────────
+
+  async healthCheck(): Promise<HealthStatus> {
+    const start = Date.now();
+    try {
+      await Sandbox.list({ apiKey: this.config.apiKey });
+      return {
+        healthy: true,
+        latencyMs: Date.now() - start,
+      };
+    } catch (err: unknown) {
+      return {
+        healthy: false,
+        message: err instanceof Error ? err.message : String(err),
+        latencyMs: Date.now() - start,
+      };
+    }
+  }
+
+  // ── Optional: extensions ────────────────────────────────────────
+
+  getExtension<K extends keyof ExtensionMap>(
+    externalId: string,
+    extension: K
+  ): ExtensionMap[K] | undefined {
+    if (extension === "files") {
+      return this.createFileExtension(externalId) as ExtensionMap[K];
+    }
+    if (extension === "network") {
+      return this.createNetworkExtension(externalId) as ExtensionMap[K];
+    }
+    return undefined;
+  }
+
+  // ── Private helpers ─────────────────────────────────────────────
+
+  private async tailscaleUp(
+    sandbox: InstanceType<typeof Sandbox>,
+    authKey: string
+  ): Promise<void> {
+    const result = await sandbox.commands.run(
+      `pgrep tailscaled >/dev/null 2>&1 || tailscaled --state=/var/lib/tailscale/tailscaled.state & sleep 1 && tailscale up --authkey=${authKey}`,
+      { timeoutMs: 30_000 }
+    );
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `[e2b] tailscale up failed: ${result.stderr.trim()}`
+      );
+    }
+  }
+
+  private resolveTemplate(image: string): string {
+    // 1. Check explicit template map
+    if (this.config.templateMap && image in this.config.templateMap) {
+      return this.config.templateMap[image];
+    }
+
+    // 2. If it looks like an E2B template ID (no / or :), use directly
+    if (!image.includes("/") && !image.includes(":")) {
+      return image;
+    }
+
+    // 3. Fall back to default template
+    if (this.config.defaultTemplate) {
+      return this.config.defaultTemplate;
+    }
+
+    throw new Error(
+      `[e2b] cannot resolve template for image "${image}". ` +
+        "Provide a templateMap entry, a valid E2B template ID, or set defaultTemplate."
+    );
+  }
+
+  private createFileExtension(externalId: string): FileExtension {
+    const apiKey = this.config.apiKey;
+    return {
+      async read(path: string): Promise<string | Buffer> {
+        const sandbox = await Sandbox.connect(externalId, { apiKey });
+        return await sandbox.files.read(path, { format: "text" });
+      },
+      async write(path: string, content: string | Buffer): Promise<void> {
+        const sandbox = await Sandbox.connect(externalId, { apiKey });
+        await sandbox.files.write(path, content.toString());
+      },
+      async list(dirPath: string): Promise<FileEntry[]> {
+        const sandbox = await Sandbox.connect(externalId, { apiKey });
+        const entries = await sandbox.files.list(dirPath);
+        return entries.map((e) => ({
+          name: e.name,
+          path: e.path ?? `${dirPath}/${e.name}`,
+          type: e.type === "dir" ? ("directory" as const) : ("file" as const),
+          size: e.size,
+        }));
+      },
+      async remove(path: string): Promise<void> {
+        const sandbox = await Sandbox.connect(externalId, { apiKey });
+        await sandbox.files.remove(path);
+      },
+      async mkdir(path: string): Promise<void> {
+        const sandbox = await Sandbox.connect(externalId, { apiKey });
+        await sandbox.files.makeDir(path);
+      },
+    };
+  }
+
+  private createNetworkExtension(externalId: string): NetworkExtension {
+    const apiKey = this.config.apiKey;
+    return {
+      async getUrl(port: number): Promise<string> {
+        const sandbox = await Sandbox.connect(externalId, { apiKey });
+        const host = sandbox.getHost(port);
+        return `https://${host}`;
+      },
+    };
+  }
+}
+
+// ── Utility functions ───────────────────────────────────────────────
+
+function isNotFoundError(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) return false;
+  // E2B SDK throws NotFoundError for missing sandboxes
+  if ("statusCode" in err && (err as { statusCode: number }).statusCode === 404) {
+    return true;
+  }
+  if (err instanceof Error && err.constructor.name === "NotFoundError") {
+    return true;
+  }
+  if (err instanceof Error && /not found|does not exist/i.test(err.message)) {
+    return true;
+  }
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { E2BProvider } from "./e2b-provider";
+export type { E2BProviderConfig } from "./config";