hlab: Convertir un homelab Proxmox en una pequeña plataforma

Hay un momento en todo homelab serio en el que la parte divertida empieza a parecer administración. Crear una VM en Proxmox es bastante agradable. Crear la décima ya es otra cosa. Empiezas a recordar qué nodo tiene el template correcto, qué storage debes usar, qué bridge pertenece a la LAN, qué rango de VM IDs reservaste para experimentos y qué imagen de cloud-init todavía tiene el guest agent bien instalado.

En ese punto el problema ya no es virtualización. El problema es que tu homelab se volvió una pequeña nube, pero sigues operándolo como una colección de máquinas creadas a mano.

Ese es el espacio que hlab intenta cerrar. Es un proyecto hobby open source para crear y administrar VMs y contenedores LXC de Proxmox desde la terminal, con una página del proyecto en hlab.sh. La idea es simple: conservar el poder de Proxmox, Terraform y Ansible, pero exponerlo con una experiencia más parecida a una pequeña Platform-as-a-Service que a una pila de scripts de infraestructura.

La observación: los homelabs terminan pareciéndose a una plataforma

La mayoría de homelabs no empieza con ambiciones de platform engineering.

Empiezan con una necesidad práctica: una VM para un reverse proxy, otra para una base de datos, un nodo temporal de Kubernetes, un sandbox Linux, un runner de CI, un container para monitoreo. Las primeras máquinas son manejables porque recuerdas las decisiones. Después de un tiempo, esas decisiones se repiten tanto que se convierten en un flujo de trabajo.

Y los flujos de trabajo repetidos tarde o temprano piden una superficie de producto.

Por eso hlab no parte de la pregunta “¿cómo genero Terraform?”. Parte de una pregunta más útil: “quiero un servidor nuevo; ¿qué sabe ya la herramienta?”

La métrica útil aquí es time-to-first-experiment. Un homelab está sano cuando la curiosidad puede moverse rápido de “quiero probar esto” a “tengo una máquina desechable donde puedo romperlo con seguridad”. Cada bridge recordado de memoria, cada inventario escrito a mano y cada VM ID olvidado alarga esa distancia.

El modelo mental: una pequeña PaaS para Proxmox

Las PaaS públicas son útiles porque esconden la forma aburrida de la infraestructura detrás de un número pequeño de decisiones. Eliges un plan, un runtime, quizá una región, y la plataforma se encarga de la maquinaria de abajo.

hlab lleva esa idea al homelab.

No reemplaza Proxmox. No pretende que tu rack sea AWS. Simplemente le da a tu laboratorio una capa de autoservicio:

Ese mapeo es lo interesante del proyecto. No es un wrapper que solo acorta comandos. Es una pequeña capa de producto encima de un sustrato real de infraestructura.

La TUI: donde aparece la sensación de plataforma

La experiencia principal es la dashboard TUI. Al ejecutar hlab sin argumentos se abre una interfaz de pantalla completa donde puedes inspeccionar y administrar VMs y containers sin salir de la terminal.

Desde ese dashboard, el flujo de creación se siente más como un formulario de plataforma que como un cuestionario de Terraform.

Primero eliges si quieres una VM o un contenedor LXC. Después la herramienta pregunta por la imagen. Para VMs, esa imagen no es una ISO arbitraria; es un template de VM en Proxmox que tú ya construiste. Esa restricción importa. Una fábrica confiable de VMs empieza con golden images confiables. Si el template tiene el guest agent correcto, cloud-init bien configurado, paquetes base y layout de disco, cada clon hereda esas decisiones.

El template elegido también le da información útil a hlab. Los templates viven en nodos específicos de Proxmox, y un clon muchas veces debe caer donde el template y el storage local tienen sentido. En vez de obligarte a responder todo manualmente, la TUI deja que la infraestructura guíe las opciones.

Luego viene el plan.

1
Create VM
2

3
Template
4
  ubuntu-24.04-template (#200) · pve1
5

6
Plan
7
  nano   1 CPU · 1 GB RAM  · 10 GB disk
8
  KVM1   1 CPU · 2 GB RAM  · 16 GB disk
9
  KVM2   2 CPU · 4 GB RAM  · 32 GB disk
10
  KVM4   4 CPU · 8 GB RAM  · 48 GB disk
11
  KVM8   8 CPU · 16 GB RAM · 64 GB disk
12
  Custom

Esta es la parte parecida a una PaaS. En lugar de decidir CPU, RAM y disco cada vez, la mayoría de VMs se puede describir por intención: sandbox pequeño, servicio normal, nodo más pesado. Cuando el catálogo no alcanza, Custom mantiene abierta la salida.

Después, la TUI pide identidad y red: VM ID, hostname, DHCP o IP estática, gateway y DNS cuando hace falta, usuario admin, password y SSH key opcional. Antes de aplicar algo, muestra una pantalla de revisión. Ese paso importa porque la herramienta busca reducir trabajo accidental de infraestructura, no esconder consecuencias.

Debajo: Terraform y Ansible sin cargar con su mantenimiento

El diseño está separado en dos fases.

create construye el guest. provision instala software.

Esa separación mantiene honesto el ciclo de vida. Terraform posee la forma de la máquina: VM o container, ID, CPU, RAM, disco, red y lifecycle en Proxmox. Ansible posee lo que pasa dentro del guest: Docker, Podman, k3s, Node.js, Go, Python, Rust, dotfiles y tooling de terminal para agentes como Claude Code, OpenCode y Hermes.

El usuario no mantiene esos archivos de Terraform y Ansible a mano. hlab los genera y orquesta desde una declaración pequeña guardada bajo ~/.hlab.

1
~/.hlab/
2
  config.yaml     URL de Proxmox, API token, defaults, SSH keys, dotfiles repo
3
  plans.yaml      catálogo editable de tamaños para VM y LXC
4
  vms/            declaraciones por guest
5
  terraform/      workspace de Terraform generado
6
  ansible/        inventario y datos de provisioning generados

Ese layout le da al homelab algo que muchas configuraciones ad-hoc no tienen: una fuente de verdad. La dashboard se siente interactiva, pero el resultado sigue siendo lo bastante declarativo como para inspeccionarlo, versionarlo y razonarlo.

La CLI headless: automatización, scripts y agentes de IA

La TUI es la superficie más cómoda, pero no es la única.

Cada acción importante también tiene una forma CLI. Eso importa porque las herramientas de infraestructura tarde o temprano son usadas por otras herramientas: scripts de shell, jobs de CI, cron, bootstrap scripts y, cada vez más, agentes de IA que necesitan una forma segura y repetible de pedir infraestructura.

Por ejemplo, un agente o script de automatización no debería tener que manejar una terminal interactiva para crear una VM desechable. Puede usar la ruta headless:

1
hlab vm create \
2
  --name agent-sandbox \
3
  --vmid 6201 \
4
  --template ubuntu-24.04-template \
5
  --plan KVM2 \
6
  --dhcp \
7
  --user admin \
8
  --password "$HLAB_VM_PASSWORD"
9

10
hlab vm provision agent-sandbox --software docker,node,go,opencode

Ahí hlab deja de ser solo una comodidad. La TUI le da a los humanos una buena cabina de operación. La CLI le da a la automatización un contrato estable.

El mismo patrón aplica a containers:

1
hlab ct create \
2
  --name cache \
3
  --vmid 6210 \
4
  --template-file 'local:vztmpl/debian-12-standard.tar.zst' \
5
  --plan small \
6
  --dhcp=false \
7
  --ip 192.168.1.210/24 \
8
  --gateway 192.168.1.1 \
9
  --password "$HLAB_CT_PASSWORD"

Para flujos asistidos por IA, esa diferencia es útil. Una persona puede explorar y confirmar desde la dashboard. Un agente puede pedir un plan conocido, instalar un conjunto conocido de software, ejecutar trabajo y destruir el guest después. La interfaz es predecible para automatizar, pero sigue conectada a las mismas declaraciones que ve el humano.

Las operaciones day-2 también son parte del producto

Crear una VM es solo la primera operación. Una herramienta de homelab se vuelve valiosa cuando también maneja la segunda, la tercera y la número veinte.

hlab incluye las acciones day-2 esperadas: SSH, start, stop, reboot, snapshot, rollback, resize, migrate, update, destroy y chequeos de drift con hlab plan. También puede adoptar VMs o containers existentes que fueron creados fuera de la herramienta, importándolos a su modelo de gestión sin modificar el guest vivo cuando la adopción no es segura.

Ese último detalle importa. La infraestructura hobby también merece herramientas prudentes. Una buena herramienta de homelab debería hacer más rápida la experimentación sin hacer más fácil la destrucción accidental.

Trade-offs: lo que hlab asume

hlab es opinado, y esas opiniones son parte del diseño.

La suposición más grande es que las VMs deben clonarse desde templates que el usuario ya preparó. Es una buena restricción cuando quieres repetibilidad. Es menos cómoda si tu flujo normal es descargar ISOs e instalar máquinas manualmente cada vez.

La segunda suposición es que Terraform y Ansible son los motores adecuados de ejecución. Eso mantiene la herramienta construida sobre primitivas maduras de infraestructura, pero también significa que la máquina que ejecuta hlab necesita esas herramientas disponibles. El instalador ayuda con eso, pero la dependencia es real.

La tercera suposición es que un homelab se beneficia de un poco de pensamiento de plataforma. Para un solo host Proxmox con dos VMs de larga vida, la abstracción puede ser innecesaria. Para un laboratorio de dos nodos donde creas, redimensionas, provisionas, haces snapshots y destruyes guests con frecuencia, el apalancamiento empieza a aparecer.

Por qué vale la pena seguirlo

La idea interesante detrás de hlab no es que pueda crear una VM. Proxmox ya puede hacerlo.

La idea interesante es que incluso un homelab se beneficia de una superficie de producto cuando las mismas decisiones de infraestructura se repiten lo suficiente. Los planes codifican tamaños. Los templates codifican decisiones de sistema operativo. La TUI codifica el flujo humano. La CLI codifica el contrato de automatización. Terraform y Ansible codifican la ejecución.

Esa combinación convierte “necesito otro servidor” en una acción más pequeña, segura y repetible.

Si usas Proxmox en casa y quieres que tu laboratorio se sienta menos como una secuencia de tareas manuales y más como una pequeña plataforma interna, empieza por hlab.sh, y luego explora el código en github.com/aikssen/hlab.

Ideas clave

• hlab es un proyecto hobby open source que le da a los homelabs Proxmox una experiencia de autoservicio en terminal.
• Su modelo mental se parece a una pequeña PaaS: templates como imágenes, planes como tamaños de instancia, provisioning como add-ons y operaciones day-2 como acciones de plataforma.
• La TUI es el flujo humano principal y debería ser el primer lugar donde la mayoría de usuarios pruebe la herramienta.
• La CLI headless importa para scripts, CI, automatización repetible y agentes de IA que necesitan infraestructura sin manejar una UI.
• La restricción principal es deliberada: las VMs confiables empiezan desde templates confiables construidos por el usuario.

Seguir explorando

• Visita la página del proyecto: hlab.sh
• Lee y contribuye al código: github.com/aikssen/hlab
• Conceptos relacionados: Homelab, Proxmox, Internal Developer Platforms, Golden Images, Infrastructure as Code