This project provides a reverse proxy for GitHub Copilot, exposing OpenAI-compatible endpoints for use with tools and clients that expect the OpenAI API. It follows the authentication and token management approach used by OpenCode.

❗ IMPORTANT: Vision/Image capability is not available on all GitHub Copilot accounts!

• Even if your account supports GPT-4o, vision features may not be enabled for your Copilot subscription.
• Some orgs and accounts do not have access to vision/image generation/analysis, or may have different levels of support than OpenAI direct accounts.
• This proxy supports vision for Copilot accounts if your Copilot subscription supports it. If your account does not, you will receive a relevant error from the upstream API.
• For latest details, check your Copilot subscription or contact GitHub support for your organization/account.

• OAuth Device Flow Authentication: Secure authentication with GitHub Copilot using the same flow as OpenCode
• Vision Support: Full support for image/vision requests with base64-encoded images in OpenAI-compatible format
• Advanced Token Management:
  • Proactive token refresh (refreshes at 20% of token lifetime, minimum 5 minutes)
  • Exponential backoff retry logic for failed token refreshes
  • Automatic fallback to full re-authentication when needed
  • Detailed token status monitoring
• Robust Request Handling:
  • Automatic retry with exponential backoff for chat completions (3 attempts)
  • Network error recovery and rate limiting handling
  • 30-second request timeout protection
• OpenAI-Compatible API: Exposes /v1/chat/completions, /v1/responses, and /v1/models endpoints
• Request/Response Transformation: Handles model name mapping and ensures OpenAI compatibility
• Configurable Port: Default port 8081, configurable via CLI or config file
• Health Monitoring: /health endpoint for service monitoring
• Graceful Shutdown: Proper signal handling and graceful server shutdown
• Comprehensive Logging: Request/response logging for debugging and monitoring
• Enhanced CLI Commands: Status monitoring, manual token refresh, and detailed configuration display
• Production-Ready Performance: HTTP connection pooling, circuit breaker, request coalescing, and memory optimization
• Monitoring & Profiling: Built-in pprof endpoints for memory, CPU, and goroutine analysis

Pre-built binaries are available for each release on the Releases page.

Available platforms:

• Linux: AMD64, ARM64
• macOS: AMD64 (Intel), ARM64 (Apple Silicon)
• Windows: AMD64, ARM64

Docker images are automatically built and published to GitHub Container Registry via GitHub Actions:

# Pull the latest image
docker pull ghcr.io/privapps/github-copilot-svcs:latest

# Pull a specific version (example)
docker pull ghcr.io/privapps/github-copilot-svcs:0.0.2

Available architectures:

• linux/amd64
• linux/arm64

Releases are automatically created when code is merged to the main branch:

• Version numbers follow semantic versioning (starting from v0.0.1)
• Cross-platform binaries are built and attached to each release
• Release notes include download links for all supported platforms

This service includes enterprise-grade performance optimizations:

• Connection Pooling: Shared HTTP client with configurable connection limits (100 max idle, 20 per host)
• Configurable Timeouts: Fully customizable timeout settings via config.json for all server operations
• Streaming Support: Read (30s), Write (300s), and Idle (120s) timeouts optimized for AI chat streaming
• Long Response Handling: HTTP client and proxy context timeouts support up to 300s (5 minutes) for extended AI conversations
• Request Limits: 5MB request body size limit to prevent memory exhaustion
• Advanced Transport: Configurable dial timeout (10s), TLS handshake timeout (10s), keep-alive (30s)

• Circuit Breaker: Automatic failure detection and recovery (5 failure threshold, 30s timeout)
• Context Propagation: Request contexts with 25s timeout and proper cancellation
• Request Coalescing: Deduplicates identical concurrent requests to models endpoint
• Exponential Backoff: Enhanced retry logic with circuit breaker integration
• Worker Pool: Concurrent request processing with dedicated worker goroutines (CPU*2 workers)

• Buffer Pooling: sync.Pool for request/response buffer reuse to reduce GC pressure
• Memory Optimization: Streaming support with 32KB buffers for large responses
• Graceful Shutdown: Proper resource cleanup and coordinated shutdown with worker pool termination
• Shared Clients: Centralized HTTP client eliminates resource duplication
• Worker Pool Management: Automatic worker lifecycle management with graceful termination

• Profiling Endpoints: /debug/pprof/* for memory, CPU, and goroutine analysis
• Enhanced Logging: Circuit breaker state, request coalescing, and performance data
• Health Monitoring: Detailed /health endpoint for load balancer integration

If you have make installed, you can build, run, and test the project easily:

make build      # Build the binary
make run        # Start the proxy server
make test       # Run unit tests
make test-all   # Run all tests
make test-coverage # Generate coverage report
make clean      # Remove the binary
make lint       # Run linting
make fmt        # Format code
make vet        # Run go vet
make security   # Run security analysis
make docker-build       # Build Docker image
make docker-run         # Run Docker container

You can control which models are available by specifying allowed_models in your config file (config.json).

Example:

{
  "allowed_models": ["gpt-4o", "claude-3.7-sonnet"]
}

• If set, both CLI and REST /v1/models lists are filtered and show a note.
• Proxy requests to /v1/chat/completions will only allow those models, rejecting others with HTTP 400.
• If omitted or set to null, all models are permitted (default behavior).

You can build binaries for different platforms using the following Makefile targets:

• make build-linux-amd64 Build for Linux amd64
• make build-linux-arm64 Build for Linux arm64
• make build-darwin-amd64 Build for macOS amd64
• make build-darwin-arm64 Build for macOS arm64
• make build-windows-amd64 Build for Windows amd64
• make build-windows-arm64 Build for Windows arm64

The output binaries will be named accordingly (e.g., github-copilot-svcs-windows-arm64.exe).

make build
# or manually:
go build -o github-copilot-svcs

# Copy example config and customize timeout values
cp config.example.json ~/.local/share/github-copilot-svcs/config.json
# Edit the timeouts section as needed

./github-copilot-svcs auth

make run
# or manually:
./github-copilot-svcs run

docker run --rm \
  -p 8081:8081 \
  -v ~/.local/share/github-copilot-svcs:/home/appuser/.local/share/github-copilot-svcs  \
  ghcr.io/privapps/github-copilot-svcs:latest

The status command now provides detailed token information with optional JSON output:

./github-copilot-svcs status
./github-copilot-svcs status --json  # JSON format output

Example output:

Configuration file: ~/.local/share/github-copilot-svcs/config.json
Port: 8081
Authentication: ✓ Authenticated
Token expires: in 29m 53s (1793 seconds)
Status: ✅ Token is healthy
Has GitHub token: true
Refresh interval: 1500 seconds

Status indicators:

• ✅ Token is healthy: Token has plenty of time remaining
• ⚠️ Token will be refreshed soon: Token is approaching refresh threshold
• ❌ Token needs refresh: Token has expired or will expire very soon

Once running, the proxy exposes these OpenAI-compatible endpoints:

POST http://localhost:8081/v1/chat/completions
Content-Type: application/json

{
  "model": "gpt-4.1",
  "messages": [
    {"role": "user", "content": "Hello, world!"}
  ],
  "max_tokens": 100
}

For GPT-5.x models (nano, mini, codex variants):

POST http://localhost:8081/v1/responses
Content-Type: application/json

{
  "model": "gpt-5.6-luna",
  "input": "Hello, world!",
  "max_output_tokens": 100
}

GET http://localhost:8081/v1/models

GET http://localhost:8081/health

GET http://localhost:8081/debug/pprof/          # Overview of available profiles
GET http://localhost:8081/debug/pprof/heap      # Memory heap profile
GET http://localhost:8081/debug/pprof/goroutine # Goroutine profile
GET http://localhost:8081/debug/pprof/profile   # CPU profile (30s sampling)
GET http://localhost:8081/debug/pprof/trace     # Execution trace

The proxy implements proactive token management to minimize authentication interruptions:

• Proactive Refresh: Tokens are refreshed when 20% of their lifetime remains (typically 5-6 minutes before expiration for 25-minute tokens)
• Retry Logic: Failed token refreshes are retried up to 3 times with exponential backoff (2s, 8s, 18s delays)
• Fallback Authentication: If token refresh fails completely, the system falls back to full device flow re-authentication
• Background Monitoring: Token status is continuously monitored during API requests

Chat completion requests are automatically retried to handle transient failures:

• Automatic Retries: Up to 3 attempts for failed requests
• Smart Retry Logic: Only retries on network errors, server errors (5xx), rate limiting (429), and timeouts (408)
• Exponential Backoff: Retry delays of 1s, 4s, 9s to avoid overwhelming the API
• Timeout Protection: 30-second timeout per request attempt

# Manual token refresh if needed
./github-copilot-svcs refresh

# Check current token status
./github-copilot-svcs status

# Re-authenticate if all else fails
./github-copilot-svcs auth

The configuration is stored in ~/.local/share/github-copilot-svcs/config.json:

{
  "port": 8081,
  "github_token": "gho_...",
  "copilot_token": "ghu_...",
  "expires_at": 1720000000,
  "refresh_in": 1500,
  "headers": {
    "user_agent": "GitHubCopilotChat/0.29.1",
    "editor_version": "vscode/1.102.3",
    "editor_plugin_version": "copilot-chat/0.29.1",
    "copilot_integration_id": "vscode-chat",
    "openai_intent": "conversation-edits",
    "x_initiator": "user"
  },
  "timeouts": {
    "http_client": 300,
    "server_read": 30,
    "server_write": 300,
    "server_idle": 120,
    "proxy_context": 300,
    "circuit_breaker": 30,
    "keep_alive": 30,
    "tls_handshake": 10,
    "dial_timeout": 10,
    "idle_conn_timeout": 90
  }
}

• port: Server port (default: 8081)
• github_token: GitHub OAuth token for Copilot access
• copilot_token: GitHub Copilot API token
• expires_at: Unix timestamp when the Copilot token expires
• refresh_in: Seconds until token should be refreshed (typically 1500 = 25 minutes)
• headers: (optional) HTTP headers to use for all Copilot API requests (see below)

The headers section allows you to customize the HTTP headers sent to the Copilot API. All fields are optional; defaults are shown below:

You can override any of these by editing your config.json.

All timeout values are specified in seconds and have sensible defaults:

Streaming Support: The service is optimized for long-running streaming chat completions with timeouts up to 300 seconds (5 minutes) to support extended AI conversations.

Custom Configuration: You can copy config.example.json as a starting point and modify timeout values based on your environment:

cp config.example.json ~/.local/share/github-copilot-svcs/config.json
# Edit the timeouts section as needed

The authentication follows GitHub Copilot's OAuth device flow:

1. Device Authorization: Generates a device code and user code
2. User Authorization: User visits GitHub and enters the user code
3. Token Exchange: Polls for GitHub OAuth token
4. Copilot Token: Exchanges GitHub token for Copilot API token
5. Automatic Refresh: Refreshes Copilot token as needed

The proxy automatically maps common model names to GitHub Copilot models. Each model has an api_type field indicating which endpoint to use:

Note: Use the /v1/models endpoint to see all available models and their api_type field to determine which endpoint to use.

• Tokens are stored securely in the user's home directory with restricted permissions (0700)
• All communication with GitHub Copilot uses HTTPS
• No sensitive data is logged
• Automatic token refresh prevents long-lived token exposure

# Re-authenticate
./github-copilot-svcs auth

# Check current status
./github-copilot-svcs status

# Check if service is running
curl http://localhost:8081/health

# List available models with api_type field
curl http://localhost:8081/v1/models

# Test chat completions
curl -X POST http://localhost:8081/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4.1","messages":[{"role":"user","content":"hi"}]}'

# Test responses API
curl -X POST http://localhost:8081/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-luna","input":"hi","max_output_tokens":20}'

# Use a different port
# Edit ~/.local/share/github-copilot-svcs/config.json
# Or delete config file and restart to select new port

# Chat Completions (for GPT-4.x, Claude, Gemini models)
curl -X POST http://localhost:8081/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [{"role": "user", "content": "Write a hello world in Python"}],
    "max_tokens": 100
  }'

# Responses API (for GPT-5.x nano/mini/codex models)
curl -X POST http://localhost:8081/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "input": "Write a hello world in Python",
    "max_output_tokens": 100
  }'

The proxy fully supports vision capabilities with base64-encoded images in OpenAI-compatible format:

# Example with base64-encoded image
curl -X POST http://localhost:8081/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQ..."}}
      ]
    }],
    "max_tokens": 300
  }'

Vision Features:

• Supports multi-part message content (text + images)
• Accepts base64-encoded images as data URIs
• Supports detail parameter (auto, low, high)
• Compatible with vision-capable models (gpt-4o, claude-haiku-4.5, etc.)
• Backward compatible with text-only requests

Example Script: The repository includes test_vision_proxy.sh that demonstrates vision capabilities:

./test_vision_proxy.sh dog.jpeg "Describe this image in detail"

import openai

# Point OpenAI client to the proxy
client = openai.OpenAI(
    base_url="http://localhost:8081/v1",
    api_key="dummy"  # Not used, but required by client
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello, world!"}]
)
print(response.choices[0].message.content)

from langchain.llms import OpenAI

llm = OpenAI(
    openai_api_base="http://localhost:8081/v1",
    openai_api_key="dummy"  # Not used
)
response = llm("Write a hello world in Python")
print(response)

To use this proxy with Codex CLI, add a model provider configuration to your Codex config file (e.g., ~/.codex/config.toml):

model = "gpt-5.6-terra"
model_provider = "local-ghcp"
model_reasoning_effort = "medium"

[model_providers.local-ghcp]
name = "local-ghcp"
base_url = "http://localhost:8081/v1"
wire_api = "responses"
experimental_bearer_token = "sk-local"
requires_openai_auth = false
supports_websockets = false

This configures Codex to use the proxy's Responses API endpoint (/v1/responses) for GPT-5.x models. The wire_api = "responses" setting ensures Codex uses the correct transport.

git clone <repository>
cd github-copilot-svcs
make build
# or manually:
go mod tidy
go build -o github-copilot-svcs ./cmd/github-copilot-svcs

make test          # Run unit tests
make test-all      # Run all tests (unit + integration)
make test-coverage # Run tests with coverage report
# or manually:
go test ./test/...

The project includes comprehensive test coverage:

• Unit Tests: Testing individual components (auth, config, logger)
• Integration Tests: Testing API endpoints and server functionality
• Coverage Reports: HTML and terminal coverage reports available

Generate coverage reports:

make test-coverage  # Generates coverage.html and shows terminal summary

Current test coverage: ~45% across all packages, with excellent coverage in core components like logging (95%+) and configuration (58%+).

Apache License 2.0 - see LICENSE file for details.

This is free software: you are free to change and redistribute it under the terms of the Apache 2.0 license.

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (use descriptive names)
3. Make your changes (follow Go code style and best practices)
4. Add or update tests as needed
5. Run all tests and ensure coverage is not reduced
6. Document your changes in the README if relevant
7. Submit a pull request with a clear description

• Tokens and secrets are stored securely in the user's home directory with restricted permissions (0700)
• No sensitive data is logged
• All communication with GitHub Copilot uses HTTPS
• Automatic token refresh prevents long-lived token exposure
• Do not commit secrets or sensitive config files; check your .gitignore
• For security issues, please contact the maintainers directly

Q: Authentication fails or times out A: Run ./github-copilot-svcs auth again and check your network connection. Ensure your GitHub account has Copilot access.

Q: Service won't start or port is in use A: Edit your config file to use a different port, or stop the conflicting service.

Q: Token expires too quickly A: Check your system clock and ensure the refresh interval in config is set correctly.

Q: How do I update configuration? A: Edit ~/.local/share/github-copilot-svcs/config.json or use environment variables if supported.

Q: How do I report a bug or request a feature? A: Open an issue on GitHub with details about your environment and the problem.

For issues and questions:

1. Check the troubleshooting and FAQ sections
2. Review the logs for error messages
3. Open an issue with detailed information about your setup and the problem