diff --git a/README.md b/README.md index 0d71f8f..d19d443 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,6 @@ [![npm downloads](https://img.shields.io/npm/dm/antigravity-claude-proxy.svg)](https://www.npmjs.com/package/antigravity-claude-proxy) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -Buy Me A Coffee - 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**. ![Antigravity Claude Proxy Banner](images/banner.png) @@ -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). - -![Antigravity 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 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. - -![AntiGravity Claude Proxy Bar](https://github.com/IrvanFza/antigravity-claude-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). -- **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 --- +Buy Me A Coffee + ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left&cache-control=no-cache)](https://www.star-history.com/#badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left) diff --git a/docs/api-endpoints.md b/docs/api-endpoints.md new file mode 100644 index 0000000..546a393 --- /dev/null +++ b/docs/api-endpoints.md @@ -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 | diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..b556026 --- /dev/null +++ b/docs/configuration.md @@ -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. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..9d60d2f --- /dev/null +++ b/docs/development.md @@ -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 diff --git a/docs/legal.md b/docs/legal.md new file mode 100644 index 0000000..806fb2f --- /dev/null +++ b/docs/legal.md @@ -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. diff --git a/docs/load-balancing.md b/docs/load-balancing.md new file mode 100644 index 0000000..f958022 --- /dev/null +++ b/docs/load-balancing.md @@ -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 +``` diff --git a/docs/menubar-app.md b/docs/menubar-app.md new file mode 100644 index 0000000..e9452d5 --- /dev/null +++ b/docs/menubar-app.md @@ -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. + +![AntiGravity Claude Proxy Bar](https://github.com/IrvanFza/antigravity-claude-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). +- **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. diff --git a/docs/models.md b/docs/models.md new file mode 100644 index 0000000..e81e107 --- /dev/null +++ b/docs/models.md @@ -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. diff --git a/docs/safety-notices.md b/docs/safety-notices.md new file mode 100644 index 0000000..4ebe8b8 --- /dev/null +++ b/docs/safety-notices.md @@ -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.** diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..0b09051 --- /dev/null +++ b/docs/testing.md @@ -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 +``` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..36bc0bc --- /dev/null +++ b/docs/troubleshooting.md @@ -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 +``` diff --git a/docs/web-console.md b/docs/web-console.md new file mode 100644 index 0000000..18af29e --- /dev/null +++ b/docs/web-console.md @@ -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). + +![Antigravity 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 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).