Skip to content
Docs

Sandbox Authentication

The Sandbox SDK supports two authentication methods: Vercel OIDC tokens (recommended) and access tokens.

The SDK uses Vercel OpenID Connect (OIDC) tokens when available.

Local development: Download a development token by connecting to a Vercel project:

vercel link
vercel env pull

This creates a .env.local file with a VERCEL_OIDC_TOKEN. The token expires after 12 hours, so run vercel env pull again if you see authentication errors.

Production: Vercel manages token expiration automatically when your code runs on Vercel.

Use access tokens when VERCEL_OIDC_TOKEN is unavailable, such as in external CI/CD systems or non-Vercel environments.

You need:

Set these as environment variables:

VERCEL_TEAM_ID=team_xxx
VERCEL_PROJECT_ID=prj_xxx
VERCEL_TOKEN=your_access_token

Then pass them to the SDK:

index.ts
import { Sandbox } from '@vercel/sandbox';
 
const sandbox = await Sandbox.create({
  teamId: process.env.VERCEL_TEAM_ID!,
  projectId: process.env.VERCEL_PROJECT_ID!,
  token: process.env.VERCEL_TOKEN!,
});
ScenarioRecommended method
Local developmentOIDC token via vercel env pull
Deployed on VercelOIDC token (automatic)
External CI/CDAccess token
Non-Vercel hostingAccess token

Each Vercel OIDC token belongs to one Vercel project. The development token that vercel env pull downloads belongs to the project you connected with vercel link. The Sandbox CLI authenticates with VERCEL_OIDC_TOKEN when you don't pass --token and VERCEL_AUTH_TOKEN isn't set. It reads the variable from your environment or from a .env.local file in the current directory. If you also don't pass --scope or --project, the CLI can infer the team and project for a command from the token. A sandbox you create then belongs to the token's project, which can differ from the project you meant to use.

To work in a different team and project, pass both --scope and --project:

Terminal
sandbox create --name my-sandbox --scope my-team --project my-project

The sandbox create command prints the team and project it created the sandbox in, so you can confirm where the sandbox lives:

✅ Sandbox my-sandbox created.
   │ team: my-team
   │ region: iad1
   │ project: my-project
   ╰ connect with: sandbox ssh my-sandbox

Pass the same --scope and --project to later commands that reference the sandbox by name, such as sandbox connect. For the options each command accepts, see the Sandbox CLI reference.

Last updated August 25, 2026

Was this helpful?

supported.