Files
gemini-nexus/README.pt-BR.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

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 Status License

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

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.

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

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

💻 Documentação e desenvolvimento

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 v1internal do 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: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).

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