evandro e3652f43f5
Tests / Type Check (pull_request) In progress
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
docs(readme): padrão SaaS
2026-11-16 00:02:29 -03:00
2026-05-02 00:32:21 -03:00
2026-11-16 00:02:29 -03:00
2026-05-02 00:32:21 -03:00
2026-05-02 00:32:21 -03:00
2026-05-02 05:13:21 +00:00
2026-05-02 00:32:21 -03:00
2026-05-02 05:13:21 +00:00
2026-11-16 00:02:29 -03:00
2026-11-16 00:02:29 -03:00
2026-11-16 00:02:29 -03:00
2026-11-16 00:02:29 -03:00
2026-05-02 00:32:21 -03:00

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 Status License

Quickstart · Docs · Issues

English · Português · 中文 · Español

🖼️ Demo

Accounts page: a Google account in the pool with per-model quota bars, the Auto-Switch toggle and the global quota counter

More screenshots: usage, proxy, routing, docs, connections, settings

Usage analytics

Proxy monitor

Routing config

Documentation

Active connections

Settings

✨ 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.

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).

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.

🚀 Quickstart

There are no prebuilt downloads on the Gitea 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)
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:

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).
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

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.

🔒 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); 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 and 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.

📚 Documentation

🗂️ Structure

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

Windows shows "Windows protected your PC". Is that expected?

Yes. Builds are not code-signed. Click More info → Run anyway.

My IDE cannot reach the proxy.

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.

Do I need an API key?

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.

Can I use Claude models?

Yes, through model mapping on the Google accounts in the pool, not through separate Claude accounts.

Where are my tokens stored?

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.

Can I use it commercially?

Check the License first: code inherited from AntigravityManager is CC BY-NC-SA 4.0 (non-commercial), new code is MIT.

🛣️ Limitations and next steps

  • Upstream access goes through Google's v1internal Cloud Code endpoints and OAuth scopes (src/services/GoogleAPIService.ts). These are internal, undocumented APIs and may change without notice. The project is unofficial and not affiliated with Google or Anthropic.
  • Accounts are added through Google OAuth; Claude models are reached through model mapping, not through separate Claude accounts.
  • End-to-end tests are not run in CI (Electron needs a graphical environment); run pnpm run test:e2e locally.
  • The Windows MSI is only produced when the WiX Toolset is available on the build machine; otherwise the Windows artifact is the ZIP.
  • The workflows in .github/workflows/ are written for GitHub (they call the gh CLI and the GitHub release publisher), so this README shows no CI badge.
  • Next step stated by the project: migrate the remaining original code to MIT (see License).

🤝 Contributing

Read CONTRIBUTING.md and CODE_OF_CONDUCT.md. Releases are versioned by semantic-release from Conventional Commits. Before opening a PR, these must pass:

pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test

📄 License

Mixed licensing: code inherited from AntigravityManager (by Draculabo) is CC BY-NC-SA 4.0 (non-commercial, share-alike); all new code is MIT. The project is migrating to MIT as the remaining original code is rewritten, so check both files before any commercial use.


S
Description
Gateway local que unifica contas Gemini e Claude numa API compatível com OpenAI e Anthropic
Readme CC-BY-SA-4.0
84 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 88.2%
Python 9.5%
JavaScript 1.7%
CSS 0.4%
PowerShell 0.2%