---
title: Using private GitHub repositories with Vercel Sandbox
description: Learn how to use Vercel Sandbox with private GitHub repositories using fine-grained tokens, classic tokens, or GitHub App tokens.
url: "https://vercel.com/kb/guide/sandbox-private-github-repositories"
published: 2026-02-09
last_updated: 2026-05-26
authors: Allen Zhou
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

When using [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) with private repositories, you need to authenticate with a [GitHub personal access token](#fine-grained-personal-access-token) or [Github App token](#github-app-installation-token). This guide explains how.

## Prerequisites

- A [Vercel](https://vercel.com/signup) account
  
- The `@vercel/sandbox` SDK [installed](https://vercel.com/docs/vercel-sandbox/quickstart#install-the-sdk)
  
- Access to a private GitHub repository
  

## Create a sandbox from a private repository

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`.

```typescript
import { Sandbox } from '@vercel/sandbox';
import ms from 'ms';

async function main() {
  const sandbox = await Sandbox.create({
    source: {
      url: 'https://github.com/your-org/private-repo.git',
      type: 'git',
      username: 'x-access-token',
      password: process.env.GIT_ACCESS_TOKEN!,
    },
    timeout: ms('5m'),
    ports: [3000],
  });

  const result = await sandbox.runCommand('echo', ['Hello sandbox!']);
  console.log(`Message: ${await result.stdout()}`);
}

main().catch(console.error);
```

## Authentication options

GitHub offers several authentication methods. Choose the one that best fits your use case.

### Fine-grained personal access token

Fine-grained tokens offer repository-specific access and enhanced security. This is the recommended approach for individual developers.

1. Go to [GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens](https://github.com/settings/personal-access-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 `Contents: Read` and `Metadata: Read`
  

1. Click **Generate token** and copy the token
   

### GitHub App installation token

For platforms where users install your GitHub App, use installation access tokens. This is the recommended approach for multi-tenant platforms.

GitHub App tokens provide several advantages:

- Short-lived tokens (1 hour) reduce security risk
  
- Users grant access through GitHub's familiar OAuth flow
  
- Tokens are scoped to specific installations
  
- Higher rate limits than personal access tokens
  

Generate an installation token using the GitHub API:

```typescript
import { App } from '@octokit/app';
import { Sandbox } from '@vercel/sandbox';

const app = new App({
  appId: process.env.GITHUB_APP_ID!,
  privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
});

async function createSandboxForUser(installationId: number, repoUrl: string) {
  // Generate a short-lived installation token
  const octokit = await app.getInstallationOctokit(installationId);
  const { token } = await octokit.rest.apps.createInstallationAccessToken({
    installation_id: installationId,
  });

  const sandbox = await Sandbox.create({
    source: {
      url: repoUrl,
      type: 'git',
      username: 'x-access-token',
      password: token,
    },
    timeout: 5 * 60 * 1000,
    ports: [3000],
  });

  return sandbox;
}
```

### Classic personal access token

Classic tokens work similarly to fine-grained tokens but with broader scope. Create one at [GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens) with the `repo` scope.

## Building a platform with user repositories

When building a platform where users bring their own private repositories, follow this pattern:

1. **Create a GitHub App** and configure it with the `Contents: Read` permission
   
2. **Users install your app** on their repositories through GitHub's OAuth flow
   
3. **Store the installation ID** when the user completes the installation
   
4. **Generate a fresh token** each time you create a sandbox
   
5. **Pass the token** to `Sandbox.create()` as shown above
   

## Running commands in the sandbox

After creating the sandbox, run commands to install dependencies and start your application:

```typescript
const sandbox = await Sandbox.create({
  source: {
    url: 'https://github.com/your-org/private-repo.git',
    type: 'git',
    username: 'x-access-token',
    password: token,
  },
  timeout: 5 * 60 * 1000,
  ports: [3000],
});

// Install dependencies
const install = await sandbox.runCommand({
  cmd: 'npm',
  args: ['install'],
  stdout: process.stdout,
  stderr: process.stderr,
});

if (install.exitCode !== 0) {
  throw new Error('Installation failed');
}

// Start the dev server in the background
await sandbox.runCommand({
  cmd: 'npm',
  args: ['run', 'dev'],
  detached: true,
});

// Get the sandbox URL
console.log(`Sandbox running at: ${sandbox.domain(3000)}`);
```

## Security considerations

- **Never log or store tokens in plain text**
  
- **Use environment variables** to pass tokens to your application
  
- **Prefer short-lived tokens** (GitHub App installation tokens) over long-lived personal access tokens
  
- **Grant minimal permissions** Read is sufficient for cloning
  
- **Rotate tokens regularly** if using personal access tokens
  

* * *

Use the Vercel AI Action to call the AI Gateway inside a GitHub Action. Generate text or structured JSON, set system messages, and handle untrusted input safely.

[Run AI prompts in your GitHub Actions with the Vercel AI Action](/kb/guide/run-ai-prompts-in-your-github-actions-with-the-vercel-ai-action)

## Related Documentation

- [Vercel Sandbox](/docs/vercel-sandbox)

## More Vercel Sandbox guides

- [Build a v0-style app builder with OpenAI Agents API and Vercel Sandbox](/kb/guide/v0-clone-openai-agents-vercel-sandbox): Build a chat-to-app workspace with live Next.js previews, follow-up edits, and saved projects using the OpenAI Agents API preview, Vercel Sandbox, and Queues.
- [Investigate GitHub issues with \`HarnessAgent\` and Vercel Sandbox](/kb/guide/sandboxed-coding-agent-with-harnessagent): Use HarnessAgent to run coding agent harnesses like Claude Code or Codex against untrusted code inside Vercel Sandbox. Reproduce GitHub issues with the agent harness and generate a report for the maintainer.
- [Build a software factory with eve](/kb/guide/eve-software-factory): Foreman, a software factory built on eve. It turns GitHub and Linear work items into reviewed draft pull requests through four agent stations, triaging issues and fixing its own red CI along the way.