Advanced Configuration

Customize Antigravity Claude Proxy’s behavior through environment variables, configuration files, or the Web Console.

Configuration Priority

Settings are applied in the following order (highest to lowest priority):

Environment variables (e.g., PORT=3000)
Config file (~/.config/antigravity-proxy/config.json)
Default values (built-in defaults)

Most users can configure everything through the Web Console at http://localhost:8080 without editing files directly.

Environment Variables

Server Configuration

PORT

number

default:"8080"

HTTP server port. The proxy listens on this port for API requests.

PORT=3000 npm start

HOST

string

default:"0.0.0.0"

Bind address. Use 127.0.0.1 to restrict to localhost only.

HOST=127.0.0.1 npm start

Security

API_KEY

string

default:""

Protect /v1/* API endpoints with a bearer token. When set, clients must include Authorization: Bearer YOUR_API_KEY.

API_KEY=your-secret-key npm start

Keep this value secret. Do not commit it to version control.

WEBUI_PASSWORD

string

default:""

Password-protect the Web Console. Users will be prompted to enter this password when accessing the dashboard.

WEBUI_PASSWORD=admin123 npm start

Proxy & Network

HTTP_PROXY

string

default:""

Route outbound API requests through an HTTP proxy. Useful for corporate firewalls or debugging.

# Route through local proxy
HTTP_PROXY=http://127.0.0.1:8888 npm start

# Corporate proxy with auth
HTTP_PROXY=http://user:[email protected]:3128 npm start

HTTPS_PROXY

string

default:""

Same as HTTP_PROXY but for HTTPS requests. Both variables are supported (case-insensitive).

Developer Mode

DEV_MODE

boolean

default:"false"

Enable developer mode with debug logging and advanced features.

DEV_MODE=true npm start

When enabled:

Debug logs are printed to console
/api/strategy/health endpoint is accessible
Dev tools panel is visible in WebUI
Screenshot mode and placeholder data are available

DEBUG

boolean

default:"false"

Legacy alias for DEV_MODE. Setting DEBUG=true automatically enables developer mode.

DEBUG=true npm start

Model Fallback

FALLBACK

boolean

default:"false"

Enable automatic model fallback when quota is exhausted. See Fallback Strategy for details.

FALLBACK=true npm start
# Or use CLI flag
npm start -- --fallback

systemd / Service Deployments

CLAUDE_CONFIG_PATH

string

default:"~/.claude"

Path to the .claude directory containing settings.json. Required when running as a systemd service.Problem: When running as a systemd service, os.homedir() returns the service user’s home (e.g., /root), not the real user’s home.Solution: Set this variable to the real user’s .claude directory.

CLAUDE_CONFIG_PATH=/home/username/.claude npm start

Example systemd service file:

[Service]
User=myuser
Environment="CLAUDE_CONFIG_PATH=/home/myuser/.claude"
ExecStart=/usr/bin/npm start

OAuth Callback Port

OAUTH_CALLBACK_PORT

number

default:"51121"

Port for OAuth callback server during account authentication. Windows users may need to change this if the default port is reserved by Hyper-V/WSL2.

OAUTH_CALLBACK_PORT=51122 npm run accounts:add

Fallback ports: 51122, 51123, 51124, 51125, 51126

Config File Structure

The config file is located at ~/.config/antigravity-proxy/config.json. It is created automatically on first run.

Example config.json

{
  "apiKey": "",
  "webuiPassword": "",
  "debug": false,
  "devMode": false,
  "logLevel": "info",
  "maxRetries": 5,
  "retryBaseMs": 1000,
  "retryMaxMs": 30000,
  "defaultCooldownMs": 10000,
  "maxWaitBeforeErrorMs": 120000,
  "maxAccounts": 10,
  "globalQuotaThreshold": 0,
  "requestThrottlingEnabled": false,
  "requestDelayMs": 200,
  "accountSelection": {
    "strategy": "hybrid",
    "healthScore": {
      "initial": 70,
      "successReward": 1,
      "rateLimitPenalty": -10,
      "failurePenalty": -20,
      "recoveryPerHour": 10,
      "minUsable": 50,
      "maxScore": 100
    },
    "tokenBucket": {
      "maxTokens": 50,
      "tokensPerMinute": 6,
      "initialTokens": 50
    },
    "quota": {
      "lowThreshold": 0.10,
      "criticalThreshold": 0.05,
      "staleMs": 300000
    },
    "weights": {
      "health": 2,
      "tokens": 5,
      "quota": 3,
      "lru": 0.1
    }
  }
}

Retry & Rate Limiting

maxRetries

number

default:"5"

Maximum number of retry attempts for failed requests.

retryBaseMs

number

default:"1000"

Base delay in milliseconds for exponential backoff.

retryMaxMs

number

default:"30000"

Maximum retry delay in milliseconds (30 seconds).

defaultCooldownMs

number

default:"10000"

Default cooldown period after rate limit errors (10 seconds).

maxWaitBeforeErrorMs

number

default:"120000"

Maximum time to wait before giving up and returning an error (2 minutes).

rateLimitDedupWindowMs

number

default:"2000"

Deduplication window to prevent concurrent retry storms (2 seconds).

maxConsecutiveFailures

number

default:"3"

Number of consecutive failures before applying extended cooldown.

extendedCooldownMs

number

default:"60000"

Extended cooldown period after repeated failures (1 minute).

switchAccountDelayMs

number

default:"5000"

Delay before switching accounts after a rate limit (5 seconds).

Capacity & Backoff

maxCapacityRetries

number

default:"5"

Maximum retries for model capacity exhaustion errors.

capacityBackoffTiersMs

array

default:"[5000, 10000, 20000, 30000, 60000]"

Progressive backoff tiers for capacity exhaustion (in milliseconds).

"capacityBackoffTiersMs": [5000, 10000, 20000, 30000, 60000]

Account Management

maxAccounts

number

default:"10"

Maximum number of Google accounts allowed (1-100). Configurable via WebUI.

globalQuotaThreshold

number

default:"0"

Global minimum quota fraction before switching accounts.

0 = Disabled (use quota until exhausted)
0.01 to 0.99 = Switch when quota drops below this fraction
Example: 0.10 = Switch when quota falls below 10%

This can be overridden per-account and per-model in the Web Console.

requestThrottlingEnabled

boolean

default:"false"

Enable delay before each Google API request (opt-in). Helps prevent rate limits in high-concurrency scenarios.

requestDelayMs

number

default:"200"

Delay in milliseconds when request throttling is enabled (100-5000ms).

Account Selection Strategy

The accountSelection object configures the load balancing strategy.

accountSelection.strategy

string

default:"hybrid"

Account selection algorithm:

sticky: Cache-optimized (stays on same account)
round-robin: Load-balanced (rotates every request)
hybrid: Smart distribution (default)

npm start -- --strategy=sticky

Hybrid Strategy Tuning

These settings only apply when strategy is set to hybrid.

accountSelection.healthScore

object

Health scoring configuration:

initial (70): Starting score for new accounts
successReward (1): Points added on successful request
rateLimitPenalty (-10): Points subtracted on rate limit
failurePenalty (-20): Points subtracted on other failures
recoveryPerHour (10): Passive recovery rate
minUsable (50): Minimum score to be selected
maxScore (100): Maximum score cap

accountSelection.tokenBucket

object

Client-side rate limiting via token bucket:

maxTokens (50): Maximum token capacity
tokensPerMinute (6): Regeneration rate
initialTokens (50): Starting tokens for new accounts

accountSelection.quota

object

Quota awareness thresholds:

lowThreshold (0.10): Reduce score when quota falls below 10%
criticalThreshold (0.05): Exclude from selection below 5%
staleMs (300000): Max age of quota data to trust (5 minutes)

accountSelection.weights

object

Component weights for score calculation:

health (2): Weight for health score component
tokens (5): Weight for token bucket component
quota (3): Weight for quota awareness component
lru (0.1): Weight for LRU freshness component

Scoring formula:

score = (Health × 2) + ((Tokens / MaxTokens × 100) × 5) + (Quota × 3) + (LRU × 0.1)

Quota Threshold Configuration

Quota thresholds protect accounts from complete exhaustion by switching to another account when quota drops below a configurable level.

Three-Tier Resolution

Thresholds are checked in priority order:

Per-model (account.modelQuotaThresholds[modelId])
Per-account (account.quotaThreshold)
Global (config.globalQuotaThreshold)

{
  "globalQuotaThreshold": 0.10  // 10% minimum for all accounts/models
}

Configuring via WebUI

Global threshold

Navigate to Settings → Server and adjust the Global Quota Threshold slider (0-99%).

Per-account threshold

Go to Accounts
Click the settings icon next to an account
Adjust the Account Quota Threshold slider

Per-model threshold

Go to Models
Drag the colored markers on quota bars to set per-account thresholds for each model
Markers are color-coded by account

Server Presets

The proxy includes built-in presets optimized for different scenarios. Access them via Settings → Server in the WebUI.

Default (3-5 Accounts)

Balanced settings for most users:

Strategy: Hybrid
Max retries: 5
Max wait: 2 minutes
Account selection: Balanced weights

Many Accounts (10+)

Optimized for high account counts:

Strategy: Hybrid
Max retries: 3 (faster failures)
Max wait: 1 minute
Account selection: Prioritizes health over LRU

Conservative

Maximum reliability with longer waits:

Strategy: Sticky (best for caching)
Max retries: 8
Max wait: 4 minutes
Account selection: Gentle penalties, slow recovery

Editing the Config File

You can edit the config file manually or through the WebUI.

WebUI (Recommended)
Manual Editing

Open http://localhost:8080
Navigate to Settings → Server
Adjust settings using sliders and dropdowns
Changes are saved automatically

Open ~/.config/antigravity-proxy/config.json in a text editor
Edit the desired fields
Restart the proxy to apply changes

# Edit config
nano ~/.config/antigravity-proxy/config.json

# Restart proxy
npm start

Manual edits to config.json may be overwritten by WebUI changes. Use the WebUI for real-time configuration updates.

systemd Service Setup

When running the proxy as a systemd service, set the CLAUDE_CONFIG_PATH environment variable to the real user’s .claude directory.

Example Service File

/etc/systemd/system/antigravity-proxy.service

[Unit]
Description=Antigravity Claude Proxy
After=network.target

[Service]
Type=simple
User=myuser
WorkingDirectory=/home/myuser/antigravity-claude-proxy
Environment="NODE_ENV=production"
Environment="CLAUDE_CONFIG_PATH=/home/myuser/.claude"
Environment="PORT=8080"
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and Start

sudo systemctl daemon-reload
sudo systemctl enable antigravity-proxy
sudo systemctl start antigravity-proxy
sudo systemctl status antigravity-proxy

Troubleshooting

Changes not taking effect

Check that you’re editing the correct config file (~/.config/antigravity-proxy/config.json)
Restart the proxy after manual edits
Environment variables override config file settings

Port already in use

Change the port using the PORT environment variable:

PORT=3000 npm start

OAuth callback fails on Windows

Windows may reserve ports 49152-65535 for Hyper-V/WSL2. Set OAUTH_CALLBACK_PORT to a lower port:

OAUTH_CALLBACK_PORT=51122 npm run accounts:add

Config file not found

The config file is created automatically on first run. If it’s missing:

mkdir -p ~/.config/antigravity-proxy
echo '{}' > ~/.config/antigravity-proxy/config.json

Get Started

Guides

Configuration

Integrations

Configuration Priority

Environment Variables

Server Configuration

Security

Proxy & Network

Developer Mode

Model Fallback

systemd / Service Deployments

OAuth Callback Port

Config File Structure

Example config.json

Retry & Rate Limiting

Capacity & Backoff

Account Management

Account Selection Strategy

Hybrid Strategy Tuning

Quota Threshold Configuration

Three-Tier Resolution

Configuring via WebUI

Server Presets

Default (3-5 Accounts)

Many Accounts (10+)

Conservative

Editing the Config File

systemd Service Setup

Example Service File

Enable and Start

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Guides

Configuration

Integrations

​Configuration Priority

​Environment Variables

​Server Configuration

​Security

​Proxy & Network

​Developer Mode

​Model Fallback

​systemd / Service Deployments

​OAuth Callback Port

​Config File Structure

​Example config.json

​Retry & Rate Limiting

​Capacity & Backoff

​Account Management

​Account Selection Strategy

​Hybrid Strategy Tuning

​Quota Threshold Configuration

​Three-Tier Resolution

​Configuring via WebUI

​Server Presets

​Default (3-5 Accounts)

​Many Accounts (10+)

​Conservative

​Editing the Config File

​systemd Service Setup

​Example Service File

​Enable and Start

​Troubleshooting

Build docs developers (and LLMs) love

Configuration Priority

Environment Variables

Server Configuration

Security

Proxy & Network

Developer Mode

Model Fallback

systemd / Service Deployments

OAuth Callback Port

Config File Structure

Example config.json

Retry & Rate Limiting

Capacity & Backoff

Account Management

Account Selection Strategy

Hybrid Strategy Tuning

Quota Threshold Configuration

Three-Tier Resolution

Configuring via WebUI

Server Presets

Default (3-5 Accounts)

Many Accounts (10+)

Conservative

Editing the Config File

systemd Service Setup

Example Service File

Enable and Start

Troubleshooting