



Início rápido · Docs · Issues
English · Português · 中文 · Español
## 📸 Screenshots
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