Files
gemini-nexus/README.es.md
T
evandro e3652f43f5
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
docs(readme): padrão SaaS
2026-11-16 00:02:29 -03:00

17 KiB

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

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.

⚡ Inicio rápido

Todavía no hay descargas precompiladas en la página de Releases de Gitea (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)
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:

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

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.

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

💻 Documentación y desarrollo

Estructura

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.

¿Puedo usarlo comercialmente?

Revisa antes la 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). 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).

🤝 Contribuir

Lee CONTRIBUTING.md y CODE_OF_CONDUCT.md. Las versiones las genera semantic-release a partir de Conventional Commits. Antes de abrir un PR, esto tiene que pasar:

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

📄 Licencia

Licencia mixta: el código heredado de AntigravityManager (de Draculabo) es CC BY-NC-SA 4.0 (no comercial, compartir igual); todo el código nuevo es 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.