@vercel/sandbox 0.0.8 → 0.0.10

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.8 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.8 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,20 @@
 # @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
+
+- Add `cmd.kill()` to stop/signal commands ([#48](https://github.com/vercel/sandbox-sdk/pull/48))
+- Update SDK to use the new API ([#51](https://github.com/vercel/sandbox-sdk/pull/51))
+
 ## 0.0.8
 
 ### 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

@@ -1,5 +1,5 @@
 import { BaseClient, type Parsed, type RequestParams } from "./base-client";
-import { Command, CommandFinished, LogLine, StoppedSandbox } from "./validators";
+import { SandboxResponse, CommandResponse, CommandFinishedResponse, LogLine } from "./validators";
 import { FileWriter } from "./file-writer";
 import { z } from "zod";
 export declare class APIClient extends BaseClient {
@@ -10,6 +10,31 @@ export declare class APIClient extends BaseClient {
         token: string;
     });
     protected request(path: string, params?: RequestParams): Promise<import("node-fetch").Response>;
+    getSandbox(params: {
+        sandboxId: string;
+    }): Promise<Parsed<{
+        sandbox: {
+            region: string;
+            timeout: number;
+            status: "pending" | "running" | "stopping" | "stopped" | "failed";
+            id: string;
+            memory: number;
+            vcpus: number;
+            runtime: string;
+            requestedAt: number;
+            createdAt: number;
+            updatedAt: number;
+            duration?: number | undefined;
+            startedAt?: number | undefined;
+            requestedStopAt?: number | undefined;
+            stoppedAt?: number | undefined;
+        };
+        routes: {
+            port: number;
+            url: string;
+            subdomain: string;
+        }[];
+    }>>;
     createSandbox(params: {
         ports?: number[];
         projectId: string;
@@ -18,6 +43,8 @@ export declare class APIClient extends BaseClient {
             url: string;
             depth?: number;
             revision?: string;
+            username?: string;
+            password?: string;
         } | {
             type: "tarball";
             url: string;
@@ -28,9 +55,25 @@ export declare class APIClient extends BaseClient {
         };
         runtime?: "node22" | "python3.13";
     }): Promise<Parsed<{
-        sandboxId: string;
+        sandbox: {
+            region: string;
+            timeout: number;
+            status: "pending" | "running" | "stopping" | "stopped" | "failed";
+            id: string;
+            memory: number;
+            vcpus: number;
+            runtime: string;
+            requestedAt: number;
+            createdAt: number;
+            updatedAt: number;
+            duration?: number | undefined;
+            startedAt?: number | undefined;
+            requestedStopAt?: number | undefined;
+            stoppedAt?: number | undefined;
+        };
         routes: {
             port: number;
+            url: string;
             subdomain: string;
         }[];
     }>>;
@@ -41,18 +84,26 @@ export declare class APIClient extends BaseClient {
         args: string[];
         env: Record<string, string>;
     }): Promise<Parsed<{
-        cmdId: string;
+        command: {
+            name: string;
+            cwd: string;
+            args: string[];
+            id: string;
+            startedAt: number;
+            sandboxId: string;
+            exitCode: number | null;
+        };
     }>>;
     getCommand(params: {
         sandboxId: string;
         cmdId: string;
         wait: true;
-    }): Promise<Parsed<z.infer<typeof CommandFinished>>>;
+    }): Promise<Parsed<z.infer<typeof CommandFinishedResponse>>>;
     getCommand(params: {
         sandboxId: string;
         cmdId: string;
         wait?: boolean;
-    }): Promise<Parsed<z.infer<typeof Command>>>;
+    }): Promise<Parsed<z.infer<typeof CommandResponse>>>;
     mkDir(params: {
         sandboxId: string;
         path: string;
@@ -76,11 +127,26 @@ export declare class APIClient extends BaseClient {
         path: string;
         cwd?: string;
     }): Promise<NodeJS.ReadableStream | null>;
+    killCommand(params: {
+        sandboxId: string;
+        commandId: string;
+        signal: number;
+    }): Promise<Parsed<{
+        command: {
+            name: string;
+            cwd: string;
+            args: string[];
+            id: string;
+            startedAt: number;
+            sandboxId: string;
+            exitCode: number | null;
+        };
+    }>>;
     getLogs(params: {
         sandboxId: string;
         cmdId: string;
     }): AsyncIterable<z.infer<typeof LogLine>>;
     stopSandbox(params: {
         sandboxId: string;
-    }): Promise<Parsed<z.infer<typeof StoppedSandbox>>>;
+    }): Promise<Parsed<z.infer<typeof SandboxResponse>>>;
 }

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"));
@@ -41,8 +42,11 @@ class APIClient extends base_client_1.BaseClient {
             },
         });
     }
+    async getSandbox(params) {
+        return (0, base_client_1.parseOrThrow)(validators_1.SandboxAndRoutesResponse, await this.request(`/v1/sandboxes/${params.sandboxId}`));
+    }
     async createSandbox(params) {
-        return (0, base_client_1.parseOrThrow)(validators_1.CreatedSandbox, await this.request("/v1/sandboxes", {
+        return (0, base_client_1.parseOrThrow)(validators_1.SandboxAndRoutesResponse, await this.request("/v1/sandboxes", {
             method: "POST",
             body: JSON.stringify({
                 projectId: params.projectId,
@@ -55,7 +59,7 @@ class APIClient extends base_client_1.BaseClient {
         }));
     }
     async runCommand(params) {
-        return (0, base_client_1.parseOrThrow)(validators_1.CreatedCommand, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd`, {
+        return (0, base_client_1.parseOrThrow)(validators_1.CommandResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd`, {
             method: "POST",
             body: JSON.stringify({
                 command: params.command,
@@ -67,11 +71,11 @@ class APIClient extends base_client_1.BaseClient {
     }
     async getCommand(params) {
         return params.wait
-            ? (0, base_client_1.parseOrThrow)(validators_1.CommandFinished, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`, { query: { wait: "true" } }))
-            : (0, base_client_1.parseOrThrow)(validators_1.Command, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`));
+            ? (0, base_client_1.parseOrThrow)(validators_1.CommandFinishedResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`, { query: { wait: "true" } }))
+            : (0, base_client_1.parseOrThrow)(validators_1.CommandResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`));
     }
     async mkDir(params) {
-        return (0, base_client_1.parseOrThrow)(validators_1.WrittenFile, await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
+        return (0, base_client_1.parseOrThrow)(validators_1.EmptyResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
             method: "POST",
             body: JSON.stringify({ path: params.path, cwd: params.cwd }),
         }));
@@ -79,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,
         };
     }
@@ -94,8 +100,8 @@ 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();
-        await (0, base_client_1.parseOrThrow)(validators_1.WrittenFile, await response);
+        writer.end();
+        await (0, base_client_1.parseOrThrow)(validators_1.EmptyResponse, await response);
     }
     async readFile(params) {
         const response = await this.request(`/v1/sandboxes/${params.sandboxId}/fs/read`, {
@@ -107,6 +113,12 @@ class APIClient extends base_client_1.BaseClient {
         }
         return response.body;
     }
+    async killCommand(params) {
+        return (0, base_client_1.parseOrThrow)(validators_1.CommandResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/${params.commandId}/kill`, {
+            method: "POST",
+            body: JSON.stringify({ signal: params.signal }),
+        }));
+    }
     async *getLogs(params) {
         const url = `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}/logs`;
         const response = await this.request(url, { method: "GET" });
@@ -133,7 +145,7 @@ class APIClient extends base_client_1.BaseClient {
     }
     async stopSandbox(params) {
         const url = `/v1/sandboxes/${params.sandboxId}/stop`;
-        return (0, base_client_1.parseOrThrow)(validators_1.StoppedSandbox, await this.request(url, { method: "POST" }));
+        return (0, base_client_1.parseOrThrow)(validators_1.SandboxResponse, await this.request(url, { method: "POST" }));
     }
 }
 exports.APIClient = APIClient;

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

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

package/dist/api-client/index.js

@@ -1,5 +1,20 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APIClient = void 0;
 var api_client_1 = require("./api-client");
 Object.defineProperty(exports, "APIClient", { enumerable: true, get: function () { return api_client_1.APIClient; } });
+__exportStar(require("./validators"), exports);