claude-code-sandbox/docs/github-authentication.md

GitHub Authentication

This document explains how to set up GitHub authentication for use within Claude Sandbox containers.

Overview

Claude Sandbox uses GitHub tokens for authentication, providing a secure and simple way to access private repositories and push changes.

Authentication Methods (in order of preference)

1. GitHub CLI Token (Recommended)

The most secure and convenient method:

# One-time setup on host:
gh auth login

# The token is automatically discovered and passed to containers

How it works:

• Claude Sandbox runs gh auth token to get your token
• Token is passed as GITHUB_TOKEN environment variable
• Git is configured to use the token for both HTTPS and SSH URLs
• Works for cloning, pulling, and pushing

Benefits:

• ✅ Cross-platform (macOS, Linux, Windows)
• ✅ Secure (tokens can be scoped)
• ✅ Easy to refresh (gh auth refresh)
• ✅ No manual token management

2. Environment Variables

Set a token in your shell:

# Using GitHub Personal Access Token
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Or using GitHub CLI token
export GH_TOKEN=$(gh auth token)

# Then run
claude-sandbox

Supported variables:

• GITHUB_TOKEN - Standard GitHub token variable
• GH_TOKEN - GitHub CLI token variable

3. Git Configuration

Your .gitconfig is automatically copied to containers, preserving:

• User name and email
• Custom aliases
• Other git settings (excluding credential helpers)

Setup Examples

Quick Setup (GitHub CLI)

# Install GitHub CLI
brew install gh  # macOS
# or
sudo apt install gh  # Ubuntu/Debian

# Authenticate
gh auth login

# Run claude-sandbox (token is auto-detected)
claude-sandbox

Manual Token Setup

1. Create a Personal Access Token:

   • Go to GitHub Settings → Developer settings → Personal access tokens
   • Create a token with repo scope
   • Copy the token

2. Set environment variable:

   export GITHUB_TOKEN=ghp_your_token_here
   claude-sandbox
   

Using in Container

Once authenticated, git is automatically configured to use your token:

# Clone private repos (both HTTPS and SSH URLs work)
git clone https://github.com/username/private-repo.git
git clone git@github.com:username/private-repo.git

# Use GitHub CLI
gh repo create
gh pr create
gh issue list

# Push changes
git push origin main

Configuration File

Add GitHub token to your project's claude-sandbox.config.json:

{
  "environment": {
    "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
  }
}

Warning: Don't commit tokens to version control!

Troubleshooting

Permission Denied

If you get "Permission denied" errors:

1. Check if token is available:

   # In container
   echo $GITHUB_TOKEN
   gh auth status
   

2. Verify git configuration:

   git config --list | grep url
   

Token Not Found

If no token is detected:

• Ensure you're logged in with gh auth login
• Or set GITHUB_TOKEN environment variable
• Check that the token has appropriate scopes

Rate Limiting

If you hit rate limits:

• Ensure you're using an authenticated token
• Check rate limit: gh api rate_limit

Security Best Practices

1. Use Scoped Tokens: Only grant necessary permissions (usually just repo)
2. Rotate Tokens: Regularly refresh tokens
3. Don't Commit Tokens: Use environment variables
4. Use GitHub CLI: It manages token lifecycle automatically

Platform-Specific Notes

macOS

• GitHub CLI token stored in macOS Keychain
• Git credentials may use osxkeychain helper

Linux

• GitHub CLI token in ~/.config/gh/
• Git credentials may use libsecret

Windows (WSL)

• Use WSL for best compatibility
• GitHub CLI works in WSL

Advanced Configuration

Multiple GitHub Accounts

Use different tokens for different organizations:

# For work repos
export GITHUB_TOKEN=ghp_work_token

# For personal repos (in another session)
export GITHUB_TOKEN=ghp_personal_token

Custom Git Configuration

The container automatically configures git to use tokens for all GitHub URLs:

• https://github.com/ URLs use token authentication
• git@github.com: URLs are rewritten to use HTTPS with token

This means you can clone repositories using either format and authentication will work seamlessly.