# ZeroGravity

<p align="center">
  <img src="assets/logo.png" alt="ZeroGravity" width="200" />
</p>

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

```mermaid
%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'primaryBorderColor': '#7c3aed', 'lineColor': '#7c3aed', 'secondaryColor': '#16213e', 'tertiaryColor': '#0f3460', 'edgeLabelBackground': '#1a1a2e', 'nodeTextColor': '#e0e0e0'}}}%%
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:#7c3aed,color:#fff
    style MITM fill:#e94560,color:#fff
    style LS fill:#2563eb,color:#fff
    style Google fill:#059669,color:#fff
```

## Quick Start

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

# Or use the daemon manager
zg start
```

## 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"}'`

## `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

Private. Do not distribute.