@vercel/sandbox 0.0.9 → 0.0.10

package/.turbo/turbo-build.log

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

package/.turbo/turbo-typecheck.log

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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @vercel/sandbox
 
+## 0.0.10
+
+### Patch Changes
+
+- Add `readFile` and fix a bug writing files to a Sandbox ([#54](https://github.com/vercel/sandbox-sdk/pull/54))
+
+- Remove unused `routes` parameter from getSandbox ([#59](https://github.com/vercel/sandbox-sdk/pull/59))
+
 ## 0.0.9
 
 ### Patch Changes

package/README.md

@@ -1,5 +1,5 @@
 Vercel Sandbox allows you to run arbitrary code in isolated, ephemeral Linux
-VMs. This product is in private beta.
+VMs. This product is in [beta](https://vercel.com/docs/release-phases#beta).
 
 ## What is a sandbox?
 
@@ -9,14 +9,9 @@ infrastructure][hive] that powers 1M+ builds a day at Vercel.
 
 ## Getting started
 
-Vercel Sandbox is in private beta. These examples will not work unless these
-APIs are enabled for your team.
+Vercel Sandbox is in [beta](https://vercel.com/docs/release-phases#beta).
 
-- Go to your team settings, and copy the team ID.
-- Go to a project's settings, and copy the project ID.
-- Go to your Vercel account settings and [create a token][create-token]. Make
-  sure it is scoped to the team ID from the previous step.
-- Create a new project:
+To get started, create a new project:
 
 ```sh
 mkdir sandbox-test
@@ -26,6 +21,18 @@ pnpm add @vercel/sandbox ms
 pnpm add -D @types/ms @types/node
 ```
 
+Link it to Vercel:
+
+```sh
+vercel link
+```
+
+Pull its environment variables:
+
+```sh
+vercel env pull
+```
+
 Now create `next-dev.ts`:
 
 {@includeCode ../cli/src/example-next.ts}
@@ -33,7 +40,7 @@ Now create `next-dev.ts`:
 Run it like this:
 
 ```sh
-VERCEL_TEAM_ID=<team_id> VERCEL_TOKEN=<token> VERCEL_PROJECT_ID=<project_id> node --experimental-strip-types ./next-dev.ts
+node --env-file .env.local --experimental-strip-types ./next-dev.ts
 ```
 
 This will:
@@ -45,12 +52,53 @@ This will:
 
 All while streaming logs to your local terminal.
 
+## Authentication
+
+### Vercel OIDC token
+
+The SDK uses Vercel OIDC tokens to authenticate whenever available. This is the
+most straightforward and recommended way to authenticate.
+
+When developing locally, you can download a development token to `.env.local`
+using `vercel env pull`. After 12 hours the development token expires, meaning
+you will have to call `vercel env pull` again.
+
+In production, Vercel manages token expiration for you.
+
+### Access token
+
+If you want to use the SDK from an environment where `VERCEL_OIDC_TOKEN` is
+unavailable, you can also authenticate using an access token:
+
+- Go to your team settings, and copy the team ID.
+- Go to a project's settings, and copy the project ID.
+- Go to your Vercel account settings and [create a token][create-token]. Make
+  sure it is scoped to the team ID from the previous step.
+
+Set your team ID, project ID, and token to the environment variables
+`VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_TOKEN`. Then pass these to
+the `create` method:
+
+```ts
+const sandbox = await Sandbox.create({
+  teamId: process.env.VERCEL_TEAM_ID!,
+  projectId: process.env.VERCEL_PROJECT_ID!,
+  token: process.env.VERCEL_TOKEN!,
+  source: {
+    url: "https://github.com/vercel/sandbox-example-next.git",
+    type: "git",
+  },
+  resources: { vcpus: 4 },
+  timeout: ms("5m"),
+  ports: [3000],
+  runtime: "node22",
+});
+```
+
 ## Limitations
 
-- Sandbox only supports cloning public repositories at the moment.
 - `sudo` is not available. User code is executed as the `vercel-sandbox` user.
 - Max resources: 8 vCPUs. You will get 2048 MB of memory per vCPU.
-- All APIs of the SDK are subject to change. **We make no stability promises.**
 
 ## System
 
@@ -78,7 +126,8 @@ whois
 zstd
 ```
 
-- The `node22` system ships a Node 22 runtime under `/vercel/runtimes/node22`.
+- The `node22` image ships a Node 22 runtime under `/vercel/runtimes/node22`.
+- The `python3.13` image ships a Python 3.13 runtime under `/vercel/runtimes/python`.
 - User code is executed as the `vercel-sandbox` user.
 - `/vercel/sandbox` is writable.
 

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

@@ -43,6 +43,8 @@ export declare class APIClient extends BaseClient {
             url: string;
             depth?: number;
             revision?: string;
+            username?: string;
+            password?: string;
         } | {
             type: "tarball";
             url: string;

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

@@ -10,6 +10,7 @@ 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 consume_readable_1 = require("../utils/consume-readable");
 const jsonlines_1 = __importDefault(require("jsonlines"));
 const os_1 = __importDefault(require("os"));
 const ms_1 = __importDefault(require("ms"));
@@ -82,11 +83,13 @@ class APIClient extends base_client_1.BaseClient {
     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,
-            }),
+            response: (async () => {
+                return this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
+                    method: "POST",
+                    headers: { "content-type": "application/gzip" },
+                    body: await (0, consume_readable_1.consumeReadable)(writer.readable),
+                });
+            })(),
             writer,
         };
     }
@@ -97,7 +100,7 @@ class APIClient extends base_client_1.BaseClient {
         for (const file of params.files) {
             await writer.addFile({ name: file.path, content: file.stream });
         }
-        await writer.end();
+        writer.end();
         await (0, base_client_1.parseOrThrow)(validators_1.EmptyResponse, await response);
     }
     async readFile(params) {

package/dist/sandbox.d.ts

@@ -19,6 +19,13 @@ export interface CreateSandboxParams {
         url: string;
         depth?: number;
         revision?: string;
+    } | {
+        type: "git";
+        url: string;
+        username: string;
+        password: string;
+        depth?: number;
+        revision?: string;
     } | {
         type: "tarball";
         url: string;
@@ -48,13 +55,6 @@ export interface CreateSandboxParams {
 }
 /** @inline */
 interface GetSandboxParams {
-    /**
-     * Port-to-subdomain route mappings.
-     */
-    routes: Array<{
-        subdomain: string;
-        port: number;
-    }>;
     /**
      * Unique identifier of the sandbox.
      */
@@ -183,6 +183,16 @@ export declare class Sandbox {
      * @param path - Path of the directory to create
      */
     mkDir(path: string): Promise<void>;
+    /**
+     * Read a file from the filesystem of this sandbox.
+     *
+     * @param file - File to read, with path and optional cwd
+     * @returns A promise that resolves to a ReadableStream containing the file contents
+     */
+    readFile(file: {
+        path: string;
+        cwd?: string;
+    }): Promise<NodeJS.ReadableStream | null>;
     /**
      * Write files to the filesystem of this sandbox.
      *

package/dist/sandbox.js

@@ -143,6 +143,19 @@ class Sandbox {
             path: path,
         });
     }
+    /**
+     * Read a file from the filesystem of this sandbox.
+     *
+     * @param file - File to read, with path and optional cwd
+     * @returns A promise that resolves to a ReadableStream containing the file contents
+     */
+    async readFile(file) {
+        return this.client.readFile({
+            sandboxId: this.sandbox.id,
+            path: file.path,
+            cwd: file.cwd,
+        });
+    }
     /**
      * Write files to the filesystem of this sandbox.
      *

package/dist/utils/consume-readable.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Consumes a readable entirely concatenating all content in a single Buffer
+ * @param readable A Readable stream
+ */
+export declare function consumeReadable(readable: NodeJS.ReadableStream): Promise<Buffer<ArrayBufferLike>>;

package/dist/utils/consume-readable.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consumeReadable = consumeReadable;
+/**
+ * Consumes a readable entirely concatenating all content in a single Buffer
+ * @param readable A Readable stream
+ */
+function consumeReadable(readable) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        readable.on("error", (err) => reject(err));
+        readable.on("data", (chunk) => chunks.push(chunk));
+        readable.on("end", () => resolve(Buffer.concat(chunks)));
+    });
+}

package/dist/version.d.ts

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -16,6 +16,7 @@ import { APIError } from "./api-error";
 import { FileWriter } from "./file-writer";
 import { LRUCache } from "lru-cache";
 import { VERSION } from "../version";
+import { consumeReadable } from "../utils/consume-readable";
 import { z } from "zod";
 import jsonlines from "jsonlines";
 import os from "os";
@@ -66,7 +67,14 @@ export class APIClient extends BaseClient {
     ports?: number[];
     projectId: string;
     source?:
-      | { type: "git"; url: string; depth?: number; revision?: string }
+      | {
+          type: "git";
+          url: string;
+          depth?: number;
+          revision?: string;
+          username?: string;
+          password?: string;
+        }
       | { type: "tarball"; url: string };
     timeout?: number;
     resources?: { vcpus: number };
@@ -153,11 +161,13 @@ 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,
-      }),
+      response: (async () => {
+        return this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
+          method: "POST",
+          headers: { "content-type": "application/gzip" },
+          body: await consumeReadable(writer.readable),
+        });
+      })(),
       writer,
     };
   }
@@ -174,7 +184,7 @@ export class APIClient extends BaseClient {
       await writer.addFile({ name: file.path, content: file.stream });
     }
 
-    await writer.end();
+    writer.end();
     await parseOrThrow(EmptyResponse, await response);
   }
 

package/src/sandbox.test.ts

@@ -0,0 +1,29 @@
+import { it, beforeEach, afterEach, expect } from "vitest";
+import { consumeReadable } from "./utils/consume-readable";
+import { Sandbox } from "./sandbox";
+
+let sandbox: Sandbox;
+
+beforeEach(async () => {
+  sandbox = await Sandbox.create({
+    projectId: process.env.VERCEL_PROJECT_ID!,
+    teamId: process.env.VERCEL_TEAM_ID!,
+    token: process.env.VERCEL_TOKEN!,
+  });
+});
+
+afterEach(async () => {
+  await sandbox.stop();
+});
+
+it("allows to write files and then read them", async () => {
+  await sandbox.writeFiles([
+    { path: "hello1.txt", stream: Buffer.from("Hello 1") },
+    { path: "hello2.txt", stream: Buffer.from("Hello 2") },
+  ]);
+
+  const content1 = await sandbox.readFile({ path: "hello1.txt" });
+  const content2 = await sandbox.readFile({ path: "hello2.txt" });
+  expect((await consumeReadable(content1!)).toString()).toBe("Hello 1");
+  expect((await consumeReadable(content2!)).toString()).toBe("Hello 2");
+});

package/src/sandbox.ts

@@ -16,7 +16,20 @@ export interface CreateSandboxParams {
    * - `revision`: Clones and checks out a specific commit, branch, or tag
    */
   source?:
-    | { type: "git"; url: string; depth?: number; revision?: string }
+    | {
+        type: "git";
+        url: string;
+        depth?: number;
+        revision?: string;
+      }
+    | {
+        type: "git";
+        url: string;
+        username: string;
+        password: string;
+        depth?: number;
+        revision?: string;
+      }
     | { type: "tarball"; url: string };
   /**
    * Array of port numbers to expose from the sandbox.
@@ -43,10 +56,6 @@ export interface CreateSandboxParams {
 
 /** @inline */
 interface GetSandboxParams {
-  /**
-   * Port-to-subdomain route mappings.
-   */
-  routes: Array<{ subdomain: string; port: number }>;
   /**
    * Unique identifier of the sandbox.
    */
@@ -294,6 +303,20 @@ export class Sandbox {
     });
   }
 
+  /**
+   * Read a file from the filesystem of this sandbox.
+   *
+   * @param file - File to read, with path and optional cwd
+   * @returns A promise that resolves to a ReadableStream containing the file contents
+   */
+  async readFile(file: { path: string; cwd?: string }) {
+    return this.client.readFile({
+      sandboxId: this.sandbox.id,
+      path: file.path,
+      cwd: file.cwd,
+    });
+  }
+
   /**
    * Write files to the filesystem of this sandbox.
    *

package/src/utils/consume-readable.ts

@@ -0,0 +1,12 @@
+/**
+ * Consumes a readable entirely concatenating all content in a single Buffer
+ * @param readable A Readable stream
+ */
+export function consumeReadable(readable: NodeJS.ReadableStream) {
+  return new Promise<Buffer>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    readable.on("error", (err) => reject(err));
+    readable.on("data", (chunk) => chunks.push(chunk));
+    readable.on("end", () => resolve(Buffer.concat(chunks)));
+  });
+}

package/src/version.ts

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