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
2026-02-01 21:00:53 +05:30
parent b72aa0e056
commit 2ea9f4ba8e
12 changed files with 366 additions and 383 deletions

95
docs/troubleshooting.md Normal file
View 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
```