Gemini Nexus: gateway de escritorio que agrupa cuentas de Google tras una API local compatible con OpenAI y Anthropic en http://localhost:8045/v1, y cambia de cuenta cuando se agota la cuota ![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)

Inicio rápido · Docs · Issues

English · Português · 中文 · Español
## 📸 Capturas de pantalla

Página Accounts: una cuenta de Google en el pool con barras de cuota por modelo, el interruptor Auto-Switch y el contador de cuota global

Más capturas: uso, proxy, enrutamiento, docs, conexiones, ajustes

Analítica de uso

Monitor del proxy

Configuración de enrutamiento

Documentación

Conexiones activas

Ajustes

## 🎯 Características Trabajar con IDEs con IA sobre una sola cuenta de Google significa cuota que se agota, cambios de cuenta manuales y ninguna visibilidad de lo que el proxy envía hacia arriba. Gemini Nexus reúne todas las cuentas en un pool y las sirve por un único endpoint local.
Un endpoint local
POST /v1/chat/completions (OpenAI), POST /v1/messages (Anthropic), GET /v1/models y GET /v1/models/capabilities, para que Cursor, Windsurf, OpenCode, Claude Code y clientes similares puedan conectarse. Los nombres de modelo se mapean con custom_mapping y anthropic_mapping.
Pool de cuentas
Cuentas de Google añadidas por OAuth, cada una con su estado (Active, Rate Limited, Expired), hora del último uso y una URL de proxy opcional por cuenta.
Cambio automático
CloudMonitorService consulta la cuota cada 5 minutos y AutoSwitchService pasa a otra cuenta cuando la cuota baja del 5 % o la cuenta sufre rate limit.
Planificación con circuit breaker
cache-first, balance (por defecto) o performance-first, con circuit breaker por cuenta (backoff por defecto 60 s → 5 min → 30 min → 2 h).
Uso y coste
Consumo de tokens por cuenta y por modelo, gráficos de prompt y completion y estimación de coste con precios por modelo editables.
Inspector de tráfico
Latencia, estado y modelo de cada petición, replay de peticiones registradas, snippets cURL y Python generados y un Quick Setup para IDEs.
Las credenciales guardadas se cifran con AES-256-GCM bajo una clave maestra en el llavero del sistema (ver [Modelo de seguridad](#modelo-de-seguridad)). ## Cómo funciona 1. **Añade cuentas.** Inicia sesión con Google OAuth en la página Accounts. Los tokens se cifran antes de llegar a SQLite. 2. **Apunta tu IDE al proxy.** Activa el proxy en la página Proxy (viene apagado) y usa `http://localhost:8045/v1` con la API key que se muestra allí, en formato OpenAI o Anthropic. 3. **Nexus enruta cada petición.** El token manager elige una cuenta según el modo de planificación y el estado del circuit breaker, llama a las APIs upstream de Google con el token OAuth de esa cuenta, y el cambio automático actúa cuando la cuota baja del 5 % o una cuenta sufre rate limit. El flujo completo, con los componentes implicados, está en [Arquitectura](#arquitectura). ## ⚡ Inicio rápido Todavía no hay descargas precompiladas en la página de [Releases de Gitea](https://git.evandro.dev.br/evandro/gemini-nexus/releases) (los workflows de release en `.github/workflows/` apuntan a GitHub), así que compila desde el código fuente. | Herramienta | Versión mínima | |---|---| | Node.js | 20+ (recomendado en `AGENTS.md`; `.nvmrc` fija 22.17.1) | | pnpm | 10.11.0 (`packageManager`; el lockfile es `pnpm-lock.yaml`) | | Toolchain nativa | necesaria para `better-sqlite3` y `keytar`: Visual Studio 2022 Build Tools (C++) en Windows, Xcode Command Line Tools en macOS, `build-essential` + `python3` + `libsecret-1-dev` en Ubuntu (`base-devel` + `python` + `libsecret` en Arch) | ```bash git clone https://git.evandro.dev.br/evandro/gemini-nexus.git cd gemini-nexus pnpm install # el postinstall ejecuta scripts/setup-dev.js --check-only para verificar la toolchain pnpm start # modo dev (Electron + Vite HMR) pnpm run make # instaladores/paquetes para la plataforma actual pnpm run make:win # Windows: extrae WiX de wix314-binaries.zip y luego ejecuta make ``` Después añade al menos una cuenta, activa el proxy (viene apagado) y apunta tu IDE a él: ```text API Base URL: http://localhost:8045/v1 (por defecto, configurable en la página Proxy; los builds de desarrollo usan 8046) API Key: (cópiala de la página Proxy de la app) Model: gemini-3-flash (o cualquier modelo mapeado) ``` > [!WARNING] > Los builds no están firmados. Si Windows muestra "Windows protegió su PC", haz clic en **Más información → Ejecutar de todas formas**. No hay `.env.example` y ninguna variable es obligatoria. Variables opcionales que lee el código o que describen los docs: | Variable | Obligatoria | Descripción | |---|---|---| | `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | No | Envía las peticiones salientes de la app por un proxy local (ver inspección TLS en [Modelo de seguridad](#modelo-de-seguridad)). | | `NODE_EXTRA_CA_CERTS` | No | Certificado de CA adicional para el TLS del lado Node al inspeccionar tráfico. | | `SENTRY_DSN` | No | DSN de Sentry usado cuando el envío de errores está activado. | ## 🛠️ Stack | Capa | Tecnología | |---|---| | Shell de escritorio | Electron 41, Electron Forge, Vite | | Interfaz | React 19, TypeScript, Tailwind CSS 4, Radix UI, gráficos Nivo, i18next | | Flujo de datos de la app | TanStack Router y Query, oRPC sobre IPC de Electron | | Proxy | NestJS 11 sobre Fastify | | Almacenamiento | SQLite (better-sqlite3 + Drizzle ORM), llavero del sistema vía `keytar` | | Logs y errores | Winston (archivos rotativos), Sentry (opcional) | | Pruebas | Vitest, Playwright | ## Arquitectura ```mermaid flowchart LR C["Cliente: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["Proxy NestJS, puerto 8045"] P --> S["Planificador de cuentas y circuit breaker"] S -->|"cuenta Google OAuth"| G["APIs upstream de Google"] M["CloudMonitor y AutoSwitch, cuota cada 5 min"] -->|"consulta de cuota"| G S -->|"lee cuentas"| DB[("SQLite: better-sqlite3 y Drizzle")] M --> DB K["AES-256-GCM, clave maestra en el llavero del sistema"] -->|"cifra tokens"| DB ``` 1. Un cliente envía peticiones en formato OpenAI o Anthropic al proxy NestJS (Fastify, escuchando en `0.0.0.0`). 2. El guard del proxy comprueba la API key cuando hay una configurada; con la clave vacía el proxy funciona en modo abierto. 3. El token manager elige una cuenta según el modo de planificación y el estado del circuit breaker de cada cuenta, y llama a las APIs upstream de Google con el token OAuth de esa cuenta. 4. `CloudMonitorService` consulta la cuota cada 5 minutos y `AutoSwitchService` cambia la cuenta activa cuando la cuota está por debajo del 5 % o la cuenta sufre rate limit. 5. El renderer React 19 (TanStack Router y Query) habla con el proceso principal mediante oRPC sobre IPC; cuentas, uso y ajustes viven en SQLite (better-sqlite3 + Drizzle). Notas de diseño: [`docs/cloud_features.md`](docs/cloud_features.md). ## Modelo de seguridad Gemini Nexus guarda tokens OAuth de varias cuentas y reenvía tráfico hacia arriba, así que el manejo de credenciales es el núcleo del diseño. Todo lo de abajo está implementado en este repositorio; los límites se indican donde existen. - **Almacenamiento y aislamiento de credenciales.** `token_json` y `quota_json` se cifran con AES-256-GCM (IV único por operación, autenticado) antes de llegar a SQLite. La clave maestra vive en el almacén de credenciales del sistema vía `keytar` (Administrador de credenciales de Windows, Keychain de macOS, Secret Service/libsecret en Linux), nunca en un archivo plano. Las filas heredadas en texto plano se migran al arrancar. Las cuentas se guardan en su propia base de datos (`cloud_accounts.db`), independiente de la base local del IDE. - **Enmascarado de logs.** Claves como `token`, `refresh_token`, `api_key`, `authorization`, `cookie` y `client_secret` se sustituyen por `[REDACTED]` antes de registrarse ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); el logger de tráfico también oculta las cabeceras `authorization`, `x-api-key` y `cookie`. - **Registro de peticiones, no pista de auditoría.** Winston escribe logs de API, tráfico y app en archivos rotativos (log de API: 30 días, 50 MB por archivo). Son logs operativos, no una pista de auditoría a prueba de manipulación; los archivos `*-audit.json` son el control de rotación de `winston-daily-rotate-file`. - **Acceso al proxy.** El proxy viene apagado. Una vez activado escucha en `0.0.0.0`, y las peticiones solo se autentican cuando `api_key` no está vacía (vacía significa modo abierto). Define una clave y mantenla privada. - **Inspección TLS (solo para depurar).** [`docs/proxyman-install.md`](docs/proxyman-install.md) y [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explican cómo leer el tráfico HTTPS de la app con Proxyman: confiar en su CA raíz, definir las variables de proxy y `NODE_EXTRA_CA_CERTS` y después iniciar la app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (y el flag `-AllowInsecureTls` del script) es un ajuste temporal; nunca lo dejes activado. No hagas commit de direcciones de proxy, rutas de certificados, cookies ni códigos OAuth, y oculta datos de los logs antes de compartirlos. `scripts/start-antigravity-with-proxyman.ps1` apunta al cliente oficial de Antigravity instalado, no a esta app. - **Envío de errores.** Los informes de Sentry (necesitan `SENTRY_DSN`) dependen del ajuste `error_reporting_enabled`, que `DEFAULT_APP_CONFIG` trae como `true`; desactívalo en Settings para no enviarlos. El segmento con el nombre de usuario de Windows se enmascara en los mensajes de excepción enviados. Versiones soportadas y cómo reportar una vulnerabilidad: [`SECURITY.md`](SECURITY.md). ## 💻 Documentación y desarrollo - [`docs/cloud_features.md`](docs/cloud_features.md): diseño del pool de cuentas, la monitorización de cuota y el cambio automático. - [`docs/proxyman-install.md`](docs/proxyman-install.md) y [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): configuración de la inspección TLS (Windows). - [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): integración con endpoint personalizado de OpenCode (en portugués). - [`cli/README.md`](cli/README.md): la herramienta de línea de comandos en Python. - [`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). - Traducciones: [English](README.md), [Português](README.pt-BR.md), [中文](README.zh-CN.md). ### Estructura ```text src/ ├── components/ # UI (proxy/, usage/, primitivas ui/) ├── ipc/ # routers oRPC (account, cloud, config, gateway, usage...) ├── server/ # gateway proxy NestJS (módulos: proxy, usage) ├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService ├── routes/ # index, usage, proxy, settings ├── utils/ # paths, logger, sensitiveDataMasking └── tests/ # pruebas unitarias (Vitest) y E2E (Playwright) cli/ # CLI de Python aparte para cambiar de cuenta y consultar cuota docs/ # notas de diseño y guías de Proxyman scripts/ # setup-dev, build-windows, generate-assets ``` ### Scripts | Comando | Qué hace | |---|---| | `pnpm start` | Ejecuta la app en modo dev (`electron-forge start`, con `DEBUG=electron-forge:*`). | | `pnpm run dev` | Igual que `start`. | | `pnpm run package` | Empaqueta la app con Electron Forge, sin generar instaladores. | | `pnpm run make` | Genera instaladores/paquetes para la plataforma actual. | | `pnpm run make:win` | Helper de build en Windows: extrae WiX de `wix314-binaries.zip`, lo añade al `PATH` y ejecuta `electron-forge make`. | | `pnpm run publish` | Publica mediante Electron Forge. | | `pnpm run setup` | Ejecuta `scripts/setup-dev.js`: detecta la toolchain nativa e instala o guía la configuración. | | `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; se ejecuta solo tras `pnpm install`. | | `pnpm run lint` | ESLint sobre el repositorio. | | `pnpm run format` | Comprobación de Prettier. | | `pnpm run format:write` | Prettier con escritura. | | `pnpm test` | Pruebas unitarias Vitest (`vitest run`). | | `pnpm run test:watch` | Vitest en modo watch. | | `pnpm run test:unit` | Vitest (modo por defecto). | | `pnpm run test:e2e` | Pruebas E2E con Playwright. | | `pnpm run test:all` | Pruebas unitarias y después Playwright. | | `pnpm run type-check` | `tsc --noEmit`. | ## ❓ Preguntas frecuentes
Windows muestra "Windows protegió su PC". ¿Es normal? Sí. Los builds no están firmados. Haz clic en **Más información → Ejecutar de todas formas**.
Mi IDE no llega al proxy. El proxy viene apagado: actívalo en la página Proxy. El puerto por defecto es `8045` (`8046` en builds de desarrollo) y se puede cambiar allí. Copia la API key de esa misma página y comprueba que haya al menos una cuenta en el pool.
¿Necesito una API key? Con `api_key` vacía el proxy funciona en modo abierto. Una vez activado escucha en `0.0.0.0`, así que define una clave y mantenla privada.
¿Puedo usar modelos Claude? Sí, mediante el mapeo de modelos sobre las cuentas de Google del pool, no con cuentas de Claude separadas.
¿Dónde se guardan mis tokens? En un `cloud_accounts.db` aparte, con `token_json` y `quota_json` cifrados con AES-256-GCM. La clave maestra vive en el almacén de credenciales del sistema vía `keytar`. Detalles en [Modelo de seguridad](#modelo-de-seguridad).
¿Puedo usarlo comercialmente? Revisa antes la [Licencia](#-licencia): el código heredado de AntigravityManager es CC BY-NC-SA 4.0 (no comercial) y el código nuevo es MIT.
## Limitaciones y próximos pasos - El acceso upstream pasa por los endpoints `v1internal` de Cloud Code de Google y por scopes OAuth ([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts)). Son APIs internas, sin documentar, que pueden cambiar sin aviso. El proyecto no es oficial y no está afiliado a Google ni a Anthropic. - Las cuentas se añaden por Google OAuth; a los modelos Claude se llega mediante el mapeo de modelos, no con cuentas de Claude separadas. - Las pruebas end-to-end no se ejecutan en CI (Electron necesita un entorno gráfico); ejecuta `pnpm run test:e2e` en local. - El MSI de Windows solo se genera cuando el WiX Toolset está disponible en la máquina de build; si no, el artefacto de Windows es el ZIP. - Los workflows de `.github/workflows/` están escritos para GitHub (llaman al CLI `gh` y al publicador de releases de GitHub), por eso este README no muestra badge de CI. - Próximo paso declarado por el proyecto: migrar el código original restante a MIT (ver la [Licencia](#-licencia)). ## 🤝 Contribuir Lee [`CONTRIBUTING.md`](CONTRIBUTING.md) y [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Las versiones las genera semantic-release a partir de Conventional Commits. Antes de abrir un PR, esto tiene que pasar: ```bash pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test ``` ## 📄 Licencia Licencia mixta: el código heredado de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (de Draculabo) es [CC BY-NC-SA 4.0](LICENSE) (no comercial, compartir igual); todo el código nuevo es [MIT](LICENSE-MIT). El proyecto está migrando a MIT a medida que se reescribe el código original restante, así que revisa ambos archivos antes de cualquier uso comercial. ---
Logo de Gemini Nexus

Gemini Nexus en Gitea · Reportar un problema · Inicio rápido