Skip to content
Back to search

sandbox

Vercel Sandbox is an ephemeral compute primitive designed to safely run untrusted or user-generated code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/vercel/sandbox with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/vercel/sandbox'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vercel--sandbox/badge.svg)](/listings/vercel--sandbox)

HTML

<a href="/listings/vercel--sandbox"><img src="/api/listings/vercel--sandbox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

To get started using Ubuntu with Node.js 24, create a new project:

mkdir my-sandbox-app && cd my-sandbox-app
npm init -y
vercel link

Pull your authentication token:

vercel env pull

Install the Sandbox SDK:

pnpm i @vercel/sandbox

Install the Sandbox Skill:

npx skills add vercel/sandbox

Create a `index.mts` file:

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 },
    ports: [3000],
  });

  console.log(`Installing dependencies...`);
  const install = await sandbox.runCommand({
    cmd: "npm",
    args: ["install", "--loglevel", "info"],
    cwd: "sandbox-example-next",
    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"],
    cwd: "sandbox-example-next",
    stderr: process.stderr,
    stdout: process.stdout,
    detached: true,
  });

  await setTimeout(500);
  spawn("open", [sandbox.domain(3000)]);
}

main().catch(console.error);

Run it:

node --experimental-strip-types --env-file .env.local index.mts

This will:

- Start a sandbox, seeding it with a git repository. - Install dependencies. - Run a `next dev` server - Open it in your browser

All while streaming logs to your local terminal.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 254 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Vercel Sandbox
  2. Vercel Sandbox allows you to run arbitrary code in isolated Linux microVMs.
  3. Sandboxes are persistent by default: the filesystem is snapshotted when a
  4. session stops and restored when it resumes. View the documentation
  5. [here](https://vercel.com/docs/vercel-sandbox).
  6. ## Packages
  7. - [`@vercel/sandbox`](https://www.npmjs.com/package/@vercel/sandbox) - The SDK for programmatic access to Vercel Sandbox. [Source](https://github.com/vercel/sandbox/tree/main/packages/vercel-sandbox) | [Documentation](https://vercel.com/docs/vercel-sandbox/sdk-reference)
  8. - [`sandbox`](https://www.npmjs.com/package/sandbox) - The CLI for interacting with Vercel Sandbox from the command line. [Source](https://github.com/vercel/sandbox/tree/main/packages/sandbox) | [Documentation](https://vercel.com/docs/vercel-sandbox/cli-reference)
  9. ## What is a sandbox?
  10. A sandbox is an isolated Linux system for your experimentation and use.
  11. Internally, it is a Firecracker MicroVM that is powered by [the same
  12. infrastructure][hive] that powers 2M+ builds a day at Vercel.
  13. ## Getting started
  14. To get started using Ubuntu with Node.js 24, create a new project:
  15. ```sh
  16. mkdir my-sandbox-app && cd my-sandbox-app
  17. npm init -y
  18. vercel link
  19. ```
  20. Pull your authentication token:
  21. ```sh
  22. vercel env pull
  23. ```
  24. Install the Sandbox SDK:
  25. ```sh
  26. pnpm i @vercel/sandbox
  27. ```
  28. Install the Sandbox Skill:
  29. ```sh
  30. npx skills add vercel/sandbox
  31. ```
  32. Create a `index.mts` file:
  33. ```ts
  34. import { Sandbox } from "@vercel/sandbox";
  35. import { setTimeout } from "timers/promises";
  36. import { spawn } from "child_process";
  37. async function main() {
  38. const sandbox = await Sandbox.create({
  39. source: {
  40. url: "https://github.com/vercel/sandbox-example-next.git",
  41. type: "git",
  42. },
  43. resources: { vcpus: 4 },
  44. ports: [3000],
  45. });
  46. console.log(`Installing dependencies...`);
  47. const install = await sandbox.runCommand({
  48. cmd: "npm",
  49. args: ["install", "--loglevel", "info"],
  50. cwd: "sandbox-example-next",
  51. stderr: process.stderr,
  52. stdout: process.stdout,
  53. });
  54. if (install.exitCode != 0) {
  55. console.log("installing packages failed");
  56. process.exit(1);
  57. }
  58. console.log(`Starting the development server...`);
  59. await sandbox.runCommand({
  60. cmd: "npm",
  61. args: ["run", "dev"],
  62. cwd: "sandbox-example-next",
  63. stderr: process.stderr,
  64. stdout: process.stdout,
  65. detached: true,
  66. });
  67. await setTimeout(500);
  68. spawn("open", [sandbox.domain(3000)]);
  69. }
  70. main().catch(console.error);
  71. ```
  72. Run it:
  73. ```sh
  74. node --experimental-strip-types --env-file .env.local index.mts
  75. ```
  76. This will:
  77. - Start a sandbox, seeding it with a git repository.
  78. - Install dependencies.
  79. - Run a `next dev` server
  80. - Open it in your browser
  81. All while streaming logs to your local terminal.
  82. ## Authentication
  83. ### Vercel OIDC token
  84. The SDK uses Vercel OIDC tokens to authenticate whenever available. This is the
  85. most straightforward and recommended way to authenticate.
  86. When developing locally, you can download a development token to `.env.local`
  87. using `vercel env pull`. After 12 hours the development token expires, meaning
  88. you will have to call `vercel env pull` again.
  89. In production, Vercel manages token expiration for you.
  90. ### Access token
  91. If you want to use the SDK from an environment where `VERCEL_OIDC_TOKEN` is
  92. unavailable, you can also authenticate using an access token:
  93. - Go to your team settings, and copy the team ID.
  94. - Go to a project's settings, and copy the project ID.
  95. - Go to your Vercel account settings and [create a token][create-token]. Make
  96. sure it is scoped to the team ID from the previous step.
  97. Set your team ID, project ID, and token to the environment variables
  98. `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_TOKEN`. Then pass these to
  99. the `create` method:
  100. ```ts
  101. const sandbox = await Sandbox.create({
  102. teamId: process.env.VERCEL_TEAM_ID!,
  103. projectId: process.env.VERCEL_PROJECT_ID!,
  104. token: process.env.VERCEL_TOKEN!,
  105. source: {
  106. url: "https://github.com/vercel/sandbox-example-next.git",
  107. type: "git",
  108. },
  109. resources: { vcpus: 4 },
  110. // Defaults to 5 minutes. The maximum is 24 hours for Pro/Enterprise, and 45 minutes for Hobby.
  111. timeout: ms("5m"),
  112. ports: [3000],
  113. });
  114. ```
  115. ## Workflow DevKit integration
  116. `Sandbox` and `CommandFinished` support serialization with the
  117. [Workflow DevKit](https://vercel.com/docs/workflow). When a sandbox instance
  118. crosses a step boundary the SDK serializes sandbox metadata and routes, then
  119. rehydrates synchronously from that snapshot. Deserialized instances lazily
  120. recreate an API client using OIDC or environment credentials when needed.
  121. ## Limitations
  122. - Max resources: 4 vCPUs on Hobby, 8 vCPUs on Pro, 32 vCPUs on Enterprise. You will get 2048 MB of memory per vCPU.
  123. - Sandboxes have a maximum duration of 24 hours for Pro/Enterprise and 45 minutes for Hobby,
  124. with a default of 5 minutes. This can be configured using the `timeout` option of `Sandbox.create()`.
  125. ## Sudo access
  126. The default image allows users to run commands as root. This can be used to
  127. install packages and system tools:
  128. ```typescript
  129. import { Sandbox } from "@vercel/sandbox";
  130. const sandbox = await Sandbox.create();
  131. await sandbox.runCommand({
  132. cmd: "apt-get",
  133. args: ["update"],
  134. sudo: true,
  135. });
  136. await sandbox.runCommand({
  137. cmd: "apt-get",
  138. args: ["install", "-y", "golang-go"],
  139. sudo: true,
  140. });
  141. ```
  142. Sandbox runs sudo in the following configuration:
  143. - `HOME` is set to `/root` – Executed commands will source root's configuration
  144. files (e.g. `.gitconfig`, `.bashrc`, etc).
  145. - Environment variables are not reset before executing the command.
  146. - `PATH` is left unchanged – sudo won't change the value of PATH, so local or
  147. project-specific binaries will still be found.
  148. [create-token]: https://vercel.com/account/settings/tokens
  149. [hive]: https://vercel.com/blog/a-deep-dive-into-hive-vercels-builds-infrastructure
  150. [vcr-docs]: https://vercel.com/docs/container-registry
  151. [images-docs]: https://vercel.com/docs/sandbox/concepts/images
  152. The skill provides comprehensive guidance on using the `@vercel/sandbox` SDK, including code patterns, best practices, and API reference.
  153. ## Default image
  154. Sandboxes use [`vercel/sandbox/universal:latest`](./images/universal) by
  155. default. This Ubuntu-based image includes Node.js 24, Bun, Python 3.14, coding
  156. agents, and common development and debugging utilities. It runs as the
  157. `ubuntu` user with passwordless sudo.
  158. ## Vercel Managed Images
  159. Vercel provides several public images optimized to use in Sandbox.
  160. The Dockerfiles for Vercel Managed Images published under `vercel/sandbox/*` live in [`images/`](https://github.com/vercel/sandbox/tree/main/images):
  161. - [`vercel/sandbox/universal:latest`](./images/universal): Default image with Node.js, Python, coding agents, and utilities.
  162. - [`vercel/sandbox/node:22|24|26`](./images/node): Node.js with pnpm.
  163. - [`vercel/sandbox/python:3.14`](./images/python): Python with pip, venv, and uv.
  164. - [`vercel/sandbox/ubuntu:latest`](./images/ubuntu): Minimal Ubuntu base.
  165. - [`vercel/sandbox/arch:latest`](./images/arch): Arch Linux with yay/AUR support.
  166. See the [images README](https://github.com/vercel/sandbox/tree/main/images#readme)
  167. for build instructions.
  168. ### Custom images
  169. A sandbox can boot from any OCI image by pushing it to
  170. [Vercel Container Registry (VCR)][vcr-docs] and passing `image` to
  171. `Sandbox.create()`.
  172. Build and push a `linux/amd64` image to VCR:
  173. ```sh
  174. vercel vcr login docker
  175. vercel vcr build docker . my-repository:latest --push
  176. ```
  177. The CLI uses the linked project, defaults to `linux/amd64`, and constructs the
  178. full VCR reference automatically.
  179. VCR implements the Docker Registry API, so any OCI compatible tooling can also be used, such as `buildah` or `podman`.
  180. Then start a sandbox from it:
  181. ```ts
  182. const sandbox = await Sandbox.create({
  183. image: "my-repository:latest",
  184. });
  185. ```
  186. See the [images documentation][images-docs] for more details.
  187. ## Authors
  188. This library is created by [Vercel](https://vercel.com) team members, with contributions from the [Open Source Community](https://github.com/vercel/sandbox/graphs/contributors) welcome and highly appreciated.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.