@sandbox-engine/sdk 0.1.0

package/README.md

@@ -0,0 +1,168 @@
+# @sandbox-engine/sdk
+
+SDK for creating and managing isolated sandbox environments. Each sandbox is an isolated Docker container with its own filesystem, process namespace, and network — run untrusted code safely.
+
+## Installation
+
+```bash
+npm install @sandbox-engine/sdk
+# or
+pnpm add @sandbox-engine/sdk
+```
+
+## Quick Start
+
+```ts
+import { Sandbox } from '@sandbox-engine/sdk'
+
+const sandbox = await Sandbox.create({
+  serverUrl: 'https://your-sandbox-server.com',
+  apiKey: 'your-api-key',
+})
+
+const result = await sandbox.exec('node', { args: ['-e', 'console.log(1 + 1)'] })
+console.log(result.stdout) // "2\n"
+
+await sandbox.close()
+```
+
+## Configuration via environment variables
+
+Instead of passing `serverUrl` and `apiKey` every time, set environment variables:
+
+```bash
+SANDBOX_SERVER_URL=https://your-sandbox-server.com
+SANDBOX_API_KEY=your-api-key
+```
+
+```ts
+// No options needed — reads from env
+const sandbox = await Sandbox.create()
+```
+
+## Custom environments (Dockerfile)
+
+Define exactly what's installed in your sandbox using a Dockerfile snippet:
+
+```ts
+const sandbox = await Sandbox.create({
+  dockerfile: `
+    RUN npm install -g @anthropic-ai/claude-code typescript
+    RUN pip install numpy pandas matplotlib
+  `,
+})
+
+// First call: builds a Docker image (~seconds to minutes)
+// Subsequent calls with same Dockerfile: instant (cached by content hash)
+```
+
+You don't need a `FROM` — the base sandbox image is automatically prepended.
+
+## API
+
+### `Sandbox.create(opts?)`
+
+Creates and starts a new sandbox. Returns when the sandbox is ready.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serverUrl` | `string` | `$SANDBOX_SERVER_URL` or `localhost:4000` | Sandbox server URL |
+| `apiKey` | `string` | `$SANDBOX_API_KEY` or `dev-api-key` | API key |
+| `template` | `string` | `'base'` | Pre-built Docker image tag |
+| `dockerfile` | `string` | — | Custom Dockerfile content |
+| `timeout` | `number` | `300000` | TTL in ms before auto-destroy |
+
+---
+
+### `sandbox.exec(cmd, opts?)`
+
+Execute a command and wait for it to finish.
+
+```ts
+const result = await sandbox.exec('python3', {
+  args: ['script.py'],
+  cwd: '/app',
+  env: { PYTHONPATH: '/app/lib' },
+  timeout: 30_000,
+})
+console.log(result.stdout)   // string
+console.log(result.stderr)   // string
+console.log(result.exitCode) // number
+```
+
+#### Streaming exec
+
+```ts
+const proc = await sandbox.exec('npm install', { stream: true })
+proc.on('stdout', (data) => process.stdout.write(data))
+proc.on('stderr', (data) => process.stderr.write(data))
+const { exitCode } = await proc.wait()
+```
+
+---
+
+### `sandbox.fs`
+
+```ts
+// Write a file
+await sandbox.fs.write('/app/index.js', 'console.log("hello")')
+
+// Read a file
+const content = await sandbox.fs.read('/app/index.js')
+
+// List a directory
+const files = await sandbox.fs.list('/app')
+// [{ name: 'index.js', path: '/app/index.js', isFile: true, isDirectory: false }]
+
+// Delete a file or directory
+await sandbox.fs.delete('/app/tmp')
+```
+
+---
+
+### `sandbox.terminal()`
+
+Opens an interactive PTY terminal session.
+
+```ts
+const term = await sandbox.terminal()
+
+term.on('data', (data) => process.stdout.write(data))
+term.write('ls -la\n')
+term.resize(120, 40) // cols, rows
+term.close()
+```
+
+---
+
+### `sandbox.ports.list()`
+
+Returns host port mappings for ports exposed by the sandbox (3000–3004).
+
+```ts
+const ports = await sandbox.ports.list()
+// [{ containerPort: 3000, hostPort: 15234, url: 'http://host:15234' }]
+```
+
+---
+
+### `sandbox.close()`
+
+Destroys the sandbox and frees all resources. Always call this when done.
+
+```ts
+await sandbox.close()
+```
+
+## Server setup
+
+The SDK connects to a **sandbox-engine server** you deploy. See the [server repository](https://github.com/your-org/sandbox-engine) for deployment instructions.
+
+### Quick deploy (Ubuntu VPS)
+
+```bash
+# On your VPS
+git clone https://github.com/your-org/sandbox-engine /opt/sandbox-engine
+cd /opt/sandbox-engine
+bash scripts/setup-vps.sh
+```

package/dist/index.d.mts

@@ -0,0 +1,118 @@
+import WebSocket from 'ws';
+import { EventEmitter } from 'node:events';
+
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private headers;
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown, timeoutMs?: number): Promise<T>;
+    delete(path: string, query?: Record<string, string>): Promise<void>;
+    openWebSocket(path: string): WebSocket;
+}
+
+interface SandboxOptions {
+    serverUrl?: string;
+    apiKey?: string;
+    /**
+     * Name of a pre-built Docker image to use as the sandbox environment.
+     * Defaults to 'base' (sandbox-base:latest).
+     */
+    template?: string;
+    /**
+     * Custom Dockerfile content. The server will build a Docker image from it
+     * (using sandbox-base:latest as the base if no FROM is specified) and cache
+     * it by content hash. Subsequent calls with the same Dockerfile skip the build.
+     *
+     * @example
+     * dockerfile: `RUN npm install -g @anthropic-ai/claude-code`
+     */
+    dockerfile?: string;
+    timeout?: number;
+}
+interface ExecOptions {
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    stream?: boolean;
+}
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface FileEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+interface PortMapping {
+    containerPort: number;
+    hostPort: number;
+    url: string;
+}
+type WsMessageType = 'stdout' | 'stderr' | 'exit' | 'error' | 'input' | 'resize';
+interface WsMessage {
+    type: WsMessageType;
+    data?: string;
+    exitCode?: number;
+    cols?: number;
+    rows?: number;
+}
+
+declare class Filesystem {
+    private readonly sandboxId;
+    private readonly client;
+    constructor(sandboxId: string, client: HttpClient);
+    read(filePath: string): Promise<string>;
+    write(filePath: string, content: string): Promise<void>;
+    list(dirPath: string): Promise<FileEntry[]>;
+    delete(filePath: string): Promise<void>;
+}
+
+declare class Process extends EventEmitter {
+    private ws;
+    constructor(ws: WebSocket);
+    kill(): void;
+    wait(): Promise<ExecResult>;
+}
+
+declare class Terminal extends EventEmitter {
+    private ws;
+    constructor(ws: WebSocket);
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    close(): void;
+}
+
+interface SandboxApiResponse {
+    id: string;
+    status: string;
+    template: string;
+    createdAt: string;
+    expiresAt: string;
+    agentUrl: string;
+    ports: Record<string, number>;
+}
+declare class Sandbox {
+    private readonly client;
+    readonly id: string;
+    readonly fs: Filesystem;
+    private constructor();
+    static create(opts?: SandboxOptions): Promise<Sandbox>;
+    exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
+    exec(cmd: string, opts: ExecOptions & {
+        stream: true;
+    }): Promise<Process>;
+    terminal(): Promise<Terminal>;
+    readonly ports: {
+        list: () => Promise<PortMapping[]>;
+    };
+    info(): Promise<SandboxApiResponse>;
+    close(): Promise<void>;
+}
+
+export { type ExecOptions, type ExecResult, type FileEntry, Filesystem, type PortMapping, Process, Sandbox, type SandboxOptions, Terminal, type WsMessage, type WsMessageType };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import WebSocket from 'ws';
+import { EventEmitter } from 'node:events';
+
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private headers;
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown, timeoutMs?: number): Promise<T>;
+    delete(path: string, query?: Record<string, string>): Promise<void>;
+    openWebSocket(path: string): WebSocket;
+}
+
+interface SandboxOptions {
+    serverUrl?: string;
+    apiKey?: string;
+    /**
+     * Name of a pre-built Docker image to use as the sandbox environment.
+     * Defaults to 'base' (sandbox-base:latest).
+     */
+    template?: string;
+    /**
+     * Custom Dockerfile content. The server will build a Docker image from it
+     * (using sandbox-base:latest as the base if no FROM is specified) and cache
+     * it by content hash. Subsequent calls with the same Dockerfile skip the build.
+     *
+     * @example
+     * dockerfile: `RUN npm install -g @anthropic-ai/claude-code`
+     */
+    dockerfile?: string;
+    timeout?: number;
+}
+interface ExecOptions {
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    stream?: boolean;
+}
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface FileEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+interface PortMapping {
+    containerPort: number;
+    hostPort: number;
+    url: string;
+}
+type WsMessageType = 'stdout' | 'stderr' | 'exit' | 'error' | 'input' | 'resize';
+interface WsMessage {
+    type: WsMessageType;
+    data?: string;
+    exitCode?: number;
+    cols?: number;
+    rows?: number;
+}
+
+declare class Filesystem {
+    private readonly sandboxId;
+    private readonly client;
+    constructor(sandboxId: string, client: HttpClient);
+    read(filePath: string): Promise<string>;
+    write(filePath: string, content: string): Promise<void>;
+    list(dirPath: string): Promise<FileEntry[]>;
+    delete(filePath: string): Promise<void>;
+}
+
+declare class Process extends EventEmitter {
+    private ws;
+    constructor(ws: WebSocket);
+    kill(): void;
+    wait(): Promise<ExecResult>;
+}
+
+declare class Terminal extends EventEmitter {
+    private ws;
+    constructor(ws: WebSocket);
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    close(): void;
+}
+
+interface SandboxApiResponse {
+    id: string;
+    status: string;
+    template: string;
+    createdAt: string;
+    expiresAt: string;
+    agentUrl: string;
+    ports: Record<string, number>;
+}
+declare class Sandbox {
+    private readonly client;
+    readonly id: string;
+    readonly fs: Filesystem;
+    private constructor();
+    static create(opts?: SandboxOptions): Promise<Sandbox>;
+    exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
+    exec(cmd: string, opts: ExecOptions & {
+        stream: true;
+    }): Promise<Process>;
+    terminal(): Promise<Terminal>;
+    readonly ports: {
+        list: () => Promise<PortMapping[]>;
+    };
+    info(): Promise<SandboxApiResponse>;
+    close(): Promise<void>;
+}
+
+export { type ExecOptions, type ExecResult, type FileEntry, Filesystem, type PortMapping, Process, Sandbox, type SandboxOptions, Terminal, type WsMessage, type WsMessageType };

package/dist/index.js

@@ -0,0 +1,295 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Filesystem: () => Filesystem,
+  Process: () => Process,
+  Sandbox: () => Sandbox,
+  Terminal: () => Terminal
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_ws = __toESM(require("ws"));
+var HttpClient = class {
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+  baseUrl;
+  apiKey;
+  headers() {
+    return {
+      "content-type": "application/json",
+      authorization: `Bearer ${this.apiKey}`
+    };
+  }
+  async get(path, query) {
+    const qs = query ? "?" + new URLSearchParams(query).toString() : "";
+    const res = await fetch(`${this.baseUrl}${path}${qs}`, {
+      headers: this.headers(),
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`GET ${path} failed (${res.status}): ${body}`);
+    }
+    return res.json();
+  }
+  async post(path, body, timeoutMs = 3e5) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(body ?? {}),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`POST ${path} failed (${res.status}): ${text}`);
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  async delete(path, query) {
+    const qs = query ? "?" + new URLSearchParams(query).toString() : "";
+    const res = await fetch(`${this.baseUrl}${path}${qs}`, {
+      method: "DELETE",
+      headers: this.headers(),
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (!res.ok && res.status !== 404) {
+      const text = await res.text();
+      throw new Error(`DELETE ${path} failed (${res.status}): ${text}`);
+    }
+  }
+  openWebSocket(path) {
+    const wsUrl = this.baseUrl.replace(/^http/, "ws") + path;
+    return new import_ws.default(wsUrl, {
+      headers: { authorization: `Bearer ${this.apiKey}` }
+    });
+  }
+};
+
+// src/filesystem.ts
+var Filesystem = class {
+  constructor(sandboxId, client) {
+    this.sandboxId = sandboxId;
+    this.client = client;
+  }
+  sandboxId;
+  client;
+  async read(filePath) {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files`,
+      { path: filePath }
+    );
+    return res.content;
+  }
+  async write(filePath, content) {
+    await this.client.post(`/api/sandboxes/${this.sandboxId}/files`, {
+      path: filePath,
+      content
+    });
+  }
+  async list(dirPath) {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/list`,
+      { path: dirPath }
+    );
+    return res.files;
+  }
+  async delete(filePath) {
+    await this.client.delete(`/api/sandboxes/${this.sandboxId}/files`, { path: filePath });
+  }
+};
+
+// src/process.ts
+var import_node_events = require("events");
+var Process = class extends import_node_events.EventEmitter {
+  ws;
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    ws.on("message", (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "stdout") this.emit("stdout", msg.data ?? "");
+        else if (msg.type === "stderr") this.emit("stderr", msg.data ?? "");
+        else if (msg.type === "exit") this.emit("exit", msg.exitCode ?? 0);
+        else if (msg.type === "error") this.emit("error", new Error(msg.data));
+      } catch {
+      }
+    });
+    ws.on("error", (err) => this.emit("error", err));
+    ws.on("close", () => this.emit("close"));
+  }
+  kill() {
+    this.ws.close();
+  }
+  wait() {
+    return new Promise((resolve, reject) => {
+      let stdout = "";
+      let stderr = "";
+      let exitCode = 0;
+      this.on("stdout", (data) => {
+        stdout += data;
+      });
+      this.on("stderr", (data) => {
+        stderr += data;
+      });
+      this.on("exit", (code) => {
+        exitCode = code;
+        resolve({ stdout, stderr, exitCode });
+      });
+      this.on("error", reject);
+    });
+  }
+};
+
+// src/terminal.ts
+var import_node_events2 = require("events");
+var Terminal = class extends import_node_events2.EventEmitter {
+  ws;
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    ws.on("message", (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "stdout") this.emit("data", msg.data ?? "");
+        else if (msg.type === "exit") this.emit("exit", msg.exitCode ?? 0);
+      } catch {
+      }
+    });
+    ws.on("error", (err) => this.emit("error", err));
+    ws.on("close", () => this.emit("close"));
+  }
+  write(data) {
+    if (this.ws.readyState === this.ws.OPEN) {
+      const msg = { type: "input", data };
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+  resize(cols, rows) {
+    if (this.ws.readyState === this.ws.OPEN) {
+      const msg = { type: "resize", cols, rows };
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+  close() {
+    this.ws.close();
+  }
+};
+
+// src/sandbox.ts
+var Sandbox = class _Sandbox {
+  constructor(client, id) {
+    this.client = client;
+    this.id = id;
+    this.fs = new Filesystem(id, client);
+  }
+  client;
+  id;
+  fs;
+  static async create(opts = {}) {
+    const {
+      serverUrl = process.env.SANDBOX_SERVER_URL ?? "http://localhost:4000",
+      apiKey = process.env.SANDBOX_API_KEY ?? "dev-api-key",
+      template,
+      dockerfile,
+      timeout
+    } = opts;
+    const client = new HttpClient(serverUrl, apiKey);
+    const data = await client.post("/api/sandboxes", {
+      template,
+      dockerfile,
+      timeout
+    });
+    return new _Sandbox(client, data.id);
+  }
+  async exec(cmd, opts = {}) {
+    const { args, cwd, env, timeout, stream } = opts;
+    if (stream) {
+      const ws = this.client.openWebSocket(`/api/sandboxes/${this.id}/exec/stream`);
+      const proc = new Process(ws);
+      await new Promise((resolve, reject) => {
+        ws.once("open", () => {
+          const req = {
+            type: "input",
+            cmd,
+            args,
+            cwd
+          };
+          ws.send(JSON.stringify(req));
+          resolve();
+        });
+        ws.once("error", reject);
+      });
+      return proc;
+    }
+    return this.client.post(`/api/sandboxes/${this.id}/exec`, {
+      cmd,
+      args,
+      cwd,
+      env,
+      timeout
+    });
+  }
+  async terminal() {
+    const ws = this.client.openWebSocket(`/api/sandboxes/${this.id}/terminal`);
+    await new Promise((resolve, reject) => {
+      ws.once("open", resolve);
+      ws.once("error", reject);
+    });
+    return new Terminal(ws);
+  }
+  ports = {
+    list: async () => {
+      const res = await this.client.get(
+        `/api/sandboxes/${this.id}/ports`
+      );
+      return res.ports;
+    }
+  };
+  async info() {
+    return this.client.get(`/api/sandboxes/${this.id}`);
+  }
+  async close() {
+    await this.client.delete(`/api/sandboxes/${this.id}`);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Filesystem,
+  Process,
+  Sandbox,
+  Terminal
+});

package/dist/index.mjs

@@ -0,0 +1,255 @@
+// src/client.ts
+import WebSocket from "ws";
+var HttpClient = class {
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+  baseUrl;
+  apiKey;
+  headers() {
+    return {
+      "content-type": "application/json",
+      authorization: `Bearer ${this.apiKey}`
+    };
+  }
+  async get(path, query) {
+    const qs = query ? "?" + new URLSearchParams(query).toString() : "";
+    const res = await fetch(`${this.baseUrl}${path}${qs}`, {
+      headers: this.headers(),
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`GET ${path} failed (${res.status}): ${body}`);
+    }
+    return res.json();
+  }
+  async post(path, body, timeoutMs = 3e5) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(body ?? {}),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`POST ${path} failed (${res.status}): ${text}`);
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  async delete(path, query) {
+    const qs = query ? "?" + new URLSearchParams(query).toString() : "";
+    const res = await fetch(`${this.baseUrl}${path}${qs}`, {
+      method: "DELETE",
+      headers: this.headers(),
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (!res.ok && res.status !== 404) {
+      const text = await res.text();
+      throw new Error(`DELETE ${path} failed (${res.status}): ${text}`);
+    }
+  }
+  openWebSocket(path) {
+    const wsUrl = this.baseUrl.replace(/^http/, "ws") + path;
+    return new WebSocket(wsUrl, {
+      headers: { authorization: `Bearer ${this.apiKey}` }
+    });
+  }
+};
+
+// src/filesystem.ts
+var Filesystem = class {
+  constructor(sandboxId, client) {
+    this.sandboxId = sandboxId;
+    this.client = client;
+  }
+  sandboxId;
+  client;
+  async read(filePath) {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files`,
+      { path: filePath }
+    );
+    return res.content;
+  }
+  async write(filePath, content) {
+    await this.client.post(`/api/sandboxes/${this.sandboxId}/files`, {
+      path: filePath,
+      content
+    });
+  }
+  async list(dirPath) {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/list`,
+      { path: dirPath }
+    );
+    return res.files;
+  }
+  async delete(filePath) {
+    await this.client.delete(`/api/sandboxes/${this.sandboxId}/files`, { path: filePath });
+  }
+};
+
+// src/process.ts
+import { EventEmitter } from "events";
+var Process = class extends EventEmitter {
+  ws;
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    ws.on("message", (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "stdout") this.emit("stdout", msg.data ?? "");
+        else if (msg.type === "stderr") this.emit("stderr", msg.data ?? "");
+        else if (msg.type === "exit") this.emit("exit", msg.exitCode ?? 0);
+        else if (msg.type === "error") this.emit("error", new Error(msg.data));
+      } catch {
+      }
+    });
+    ws.on("error", (err) => this.emit("error", err));
+    ws.on("close", () => this.emit("close"));
+  }
+  kill() {
+    this.ws.close();
+  }
+  wait() {
+    return new Promise((resolve, reject) => {
+      let stdout = "";
+      let stderr = "";
+      let exitCode = 0;
+      this.on("stdout", (data) => {
+        stdout += data;
+      });
+      this.on("stderr", (data) => {
+        stderr += data;
+      });
+      this.on("exit", (code) => {
+        exitCode = code;
+        resolve({ stdout, stderr, exitCode });
+      });
+      this.on("error", reject);
+    });
+  }
+};
+
+// src/terminal.ts
+import { EventEmitter as EventEmitter2 } from "events";
+var Terminal = class extends EventEmitter2 {
+  ws;
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    ws.on("message", (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "stdout") this.emit("data", msg.data ?? "");
+        else if (msg.type === "exit") this.emit("exit", msg.exitCode ?? 0);
+      } catch {
+      }
+    });
+    ws.on("error", (err) => this.emit("error", err));
+    ws.on("close", () => this.emit("close"));
+  }
+  write(data) {
+    if (this.ws.readyState === this.ws.OPEN) {
+      const msg = { type: "input", data };
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+  resize(cols, rows) {
+    if (this.ws.readyState === this.ws.OPEN) {
+      const msg = { type: "resize", cols, rows };
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+  close() {
+    this.ws.close();
+  }
+};
+
+// src/sandbox.ts
+var Sandbox = class _Sandbox {
+  constructor(client, id) {
+    this.client = client;
+    this.id = id;
+    this.fs = new Filesystem(id, client);
+  }
+  client;
+  id;
+  fs;
+  static async create(opts = {}) {
+    const {
+      serverUrl = process.env.SANDBOX_SERVER_URL ?? "http://localhost:4000",
+      apiKey = process.env.SANDBOX_API_KEY ?? "dev-api-key",
+      template,
+      dockerfile,
+      timeout
+    } = opts;
+    const client = new HttpClient(serverUrl, apiKey);
+    const data = await client.post("/api/sandboxes", {
+      template,
+      dockerfile,
+      timeout
+    });
+    return new _Sandbox(client, data.id);
+  }
+  async exec(cmd, opts = {}) {
+    const { args, cwd, env, timeout, stream } = opts;
+    if (stream) {
+      const ws = this.client.openWebSocket(`/api/sandboxes/${this.id}/exec/stream`);
+      const proc = new Process(ws);
+      await new Promise((resolve, reject) => {
+        ws.once("open", () => {
+          const req = {
+            type: "input",
+            cmd,
+            args,
+            cwd
+          };
+          ws.send(JSON.stringify(req));
+          resolve();
+        });
+        ws.once("error", reject);
+      });
+      return proc;
+    }
+    return this.client.post(`/api/sandboxes/${this.id}/exec`, {
+      cmd,
+      args,
+      cwd,
+      env,
+      timeout
+    });
+  }
+  async terminal() {
+    const ws = this.client.openWebSocket(`/api/sandboxes/${this.id}/terminal`);
+    await new Promise((resolve, reject) => {
+      ws.once("open", resolve);
+      ws.once("error", reject);
+    });
+    return new Terminal(ws);
+  }
+  ports = {
+    list: async () => {
+      const res = await this.client.get(
+        `/api/sandboxes/${this.id}/ports`
+      );
+      return res.ports;
+    }
+  };
+  async info() {
+    return this.client.get(`/api/sandboxes/${this.id}`);
+  }
+  async close() {
+    await this.client.delete(`/api/sandboxes/${this.id}`);
+  }
+};
+export {
+  Filesystem,
+  Process,
+  Sandbox,
+  Terminal
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@sandbox-engine/sdk",
+  "version": "0.1.0",
+  "description": "SDK for creating and managing isolated sandbox environments",
+  "keywords": ["sandbox", "docker", "code-execution", "isolated", "e2b"],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "ws": "^8.17.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "tsup": "^8.0.2",
+    "vitest": "^1.5.0",
+    "@types/node": "^20.12.7",
+    "@types/ws": "^8.5.10"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}