@vercel/sandbox 0.0.20 → 0.0.22

package/dist/sandbox.js

@@ -35,7 +35,10 @@ class Sandbox {
             teamId: credentials.teamId,
             token: credentials.token,
         });
-        return client.listSandboxes(params);
+        return client.listSandboxes({
+            ...params,
+            signal: params.signal,
+        });
     }
     /**
      * Create a new sandbox.
@@ -57,6 +60,7 @@ class Sandbox {
             timeout: params?.timeout,
             resources: params?.resources,
             runtime: params?.runtime,
+            signal: params?.signal,
             ...privateParams,
         });
         return new Sandbox({
@@ -79,6 +83,7 @@ class Sandbox {
         });
         const sandbox = await client.getSandbox({
             sandboxId: params.sandboxId,
+            signal: params.signal,
         });
         return new Sandbox({
             client,
@@ -102,12 +107,15 @@ class Sandbox {
      * Get a previously run command by its ID.
      *
      * @param cmdId - ID of the command to retrieve
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A {@link Command} instance representing the command
      */
-    async getCommand(cmdId) {
+    async getCommand(cmdId, opts) {
         const command = await this.client.getCommand({
             sandboxId: this.sandbox.id,
             cmdId,
+            signal: opts?.signal,
         });
         return new command_1.Command({
             client: this.client,
@@ -115,9 +123,9 @@ class Sandbox {
             cmd: command.json.command,
         });
     }
-    async runCommand(commandOrParams, args) {
+    async runCommand(commandOrParams, args, opts) {
         return typeof commandOrParams === "string"
-            ? this._runCommand({ cmd: commandOrParams, args })
+            ? this._runCommand({ cmd: commandOrParams, args, signal: opts?.signal })
             : this._runCommand(commandOrParams);
     }
     /**
@@ -135,6 +143,7 @@ class Sandbox {
             cwd: params.cwd,
             env: params.env ?? {},
             sudo: params.sudo ?? false,
+            signal: params.signal,
         });
         const command = new command_1.Command({
             client: this.client,
@@ -143,7 +152,7 @@ class Sandbox {
         });
         if (params.stdout || params.stderr) {
             (async () => {
-                for await (const log of command.logs()) {
+                for await (const log of command.logs({ signal: params.signal })) {
                     if (log.stream === "stdout") {
                         params.stdout?.write(log.data);
                     }
@@ -153,30 +162,36 @@ class Sandbox {
                 }
             })();
         }
-        return params.detached ? command : command.wait();
+        return params.detached ? command : command.wait({ signal: params.signal });
     }
     /**
      * Create a directory in the filesystem of this sandbox.
      *
      * @param path - Path of the directory to create
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      */
-    async mkDir(path) {
+    async mkDir(path, opts) {
         await this.client.mkDir({
             sandboxId: this.sandbox.id,
             path: path,
+            signal: opts?.signal,
         });
     }
     /**
      * Read a file from the filesystem of this sandbox.
      *
      * @param file - File to read, with path and optional cwd
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves to a ReadableStream containing the file contents
      */
-    async readFile(file) {
+    async readFile(file, opts) {
         return this.client.readFile({
             sandboxId: this.sandbox.id,
             path: file.path,
             cwd: file.cwd,
+            signal: opts?.signal,
         });
     }
     /**
@@ -185,14 +200,17 @@ class Sandbox {
      * Writes files using the `vercel-sandbox` user.
      *
      * @param files - Array of files with path and stream/buffer contents
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves when the files are written
      */
-    async writeFiles(files) {
+    async writeFiles(files, opts) {
         return this.client.writeFiles({
             sandboxId: this.sandbox.id,
             cwd: this.sandbox.cwd,
             extractDir: "/",
             files: files,
+            signal: opts?.signal,
         });
     }
     /**
@@ -214,11 +232,14 @@ class Sandbox {
     /**
      * Stop the sandbox.
      *
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves when the sandbox is stopped
      */
-    async stop() {
+    async stop(opts) {
         await this.client.stopSandbox({
             sandboxId: this.sandbox.id,
+            signal: opts?.signal,
         });
     }
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.20";
+export declare const VERSION = "0.0.22";

package/dist/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Autogenerated by inject-version.ts
-exports.VERSION = "0.0.20";
+exports.VERSION = "0.0.22";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,7 @@
     "jsonlines": "0.1.1",
     "ms": "2.1.3",
     "tar-stream": "3.1.7",
+    "undici": "^7.16.0",
     "zod": "3.24.4"
   },
   "devDependencies": {

package/src/api-client/api-client.ts

@@ -71,10 +71,12 @@ export class APIClient extends BaseClient {
     });
   }
 
-  async getSandbox(params: { sandboxId: string }) {
+  async getSandbox(params: { sandboxId: string; signal?: AbortSignal }) {
     return parseOrThrow(
       SandboxAndRoutesResponse,
-      await this.request(`/v1/sandboxes/${params.sandboxId}`),
+      await this.request(`/v1/sandboxes/${params.sandboxId}`, {
+        signal: params.signal,
+      }),
     );
   }
 
@@ -95,6 +97,7 @@ export class APIClient extends BaseClient {
       timeout?: number;
       resources?: { vcpus: number };
       runtime?: "node22" | "python3.13" | (string & {});
+      signal?: AbortSignal;
     }>,
   ) {
     const privateParams = getPrivateParams(params);
@@ -111,6 +114,7 @@ export class APIClient extends BaseClient {
           runtime: params.runtime,
           ...privateParams,
         }),
+        signal: params.signal,
       }),
     );
   }
@@ -122,6 +126,7 @@ export class APIClient extends BaseClient {
     args: string[];
     env: Record<string, string>;
     sudo: boolean;
+    signal?: AbortSignal;
   }) {
     return parseOrThrow(
       CommandResponse,
@@ -134,6 +139,7 @@ export class APIClient extends BaseClient {
           env: params.env,
           sudo: params.sudo,
         }),
+        signal: params.signal,
       }),
     );
   }
@@ -142,44 +148,58 @@ export class APIClient extends BaseClient {
     sandboxId: string;
     cmdId: string;
     wait: true;
+    signal?: AbortSignal;
   }): Promise<Parsed<z.infer<typeof CommandFinishedResponse>>>;
   async getCommand(params: {
     sandboxId: string;
     cmdId: string;
     wait?: boolean;
+    signal?: AbortSignal;
   }): Promise<Parsed<z.infer<typeof CommandResponse>>>;
   async getCommand(params: {
     sandboxId: string;
     cmdId: string;
     wait?: boolean;
+    signal?: AbortSignal;
   }) {
     return params.wait
       ? parseOrThrow(
           CommandFinishedResponse,
           await this.request(
             `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
-            { query: { wait: "true" } },
+            { signal: params.signal, query: { wait: "true" } },
           ),
         )
       : parseOrThrow(
           CommandResponse,
           await this.request(
             `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
+            { signal: params.signal },
           ),
         );
   }
 
-  async mkDir(params: { sandboxId: string; path: string; cwd?: string }) {
+  async mkDir(params: {
+    sandboxId: string;
+    path: string;
+    cwd?: string;
+    signal?: AbortSignal;
+  }) {
     return parseOrThrow(
       EmptyResponse,
       await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
         method: "POST",
         body: JSON.stringify({ path: params.path, cwd: params.cwd }),
+        signal: params.signal,
       }),
     );
   }
 
-  getFileWriter(params: { sandboxId: string; extractDir: string }) {
+  getFileWriter(params: {
+    sandboxId: string;
+    extractDir: string;
+    signal?: AbortSignal;
+  }) {
     const writer = new FileWriter();
     return {
       response: (async () => {
@@ -190,6 +210,7 @@ export class APIClient extends BaseClient {
             "x-cwd": params.extractDir,
           },
           body: await consumeReadable(writer.readable),
+          signal: params.signal,
         });
       })(),
       writer,
@@ -217,6 +238,7 @@ export class APIClient extends BaseClient {
      * @example 1540095775951
      */
     until?: number | Date;
+    signal?: AbortSignal;
   }) {
     return parseOrThrow(
       SandboxesResponse,
@@ -234,6 +256,7 @@ export class APIClient extends BaseClient {
               : params.until?.getTime(),
         },
         method: "GET",
+        signal: params.signal,
       }),
     );
   }
@@ -243,10 +266,12 @@ export class APIClient extends BaseClient {
     cwd: string;
     files: { path: string; content: Buffer }[];
     extractDir: string;
+    signal?: AbortSignal;
   }) {
     const { writer, response } = this.getFileWriter({
       sandboxId: params.sandboxId,
       extractDir: params.extractDir,
+      signal: params.signal,
     });
 
     for (const file of params.files) {
@@ -268,12 +293,14 @@ export class APIClient extends BaseClient {
     sandboxId: string;
     path: string;
     cwd?: string;
+    signal?: AbortSignal;
   }): Promise<NodeJS.ReadableStream | null> {
     const response = await this.request(
       `/v1/sandboxes/${params.sandboxId}/fs/read`,
       {
         method: "POST",
         body: JSON.stringify({ path: params.path, cwd: params.cwd }),
+        signal: params.signal,
       },
     );
 
@@ -292,6 +319,7 @@ export class APIClient extends BaseClient {
     sandboxId: string;
     commandId: string;
     signal: number;
+    abortSignal?: AbortSignal;
   }) {
     return parseOrThrow(
       CommandResponse,
@@ -300,6 +328,7 @@ export class APIClient extends BaseClient {
         {
           method: "POST",
           body: JSON.stringify({ signal: params.signal }),
+          signal: params.abortSignal,
         },
       ),
     );
@@ -356,11 +385,12 @@ export class APIClient extends BaseClient {
 
   async stopSandbox(params: {
     sandboxId: string;
+    signal?: AbortSignal;
   }): Promise<Parsed<z.infer<typeof SandboxResponse>>> {
     const url = `/v1/sandboxes/${params.sandboxId}/stop`;
     return parseOrThrow(
       SandboxResponse,
-      await this.request(url, { method: "POST" }),
+      await this.request(url, { method: "POST", signal: params.signal }),
     );
   }
 }

package/src/api-client/base-client.ts

@@ -3,6 +3,7 @@ import { APIError } from "./api-error";
 import { ZodType } from "zod";
 import { array } from "../utils/array";
 import { withRetry, type RequestOptions } from "./with-retry";
+import { Agent } from "undici";
 
 export interface RequestParams extends RequestInit {
   headers?: Record<string, string>;
@@ -22,12 +23,16 @@ export class BaseClient {
   private fetch: ReturnType<typeof withRetry<RequestInit>>;
   private debug: boolean;
   private host: string;
+  private agent: Agent;
 
   constructor(params: { debug?: boolean; host: string; token?: string }) {
     this.fetch = withRetry(globalThis.fetch);
     this.host = params.host;
     this.debug = params.debug ?? process.env.DEBUG_FETCH === "true";
     this.token = params.token;
+    this.agent = new Agent({
+      bodyTimeout: 0, // disable body timeout to allow long logs streaming
+    });
   }
 
   protected async request(path: string, opts?: RequestParams) {
@@ -48,6 +53,9 @@ export class BaseClient {
       headers: this.token
         ? { Authorization: `Bearer ${this.token}`, ...opts?.headers }
         : opts?.headers,
+      // @ts-expect-error Node.js' and undici's Agent have different types
+      dispatcher: this.agent,
+      signal: opts?.signal,
     });
 
     if (this.debug) {

package/src/command.ts

@@ -112,13 +112,18 @@ export class Command {
    * }
    * ```
    *
+   * @param params - Optional parameters.
+   * @param params.signal - An AbortSignal to cancel waiting.
    * @returns A {@link CommandFinished} instance with populated exit code.
    */
-  async wait() {
+  async wait(params?: { signal?: AbortSignal }) {
+    params?.signal?.throwIfAborted();
+
     const command = await this.client.getCommand({
       sandboxId: this.sandboxId,
       cmdId: this.cmd.id,
       wait: true,
+      signal: params?.signal,
     });
 
     return new CommandFinished({
@@ -136,11 +141,16 @@ export class Command {
    * not output valid Unicode.
    *
    * @param stream - The output stream to read: "stdout", "stderr", or "both".
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel output streaming.
    * @returns The output of the specified stream(s) as a string.
    */
-  async output(stream: "stdout" | "stderr" | "both" = "both") {
+  async output(
+    stream: "stdout" | "stderr" | "both" = "both",
+    opts?: { signal?: AbortSignal },
+  ) {
     let data = "";
-    for await (const log of this.logs()) {
+    for await (const log of this.logs({ signal: opts?.signal })) {
       if (stream === "both" || log.stream === stream) {
         data += log.data;
       }
@@ -154,10 +164,12 @@ export class Command {
    * NOTE: This may throw string conversion errors if the command does
    * not output valid Unicode.
    *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel output streaming.
    * @returns The standard output of the command.
    */
-  async stdout() {
-    return this.output("stdout");
+  async stdout(opts?: { signal?: AbortSignal }) {
+    return this.output("stdout", opts);
   }
 
   /**
@@ -166,24 +178,28 @@ export class Command {
    * NOTE: This may throw string conversion errors if the command does
    * not output valid Unicode.
    *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel output streaming.
    * @returns The standard error output of the command.
    */
-  async stderr() {
-    return this.output("stderr");
+  async stderr(opts?: { signal?: AbortSignal }) {
+    return this.output("stderr", opts);
   }
 
   /**
    * Kill a running command in a sandbox.
    *
-   * @param params - commandId and the signal to send the running process.
-   * Defaults to SIGTERM.
+   * @param signal - The signal to send the running process. Defaults to SIGTERM.
+   * @param opts - Optional parameters.
+   * @param opts.abortSignal - An AbortSignal to cancel the kill operation.
    * @returns Promise<void>.
    */
-  async kill(signal?: Signal) {
+  async kill(signal?: Signal, opts?: { abortSignal?: AbortSignal }) {
     await this.client.killCommand({
       sandboxId: this.sandboxId,
       commandId: this.cmd.id,
       signal: resolveSignal(signal ?? "SIGTERM"),
+      abortSignal: opts?.abortSignal,
     });
   }
 }

package/src/sandbox.ts

@@ -54,6 +54,11 @@ export interface CreateSandboxParams {
    * If not specified, the default runtime `node22` will be used.
    */
   runtime?: "node22" | "python3.13" | (string & {});
+
+  /**
+   * An AbortSignal to cancel sandbox creation.
+   */
+  signal?: AbortSignal;
 }
 
 /** @inline */
@@ -62,6 +67,10 @@ interface GetSandboxParams {
    * Unique identifier of the sandbox.
    */
   sandboxId: string;
+  /**
+   * An AbortSignal to cancel the operation.
+   */
+  signal?: AbortSignal;
 }
 
 /** @inline */
@@ -98,6 +107,10 @@ interface RunCommandParams {
    * A `Writable` stream where `stderr` from the command will be piped
    */
   stderr?: Writable;
+  /**
+   * An AbortSignal to cancel the command execution
+   */
+  signal?: AbortSignal;
 }
 
 /**
@@ -147,7 +160,10 @@ export class Sandbox {
       teamId: credentials.teamId,
       token: credentials.token,
     });
-    return client.listSandboxes(params);
+    return client.listSandboxes({
+      ...params,
+      signal: params.signal,
+    });
   }
 
   /**
@@ -175,6 +191,7 @@ export class Sandbox {
       timeout: params?.timeout,
       resources: params?.resources,
       runtime: params?.runtime,
+      signal: params?.signal,
       ...privateParams,
     });
 
@@ -202,6 +219,7 @@ export class Sandbox {
 
     const sandbox = await client.getSandbox({
       sandboxId: params.sandboxId,
+      signal: params.signal,
     });
 
     return new Sandbox({
@@ -236,12 +254,18 @@ export class Sandbox {
    * Get a previously run command by its ID.
    *
    * @param cmdId - ID of the command to retrieve
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
    * @returns A {@link Command} instance representing the command
    */
-  async getCommand(cmdId: string): Promise<Command> {
+  async getCommand(
+    cmdId: string,
+    opts?: { signal?: AbortSignal },
+  ): Promise<Command> {
     const command = await this.client.getCommand({
       sandboxId: this.sandbox.id,
       cmdId,
+      signal: opts?.signal,
     });
 
     return new Command({
@@ -256,9 +280,15 @@ export class Sandbox {
    *
    * @param command - The command to execute.
    * @param args - Arguments to pass to the command.
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the command execution.
    * @returns A {@link CommandFinished} result once execution is done.
    */
-  async runCommand(command: string, args?: string[]): Promise<CommandFinished>;
+  async runCommand(
+    command: string,
+    args?: string[],
+    opts?: { signal?: AbortSignal },
+  ): Promise<CommandFinished>;
 
   /**
    * Start executing a command in detached mode.
@@ -281,9 +311,10 @@ export class Sandbox {
   async runCommand(
     commandOrParams: string | RunCommandParams,
     args?: string[],
+    opts?: { signal?: AbortSignal },
   ): Promise<Command | CommandFinished> {
     return typeof commandOrParams === "string"
-      ? this._runCommand({ cmd: commandOrParams, args })
+      ? this._runCommand({ cmd: commandOrParams, args, signal: opts?.signal })
       : this._runCommand(commandOrParams);
   }
 
@@ -302,6 +333,7 @@ export class Sandbox {
       cwd: params.cwd,
       env: params.env ?? {},
       sudo: params.sudo ?? false,
+      signal: params.signal,
     });
 
     const command = new Command({
@@ -312,7 +344,7 @@ export class Sandbox {
 
     if (params.stdout || params.stderr) {
       (async () => {
-        for await (const log of command.logs()) {
+        for await (const log of command.logs({ signal: params.signal })) {
           if (log.stream === "stdout") {
             params.stdout?.write(log.data);
           } else if (log.stream === "stderr") {
@@ -322,18 +354,21 @@ export class Sandbox {
       })();
     }
 
-    return params.detached ? command : command.wait();
+    return params.detached ? command : command.wait({ signal: params.signal });
   }
 
   /**
    * Create a directory in the filesystem of this sandbox.
    *
    * @param path - Path of the directory to create
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
    */
-  async mkDir(path: string): Promise<void> {
+  async mkDir(path: string, opts?: { signal?: AbortSignal }): Promise<void> {
     await this.client.mkDir({
       sandboxId: this.sandbox.id,
       path: path,
+      signal: opts?.signal,
     });
   }
 
@@ -341,13 +376,19 @@ export class Sandbox {
    * Read a file from the filesystem of this sandbox.
    *
    * @param file - File to read, with path and optional cwd
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
    * @returns A promise that resolves to a ReadableStream containing the file contents
    */
-  async readFile(file: { path: string; cwd?: string }) {
+  async readFile(
+    file: { path: string; cwd?: string },
+    opts?: { signal?: AbortSignal },
+  ) {
     return this.client.readFile({
       sandboxId: this.sandbox.id,
       path: file.path,
       cwd: file.cwd,
+      signal: opts?.signal,
     });
   }
 
@@ -357,14 +398,20 @@ export class Sandbox {
    * Writes files using the `vercel-sandbox` user.
    *
    * @param files - Array of files with path and stream/buffer contents
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
    * @returns A promise that resolves when the files are written
    */
-  async writeFiles(files: { path: string; content: Buffer }[]) {
+  async writeFiles(
+    files: { path: string; content: Buffer }[],
+    opts?: { signal?: AbortSignal },
+  ) {
     return this.client.writeFiles({
       sandboxId: this.sandbox.id,
       cwd: this.sandbox.cwd,
       extractDir: "/",
       files: files,
+      signal: opts?.signal,
     });
   }
 
@@ -387,11 +434,14 @@ export class Sandbox {
   /**
    * Stop the sandbox.
    *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
    * @returns A promise that resolves when the sandbox is stopped
    */
-  async stop() {
+  async stop(opts?: { signal?: AbortSignal }) {
     await this.client.stopSandbox({
       sandboxId: this.sandbox.id,
+      signal: opts?.signal,
     });
   }
 }

package/src/version.ts

@@ -1,2 +1,2 @@
 // Autogenerated by inject-version.ts
-export const VERSION = "0.0.20";
+export const VERSION = "0.0.22";