



Inicio rápido · Docs · Issues
English · Português · 中文 · Español
## 📸 Capturas de pantalla
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