Vercel Sandbox examples

Learn how to use the Sandbox SDK through real-life examples.

In this example, you create an isolated environment from a private Git repository by authenticating with a GitHub personal access token or GitHub App token, and run a simple command inside the sandbox.

The Sandbox.create() method initializes the environment with the provided repository and configuration options, including authentication credentials, timeout, and exposed ports. Once created, you can execute commands inside the sandboxed environment using runCommand.

import { Sandbox } from '@vercel/sandbox';
import ms from 'ms';
 
async function main() {
  const sandbox = await Sandbox.create({
    source: {
      url: 'https://github.com/vercel/some-private-repo.git',
      type: 'git',
      // For GitHub, you can use a fine grained, classic personal access token or GitHub App installation access token
      username: 'x-access-token',
      password: process.env.GIT_ACCESS_TOKEN!,
    },
    timeout: ms('5m'),
    ports: [3000],
  });
 
  const echo = await sandbox.runCommand('echo', ['Hello sandbox!']);
  console.log(`Message: ${await echo.stdout()}`);
}
 
main().catch(console.error);

There are several ways to authenticate with private GitHub repositories.

Fine-grained tokens provide repository-specific access and enhanced security:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens

2. Click Generate new token

3. Configure the token:

   • Token name: Give it a descriptive name (e.g., "Vercel Sandbox Access")
   • Expiration: Set an appropriate expiration date
   • Resource owner: Select your account or organization
   • Repository access: Choose "Selected repositories" and select your private repo
   • Repository permissions: Grant at minimum:
     • Contents: Read (to clone the repository)
     • Metadata: Read (for basic repository information)

4. Click "Generate token" and copy the token

5. Set it as an environment variable and run your sandbox script

   terminal

   export GIT_ACCESS_TOKEN=ghp_your_token_here
   node --experimental-strip-types ./private-repo.ts

• Create a classic personal access token
• Create a GitHub App installation token