@vercel/sandbox 0.0.12 → 0.0.14

package/.turbo/turbo-build.log

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

package/.turbo/turbo-typecheck.log

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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @vercel/sandbox
 
+## 0.0.14
+
+### Patch Changes
+
+- Use `@vercel/oidc` for authentication ([#87](https://github.com/vercel/sandbox-sdk/pull/87))
+
+- Expose more data in `Command` ([#85](https://github.com/vercel/sandbox-sdk/pull/85))
+
+## 0.0.13
+
+### Patch Changes
+
+- Add sudo support to running commands ([#72](https://github.com/vercel/sandbox-sdk/pull/72))
+
 ## 0.0.12
 
 ### Patch Changes

package/README.md

@@ -35,7 +35,52 @@ vercel env pull
 
 Now create `next-dev.ts`:
 
-{@includeCode ../cli/src/example-next.ts}
+```ts
+import ms from "ms";
+import { Sandbox } from "@vercel/sandbox";
+import { setTimeout } from "timers/promises";
+import { spawn } from "child_process";
+
+async function main() {
+  const sandbox = await Sandbox.create({
+    source: {
+      url: "https://github.com/vercel/sandbox-example-next.git",
+      type: "git",
+    },
+    resources: { vcpus: 4 },
+    timeout: ms("5m"),
+    ports: [3000],
+    runtime: "node22",
+  });
+
+  console.log(`Installing dependencies...`);
+  const install = await sandbox.runCommand({
+    cmd: "npm",
+    args: ["install", "--loglevel", "info"],
+    stderr: process.stderr,
+    stdout: process.stdout,
+  });
+
+  if (install.exitCode != 0) {
+    console.log("installing packages failed");
+    process.exit(1);
+  }
+
+  console.log(`Starting the development server...`);
+  await sandbox.runCommand({
+    cmd: "npm",
+    args: ["run", "dev"],
+    stderr: process.stderr,
+    stdout: process.stdout,
+    detached: true,
+  });
+
+  await setTimeout(500);
+  spawn("open", [sandbox.domain(3000)]);
+}
+
+main().catch(console.error);
+```
 
 Run it like this:
 
@@ -89,6 +134,7 @@ const sandbox = await Sandbox.create({
     type: "git",
   },
   resources: { vcpus: 4 },
+  // Defaults to 5 minutes. The maximum is 45 minutes.
   timeout: ms("5m"),
   ports: [3000],
   runtime: "node22",
@@ -97,8 +143,9 @@ const sandbox = await Sandbox.create({
 
 ## Limitations
 
-- `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.
+- Sandboxes have a maximum runtime duration of 45 minutes, with a default of 5
+  minutes. This can be configured using the `timeout` option of `Sandbox.create()`.
 
 ## System
 
@@ -131,5 +178,33 @@ zstd
 - User code is executed as the `vercel-sandbox` user.
 - `/vercel/sandbox` is writable.
 
+## Sudo access
+
+The `node22` and `python3.13` images allow users to run commands as root. This
+can be used to install packages and system tools:
+
+```typescript
+import { Sandbox } from "@vercel/sandbox";
+
+const sandbox = await Sandbox.create();
+await sandbox.runCommand({
+  cmd: "dnf",
+  args: ["install", "-y", "golang"],
+  sudo: true,
+});
+```
+
+Sandbox runs sudo in the following configuration:
+
+- `HOME` is set to `/root` – Executed commands will source root's configuration
+  files (e.g. `.gitconfig`, `.bashrc`, etc).
+- Environment variables are not reset before executing the command.
+- `PATH` is left unchanged – sudo won’t change the value of PATH, so local or
+  project-specific binaries will still be found.
+
+Both these images are based on Amazon Linux 2023. The full package list is
+available [here](https://docs.aws.amazon.com/linux/al2023/release-notes/all-packages-AL2023.7.html).
+
 [create-token]: https://vercel.com/account/settings/tokens
 [hive]: https://vercel.com/blog/a-deep-dive-into-hive-vercels-builds-infrastructure
+[al-2023-packages]: https://docs.aws.amazon.com/linux/al2023/release-notes/all-packages-AL2023.7.html

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

@@ -83,6 +83,7 @@ export declare class APIClient extends BaseClient {
         command: string;
         args: string[];
         env: Record<string, string>;
+        sudo: boolean;
     }): Promise<Parsed<{
         command: {
             name: string;

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

@@ -66,6 +66,7 @@ class APIClient extends base_client_1.BaseClient {
                 args: params.args,
                 cwd: params.cwd,
                 env: params.env,
+                sudo: params.sudo,
             }),
         }));
     }

package/dist/command.d.ts

@@ -24,10 +24,13 @@ export declare class Command {
      * Data for the command execution.
      */
     private cmd;
+    exitCode: number | null;
     /**
      * ID of the command execution.
      */
     get cmdId(): string;
+    get cwd(): string;
+    get startedAt(): number;
     /**
      * @param params - Object containing the client, sandbox ID, and command ID.
      * @param params.client - API client used to interact with the backend.

package/dist/command.js

@@ -19,6 +19,12 @@ class Command {
     get cmdId() {
         return this.cmd.id;
     }
+    get cwd() {
+        return this.cmd.cwd;
+    }
+    get startedAt() {
+        return this.cmd.startedAt;
+    }
     /**
      * @param params - Object containing the client, sandbox ID, and command ID.
      * @param params.client - API client used to interact with the backend.
@@ -29,6 +35,7 @@ class Command {
         this.client = client;
         this.sandboxId = sandboxId;
         this.cmd = cmd;
+        this.exitCode = cmd.exitCode ?? null;
     }
     /**
      * Iterate over the output of this command.

package/dist/sandbox.d.ts

@@ -78,6 +78,10 @@ interface RunCommandParams {
      * Environment variables to set for this command
      */
     env?: Record<string, string>;
+    /**
+     * If true, execute this command with root privileges. Defaults to false.
+     */
+    sudo?: boolean;
     /**
      * If true, the command will return without waiting for `exitCode`
      */

package/dist/sandbox.js

@@ -112,6 +112,7 @@ class Sandbox {
             args: params.args ?? [],
             cwd: params.cwd,
             env: params.env ?? {},
+            sudo: params.sudo ?? false,
         });
         const command = new command_1.Command({
             client: this.client,

package/dist/utils/get-credentials.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCredentials = getCredentials;
-const get_vercel_oidc_token_1 = require("./get-vercel-oidc-token");
+const oidc_1 = require("@vercel/oidc");
 const decode_base64_url_1 = require("./decode-base64-url");
 const zod_1 = require("zod");
 /**
@@ -19,7 +19,7 @@ function getCredentials(params) {
     if (credentials) {
         return credentials;
     }
-    const oidcToken = (0, get_vercel_oidc_token_1.getVercelOidcToken)();
+    const oidcToken = (0, oidc_1.getVercelOidcTokenSync)();
     if (oidcToken) {
         return getCredentialsFromOIDCToken(oidcToken);
     }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.12";
+export declare const VERSION = "0.0.14";

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
+    "@vercel/oidc": "^2.0.0",
     "async-retry": "1.3.3",
     "form-data": "3.0.0",
     "jsonlines": "0.1.1",

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

@@ -102,6 +102,7 @@ export class APIClient extends BaseClient {
     command: string;
     args: string[];
     env: Record<string, string>;
+    sudo: boolean;
   }) {
     return parseOrThrow(
       CommandResponse,
@@ -112,6 +113,7 @@ export class APIClient extends BaseClient {
           args: params.args,
           cwd: params.cwd,
           env: params.env,
+          sudo: params.sudo,
         }),
       }),
     );

package/src/command.test.ts

@@ -4,11 +4,7 @@ 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!,
-  });
+  sandbox = await Sandbox.create();
 });
 
 afterEach(async () => {
@@ -72,3 +68,35 @@ it("Kills a command with a SIGTERM", async () => {
   const result = await cmd.wait();
   expect(result.exitCode).toBe(143); // 128 + 15
 });
+
+it("can execute commands with sudo", async () => {
+  const cmd = await sandbox.runCommand({
+    cmd: "env",
+    sudo: true,
+    env: {
+      FOO: "bar",
+    },
+  });
+
+  expect(cmd.exitCode).toBe(0);
+
+  const output = await cmd.stdout();
+  expect(output).toContain("FOO=bar\n");
+  expect(output).toContain("USER=root\n");
+  expect(output).toContain("SUDO_USER=vercel-sandbox\n");
+
+  // The actual path contains more, but this is enough
+  // to verify that we do not reset it to a default path.
+  expect(output).toContain("PATH=/vercel/bin");
+
+  const dnf = await sandbox.runCommand({
+    cmd: "dnf",
+    args: ["install", "-y", "golang"],
+    sudo: true,
+  });
+
+  expect(dnf.exitCode).toBe(0);
+
+  const which = await sandbox.runCommand("which", ["go"]);
+  expect(which.output()).resolves.toContain("/usr/bin/go");
+});

package/src/command.ts

@@ -28,6 +28,8 @@ export class Command {
    */
   private cmd: CommandData;
 
+  public exitCode: number | null;
+
   /**
    * ID of the command execution.
    */
@@ -35,6 +37,14 @@ export class Command {
     return this.cmd.id;
   }
 
+  get cwd() {
+    return this.cmd.cwd;
+  }
+
+  get startedAt() {
+    return this.cmd.startedAt;
+  }
+
   /**
    * @param params - Object containing the client, sandbox ID, and command ID.
    * @param params.client - API client used to interact with the backend.
@@ -53,6 +63,7 @@ export class Command {
     this.client = client;
     this.sandboxId = sandboxId;
     this.cmd = cmd;
+    this.exitCode = cmd.exitCode ?? null;
   }
 
   /**

package/src/sandbox.test.ts

@@ -5,11 +5,7 @@ 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!,
-  });
+  sandbox = await Sandbox.create();
 });
 
 afterEach(async () => {
@@ -18,8 +14,8 @@ afterEach(async () => {
 
 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") },
+    { path: "hello1.txt", content: Buffer.from("Hello 1") },
+    { path: "hello2.txt", content: Buffer.from("Hello 2") },
   ]);
 
   const content1 = await sandbox.readFile({ path: "hello1.txt" });

package/src/sandbox.ts

@@ -80,6 +80,10 @@ interface RunCommandParams {
    * Environment variables to set for this command
    */
   env?: Record<string, string>;
+  /**
+   * If true, execute this command with root privileges. Defaults to false.
+   */
+  sudo?: boolean;
   /**
    * If true, the command will return without waiting for `exitCode`
    */
@@ -268,6 +272,7 @@ export class Sandbox {
       args: params.args ?? [],
       cwd: params.cwd,
       env: params.env ?? {},
+      sudo: params.sudo ?? false,
     });
 
     const command = new Command({

package/src/utils/get-credentials.ts

@@ -1,4 +1,4 @@
-import { getVercelOidcToken } from "./get-vercel-oidc-token";
+import { getVercelOidcTokenSync } from "@vercel/oidc";
 import { decodeBase64Url } from "./decode-base64-url";
 import { z } from "zod";
 
@@ -34,7 +34,7 @@ export function getCredentials<T>(params?: T | Credentials): Credentials {
     return credentials;
   }
 
-  const oidcToken = getVercelOidcToken();
+  const oidcToken = getVercelOidcTokenSync();
   if (oidcToken) {
     return getCredentialsFromOIDCToken(oidcToken);
   }

package/src/version.ts

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

package/vercel.json

@@ -0,0 +1,9 @@
+{
+  "redirects": [
+    {
+      "source": "/(.*)",
+      "destination": "https://vercel.com/docs/vercel-sandbox",
+      "permanent": true
+    }
+  ]
+}

package/dist/utils/get-vercel-oidc-token.d.ts

@@ -1,6 +0,0 @@
-/**
- * This function is implemented in @vercel/functions but it is asynchronous.
- * In order to keep it synchronous, we are implementing it here as well.
- * Ideally we should remove this and use the one from @vercel/functions.
- */
-export declare function getVercelOidcToken(): string | undefined;

package/dist/utils/get-vercel-oidc-token.js

@@ -1,21 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getVercelOidcToken = getVercelOidcToken;
-/**
- * This function is implemented in @vercel/functions but it is asynchronous.
- * In order to keep it synchronous, we are implementing it here as well.
- * Ideally we should remove this and use the one from @vercel/functions.
- */
-function getVercelOidcToken() {
-    const token = getContext().headers?.["x-vercel-oidc-token"] ??
-        process.env.VERCEL_OIDC_TOKEN;
-    if (!token && process.env.NODE_ENV === "production") {
-        throw new Error(`The 'x-vercel-oidc-token' header is missing from the request. Do you have the OIDC option enabled in the Vercel project settings?`);
-    }
-    return token;
-}
-const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
-function getContext() {
-    const fromSymbol = globalThis;
-    return fromSymbol[SYMBOL_FOR_REQ_CONTEXT]?.get?.() ?? {};
-}

package/src/utils/get-vercel-oidc-token.ts

@@ -1,31 +0,0 @@
-/**
- * This function is implemented in @vercel/functions but it is asynchronous.
- * In order to keep it synchronous, we are implementing it here as well.
- * Ideally we should remove this and use the one from @vercel/functions.
- */
-export function getVercelOidcToken(): string | undefined {
-  const token =
-    getContext().headers?.["x-vercel-oidc-token"] ??
-    process.env.VERCEL_OIDC_TOKEN;
-
-  if (!token && process.env.NODE_ENV === "production") {
-    throw new Error(
-      `The 'x-vercel-oidc-token' header is missing from the request. Do you have the OIDC option enabled in the Vercel project settings?`,
-    );
-  }
-
-  return token;
-}
-
-const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
-
-interface Context {
-  headers?: Record<string, string>;
-}
-
-function getContext(): Context {
-  const fromSymbol: typeof globalThis & {
-    [SYMBOL_FOR_REQ_CONTEXT]?: { get?: () => Context };
-  } = globalThis;
-  return fromSymbol[SYMBOL_FOR_REQ_CONTEXT]?.get?.() ?? {};
-}