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.
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
Markdown
[](/listings/vercel--sandbox)HTML
<a href="/listings/vercel--sandbox"><img src="/api/listings/vercel--sandbox/badge.svg" alt="findsafeskills safety rating" /></a>Install
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.
- # Vercel Sandbox
- Vercel Sandbox allows you to run arbitrary code in isolated Linux microVMs.
- Sandboxes are persistent by default: the filesystem is snapshotted when a
- session stops and restored when it resumes. View the documentation
- [here](https://vercel.com/docs/vercel-sandbox).
- ## Packages
- - [`@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)
- - [`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)
- ## What is a sandbox?
- A sandbox is an isolated Linux system for your experimentation and use.
- Internally, it is a Firecracker MicroVM that is powered by [the same
- infrastructure][hive] that powers 2M+ builds a day at Vercel.
- ## Getting started
- To get started using Ubuntu with Node.js 24, create a new project:
- ```sh
- mkdir my-sandbox-app && cd my-sandbox-app
- npm init -y
- vercel link
- ```
- Pull your authentication token:
- ```sh
- vercel env pull
- ```
- Install the Sandbox SDK:
- ```sh
- pnpm i @vercel/sandbox
- ```
- Install the Sandbox Skill:
- ```sh
- npx skills add vercel/sandbox
- ```
- Create a `index.mts` file:
- ```ts
- 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:
- ```sh
- 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.
- ## 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 },
- // Defaults to 5 minutes. The maximum is 24 hours for Pro/Enterprise, and 45 minutes for Hobby.
- timeout: ms("5m"),
- ports: [3000],
- });
- ```
- ## Workflow DevKit integration
- `Sandbox` and `CommandFinished` support serialization with the
- [Workflow DevKit](https://vercel.com/docs/workflow). When a sandbox instance
- crosses a step boundary the SDK serializes sandbox metadata and routes, then
- rehydrates synchronously from that snapshot. Deserialized instances lazily
- recreate an API client using OIDC or environment credentials when needed.
- ## Limitations
- - Max resources: 4 vCPUs on Hobby, 8 vCPUs on Pro, 32 vCPUs on Enterprise. You will get 2048 MB of memory per vCPU.
- - Sandboxes have a maximum duration of 24 hours for Pro/Enterprise and 45 minutes for Hobby,
- with a default of 5 minutes. This can be configured using the `timeout` option of `Sandbox.create()`.
- ## Sudo access
- The default image allows 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: "apt-get",
- args: ["update"],
- sudo: true,
- });
- await sandbox.runCommand({
- cmd: "apt-get",
- args: ["install", "-y", "golang-go"],
- 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.
- [create-token]: https://vercel.com/account/settings/tokens
- [hive]: https://vercel.com/blog/a-deep-dive-into-hive-vercels-builds-infrastructure
- [vcr-docs]: https://vercel.com/docs/container-registry
- [images-docs]: https://vercel.com/docs/sandbox/concepts/images
- The skill provides comprehensive guidance on using the `@vercel/sandbox` SDK, including code patterns, best practices, and API reference.
- ## Default image
- Sandboxes use [`vercel/sandbox/universal:latest`](./images/universal) by
- default. This Ubuntu-based image includes Node.js 24, Bun, Python 3.14, coding
- agents, and common development and debugging utilities. It runs as the
- `ubuntu` user with passwordless sudo.
- ## Vercel Managed Images
- Vercel provides several public images optimized to use in Sandbox.
- The Dockerfiles for Vercel Managed Images published under `vercel/sandbox/*` live in [`images/`](https://github.com/vercel/sandbox/tree/main/images):
- - [`vercel/sandbox/universal:latest`](./images/universal): Default image with Node.js, Python, coding agents, and utilities.
- - [`vercel/sandbox/node:22|24|26`](./images/node): Node.js with pnpm.
- - [`vercel/sandbox/python:3.14`](./images/python): Python with pip, venv, and uv.
- - [`vercel/sandbox/ubuntu:latest`](./images/ubuntu): Minimal Ubuntu base.
- - [`vercel/sandbox/arch:latest`](./images/arch): Arch Linux with yay/AUR support.
- See the [images README](https://github.com/vercel/sandbox/tree/main/images#readme)
- for build instructions.
- ### Custom images
- A sandbox can boot from any OCI image by pushing it to
- [Vercel Container Registry (VCR)][vcr-docs] and passing `image` to
- `Sandbox.create()`.
- Build and push a `linux/amd64` image to VCR:
- ```sh
- vercel vcr login docker
- vercel vcr build docker . my-repository:latest --push
- ```
- The CLI uses the linked project, defaults to `linux/amd64`, and constructs the
- full VCR reference automatically.
- VCR implements the Docker Registry API, so any OCI compatible tooling can also be used, such as `buildah` or `podman`.
- Then start a sandbox from it:
- ```ts
- const sandbox = await Sandbox.create({
- image: "my-repository:latest",
- });
- ```
- See the [images documentation][images-docs] for more details.
- ## Authors
- 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 inFree to use. If it’s helped, pass it on.