CommonsProxy

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

How It Works

┌──────────────────┐     ┌─────────────────────┐     ┌─────────────────────────┐
│   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:

Claude Code CLI sends request in Anthropic Messages API format
CommonsProxy routes to appropriate provider based on account configuration
Transforms request to provider-specific format (Google Generative AI, Anthropic, OpenAI, GitHub)
Sends to provider's API using OAuth or API Key authentication
Converts response back to Anthropic format with full streaming and thinking support

Key Features:

🔄 Multi-Provider Support: Use Google, Anthropic, OpenAI, GitHub Models, GitHub Copilot, and OpenRouter accounts
🔐 Flexible Authentication: OAuth 2.0 (Google), Device Auth (Copilot, Codex), or API Keys (others)
⚖️ Intelligent Load Balancing: Hybrid/Sticky/Round-Robin strategies
📊 Real-time Quota Tracking: Dashboard shows usage across all providers
💾 Prompt Caching: Maintains cache continuity with sticky account selection
🎨 Web Management UI: Easy account management and monitoring

🎯 Supported Providers

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:

✅ Real-time via API: CommonsProxy automatically fetches and displays quota in WebUI
⚠️ Manual: Check quota limits in the provider's web console

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.

Prerequisites

Node.js 18 or later
Windsurf/Cursor IDE installed (for single-account mode) OR Google account(s) for multi-account mode

Installation

Option 1: npm (Recommended)

# Run directly with npx (no install needed)
npx commons-proxy@latest start

# Or install globally
npm install -g commons-proxy@latest
commons-proxy start

Option 2: Clone Repository

git clone https://github.com/AryanVBW/CommonsProxy.git
cd CommonsProxy
npm install
npm start

Auto-Configuration Script

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.

Option 3: Docker 🐳 (Recommended for Production)

# 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

Quick Start

1. Start the Proxy Server

# 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.

2. Link Account(s)

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.

🔵 Google Cloud Code (OAuth 2.0)

Best for: Claude and Gemini models with real-time quota tracking

WebUI Setup (Recommended):

Navigate to http://localhost:8080 → Accounts tab → Add Account
Select Google Cloud Code from provider dropdown
Complete OAuth authorization in popup window

CLI 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

🟠 Anthropic (API Key)

Best for: Direct Claude API access with official rate limits

Prerequisites: Anthropic account at console.anthropic.com, API key with billing enabled

Setup:

Get API key: https://console.anthropic.com/settings/keys
In WebUI: Accounts → Add Account → Anthropic → Paste key
Or CLI: commons-proxy accounts add --provider=anthropic

Available Models: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229

🟢 OpenAI (API Key)

Best for: GPT models and Azure OpenAI integration

Prerequisites: OpenAI account at platform.openai.com, API key with credits

Setup:

Get API key: https://platform.openai.com/api-keys
In WebUI: Accounts → Add Account → OpenAI → Paste key
Optional: Enable "Custom Endpoint" for Azure OpenAI
Or CLI: commons-proxy accounts add --provider=openai

Available Models: gpt-4-turbo-preview, gpt-4, gpt-3.5-turbo

Azure OpenAI: Supports custom endpoints for Azure deployments

🟣 GitHub Models (Personal Access Token)

Best for: Access to GitHub Marketplace models (beta)

Prerequisites: GitHub account, Personal Access Token with read:packages scope

Setup:

Create PAT: https://github.com/settings/tokens
In WebUI: Accounts → Add Account → GitHub Models → Paste token
Or CLI: commons-proxy accounts add --provider=github

Available Models: GitHub Marketplace models (varies by account/region)

🟧 GitHub Copilot (Device Authorization)

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:

In WebUI: Accounts → Add Account → GitHub Copilot
Follow the device authorization flow: visit https://github.com/login/device and enter the code shown
Or CLI: commons-proxy accounts add --provider=copilot

Available Models: GPT-4o, Claude Sonnet 4, o1-preview, o3-mini (varies by Copilot plan)

🟩 ChatGPT Plus/Pro - Codex (OAuth)

Best for: Using OpenAI Codex models with a ChatGPT Plus or Pro subscription

Prerequisites: Active ChatGPT Plus or Pro subscription at chatgpt.com

Setup:

In WebUI: Accounts → Add Account → ChatGPT Plus/Pro (Codex)
Complete OAuth via browser popup (PKCE flow) or device authorization
Or CLI: commons-proxy accounts add --provider=codex

Available Models: GPT-5 Codex, GPT-5.1 Codex (varies by subscription tier)

🟣 OpenRouter (API Key)

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:

Get API key: https://openrouter.ai/keys
In WebUI: Accounts → Add Account → OpenRouter → Paste key
Or CLI: commons-proxy accounts add --provider=openrouter

Available 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
CONTRIBUTING.md - Adding new providers

3. Verify It's Working

# Health check
curl http://localhost:8080/health

# Check account status and quota limits
curl "http://localhost:8080/account-limits?format=table"

Using with Claude Code CLI

Configure Claude Code

You can configure these settings in two ways:

Via Web Console (Recommended)

Open the WebUI at http://localhost:8080.
Go to Settings → Claude CLI.
Select your preferred models and click Apply to Claude CLI.

[!TIP] > Configuration Precedence: System environment variables (set in shell profile like .zshrc) take precedence over the settings.json file. If you use the Web Console to manage settings, ensure you haven't manually exported conflicting variables in your terminal.

Manual Configuration

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

Load Environment Variables

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 ~/.zshrc with ~/.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.

Run Claude Code

# 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": true to ~/.claude.json (macOS/Linux) or %USERPROFILE%\.claude.json (Windows), then restart your terminal and try again.

Multiple Claude Code Instances (Optional)

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.

Available Models

Claude Models

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

Gemini Models

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.

Multi-Account Load Balancing

When you add multiple accounts, the proxy intelligently distributes requests across them using configurable selection strategies.

Account 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

Model Fallback

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.

How It Works

Health Score Tracking: Accounts earn points for successful requests and lose points for failures/rate-limits
Token Bucket Rate Limiting: Client-side throttling with regenerating tokens (50 max, 6/minute)
Quota Awareness: Accounts with critical quota (<5%) are deprioritized; exhausted accounts trigger emergency fallback
Emergency Fallback: When all accounts appear exhausted, bypasses checks with throttle delays (250-500ms)
Automatic Cooldown: Rate-limited accounts recover automatically after reset time expires
Invalid Account Detection: Accounts needing re-authentication are marked and skipped
Prompt Caching Support: Session IDs derived from conversation enable cache hits across turns

Monitoring

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"

CLI Management Reference

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

Web Management Console

The proxy includes a built-in, modern web interface for real-time monitoring and configuration. Access the console at: http://localhost:8080 (default port).

Key Features

Real-time Dashboard: Monitor request volume, active accounts, model health, and subscription tier distribution.
Visual Model Quota: Track per-model usage and next reset times with color-coded progress indicators.
Account Management: Add/remove Google accounts via OAuth, view subscription tiers (Free/Pro/Ultra) and quota status at a glance.
Manual OAuth Mode: Add accounts on headless servers by copying the OAuth URL and pasting the authorization code.
Claude CLI Configuration: Edit your ~/.claude/settings.json directly from the browser.
Persistent History: Tracks request volume by model family for 30 days, persisting across server restarts.
Time Range Filtering: Analyze usage trends over 1H, 6H, 24H, 7D, or All Time periods.
Smart Analysis: Auto-select top 5 most used models or toggle between Family/Model views.
Live Logs: Stream server logs with level-based filtering and search.
Advanced Tuning: Configure retries, timeouts, and debug mode on the fly.
Multi-language Interface: Full support for English, Chinese (中文), Indonesian (Bahasa), and Portuguese (PT-BR).

Advanced Configuration

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.

Configurable Options

API Key Authentication: Protect /v1/* API endpoints with API_KEY env var or apiKey in config.
WebUI Password: Secure your dashboard with WEBUI_PASSWORD env var or in config.
Custom Port: Change the default 8080 port.
Retry Logic: Configure maxRetries, retryBaseMs, and retryMaxMs.
Rate Limit Handling: Comprehensive rate limit detection from headers and error messages with intelligent retry-after parsing.
Load Balancing: Adjust defaultCooldownMs and maxWaitBeforeErrorMs.
Persistence: Enable persistTokenCache to save OAuth sessions across restarts.
Max Accounts: Set maxAccounts (1-100) to limit the number of Google accounts. Default: 10.
Endpoint Fallback: Automatic 403/404 endpoint fallback for API compatibility.

Refer to config.example.json for a complete list of fields and documentation.

macOS Menu Bar App

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.

Key Features

Server Control: Start/stop the proxy server with a single click or ⌘S shortcut.
Status Indicator: Menu bar icon shows server running state at a glance.
WebUI Access: Open the web management console directly from the menu.
Port Configuration: Customize the proxy server port (default: 8080).
Auto-Start Options: Launch server on app start and launch app at login.
Native Experience: Clean, native SwiftUI interface designed for macOS.

API Endpoints

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

Testing

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

Troubleshooting

Windows: OAuth Port Error (EACCES)

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:

Option 1: Use a Custom Port (Recommended)

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

Option 2: Reset Windows NAT

Run as Administrator:

net stop winnat
net start winnat

Option 3: Check Reserved Ports

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.

Option 4: Permanently Exclude Port (Admin)

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.

"Could not extract token from Cloud Code IDE"

If using single-account mode with Windsurf/Cursor:

Make sure the IDE is installed and running
Ensure you're logged in with your Google account

Or add accounts via OAuth instead: commons-proxy accounts add

401 Authentication Errors

The token might have expired. Try:

curl -X POST http://localhost:8080/refresh-token

Or re-authenticate the account:

commons-proxy accounts

Rate Limiting (429)

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.

Account Shows as "Invalid"

Re-authenticate the account:

commons-proxy accounts
# Choose "Re-authenticate" for the invalid account

Security

WebUI Password: Set WEBUI_PASSWORD to protect the management dashboard. Password comparison uses crypto.timingSafeEqual() to prevent timing attacks.
API Key: Set API_KEY to protect /v1/* API endpoints from unauthorized access.
Bounded Caches: Internal signature caches are bounded (max 10,000 entries) with LRU eviction to prevent memory exhaustion.
Schema Depth Limits: JSON schema sanitization enforces a depth limit of 50 to prevent stack overflow from deeply nested or recursive schemas.
Config Redaction: Sensitive values (tokens, API keys, passwords) are redacted in WebUI API responses.

Safety, Usage, and Risk Notices

Intended Use

Personal / internal development only
Respect internal quotas and data handling policies
Not for production services or bypassing intended limits

Not Suitable For

Production application traffic
High-volume automated extraction
Any use that violates Acceptable Use Policies

Warning (Assumption of Risk)

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.

Legal

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.

Development

For Developers & Contributors

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.

Quick Start

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)

Frontend Development

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 configuration
postcss.config.js - PostCSS configuration

Backend-Only Development

If 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.

Project Structure

See CLAUDE.md for detailed architecture documentation, including:

Request flow and module organization
Frontend architecture (Alpine.js + Tailwind)
Service layer patterns (ErrorHandler.withLoading, AccountActions)
Dashboard module documentation

Credits

opencode — Authentication flows for GitHub Copilot (device auth) and ChatGPT Plus/Pro (Codex OAuth) are inspired by opencode's plugin architecture. Copilot client ID, header handling, and Codex PKCE/device auth flows adapted from opencode's copilot.ts and codex.ts plugins.
opencode-antigravity-auth — CommonsProxy OAuth plugin for OpenCode
claude-code-proxy — Anthropic API proxy using LiteLLM

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 270 Commits
.github		.github
bin		bin
docs		docs
opencode		opencode
public		public
src		src
tests		tests
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
config.example.json		config.example.json
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
setup.sh		setup.sh
tailwind.config.js		tailwind.config.js
test-imports.mjs		test-imports.mjs

License

AryanVBW/CommonsProxy

Folders and files

Latest commit

History

Repository files navigation

CommonsProxy

How It Works

🎯 Supported Providers

Prerequisites

Installation

Option 1: npm (Recommended)

Option 2: Clone Repository

Auto-Configuration Script

Option 3: Docker 🐳 (Recommended for Production)

Quick Start

1. Start the Proxy Server

2. Link Account(s)

🔵 Google Cloud Code (OAuth 2.0)

🟠 Anthropic (API Key)

🟢 OpenAI (API Key)

🟣 GitHub Models (Personal Access Token)

🟧 GitHub Copilot (Device Authorization)

🟩 ChatGPT Plus/Pro - Codex (OAuth)

🟣 OpenRouter (API Key)

3. Verify It's Working

Using with Claude Code CLI

Configure Claude Code

Via Web Console (Recommended)

Manual Configuration

Load Environment Variables

Run Claude Code

Multiple Claude Code Instances (Optional)

Available Models

Claude Models

Gemini Models

Multi-Account Load Balancing

Account Selection Strategies

Model Fallback

How It Works

Monitoring

CLI Management Reference

Web Management Console

Key Features

Advanced Configuration

Configurable Options

macOS Menu Bar App

Key Features

API Endpoints

Testing

Troubleshooting

Windows: OAuth Port Error (EACCES)

Option 1: Use a Custom Port (Recommended)

Option 2: Reset Windows NAT

Option 3: Check Reserved Ports

Option 4: Permanently Exclude Port (Admin)

"Could not extract token from Cloud Code IDE"

401 Authentication Errors

Rate Limiting (429)

Account Shows as "Invalid"

Security

Safety, Usage, and Risk Notices

Intended Use

Not Suitable For

Warning (Assumption of Risk)

Legal

Development

For Developers & Contributors

Quick Start

Frontend Development

Backend-Only Development

Project Structure

Credits

License

Star History

About

Resources

License

Code of conduct

Contributing

Packages