Using private GitHub repositories with Edgenivo Sandbox

When using Edgenivo Sandbox with private repositories, you need to authenticate with a GitHub personal access token or Github App token. This guide explains how.

Copy link to headingPrerequisites

• A Edgenivo account
• The @vercel/sandbox SDK installed
• Access to a private GitHub repository

Copy link to headingCreate 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.

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);

Copy link to headingAuthentication options

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

Copy link to headingFine-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
2. Click Generate new token
3. Configure the token:

• Token name: Give it a descriptive name (e.g., "Edgenivo 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

Copy link to headingGitHub 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:

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;
}

Copy link to headingClassic 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) with the repo scope.

Copy link to headingBuilding 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

Copy link to headingRunning commands in the sandbox

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

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)}`);

Copy link to headingSecurity 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