



Quickstart · Docs · Issues
English · Português · 中文 · Español
## 🖼️ Demo
One local endpoint
POST /v1/chat/completions (OpenAI), POST /v1/messages (Anthropic), GET /v1/models and GET /v1/models/capabilities, so Cursor, Windsurf, OpenCode, Claude Code and similar clients can connect. Model names are mapped through custom_mapping and anthropic_mapping. |
Account pool Google accounts added through OAuth, each with its status (Active, Rate Limited, Expired), last-used time and an optional per-account proxy URL. |
Auto-switch
CloudMonitorService polls quota every 5 minutes and AutoSwitchService moves to another account when quota drops below 5 % or the account is rate-limited. |
Scheduling with a circuit breaker
cache-first, balance (default) or performance-first, with a per-account circuit breaker (default backoff 60 s → 5 min → 30 min → 2 h). |
Usage and cost Token usage per account and model, prompt and completion charts, and cost estimates from editable per-model pricing. |
Traffic inspector Latency, status and model for each request, replay of logged requests, generated cURL and Python snippets, plus an IDE Quick Setup. |
Stored credentials are encrypted with AES-256-GCM under an OS-keychain master key (see [Security model](#-security-model)).
## How it works
1. **Add accounts.** Sign in with Google OAuth on the Accounts page. Tokens are encrypted before they reach SQLite.
2. **Point your IDE at the proxy.** Enable the proxy on the Proxy page (it is off by default) and use `http://localhost:8045/v1` with the API key shown there, in OpenAI or Anthropic format.
3. **Nexus routes each request.** The token manager picks an account by scheduling mode and circuit-breaker state, calls Google's upstream APIs with that account's OAuth token, and auto-switch moves on when quota drops below 5 % or an account is rate-limited.
The full flow, with the components involved, is in [Architecture](#-architecture).
## 🚀 Quickstart
There are no prebuilt downloads on the [Gitea Releases](https://git.evandro.dev.br/evandro/gemini-nexus/releases) page yet (the release workflows in `.github/workflows/` target GitHub), so build from source.
| Tool | Minimum version |
|---|---|
| Node.js | 20+ (recommended in `AGENTS.md`; `.nvmrc` pins 22.17.1) |
| pnpm | 10.11.0 (`packageManager`; lockfile is `pnpm-lock.yaml`) |
| Native toolchain | needed by `better-sqlite3` and `keytar`: Visual Studio 2022 Build Tools (C++) on Windows, Xcode Command Line Tools on macOS, `build-essential` + `python3` + `libsecret-1-dev` on Ubuntu (`base-devel` + `python` + `libsecret` on Arch) |
```bash
git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
cd gemini-nexus
pnpm install # postinstall runs scripts/setup-dev.js --check-only to verify the toolchain
pnpm start # dev mode (Electron + Vite HMR)
pnpm run make # installers/packages for the current platform
pnpm run make:win # Windows: extracts WiX from wix314-binaries.zip, then runs make
```
Then add at least one account, enable the proxy (it is disabled by default) and point your IDE at it:
```text
API Base URL: http://localhost:8045/v1 (default, configurable on the Proxy page; development builds use 8046)
API Key: (copy it from the Proxy page in the app)
Model: gemini-3-flash (or any mapped model)
```
> [!WARNING]
> Builds are not code-signed. If Windows shows "Windows protected your PC", click **More info → Run anyway**.
There is no `.env.example` and no variable is required. Optional variables read by the code or described in the docs:
| Variable | Required | Description |
|---|---|---|
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | No | Route the app's outbound requests through a local proxy (see [TLS inspection](#-security-model)). |
| `NODE_EXTRA_CA_CERTS` | No | Extra CA certificate for Node-side TLS when inspecting traffic. |
| `SENTRY_DSN` | No | Sentry DSN used when error reporting is enabled. |
## Stack
| Layer | Technology |
|---|---|
| Desktop shell | Electron 41, Electron Forge, Vite |
| Interface | React 19, TypeScript, Tailwind CSS 4, Radix UI, Nivo charts, i18next |
| App data flow | TanStack Router and Query, oRPC over Electron IPC |
| Proxy | NestJS 11 on Fastify |
| Storage | SQLite (better-sqlite3 + Drizzle ORM), OS keychain via `keytar` |
| Logs and errors | Winston (rotating files), Sentry (optional) |
| Tests | Vitest, Playwright |
## 🧱 Architecture
```mermaid
flowchart LR
C["Client: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["NestJS proxy, port 8045"]
P --> S["Account scheduler and circuit breaker"]
S -->|"Google OAuth account"| G["Google upstream APIs"]
M["CloudMonitor and AutoSwitch, quota every 5 min"] -->|"quota polling"| G
S -->|"reads accounts"| DB[("SQLite: better-sqlite3 and Drizzle")]
M --> DB
K["AES-256-GCM, master key in OS keychain"] -->|"encrypts tokens"| DB
```
1. A client sends OpenAI- or Anthropic-format requests to the NestJS proxy (Fastify, bound to `0.0.0.0`).
2. The proxy guard checks the API key when one is configured; with an empty key the proxy runs in open mode.
3. The token manager picks an account according to the scheduling mode and each account's circuit-breaker state, then calls Google's upstream APIs with that account's OAuth token.
4. `CloudMonitorService` polls quota every 5 minutes and `AutoSwitchService` switches the active account when quota is below 5 % or the account is rate-limited.
5. The React 19 renderer (TanStack Router and Query) talks to the main process over oRPC on IPC; accounts, usage and settings live in SQLite (better-sqlite3 + Drizzle). Design notes: [`docs/cloud_features.md`](docs/cloud_features.md).
## 🔒 Security model
Gemini Nexus holds OAuth tokens for several accounts and forwards traffic upstream, so credential handling is the core of the design. Everything below is implemented in this repository; limits are stated where they exist.
- **Credential storage and isolation.** `token_json` and `quota_json` are encrypted with AES-256-GCM (unique IV per operation, authenticated) before they reach SQLite. The master key lives in the OS credential store through `keytar` (Windows Credential Manager, macOS Keychain, Linux Secret Service/libsecret), never in a plain file. Legacy plaintext rows are migrated at startup. Accounts are kept in their own database (`cloud_accounts.db`), independent from the IDE's local database.
- **Log masking.** Keys such as `token`, `refresh_token`, `api_key`, `authorization`, `cookie` and `client_secret` are replaced by `[REDACTED]` before logging ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); the traffic logger also redacts the `authorization`, `x-api-key` and `cookie` headers.
- **Request logging, not an audit trail.** Winston writes API, traffic and app logs to rotating files (API log: 30 days, 50 MB per file). These are operational logs, not a tamper-evident audit trail; the `*-audit.json` files are rotation bookkeeping from `winston-daily-rotate-file`.
- **Proxy access.** The proxy is off by default. Once enabled it listens on `0.0.0.0`, and requests are authenticated only when `api_key` is non-empty (empty means open mode). Set a key and keep it private.
- **TLS inspection (debugging only).** [`docs/proxyman-install.md`](docs/proxyman-install.md) and [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explain how to read the app's HTTPS traffic with Proxyman: trust its root CA, set the proxy variables and `NODE_EXTRA_CA_CERTS`, then start the app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (and the script's `-AllowInsecureTls` flag) is a temporary override; never leave it on. Do not commit proxy addresses, certificate paths, cookies or OAuth codes, and redact logs before sharing them. `scripts/start-antigravity-with-proxyman.ps1` targets the installed official Antigravity client, not this app.
- **Error reporting.** Sentry reports (they need `SENTRY_DSN`) are gated by the `error_reporting_enabled` setting, which `DEFAULT_APP_CONFIG` ships as `true`; turn it off in Settings to opt out. The Windows user-name segment is masked in reported exception messages.
Supported versions and how to report a vulnerability: [`SECURITY.md`](SECURITY.md).
## 📚 Documentation
- [`docs/cloud_features.md`](docs/cloud_features.md): account pool, quota monitoring and auto-switch design.
- [`docs/proxyman-install.md`](docs/proxyman-install.md) and [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): TLS inspection setup (Windows).
- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): OpenCode custom-endpoint integration (in Portuguese).
- [`cli/README.md`](cli/README.md): the Python command-line tool.
- [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), [`CHANGELOG.md`](CHANGELOG.md), [`LICENSE`](LICENSE), [`LICENSE-MIT`](LICENSE-MIT).
- Translations: [Português](README.pt-BR.md), [中文](README.zh-CN.md), [Español](README.es.md).
### 🗂️ Structure
```text
src/
├── components/ # UI (proxy/, usage/, ui/ primitives)
├── ipc/ # oRPC routers (account, cloud, config, gateway, usage...)
├── server/ # NestJS proxy gateway (modules: proxy, usage)
├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService
├── routes/ # index, usage, proxy, settings
├── utils/ # paths, logger, sensitiveDataMasking
└── tests/ # unit tests (Vitest) and E2E (Playwright)
cli/ # separate Python CLI for account switching and quota checks
docs/ # design notes and Proxyman guides
scripts/ # setup-dev, build-windows, generate-assets
```
### 🧪 Scripts
| Command | What it does |
|---|---|
| `pnpm start` | Run the app in dev mode (`electron-forge start`, with `DEBUG=electron-forge:*`). |
| `pnpm run dev` | Same as `start`. |
| `pnpm run package` | Package the app with Electron Forge, without building installers. |
| `pnpm run make` | Build installers/packages for the current platform. |
| `pnpm run make:win` | Windows build helper: extracts WiX from `wix314-binaries.zip`, adds it to `PATH`, runs `electron-forge make`. |
| `pnpm run publish` | Publish through Electron Forge. |
| `pnpm run setup` | Run `scripts/setup-dev.js`: detect the native toolchain and install or guide the setup. |
| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; runs automatically after `pnpm install`. |
| `pnpm run lint` | ESLint over the repo. |
| `pnpm run format` | Prettier check. |
| `pnpm run format:write` | Prettier write. |
| `pnpm test` | Vitest unit tests (`vitest run`). |
| `pnpm run test:watch` | Vitest in watch mode. |
| `pnpm run test:unit` | Vitest (default mode). |
| `pnpm run test:e2e` | Playwright E2E tests. |
| `pnpm run test:all` | Unit tests, then Playwright. |
| `pnpm run type-check` | `tsc --noEmit`. |
## FAQ