@vercel/sandbox 0.0.7 → 0.0.8

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.7 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.8 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc
 

package/.turbo/turbo-typecheck.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.7 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.8 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @vercel/sandbox
 
+## 0.0.8
+
+### Patch Changes
+
+- Write files using a single compressed stream ([#44](https://github.com/vercel/sandbox-sdk/pull/44))
+- Expose `runtime` parameter ([#46](https://github.com/vercel/sandbox-sdk/pull/46))
+- Add git depth and revision options to sandbox source ([#47](https://github.com/vercel/sandbox-sdk/pull/47))
+
 ## 0.0.7
 
 ### Patch Changes

package/dist/api-client/api-client.d.ts

@@ -1,6 +1,6 @@
 import { BaseClient, type Parsed, type RequestParams } from "./base-client";
 import { Command, CommandFinished, LogLine, StoppedSandbox } from "./validators";
-import { Readable } from "stream";
+import { FileWriter } from "./file-writer";
 import { z } from "zod";
 export declare class APIClient extends BaseClient {
     private teamId;
@@ -16,6 +16,8 @@ export declare class APIClient extends BaseClient {
         source?: {
             type: "git";
             url: string;
+            depth?: number;
+            revision?: string;
         } | {
             type: "tarball";
             url: string;
@@ -24,6 +26,7 @@ export declare class APIClient extends BaseClient {
         resources?: {
             vcpus: number;
         };
+        runtime?: "node22" | "python3.13";
     }): Promise<Parsed<{
         sandboxId: string;
         routes: {
@@ -55,11 +58,17 @@ export declare class APIClient extends BaseClient {
         path: string;
         cwd?: string;
     }): Promise<Parsed<{}>>;
+    getFileWriter(params: {
+        sandboxId: string;
+    }): {
+        response: Promise<import("node-fetch").Response>;
+        writer: FileWriter;
+    };
     writeFiles(params: {
         sandboxId: string;
         files: {
             path: string;
-            stream: Readable | Buffer;
+            stream: Buffer;
         }[];
     }): Promise<void>;
     readFile(params: {

package/dist/api-client/api-client.js

@@ -4,10 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APIClient = void 0;
-const form_data_1 = __importDefault(require("form-data"));
 const base_client_1 = require("./base-client");
 const validators_1 = require("./validators");
 const api_error_1 = require("./api-error");
+const file_writer_1 = require("./file-writer");
 const lru_cache_1 = require("lru-cache");
 const version_1 = require("../version");
 const jsonlines_1 = __importDefault(require("jsonlines"));
@@ -50,6 +50,7 @@ class APIClient extends base_client_1.BaseClient {
                 source: params.source,
                 timeout: params.timeout,
                 resources: params.resources,
+                runtime: params.runtime,
             }),
         }));
     }
@@ -75,16 +76,26 @@ class APIClient extends base_client_1.BaseClient {
             body: JSON.stringify({ path: params.path, cwd: params.cwd }),
         }));
     }
+    getFileWriter(params) {
+        const writer = new file_writer_1.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) {
-        const formData = new form_data_1.default();
+        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 (0, base_client_1.parseOrThrow)(validators_1.WrittenFile, await this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
-            method: "POST",
-            headers: { ...formData.getHeaders() },
-            body: formData,
-        }));
+        await writer.end();
+        await (0, base_client_1.parseOrThrow)(validators_1.WrittenFile, await response);
     }
     async readFile(params) {
         const response = await this.request(`/v1/sandboxes/${params.sandboxId}/fs/read`, {

package/dist/api-client/file-writer.d.ts

@@ -0,0 +1,52 @@
+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 declare class FileWriter {
+    readable: Readable;
+    private pack;
+    constructor();
+    /**
+     * 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.
+     */
+    addFile(file: FileBuffer | FileStream): Promise<void>;
+    /**
+     * Allows to finish the stream returning a Promise that will
+     * resolve once the readable is effectively closed or
+     * errored.
+     */
+    end(): Promise<void>;
+}
+export {};

package/dist/api-client/file-writer.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileWriter = void 0;
+const zlib_1 = __importDefault(require("zlib"));
+const tar_stream_1 = __importDefault(require("tar-stream"));
+const stream_1 = require("stream");
+/**
+ * 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.
+ */
+class FileWriter {
+    constructor() {
+        const gzip = zlib_1.default.createGzip();
+        this.pack = tar_stream_1.default.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) {
+        return new Promise((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 stream_1.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((resolve, reject) => {
+            this.readable.on("error", reject);
+            this.readable.on("end", resolve);
+            this.pack.finalize();
+        });
+    }
+}
+exports.FileWriter = FileWriter;

package/dist/sandbox.d.ts

@@ -1,4 +1,4 @@
-import { Readable, type Writable } from "stream";
+import { type Writable } from "stream";
 import { APIClient } from "./api-client";
 import { Command, CommandFinished } from "./command";
 import { type Credentials } from "./utils/get-credentials";
@@ -8,10 +8,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 +39,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 {
@@ -181,7 +192,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

@@ -29,6 +29,7 @@ class Sandbox {
             ports: params?.ports ?? [],
             timeout: params?.timeout,
             resources: params?.resources,
+            runtime: params?.runtime,
         });
         return new Sandbox({
             client,

package/dist/version.d.ts

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

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.8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "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,
@@ -14,8 +13,8 @@ import {
   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";
@@ -60,9 +59,12 @@ export class APIClient extends BaseClient {
   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,
@@ -74,6 +76,7 @@ export class APIClient extends BaseClient {
           source: params.source,
           timeout: params.timeout,
           resources: params.resources,
+          runtime: params.runtime,
         }),
       }),
     );
@@ -141,24 +144,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(WrittenFile, await response);
   }
 
   async readFile(params: {

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/sandbox.ts

@@ -1,4 +1,4 @@
-import { Readable, type Writable } from "stream";
+import { type Writable } from "stream";
 import { APIClient } from "./api-client";
 import { Command, CommandFinished } from "./command";
 import { getCredentials, type Credentials } from "./utils/get-credentials";
@@ -9,8 +9,14 @@ 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 } | { type: "tarball"; url: string };
+  source?:
+    | { type: "git"; url: string; depth?: number; revision?: string }
+    | { type: "tarball"; url: string };
   /**
    * Array of port numbers to expose from the sandbox.
    */
@@ -26,6 +32,12 @@ export interface CreateSandboxParams {
    * 2048 MB of memory per vCPU.
    */
   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 */
@@ -113,6 +125,7 @@ export class Sandbox {
       ports: params?.ports ?? [],
       timeout: params?.timeout,
       resources: params?.resources,
+      runtime: params?.runtime,
     });
 
     return new Sandbox({
@@ -270,7 +283,7 @@ export class Sandbox {
    * @param files - Array of files with path and stream/buffer contents
    * @returns A promise that resolves when the files are written
    */
-  async writeFiles(files: { path: string; stream: Readable | Buffer }[]) {
+  async writeFiles(files: { path: string; stream: Buffer }[]) {
     return this.client.writeFiles({
       sandboxId: this.sandboxId,
       files: files,

package/src/version.ts

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