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://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**.
|
||||
|
||||
|
||||
@@ -263,387 +261,19 @@ Then run `claude` for official API or `claude-antigravity` 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
|
||||
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
|
||||
## Documentation
|
||||
|
||||
- [Available Models](docs/models.md)
|
||||
- [Multi-Account Load Balancing](docs/load-balancing.md)
|
||||
- [Web Management Console](docs/web-console.md)
|
||||
- [Advanced Configuration](docs/configuration.md)
|
||||
- [macOS Menu Bar App](docs/menubar-app.md)
|
||||
- [API Endpoints](docs/api-endpoints.md)
|
||||
- [Testing](docs/testing.md)
|
||||
- [Troubleshooting](docs/troubleshooting.md)
|
||||
- [Safety, Usage, and Risk Notices](docs/safety-notices.md)
|
||||
- [Legal](docs/legal.md)
|
||||
- [Development](docs/development.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -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
|
||||
|
||||
[](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