commons-proxy
Advanced tools
Universal AI proxy server with multi-provider support (Google Cloud Code, Anthropic, OpenAI, GitHub Models, GitHub Copilot, ChatGPT Plus/Pro, OpenRouter) - Anthropic-compatible API for Claude Code CLI
A universal AI proxy server exposing an Anthropic-compatible API backed by multiple providers (Google Cloud Code, Anthropic, OpenAI, GitHub Models, GitHub Copilot, ChatGPT Plus/Pro, OpenRouter), enabling you to use Claude, Gemini, GPT, and more with Claude Code CLI.
π v2.1.0 Released: Now supporting Anthropic, OpenAI, GitHub Models, GitHub Copilot, ChatGPT Plus/Pro (Codex), and OpenRouter in addition to Google Cloud Code!
π Quick Links: Installation | Provider Setup | Docker | Contributing
ββββββββββββββββββββ βββββββββββββββββββββββ βββββββββββββββββββββββββββ
β Claude Code ββββββΆβ CommonsProxy ββββββΆβ Multiple Providers: β
β (Anthropic β β (Universal Router)β β β’ Google Cloud Code β
β API format) β β β β β’ Anthropic API β
ββββββββββββββββββββ βββββββββββββββββββββββ β β’ OpenAI API β
β β’ GitHub Models β
β β’ GitHub Copilot β
β β’ ChatGPT Plus/Pro β
β β’ OpenRouter β
βββββββββββββββββββββββββββ
Request Flow:
Key Features:
| Provider | Auth Method | Available Models | Quota Tracking | Status |
|---|---|---|---|---|
| Google Cloud Code | OAuth 2.0 with PKCE | Claude 3.5 Sonnet/Opus, Gemini 2.0 Flash/Pro | β Real-time via API | β Primary |
| Anthropic | API Key | Claude 3.5 Sonnet/Opus/Haiku | β οΈ Manual (console) | β Supported |
| OpenAI | API Key | GPT-4 Turbo, GPT-4, GPT-3.5 Turbo | β οΈ Manual (console) | β Supported |
| GitHub Models | Personal Access Token | GitHub Marketplace models | β οΈ GitHub API limits | β Supported |
| GitHub Copilot | Device Authorization | GPT-4o, Claude Sonnet 4, o1, o3-mini | β οΈ Copilot limits | β Supported |
| ChatGPT Plus/Pro | OAuth (Browser/Device) | GPT-5 Codex, GPT-5.1 Codex | β οΈ Subscription limits | β New |
| OpenRouter | API Key | 100+ models (Claude, GPT, Gemini, Llama, etc.) | β Credit-based | β Supported |
Quota Tracking Legend:
Custom Endpoints: OpenAI provider supports custom API endpoints (Azure OpenAI, self-hosted APIs)
π Setup Guides: See docs/PROVIDERS.md for detailed setup instructions for each provider.
# Run directly with npx (no install needed)
npx commons-proxy@latest start
# Or install globally
npm install -g commons-proxy@latest
commons-proxy start
git clone https://github.com/AryanVBW/CommonsProxy.git
cd CommonsProxy
npm install
npm start
For a guided setup experience, run the included setup script after cloning:
./setup.sh
This script checks prerequisites (Node.js, npm), installs dependencies, configures Claude Code CLI settings, optionally sets up shell environment variables, and starts the proxy server.
# Pull and run from GitHub Container Registry
docker run -d \
--name commons-proxy \
-p 8080:8080 \
-v ~/.config/commons-proxy:/app/data/.config/commons-proxy \
ghcr.io/aryanvbw/commonsproxy:latest
# Or use docker-compose
curl -O https://raw.githubusercontent.com/AryanVBW/CommonsProxy/main/docker-compose.yml
docker-compose up -d
Access WebUI: Open http://localhost:8080 to configure accounts
Environment Variables:
docker run -d \
-p 8080:8080 \
-e PORT=8080 \
-e DEBUG=true \
-e WEBUI_PASSWORD=your-password \
-v ~/.config/commons-proxy:/app/data/.config/commons-proxy \
ghcr.io/aryanvbw/commonsproxy:latest
# If installed via npm
commons-proxy start
# If using npx
npx commons-proxy@latest start
# If cloned locally
npm start
The server runs on http://localhost:8080 by default.
CommonsProxy supports multiple AI providers. Add one or more accounts to get started.
π‘ Tip: You can mix and match providers! Add multiple Google accounts for load balancing, plus Anthropic/OpenAI as fallbacks.
Best for: Claude and Gemini models with real-time quota tracking
WebUI Setup (Recommended):
http://localhost:8080 β Accounts tab β Add AccountCLI Setup:
# Desktop (opens browser)
commons-proxy accounts add --provider=google
# Headless server (manual code input)
commons-proxy accounts add --provider=google --no-browser
Available Models: claude-sonnet-4-5, claude-opus-4-5, gemini-3-flash, gemini-3-pro-low, gemini-3-pro-high
Best for: Direct Claude API access with official rate limits
Prerequisites: Anthropic account at console.anthropic.com, API key with billing enabled
Setup:
commons-proxy accounts add --provider=anthropicAvailable Models: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229
Best for: GPT models and Azure OpenAI integration
Prerequisites: OpenAI account at platform.openai.com, API key with credits
Setup:
commons-proxy accounts add --provider=openaiAvailable Models: gpt-4-turbo-preview, gpt-4, gpt-3.5-turbo
Azure OpenAI: Supports custom endpoints for Azure deployments
Best for: Access to GitHub Marketplace models (beta)
Prerequisites: GitHub account, Personal Access Token with read:packages scope
Setup:
commons-proxy accounts add --provider=githubAvailable Models: GitHub Marketplace models (varies by account/region)
Best for: Using Copilot-accessible models (GPT-4o, Claude Sonnet 4, o1, o3-mini) with an active Copilot subscription
Prerequisites: GitHub account with active Copilot subscription (Individual, Business, or Enterprise)
Setup:
https://github.com/login/device and enter the code showncommons-proxy accounts add --provider=copilotAvailable Models: GPT-4o, Claude Sonnet 4, o1-preview, o3-mini (varies by Copilot plan)
Best for: Using OpenAI Codex models with a ChatGPT Plus or Pro subscription
Prerequisites: Active ChatGPT Plus or Pro subscription at chatgpt.com
Setup:
commons-proxy accounts add --provider=codexAvailable Models: GPT-5 Codex, GPT-5.1 Codex (varies by subscription tier)
Best for: Unified access to 100+ models from multiple providers through a single API key
Prerequisites: OpenRouter account at openrouter.ai, API key with credits
Setup:
commons-proxy accounts add --provider=openrouterAvailable Models: 100+ models including Claude, GPT, Gemini, Llama, Mistral, and more
π Detailed Guides: For step-by-step instructions with screenshots and troubleshooting, see:
docs/PROVIDERS.md - Complete provider setup guides# Health check
curl http://localhost:8080/health
# Check account status and quota limits
curl "http://localhost:8080/account-limits?format=table"
You can configure these settings in two ways:
http://localhost:8080.[!TIP] > Configuration Precedence: System environment variables (set in shell profile like
.zshrc) take precedence over thesettings.jsonfile. If you use the Web Console to manage settings, ensure you haven't manually exported conflicting variables in your terminal.
Create or edit the Claude Code settings file:
macOS: ~/.claude/settings.json
Linux: ~/.claude/settings.json
Windows: %USERPROFILE%\.claude\settings.json
Add this configuration:
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "test",
"ANTHROPIC_BASE_URL": "http://localhost:8080",
"ANTHROPIC_MODEL": "claude-opus-4-5-thinking",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-5-thinking",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5-thinking",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-4-5",
"CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-5-thinking",
"ENABLE_EXPERIMENTAL_MCP_CLI": "true"
}
}
Or to use Gemini models:
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "test",
"ANTHROPIC_BASE_URL": "http://localhost:8080",
"ANTHROPIC_MODEL": "gemini-3-pro-high[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "gemini-3-pro-high[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "gemini-3-flash[1m]",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3-flash[1m]",
"CLAUDE_CODE_SUBAGENT_MODEL": "gemini-3-flash[1m]",
"ENABLE_EXPERIMENTAL_MCP_CLI": "true"
}
}
Add the proxy settings to your shell profile:
macOS / Linux:
echo 'export ANTHROPIC_BASE_URL="http://localhost:8080"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="test"' >> ~/.zshrc
source ~/.zshrc
For Bash users, replace
~/.zshrcwith~/.bashrc
Windows (PowerShell):
Add-Content $PROFILE "`n`$env:ANTHROPIC_BASE_URL = 'http://localhost:8080'"
Add-Content $PROFILE "`$env:ANTHROPIC_AUTH_TOKEN = 'test'"
. $PROFILE
Windows (Command Prompt):
setx ANTHROPIC_BASE_URL "http://localhost:8080"
setx ANTHROPIC_AUTH_TOKEN "test"
Restart your terminal for changes to take effect.
# Make sure the proxy is running first
commons-proxy start
# In another terminal, run Claude Code
claude
Note: If Claude Code asks you to select a login method, add
"hasCompletedOnboarding": trueto~/.claude.json(macOS/Linux) or%USERPROFILE%\.claude.json(Windows), then restart your terminal and try again.
To run both the official Claude Code and CommonsProxy version simultaneously, add this alias:
macOS / Linux:
# Add to ~/.zshrc or ~/.bashrc
alias claude-commons='CLAUDE_CONFIG_DIR=~/.claude-account-commons ANTHROPIC_BASE_URL="http://localhost:8080" ANTHROPIC_AUTH_TOKEN="test" command claude'
Windows (PowerShell):
# Add to $PROFILE
function claude-commons {
$env:CLAUDE_CONFIG_DIR = "$env:USERPROFILE\.claude-account-commons"
$env:ANTHROPIC_BASE_URL = "http://localhost:8080"
$env:ANTHROPIC_AUTH_TOKEN = "test"
claude
}
Then run claude for official API or claude-commons for this proxy.
| Model ID | Description |
|---|---|
claude-sonnet-4-5-thinking | Claude Sonnet 4.5 with extended thinking |
claude-opus-4-5-thinking | Claude Opus 4.5 with extended thinking |
claude-sonnet-4-5 | Claude Sonnet 4.5 without thinking |
| Model ID | Description |
|---|---|
gemini-3-flash | Gemini 3 Flash with thinking |
gemini-3-pro-low | Gemini 3 Pro Low with thinking |
gemini-3-pro-high | Gemini 3 Pro High with thinking |
Gemini models include full thinking support with thoughtSignature handling for multi-turn conversations.
When you add multiple accounts, the proxy intelligently distributes requests across them using configurable selection strategies.
Choose a strategy based on your needs:
| Strategy | Best For | Description |
|---|---|---|
| Hybrid (Default) | Most users | Smart selection combining health score, token bucket rate limiting, quota awareness, and LRU freshness |
| Sticky | Prompt caching | Stays on the same account to maximize cache hits, switches only when rate-limited |
| Round-Robin | Even distribution | Cycles through accounts sequentially for balanced load |
Configure via CLI:
commons-proxy start --strategy=hybrid # Default: smart distribution
commons-proxy start --strategy=sticky # Cache-optimized
commons-proxy start --strategy=round-robin # Load-balanced
Or via WebUI: Settings β Server β Account Selection Strategy
When all accounts are exhausted for a requested model, the proxy can automatically fall back to an alternate model:
commons-proxy start --fallback
# Or: FALLBACK=true commons-proxy start
Fallback mappings preserve thinking capability (thinking models fall back to other thinking models). Fallback is disabled on recursive calls to prevent infinite chains. Configure in the WebUI under Settings β Server.
Check account status, subscription tiers, and quota anytime:
# Web UI: http://localhost:8080/ (Accounts tab - shows tier badges and quota progress)
# CLI Table:
curl "http://localhost:8080/account-limits?format=table"
If you prefer using the terminal for management:
# List all accounts
commons-proxy accounts list
# Verify account health
commons-proxy accounts verify
# Interactive CLI menu
commons-proxy accounts
The proxy includes a built-in, modern web interface for real-time monitoring and configuration. Access the console at: http://localhost:8080 (default port).
~/.claude/settings.json directly from the browser.While most users can use the default settings, you can tune the proxy behavior via the Settings β Server tab in the WebUI or by creating a config.json file.
/v1/* API endpoints with API_KEY env var or apiKey in config.WEBUI_PASSWORD env var or in config.8080 port.maxRetries, retryBaseMs, and retryMaxMs.defaultCooldownMs and maxWaitBeforeErrorMs.persistTokenCache to save OAuth sessions across restarts.maxAccounts (1-100) to limit the number of Google accounts. Default: 10.Refer to config.example.json for a complete list of fields and documentation.
For macOS users who prefer a native experience, there's a companion menu bar app that provides quick access to server controls without touching the terminal. Get it from: commons-proxy-bar
Note: This is a GUI wrapper only. You still need to install and setup the proxy server first using one of the installation methods above.
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Health check |
/account-limits | GET | Account status and quota limits (add ?format=table for ASCII table) |
/v1/messages | POST | Anthropic Messages API |
/v1/models | GET | List available models |
/refresh-token | POST | Force token refresh |
Run the test suite (requires server running):
# Start server in one terminal
npm start
# Run tests in another terminal
npm test
Individual tests:
npm run test:signatures # Thinking signatures
npm run test:multiturn # Multi-turn with tools
npm run test:streaming # Streaming SSE events
npm run test:interleaved # Interleaved thinking
npm run test:images # Image processing
npm run test:caching # Prompt caching
npm run test:strategies # Account selection strategies
npm run test:cache-control # Cache control field stripping
On Windows, the default OAuth callback port (51121) may be reserved by Hyper-V, WSL2, or Docker. If you see:
Error: listen EACCES: permission denied 0.0.0.0:51121
The proxy will automatically try fallback ports (51122-51126). If all ports fail, try these solutions:
Set a custom port outside the reserved range:
# Windows PowerShell
$env:OAUTH_CALLBACK_PORT = "3456"
commons-proxy start
# Windows CMD
set OAUTH_CALLBACK_PORT=3456
commons-proxy start
# Or add to your .env file
OAUTH_CALLBACK_PORT=3456
Run as Administrator:
net stop winnat
net start winnat
See which ports are reserved:
netsh interface ipv4 show excludedportrange protocol=tcp
If 51121 is in a reserved range, use Option 1 with a port outside those ranges.
Reserve the port before Hyper-V claims it (run as Administrator):
netsh int ipv4 add excludedportrange protocol=tcp startport=51121 numberofports=1
Note: The server automatically tries fallback ports (51122-51126) if the primary port fails.
If using single-account mode with Windsurf/Cursor:
Or add accounts via OAuth instead: commons-proxy accounts add
The token might have expired. Try:
curl -X POST http://localhost:8080/refresh-token
Or re-authenticate the account:
commons-proxy accounts
With multiple accounts, the proxy automatically switches to the next available account. With a single account, you'll need to wait for the rate limit to reset.
Re-authenticate the account:
commons-proxy accounts
# Choose "Re-authenticate" for the invalid account
WEBUI_PASSWORD to protect the management dashboard. Password comparison uses crypto.timingSafeEqual() to prevent timing attacks.API_KEY to protect /v1/* API endpoints from unauthorized access.By using this software, you acknowledge and accept the following:
Terms of Service risk: This approach may violate the Terms of Service of AI model providers (Anthropic, Google, etc.). You are solely responsible for ensuring compliance with all applicable terms and policies.
Account risk: Providers may detect this usage pattern and take punitive action, including suspension, permanent ban, or loss of access to paid subscriptions.
No guarantees: Providers may change APIs, authentication, or policies at any time, which can break this method without notice.
Assumption of risk: You assume all legal, financial, and technical risks. The authors and contributors of this project bear no responsibility for any consequences arising from your use.
Use at your own risk. Proceed only if you understand and accept these risks.
Not affiliated with Google or Anthropic. This is an independent open-source project and is not endorsed by, sponsored by, or affiliated with Google LLC or Anthropic PBC.
"Gemini", "Google Cloud", and "Google" are trademarks of Google LLC.
"Claude" and "Anthropic" are trademarks of Anthropic PBC.
Software is provided "as is", without warranty. You are responsible for complying with all applicable Terms of Service and Acceptable Use Policies.
This project uses a local Tailwind CSS build system. CSS is pre-compiled and included in the repository, so you can run the project immediately after cloning.
git clone https://github.com/AryanVBW/CommonsProxy.git
cd CommonsProxy
npm install # Automatically builds CSS via prepare hook
npm start # Start server (no rebuild needed)
If you need to modify styles in public/css/src/input.css:
# Option 1: Build once
npm run build:css
# Option 2: Watch for changes (auto-rebuild)
npm run watch:css
# Option 3: Watch both CSS and server (recommended)
npm run dev:full
File Structure:
public/css/src/input.css - Source CSS with Tailwind @apply directives (edit this)public/css/style.css - Compiled & minified CSS (auto-generated, don't edit)tailwind.config.js - Tailwind configurationpostcss.config.js - PostCSS configurationIf you're only working on backend code and don't need frontend dev tools:
npm install --production # Skip devDependencies (saves ~20MB)
npm start
Note: Pre-compiled CSS is committed to the repository, so you don't need to rebuild unless modifying styles.
See CLAUDE.md for detailed architecture documentation, including:
ErrorHandler.withLoading, AccountActions)copilot.ts and codex.ts plugins.MIT
FAQs
Universal AI proxy server with multi-provider support (Google Cloud Code, Anthropic, OpenAI, GitHub Models, GitHub Copilot, ChatGPT Plus/Pro, OpenRouter) - Anthropic-compatible API for Claude Code CLI
The npm package commons-proxy receives a total of 23 weekly downloads. As such, commons-proxy popularity was classified as not popular.
We found that commons-proxy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Β It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Socket found 37 malicious PyPI wheels that abuse Python startup hooks to launch a Bun-powered credential stealer tied to Mini Shai-Hulud/Miasma.
Security News
RubyGems and Bundler 4.0.13 introduced an opt-in cooldown feature that delays newly published gems during dependency resolution.
Security News
pnpm 11.5 now recognizes npm staged publish approvals in release metadata, preventing those releases from being mistaken for lower-trust package publishes.