docs(readme): padrão SaaS
Lint / ESLint Check (pull_request) Failing after 8m20s
Check formatting / Prettier Format Check (pull_request) Failing after 8m37s
Tests / Unit Tests (pull_request) Successful in 13m53s
Tests / Type Check (pull_request) Successful in 11m31s

This commit is contained in:
evandro committed 2026-11-16 00:02:29 -03:00
1 parent 2a5d482c52
commit e3652f43f5
14 files changed
+982 -894

No files matched your search

+122 -50
View File
@@ -1,47 +1,24 @@
<div align="center">
<img src="docs/assets/logo.png" width="110" alt="Gemini Nexus logo">
<h1>Gemini Nexus</h1>
<p><strong>Desktop gateway that pools Google accounts behind a local OpenAI/Anthropic-compatible API, with encrypted credentials and auto-switching.</strong></p>
<a href="#-quickstart">Quickstart</a> ·
<a href="#-architecture">Architecture</a> ·
<a href="#-security-model">Security</a> ·
<a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a>
<img src="assets/readme/hero.png" width="100%" alt="Gemini Nexus: a desktop gateway that pools Google accounts behind one local OpenAI- and Anthropic-compatible API at http://localhost:8045/v1, switching accounts when quota runs low">
![Stack](https://img.shields.io/badge/Stack-Electron_41_%C2%B7_React_19-47848F?logo=electron&logoColor=white)
![Status](https://img.shields.io/badge/status-v0.15.3_active-brightgreen)
![License](https://img.shields.io/badge/license-CC_BY--NC--SA_4.0_%2B_MIT-lightgrey)
<p><strong><a href="#-quickstart">Quickstart</a></strong> · <a href="#-documentation">Docs</a> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a></p>
<sub>English · <a href="README.pt-BR.md">Português</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.es.md">Español</a></sub>
</div>
<hr />
## 📌 The problem
Working with AI-powered IDEs and coding tools on a single Google account means quota that runs out, manual account switching, no idea how many tokens you spent, and no view of what the proxy actually sends upstream. Gemini Nexus keeps all accounts in one pool, switches between them automatically and shows the traffic.
## ✨ What it does
- **Pools** Google accounts added through OAuth, with status (Active, Rate Limited, Expired), last-used time and an optional per-account proxy URL.
- **Switches** accounts automatically when quota drops below 5 % or an account is rate-limited; `CloudMonitorService` polls quota every 5 minutes.
- **Schedules** requests across the pool in `cache-first`, `balance` (default) or `performance-first` mode, with a per-account circuit breaker (default backoff 60 s → 5 min → 30 min → 2 h).
- **Serves** `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.
- **Maps** requested model names to upstream models through the `custom_mapping` and `anthropic_mapping` settings; request timeout defaults to 120 s.
- **Tracks** token usage per account and model, charts prompt and completion tokens, and estimates cost with editable per-model pricing.
- **Inspects** traffic (latency, status, model), replays logged requests and generates cURL and Python snippets plus an IDE Quick Setup.
- **Protects** stored credentials with AES-256-GCM and an OS-keychain master key (see [Security model](#-security-model)).
## 🖼️ Demo
<p align="center"><img src="docs/assets/main.png" width="100%" alt="Accounts page: a Google account in the pool with per-model quota bars, the Auto-Switch toggle and the global quota counter"></p>
<details>
<summary>Screenshots</summary>
<summary>More screenshots: usage, proxy, routing, docs, connections, settings</summary>
<p align="center"><img src="docs/assets/main.png" alt="Main dashboard" width="80%"></p>
<p align="center"><img src="docs/assets/2usage.png" alt="Usage analytics" width="80%"></p>
<p align="center"><img src="docs/assets/3proxy.png" alt="Proxy monitor" width="80%"></p>
<p align="center"><img src="docs/assets/4routing.png" alt="Routing config" width="80%"></p>
@@ -51,20 +28,38 @@ Working with AI-powered IDEs and coding tools on a single Google account means q
</details>
## ✨ What it does
Working with AI-powered IDEs on a single Google account means quota that runs out, manual account switching and no view of what the proxy sends upstream. Gemini Nexus keeps every account in one pool and serves them through one local endpoint.
<table>
<tr>
<td width="50%" valign="top"><b>One local endpoint</b><br><code>POST /v1/chat/completions</code> (OpenAI), <code>POST /v1/messages</code> (Anthropic), <code>GET /v1/models</code> and <code>GET /v1/models/capabilities</code>, so Cursor, Windsurf, OpenCode, Claude Code and similar clients can connect. Model names are mapped through <code>custom_mapping</code> and <code>anthropic_mapping</code>.</td>
<td width="50%" valign="top"><b>Account pool</b><br>Google accounts added through OAuth, each with its status (Active, Rate Limited, Expired), last-used time and an optional per-account proxy URL.</td>
</tr>
<tr>
<td width="50%" valign="top"><b>Auto-switch</b><br><code>CloudMonitorService</code> polls quota every 5 minutes and <code>AutoSwitchService</code> moves to another account when quota drops below 5 % or the account is rate-limited.</td>
<td width="50%" valign="top"><b>Scheduling with a circuit breaker</b><br><code>cache-first</code>, <code>balance</code> (default) or <code>performance-first</code>, with a per-account circuit breaker (default backoff 60 s → 5 min → 30 min → 2 h).</td>
</tr>
<tr>
<td width="50%" valign="top"><b>Usage and cost</b><br>Token usage per account and model, prompt and completion charts, and cost estimates from editable per-model pricing.</td>
<td width="50%" valign="top"><b>Traffic inspector</b><br>Latency, status and model for each request, replay of logged requests, generated cURL and Python snippets, plus an IDE Quick Setup.</td>
</tr>
</table>
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
**Use a release.** Download the build for your platform from [Releases](https://git.evandro.dev.br/evandro/gemini-nexus/releases), open the app, 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**.
**Build from source.**
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 |
|---|---|
@@ -81,6 +76,17 @@ 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 |
@@ -89,6 +95,18 @@ There is no `.env.example` and no variable is required. Optional variables read
| `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
@@ -121,7 +139,16 @@ Gemini Nexus holds OAuth tokens for several accounts and forwards traffic upstre
Supported versions and how to report a vulnerability: [`SECURITY.md`](SECURITY.md).
## 🗂️ Structure
## 📚 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/
@@ -137,7 +164,7 @@ docs/ # design notes and Proxyman guides
scripts/ # setup-dev, build-windows, generate-assets
```
## 🧪 Scripts
### 🧪 Scripts
| Command | What it does |
|---|---|
@@ -159,14 +186,49 @@ scripts/ # setup-dev, build-windows, generate-assets
| `pnpm run test:all` | Unit tests, then Playwright. |
| `pnpm run type-check` | `tsc --noEmit`. |
## 📚 Documentation
## FAQ
- [`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).
<details>
<summary><b>Windows shows "Windows protected your PC". Is that expected?</b></summary>
Yes. Builds are not code-signed. Click **More info → Run anyway**.
</details>
<details>
<summary><b>My IDE cannot reach the proxy.</b></summary>
The proxy is disabled by default: enable it on the Proxy page. The default port is `8045` (`8046` in development builds) and can be changed there. Copy the API key from the same page and make sure at least one account is in the pool.
</details>
<details>
<summary><b>Do I need an API key?</b></summary>
With an empty `api_key` the proxy runs in open mode. Once enabled it listens on `0.0.0.0`, so set a key and keep it private.
</details>
<details>
<summary><b>Can I use Claude models?</b></summary>
Yes, through model mapping on the Google accounts in the pool, not through separate Claude accounts.
</details>
<details>
<summary><b>Where are my tokens stored?</b></summary>
In a separate `cloud_accounts.db`, with `token_json` and `quota_json` encrypted by AES-256-GCM. The master key lives in the OS credential store through `keytar`. Details in [Security model](#-security-model).
</details>
<details>
<summary><b>Can I use it commercially?</b></summary>
Check the [License](#-license) first: code inherited from AntigravityManager is CC BY-NC-SA 4.0 (non-commercial), new code is MIT.
</details>
## 🛣️ Limitations and next steps
@@ -188,3 +250,13 @@ pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
## 📄 License
Mixed licensing: code inherited from [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (by Draculabo) is [CC BY-NC-SA 4.0](LICENSE) (non-commercial, share-alike); all new code is [MIT](LICENSE-MIT). The project is migrating to MIT as the remaining original code is rewritten, so check both files before any commercial use.
---
<div align="center">
<img src="docs/assets/logo.png" width="56" alt="Gemini Nexus logo">
<p><strong><a href="https://git.evandro.dev.br/evandro/gemini-nexus">Gemini Nexus on Gitea</a></strong> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Report an issue</a> · <a href="#-quickstart">Quickstart</a></p>
</div>