Quickstart

This guide shows you how to run your first code in a Vercel Sandbox.

• A Vercel account
• Vercel CLI installed (npm i -g vercel)
• Node.js 22+

pnpm i @vercel/sandbox

Before you can create sandboxes, you need to connect your local directory to a Vercel project. This project handles authentication for you, so Vercel knows who's creating sandboxes and can track usage against your account.

Don't have a project yet? No problem. You can create an empty one just for sandbox development:

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

When prompted, select Create a new project. The project doesn't need any code deployed. It just needs to exist so Vercel can generate authentication tokens for you.

Already have a project? Link to it from your working directory:

vercel link

Once linked, pull your environment variables to get an authentication token:

vercel env pull

This creates a .env.local file containing a token that the SDK uses to authenticate your requests. The token expires after 12 hours during local development, so run vercel env pull again when you see authentication errors.

When you deploy to Vercel, token management happens automatically.

Create a file that creates a sandbox and runs a command:

import { Sandbox } from '@vercel/sandbox';
 
const sandbox = await Sandbox.create();
 
const result = await sandbox.runCommand('echo', ['Hello from Vercel Sandbox!']);
console.log(await result.stdout());
 
await sandbox.stop();

node --env-file .env.local index.ts

You should see:

1. Installed the SDK: Added the Vercel Sandbox package to your project.
2. Connected to a project: Linked to a Vercel project that handles authentication.
3. Pulled a token: Downloaded credentials that let the SDK create sandboxes on your behalf.
4. Created a sandbox: Spun up an isolated Linux microVM.
5. Ran a command: Executed code inside the secure environment.
6. Cleaned up: Stopped the sandbox to free resources.

Now that you have the basics working, explore more:

• Run a development server: Clone a repo and run a Next.js app in a sandbox.
• Use private repositories: Authenticate with GitHub to clone private repos.
• Install system packages: Use dnf to install additional tools.
• SDK Reference: Full API documentation.
• CLI Reference: Manage sandboxes from the terminal.