hlab

command module
v0.10.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

README

hlab

Create and manage Proxmox VMs and LXC containers, quickly and simply. Think "I want a new server" — not "I want to configure Terraform".

hlab discovers your infrastructure through the Proxmox API, asks only what it can't infer, and drives the official tools for you — Terraform for the guest lifecycle and Ansible for provisioning. You never write or maintain Terraform or Ansible by hand. It's both a CLI and a full-screen dashboard TUI.

Run hlab with no arguments for the dashboard: a live view of your VMs and containers where create / provision / ssh / snapshot / destroy all happen inside the app. The hlab vm … and hlab ct … subcommands remain for scripting.

Site: hlab.sh

hlab dashboard TUI

Features

  • Create & manage VMs and LXC containers from simple, versioned declarations.
  • Dashboard TUI — live status, cluster metrics, and every operation in one app.
  • Discovers your cluster via the Proxmox API; asks only what it can't infer.
  • Orchestrates Terraform + Ansible under the hood — no hand-written config.
  • Day-2 operations — snapshots, migrate between nodes, resize CPU/RAM/disk.
  • Adopt existing guests created outside hlab, without ever touching them.
  • Provisioning — a software catalog (Docker, Podman, k3s, language runtimes, agents) plus your dotfiles, installed idempotently.
  • Themeable — built-in themes with live switching, plus your own.

Requirements

  • A Proxmox VE cluster (tested on Proxmox 9).
  • A scoped API token — see docs/proxmox-token.md.
  • Terraform and Ansible — the installer sets these up for you (Ansible is only needed for provision).

Install

Homebrew (macOS / Linux)
brew install aikssen/tap/hlab

Installs and updates the release binary via the aikssen/tap tap (verified against the release's SHA256SUMS).

curl | bash

The one-liner installs the latest release binary to ~/.local/bin (idempotent — re-run to update; the download is verified against the release's SHA256SUMS):

curl -fsSL https://raw.githubusercontent.com/aikssen/hlab/main/scripts/install.sh | bash

Or build from a local checkout:

./scripts/install.sh    # build + install hlab to ~/.local/bin  (or: mise run install)
hlab version

The installer also installs hlab's runtime tools after hlab itself, picking the right build for your OS/arch: Terraform (pinned to a known-good version, overridable with HLAB_TERRAFORM_VERSION) and Ansible (best-effort via pipx → Homebrew → system package manager → pip). An already-installed Terraform or Ansible is detected and reused, and dependency installation is non-fatal — a tool that can't be auto-installed only warns and never blocks the hlab binary. Set HLAB_SKIP_DEPS=1 to skip the dependency phase entirely. Other knobs: HLAB_BIN_DIR, HLAB_VERSION, HLAB_FROM_RELEASE=1.

Ensure ~/.local/bin is on your PATH.

macOS note: if you download a binary manually (not via curl | bash), Gatekeeper quarantines it — clear it with xattr -d com.apple.quarantine ./hlab.

Windows

Download hlab_windows_amd64.exe (or hlab_windows_arm64.exe) from the Releases page, rename it to hlab.exe, and put it on your PATH. hlab needs terraform and git on PATH; the interactive hlab vm ssh uses the OpenSSH client bundled with Windows 10+.

Provisioning needs WSL: hlab vm provision / update and ct provision drive Ansible, which has no native Windows build — run those inside WSL. Everything else (discovery, the dashboard, create/destroy, power, snapshots, migrate, adopt, drift/plan, resize) works natively. The scripts/install.sh installer is bash; on Windows download the .exe directly (or run the script under Git Bash/WSL).

Quick start

hlab setup              # configure Proxmox connection + defaults (one time)
hlab doctor             # verify terraform + Proxmox connectivity
hlab                    # launch the dashboard TUI — manage everything here

Prefer the command line? The two-phase flow is:

hlab vm create --name web --vmid 200            # bring up the VM (Terraform)
hlab vm provision web --software docker,node     # install software (Ansible)
hlab vm ssh web
hlab vm destroy web

Two phases, by design: create brings up the guest (Terraform); provision installs software and dotfiles (Ansible), where the selection is actually chosen and persisted. The TUI drives the same two phases.

Containers work the same way under hlab ct (create from a container template):

hlab ct create --name cache --vmid 210 --template-file 'local:vztmpl/debian-12-…tar.zst' \
  --dhcp=false --ip 192.168.1.210/24 --plan small --password 's3cret'

See docs/lxc.md for container specifics.

How it fits together

hlab keeps everything it generates in a single home directory, ~/.hlab (override with HLAB_HOME). hlab creates it on first use, and you can version it with git:

~/.hlab/
  config.yaml     Proxmox URL, API token, defaults, SSH keys, dotfiles repo, theme
                  — mode 0600, gitignored (holds a secret), never committed
  plans.yaml      VM + LXC size catalogs (user-editable; seeded on first use)
  vms/            per-guest declarations *.yaml — the versioned source of truth
  terraform/      generated workspace; tfvars versioned, *.tfstate/secrets gitignored
  ansible/        generated inventory + provisioning run data

Migrating from an older hlab? Earlier versions split config across ~/.config/hlab and ~/.hlab. hlab now auto-migrates config.yaml / plans.yaml into ~/.hlab on first run, printing a one-line notice. Nothing to do by hand.

Commands

Every VM/container subcommand accepts a name or a numeric ID.

Command What it does
hlab Launch the dashboard TUI.
hlab setup Configure connection/defaults (--add-node, --add-ssh-key to extend).
hlab doctor Check terraform, Proxmox reachability, config.
hlab plan [name|id] Read-only drift report — never applies.
hlab theme [name] List or switch themes.
hlab vm create / hlab ct create Create a VM / container (Terraform).
hlab vm provision <id> Install software / dotfiles (Ansible).
hlab vm list · show · ssh Inspect and connect.
hlab vm start · stop · reboot Power control.
hlab vm migrate · resize Move between nodes; change CPU/RAM/disk.
hlab vm snapshot · snapshots · rollback · snapshot-delete Snapshots.
hlab vm adopt <id> Bring an existing, unmanaged guest under hlab's control.
hlab vm update <id> Re-provision idempotently (--upgrade also upgrades).
hlab vm add-ssh-key <id> Add an SSH key to a running guest.
hlab vm destroy <id> Destroy the guest and its declaration.

hlab ct … mirrors these for LXC containers. For every command, flag, and default, see the full command reference.

Documentation

Status

hlab is stable and in active use. Highlights so far: setup + Proxmox discovery, the create wizard, Terraform create/destroy, Ansible provisioning (a software catalog + dotfiles), a full-screen dashboard TUI, day-2 operations (migrate / snapshots / resize), full LXC support, adopting existing guests, drift detection, idempotent re-provisioning, and a cluster metrics panel.

For the current version see the latest release (or run hlab version); CHANGELOG.md tracks what changed.

Next up: provisioning profiles, state resilience, and backups (needs a NAS/PBS target).

Documentation

Overview

hlab is a CLI/TUI that creates and provisions Proxmox VMs. It discovers infrastructure via the Proxmox API, asks only what cannot be inferred, and orchestrates Terraform (and, later, Ansible) under the hood.

Source Files

View all Source files

Directories

Path Synopsis
Package assets embeds the Terraform workspace, the software catalog and (later) Ansible content into the hlab binary, so the tool is self-contained and distributable.
 Package assets embeds the Terraform workspace, the software catalog and (later) Ansible content into the hlab binary, so the tool is self-contained and distributable.
internal
ansible
Package ansible materializes the embedded Ansible content into the homelab-state workspace and runs ansible-playbook to provision a VM with its selected software.
 Package ansible materializes the embedded Ansible content into the homelab-state workspace and runs ansible-playbook to provision a VM with its selected software.
config
Package config manages hlab's global configuration, stored at ~/.hlab/config.yaml (override the home dir with $HLAB_HOME).
 Package config manages hlab's global configuration, stored at ~/.hlab/config.yaml (override the home dir with $HLAB_HOME).
engine
Package engine holds hlab's presentation-free orchestration: it persists VM declarations and drives Terraform (lifecycle) and Ansible (provisioning) over the homelab-state store.
 Package engine holds hlab's presentation-free orchestration: it persists VM declarations and drives Terraform (lifecycle) and Ansible (provisioning) over the homelab-state store.
plans
Package plans manages hlab's preconfigured VM "plans" (t-shirt sizes such as KVM1/KVM2/KVM4/KVM8).
 Package plans manages hlab's preconfigured VM "plans" (t-shirt sizes such as KVM1/KVM2/KVM4/KVM8).
proxmox
Package proxmox is a tiny client for the Proxmox VE API.
 Package proxmox is a tiny client for the Proxmox VE API.
software
Package software parses the embedded additional-software.yaml catalog used by the wizard's multi-select and (in M2) by the Ansible provisioner.
 Package software parses the embedded additional-software.yaml catalog used by the wizard's multi-select and (in M2) by the Ansible provisioner.
sshutil
Package sshutil holds the small SSH helpers shared by the CLI and the TUI: installing a public key into a live guest's authorized_keys over SSH.
 Package sshutil holds the small SSH helpers shared by the CLI and the TUI: installing a public key into a live guest's authorized_keys over SSH.
state
Package state manages the homelab-state working copy (default ~/.hlab): the versioned, declarative description of every VM hlab manages.
 Package state manages the homelab-state working copy (default ~/.hlab): the versioned, declarative description of every VM hlab manages.
terraform
Package terraform materializes the embedded Terraform workspace into the homelab-state directory, renders the tfvars from VM declarations, and drives the terraform binary (init/plan/apply/destroy/output).
 Package terraform materializes the embedded Terraform workspace into the homelab-state directory, renders the tfvars from VM declarations, and drives the terraform binary (init/plan/apply/destroy/output).
theme
Package theme holds hlab's semantic color palette.
 Package theme holds hlab's semantic color palette.
tui
Package tui implements hlab's full-screen dashboard (milestone M3): a persistent terminal UI that lists the managed VMs and runs the create / provision / setup / destroy flows over internal/engine — the same orchestration the CLI uses.
 Package tui implements hlab's full-screen dashboard (milestone M3): a persistent terminal UI that lists the managed VMs and runs the create / provision / setup / destroy flows over internal/engine — the same orchestration the CLI uses.
wizard
Package wizard implements the interactive `hlab vm create` flow described in docs/wizard.md.
 Package wizard implements the interactive `hlab vm create` flow described in docs/wizard.md.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.