GitHub Copilot API Proxy (ghc-api)

A Python Flask application that serves as a proxy server for GitHub Copilot API, providing OpenAI and Anthropic API compatibility with caching and monitoring capabilities.

Features

• OpenAI API Compatibility: /v1/chat/completions endpoint
• Anthropic API Compatibility: /v1/messages endpoint with automatic request/response translation
• Model Listing: /v1/models endpoint listing available models
• Model Name Mapping: Translate model names with exact and prefix-based matching
• Token Management: Automatic GitHub Copilot token refresh
• Vision Support: Handle image inputs and enable vision capabilities
• Memory Caching: Cache all requests and responses (up to 1000 entries)
• Web Dashboard: Real-time statistics and request browser
• Request Details: View full request/response bodies with JSON formatting
• Export/Import: Export and import request history as JSON Lines files
• Optional Request File Logging: Save completed requests to daily JSON Lines files
• Request File Statistics: Build reusable line-level indexes, inspect size/latency/token distributions, and drill into exact historical requests
• Content Filtering: Remove or add content from system prompts and tool results
• Code Agent Manager UI: Install Codex/Claude/Copilot CLI and manage config sync from dashboard
• Code Agent Interaction: Web UI to create and interact with Claude Code, Codex, and Copilot CLI agents via the Agent Client Protocol (ACP)
• Config Sync: Sync Claude Code, Codex, and ghc-api config files with OneDrive
• Safe Backups: Auto backup overwritten config files as *.YYYYMMDD_HHMMSS.bak
• Machine Token Usage Logs: Periodic token usage JSONL per machine with cross-machine overview in dashboard
• Optional User-Token Auth: Opt-in middleware gates LLM endpoints behind self-signup + admin-approved tokens; requests, stats, and token usage are then grouped per user

Maintenance Guides

• Anthropic Messages to Responses compatibility warning runbook

Installation

Install the package using pip:

pip install ghc-api

Or install from source:

pip install .

Usage

Start the server with the ghc-api command:

ghc-api

By default, the server will start on http://localhost:8313.

Command Line Options

• -p PORT or --port PORT: Specify the port to listen on (default: 8313)
• -a ADDRESS or --address ADDRESS: Specify the address to listen on (default: localhost)
• -c or --config: Generate a YAML config file in ~/.ghc-api/config.yaml
• --delete-github-token: Delete the locally saved github_token.txt and exit
• --github-device-login: Run GitHub Device Flow, replace the locally saved token, and exit
• -v or --version: Show version (for example ghc-api 1.0.21)
• --help: Show help message

Configuration

The application looks for a configuration file at ~/.ghc-api/config.yaml. You can generate this file using:

ghc-api --config

The config file contains:

# Server Settings
address: localhost
port: 8313
debug: false

# GitHub Copilot Account Type
# Options: "individual", "business", "enterprise"
account_type: individual

# Version settings (used to build request headers)
vscode_version: "1.93.0"
api_version: "2025-04-01"
copilot_version: "0.26.7"

# Model Name Mappings
model_mappings:
  # Exact match mappings
  exact:
    opus: claude-opus-4.5
    sonnet: claude-sonnet-4.5
    haiku: claude-haiku-4.5
  # Prefix match mappings
  prefix:
    claude-sonnet-4-: claude-sonnet-4
    claude-opus-4.5-: claude-opus-4.5

# Chat completions endpoint overrides
chat_completions_model_support:
  exact: []
  prefix:
    - gpt-
    - mai-code-

# Content Filtering
system_prompt_remove: []    # Strings to remove from system prompts
system_prompt_add: []       # Strings to append to system prompts
tool_result_suffix_remove: [] # Strings to remove from end of tool results

# Optional request persistence
save_request_to_file: false # If true, save completed requests to requests/YYYY-MM-DD.jl

# Optional OneDrive access gate
disable_onedrive_access: true # If true, skip all OneDrive detection/sync/shared reads

# Optional leaked tool-call recovery (direct Anthropic /v1/messages streaming)
enable_tool_call_recovery: false # If true, recover tool calls Copilot leaks as plain text

# Streaming reliability
upstream_read_timeout: 1800   # Read timeout (seconds) for each upstream Copilot request
sse_keepalive_interval: 30    # Send a keepalive ping to the client when a stream is idle
                              # this many seconds (keeps clients like Claude Code from
                              # timing out while the model "thinks"). Set 0 to disable.

Token Management

The application follows this priority for getting the GitHub token:

1. GITHUB_TOKEN environment variable
2. Token file at ~/.ghc-api/github_token.txt
3. Interactive GitHub Device Flow authentication

To discard only the local token file, or explicitly sign in again without starting the server:

ghc-api --delete-github-token
ghc-api --github-device-login

The Code Agent Manager shows the latest Copilot token refresh attempt/result and can start a new Device Flow. The UI displays GitHub's short user code and verification URL; the secret device code and resulting access token remain server-side. If GITHUB_TOKEN is set, deleting the local file does not remove that environment variable, and it will take priority again after restart.

Copilot token refresh failures are appended as structured JSON lines to error.log in the ghc-api config directory. The upstream response body is retained for debugging up to 64 KiB; authentication headers and tokens are not logged.

Config Sync and OneDrive

ghc-api can manage and sync these files:

• Claude Code: ~/.claude/settings.json
• Codex: ~/.codex/config.toml
• ghc-api: ~/.ghc-api/config.yaml (or %APPDATA%/ghc-api/config.yaml on Windows)

OneDrive detection priority:

1. ~/OneDrive - *
2. ~/OneDrive
3. In WSL: /mnt/c/Users/<username>/OneDrive - * then /mnt/c/Users/<username>/OneDrive

To disable all OneDrive-dependent operations, set disable_onedrive_access: true in config.yaml. When enabled, ghc-api skips OneDrive detection, config sync actions, and shared OneDrive hash reads.

Sync target folder:

• .ghc-api/configSync under detected OneDrive root

Machine folder:

• .ghc-api/agents/{hostname}_{os} where os is Win, Linux, or WSL

Hash files:

• .ghc-api/configSync/config.sha1
• .ghc-api/agents/{hostname}_{os}/ghc-api/config.sha1

Hashes are recalculated when local config file timestamp is newer than the hash file. On startup, ghc-api checks synced files and prints config differences to stdout (and UI indicator if different).

Token Usage Logging

Every 5 minutes, ghc-api writes token usage delta (if non-zero) to:

• OneDrive mode: .ghc-api/agents/{hostname}_{os}/token_usage.jl
• Fallback when OneDrive is unavailable: ~/.ghc-api/token_usage.jl

Also flushes pending usage on shutdown (Ctrl+C/termination/normal exit).

Each JSONL line includes:

• timestamp (unix seconds)
• models list with:
  • model
  • request_count
  • input_tokens
  • output_tokens
  • total_tokens

Request File Logging

When save_request_to_file: true, ghc-api appends each completed request to:

• <ghc-api config dir>/requests/YYYY-MM-DD.jl

The saved .jl line format is the same as dashboard export (/api/requests/export) and can be imported by dashboard import (/api/requests/import).

Open /request-stats to select one or more daily files and generate request-size, request-duration, and billing-token distributions overall, by model, or by exact HTTP response code. Scans run asynchronously and write one lightweight JSONL sidecar plus metadata per request file under requests/.request-stats-index/. Each sidecar row stores scalar metrics and the source byte offset/length/hash, never request/response bodies or headers. If a source file is unchanged its sidecar is reused without reopening the source; append-only growth is indexed incrementally, while truncated, replaced, corrupt, or incompatible files are rebuilt safely.

Histogram bars are interactive: selecting a bucket shows the exact indexed requests that contributed to it. Each result opens a stable /request-file-detail link which seeks directly to the original .jl line and verifies its SHA-256 before returning the complete persisted record. These links remain valid while the source file is unchanged; a changed source reports that the index must be rebuilt. Detail rendering is capped at 4 MiB per JSONL line.

The token views follow the fields persisted by ghc-api: input not cached (input_tokens), cache write (cache_creation_input_tokens), cache read (cache_read_input_tokens), output (output_tokens), and their total. Provider compatibility paths use the same existing field mappings as the request log itself. Distributions include every persisted request attempt, including failed attempts; failures commonly record zero usage tokens.

Code Agent Interaction

The Code Agent page (/agent) provides a web interface for interacting with AI coding agents via the Agent Client Protocol (ACP). Supported agents:

Agent	Package	Install
Claude Code	@agentclientprotocol/claude-agent-acp	npm install -g @agentclientprotocol/claude-agent-acp
Codex	codex-acp	Download from GitHub releases
Copilot CLI	@github/copilot	npm install -g @github/copilot

Agent binaries are resolved in order: environment variable override (CLAUDE_ACP_BINARY, CODEX_ACP_BINARY, COPILOT_CLI_BINARY), then PATH lookup, then npm global packages.

Session data is stored in:

• OneDrive mode: .ghc-api/agents/{hostname}_{os}/sessions/
• Fallback: ~/.ghc-api/sessions/ (or %APPDATA%/ghc-api/sessions/ on Windows)

Recent working directories are persisted to workdirs.json in the same location. Sessions from other machines are browsable via the machine selector dropdown when OneDrive is enabled.

User-Token Authentication (Optional)

When you want to share a single ghc-api instance among multiple people without giving everyone unrestricted access to the deployer's Copilot quota, enable token auth:

ghc-api --enable-auth
# or set in ~/.ghc-api/config.yaml:
#   enable_auth: true

Once enabled, LLM endpoints (/v1/chat/completions, /v1/messages, /v1/responses, /v1/models, plus their non-/v1 aliases) require an approved user token. Dashboard and admin endpoints stay open at the Flask layer — they're expected to be gated by a reverse proxy in production (see Production Deployment).

Self-signup flow:

1. User opens http://<host>:8313/signup, fills user_id (letters/digits/_-., max 64 chars) and an optional display name, submits.
2. Server generates a token of the form gha_<43 url-safe chars>, returns it once. Status is pending.
3. Admin opens the dashboard → Code Agent Manager → Users section → clicks Approve next to the new user. (Or curl -X POST http://localhost:8313/api/users/<id>/approve.)
4. The user can now use the token. Revocation and deletion are available from the same panel.

Token presentation (middleware accepts any of these, first match wins):

1. Authorization: Bearer <token> — OpenAI SDK, Claude Code (ANTHROPIC_AUTH_TOKEN), Codex, curl
2. x-api-key: <token> — Anthropic SDK (ANTHROPIC_API_KEY)
3. ?api_key=<token> query parameter — curl one-liners

Client configuration examples (assuming server at localhost:8313 and an approved token gha_abc...xyz):

Claude Code — ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8313",
    "ANTHROPIC_AUTH_TOKEN": "gha_abc...xyz"
  }
}

Note: ANTHROPIC_BASE_URL is without /v1. Prefer ANTHROPIC_AUTH_TOKEN over ANTHROPIC_API_KEY for proxies.

Codex — ~/.codex/config.toml:

model_provider = "ghc-api"
model = "gpt-4o"

[model_providers.ghc-api]
name = "GHC API Proxy"
base_url = "http://localhost:8313/v1"
env_key = "GHC_API_TOKEN"
wire_api = "chat"   # or "responses"

Then export GHC_API_TOKEN=gha_abc...xyz. Note: Codex's base_url includes /v1.

OpenAI Python SDK:

client = OpenAI(base_url="http://localhost:8313/v1", api_key="gha_abc...xyz")

Anthropic Python SDK:

client = anthropic.Anthropic(base_url="http://localhost:8313", api_key="gha_abc...xyz")

curl:

curl http://localhost:8313/v1/chat/completions \
  -H "Authorization: Bearer gha_abc...xyz" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}]}'

Per-user dashboard views: with auth on, the request browser, statistics, and cross-machine token-usage overview all gain a "Filter by user" dropdown. Requests issued before auth was enabled (and any anonymous calls when auth is off) show up under a single anonymous bucket.

Token registry storage:

• If OneDrive is detected and disable_onedrive_access: false: {OneDrive}/.ghc-api/configSync/users.json (shared across machines — register once, use anywhere).
• Otherwise: ~/.ghc-api/users.json (local-only).

The registry file is re-read whenever its mtime changes (checked every 5 seconds), so approval / revocation on one machine propagates to others as soon as OneDrive syncs the file.

API Endpoints

OpenAI Compatible

• POST /v1/chat/completions - Chat completions
• POST /chat/completions - Chat completions (without v1 prefix)
• GET /v1/models - List available models
• GET /models - List available models (without v1 prefix)

Anthropic Compatible

• POST /v1/messages - Messages API (Anthropic format)

Dashboard & Monitoring

• GET / - Web dashboard with statistics
• GET /requests - Request browser page
• GET /request-stats - Multi-file persisted request statistics page
• GET /api/request-stats/files - List daily request files and index state without scanning contents
• POST /api/request-stats/jobs - Start an asynchronous statistics/index job for selected files
• GET /api/request-stats/jobs/<id> - Read job progress and completed statistics
• POST /api/request-stats/jobs/<id>/cancel - Cancel an active statistics job
• GET /api/request-stats/datasets/<id>/requests - Paginate requests contributing to a selected histogram bucket
• GET /request-file-detail - Stable historical request detail page
• GET /api/request-stats/request-detail - Read and hash-verify one indexed JSONL request by file offset
• GET /api/runtime-config - Read in-memory runtime config
• POST /api/runtime-config - Update in-memory runtime config (no file write)
• GET /api/stats - JSON statistics endpoint
• GET /api/requests - Paginated list of requests
• GET /api/requests/search - Full-text search in request/response bodies
• GET /api/requests/export - Export all requests as JSON Lines file
• POST /api/requests/import - Import requests from JSON Lines file
• GET /api/request/<id> - Individual request details
• GET /api/request/<id>/request-body - Request body only
• GET /api/request/<id>/response-body - Response body only
• GET /api/config-manager/status - Config manager status and diff info
• POST /api/config-manager/install-tools - Install Codex/Claude/Copilot CLI
• POST /api/config-manager/sync-to-onedrive - Sync local config to OneDrive
• POST /api/config-manager/sync-from-onedrive - Copy OneDrive config to local machine with backups
• GET /api/config-manager/token-usage?range=all|day|week|month - Cross-machine token usage overview
• GET /api/config-manager/config-hashes - Config hash overview for shared OneDrive and each machine (with create time)

User Authentication

Active only when enable_auth: true. See User-Token Authentication above.

• GET /signup - Self-signup form (public)
• POST /signup - Create a pending user, return token (public)
• GET /api/users-list - User list without tokens, for filter dropdowns (public)
• GET /api/users - Full user list including tokens (admin: gate behind reverse proxy)
• POST /api/users/<user_id>/approve - Mark a pending user as approved (admin)
• POST /api/users/<user_id>/revoke - Revoke an approved user (admin)
• DELETE /api/users/<user_id> - Remove a user from the registry (admin)

Per-user filtering is also available on existing endpoints via the ?user=<user_id> query parameter: /api/stats, /api/requests, /api/requests/search, /api/config-manager/token-usage.

Code Agent (ACP)

• GET /agent - Code agent interaction page
• POST /api/agent/sessions - Create a new agent session
• GET /api/agent/sessions - List sessions (paginated, filterable by machine)
• GET /api/agent/sessions/<id> - Get session detail with message history
• POST /api/agent/sessions/<id>/prompt - Send a prompt (returns SSE stream)
• POST /api/agent/sessions/<id>/cancel - Cancel the current prompt
• DELETE /api/agent/sessions/<id> - Terminate a session
• GET /api/agent/machines - List available machine names
• GET /api/agent/workdirs - List recent working directories

Example Usage

With OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8313/v1",
    api_key="not-needed"  # Token is managed by the proxy
)

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

With Anthropic Python SDK

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:8313",
    api_key="not-needed"  # Token is managed by the proxy
)

message = client.messages.create(
    model="claude-sonnet-4",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
print(message.content[0].text)

With cURL

# Chat completions
curl http://localhost:8313/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# List models
curl http://localhost:8313/v1/models

Dashboard

Access the web dashboard at http://localhost:8313/ to:

• View overall statistics (total requests, data transfer)
• See per-model usage statistics
• See per-endpoint analytics
• Browse recent requests
• View detailed request/response bodies
• Use Request Stats (/request-stats) to multi-select persisted daily files, compare overall/model/response-code distributions, click histogram buckets for matching requests, and open hash-verified historical details
• Use Code Agent Manager to:
  • Install code-agent CLIs
  • Sync config files to/from OneDrive
  • See config mismatch alerts
  • View token usage overview by machine/model with time-range and machine filters
  • View config hash overview by machine and shared OneDrive hash with create times
• Use Code Agent page (/agent) to:
  • Create interactive sessions with Claude Code, Codex, or Copilot CLI
  • Send prompts and receive real-time streaming responses (text, tool calls, thinking)
  • Toggle verbose mode for detailed tool inputs/outputs, stdout/stderr, and token usage
  • Browse sessions across machines via OneDrive
  • Resume viewing past session history

Production deployment

When you expose ghc-api beyond localhost (sharing a single instance with other people, putting it on a VPS, etc.), put a reverse proxy in front to authenticate admin paths. ghc-api intentionally does not authenticate dashboard pages or admin APIs at the Flask layer — that responsibility is delegated to your reverse proxy.

Path classification

Category	Paths	How to gate
Public — LLM API	POST /v1/chat/completions, /chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /responses, GET /v1/models, /models, /v1/models/full/, /models/full/	No basic-auth (clients send Authorization: Bearer <user-token>); ghc-api's own middleware checks the user token when enable_auth=true
Public — signup	GET /signup, POST /signup, GET /api/users-list (token-redacted)	No basic-auth — anyone may request an account
Admin — user mgmt	GET /api/users, POST /api/users/<id>/approve, POST /api/users/<id>/revoke, DELETE /api/users/<id>	basic-auth — GET /api/users returns plaintext tokens
Admin — config & data	POST /api/runtime-config, POST /api/config-manager/install-tools, POST /api/config-manager/sync-to-onedrive, POST /api/config-manager/sync-from-onedrive, POST /api/requests/import	basic-auth — affect global state
Admin — dashboard & inspection	GET /, /requests, /request-stats, /request-file-detail, /code-agent-manager, /chat, /agent, all /api/request-stats/*, GET /api/stats, /api/requests*, /api/request/<id>*, /api/config-manager/*, /api/agent/*	basic-auth — request data and usage aggregates may expose other users' activity

Sample nginx config

Default-deny strategy: protect everything with basic-auth, then explicitly allow the public paths.

server {
    listen 443 ssl http2;
    server_name ghc.example.com;

    # ssl_certificate / ssl_certificate_key go here

    # Default for the whole server: admin basic-auth required.
    auth_basic "ghc-api admin";
    auth_basic_user_file /etc/nginx/ghc-api.htpasswd;

    # ---- Public: LLM API (auth is enforced by ghc-api itself via user tokens) ----
    location /v1/ {
        auth_basic off;
        proxy_pass http://127.0.0.1:8313;
        proxy_buffering off;          # SSE / streaming responses
        proxy_read_timeout 1200s;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    # Aliases without the /v1 prefix
    location ~ ^/(chat/completions|responses|models)(/|$) {
        auth_basic off;
        proxy_pass http://127.0.0.1:8313;
        proxy_buffering off;
        proxy_read_timeout 1200s;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # ---- Public: signup page and token-redacted user list ----
    location = /signup {
        auth_basic off;
        proxy_pass http://127.0.0.1:8313;
    }
    location = /api/users-list {
        auth_basic off;
        proxy_pass http://127.0.0.1:8313;
    }

    # ---- Everything else: admin basic-auth applies ----
    location / {
        proxy_pass http://127.0.0.1:8313;
        proxy_buffering off;
        proxy_read_timeout 1200s;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Create the password file (use bcrypt via -B):

sudo htpasswd -cB /etc/nginx/ghc-api.htpasswd admin
# add more admins later without -c:
sudo htpasswd -B /etc/nginx/ghc-api.htpasswd alice

Critical caveats

• Never apply auth_basic to LLM API paths. Clients like Codex, Claude Code, and the OpenAI SDK send Authorization: Bearer <token>, not HTTP basic. nginx would 401 the request before ghc-api ever sees it.
• Always set proxy_buffering off; and a long proxy_read_timeout for any location that forwards LLM traffic — otherwise streamed responses stall or get truncated.
• The two Authorization schemes don't conflict: basic-auth lives in admin location blocks (Authorization: Basic ...), user tokens live in LLM location blocks (Authorization: Bearer ...). They never coexist on the same request.
• For local-only single-user use without nginx, bind ghc-api to localhost so the admin endpoints aren't reachable from the network: ghc-api --enable-auth -a 127.0.0.1.

Architecture

• Modular Design: Organized into separate modules for maintainability
  • main.py - Entry point and configuration loading
  • app.py - Flask application factory
  • config.py - Configuration constants and model mappings
  • cache.py - Request caching and statistics
  • translator.py - OpenAI/Anthropic format translation
  • streaming.py - Streaming response handling
  • token_manager.py - GitHub token management
  • routes/ - API endpoint handlers (openai, anthropic, dashboard, agent)
  • acp/ - Agent Client Protocol implementation (JSON-RPC 2.0 over subprocess stdio)
• Thread-Safe Caching: Uses threading locks for concurrent access
• Memory-Based Storage: No external database dependencies
• RESTful API Design: Follows REST conventions

License

MIT License