@sandbox-engine/sdk 0.1.2 → 0.1.4

package/README.md

@@ -70,7 +70,7 @@ Creates and starts a new sandbox. Returns when the sandbox is ready.
 | `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 |
+| `timeout` | `number` | `300000` | Timer duration in ms. Resets on every API call. Use `0` to never expire. |
 
 ---
 
@@ -146,6 +146,19 @@ const ports = await sandbox.ports.list()
 
 ---
 
+### `sandbox.keepalive(timeout?)`
+
+Resets the expiry countdown from now. Use when the orchestrator needs to keep the sandbox alive without doing real work (e.g. an LLM reasoning between steps).
+
+```ts
+await sandbox.keepalive()              // reset with original timeout
+await sandbox.keepalive(10 * 60_000)   // extend to 10 min from now
+```
+
+Any API call (`exec`, `fs`, `ports`, etc.) also resets the timer automatically.
+
+---
+
 ### `sandbox.close()`
 
 Destroys the sandbox and frees all resources. Always call this when done.

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;
 }
 
@@ -31,6 +31,32 @@ interface SandboxOptions {
     dockerfile?: string;
     timeout?: number;
 }
+interface SandboxConnectOptions {
+    serverUrl?: string;
+    apiKey?: string;
+}
+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;
     expiresAt: string;
@@ -99,6 +125,37 @@ 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>;
+}
+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);
@@ -112,7 +169,8 @@ interface SandboxApiResponse {
     status: string;
     template: string;
     createdAt: string;
-    expiresAt: string;
+    timeout: number;
+    expiresAt: string | null;
     agentUrl: string;
     ports: Record<string, number>;
 }
@@ -120,8 +178,15 @@ declare class Sandbox {
     private readonly client;
     readonly id: string;
     readonly fs: Filesystem;
+    readonly processes: ProcessManager;
     private constructor();
+    private static resolveClient;
     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;
@@ -136,7 +201,8 @@ declare class Sandbox {
         unexpose: (containerPort: number) => Promise<void>;
     };
     info(): Promise<SandboxApiResponse>;
+    keepalive(timeout?: number): Promise<SandboxApiResponse>;
     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 FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, ProcessManager, type ProxyEnvResult, Sandbox, type SandboxConnectOptions, type SandboxOptions, type StartProcessOptions, 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;
 }
 
@@ -31,6 +31,32 @@ interface SandboxOptions {
     dockerfile?: string;
     timeout?: number;
 }
+interface SandboxConnectOptions {
+    serverUrl?: string;
+    apiKey?: string;
+}
+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;
     expiresAt: string;
@@ -99,6 +125,37 @@ 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>;
+}
+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);
@@ -112,7 +169,8 @@ interface SandboxApiResponse {
     status: string;
     template: string;
     createdAt: string;
-    expiresAt: string;
+    timeout: number;
+    expiresAt: string | null;
     agentUrl: string;
     ports: Record<string, number>;
 }
@@ -120,8 +178,15 @@ declare class Sandbox {
     private readonly client;
     readonly id: string;
     readonly fs: Filesystem;
+    readonly processes: ProcessManager;
     private constructor();
+    private static resolveClient;
     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;
@@ -136,7 +201,8 @@ declare class Sandbox {
         unexpose: (containerPort: number) => Promise<void>;
     };
     info(): Promise<SandboxApiResponse>;
+    keepalive(timeout?: number): Promise<SandboxApiResponse>;
     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 FileWriteEntry, type FileWriteManyResult, Filesystem, type PortMapping, Process, ProcessManager, type ProxyEnvResult, Sandbox, type SandboxConnectOptions, type SandboxOptions, type StartProcessOptions, 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;
@@ -186,6 +194,89 @@ 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;
+  }
+};
+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 +318,41 @@ 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 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
     });
     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) {
@@ -313,14 +419,22 @@ var Sandbox = class _Sandbox {
   async info() {
     return this.client.get(`/api/sandboxes/${this.id}`);
   }
+  async keepalive(timeout) {
+    return this.client.post(
+      `/api/sandboxes/${this.id}/keepalive`,
+      timeout !== void 0 ? { timeout } : {}
+    );
+  }
   async close() {
     await this.client.delete(`/api/sandboxes/${this.id}`);
   }
 };
 // 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;
@@ -147,6 +153,89 @@ 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;
+  }
+};
+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 +277,41 @@ 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 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
     });
     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) {
@@ -274,13 +378,21 @@ var Sandbox = class _Sandbox {
   async info() {
     return this.client.get(`/api/sandboxes/${this.id}`);
   }
+  async keepalive(timeout) {
+    return this.client.post(
+      `/api/sandboxes/${this.id}/keepalive`,
+      timeout !== void 0 ? { timeout } : {}
+    );
+  }
   async close() {
     await this.client.delete(`/api/sandboxes/${this.id}`);
   }
 };
 export {
+  BackgroundProcess,
   Filesystem,
   Process,
+  ProcessManager,
   Sandbox,
   Terminal
 };

package/package.json

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