docs: refactor README by moving sections to docs/ folder
Move 11 documentation sections to separate markdown files in docs/: - models.md, load-balancing.md, web-console.md, configuration.md - menubar-app.md, api-endpoints.md, testing.md, troubleshooting.md - safety-notices.md, legal.md, development.md README now contains a Documentation section with links to each doc. Also moved donation link to above Star History section. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Badri Narayanan S
398
README.md
398
README.md
@@ -4,8 +4,6 @@
|
|||||||
[](https://www.npmjs.com/package/antigravity-claude-proxy)
|
[](https://www.npmjs.com/package/antigravity-claude-proxy)
|
||||||
[](https://opensource.org/licenses/MIT)
|
[](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 proxy server that exposes an **Anthropic-compatible API** backed by **Antigravity's Cloud Code**, letting you use Claude and Gemini models with **Claude Code CLI**.
|
A proxy server that exposes an **Anthropic-compatible API** backed by **Antigravity's Cloud Code**, letting you use Claude and Gemini models with **Claude Code CLI**.
|
||||||
|
|
||||||
|
|
||||||
@@ -263,387 +261,19 @@ Then run `claude` for official API or `claude-antigravity` for this proxy.
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Available Models
|
## Documentation
|
||||||
|
|
||||||
### Claude Models
|
- [Available Models](docs/models.md)
|
||||||
|
- [Multi-Account Load Balancing](docs/load-balancing.md)
|
||||||
| Model ID | Description |
|
- [Web Management Console](docs/web-console.md)
|
||||||
| ---------------------------- | ---------------------------------------- |
|
- [Advanced Configuration](docs/configuration.md)
|
||||||
| `claude-sonnet-4-5-thinking` | Claude Sonnet 4.5 with extended thinking |
|
- [macOS Menu Bar App](docs/menubar-app.md)
|
||||||
| `claude-opus-4-5-thinking` | Claude Opus 4.5 with extended thinking |
|
- [API Endpoints](docs/api-endpoints.md)
|
||||||
| `claude-sonnet-4-5` | Claude Sonnet 4.5 without thinking |
|
- [Testing](docs/testing.md)
|
||||||
|
- [Troubleshooting](docs/troubleshooting.md)
|
||||||
### Gemini Models
|
- [Safety, Usage, and Risk Notices](docs/safety-notices.md)
|
||||||
|
- [Legal](docs/legal.md)
|
||||||
| Model ID | Description |
|
- [Development](docs/development.md)
|
||||||
| ------------------- | ------------------------------- |
|
|
||||||
| `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
|
|
||||||
antigravity-claude-proxy start --strategy=hybrid # Default: smart distribution
|
|
||||||
antigravity-claude-proxy start --strategy=sticky # Cache-optimized
|
|
||||||
antigravity-claude-proxy start --strategy=round-robin # Load-balanced
|
|
||||||
```
|
|
||||||
|
|
||||||
**Or via WebUI:** Settings → Server → Account Selection Strategy
|
|
||||||
|
|
||||||
### 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 below configurable quota thresholds are deprioritized; exhausted accounts trigger emergency fallback
|
|
||||||
- **Quota Protection**: Set minimum quota levels globally, per-account, or per-model to switch accounts before quota runs out
|
|
||||||
- **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
|
|
||||||
antigravity-claude-proxy accounts list
|
|
||||||
|
|
||||||
# Verify account health
|
|
||||||
antigravity-claude-proxy accounts verify
|
|
||||||
|
|
||||||
# Interactive CLI menu
|
|
||||||
antigravity-claude-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 and draggable per-account threshold markers.
|
|
||||||
- **Account Management**: Add/remove Google accounts via OAuth, view subscription tiers (Free/Pro/Ultra), quota status, and per-account threshold settings.
|
|
||||||
- **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.
|
|
||||||
- **Quota Protection**: Set global or per-account minimum quota thresholds to proactively switch accounts before quota runs out.
|
|
||||||
- **Advanced Tuning**: Configure retries, timeouts, and debug mode on the fly.
|
|
||||||
- **Multi-language Interface**: Full support for English, Chinese (中文), Indonesian (Bahasa), Portuguese (PT-BR), and Turkish (Türkçe).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
- **Quota Threshold**: Set `globalQuotaThreshold` (0-0.99) to switch accounts before quota drops below a minimum level. Supports per-account and per-model overrides.
|
|
||||||
- **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: [antigravity-claude-proxy-bar](https://github.com/IrvanFza/antigravity-claude-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.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 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).
|
|
||||||
- **Account Selection Strategy**: Choose between Hybrid, Sticky, or Round-Robin load balancing strategies.
|
|
||||||
- **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"
|
|
||||||
antigravity-claude-proxy start
|
|
||||||
|
|
||||||
# Windows CMD
|
|
||||||
set OAUTH_CALLBACK_PORT=3456
|
|
||||||
antigravity-claude-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 Antigravity"
|
|
||||||
|
|
||||||
If using single-account mode with Antigravity:
|
|
||||||
|
|
||||||
1. Make sure Antigravity app is installed and running
|
|
||||||
2. Ensure you're logged in to Antigravity
|
|
||||||
|
|
||||||
Or add accounts via OAuth instead: `antigravity-claude-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
|
|
||||||
antigravity-claude-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
|
|
||||||
antigravity-claude-proxy accounts
|
|
||||||
# Choose "Re-authenticate" for the invalid account
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
- "Antigravity", "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/badri-s2001/antigravity-claude-proxy.git
|
|
||||||
cd antigravity-claude-proxy
|
|
||||||
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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -662,6 +292,8 @@ 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>
|
||||||
|
|
||||||
## Star History
|
## Star History
|
||||||
|
|
||||||
[](https://www.star-history.com/#badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left)
|
[](https://www.star-history.com/#badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left)
|
||||||
|
|||||||
9
docs/api-endpoints.md
Normal file
9
docs/api-endpoints.md
Normal file
@@ -0,0 +1,9 @@
|
|||||||
|
# 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 |
|
||||||
18
docs/configuration.md
Normal file
18
docs/configuration.md
Normal file
@@ -0,0 +1,18 @@
|
|||||||
|
# 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.
|
||||||
|
- **Quota Threshold**: Set `globalQuotaThreshold` (0-0.99) to switch accounts before quota drops below a minimum level. Supports per-account and per-model overrides.
|
||||||
|
- **Endpoint Fallback**: Automatic 403/404 endpoint fallback for API compatibility.
|
||||||
|
|
||||||
|
Refer to `config.example.json` for a complete list of fields and documentation.
|
||||||
54
docs/development.md
Normal file
54
docs/development.md
Normal file
@@ -0,0 +1,54 @@
|
|||||||
|
# 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/badri-s2001/antigravity-claude-proxy.git
|
||||||
|
cd antigravity-claude-proxy
|
||||||
|
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
|
||||||
9
docs/legal.md
Normal file
9
docs/legal.md
Normal file
@@ -0,0 +1,9 @@
|
|||||||
|
# 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.
|
||||||
|
|
||||||
|
- "Antigravity", "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.
|
||||||
59
docs/load-balancing.md
Normal file
59
docs/load-balancing.md
Normal file
@@ -0,0 +1,59 @@
|
|||||||
|
# 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
|
||||||
|
antigravity-claude-proxy start --strategy=hybrid # Default: smart distribution
|
||||||
|
antigravity-claude-proxy start --strategy=sticky # Cache-optimized
|
||||||
|
antigravity-claude-proxy start --strategy=round-robin # Load-balanced
|
||||||
|
```
|
||||||
|
|
||||||
|
**Or via WebUI:** Settings → Server → Account Selection Strategy
|
||||||
|
|
||||||
|
## 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 below configurable quota thresholds are deprioritized; exhausted accounts trigger emergency fallback
|
||||||
|
- **Quota Protection**: Set minimum quota levels globally, per-account, or per-model to switch accounts before quota runs out
|
||||||
|
- **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
|
||||||
|
antigravity-claude-proxy accounts list
|
||||||
|
|
||||||
|
# Verify account health
|
||||||
|
antigravity-claude-proxy accounts verify
|
||||||
|
|
||||||
|
# Interactive CLI menu
|
||||||
|
antigravity-claude-proxy accounts
|
||||||
|
```
|
||||||
17
docs/menubar-app.md
Normal file
17
docs/menubar-app.md
Normal file
@@ -0,0 +1,17 @@
|
|||||||
|
# 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: [antigravity-claude-proxy-bar](https://github.com/IrvanFza/antigravity-claude-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](../README.md#installation) 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).
|
||||||
|
- **Account Selection Strategy**: Choose between Hybrid, Sticky, or Round-Robin load balancing strategies.
|
||||||
|
- **Auto-Start Options**: Launch server on app start and launch app at login.
|
||||||
|
- **Native Experience**: Clean, native SwiftUI interface designed for macOS.
|
||||||
19
docs/models.md
Normal file
19
docs/models.md
Normal file
@@ -0,0 +1,19 @@
|
|||||||
|
# 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.
|
||||||
27
docs/safety-notices.md
Normal file
27
docs/safety-notices.md
Normal file
@@ -0,0 +1,27 @@
|
|||||||
|
# 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.**
|
||||||
24
docs/testing.md
Normal file
24
docs/testing.md
Normal file
@@ -0,0 +1,24 @@
|
|||||||
|
# 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
|
||||||
|
```
|
||||||
95
docs/troubleshooting.md
Normal file
95
docs/troubleshooting.md
Normal file
@@ -0,0 +1,95 @@
|
|||||||
|
# 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"
|
||||||
|
antigravity-claude-proxy start
|
||||||
|
|
||||||
|
# Windows CMD
|
||||||
|
set OAUTH_CALLBACK_PORT=3456
|
||||||
|
antigravity-claude-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 Antigravity"
|
||||||
|
|
||||||
|
If using single-account mode with Antigravity:
|
||||||
|
|
||||||
|
1. Make sure Antigravity app is installed and running
|
||||||
|
2. Ensure you're logged in to Antigravity
|
||||||
|
|
||||||
|
Or add accounts via OAuth instead: `antigravity-claude-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
|
||||||
|
antigravity-claude-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
|
||||||
|
antigravity-claude-proxy accounts
|
||||||
|
# Choose "Re-authenticate" for the invalid account
|
||||||
|
```
|
||||||
20
docs/web-console.md
Normal file
20
docs/web-console.md
Normal file
@@ -0,0 +1,20 @@
|
|||||||
|
# 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 and draggable per-account threshold markers.
|
||||||
|
- **Account Management**: Add/remove Google accounts via OAuth, view subscription tiers (Free/Pro/Ultra), quota status, and per-account threshold settings.
|
||||||
|
- **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.
|
||||||
|
- **Quota Protection**: Set global or per-account minimum quota thresholds to proactively switch accounts before quota runs out.
|
||||||
|
- **Advanced Tuning**: Configure retries, timeouts, and debug mode on the fly.
|
||||||
|
- **Multi-language Interface**: Full support for English, Chinese (中文), Indonesian (Bahasa), Portuguese (PT-BR), and Turkish (Türkçe).
|
||||||
Reference in New Issue
Block a user