# CommonsProxy

[![npm version](https://img.shields.io/npm/v/commons-proxy.svg)](https://www.npmjs.com/package/commons-proxy)
[![npm downloads](https://img.shields.io/npm/dm/commons-proxy.svg)](https://www.npmjs.com/package/commons-proxy)
[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://ghcr.io/aryanvbw/commonsproxy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<a href="https://buymeacoffee.com/badrinarayanans" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50"></a>

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](#installation) | [Provider Setup](docs/PROVIDERS.md) | [Docker](#option-3-docker-recommended-for-production) | [Contributing](CONTRIBUTING.md)

## 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**:
1. Claude Code CLI sends request in **Anthropic Messages API format**
2. CommonsProxy routes to appropriate provider based on account configuration
3. Transforms request to **provider-specific format** (Google Generative AI, Anthropic, OpenAI, GitHub)
4. Sends to provider's API using OAuth or API Key authentication
5. 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`](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)

```bash
# 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

```bash
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:

```bash
./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)

```bash
# 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**:
```bash
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

```bash
# 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):
1. Navigate to `http://localhost:8080` → **Accounts** tab → **Add Account**
2. Select **Google Cloud Code** from provider dropdown
3. Complete OAuth authorization in popup window

**CLI Setup**:
```bash
# 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](https://console.anthropic.com), API key with billing enabled

**Setup**:
1. Get API key: https://console.anthropic.com/settings/keys
2. In WebUI: **Accounts** → **Add Account** → **Anthropic** → Paste key
3. 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](https://platform.openai.com), API key with credits

**Setup**:
1. Get API key: https://platform.openai.com/api-keys
2. In WebUI: **Accounts** → **Add Account** → **OpenAI** → Paste key
3. Optional: Enable "Custom Endpoint" for Azure OpenAI
4. 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**:
1. Create PAT: https://github.com/settings/tokens
2. In WebUI: **Accounts** → **Add Account** → **GitHub Models** → Paste token
3. 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**:
1. In WebUI: **Accounts** → **Add Account** → **GitHub Copilot**
2. Follow the device authorization flow: visit `https://github.com/login/device` and enter the code shown
3. 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](https://chatgpt.com)

**Setup**:
1. In WebUI: **Accounts** → **Add Account** → **ChatGPT Plus/Pro (Codex)**
2. Complete OAuth via browser popup (PKCE flow) or device authorization
3. 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](https://openrouter.ai), API key with credits

**Setup**:
1. Get API key: https://openrouter.ai/keys
2. In WebUI: **Accounts** → **Add Account** → **OpenRouter** → Paste key
3. 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`](docs/PROVIDERS.md) - Complete provider setup guides
- [CONTRIBUTING.md](CONTRIBUTING.md) - Adding new providers

### 3. Verify It's Working

```bash
# 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)**

1. Open the WebUI at `http://localhost:8080`.
2. Go to **Settings** → **Claude CLI**.
3. 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:

```json
{
  "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:

```json
{
  "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:**

```bash
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):**

```powershell
Add-Content $PROFILE "`n`$env:ANTHROPIC_BASE_URL = 'http://localhost:8080'"
Add-Content $PROFILE "`$env:ANTHROPIC_AUTH_TOKEN = 'test'"
. $PROFILE
```

**Windows (Command Prompt):**

```cmd
setx ANTHROPIC_BASE_URL "http://localhost:8080"
setx ANTHROPIC_AUTH_TOKEN "test"
```

Restart your terminal for changes to take effect.

### Run Claude Code

```bash
# 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:**

```bash
# 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):**

```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:**

```bash
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:

```bash
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:

```bash
# 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:

```bash
# 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).

![CommonsProxy Console](images/webui-dashboard.png)

### 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](https://github.com/IrvanFza/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](#installation) above.

![AntiGravity Claude Proxy Bar](https://github.com/IrvanFza/commons-proxy-bar/blob/main/images/application.png?raw=true)

### 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):

```bash
# Start server in one terminal
npm start

# Run tests in another terminal
npm test
```

Individual tests:

```bash
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:

```bash
# 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:

```powershell
net stop winnat
net start winnat
```

#### Option 3: Check Reserved Ports

See which ports are reserved:

```powershell
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):

```powershell
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:

1. Make sure the IDE is installed and running
2. 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:

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

Or re-authenticate the account:

```bash
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:

```bash
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

```bash
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`:

```bash
# 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:

```bash
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](./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](https://github.com/nichochar/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](https://github.com/NoeFabris/opencode-antigravity-auth)** — CommonsProxy OAuth plugin for OpenCode
- **[claude-code-proxy](https://github.com/1rgs/claude-code-proxy)** — Anthropic API proxy using LiteLLM

---

## License

MIT

---

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=badrisnarayanan/commons-proxy&type=date&legend=top-left&cache-control=no-cache)](https://www.star-history.com/#badrisnarayanan/commons-proxy&type=date&legend=top-left)