zerogravity/README.md

ZeroGravity

OpenAI-compatible proxy that intercepts and relays requests to Google's Antigravity language server, impersonating the real Electron webview.

---

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#2a2a2a', 'primaryTextColor': '#d0d0d0', 'primaryBorderColor': '#888', 'lineColor': '#888', 'secondaryColor': '#333', 'tertiaryColor': '#3a3a3a', 'edgeLabelBackground': '#2a2a2a', 'nodeTextColor': '#d0d0d0'}}}%%
graph LR
    Client["Client"] -->|"OpenAI / Gemini API"| Proxy["Proxy :8741"]
    Proxy -->|"gRPC (dummy prompt)"| LS["Standalone LS"]
    LS -->|"HTTPS :443"| MITM["MITM :8742"]
    MITM -->|"Modified request<br/>(real prompt + tools)"| Google["Google API"]
    Google -->|"SSE response"| MITM
    MITM -->|"Usage, errors,<br/>function calls"| Proxy
    LS -.->|"iptables redirect<br/>(UID-scoped)"| MITM

    style Proxy fill:#4a4a4a,color:#e0e0e0,stroke:#888
    style MITM fill:#3a3a3a,color:#e0e0e0,stroke:#888
    style LS fill:#505050,color:#e0e0e0,stroke:#888
    style Google fill:#444,color:#e0e0e0,stroke:#888

Models

Name	Label	Notes
opus-4.6	Claude Opus 4.6 (Thinking)	Default model
opus-4.5	Claude Opus 4.5 (Thinking)	—
gemini-3-pro	Gemini 3 Pro (High)	Default Pro tier
gemini-3-pro-high	Gemini 3 Pro (High)	Alias
gemini-3-pro-low	Gemini 3 Pro (Low)	—
gemini-3-flash	Gemini 3 Flash	Recommended for dev

Quick Start

# Headless mode (no running Antigravity app needed)
RUST_LOG=info ./target/release/zerogravity --headless

# Or use the daemon manager
zg start

Setup

Linux

# Prerequisites: Rust toolchain, iptables
./scripts/setup-linux.sh

Creates a zerogravity-ls system user for UID-scoped iptables isolation, installs a systemd user service, and builds the release binary.

# Start the service
systemctl --user enable --now zerogravity

# Or use the daemon manager
zg start

macOS

# Prerequisites: Rust toolchain
./scripts/setup-macos.sh

Installs a launchd plist for automatic startup. No UID isolation — runs in headless/HTTPS_PROXY mode only.

# Start the service
launchctl load ~/Library/LaunchAgents/com.zerogravity.proxy.plist

# Or use the daemon manager
zg start

Windows

# Prerequisites: Rust toolchain
# Run as Administrator
powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1

Creates config directories, builds the release binary, and installs a scheduled task for automatic startup at logon.

# Start now
schtasks /run /tn "ZeroGravity Proxy"

# Or manually
.\target\release\zerogravity.exe

Endpoints

Method	Path	Description
POST	/v1/responses	Responses API (sync + streaming)
POST	/v1/chat/completions	Chat Completions API (OpenAI compat)
POST	/v1beta/models/{model}:{action}	Official Gemini v1beta routes
GET/POST	/v1/search	Web Search via Google grounding (WIP)
GET	/v1/models	List available models
GET	/v1/sessions	List active sessions
DELETE	/v1/sessions/{id}	Delete a session
POST	/v1/token	Set OAuth token at runtime
GET	/v1/usage	MITM-intercepted token usage
GET	/v1/quota	LS quota and rate limits
GET	/health	Health check

Authentication

The proxy needs an OAuth token:

1. Env var: ZEROGRAVITY_TOKEN=ya29.xxx
2. Token file: ~/.config/zerogravity-token
3. Runtime: curl -X POST http://localhost:8741/v1/token -d '{"token":"ya29.xxx"}'

How to get the token

1. Open Antigravity → Help > Toggle Developer Tools
2. Go to the Network tab
3. Send any prompt
4. Find a request to generativelanguage.googleapis.com or SendUserCascadeMessage
5. Copy the ya29.xxx... token from the Authorization header or protobuf payload

Note: OAuth tokens expire after ~1 hour. If Antigravity is installed on the same machine, the proxy reads state.vscdb which contains a refresh token — auto-refresh works automatically even without Antigravity running. If you provide a bare ya29.xxx token via env/file/runtime, there's no refresh token, so you'll need to update it manually when it expires.

zg Commands

Command	Description
zg start	Start the proxy daemon
zg stop	Stop the proxy daemon
zg restart	Rebuild + restart
zg rebuild	Build release binary only
zg status	Service status + quota + usage
zg logs [N]	Tail last N lines + follow
zg test [msg]	Quick test request
zg health	Health check

Documentation

Doc	Contents
architecture.md	System overview, module map, request lifecycle (mermaid)
mitm.md	MITM proxy internals, event flow, request modification
traces.md	Per-call debug trace system
extension-server-analysis.md	Extension server protocol reverse engineering
ls-binary-analysis.md	LS binary reverse engineering — model catalog, gRPC services, protos

License

MIT