Proxmox & Coolify Manager

Toolkit para operar un homelab con ayuda de un agente: un host Proxmox local y el stack Coolify que corre dentro de su LXC 102, más el túnel de Cloudflare y los repos en GitHub y Gitea.

La idea es simple: este repo guarda el contexto, los runbooks y los scripts seguros para que un agente pueda diagnosticar y ayudarte a gestionar la infraestructura sin depender de memoria suelta ni de secretos pegados en Markdown.

Empieza por aquí

Si quieres…	Lee
saber qué script usar para algo	docs/TOOL-INDEX.md — el catálogo canónico
saber qué existe y qué versión corre	docs/proxmox-inventory.md
que un agente opere el sistema	CLAUDE.md — arquitectura + router de intención
resolver un problema concreto	docs/runbooks/

Cuatro trampas conocidas producen resultados silenciosamente incorrectos (el flag -Raw invertido entre wrappers, comillas anidadas corrompidas en SSH, nombres de contenedor no adivinables, y el 404 que Cloudflare impone a /applications/* en el hostname público). Están documentadas en la §1 del índice. Léela antes de operar.

Estado verificado

Verificado el 2026-08-29 desde esta máquina:

Host Proxmox: 192.168.0.200, nodo thinkcentre, Proxmox VE 9.1.1, kernel 6.17.2-1-pve
LXC: 100 hermes (running — commit 5d3c15aaa, MiniMax-M3), 102 coolify (running)
Sin VMs QEMU
Docker corre dentro del LXC 102: 68 contenedores, 28 recursos registrados en Coolify
Coolify v4.3.14 — su API está completa contra el origen (http://192.168.0.117:8000/api/v1); vía Cloudflare /applications/* y /github-apps devuelven 404 (bloqueo del edge, no de Coolify). Los endpoints de estado exigen POST desde v4.2.
SSH con clave local: OK · API de Coolify: OK · API de Proxmox: OK (token root@pam!openclaw cargado en .env.local.ps1)
API de Cloudflare: sin token cargado, se gestiona desde el dashboard

Credenciales y llaves SSH verificadas: ACCESS.md (local, gitignored).

Estructura

CLAUDE.md              Arquitectura, router de intención y reglas para el agente
docs/
  TOOL-INDEX.md        Catálogo canónico de herramientas + gotchas   ← empieza aquí
  proxmox-inventory.md Estado verificado del sistema (fuente de verdad)
  AGENTS-coolify-apps.md  Contrato para construir una app deployable en este Coolify
  runbooks/            Procedimientos vigentes
  casos/               Casos resueltos paso a paso
  incidentes/          Archivo histórico — NO es fuente de verdad
scripts/               Wrappers de host: SSH, API, inventario, Cloudflare, Chatwoot
  apps/                Scripts de deploy específicos de una app
  host/                Artefactos que se despliegan en el host Proxmox
agent/                 Skill de operación del host Proxmox
coolify_skill/         Skill de operación de Coolify + referencia de su API
deploy_skill/          Skill de deploy de proyectos nuevos a Coolify
gitea_skill/           Skill de la capa de hosting git self-hosted

Cada carpeta *_skill/ tiene un SKILL.md (reglas operativas) y un TOOLS.md (ejemplos ejecutables).

Runbooks

Runbook	Qué cubre
conexion.md	Establecer y verificar el acceso
diagnostico.md	Triage general del host
coolify-docker.md	Operar Docker dentro del LXC 102
seguridad.md	Postura de seguridad y manejo de secretos
cloudflare-tunnel.md	Túnel y rutas (gestionado desde el dashboard)
autostart-coolify.md	Auto-arranque del stack tras un corte de luz
chatwoot-update.md	Actualizar Chatwoot sin perder la edición enterprise
nextcloud.md	Recuperación y fix HTTPS
baserow.md	Puesta en vivo y fix de red/Traefik

Configuración local

Los secretos no viven en el repo. Van en .env.local.ps1, ignorado por Git. Copia la plantilla y rellénala:

Copy-Item .env.example .env.local.ps1

Luego, en cada sesión:

. .\.env.local.ps1
.\scripts\Test-ProxmoxConnection.ps1     # smoke test; sale 1 si algo falla
.\scripts\Get-ProxmoxInventory.ps1       # inventario completo
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct list"

Para la verificación operativa con navegador (Test-ServiceOnline.ps1) hace falta Node: npm install una vez en la raíz del repo.

Reglas de operación

Solo-lectura primero. El default es diagnosticar.
Confirmación explícita antes de cualquier cambio de estado: borrar, reiniciar, apagar, deployar, editar red/storage, actualizar paquetes o modificar servicios. Para acciones riesgosas, captura el estado actual y enuncia el rollback antes de actuar.
Prefiere los scripts del repo antes que comandos manuales largos.
Nunca registres tokens, passwords ni claves privadas en Markdown.

La versión completa y vinculante está en la §6 del índice de herramientas.

5.2 KiB Raw Blame History