Improvements to documentation with regards to remote OAuth issue

.env.example

@@ -52,6 +52,13 @@
 # --- Chutes ---
 #CHUTES_API_KEY_1="YOUR_CHUTES_API_KEY"
 
+# --- Hatz AI ---
+# Hatz uses the Responses API internally. The proxy translates Chat Completions
+# requests to Hatz's /v1/openai/responses endpoint automatically.
+# Authentication uses X-API-Key header (not Bearer token).
+#HATZ_API_KEY_1="YOUR_HATZ_API_KEY"
+#HATZ_API_KEY_2="YOUR_HATZ_API_KEY_2"
+
 # ------------------------------------------------------------------------------
 # | [OAUTH] Provider OAuth 2.0 Credentials                                     |
 # ------------------------------------------------------------------------------

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:**

src/proxy_app/main.py

@@ -703,6 +703,9 @@ async def verify_anthropic_api_key(
     Dependency to verify API key for Anthropic endpoints.
     Accepts either x-api-key header (Anthropic style) or Authorization Bearer (OpenAI style).
     """
+    # If PROXY_API_KEY is not set or empty, skip verification (open access)
+    if not PROXY_API_KEY:
+        return x_api_key or auth
     # Check x-api-key first (Anthropic style)
     if x_api_key and x_api_key == PROXY_API_KEY:
         return x_api_key

src/rotator_library/providers/antigravity_provider.py

@@ -747,16 +747,19 @@ def _clean_claude_schema(schema: Any, for_gemini: bool = False) -> Any:
         "$id",
         "$ref",
         "$defs",
-        "$schema",  # Rejected by 'parameters' key
+        "$schema",
+        "$comment",
+        "$vocabulary",
+        "$dynamicRef",
+        "$dynamicAnchor",
         "definitions",
-        "default",  # Rejected by 'parameters' key
-        "examples",  # Rejected by 'parameters' key
+        "default",  # Rejected by 'parameters' key, sometimes
+        "examples",  # Rejected by 'parameters' key, sometimes
         "title",  # May cause issues in nested objects
     }
 
-    # Validation keywords - only remove at schema-definition level,
-    # NOT when they appear as property names under "properties"
-    # Note: These are common property names that could be used by tools:
+    # Validation keywords to strip ONLY for Claude (Gemini accepts these)
+    # These are common property names that could be used by tools:
     # - "pattern" (glob, grep, regex tools)
     # - "format" (export, date/time tools)
     # - "minimum"/"maximum" (range tools)
@@ -765,27 +768,55 @@ def _clean_claude_schema(schema: Any, for_gemini: bool = False) -> Any:
     # but we now use 'parameters' key which may silently ignore some):
     # Note: $schema, default, examples, title moved to meta_keywords (always stripped)
     validation_keywords_claude_only = {
+        # Array validation - Gemini accepts
         "minItems",
         "maxItems",
-        "uniqueItems",
+        # String validation - Gemini accepts
         "pattern",
         "minLength",
         "maxLength",
+        "format",
+        # Number validation - Gemini accepts
         "minimum",
         "maximum",
+        # Object validation - Gemini accepts
+        "minProperties",
+        "maxProperties",
+        # Composition - Gemini accepts
+        "not",
+        "prefixItems",
+    }
+
+    # Validation keywords to strip for ALL models (Gemini and Claude)
+    validation_keywords_all_models = {
+        # Number validation - Gemini rejects
         "exclusiveMinimum",
         "exclusiveMaximum",
         "multipleOf",
-        "format",
-        "minProperties",
-        "maxProperties",
+        # Array validation - Gemini rejects
+        "uniqueItems",
+        "contains",
+        "minContains",
+        "maxContains",
+        "unevaluatedItems",
+        # Object validation - Gemini rejects
         "propertyNames",
+        "unevaluatedProperties",
+        "dependentRequired",
+        "dependentSchemas",
+        # Content validation - Gemini rejects
         "contentEncoding",
         "contentMediaType",
         "contentSchema",
+        # Meta annotations - Gemini rejects
+        "examples",
         "deprecated",
         "readOnly",
         "writeOnly",
+        # Conditional - Gemini rejects
+        "if",
+        "then",
+        "else",
     }
 
     # Handle 'anyOf', 'oneOf', and 'allOf' for Claude
@@ -891,6 +922,10 @@ def _clean_claude_schema(schema: Any, for_gemini: bool = False) -> Any:
             # For Claude: skip - not supported
             continue
 
+        # Strip keywords unsupported by ALL models (both Gemini and Claude)
+        if key in validation_keywords_all_models:
+            continue
+
         # Special handling for additionalProperties:
         # For Gemini: pass through as-is (Gemini accepts {}, true, false, typed schemas)
         # For Claude: normalize permissive values ({} or true) to true