17 KiB
📸 Screenshots
🎯 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 localPOST /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 breakercache-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).
Como funciona
- Adicione contas. Entre com Google OAuth na página Accounts. Os tokens são criptografados antes de chegar ao SQLite.
- Aponte a IDE para o proxy. Ative o proxy na página Proxy (ele vem desligado) e use
http://localhost:8045/v1com a API key mostrada ali, no formato OpenAI ou Anthropic. - 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.
⚡ Início rápido
Ainda não há downloads prontos na página de Releases do Gitea (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) |
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:
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). |
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
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
- Um cliente envia requisições no formato OpenAI ou Anthropic para o proxy NestJS (Fastify, escutando em
0.0.0.0). - O guard do proxy confere a API key quando há uma configurada; com a chave vazia o proxy roda em modo aberto.
- 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.
- O
CloudMonitorServiceconsulta a cota a cada 5 minutos e oAutoSwitchServicetroca a conta ativa quando a cota está abaixo de 5 % ou a conta sofre rate limit. - 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.
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_jsonequota_jsonsã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 viakeytar(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,cookieeclient_secretsão trocadas por[REDACTED]antes de ir para o log (src/utils/sensitiveDataMasking.ts); o logger de tráfego também oculta os headersauthorization,x-api-keyecookie. - 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.jsonsão o controle de rotação dowinston-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 quandoapi_keynão está vazia (vazia significa modo aberto). Defina uma chave e mantenha-a privada. - Inspeção TLS (só para debug).
docs/proxyman-install.mdedocs/proxyman-debugging.mdexplicam como ler o tráfego HTTPS do app com o Proxyman: confiar na CA raiz dele, definir as variáveis de proxy eNODE_EXTRA_CA_CERTSe então iniciar o app.NODE_TLS_REJECT_UNAUTHORIZED=0(e a flag-AllowInsecureTlsdo 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.ps1mira 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çãoerror_reporting_enabled, que oDEFAULT_APP_CONFIGtraz comotrue; 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.
💻 Documentação e desenvolvimento
docs/cloud_features.md: design do pool de contas, do monitoramento de cota e da troca automática.docs/proxyman-install.mdedocs/proxyman-debugging.md: configuração da inspeção TLS (Windows).docs/OpencodeAPI.md: integração com endpoint customizado do OpenCode (em português).cli/README.md: a ferramenta de linha de comando em Python.CONTRIBUTING.md,SECURITY.md,CODE_OF_CONDUCT.md,CHANGELOG.md,LICENSE,LICENSE-MIT.- Traduções: English, 中文, Español.
Estrutura
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.
Posso usar comercialmente?
Veja 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
v1internaldo Cloud Code do Google e por escopos OAuth (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:e2elocalmente. - 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 CLIghe 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).
🤝 Contribuindo
Leia o CONTRIBUTING.md e o 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:
pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
📄 Licença
Licença mista: o código herdado do AntigravityManager (de Draculabo) é CC BY-NC-SA 4.0 (não comercial, compartilhamento pela mesma licença); todo o código novo é 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.








