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 pullThis 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:
- Your Vercel team ID
- Your Vercel project ID
- A Vercel access token with access to the team
Set these as environment variables:
VERCEL_TEAM_ID=team_xxx
VERCEL_PROJECT_ID=prj_xxx
VERCEL_TOKEN=your_access_tokenThen pass them to the SDK:
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!,
});
| Scenario | Recommended method |
|---|---|
| Local development | OIDC token via vercel env pull |
| Deployed on Vercel | OIDC token (automatic) |
| External CI/CD | Access token |
| Non-Vercel hosting | Access 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:
sandbox create --name my-sandbox --scope my-team --project my-projectThe 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-sandboxPass 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.
Was this helpful?