# 🦇 gotham-browser

Motor de automação de browser do GOTHAM_OS. Usa [browser-use](https://github.com/browser-use/browser-use) OSS com Playwright/Chromium — 100% self-hosted, zero cloud externo.

## Casos de uso

- **Pesquisa de suprassumo** — varrer Reddit/HN/GitHub/X ao vivo para freshness check do STACK_ARSENAL
- **Inteligência competitiva** — scraping de LPs, preços, ads de concorrentes (BENCHMARK_LABS)
- **Auditoria de UI/UX** — inspecionar checkout, formulários, fluxos ao vivo
- **Automação** — qualquer tarefa que exige navegar, clicar, extrair

## Arquitetura

```
Claude Code (WSL)         ──MCP stdio──→  browser-use CLI (uvx, local)
Codex / agy / OpenCode    ──REST POST──→  gotham-browser :7893 (Coolify / Oracle VPS)
                                                   ↓
                                       Playwright/Chromium headless
                                                   ↓
                                   LLM do arsenal GOTHAM (canon §3)
                                                   ↓
                                   gotham-realtime :7892 (eventos opcionais, quando configurado)
```

## MCP — Claude Code (WSL)

```bash
# Status
claude mcp list | grep gotham-browser
# → gotham-browser: uvx browser-use[cli] --mcp  ✓ Connected

# Usar (dentro do Claude Code):
# "Acessa reddit.com/r/selfhosted e me traz os 5 posts mais votados"
# "Testa o checkout do verifiedbms.com e me diz o que está quebrado"
```

## REST API — Outros CLIs da VPS

Endpoint: `http://localhost:7893` (interno VPS). Runtime atual: Coolify.

```bash
# Health
curl http://localhost:7893/health
# → {"ok":true,"service":"gotham-browser","version":"0.1.0"}

# Tarefa
curl -X POST http://localhost:7893/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Scrape top posts r/selfhosted this week", "llm_provider": "nvidia"}'
```

## Arsenal de LLMs (canon 12-DELEGACAO §2-§3)

Todos sem custo adicional — usam as chaves já no ecossistema GOTHAM.

| Provider | Modelos padrão | Custo | Chave |
|---|---|---|---|
| `nvidia` **(padrão)** | openai/gpt-oss-120b | Free ~40 RPM | `NVIDIA_API_KEY` (env) |
| `zen-free` | nemotron-3-ultra-free, deepseek-v4-flash-free | Free, sem chave | — |
| `go` | glm-5.1, kimi-k2.6, deepseek-v4-pro | $10/mês OpenCode Go | `auth.json` auto |
| `gemini` | gemini-2.5-flash | Free 20/dia | `GOOGLE_API_KEY` / `auth.json` |
| `openrouter` | variados free/paid | ver OR | `OPENROUTER_API_KEY` |
| `claude` | claude-sonnet-4-6 | Pago | `ANTHROPIC_API_KEY` |
| `opus` | claude-opus-4-8 | Pago (nuclear) | `ANTHROPIC_API_KEY` |

## Estrutura

```
src/
├── main.py      # FastAPI REST + MCP server + CLI entry
├── agent.py     # browser-use wrapper — arsenal completo GOTHAM
└── realtime.py  # emite eventos opcionais para gotham-realtime
Dockerfile       # ARM64 + x86_64, playwright install --with-deps
docker-compose.yml  # porta 7893
.env.example     # todas as vars documentadas
```

## Deploy

### WSL (MCP local — Claude Code)
```bash
# Chromium instalado em: ~/.local/share/gotham-browser-venv
# MCP registrado em: ~/.claude.json (project: /mnt/c/GOTHAM_OS)
# Verificar: claude mcp list
```

### Oracle VPS / Coolify (REST — todos CLIs)

Estado atual em 2026-06-08:

- Runtime: Coolify, não docker-compose manual.
- Coolify app uuid: `pd3jyi52ngb6xze3p8ubxh14`
- Repo fonte: `gotham-os/gotham-browser`
- Branch: `master`
- Porta publicada: `7893`
- Health validado: `http://127.0.0.1:7893/health`
- `gotham-realtime` não roda na VPS; deixe `GOTHAM_REALTIME_URL` vazio no Coolify.

```bash
# Health na VPS:
curl http://127.0.0.1:7893/health
```

### .env mínimo
```env
BROWSER_LLM_PROVIDER=nvidia
NVIDIA_API_KEY=nvapi-...
GOTHAM_REALTIME_URL=http://127.0.0.1:7892/ingest
BROWSER_HEADLESS=true
```

Na VPS Oracle, deixe `GOTHAM_REALTIME_URL` vazio se o broker `gotham-realtime` nao estiver rodando localmente.

## Histórico Operacional

- `070df87` — prepara compose para Coolify: remove host networking, torna realtime opcional, aceita `llm_provider`.
- `07a5d23` — remove bind mount `./src:/app/src:ro`, que quebrava `python -m src.main` no container Coolify.
- Output canonico GOTHAM: `05_OUTPUTS_IA/DEPLOY_GOTHAM_BROWSER_COOLIFY_20260608.md`.

## Repo

`gotham-os/gotham-browser` | Código local: `/mnt/c/GOTHAM_REPOS/gotham-browser` | VPS: `/opt/gotham/stacks/gotham-browser`