Improvements to documentation with regards to remote OAuth issue

DOCUMENTATION.md

@@ -237,6 +237,48 @@ The manager supports loading credentials from two sources, with a clear priority
 - This is the key to "Stateless Deployment" for platforms like Railway, Render, Heroku
 - Credentials are referenced internally using `env://` URIs (e.g., `env://gemini_cli/1`)
 
+#### 2.6.4. Remote Host Authentication (SSH Port Forwarding)
+
+When the proxy is deployed on a remote host (VPS, cloud server, etc.), OAuth authentication requires special handling because OAuth callbacks are sent to `localhost`, which on the remote server refers to the server itself, not your local machine.
+
+**The Problem:**
+
+- Proxy runs on remote VPS at `your-vps-ip`
+- You attempt to add OAuth credentials using the credential tool on the VPS
+- OAuth provider redirects to `http://localhost:PORT/callback`
+- On the VPS, `localhost` points to the VPS's localhost, not your local browser
+- The callback fails because your browser cannot connect to the VPS's localhost
+
+**The Solution: SSH Port Forwarding**
+
+Create an SSH tunnel to forward OAuth callback ports from the VPS to your local machine:
+
+```bash
+# Single provider examples
+ssh -L 8085:localhost:8085 user@your-vps-ip          # Gemini CLI
+ssh -L 51121:localhost:51121 user@your-vps-ip        # Antigravity
+ssh -L 11451:localhost:11451 user@your-vps-ip        # iFlow
+
+# Multiple providers simultaneously
+ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip
+```
+
+**Workflow:**
+
+1. **Establish SSH tunnel** (keep this connection open)
+2. **Run credential tool on VPS** (in separate SSH session)
+3. **Complete browser-based OAuth** - callbacks are forwarded via tunnel
+4. **Close SSH tunnel** after authentication completes
+
+**Alternative Approach: Local Authentication + Export**
+
+If SSH port forwarding is not feasible:
+1. Complete OAuth flows locally on your machine
+2. Export credentials to environment variables using credential tool's export feature
+3. Deploy `.env` file to remote server
+
+This approach uses the credential tool's export functionality to generate environment variable representations of OAuth credentials, which can then be deployed to stateless environments without requiring SSH tunnels.
+
 **Gemini CLI Environment Variables:**
 
 Single credential (legacy format):

Deployment guide.md

@@ -523,13 +523,13 @@ SSH tunnels forward ports from your local machine to the remote VPS, allowing yo
 From your **local machine**, open a terminal and run:
 
 ```bash
-# Forward all OAuth callback ports at once
-ssh -L 51121:localhost:51121 -L 8085:localhost:8085 -L 11451:localhost:11451 user@your-vps-ip
+# Forward all OAuth callback ports at once (recommended)
+ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip
 
 # Alternative: Forward ports individually as needed
-ssh -L 51121:localhost:51121 user@your-vps-ip  # For Antigravity
 ssh -L 8085:localhost:8085 user@your-vps-ip    # For Gemini CLI
-ssh -L 11451:localhost:11451 user@your-vps-ip  # For iFlow
+ssh -L 51121:localhost:51121 user@your-vps-ip   # For Antigravity
+ssh -L 11451:localhost:11451 user@your-vps-ip    # For iFlow
 ```
 
 **Keep this SSH session open** during the entire authentication process.

README.md

@@ -774,6 +774,76 @@ For platforms without file persistence (Railway, Render, Vercel):
 
 </details>
 
+<details>
+<summary><b>Remote Host Deployment (SSH Port Forwarding)</b></summary>
+
+When the proxy is running on a remote host (VPS, cloud server, etc.), OAuth token authentication requires SSH port forwarding. This is because the OAuth callback URL is sent to `localhost`, which on the remote server points to the server itself, not your local machine.
+
+**The Problem:**
+
+- You run the proxy on a remote VPS
+- You try to add OAuth credentials using the credential tool
+- The OAuth provider redirects to `http://localhost:PORT/callback`
+- On the VPS, `localhost` refers to the VPS, not your local machine
+- The callback fails because your browser can't reach the VPS's localhost
+
+**The Solution: SSH Port Forwarding**
+
+Use SSH to tunnel the OAuth callback ports from the VPS back to your local machine. You only need to do this when adding OAuth credentials.
+
+**Single Provider Examples:**
+
+```bash
+# Gemini CLI (port 8085)
+ssh -L 8085:localhost:8085 user@your-vps-ip
+
+# Antigravity (port 51121)
+ssh -L 51121:localhost:51121 user@your-vps-ip
+
+# iFlow (port 11451)
+ssh -L 11451:localhost:11451 user@your-vps-ip
+```
+
+**Multiple Providers at Once:**
+
+```bash
+# Forward all three OAuth ports simultaneously
+ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip
+```
+
+**Complete Workflow:**
+
+1. **Establish SSH tunnel** (keep this connection open):
+   ```bash
+   ssh -L 8085:localhost:8085 -L 51121:localhost:51121 user@your-vps-ip
+   ```
+
+2. **Run the credential tool on the VPS** (in a separate terminal or SSH session):
+   ```bash
+   ssh user@your-vps-ip
+   cd /path/to/LLM-API-Key-Proxy
+   python -m rotator_library.credential_tool
+   ```
+
+3. **Complete OAuth authentication**:
+   - The credential tool will open a browser window
+   - Because of the SSH tunnel, the callback will be forwarded to your local machine
+   - Complete the authentication flow as normal
+
+4. **Close SSH tunnel** after authentication is complete
+
+**Alternative: Local Authentication + Deploy Credentials**
+
+If you prefer not to use SSH port forwarding:
+
+1. Complete OAuth flows locally on your machine
+2. Export credentials to environment variables using the credential tool
+3. Deploy the `.env` file to your remote server
+
+See the "Stateless Deployment" section above for details on exporting credentials.
+
+</details>
+
 <details>
 <summary><b>OAuth Callback Port Configuration</b></summary>
 
@@ -930,11 +1000,13 @@ For OAuth providers (Antigravity, Gemini CLI, etc.), you must authenticate local
 
 ```bash
 # Forward callback ports through SSH
-ssh -L 51121:localhost:51121 -L 8085:localhost:8085 user@your-vps
+ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip
 
-# Then run credential tool on the VPS
+# Then run credential tool on the VPS in a separate terminal
 ```
 
+This creates a tunnel that forwards OAuth callback ports from the VPS to your local machine, allowing the browser-based authentication to complete successfully.
+
 **Systemd Service:**
 
 ```ini
@@ -953,6 +1025,7 @@ WantedBy=multi-user.target
 ```
 
 See [VPS Deployment](Deployment%20guide.md#appendix-deploying-to-a-custom-vps) for complete guide.
+See the [Remote Host Deployment (SSH Port Forwarding)](#remote-host-deployment-ssh-port-forwarding) section above for detailed OAuth setup instructions.
 
 </details>
 
@@ -967,6 +1040,7 @@ See [VPS Deployment](Deployment%20guide.md#appendix-deploying-to-a-custom-vps) f
 | All keys on cooldown | All keys failed recently; check `logs/detailed_logs/` for upstream errors |
 | Model not found | Verify format is `provider/model_name` (e.g., `gemini/gemini-2.5-flash`) |
 | OAuth callback failed | Ensure callback port (8085, 51121, 11451) isn't blocked by firewall |
+| OAuth callback failed on remote VPS | Use SSH port forwarding: `ssh -L 8085:localhost:8085 -L 51121:localhost:51121 user@your-vps-ip` |
 | Streaming hangs | Increase `TIMEOUT_READ_STREAMING`; check provider status |
 
 **Detailed Logs:**