@sandbox-engine/sdk 0.1.3 → 0.2.0

package/dist/index.d.mts

@@ -8,7 +8,7 @@ declare class HttpClient {
     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>;
+    delete<T = void>(path: string, query?: Record<string, string>): Promise<T>;
     openWebSocket(path: string): WebSocket;
 }
 
@@ -30,6 +30,52 @@ interface SandboxOptions {
      */
     dockerfile?: string;
     timeout?: number;
+    /** Environment variables injected into the container for the entire session. */
+    env?: Record<string, string>;
+}
+interface SandboxConnectOptions {
+    serverUrl?: string;
+    apiKey?: string;
+}
+interface SandboxListOptions {
+    serverUrl?: string;
+    apiKey?: string;
+}
+interface SandboxSummary {
+    id: string;
+    status: string;
+    template: string;
+    createdAt: string;
+    timeout: number;
+    expiresAt: string | null;
+    agentUrl: string;
+    ports: Record<string, number>;
+}
+interface StreamLogsOptions {
+    onStdout?: (line: string) => void;
+    onStderr?: (line: string) => void;
+}
+interface StartProcessOptions {
+    command?: string;
+    cmd?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    processId?: string;
+}
+interface BackgroundProcessInfo {
+    id: string;
+    pid: number;
+    command: string;
+    status: 'running' | 'exited';
+    exitCode: number | null;
+}
+interface WaitForPortOptions {
+    host?: string;
+    timeout?: number;
+}
+interface WaitForLogOptions {
+    timeout?: number;
 }
 interface ProxyEnvResult {
     proxyBase: string;
@@ -66,6 +112,23 @@ interface FileWriteManyResult {
         error?: string;
     }>;
 }
+interface FileStat {
+    path: string;
+    size: number;
+    mtime: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+interface FileWatchEvent {
+    type: 'change' | 'rename' | 'error';
+    eventType: 'create' | 'modify' | 'delete';
+    path: string;
+    data?: string;
+}
+interface FileWatchOptions {
+    recursive?: boolean;
+    onEvent: (event: FileWatchEvent) => void;
+}
 interface PortMapping {
     containerPort: number;
     hostPort: number;
@@ -90,6 +153,12 @@ declare class Filesystem {
     writeMany(files: FileWriteEntry[]): Promise<FileWriteManyResult>;
     rename(oldPath: string, newPath: string): Promise<void>;
     delete(filePath: string): Promise<void>;
+    stat(filePath: string): Promise<FileStat>;
+    readBytes(filePath: string): Promise<Uint8Array>;
+    writeBytes(filePath: string, data: Uint8Array | Buffer): Promise<void>;
+    watch(dirPath: string, opts: FileWatchOptions): Promise<{
+        close: () => void;
+    }>;
 }
 
 declare class Process extends EventEmitter {
@@ -99,6 +168,40 @@ declare class Process extends EventEmitter {
     wait(): Promise<ExecResult>;
 }
 
+declare class BackgroundProcess {
+    private readonly sandboxId;
+    private readonly client;
+    readonly id: string;
+    readonly pid: number;
+    readonly command: string;
+    constructor(sandboxId: string, client: HttpClient, info: BackgroundProcessInfo);
+    private path;
+    getStatus(): Promise<BackgroundProcessInfo>;
+    getLogs(): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    kill(): Promise<void>;
+    waitForExit(timeout?: number): Promise<{
+        exitCode: number;
+    }>;
+    waitForPort(port: number, opts?: WaitForPortOptions): Promise<void>;
+    waitForLog(pattern: string | RegExp, opts?: WaitForLogOptions): Promise<string>;
+    streamLogs(opts?: StreamLogsOptions): {
+        close: () => void;
+    };
+}
+declare class ProcessManager {
+    private readonly sandboxId;
+    private readonly client;
+    constructor(sandboxId: string, client: HttpClient);
+    start(opts: StartProcessOptions): Promise<BackgroundProcess>;
+    list(): Promise<BackgroundProcessInfo[]>;
+    get(processId: string): Promise<BackgroundProcess>;
+    kill(processId: string): Promise<void>;
+    killAll(): Promise<number>;
+}
+
 declare class Terminal extends EventEmitter {
     private ws;
     constructor(ws: WebSocket);
@@ -121,8 +224,16 @@ declare class Sandbox {
     private readonly client;
     readonly id: string;
     readonly fs: Filesystem;
+    readonly processes: ProcessManager;
     private constructor();
+    private static resolveClient;
+    static list(opts?: SandboxListOptions): Promise<SandboxSummary[]>;
     static create(opts?: SandboxOptions): Promise<Sandbox>;
+    /**
+     * Reconnect to an existing sandbox by ID.
+     * Works after server restart if the container is still running (auto-adopt).
+     */
+    static connect(sandboxId: string, opts?: SandboxConnectOptions): Promise<Sandbox>;
     exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
     exec(cmd: string, opts: ExecOptions & {
         stream: true;
@@ -141,4 +252,4 @@ declare class Sandbox {
     close(): Promise<void>;
 }
 
-export { type ExecOptions, type ExecResult, type FileEntry, type FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, type ProxyEnvResult, Sandbox, type SandboxOptions, Terminal, type WsMessage, type WsMessageType };
+export { BackgroundProcess, type BackgroundProcessInfo, type ExecOptions, type ExecResult, type FileEntry, type FileStat, type FileWatchEvent, type FileWatchOptions, type FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, ProcessManager, type ProxyEnvResult, Sandbox, type SandboxConnectOptions, type SandboxListOptions, type SandboxOptions, type SandboxSummary, type StartProcessOptions, type StreamLogsOptions, Terminal, type WaitForLogOptions, type WaitForPortOptions, type WsMessage, type WsMessageType };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ declare class HttpClient {
     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>;
+    delete<T = void>(path: string, query?: Record<string, string>): Promise<T>;
     openWebSocket(path: string): WebSocket;
 }
 
@@ -30,6 +30,52 @@ interface SandboxOptions {
      */
     dockerfile?: string;
     timeout?: number;
+    /** Environment variables injected into the container for the entire session. */
+    env?: Record<string, string>;
+}
+interface SandboxConnectOptions {
+    serverUrl?: string;
+    apiKey?: string;
+}
+interface SandboxListOptions {
+    serverUrl?: string;
+    apiKey?: string;
+}
+interface SandboxSummary {
+    id: string;
+    status: string;
+    template: string;
+    createdAt: string;
+    timeout: number;
+    expiresAt: string | null;
+    agentUrl: string;
+    ports: Record<string, number>;
+}
+interface StreamLogsOptions {
+    onStdout?: (line: string) => void;
+    onStderr?: (line: string) => void;
+}
+interface StartProcessOptions {
+    command?: string;
+    cmd?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    processId?: string;
+}
+interface BackgroundProcessInfo {
+    id: string;
+    pid: number;
+    command: string;
+    status: 'running' | 'exited';
+    exitCode: number | null;
+}
+interface WaitForPortOptions {
+    host?: string;
+    timeout?: number;
+}
+interface WaitForLogOptions {
+    timeout?: number;
 }
 interface ProxyEnvResult {
     proxyBase: string;
@@ -66,6 +112,23 @@ interface FileWriteManyResult {
         error?: string;
     }>;
 }
+interface FileStat {
+    path: string;
+    size: number;
+    mtime: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+interface FileWatchEvent {
+    type: 'change' | 'rename' | 'error';
+    eventType: 'create' | 'modify' | 'delete';
+    path: string;
+    data?: string;
+}
+interface FileWatchOptions {
+    recursive?: boolean;
+    onEvent: (event: FileWatchEvent) => void;
+}
 interface PortMapping {
     containerPort: number;
     hostPort: number;
@@ -90,6 +153,12 @@ declare class Filesystem {
     writeMany(files: FileWriteEntry[]): Promise<FileWriteManyResult>;
     rename(oldPath: string, newPath: string): Promise<void>;
     delete(filePath: string): Promise<void>;
+    stat(filePath: string): Promise<FileStat>;
+    readBytes(filePath: string): Promise<Uint8Array>;
+    writeBytes(filePath: string, data: Uint8Array | Buffer): Promise<void>;
+    watch(dirPath: string, opts: FileWatchOptions): Promise<{
+        close: () => void;
+    }>;
 }
 
 declare class Process extends EventEmitter {
@@ -99,6 +168,40 @@ declare class Process extends EventEmitter {
     wait(): Promise<ExecResult>;
 }
 
+declare class BackgroundProcess {
+    private readonly sandboxId;
+    private readonly client;
+    readonly id: string;
+    readonly pid: number;
+    readonly command: string;
+    constructor(sandboxId: string, client: HttpClient, info: BackgroundProcessInfo);
+    private path;
+    getStatus(): Promise<BackgroundProcessInfo>;
+    getLogs(): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    kill(): Promise<void>;
+    waitForExit(timeout?: number): Promise<{
+        exitCode: number;
+    }>;
+    waitForPort(port: number, opts?: WaitForPortOptions): Promise<void>;
+    waitForLog(pattern: string | RegExp, opts?: WaitForLogOptions): Promise<string>;
+    streamLogs(opts?: StreamLogsOptions): {
+        close: () => void;
+    };
+}
+declare class ProcessManager {
+    private readonly sandboxId;
+    private readonly client;
+    constructor(sandboxId: string, client: HttpClient);
+    start(opts: StartProcessOptions): Promise<BackgroundProcess>;
+    list(): Promise<BackgroundProcessInfo[]>;
+    get(processId: string): Promise<BackgroundProcess>;
+    kill(processId: string): Promise<void>;
+    killAll(): Promise<number>;
+}
+
 declare class Terminal extends EventEmitter {
     private ws;
     constructor(ws: WebSocket);
@@ -121,8 +224,16 @@ declare class Sandbox {
     private readonly client;
     readonly id: string;
     readonly fs: Filesystem;
+    readonly processes: ProcessManager;
     private constructor();
+    private static resolveClient;
+    static list(opts?: SandboxListOptions): Promise<SandboxSummary[]>;
     static create(opts?: SandboxOptions): Promise<Sandbox>;
+    /**
+     * Reconnect to an existing sandbox by ID.
+     * Works after server restart if the container is still running (auto-adopt).
+     */
+    static connect(sandboxId: string, opts?: SandboxConnectOptions): Promise<Sandbox>;
     exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
     exec(cmd: string, opts: ExecOptions & {
         stream: true;
@@ -141,4 +252,4 @@ declare class Sandbox {
     close(): Promise<void>;
 }
 
-export { type ExecOptions, type ExecResult, type FileEntry, type FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, type ProxyEnvResult, Sandbox, type SandboxOptions, Terminal, type WsMessage, type WsMessageType };
+export { BackgroundProcess, type BackgroundProcessInfo, type ExecOptions, type ExecResult, type FileEntry, type FileStat, type FileWatchEvent, type FileWatchOptions, type FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, ProcessManager, type ProxyEnvResult, Sandbox, type SandboxConnectOptions, type SandboxListOptions, type SandboxOptions, type SandboxSummary, type StartProcessOptions, type StreamLogsOptions, Terminal, type WaitForLogOptions, type WaitForPortOptions, type WsMessage, type WsMessageType };

package/dist/index.js

@@ -30,8 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BackgroundProcess: () => BackgroundProcess,
   Filesystem: () => Filesystem,
   Process: () => Process,
+  ProcessManager: () => ProcessManager,
   Sandbox: () => Sandbox,
   Terminal: () => Terminal
 });
@@ -86,9 +88,15 @@ var HttpClient = class {
       signal: AbortSignal.timeout(3e4)
     });
     if (!res.ok && res.status !== 404) {
-      const text = await res.text();
-      throw new Error(`DELETE ${path} failed (${res.status}): ${text}`);
+      const text2 = await res.text();
+      throw new Error(`DELETE ${path} failed (${res.status}): ${text2}`);
+    }
+    if (res.status === 204 || res.headers.get("content-length") === "0") {
+      return void 0;
     }
+    const text = await res.text();
+    if (!text) return void 0;
+    return JSON.parse(text);
   }
   openWebSocket(path) {
     const wsUrl = this.baseUrl.replace(/^http/, "ws") + path;
@@ -141,6 +149,49 @@ var Filesystem = class {
   async delete(filePath) {
     await this.client.delete(`/api/sandboxes/${this.sandboxId}/files`, { path: filePath });
   }
+  async stat(filePath) {
+    return this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/stat`,
+      { path: filePath }
+    );
+  }
+  async readBytes(filePath) {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/bytes`,
+      { path: filePath }
+    );
+    return Uint8Array.from(Buffer.from(res.data, "base64"));
+  }
+  async writeBytes(filePath, data) {
+    await this.client.post(`/api/sandboxes/${this.sandboxId}/files/bytes`, {
+      path: filePath,
+      data: Buffer.from(data).toString("base64")
+    });
+  }
+  async watch(dirPath, opts) {
+    const ws = this.client.openWebSocket(`/api/sandboxes/${this.sandboxId}/files/watch`);
+    await new Promise((resolve, reject) => {
+      ws.once("open", () => {
+        ws.send(JSON.stringify({ path: dirPath, recursive: opts.recursive ?? false }));
+        resolve();
+      });
+      ws.once("error", reject);
+    });
+    ws.on("message", (raw) => {
+      try {
+        const event = JSON.parse(raw.toString());
+        opts.onEvent(event);
+      } catch {
+      }
+    });
+    return {
+      close: () => {
+        if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+          ws.close();
+        }
+      }
+    };
+  }
 };
 
 // src/process.ts
@@ -186,6 +237,112 @@ var Process = class extends import_node_events.EventEmitter {
   }
 };
 
+// src/background-process.ts
+var BackgroundProcess = class {
+  constructor(sandboxId, client, info) {
+    this.sandboxId = sandboxId;
+    this.client = client;
+    this.id = info.id;
+    this.pid = info.pid;
+    this.command = info.command;
+  }
+  sandboxId;
+  client;
+  id;
+  pid;
+  command;
+  path(suffix) {
+    return `/api/sandboxes/${this.sandboxId}/processes/${this.id}${suffix}`;
+  }
+  async getStatus() {
+    return this.client.get(this.path(""));
+  }
+  async getLogs() {
+    return this.client.get(this.path("/logs"));
+  }
+  async kill() {
+    await this.client.delete(this.path(""));
+  }
+  async waitForExit(timeout) {
+    return this.client.post(this.path("/wait-exit"), { timeout }, (timeout ?? 3e5) + 5e3);
+  }
+  async waitForPort(port, opts = {}) {
+    await this.client.post(
+      this.path("/wait-for-port"),
+      { port, host: opts.host, timeout: opts.timeout },
+      (opts.timeout ?? 3e4) + 5e3
+    );
+  }
+  async waitForLog(pattern, opts = {}) {
+    const patternStr = pattern instanceof RegExp ? pattern.source : pattern;
+    const res = await this.client.post(
+      this.path("/wait-for-log"),
+      { pattern: patternStr, timeout: opts.timeout },
+      (opts.timeout ?? 3e4) + 5e3
+    );
+    return res.match;
+  }
+  streamLogs(opts = {}) {
+    const ws = this.client.openWebSocket(
+      `/api/sandboxes/${this.sandboxId}/processes/logs/stream`
+    );
+    ws.on("open", () => {
+      ws.send(JSON.stringify({ processId: this.id }));
+    });
+    ws.on("message", (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "stdout") opts.onStdout?.(msg.data ?? "");
+        else if (msg.type === "stderr") opts.onStderr?.(msg.data ?? "");
+      } catch {
+      }
+    });
+    return {
+      close: () => {
+        if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+          ws.close();
+        }
+      }
+    };
+  }
+};
+var ProcessManager = class {
+  constructor(sandboxId, client) {
+    this.sandboxId = sandboxId;
+    this.client = client;
+  }
+  sandboxId;
+  client;
+  async start(opts) {
+    const info = await this.client.post(
+      `/api/sandboxes/${this.sandboxId}/processes`,
+      opts
+    );
+    return new BackgroundProcess(this.sandboxId, this.client, info);
+  }
+  async list() {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/processes`
+    );
+    return res.processes;
+  }
+  async get(processId) {
+    const info = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/processes/${processId}`
+    );
+    return new BackgroundProcess(this.sandboxId, this.client, info);
+  }
+  async kill(processId) {
+    await this.client.delete(`/api/sandboxes/${this.sandboxId}/processes/${processId}`);
+  }
+  async killAll() {
+    const res = await this.client.delete(
+      `/api/sandboxes/${this.sandboxId}/processes`
+    );
+    return res?.killed ?? 0;
+  }
+};
+
 // src/terminal.ts
 var import_node_events2 = require("events");
 var Terminal = class extends import_node_events2.EventEmitter {
@@ -227,26 +384,46 @@ var Sandbox = class _Sandbox {
     this.client = client;
     this.id = id;
     this.fs = new Filesystem(id, client);
+    this.processes = new ProcessManager(id, client);
   }
   client;
   id;
   fs;
+  processes;
+  static resolveClient(opts = {}) {
+    const serverUrl = opts.serverUrl ?? process.env.SANDBOX_SERVER_URL ?? "http://localhost:4000";
+    const apiKey = opts.apiKey ?? process.env.SANDBOX_API_KEY ?? "dev-api-key";
+    return new HttpClient(serverUrl, apiKey);
+  }
+  static async list(opts = {}) {
+    const client = _Sandbox.resolveClient(opts);
+    return client.get("/api/sandboxes");
+  }
   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 client = _Sandbox.resolveClient(opts);
     const data = await client.post("/api/sandboxes", {
-      template,
-      dockerfile,
-      timeout
+      template: opts.template,
+      dockerfile: opts.dockerfile,
+      timeout: opts.timeout,
+      env: opts.env
     });
     return new _Sandbox(client, data.id);
   }
+  /**
+   * Reconnect to an existing sandbox by ID.
+   * Works after server restart if the container is still running (auto-adopt).
+   */
+  static async connect(sandboxId, opts = {}) {
+    const client = _Sandbox.resolveClient(opts);
+    const data = await client.post(
+      `/api/sandboxes/${sandboxId}/connect`,
+      {}
+    );
+    if (data.status === "stopped") {
+      throw new Error(`Sandbox ${sandboxId} is stopped`);
+    }
+    return new _Sandbox(client, data.id);
+  }
   async exec(cmd, opts = {}) {
     const { args, cwd, env, timeout, stream } = opts;
     if (stream) {
@@ -325,8 +502,10 @@ var Sandbox = class _Sandbox {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BackgroundProcess,
   Filesystem,
   Process,
+  ProcessManager,
   Sandbox,
   Terminal
 });

package/dist/index.mjs

@@ -47,9 +47,15 @@ var HttpClient = class {
       signal: AbortSignal.timeout(3e4)
     });
     if (!res.ok && res.status !== 404) {
-      const text = await res.text();
-      throw new Error(`DELETE ${path} failed (${res.status}): ${text}`);
+      const text2 = await res.text();
+      throw new Error(`DELETE ${path} failed (${res.status}): ${text2}`);
+    }
+    if (res.status === 204 || res.headers.get("content-length") === "0") {
+      return void 0;
     }
+    const text = await res.text();
+    if (!text) return void 0;
+    return JSON.parse(text);
   }
   openWebSocket(path) {
     const wsUrl = this.baseUrl.replace(/^http/, "ws") + path;
@@ -102,6 +108,49 @@ var Filesystem = class {
   async delete(filePath) {
     await this.client.delete(`/api/sandboxes/${this.sandboxId}/files`, { path: filePath });
   }
+  async stat(filePath) {
+    return this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/stat`,
+      { path: filePath }
+    );
+  }
+  async readBytes(filePath) {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/files/bytes`,
+      { path: filePath }
+    );
+    return Uint8Array.from(Buffer.from(res.data, "base64"));
+  }
+  async writeBytes(filePath, data) {
+    await this.client.post(`/api/sandboxes/${this.sandboxId}/files/bytes`, {
+      path: filePath,
+      data: Buffer.from(data).toString("base64")
+    });
+  }
+  async watch(dirPath, opts) {
+    const ws = this.client.openWebSocket(`/api/sandboxes/${this.sandboxId}/files/watch`);
+    await new Promise((resolve, reject) => {
+      ws.once("open", () => {
+        ws.send(JSON.stringify({ path: dirPath, recursive: opts.recursive ?? false }));
+        resolve();
+      });
+      ws.once("error", reject);
+    });
+    ws.on("message", (raw) => {
+      try {
+        const event = JSON.parse(raw.toString());
+        opts.onEvent(event);
+      } catch {
+      }
+    });
+    return {
+      close: () => {
+        if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+          ws.close();
+        }
+      }
+    };
+  }
 };
 
 // src/process.ts
@@ -147,6 +196,112 @@ var Process = class extends EventEmitter {
   }
 };
 
+// src/background-process.ts
+var BackgroundProcess = class {
+  constructor(sandboxId, client, info) {
+    this.sandboxId = sandboxId;
+    this.client = client;
+    this.id = info.id;
+    this.pid = info.pid;
+    this.command = info.command;
+  }
+  sandboxId;
+  client;
+  id;
+  pid;
+  command;
+  path(suffix) {
+    return `/api/sandboxes/${this.sandboxId}/processes/${this.id}${suffix}`;
+  }
+  async getStatus() {
+    return this.client.get(this.path(""));
+  }
+  async getLogs() {
+    return this.client.get(this.path("/logs"));
+  }
+  async kill() {
+    await this.client.delete(this.path(""));
+  }
+  async waitForExit(timeout) {
+    return this.client.post(this.path("/wait-exit"), { timeout }, (timeout ?? 3e5) + 5e3);
+  }
+  async waitForPort(port, opts = {}) {
+    await this.client.post(
+      this.path("/wait-for-port"),
+      { port, host: opts.host, timeout: opts.timeout },
+      (opts.timeout ?? 3e4) + 5e3
+    );
+  }
+  async waitForLog(pattern, opts = {}) {
+    const patternStr = pattern instanceof RegExp ? pattern.source : pattern;
+    const res = await this.client.post(
+      this.path("/wait-for-log"),
+      { pattern: patternStr, timeout: opts.timeout },
+      (opts.timeout ?? 3e4) + 5e3
+    );
+    return res.match;
+  }
+  streamLogs(opts = {}) {
+    const ws = this.client.openWebSocket(
+      `/api/sandboxes/${this.sandboxId}/processes/logs/stream`
+    );
+    ws.on("open", () => {
+      ws.send(JSON.stringify({ processId: this.id }));
+    });
+    ws.on("message", (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "stdout") opts.onStdout?.(msg.data ?? "");
+        else if (msg.type === "stderr") opts.onStderr?.(msg.data ?? "");
+      } catch {
+      }
+    });
+    return {
+      close: () => {
+        if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+          ws.close();
+        }
+      }
+    };
+  }
+};
+var ProcessManager = class {
+  constructor(sandboxId, client) {
+    this.sandboxId = sandboxId;
+    this.client = client;
+  }
+  sandboxId;
+  client;
+  async start(opts) {
+    const info = await this.client.post(
+      `/api/sandboxes/${this.sandboxId}/processes`,
+      opts
+    );
+    return new BackgroundProcess(this.sandboxId, this.client, info);
+  }
+  async list() {
+    const res = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/processes`
+    );
+    return res.processes;
+  }
+  async get(processId) {
+    const info = await this.client.get(
+      `/api/sandboxes/${this.sandboxId}/processes/${processId}`
+    );
+    return new BackgroundProcess(this.sandboxId, this.client, info);
+  }
+  async kill(processId) {
+    await this.client.delete(`/api/sandboxes/${this.sandboxId}/processes/${processId}`);
+  }
+  async killAll() {
+    const res = await this.client.delete(
+      `/api/sandboxes/${this.sandboxId}/processes`
+    );
+    return res?.killed ?? 0;
+  }
+};
+
 // src/terminal.ts
 import { EventEmitter as EventEmitter2 } from "events";
 var Terminal = class extends EventEmitter2 {
@@ -188,26 +343,46 @@ var Sandbox = class _Sandbox {
     this.client = client;
     this.id = id;
     this.fs = new Filesystem(id, client);
+    this.processes = new ProcessManager(id, client);
   }
   client;
   id;
   fs;
+  processes;
+  static resolveClient(opts = {}) {
+    const serverUrl = opts.serverUrl ?? process.env.SANDBOX_SERVER_URL ?? "http://localhost:4000";
+    const apiKey = opts.apiKey ?? process.env.SANDBOX_API_KEY ?? "dev-api-key";
+    return new HttpClient(serverUrl, apiKey);
+  }
+  static async list(opts = {}) {
+    const client = _Sandbox.resolveClient(opts);
+    return client.get("/api/sandboxes");
+  }
   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 client = _Sandbox.resolveClient(opts);
     const data = await client.post("/api/sandboxes", {
-      template,
-      dockerfile,
-      timeout
+      template: opts.template,
+      dockerfile: opts.dockerfile,
+      timeout: opts.timeout,
+      env: opts.env
     });
     return new _Sandbox(client, data.id);
   }
+  /**
+   * Reconnect to an existing sandbox by ID.
+   * Works after server restart if the container is still running (auto-adopt).
+   */
+  static async connect(sandboxId, opts = {}) {
+    const client = _Sandbox.resolveClient(opts);
+    const data = await client.post(
+      `/api/sandboxes/${sandboxId}/connect`,
+      {}
+    );
+    if (data.status === "stopped") {
+      throw new Error(`Sandbox ${sandboxId} is stopped`);
+    }
+    return new _Sandbox(client, data.id);
+  }
   async exec(cmd, opts = {}) {
     const { args, cwd, env, timeout, stream } = opts;
     if (stream) {
@@ -285,8 +460,10 @@ var Sandbox = class _Sandbox {
   }
 };
 export {
+  BackgroundProcess,
   Filesystem,
   Process,
+  ProcessManager,
   Sandbox,
   Terminal
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandbox-engine/sdk",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "SDK for creating and managing isolated sandbox environments",
   "keywords": ["sandbox", "docker", "code-execution", "isolated", "e2b"],
   "license": "MIT",