Antigravity Proxy

Antigravity Proxy

Use any AI provider with Antigravity 2.0 — NVIDIA, OpenRouter, OpenAI, Groq, Anthropic, Google Gemini, OpenCode Zen, OpenCode Go, or 9+ local inference solutions.

Quick Install

npm install -g @12errh/antigravity-proxy
antigravity setup    # interactive wizard — picks provider, enters API key, configures port
antigravity start    # starts proxy + dashboard + launches Antigravity desktop

No clone required. The npm package includes everything: CLI, proxy, dashboard, certs, and all providers. Install once, run anywhere.

Quick Start

Prerequisites

• Antigravity 2.0 Desktop (Windows, macOS, or Linux)
• Node.js 20+
• Administrator/root privileges (port 443) — on Linux/macOS run sudo antigravity start; the CLI re-execs under a Node 20+ it finds on your machine (nvm, fnm, volta, or system), so sudo doesn't need Node on root's PATH
• At least one API key or local model server

Platform Support

Prerequisite differs per platform: port 443 needs Administrator on Windows (the CLI raises UAC automatically) and root/sudo on Linux/macOS. The desktop app always connects on 443 (routed to the proxy via the hosts file), so proxy mode must bind 443 to intercept app traffic — a PROXY_PORT of e.g. 8443 is auto-corrected back to 443 on root starts. --port 8443 runs the proxy without elevation for direct API testing only; the desktop app's sign-in won't be intercepted on other ports.

Launch via CLI (recommended)

npm install -g @12errh/antigravity-proxy
antigravity start                    # background mode — runs silently, launches desktop
antigravity start --foreground       # foreground mode — see live logs in terminal
antigravity start --port 8443        # no admin needed (testing only — app sign-in needs 443)
antigravity start --trust-cert       # auto-trust TLS certificate
antigravity stop                     # stop everything cleanly

Launch from source (development)

Get the Repository

git clone https://github.com/12errh/antigravity-proxy.git
cd antigravity-proxy

Windows (PowerShell as Administrator)

.\start.ps1

macOS / Linux

chmod +x start.sh
./start.sh

Without admin (port 8443 — testing only)

./start.sh --port 8443

The desktop app always connects on 443; use --simple to launch the app with no proxy, or run with sudo/Administrator for app interception.

Then open http://localhost:4000 in your browser to configure providers, model mappings, and view live stats.

🎯 Key Features

🚀 How It Works

graph TD
    A[Antigravity 2.0 Desktop] --> B[TLS 443]
    B --> C[Proxy]
    C --> D[Cloud APIs]
    C --> E[Local APIs]
    C --> F[Dashboard]
    
    D --> G[OpenRouter]
    D --> H[NVIDIA]
    D --> I[OpenAI]
    D --> J[Groq]
    D --> K[Anthropic]
    D --> L[Google Gemini]
    D --> M[Zen]
    
    E --> N[Ollama]
    E --> O[vLLM]
    E --> P[LM Studio]
    E --> Q[llama.cpp]
    
    F --> R[Live Logs]
    F --> S[Request History]
    F --> T[Config Editor]
    F --> U[Model Matrix]
    F --> V[Provider Priority]

Per Request Pipeline

1. TLS Intercept — Receives Gemini API call on port 443
2. Context Stripping — Removes bulk context, injects compact agent-context.md reference
3. Tool Normalization — Resolves aliases, coerces types, fills defaults
4. Model Resolution — Routes through priority order with retry + backoff
5. Capability Detection — Auto-detects reasoning/vision/tool support
6. Reasoning Effort — Applies reasoning_effort if configured
7. Translation — Converts to target provider's API format
8. Streaming — Returns SSE response wrapped in Gemini format
9. Logging — Records to SQLite for cost tracking, history, sessions

📊 Supported Providers

Cloud APIs

Local Inference

📋 Models Tab — Matrix

The Models tab shows a matrix: one row per Antigravity model alias, one column per provider.

graph TD
    A[Model Alias] --> B[Default]
    A --> C[OpenRouter]
    A --> D[Zen]
    
    E[claude-sonnet-4-6] --> F[claude-sonnet-4-5]
    E --> G[anthropic/claude-3-5-sonnet-20241022]
    E --> H[claude-sonnet-4-5]
    
    I[gemini-2.5-flash] --> J[gemini-2.5-flash]
    I --> K[google/gemini-2.0-flash-exp]
    I --> L[deepseek-v4-flash]
    
    M[gpt-4o] --> N[openai/gpt-4o]
    M --> O[openai/gpt-4o]

Features:

• Double-click any cell to open live model picker
• Column toggles to hide unused providers
• Quick-add buttons (+ Claude, + Gemini, + GPT)
• Empty cells use Default value
• Provider logos in filled cells

🧠 Model Options — Reasoning Effort

Some models support reasoning_effort to control thinking depth:

Auto-detection: The Model Options tab detects supported models and lets you set levels per model. Settings persist in proxy/reasoning-effort.json without restart.

⚙️ Config Tab — API Keys

All keys are hot-reloaded from .env — no restart needed.

🏗️ Architecture

graph TD
    %% Root level
    A[agent-context.md] --> B[start.ps1]
    B --> C[README.md]
    C --> D[CHANGELOG.md]
    C --> E[docs/]
    C --> F[proxy/]
    
    %% docs/ directory
    E --> G[SETUP.md]
    E --> H[CONFIGURATION.md]
    E --> I[DEVELOPER.md]
    
    %% proxy/ directory
    F --> K[src/]
    
    %% src/ directory - main components
    K --> L[adapters/]
    K --> M[adapter.ts]
    K --> N[provider-plugin.ts]
    K --> O[provider-registry.ts]
    K --> P[plugins/]
    K --> Q[tool-capabilities.ts]
    K --> R[tool-normalizer.ts]
    K --> S[model-capabilities.ts]
    K --> T[router.ts]
    K --> U[models.ts]
    K --> V[index.ts]
    K --> W[engine.ts]
    K --> X[mapper.ts]
    K --> Y[config.ts]
    K --> Z[provider-cache.ts]
    
    %% adapters subdirectory
    L --> A1[openai.ts]
    L --> A2[anthropic.ts]
    L --> A3[google.ts]
    L --> A4[groq.ts]
    L --> A5[zen.ts]
    L --> A6[nvidia.ts]
    L --> A7[types.ts]
    
    %% plugins subdirectory
    P --> B1[builtin-plugins.ts]
    
    %% dashboard subdirectory
    F --> C1[dashboard/]
    C1 --> C2[index.html]
    C1 --> C3[login.html]
    
    %% Other files in proxy/
    F --> D1[models.json]
    F --> D2[pricing.json]
    F --> D3[reasoning-effort.json]
    F --> D4[blocklist.json]
    F --> D5[.env]
    F --> D6[.env.example]
    F --> D7[certs/]
    F --> D8[logs/]
    
    %% Note: actual configuration for certs and logs are nested

---

## 🔧 Environment Variables

```env
# Provider priority (first = primary)
PROVIDER_PRIORITY=openrouter,nvidia,zen

# API keys
OPENROUTER_API_KEY=sk-or-v1-...
NVIDIA_API_KEY=nvapi-...
OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk_...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...
OPENCODE_API_KEY=sk-...
OPENCODE_GO_API_KEY=sk-opencode-go-...

# Ports
PROXY_PORT=443          # TLS port the desktop app connects to (root starts auto-correct other values)
API_PORT=4000           # Dashboard + REST API port

# Retry & failover
PROXY_RETRIES=3         # Attempts per provider
PROXY_BACKOFF_MS=100    # Initial backoff (doubles each retry)

# Rate limiting (0 = unlimited)
RATE_LIMIT_GLOBAL=0
RATE_LIMIT_PROVIDER=0
RATE_LIMIT_WINDOW_MS=60000

# Logging
LOG_LEVEL=info          # debug | info | warn | error
LOG_MAX_SIZE_MB=10      # Rotate when reached
LOG_MAX_FILES=5         # Keep N rotated files
LOG_MAX_AGE_DAYS=30     # Delete files older than

# Dashboard auth (optional)
DASHBOARD_USER=admin
DASHBOARD_PASSWORD=your_password

# Failover webhook (optional)
FAILOVER_WEBHOOK_URL=https://hooks.example.com/webhook

# Workspace context hardening
WORKSPACE_CONTEXT_ENVELOPE=strict   # off | loose | strict

# Inline context mode
CONTEXT_STRIP_MODE=lite             # lite (recommended) | strip | passthrough

💡 Context Mode Explained

Lite (recommended): Uses compressed agent-context-lite.md (~3.5K tokens) — same tool coverage as full context, 66% fewer tokens. Strips native Antigravity context, injects compressed version.

Strip: Uses full agent-context.md (~10K tokens) — removes bulk context (skills/plugins/identity), injects complete operating manual.

Passthrough: Forwards native Antigravity context unchanged (~28K tokens) — simplest approach, no injection overhead.

📚 Quick Links

• Setup Guide
• Configuration Reference
• Developer Guide ← For adding providers & plugin development
• CHANGELOG
• Contributing
• Security Policy

⚡ Development Quick Start

cd proxy
npm install            # Install dependencies
npm run build          # Compile TypeScript → dist/
npm run typecheck      # Type-check only
npm test               # Run tests
npm run dev            # Watch mode

New Providers: See docs/DEVELOPER.md for plugin architecture guide.

Run tests:

# All tests
npm test

# Filter by component
npx tsx test/run.ts plugin-architecture
npx tsx test/run.ts tool-translation
npx tsx test/run.ts model-discovery
npx tsx test/run.ts provider-adapters

📝 License

MIT — see LICENSE.