Gemini Nexus: gateway desktop que reúne contas Google atrás de uma API local compatível com OpenAI e Anthropic em http://localhost:8045/v1, trocando de conta quando a cota acaba ![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)

Início rápido · Docs · Issues

English · Português · 中文 · Español
## 📸 Screenshots

Página Accounts: uma conta Google no pool com barras de cota por modelo, o botão Auto-Switch e o contador de cota global

Mais screenshots: uso, proxy, roteamento, docs, conexões, configurações

Analytics de uso

Monitor do proxy

Configuração de roteamento

Documentação

Conexões ativas

Configurações

## 🎯 Funcionalidades Usar IDEs com IA numa única conta Google significa cota que acaba, troca manual de conta e nenhuma visão do que o proxy manda para cima. O Gemini Nexus mantém todas as contas num pool e as serve por um único endpoint local.
Um endpoint local
POST /v1/chat/completions (OpenAI), POST /v1/messages (Anthropic), GET /v1/models e GET /v1/models/capabilities, para que Cursor, Windsurf, OpenCode, Claude Code e clientes parecidos se conectem. Os nomes de modelo são mapeados por custom_mapping e anthropic_mapping.
Pool de contas
Contas Google adicionadas via OAuth, cada uma com status (Active, Rate Limited, Expired), horário do último uso e uma URL de proxy opcional por conta.
Troca automática
O CloudMonitorService consulta a cota a cada 5 minutos e o AutoSwitchService passa para outra conta quando a cota cai abaixo de 5 % ou a conta sofre rate limit.
Agendamento com circuit breaker
cache-first, balance (padrão) ou performance-first, com circuit breaker por conta (backoff padrão 60 s → 5 min → 30 min → 2 h).
Uso e custo
Consumo de tokens por conta e por modelo, gráficos de prompt e completion e estimativa de custo com preço por modelo editável.
Inspetor de tráfego
Latência, status e modelo de cada requisição, replay de requisições registradas, snippets cURL e Python gerados e um Quick Setup para IDEs.
As credenciais salvas são criptografadas com AES-256-GCM sob uma chave mestra guardada no chaveiro do sistema (veja [Modelo de segurança](#modelo-de-segurança)). ## Como funciona 1. **Adicione contas.** Entre com Google OAuth na página Accounts. Os tokens são criptografados antes de chegar ao SQLite. 2. **Aponte a IDE para o proxy.** Ative o proxy na página Proxy (ele vem desligado) e use `http://localhost:8045/v1` com a API key mostrada ali, no formato OpenAI ou Anthropic. 3. **O Nexus roteia cada requisição.** O token manager escolhe uma conta pelo modo de agendamento e pelo estado do circuit breaker, chama as APIs upstream do Google com o token OAuth dessa conta, e a troca automática entra em ação quando a cota cai abaixo de 5 % ou uma conta sofre rate limit. O fluxo completo, com os componentes envolvidos, está em [Arquitetura](#arquitetura). ## ⚡ Início rápido Ainda não há downloads prontos na página de [Releases do Gitea](https://git.evandro.dev.br/evandro/gemini-nexus/releases) (os workflows de release em `.github/workflows/` são para o GitHub), então compile pelo código-fonte. | Ferramenta | Versão mínima | |---|---| | Node.js | 20+ (recomendado no `AGENTS.md`; o `.nvmrc` fixa 22.17.1) | | pnpm | 10.11.0 (`packageManager`; o lockfile é `pnpm-lock.yaml`) | | Toolchain nativa | exigida por `better-sqlite3` e `keytar`: Visual Studio 2022 Build Tools (C++) no Windows, Xcode Command Line Tools no macOS, `build-essential` + `python3` + `libsecret-1-dev` no Ubuntu (`base-devel` + `python` + `libsecret` no Arch) | ```bash git clone https://git.evandro.dev.br/evandro/gemini-nexus.git cd gemini-nexus pnpm install # o postinstall roda scripts/setup-dev.js --check-only para conferir a toolchain pnpm start # modo dev (Electron + Vite HMR) pnpm run make # instaladores/pacotes para a plataforma atual pnpm run make:win # Windows: extrai o WiX de wix314-binaries.zip e roda o make ``` Depois adicione pelo menos uma conta, ative o proxy (ele vem desligado) e aponte sua IDE para ele: ```text API Base URL: http://localhost:8045/v1 (padrão, configurável na página Proxy; builds de desenvolvimento usam 8046) API Key: (copie da página Proxy no app) Model: gemini-3-flash (ou qualquer modelo mapeado) ``` > [!WARNING] > Os builds não são assinados. Se o Windows mostrar "O Windows protegeu o seu computador", clique em **Mais informações → Executar mesmo assim**. Não existe `.env.example` e nenhuma variável é obrigatória. Variáveis opcionais lidas pelo código ou descritas nos docs: | Variável | Obrigatória | Descrição | |---|---|---| | `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Não | Encaminha as requisições de saída do app por um proxy local (veja inspeção TLS em [Modelo de segurança](#modelo-de-segurança)). | | `NODE_EXTRA_CA_CERTS` | Não | Certificado de CA extra para o TLS do lado Node ao inspecionar tráfego. | | `SENTRY_DSN` | Não | DSN do Sentry usado quando o envio de erros está ativo. | ## 🛠️ Stack | Camada | Tecnologia | |---|---| | Shell desktop | Electron 41, Electron Forge, Vite | | Interface | React 19, TypeScript, Tailwind CSS 4, Radix UI, gráficos Nivo, i18next | | Fluxo de dados do app | TanStack Router e Query, oRPC sobre IPC do Electron | | Proxy | NestJS 11 sobre Fastify | | Armazenamento | SQLite (better-sqlite3 + Drizzle ORM), chaveiro do sistema via `keytar` | | Logs e erros | Winston (arquivos rotativos), Sentry (opcional) | | Testes | Vitest, Playwright | ## Arquitetura ```mermaid flowchart LR C["Cliente: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["Proxy NestJS, porta 8045"] P --> S["Agendador de contas e circuit breaker"] S -->|"conta Google OAuth"| G["APIs upstream do Google"] M["CloudMonitor e AutoSwitch, cota a cada 5 min"] -->|"consulta de cota"| G S -->|"lê contas"| DB[("SQLite: better-sqlite3 e Drizzle")] M --> DB K["AES-256-GCM, chave mestra no chaveiro do sistema"] -->|"criptografa tokens"| DB ``` 1. Um cliente envia requisições no formato OpenAI ou Anthropic para o proxy NestJS (Fastify, escutando em `0.0.0.0`). 2. O guard do proxy confere a API key quando há uma configurada; com a chave vazia o proxy roda em modo aberto. 3. O token manager escolhe uma conta segundo o modo de agendamento e o estado do circuit breaker de cada conta, e chama as APIs upstream do Google com o token OAuth dessa conta. 4. O `CloudMonitorService` consulta a cota a cada 5 minutos e o `AutoSwitchService` troca a conta ativa quando a cota está abaixo de 5 % ou a conta sofre rate limit. 5. O renderer React 19 (TanStack Router e Query) conversa com o processo principal via oRPC sobre IPC; contas, uso e configurações ficam no SQLite (better-sqlite3 + Drizzle). Notas de design: [`docs/cloud_features.md`](docs/cloud_features.md). ## Modelo de segurança O Gemini Nexus guarda tokens OAuth de várias contas e repassa tráfego para cima, então o tratamento de credenciais é o centro do design. Tudo abaixo está implementado neste repositório; os limites aparecem onde existem. - **Armazenamento e isolamento de credenciais.** `token_json` e `quota_json` são criptografados com AES-256-GCM (IV único por operação, autenticado) antes de chegar ao SQLite. A chave mestra fica no cofre de credenciais do sistema via `keytar` (Gerenciador de Credenciais do Windows, Keychain do macOS, Secret Service/libsecret no Linux), nunca num arquivo comum. Linhas legadas em texto puro são migradas na inicialização. As contas ficam num banco próprio (`cloud_accounts.db`), separado do banco local da IDE. - **Mascaramento de logs.** Chaves como `token`, `refresh_token`, `api_key`, `authorization`, `cookie` e `client_secret` são trocadas por `[REDACTED]` antes de ir para o log ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); o logger de tráfego também oculta os headers `authorization`, `x-api-key` e `cookie`. - **Log de requisições, não trilha de auditoria.** O Winston grava logs de API, tráfego e app em arquivos rotativos (log de API: 30 dias, 50 MB por arquivo). São logs operacionais, não uma trilha de auditoria à prova de adulteração; os arquivos `*-audit.json` são o controle de rotação do `winston-daily-rotate-file`. - **Acesso ao proxy.** O proxy vem desligado. Quando ativado, escuta em `0.0.0.0`, e as requisições só são autenticadas quando `api_key` não está vazia (vazia significa modo aberto). Defina uma chave e mantenha-a privada. - **Inspeção TLS (só para debug).** [`docs/proxyman-install.md`](docs/proxyman-install.md) e [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explicam como ler o tráfego HTTPS do app com o Proxyman: confiar na CA raiz dele, definir as variáveis de proxy e `NODE_EXTRA_CA_CERTS` e então iniciar o app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (e a flag `-AllowInsecureTls` do script) é um ajuste temporário; nunca deixe ligado. Não faça commit de endereços de proxy, caminhos de certificado, cookies ou códigos OAuth, e oculte dados dos logs antes de compartilhá-los. `scripts/start-antigravity-with-proxyman.ps1` mira o cliente oficial do Antigravity instalado, não este app. - **Envio de erros.** Os relatórios do Sentry (precisam de `SENTRY_DSN`) dependem da configuração `error_reporting_enabled`, que o `DEFAULT_APP_CONFIG` traz como `true`; desative em Settings para não enviar. O trecho com o nome de usuário do Windows é mascarado nas mensagens de exceção enviadas. Versões suportadas e como reportar uma vulnerabilidade: [`SECURITY.md`](SECURITY.md). ## 💻 Documentação e desenvolvimento - [`docs/cloud_features.md`](docs/cloud_features.md): design do pool de contas, do monitoramento de cota e da troca automática. - [`docs/proxyman-install.md`](docs/proxyman-install.md) e [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): configuração da inspeção TLS (Windows). - [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): integração com endpoint customizado do OpenCode (em português). - [`cli/README.md`](cli/README.md): a ferramenta de linha de comando em 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). - Traduções: [English](README.md), [中文](README.zh-CN.md), [Español](README.es.md). ### Estrutura ```text src/ ├── components/ # UI (proxy/, usage/, primitivos 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/ # testes unitários (Vitest) e E2E (Playwright) cli/ # CLI Python separada para trocar de conta e consultar cota docs/ # notas de design e guias do Proxyman scripts/ # setup-dev, build-windows, generate-assets ``` ### Scripts | Comando | O que faz | |---|---| | `pnpm start` | Roda o app em modo dev (`electron-forge start`, com `DEBUG=electron-forge:*`). | | `pnpm run dev` | O mesmo que `start`. | | `pnpm run package` | Empacota o app com o Electron Forge, sem gerar instaladores. | | `pnpm run make` | Gera instaladores/pacotes para a plataforma atual. | | `pnpm run make:win` | Helper de build no Windows: extrai o WiX de `wix314-binaries.zip`, coloca no `PATH` e roda `electron-forge make`. | | `pnpm run publish` | Publica pelo Electron Forge. | | `pnpm run setup` | Roda `scripts/setup-dev.js`: detecta a toolchain nativa e instala ou orienta a configuração. | | `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; roda sozinho depois do `pnpm install`. | | `pnpm run lint` | ESLint no repositório. | | `pnpm run format` | Checagem do Prettier. | | `pnpm run format:write` | Prettier com escrita. | | `pnpm test` | Testes unitários Vitest (`vitest run`). | | `pnpm run test:watch` | Vitest em modo watch. | | `pnpm run test:unit` | Vitest (modo padrão). | | `pnpm run test:e2e` | Testes E2E com Playwright. | | `pnpm run test:all` | Testes unitários e depois Playwright. | | `pnpm run type-check` | `tsc --noEmit`. | ## ❓ FAQ
O Windows mostra "O Windows protegeu o seu computador". É normal? Sim. Os builds não são assinados. Clique em **Mais informações → Executar mesmo assim**.
Minha IDE não alcança o proxy. O proxy vem desligado: ative-o na página Proxy. A porta padrão é `8045` (`8046` em builds de desenvolvimento) e pode ser trocada ali. Copie a API key da mesma página e confira se há pelo menos uma conta no pool.
Preciso de uma API key? Com `api_key` vazia o proxy roda em modo aberto. Quando ativado ele escuta em `0.0.0.0`, então defina uma chave e mantenha-a privada.
Dá para usar modelos Claude? Sim, por mapeamento de modelos nas contas Google do pool, não por contas Claude separadas.
Onde ficam meus tokens? Num `cloud_accounts.db` separado, com `token_json` e `quota_json` criptografados em AES-256-GCM. A chave mestra fica no cofre de credenciais do sistema via `keytar`. Detalhes em [Modelo de segurança](#modelo-de-segurança).
Posso usar comercialmente? Veja a [Licença](#-licença) antes: o código herdado do AntigravityManager é CC BY-NC-SA 4.0 (não comercial) e o código novo é MIT.
## Limitações e próximos passos - O acesso upstream passa pelos endpoints `v1internal` do Cloud Code do Google e por escopos OAuth ([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts)). São APIs internas, sem documentação, que podem mudar sem aviso. O projeto é não oficial e não tem vínculo com o Google nem com a Anthropic. - As contas entram via Google OAuth; os modelos Claude são acessados por mapeamento de modelos, não por contas Claude separadas. - Os testes end-to-end não rodam no CI (o Electron precisa de ambiente gráfico); rode `pnpm run test:e2e` localmente. - O MSI do Windows só é gerado quando o WiX Toolset está disponível na máquina de build; caso contrário o artefato do Windows é o ZIP. - Os workflows em `.github/workflows/` foram escritos para o GitHub (chamam o CLI `gh` e o publisher de releases do GitHub), por isso este README não mostra badge de CI. - Próximo passo declarado pelo projeto: migrar o código original restante para MIT (veja a [Licença](#-licença)). ## 🤝 Contribuindo Leia o [`CONTRIBUTING.md`](CONTRIBUTING.md) e o [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). As versões são geradas pelo semantic-release a partir de Conventional Commits. Antes de abrir um PR, isto precisa passar: ```bash pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test ``` ## 📄 Licença Licença mista: o código herdado do [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (de Draculabo) é [CC BY-NC-SA 4.0](LICENSE) (não comercial, compartilhamento pela mesma licença); todo o código novo é [MIT](LICENSE-MIT). O projeto está migrando para MIT à medida que o código original restante é reescrito, então confira os dois arquivos antes de qualquer uso comercial. ---
Logo do Gemini Nexus

Gemini Nexus no Gitea · Reportar um problema · Início rápido