![\"Antigravity\"](\"https://antigravity.google/assets/image/brand/antigravity-icon__full-color.png\"){kind=icon}
\n\n \n
Use any AI provider with Antigravity 2.0 — NVIDIA, OpenRouter, OpenAI, Groq, Anthropic, Google Gemini, OpenCode Zen, OpenCode Go, or 9+ local inference solutions.
\n\n\n\n---\n\n## Quick Install\n\n```bash\nnpm install -g @12errh/antigravity-proxy\nantigravity setup # interactive wizard — picks provider, enters API key, configures port\nantigravity start # starts proxy + dashboard + launches Antigravity desktop\n```\n\n> **No clone required.** The npm package includes everything: CLI, proxy, dashboard, certs, and all providers. Install once, run anywhere.\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Antigravity 2.0 Desktop** (Windows, macOS, or Linux)\n- **Node.js 20+** \n- **Administrator/root privileges** (port 443; can use 8443 without admin)\n- At least one API key or local model server\n\n### Platform Support\n\n| Platform | Status | Notes |\n|----------|--------|-------|\n| **Windows 10/11** | ✅ Tested | CLI handles cert install, port binding, and launch |\n| **macOS** | ⚠️ Untested | CLI with best-effort cert trust. Report issues on GitHub. |\n| **Linux** | ⚠️ Untested | CLI with best-effort cert trust. Report issues on GitHub. |\n\n> TypeScript code is cross-platform. Only TLS cert trust is platform-specific.\n\n### Launch via CLI (recommended)\n\n```bash\nnpm install -g @12errh/antigravity-proxy\nantigravity start # background mode — runs silently, launches desktop\nantigravity start --foreground # foreground mode — see live logs in terminal\nantigravity start --port 8443 # no admin needed\nantigravity start --trust-cert # auto-trust TLS certificate\nantigravity stop # stop everything cleanly\n```\n\n### Launch from source (development)\n\n**Get the Repository**\n\n```bash\ngit clone https://github.com/12errh/antigravity-proxy.git\ncd antigravity-proxy\n```\n\n**Windows (PowerShell as Administrator)**\n\n```powershell\n.\\start.ps1\n```\n\n**macOS / Linux**\n\n```bash\nchmod +x start.sh\n./start.sh\n```\n\n**Without admin (port 8443)**\n\n```bash\n./start.sh --port 8443\n```\n\nThen open **http://localhost:4000** in your browser to configure providers, model mappings, and view live stats.\n\n---\n\n## 🎯 Key Features\n\n| Feature | Status | Description |\n|---------|--------|-------------|\n| **Auto context compaction** | ✅ | LLM-based summarization when approaching context limits |\n| **Model fallback per provider** | ✅ | Try multiple models within same provider before failover |\n| **Multi-provider failover** | ✅ | Priority chain with exponential backoff |\n| **Per-model routing** | ✅ | One row per model alias, one column per provider |\n| **Retry + backoff** | ✅ | Configurable per-provider and global |\n| **Hot-reload config** | ✅ | No restart needed for changes |\n| **Tool normalization** | ✅ | Alias resolution, type coercion, default filling |\n| **Model capability detection** | ✅ | Auto-detect reasoning, vision, tools |\n| **Provider optimizations** | ✅ | Groq (image stripping), Zen/NVIDIA (reasoning effort) |\n| **Real-time dashboard** | ✅ | Live logs, stats, config editor |\n| **Cost tracking** | ✅ | Per-day, per-model, per-provider |\n| **Local discovery** | ✅ | 9+ inference solutions auto-detected |\n| **Full-text search** | ✅ | Search requests, sessions, logs |\n| **Blocklist** | ✅ | Provider, model, content filtering |\n| **Session comparison** | ✅ | Side-by-side session analysis |\n\n---\n\n## 🚀 How It Works\n\n```mermaid\ngraph TD\n A[Antigravity 2.0 Desktop] --> B[TLS 443]\n B --> C[Proxy]\n C --> D[Cloud APIs]\n C --> E[Local APIs]\n C --> F[Dashboard]\n \n D --> G[OpenRouter]\n D --> H[NVIDIA]\n D --> I[OpenAI]\n D --> J[Groq]\n D --> K[Anthropic]\n D --> L[Google Gemini]\n D --> M[Zen]\n \n E --> N[Ollama]\n E --> O[vLLM]\n E --> P[LM Studio]\n E --> Q[llama.cpp]\n \n F --> R[Live Logs]\n F --> S[Request History]\n F --> T[Config Editor]\n F --> U[Model Matrix]\n F --> V[Provider Priority]\n```\n\n### Per Request Pipeline\n\n1. **TLS Intercept** — Receives Gemini API call on port 443\n2. **Context Stripping** — Removes bulk context, injects compact `agent-context.md` reference\n3. **Tool Normalization** — Resolves aliases, coerces types, fills defaults\n4. **Model Resolution** — Routes through priority order with retry + backoff\n5. **Capability Detection** — Auto-detects reasoning/vision/tool support\n6. **Reasoning Effort** — Applies `reasoning_effort` if configured\n7. **Translation** — Converts to target provider's API format\n8. **Streaming** — Returns SSE response wrapped in Gemini format\n9. **Logging** — Records to SQLite for cost tracking, history, sessions\n\n---\n\n## 📊 Supported Providers\n\n### Cloud APIs\n\n| Provider | Type | Env Var | Notes |\n|----------|------|---------|-------|\n| **OpenRouter** | Cloud API | `OPENROUTER_API_KEY` | 300+ models in one key |\n| **NVIDIA NIM** | Cloud API | `NVIDIA_API_KEY` | Free credits on signup |\n| **OpenAI** | Cloud API | `OPENAI_API_KEY` | GPT-4o, o-series |\n| **Groq** | Cloud API | `GROQ_API_KEY` | Ultra-fast LPU inference |\n| **Anthropic** | Cloud API | `ANTHROPIC_API_KEY` | Claude 3.x / 4.x |\n| **Google Gemini** | Cloud API | `GOOGLE_API_KEY` | Gemini 2.5 Pro/Flash |\n| **OpenCode Zen** | Cloud gateway | `OPENCODE_API_KEY` | Claude, GPT, Gemini, Grok, Kimi, GLM — one key |\n| **OpenCode Go** | Cloud gateway | `OPENCODE_GO_API_KEY` | DeepSeek, Qwen, MiniMax, GLM, Kimi, MiMo — $10/mo |\n\n### Local Inference\n\n| Provider | Type | Notes |\n|----------|------|-------|\n| **Ollama** | Local | Auto-discovered on port 11434 |\n| **vLLM** | Local | Auto-discovered on port 8000 |\n| **LM Studio** | Local | Auto-discovered on port 1234 |\n| **llama.cpp** | Local | Auto-discovered on port 8080 |\n| **text-generation-webui** | Local | Auto-discovered on port 5000 |\n| **TabbyAPI** | Local | Auto-discovered on port 5000 |\n| **LocalAI** | Local | Auto-discovered on port 8080 |\n| **LiteLLM** | Local | Auto-discovered on port 4000 |\n| **Aphrodite Engine** | Local | Auto-discovered on port 8000 |\n\n---\n\n## 📋 Models Tab — Matrix\n\nThe Models tab shows a matrix: one row per Antigravity model alias, one column per provider.\n\n```mermaid\ngraph TD\n A[Model Alias] --> B[Default]\n A --> C[OpenRouter]\n A --> D[Zen]\n \n E[claude-sonnet-4-6] --> F[claude-sonnet-4-5]\n E --> G[anthropic/claude-3-5-sonnet-20241022]\n E --> H[claude-sonnet-4-5]\n \n I[gemini-2.5-flash] --> J[gemini-2.5-flash]\n I --> K[google/gemini-2.0-flash-exp]\n I --> L[deepseek-v4-flash]\n \n M[gpt-4o] --> N[openai/gpt-4o]\n M --> O[openai/gpt-4o]\n```\n\n**Features:**\n- Double-click any cell to open live model picker\n- Column toggles to hide unused providers\n- Quick-add buttons (`+ Claude`, `+ Gemini`, `+ GPT`)\n- Empty cells use Default value\n- Provider logos in filled cells\n\n---\n\n## 🧠 Model Options — Reasoning Effort\n\nSome models support `reasoning_effort` to control thinking depth:\n\n| Model family | Levels |\n|--------------|--------|\n| DeepSeek R-series | low, medium, high, max |\n| NVIDIA stepfun | low, medium, high, max |\n| OpenAI o-series | low, medium, high |\n| Qwen Thinking, GLM Thinking, Kimi | low, medium, high |\n\n**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.\n\n---\n\n## ⚙️ Config Tab — API Keys\n\n| Key | Provider |\n|-----|----------|\n| `OPENROUTER_API_KEY` | [openrouter.ai/keys](https://openrouter.ai/keys) |\n| `NVIDIA_API_KEY` | [build.nvidia.com](https://build.nvidia.com) — free credits on signup |\n| `OPENAI_API_KEY` | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |\n| `GROQ_API_KEY` | [console.groq.com/keys](https://console.groq.com/keys) |\n| `ANTHROPIC_API_KEY` | [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys) |\n| `GOOGLE_API_KEY` | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |\n| `OPENCODE_API_KEY` | [opencode.ai/auth](https://opencode.ai/auth) — one key for Claude, GPT, Gemini, Grok, Kimi, GLM |\n\nAll keys are hot-reloaded from `.env` — no restart needed.\n\n---\n\n## 🏗️ Architecture\n\n```mermaid\ngraph TD\n %% Root level\n A[agent-context.md] --> B[start.ps1]\n B --> C[README.md]\n C --> D[CHANGELOG.md]\n C --> E[docs/]\n C --> F[proxy/]\n \n %% docs/ directory\n E --> G[SETUP.md]\n E --> H[CONFIGURATION.md]\n E --> I[DEVELOPER.md]\n E --> J[antigravity-v2-analysis.md]\n \n %% proxy/ directory\n F --> K[src/]\n \n %% src/ directory - main components\n K --> L[adapters/]\n K --> M[adapter.ts]\n K --> N[provider-plugin.ts]\n K --> O[provider-registry.ts]\n K --> P[plugins/]\n K --> Q[tool-capabilities.ts]\n K --> R[tool-normalizer.ts]\n K --> S[model-capabilities.ts]\n K --> T[router.ts]\n K --> U[models.ts]\n K --> V[index.ts]\n K --> W[engine.ts]\n K --> X[mapper.ts]\n K --> Y[config.ts]\n K --> Z[provider-cache.ts]\n \n %% adapters subdirectory\n L --> A1[openai.ts]\n L --> A2[anthropic.ts]\n L --> A3[google.ts]\n L --> A4[groq.ts]\n L --> A5[zen.ts]\n L --> A6[nvidia.ts]\n L --> A7[types.ts]\n \n %% plugins subdirectory\n P --> B1[builtin-plugins.ts]\n \n %% dashboard subdirectory\n F --> C1[dashboard/]\n C1 --> C2[index.html]\n C1 --> C3[login.html]\n \n %% Other files in proxy/\n F --> D1[models.json]\n F --> D2[pricing.json]\n F --> D3[reasoning-effort.json]\n F --> D4[blocklist.json]\n F --> D5[.env]\n F --> D6[.env.example]\n F --> D7[certs/]\n F --> D8[logs/]\n \n %% Note: actual configuration for certs and logs are nested\n```\n```\n\n---\n\n## 🔧 Environment Variables\n\n```env\n# Provider priority (first = primary)\nPROVIDER_PRIORITY=openrouter,nvidia,zen\n\n# API keys\nOPENROUTER_API_KEY=sk-or-v1-...\nNVIDIA_API_KEY=nvapi-...\nOPENAI_API_KEY=sk-...\nGROQ_API_KEY=gsk_...\nANTHROPIC_API_KEY=sk-ant-...\nGOOGLE_API_KEY=AIza...\nOPENCODE_API_KEY=sk-...\nOPENCODE_GO_API_KEY=sk-opencode-go-...\n\n# Ports\nPROXY_PORT=443 # TLS port Antigravity connects to\nAPI_PORT=4000 # Dashboard + REST API port\n\n# Retry & failover\nPROXY_RETRIES=3 # Attempts per provider\nPROXY_BACKOFF_MS=100 # Initial backoff (doubles each retry)\n\n# Rate limiting (0 = unlimited)\nRATE_LIMIT_GLOBAL=0\nRATE_LIMIT_PROVIDER=0\nRATE_LIMIT_WINDOW_MS=60000\n\n# Logging\nLOG_LEVEL=info # debug | info | warn | error\nLOG_MAX_SIZE_MB=10 # Rotate when reached\nLOG_MAX_FILES=5 # Keep N rotated files\nLOG_MAX_AGE_DAYS=30 # Delete files older than\n\n# Dashboard auth (optional)\nDASHBOARD_USER=admin\nDASHBOARD_PASSWORD=your_password\n\n# Failover webhook (optional)\nFAILOVER_WEBHOOK_URL=https://hooks.example.com/webhook\n\n# Workspace context hardening\nWORKSPACE_CONTEXT_ENVELOPE=strict # off | loose | strict\n\n# Inline context mode\nCONTEXT_STRIP_MODE=lite # lite (recommended) | strip | passthrough\n```\n\n> ### 💡 Context Mode Explained\n>\n> **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.\n>\n> **Strip:** Uses full `agent-context.md` (~10K tokens) — removes bulk context (skills/plugins/identity), injects complete operating manual.\n>\n> **Passthrough:** Forwards native Antigravity context unchanged (~28K tokens) — simplest approach, no injection overhead.\n\n---\n\n## 📚 Quick Links\n\n- [Setup Guide](docs/SETUP.md)\n- [Configuration Reference](docs/CONFIGURATION.md)\n- [Developer Guide](docs/DEVELOPER.md) ← **For adding providers & plugin development**\n- [CHANGELOG](CHANGELOG.md)\n- [Contributing](CONTRIBUTING.md)\n- [Security Policy](SECURITY.md)\n\n---\n\n## ⚡ Development Quick Start\n\n```bash\ncd proxy\nnpm install # Install dependencies\nnpm run build # Compile TypeScript → dist/\nnpm run typecheck # Type-check only\nnpm test # Run tests\nnpm run dev # Watch mode\n```\n\n**New Providers:** See `docs/DEVELOPER.md` for plugin architecture guide.\n\n**Run tests:**\n\n```bash\n# All tests\nnpm test\n\n# Filter by component\nnpx tsx test/run.ts plugin-architecture\nnpx tsx test/run.ts tool-translation\nnpx tsx test/run.ts model-discovery\nnpx tsx test/run.ts provider-adapters\n```\n\n## 📝 License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}![\"npm](\"https://img.shields.io/npm/v/@12errh/antigravity-proxy.svg\")
\n ![\"npm](\"https://img.shields.io/npm/dm/@12errh/antigravity-proxy.svg\")
\n ![\"CI\"](\"https://github.com/12errh/antigravity-proxy/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"Node](\"https://img.shields.io/badge/node-%3E%3D20-brightgreen\"){kind=icon}
=20\">\n ![\"MIT\"](\"https://img.shields.io/badge/license-MIT-blue\"){kind=icon}
\n ![\"Platform\"](\"https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey\"){kind=icon}
\n