# Plano Técnico — Clone da Mia + Acesso N8N Remoto

**Autor:** Paulo (paulo-dev)
**Solicitado por:** Renato via Mia
**Data:** 2026-06-01

---

## PERGUNTA 1 — Clonar estrutura da Mia em outra VPS

### Inventário do setup atual

**Stack runtime**
- Ubuntu 24.04 (kernel 6.8), user `mia` (uid 1001)
- Python 3.12.3, Node.js v22.22.2
- Claude Code CLI v2.1.118 (OAuth conta Pro/Max do Renato)
- tmux (orquestra sessão `mia` onde o CLI vive)

**Arquivos críticos**
- `/opt/mia/` (1.5 GB): CLAUDE.md, knowledge, workspace, scripts, hooks, agent-manager, memory-service
- `/opt/mia/.claude/agents/` — 7 subagentes (amanda-crm, davi-sdr, jonathan-copy, juliana-ops, leo-web, paulo-dev, rafael-projetos)
- `/opt/mia-bot/` (72 MB): bot.py, outbox/inbox/sent/failed, audio, images, logs, state
- `/home/mia/` (10 GB): sessões do Claude, history.jsonl, projects, file-history, plans, tasks, plugins, skills, skill_sources, .credentials.json
- `/home/mia/.claude/skills/` (symlinks para `/home/mia/skill_sources/`)
- `/home/mia/.claude/settings.json`

**Systemd (4 units)**
- `mia.service` (sobe Claude CLI dentro do tmux)
- `mia-bot.service` (bot Python Telegram)
- `mia-bot-reserve.service` (disabled mas running — bug)
- `mia-refresh.timer` + `mia-refresh.service` (renovação OAuth a cada 6h)

**Secrets (.env)**
- `/opt/mia-bot/.env` — 24 chaves (TELEGRAM_BOT_TOKEN, OPENAI_API_KEY, ELEVENLABS_*, HOSTGATOR_TOKEN, CPANEL_*, UNICHAT_*, UNNICHAT_*, SUPABASE_*, ANTHROPIC_API_KEY, RESEND_API_KEY)
- `/opt/mia/.env` — identidade (AGENTE_NAME, OWNER_NAME, OWNER_EMAIL, NICHO, INSTAGRAM_HANDLE, VPS_IP, DATABASE_URL) — já parametrizado, ótimo sinal
- `/home/mia/.claude/.credentials.json` — OAuth token Claude (intransferível, um por cliente)

**O que NÃO clonar**
- `/opt/mia/workspace/` inteiro (1.4 GB de projetos de cliente)
- `/home/mia/.claude/projects/` (sessões/transcripts do Claude)
- `/home/mia/.claude/{history.jsonl, file-history, paste-cache, sessions, plans, tasks}`
- `.credentials.json` (cada cliente faz /login)
- `outbox/inbox/sent/failed/state` do bot
- Os 24 secrets do `.env`

### Estratégia: 3 camadas

1. **CORE** (repo git privado `mia-core`) — código, templates, sem dados/secrets
2. **CONFIG** (gerada pelo bootstrap) — .env com placeholders `{{TELEGRAM_BOT_TOKEN}}`, `{{AGENTE_NAME}}`, etc
3. **SECRETS** (input manual ou 1Password/sops) — injetada na hora, nunca commitada

**Tratamento do OAuth Claude:** cada cliente roda `claude /login` na própria VPS. Script de setup pausa e instrui.

### Pré-requisitos VPS destino

- 4 vCPU, 8 GB RAM, 50 GB SSD (16 GB pra cliente com volume alto)
- Ubuntu 24.04 LTS
- Pacotes: `python3.12 python3-pip tmux git curl jq sudo ffmpeg`
- Node.js 22.x
- Claude CLI: `npm i -g @anthropic-ai/claude-code`
- User `mia` com sudo NOPASSWD restrito a `systemctl {start,stop,restart} mia*`
- Easypanel/Traefik **opcional** (só se cliente hospedar landings)

### Roadmap em 5 fases

| Fase | Tempo | O que acontece |
|---|---|---|
| 0 | 8-12h (one-time) | Criar repo mia-core + templates + script bootstrap idempotente |
| 1 | 15 min | Provisionar VPS, DNS, firewall, SSH, user mia, pacotes |
| 2 | 10 min | `setup-mia-clone.sh --client-slug=acme` clona, instala, cria dirs, systemd (sem iniciar) |
| 3 | 15 min | Wizard interativo coleta credenciais, gera .env files (600, dono mia) |
| 4 | 10 min | `claude /login` manual + `systemctl enable --now mia.service mia-bot.service mia-refresh.timer` |
| 5 | 10 min | Validação end-to-end via Telegram |

**Total primeira clonagem:** ~1h. Subsequentes: 30-40 min.

### Riscos

1. **OAuth Claude não replicável** — 1 /login por VPS. Verificar política Anthropic sobre múltiplas sessões Pro/Max
2. **tmux + systemd Type=forking frágil** (dor recorrente — já tem timer de renovação justamente por isso)
3. **mia-bot-reserve.service running mas disabled** — bug atual, investigar antes de clonar
4. **Skill sources são symlinks** — copiar com tar/rsync sem `-L` quebra
5. **history.jsonl e sessions crescem indefinidamente** (10 GB atual) — implementar rotação dia 1
6. **Identidade espalhada em vários .md** ("Mia", "Renato", "Climb Digital") — precisa sed/jinja parametrizado, senão clone vira Mia falando que é Mia pro cliente errado
7. **Telegram bot por cliente** — cada um cria no @BotFather

### Estimativa

- Setup do repo core + script: **8-12h** (one-time)
- Cada clone novo: **1h**

---

## PERGUNTA 2 — Mia acessar N8N remoto

### Caminhos avaliados

| Caminho | Veredito |
|---|---|
| **API REST do N8N** (`/api/v1/executions`) | ✅ Melhor opção — oficial, JSON estruturado, filtros |
| API do Portainer | Inferior, usa só se N8N API não atender |
| Docker Remote API c/ TLS | ❌ Vetor RCE clássico, não recomendado |
| SSH + `docker logs n8n` | ✅ Fallback diagnóstico |
| MCP server (n8n-mcp) | Vale numa V2, não V1 |

**Recomendação: API REST como principal + SSH como fallback.**

### Credenciais

**API N8N:**
- Gerar API key no painel (Settings > n8n API)
- Escopo: `executions:read` + `workflows:read` apenas (sem write, sem deletar)
- Guardar em `/opt/mia-bot/.env`: `N8N_API_URL` + `N8N_API_KEY`

**SSH fallback:**
- Par ed25519 dedicado: `ssh-keygen -t ed25519 -f /home/mia/.ssh/n8n_remote`
- Forced-command no authorized_keys da VPS destino:
  ```
  command="docker logs --tail 200 n8n",no-port-forwarding ssh-ed25519 ...
  ```

### Permissões mínimas

- **API key**: somente leitura. Mia diagnostica, humano executa ação destrutiva
- **SSH key**: forced-command read-only

### Integração

Script em `/opt/mia/scripts/n8n_check.py`:
```
n8n_check.py executions --status=error --limit=20
n8n_check.py executions --workflow="lead capture" --since=yesterday
n8n_check.py execution-detail <id>
```

Quando Renato pede "tem erro no lead capture ontem", Mia invoca via Bash, parseia JSON, formata em PT-BR pro outbox.

### Roadmap

1. **MVP em ~2h** — script bash `n8n_errors.sh` (curl + jq)
2. **V1 em ~1 dia** — Python com cache, comandos múltiplos, sugestão de fix
3. **V2 futuro** — MCP server local

### Proposta MVP 2h

```bash
/opt/mia/scripts/n8n_errors.sh
  - lê N8N_API_URL e N8N_API_KEY do env
  - curl GET /api/v1/executions?status=error&limit=20
  - jq parseia: id, workflowName, startedAt, stoppedAt
  - pra cada erro, curl GET /api/v1/executions/{id} pega stacktrace
  - formata markdown: "❌ Workflow X falhou em Y - erro: Z"
```

### Riscos

1. API key vaza — read-only mitiga, mas tem PII de execução. Rotacionar trimestralmente
2. Rate limit N8N Community — cache em /tmp/
3. N8N sem HTTPS — API key em plaintext. Exigir HTTPS
4. Payloads gigantes — script trunca antes de mandar pro Telegram

---

## SÍNTESE EXECUTIVA

**Clone Mia:** factível, 8-12h upfront, ROI a partir de 2-3 clones. Bloqueios principais: OAuth Claude (1 /login por VPS) e fragilidade tmux+systemd.

**Acesso N8N:** API REST do N8N + SSH fallback. MVP de 2h resolve 80%. Nunca Docker Remote API.