@vercel/sandbox 0.0.7 → 0.0.9

package/dist/sandbox.d.ts

@@ -1,6 +1,7 @@
-import { Readable, type Writable } from "stream";
+import type { SandboxData, SandboxRouteData } from "./api-client";
+import type { Writable } from "stream";
 import { APIClient } from "./api-client";
-import { Command, CommandFinished } from "./command";
+import { Command, type CommandFinished } from "./command";
 import { type Credentials } from "./utils/get-credentials";
 /** @inline */
 export interface CreateSandboxParams {
@@ -8,10 +9,16 @@ export interface CreateSandboxParams {
      * The source of the sandbox.
      *
      * Omit this parameter start a sandbox without a source.
+     *
+     * For git sources:
+     * - `depth`: Creates shallow clones with limited commit history (minimum: 1)
+     * - `revision`: Clones and checks out a specific commit, branch, or tag
      */
     source?: {
         type: "git";
         url: string;
+        depth?: number;
+        revision?: string;
     } | {
         type: "tarball";
         url: string;
@@ -33,6 +40,11 @@ export interface CreateSandboxParams {
     resources?: {
         vcpus: number;
     };
+    /**
+     * The runtime of the sandbox, currently only `node22` and `python3.13` are supported.
+     * If not specified, the default runtime `node22` will be used.
+     */
+    runtime?: "node22" | "python3.13";
 }
 /** @inline */
 interface GetSandboxParams {
@@ -91,14 +103,15 @@ export declare class Sandbox {
      * Routes from ports to subdomains.
     /* @hidden
      */
-    readonly routes: {
-        subdomain: string;
-        port: number;
-    }[];
+    readonly routes: SandboxRouteData[];
     /**
      * Unique ID of this sandbox.
      */
-    readonly sandboxId: string;
+    get sandboxId(): string;
+    /**
+     * Data about this sandbox.
+     */
+    private readonly sandbox;
     /**
      * Create a new sandbox.
      *
@@ -120,13 +133,10 @@ export declare class Sandbox {
      * @param routes - Port-to-subdomain mappings for exposed ports
      * @param sandboxId - Unique identifier for the sandbox
      */
-    constructor({ client, routes, sandboxId, }: {
+    constructor({ client, routes, sandbox, }: {
         client: APIClient;
-        routes: {
-            subdomain: string;
-            port: number;
-        }[];
-        sandboxId: string;
+        routes: SandboxRouteData[];
+        sandbox: SandboxData;
     });
     /**
      * Get a previously run command by its ID.
@@ -134,7 +144,7 @@ export declare class Sandbox {
      * @param cmdId - ID of the command to retrieve
      * @returns A {@link Command} instance representing the command
      */
-    getCommand(cmdId: string): Command;
+    getCommand(cmdId: string): Promise<Command>;
     /**
      * Start executing a command in this sandbox.
      *
@@ -181,7 +191,7 @@ export declare class Sandbox {
      */
     writeFiles(files: {
         path: string;
-        stream: Readable | Buffer;
+        stream: Buffer;
     }[]): Promise<void>;
     /**
      * Get the public domain of a port of this sandbox.

package/dist/sandbox.js

@@ -11,6 +11,12 @@ const get_credentials_1 = require("./utils/get-credentials");
  * @hideconstructor
  */
 class Sandbox {
+    /**
+     * Unique ID of this sandbox.
+     */
+    get sandboxId() {
+        return this.sandbox.id;
+    }
     /**
      * Create a new sandbox.
      *
@@ -29,10 +35,11 @@ class Sandbox {
             ports: params?.ports ?? [],
             timeout: params?.timeout,
             resources: params?.resources,
+            runtime: params?.runtime,
         });
         return new Sandbox({
             client,
-            sandboxId: sandbox.json.sandboxId,
+            sandbox: sandbox.json.sandbox,
             routes: sandbox.json.routes,
         });
     }
@@ -48,10 +55,13 @@ class Sandbox {
             teamId: credentials.teamId,
             token: credentials.token,
         });
+        const sandbox = await client.getSandbox({
+            sandboxId: params.sandboxId,
+        });
         return new Sandbox({
             client,
-            sandboxId: params.sandboxId,
-            routes: params.routes,
+            sandbox: sandbox.json.sandbox,
+            routes: sandbox.json.routes,
         });
     }
     /**
@@ -61,10 +71,10 @@ class Sandbox {
      * @param routes - Port-to-subdomain mappings for exposed ports
      * @param sandboxId - Unique identifier for the sandbox
      */
-    constructor({ client, routes, sandboxId, }) {
+    constructor({ client, routes, sandbox, }) {
         this.client = client;
         this.routes = routes;
-        this.sandboxId = sandboxId;
+        this.sandbox = sandbox;
     }
     /**
      * Get a previously run command by its ID.
@@ -72,11 +82,15 @@ class Sandbox {
      * @param cmdId - ID of the command to retrieve
      * @returns A {@link Command} instance representing the command
      */
-    getCommand(cmdId) {
+    async getCommand(cmdId) {
+        const command = await this.client.getCommand({
+            sandboxId: this.sandbox.id,
+            cmdId,
+        });
         return new command_1.Command({
             client: this.client,
-            sandboxId: this.sandboxId,
-            cmdId,
+            sandboxId: this.sandbox.id,
+            cmd: command.json.command,
         });
     }
     async runCommand(commandOrParams, args) {
@@ -93,7 +107,7 @@ class Sandbox {
      */
     async _runCommand(params) {
         const commandResponse = await this.client.runCommand({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
             command: params.cmd,
             args: params.args ?? [],
             cwd: params.cwd,
@@ -101,8 +115,8 @@ class Sandbox {
         });
         const command = new command_1.Command({
             client: this.client,
-            sandboxId: this.sandboxId,
-            cmdId: commandResponse.json.cmdId,
+            sandboxId: this.sandbox.id,
+            cmd: commandResponse.json.command,
         });
         if (params.stdout || params.stderr) {
             (async () => {
@@ -125,7 +139,7 @@ class Sandbox {
      */
     async mkDir(path) {
         await this.client.mkDir({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
             path: path,
         });
     }
@@ -137,7 +151,7 @@ class Sandbox {
      */
     async writeFiles(files) {
         return this.client.writeFiles({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
             files: files,
         });
     }
@@ -164,7 +178,7 @@ class Sandbox {
      */
     async stop() {
         await this.client.stopSandbox({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
         });
     }
 }

package/dist/utils/resolveSignal.d.ts

@@ -0,0 +1,13 @@
+declare const linuxSignalMapping: {
+    readonly SIGHUP: 1;
+    readonly SIGINT: 2;
+    readonly SIGQUIT: 3;
+    readonly SIGKILL: 9;
+    readonly SIGTERM: 15;
+    readonly SIGCONT: 18;
+    readonly SIGSTOP: 19;
+};
+type CommonLinuxSignals = keyof typeof linuxSignalMapping;
+export type Signal = CommonLinuxSignals | number;
+export declare function resolveSignal(signal: Signal): number;
+export {};

package/dist/utils/resolveSignal.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSignal = resolveSignal;
+const linuxSignalMapping = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGKILL: 9,
+    SIGTERM: 15,
+    SIGCONT: 18,
+    SIGSTOP: 19,
+};
+function resolveSignal(signal) {
+    if (typeof signal === "number") {
+        return signal;
+    }
+    if (signal in linuxSignalMapping) {
+        return linuxSignalMapping[signal];
+    }
+    throw new Error(`Unknown signal name: ${String(signal)}`);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.7";
+export declare const VERSION = "0.0.9";

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.7";
+exports.VERSION = "0.0.9";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,6 +15,8 @@
     "lru-cache": "11.1.0",
     "ms": "2.1.3",
     "node-fetch": "2.6.11",
+    "tar-stream": "3.1.7",
+    "zlib": "1.0.5",
     "zod": "3.24.4"
   },
   "devDependencies": {
@@ -23,6 +25,7 @@
     "@types/ms": "2.1.0",
     "@types/node": "22.15.12",
     "@types/node-fetch": "2.6.12",
+    "@types/tar-stream": "3.1.4",
     "dotenv": "16.5.0",
     "typedoc": "0.28.5",
     "typescript": "5.8.3",

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

@@ -1,4 +1,3 @@
-import FormData from "form-data";
 import {
   BaseClient,
   parseOrThrow,
@@ -6,16 +5,15 @@ import {
   type RequestParams,
 } from "./base-client";
 import {
-  Command,
-  CommandFinished,
-  CreatedCommand,
-  CreatedSandbox,
+  SandboxAndRoutesResponse,
+  SandboxResponse,
+  CommandResponse,
+  CommandFinishedResponse,
+  EmptyResponse,
   LogLine,
-  StoppedSandbox,
-  WrittenFile,
 } from "./validators";
-import { Readable } from "stream";
 import { APIError } from "./api-error";
+import { FileWriter } from "./file-writer";
 import { LRUCache } from "lru-cache";
 import { VERSION } from "../version";
 import { z } from "zod";
@@ -57,15 +55,25 @@ export class APIClient extends BaseClient {
     });
   }
 
+  async getSandbox(params: { sandboxId: string }) {
+    return parseOrThrow(
+      SandboxAndRoutesResponse,
+      await this.request(`/v1/sandboxes/${params.sandboxId}`),
+    );
+  }
+
   async createSandbox(params: {
     ports?: number[];
     projectId: string;
-    source?: { type: "git"; url: string } | { type: "tarball"; url: string };
+    source?:
+      | { type: "git"; url: string; depth?: number; revision?: string }
+      | { type: "tarball"; url: string };
     timeout?: number;
     resources?: { vcpus: number };
+    runtime?: "node22" | "python3.13";
   }) {
     return parseOrThrow(
-      CreatedSandbox,
+      SandboxAndRoutesResponse,
       await this.request("/v1/sandboxes", {
         method: "POST",
         body: JSON.stringify({
@@ -74,6 +82,7 @@ export class APIClient extends BaseClient {
           source: params.source,
           timeout: params.timeout,
           resources: params.resources,
+          runtime: params.runtime,
         }),
       }),
     );
@@ -87,7 +96,7 @@ export class APIClient extends BaseClient {
     env: Record<string, string>;
   }) {
     return parseOrThrow(
-      CreatedCommand,
+      CommandResponse,
       await this.request(`/v1/sandboxes/${params.sandboxId}/cmd`, {
         method: "POST",
         body: JSON.stringify({
@@ -104,12 +113,12 @@ export class APIClient extends BaseClient {
     sandboxId: string;
     cmdId: string;
     wait: true;
-  }): Promise<Parsed<z.infer<typeof CommandFinished>>>;
+  }): Promise<Parsed<z.infer<typeof CommandFinishedResponse>>>;
   async getCommand(params: {
     sandboxId: string;
     cmdId: string;
     wait?: boolean;
-  }): Promise<Parsed<z.infer<typeof Command>>>;
+  }): Promise<Parsed<z.infer<typeof CommandResponse>>>;
   async getCommand(params: {
     sandboxId: string;
     cmdId: string;
@@ -117,14 +126,14 @@ export class APIClient extends BaseClient {
   }) {
     return params.wait
       ? parseOrThrow(
-          CommandFinished,
+          CommandFinishedResponse,
           await this.request(
             `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
             { query: { wait: "true" } },
           ),
         )
       : parseOrThrow(
-          Command,
+          CommandResponse,
           await this.request(
             `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
           ),
@@ -133,7 +142,7 @@ export class APIClient extends BaseClient {
 
   async mkDir(params: { sandboxId: string; path: string; cwd?: string }) {
     return parseOrThrow(
-      WrittenFile,
+      EmptyResponse,
       await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
         method: "POST",
         body: JSON.stringify({ path: params.path, cwd: params.cwd }),
@@ -141,24 +150,32 @@ export class APIClient extends BaseClient {
     );
   }
 
+  getFileWriter(params: { sandboxId: string }) {
+    const writer = new FileWriter();
+    return {
+      response: this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
+        method: "POST",
+        headers: { "content-type": "application/gzip" },
+        body: writer.readable,
+      }),
+      writer,
+    };
+  }
+
   async writeFiles(params: {
     sandboxId: string;
-    files: { path: string; stream: Readable | Buffer }[];
+    files: { path: string; stream: Buffer }[];
   }) {
-    const formData = new FormData();
+    const { writer, response } = this.getFileWriter({
+      sandboxId: params.sandboxId,
+    });
 
     for (const file of params.files) {
-      formData.append(file.path, file.stream, file.path);
+      await writer.addFile({ name: file.path, content: file.stream });
     }
 
-    await parseOrThrow(
-      WrittenFile,
-      await this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
-        method: "POST",
-        headers: { ...formData.getHeaders() },
-        body: formData,
-      }),
-    );
+    await writer.end();
+    await parseOrThrow(EmptyResponse, await response);
   }
 
   async readFile(params: {
@@ -181,6 +198,23 @@ export class APIClient extends BaseClient {
     return response.body;
   }
 
+  async killCommand(params: {
+    sandboxId: string;
+    commandId: string;
+    signal: number;
+  }) {
+    return parseOrThrow(
+      CommandResponse,
+      await this.request(
+        `/v1/sandboxes/${params.sandboxId}/${params.commandId}/kill`,
+        {
+          method: "POST",
+          body: JSON.stringify({ signal: params.signal }),
+        },
+      ),
+    );
+  }
+
   async *getLogs(params: {
     sandboxId: string;
     cmdId: string;
@@ -215,10 +249,10 @@ export class APIClient extends BaseClient {
 
   async stopSandbox(params: {
     sandboxId: string;
-  }): Promise<Parsed<z.infer<typeof StoppedSandbox>>> {
+  }): Promise<Parsed<z.infer<typeof SandboxResponse>>> {
     const url = `/v1/sandboxes/${params.sandboxId}/stop`;
     return parseOrThrow(
-      StoppedSandbox,
+      SandboxResponse,
       await this.request(url, { method: "POST" }),
     );
   }

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

@@ -0,0 +1,90 @@
+import zlib from "zlib";
+import tar, { type Pack } from "tar-stream";
+import { Readable } from "stream";
+
+interface FileBuffer {
+  /**
+   * The name (path) of the file to write.
+   */
+  name: string;
+  /**
+   * The content of the file as a Buffer.
+   */
+  content: Buffer;
+}
+
+interface FileStream {
+  /**
+   * The name (path) of the file to write.
+   */
+  name: string;
+  /**
+   * A Readable stream to consume the content of the file.
+   */
+  content: Readable;
+  /**
+   * The expected size of the file. This is required to write
+   * the header of the compressed file.
+   */
+  size: number;
+}
+
+/**
+ * Allows to create a Readable stream with methods to write files
+ * to it and to finish it. Files written are compressed together
+ * and gzipped in the stream.
+ */
+export class FileWriter {
+  public readable: Readable;
+  private pack: Pack;
+
+  constructor() {
+    const gzip = zlib.createGzip();
+    this.pack = tar.pack();
+    this.readable = this.pack.pipe(gzip);
+  }
+
+  /**
+   * Allows to add a file to the stream. Size is required to write
+   * the tarball header so when content is a stream it must be
+   * provided.
+   *
+   * Returns a Promise resolved once the file is written in the
+   * stream.
+   */
+  async addFile(file: FileBuffer | FileStream) {
+    return new Promise<void>((resolve, reject) => {
+      const entry = this.pack.entry(
+        "size" in file
+          ? { name: file.name, size: file.size }
+          : { name: file.name, size: file.content.length },
+        (error) => {
+          if (error) {
+            return reject(error);
+          } else {
+            resolve();
+          }
+        },
+      );
+
+      if (file.content instanceof Readable) {
+        file.content.pipe(entry);
+      } else {
+        entry.end(file.content);
+      }
+    });
+  }
+
+  /**
+   * Allows to finish the stream returning a Promise that will
+   * resolve once the readable is effectively closed or
+   * errored.
+   */
+  async end() {
+    return new Promise<void>((resolve, reject) => {
+      this.readable.on("error", reject);
+      this.readable.on("end", resolve);
+      this.pack.finalize();
+    });
+  }
+}

package/src/api-client/index.ts

@@ -1 +1,2 @@
 export { APIClient } from "./api-client";
+export * from "./validators";

package/src/api-client/validators.ts

@@ -1,36 +1,66 @@
 import { z } from "zod";
 
-export const CreatedSandbox = z.object({
-  sandboxId: z.string(),
-  routes: z.array(z.object({ subdomain: z.string(), port: z.number() })),
+export type SandboxData = z.infer<typeof Sandbox>;
+
+export const Sandbox = z.object({
+  id: z.string(),
+  memory: z.number(),
+  vcpus: z.number(),
+  region: z.string(),
+  runtime: z.string(),
+  timeout: z.number(),
+  status: z.enum(["pending", "running", "stopping", "stopped", "failed"]),
+  requestedAt: z.number(),
+  startedAt: z.number().optional(),
+  requestedStopAt: z.number().optional(),
+  stoppedAt: z.number().optional(),
+  duration: z.number().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
 });
 
-export const CreatedCommand = z.object({
-  cmdId: z.string(),
+export type SandboxRouteData = z.infer<typeof SandboxRoute>;
+
+export const SandboxRoute = z.object({
+  url: z.string(),
+  subdomain: z.string(),
+  port: z.number(),
 });
 
+export type CommandData = z.infer<typeof Command>;
+
 export const Command = z.object({
+  id: z.string(),
+  name: z.string(),
   args: z.array(z.string()),
-  cmdId: z.string(),
   cwd: z.string(),
+  sandboxId: z.string(),
   exitCode: z.number().nullable(),
-  name: z.string(),
+  startedAt: z.number(),
 });
 
-export const CommandFinished = z.object({
-  args: z.array(z.string()),
-  cmdId: z.string(),
-  cwd: z.string(),
+const CommandFinished = Command.extend({
   exitCode: z.number(),
-  name: z.string(),
 });
 
-export const WrittenFile = z.object({});
+export const SandboxResponse = z.object({
+  sandbox: Sandbox,
+});
 
-export const StoppedSandbox = z.object({
-  sandboxId: z.string(),
+export const SandboxAndRoutesResponse = SandboxResponse.extend({
+  routes: z.array(SandboxRoute),
+});
+
+export const CommandResponse = z.object({
+  command: Command,
+});
+
+export const CommandFinishedResponse = z.object({
+  command: CommandFinished,
 });
 
+export const EmptyResponse = z.object({});
+
 export const LogLine = z.object({
   stream: z.enum(["stdout", "stderr"]),
   data: z.string(),