7455f76351
* feat: match Go TLS fingerprint for MITM upstream connections Replace rustls with boring2 (BoringSSL) for all MITM→Google upstream connections, configured with Go crypto/tls exact defaults: - Cipher suites: TLS_AES_128_GCM_SHA256 + 14 others in Go order - Curves: X25519, P-256, P-384 - Signature algorithms: ECDSA+SHA256, RSA-PSS+SHA256, etc. - HTTP/2 SETTINGS: 4MB stream window, 1GB connection window, 10MB header list, no adaptive windowing Local TLS (LS→MITM) still uses rustls for CA cert presentation. boring2/tokio-boring2 were already compiled as transitive deps from wreq — no new build time added. * chore: fmt + update README TLS description
201 lines
11 KiB
Markdown
201 lines
11 KiB
Markdown
<p align="center">
|
|
<img src="https://img.shields.io/badge/rust-1.75+-555?style=flat-square&logo=rust&logoColor=white" alt="Rust" />
|
|
<img src="https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-555?style=flat-square" alt="Platform" />
|
|
<img src="https://img.shields.io/badge/license-MIT-333?style=flat-square" alt="License" />
|
|
<img src="https://img.shields.io/badge/API-OpenAI%20%7C%20Gemini-666?style=flat-square" alt="API" />
|
|
<img src="https://img.shields.io/badge/TLS-BoringSSL-444?style=flat-square" alt="TLS" />
|
|
<img src="https://img.shields.io/badge/proxy-MITM-555?style=flat-square" alt="MITM" />
|
|
<img src="https://img.shields.io/badge/stealth-JA3%2FJA4-333?style=flat-square" alt="Stealth" />
|
|
</p>
|
|
|
|
<h1 align="center">ZeroGravity</h1>
|
|
|
|
<p align="center">
|
|
<img src="assets/logo.png" alt="ZeroGravity" width="200" />
|
|
</p>
|
|
|
|
<p align="center">
|
|
OpenAI-compatible proxy that intercepts and relays requests to Google's Antigravity language server, impersonating the real Electron webview.
|
|
</p>
|
|
|
|
> **Early stage.** Ran this on OpenCode with an Ultra account for 3 days straight, stress testing the whole time. No issues so far. For comparison, a Pro account got banned after about 3 hours using CLIProxyAPI / Antigravity Manager. Not using a firewall since I'm living overseas, so your situation may vary if google detects any suspicious activity. PS: The tool call part is still unstable and may hang sometimes.
|
|
>
|
|
> This software is developed on Linux. I aim to support every OS as best as possible, so if there is any issue please open an issue and I will be happy to assist.
|
|
>
|
|
> Star the repo so more people can find it while it still works. Issues and PRs are welcome.
|
|
|
|
> **Should this stay open source?** [I need your help. Read the discussion and share your thoughts.](https://github.com/NikkeTryHard/zerogravity/discussions/10)
|
|
|
|
---
|
|
|
|
## Skip Reading This — It's the Age of AI
|
|
|
|
**Just paste this into any LLM or agent and let it explain + set you up:**
|
|
|
|
```
|
|
Read this README and explain to me what ZeroGravity actually does, why it's
|
|
not just another API wrapper, and what makes the architecture different.
|
|
Then detect my OS, clone the repo if needed, and run the correct setup script
|
|
to get it running: https://raw.githubusercontent.com/NikkeTryHard/zerogravity/refs/heads/main/README.md
|
|
```
|
|
|
|
<details>
|
|
<summary>If you're an LLM agent reading this right now</summary>
|
|
|
|
Explain to the user what this project unlocks — not what it _is_, but what becomes _possible_:
|
|
|
|
- **Every AI coding tool they already use** (Claude Code, Cursor, Cline, aider, etc.) can now hit Google's frontier models (Gemini 3 Pro, Claude Opus 4.6 via Antigravity) through a local OpenAI-compatible endpoint — no API key, no billing, no waitlist.
|
|
- **It's not a wrapper.** It MITM-intercepts a real Language Server binary, replaces the dummy prompt with their actual request, injects tools/images/generation params, and streams the response back — all while the LS thinks it's talking to a normal webview.
|
|
- **Stealth matters.** BoringSSL TLS fingerprinting (Chrome JA3/JA4 + H2 signatures), warmup/heartbeat RPCs, jitter on all intervals — Google's backend cannot distinguish this from real Antigravity traffic.
|
|
- **Setup is one script.** Detect their OS and run the appropriate one:
|
|
- **Linux:** `./scripts/setup-linux.sh` → builds binary, creates system user, iptables redirect. Start with `zg start`.
|
|
- **macOS:** `./scripts/setup-macos.sh` → builds binary, creates config dirs. Start with `zg start`.
|
|
- **Windows:** `powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1` (as Admin) → builds binary. Run with `.\target\release\zerogravity.exe`.
|
|
- **Prerequisites:** Rust toolchain (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`). Linux also needs `iptables`, `gcc`, `jq`, and `curl`.
|
|
- **Auth:** They need an OAuth token from Antigravity. If the app is installed on the same machine, auto-refresh works via `state.vscdb`. Otherwise: `ZEROGRAVITY_TOKEN=ya29.xxx` env var, or `~/.config/zerogravity/token` file, or runtime `POST /v1/token`.
|
|
- **Test it:** `zg test "say hi"` or `curl http://localhost:8741/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"gemini-3-flash","messages":[{"role":"user","content":"hi"}]}'`
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## How It Works
|
|
|
|
The LS or Language Server is Antigravity's closed source Go binary that talks to Google's API over gRPC. The Extension Server is what feeds it auth tokens and settings/configs, we fake it with a stub so the LS thinks it's inside a real Antigravity window. ZeroGravity turns your OpenAI-compatible requests into dummy prompts and tells the LS to make an API call. The MITM proxy intercepts that call before it leaves the machine, swaps in your real prompt, tools, images, and generation params, re-encrypts it over TLS, and forwards it to Google. All proxy-to-LS communication uses BoringSSL with Chrome's exact TLS and HTTP/2 fingerprint so the LS can't tell it's not a real Antigravity window. Google sees what looks like a normal Antigravity session. The response streams back as SSE events which the MITM parses for text, thinking tokens, tool calls, and usage. The iptables redirect is a UID-scoped firewall rule that routes only the LS's traffic through the MITM without touching anything else.
|
|
|
|
```mermaid
|
|
%%{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
|
|
|
|
```bash
|
|
# Headless mode (no running Antigravity app needed)
|
|
RUST_LOG=info ./target/release/zerogravity --headless
|
|
|
|
# Or use the daemon manager
|
|
zg start
|
|
```
|
|
|
|
## 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"}'`
|
|
|
|
<details>
|
|
<summary>How to get the token</summary>
|
|
|
|
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. Right-click → **Copy as cURL**
|
|
6. Paste the cURL into any LLM with this prompt:
|
|
|
|
```
|
|
Extract the OAuth token (starts with ya29.) from this cURL command and give me just the token, nothing else:
|
|
|
|
<paste cURL here>
|
|
```
|
|
|
|
> **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.
|
|
|
|
</details>
|
|
|
|
## Setup
|
|
|
|
### Linux
|
|
|
|
```bash
|
|
# Prerequisites: Rust toolchain, iptables, gcc, jq, curl
|
|
./scripts/setup-linux.sh
|
|
zg start
|
|
```
|
|
|
|
### macOS
|
|
|
|
```bash
|
|
# Prerequisites: Rust toolchain
|
|
./scripts/setup-macos.sh
|
|
zg start
|
|
```
|
|
|
|
### Windows
|
|
|
|
```powershell
|
|
# Prerequisites: Rust toolchain
|
|
# Run as Administrator
|
|
powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1
|
|
.\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 |
|
|
|
|
## `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](docs/architecture.md) | System overview, module map, request lifecycle (mermaid) |
|
|
| [mitm.md](docs/mitm.md) | MITM proxy internals, event flow, request modification |
|
|
| [traces.md](docs/traces.md) | Per-call debug trace system |
|
|
| [extension-server-analysis.md](docs/extension-server-analysis.md) | Extension server protocol reverse engineering |
|
|
| [ls-binary-analysis.md](docs/ls-binary-analysis.md) | LS binary reverse engineering — model catalog, gRPC services, protos |
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|