# PoC: Agente AI controlador de container LXC no Proxmox

## 1. Objetivo
Criar uma estrutura de testes onde um agente AI executa ações reais dentro de um container LXC no Proxmox, sem depender de API web ou ferramentas locais inexistentes.

## 2. Pré-requisitos (no Proxmox node)

```
- Proxmox VE 7.x ou 8.x
- Acesso root ou usuário com privilégios PVEAuditor
- PVE CLI instalada no host (`pct`, `qm` se for VM)
- Storage configurado para templates LXC
- Rede bridge configurada (ex: `vmbr0`)
```

## 3. Templates/containers prontos recomendados

Use templates nativos do Proxmox ou da comunidade:

| Template | Uso recomendado | Por quê |
|---|---|---|
| `debian-13-standard` | Base mínima e testável | Estável, pacotes `lxc-utils` disponíveis |
| `debian-12-standard` | Compatibilidade ampla | Muitos guias e ferramentas prontas |
| `ubuntu-22.04-standard` | Apps populares | Ecossistema Python/Node forte para agentes |
| `alpine-3.19-standard` | Containers leves | Baixo overhead, ideal para PoC rápido |
| `debian-13-cloudinit` | Automação de setup | Cloud-init facilita provisionamento repetitivo |

Como checar templates disponíveis no host:

```bash
pveam available   #lista templates da comunidade
pveam lists       #mostra templates já baixados
```

## 4. Estrutura do PoC

### 4.1 Containers de teste sugeridos

CT 101 — `agent-target` (alvo das ações do agente)
- Template: `debian-13-standard`
- CPU: 1-2 cores | RAM: 512MB-1GB | Disco: 4GB
- Rede: bridge `vmbr0`, DHCP ou IP fixo
- Inicialização: automática

CT 102 — `agent-runner` (onde roda o agente)
- Template: `ubuntu-22.04-standard`
- CPU: 2 cores | RAM: 2GB | Disco: 8GB
- Rede: mesma bridge, IP fixo
- Pacotes mínimos: `python3`, `pip`, `git`

### 4.2 Fluxo de operação

```
Agente (CLI/Python) → SSH/LXC-attach → Container alvo
```

O agente pode operar por dois caminhos:

1. **Via LXC-attach** (mais simples, se rodar no host)
2. **Via SSH** (mais realista, se o agente rodar em outro lugar)

Para este PoC, priorizo `lxc-attach` por simplicidade.

## 5. Passo a passo do PoC

### Passo 1 — Provisionar containers no Proxmox

```bash
# No Proxmox: baixar template (exemplo)
pveam download local debian-13-standard

# Criar CT alvo (agent-target)
pct create 101 local:vztmpl/debian-13-standard \
  --hostname agent-target \
  --memory 1024 \
  --cores 2 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp

pct start 101
pct exec 101 -- apt update
pct exec 101 -- apt install -y lxc-utils python3 sudo
```

### Passo 2 — Configurar acesso

```bash
# Opção A: lxc-attach direto (roda no Proxmox host)
pct exec 101 -- whoami

# Opção B: SSH dentro do CT
pct exec 101 -- apt install -y openssh-server
pct exec 101 -- passwd root   # definir senha
# Descobrir IP do CT
pct exec 101 -- ip a
# Conectar de outro CT/runner:
ssh root@<IP_CT101>
```

### Passo 3 — Instalar ferramentas do agente no runner

```bash
# No agent-runner (CT 102)
apt update && apt install -y python3 python3-pip git
pip install requests paramiko   #ou dependências específicas do agente
```

### Passo 4 — Defina o comportamento do agente

Exemplo de ações que o agente pode executar no `agent-target`:

- Ler arquivos: `cat /etc/hostname`, `ls /var/log`
- Instalar pacotes: `apt install -y htop`
- Gerenciar serviços: `systemctl status cron`
- Editar arquivos: `echo "test" > /tmp/poc.txt`
- Coletar métricas: `df -h`, `free -m`, `top -b -n 1`

### Passo 5 — Crie scripts de teste

Estruture testes como arquivos YAML/JSON ou Python:

```python
# exemplo_tarefa.yaml
tarefa: instalar_pacote
container: 101
comando: apt install -y htop
valido_se:
  - comando_retorna_0: true
  - arquivo_existe: /usr/bin/htop
```

```python
# executor.py (simplificado)
import subprocess, yaml

def executar(tarefa):
    cid = tarefa["container"]
    cmd = tarefa["comando"]
    res = subprocess.run(["pct", "exec", str(cid), "--"] + cmd.split(),
                         capture_output=True, text=True)
    print(res.stdout, res.stderr)
    validar(tarefa["valido_se"])
```

### Passo 6 — Valide e documente

- Crie 5-7 cenários de teste
- Registre saídas e tempos
- Documente o que funciona, o que falha e por quê
- Meça: taxa de sucesso, tempo médio de execução, ruído (logs/erros)

## 6. Containers auxiliares opcionais

Se quiser expandir o PoC depois:

| CT | Propósito |
|---|---|
| `agent-logger` | Coleta centralizada de logs/relatórios |
| `agent-gateway` | API REST que recebe comandos e dispara ações nos CTs |
| `agent-sandbox` | CT efêmero para testes destrutivos (snapshot antes/depois) |

## 7. Segurança e isolamento

- Nunca execute o agente como root no runner sem RBAC/restrições
- Use passwords/SSH keys dedicadas para automação
- Faça snapshot do CT alvo antes de testes destrutivos
- Limite o que o agente pode executar (allowlist de comandos ou sandbox)

## 8. Critérios de sucesso do PoC

- [ ] Agente consegue listar processos no CT alvo
- [ ] Agente instala um pacote simples
- [ ] Agente cria/edita/remove arquivos no CT alvo
- [ ] Relatório de execução é gerado automaticamente
- [ ] Pelo menos 3 cenários de falha são tratados (ex: comando inválido, timeout)

## 9. Próximos passos após PoC

- Mover execução para API Proxmox (`/api2/json/cluster/{type}/{id}/status`)
- Adicionar orquestração multi-CT
- Adicionar observabilidade (métricas, traces)
- Integrar com agente AI real (CLI, SDK ou modelo local)