---
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: /kb/guide/sandbox-private-github-repositories
canonical_url: "https://vercel.com/kb/guide/sandbox-private-github-repositories"
published: 2026-02-09
last_updated: 2026-05-26
authors: Allen Zhou
related:
  - /docs/vercel-sandbox
  - /docs/vercel-sandbox/quickstart
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---
<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [Examples](https://vercel.com/docs/sandbox/working-with-sandbox?from=related) — Task-oriented examples for common Vercel Sandbox operations in TypeScript and Python.
- [Quickstart](https://vercel.com/docs/sandbox/quickstart?from=related) — Learn how to run your first code in a Vercel Sandbox.
- [Sandbox](https://vercel.com/docs/sandbox?from=related) — Vercel Sandbox allows you to run arbitrary code in isolated, ephemeral Linux VMs.
- [Concepts](https://vercel.com/docs/sandbox/concepts?from=related) — Learn how Vercel Sandboxes provide on-demand, isolated compute environments for running untrusted code, testing applicat
- [Run Commands in Vercel Sandbox](https://vercel.com/docs/sandbox/run-commands-in-sandbox?from=related) — Create isolated sandbox environments to run builds, tests, and commands safely.
- [Using Vercel Sandbox to run Claude’s Agent SDK](https://vercel.com/kb/guide/using-vercel-sandbox-claude-agent-sdk?from=related) — Learn how to deploy Claude's Agent SDK in Vercel Sandbox for secure and isolated execution of AI-powered code generation
- [Safely running AI generated code in your Next.js application](https://vercel.com/kb/guide/running-ai-generated-code-sandbox?from=related) — How to execute untrusted, AI‑generated code from a Next.js app using Vercel Sandbox, an isolated, ephemeral environment.
- [How to test a container image in Vercel Sandbox before deploying](https://vercel.com/kb/guide/test-container-image-vercel-sandbox?from=related) — Validate a container image before deploying by booting it as a custom Sandbox image from Vercel Container Registry \(VCR

Full cross-link map for this page: [/kb/guide/sandbox-private-github-repositories.graph.md](/kb/guide/sandbox-private-github-repositories.graph.md)
<!-- /docsgraph:related -->


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
  

* * *