[!WARNING] Installed or last updated HomelabHero before July 18, 2026? Re-run the installer once.

A newer version of npm began blocking package install scripts, which broke the native modules HomelabHero depends on (better-sqlite3, node-pty, bcrypt). On affected boxes, Claude Code installed but would not start, or the web UI and terminal failed to load. Symptoms included:

npm warn allow-scripts ... did not run install scripts

...or Claude simply not responding after an update.

The fix went live July 18, 2026. Re-run the same install command from the video:

apt update && apt install -y curl && \
curl -fsSL https://raw.githubusercontent.com/serversathome/homelabhero/main/install.sh | bash

This is a reinstall, not a reconfigure. It is safe and idempotent: your users, credentials, and registered servers are preserved, and your hh list stays exactly as-is. Nothing gets wiped.

At Step 10 (adding servers), skip it. Your servers are already registered and skipping breaks nothing. Same for the Claude sign-in step if you are already signed in.

After this one re-run, the box updates itself: a weekly job (and hh update) keeps HomelabHero, Node, and your OS current automatically.

HomelabHero

Turn a fresh LXC into an AI homelab command center. One command installs Claude Code plus the claudecodeui web front end, preloaded with context and troubleshooting skills, and wires up a credential broker so Claude can operate your TrueNAS, Proxmox, and Linux machines over SSH without ever seeing a single credential.

Install and update

On a fresh Ubuntu 26.04 LXC, run one command. (The installer is Ubuntu/Debian only: it uses apt, systemd, and visudo. It has not been tested on other distros.) A new LXC usually has only a root user and no curl, so this installs curl first (drop the apt part if you already have curl; add sudo in front of apt if you run as a non-root user):

apt update && apt install -y curl && \
  curl -fsSL https://raw.githubusercontent.com/serversathome/homelabhero/main/install.sh | bash

Then just answer the prompts. The script installs everything, walks you through signing Claude in once, finds and adds your servers, and finishes by handing you a browser link. From that point on you live in the web UI and talk to Claude in plain language ("how is everything doing", "what's running", "restart jellyfin"). You do not need to remember any commands.

The hh commands below still exist for power users and are available in the web UI's built-in terminal, but the normal experience is the browser.

Updating to the latest code

You do not have to do anything. Updates arrive on their own: the weekly job runs hh update, and you can run it yourself any time to force the latest right now:

hh update

That is the one command. It pulls the latest HomelabHero, re-runs the installer non-interactively to refresh everything (CLI and broker, skills, CLAUDE.md, capability docs, Node/npm at the latest LTS, the Claude Code + claudecodeui packages, the service), then patches the OS and runs a health check. It is a reinstall, not a reconfigure and fully idempotent: it keeps your users, your credentials, your registered hosts (your hh list is left exactly as-is), and your ops notes, and skips Claude sign-in if you are already signed in. See Staying up to date for exactly what it does and does not touch.

If you are onboarding a box that predates self-update (no /etc/homelabhero/install.conf), run the install one-liner once to enable it, after which hh update maintains it:

apt update && apt install -y curl && \
  curl -fsSL https://raw.githubusercontent.com/serversathome/homelabhero/main/install.sh | bash

Commands

hh list                      registered hosts (no secrets)
hh run <alias> "<command>"   run a command on a host via the broker
hh test <alias>              connectivity check
hh overview                  read-only vitals sweep across all hosts
hh inventory [alias]         what is RUNNING (VMs, LXCs, containers, apps)
hh diff [alias]              inventory drift vs the last saved snapshot
hh scan [cidr]               discover live hosts on the network
hh doctor                    check the whole setup is healthy
hh provision <alias> <host> [port] [platform] [user]
                             register a host with a generated key (UI-safe);
                             connects as root by default (pass a user to override)

hh add-host                  register a host (operator)
hh rm-host <alias>           remove a host and its credential
hh update                    update everything now: HomelabHero + OS (operator)
hh login                     log Claude Code in as the agent user
hh audit [lines]             review the broker audit log (operator)
hh version                   print the HomelabHero version

The idea

• A control-plane LXC that reaches everything else. It runs the UI and the agent; the workloads stay on your real machines.
• Claude connects only through hh run <alias> "<command>". Same command for TrueNAS, Proxmox, and any Linux host, all reached as a normal shell over SSH.
• Credentials never touch the LLM (see below).

Credential isolation (the important part)

HomelabHero uses privilege separation with a connection broker. Three users:

• your operator account (installs, registers hosts)
• hhagent (runs Claude and the web UI, deliberately low-privilege)
• hhvault (owns every credential, mode 700)

Claude runs as hhagent, which cannot read anything hhvault owns. To reach a host, Claude runs hh run, which invokes the broker hh-connect through a single narrow sudoers rule (hhagent may run only that one program, only as hhvault). The broker looks the host up in the non-secret registry, reads the key or password from the vault, and opens the connection. Claude gets the output, never the secret. Even a fully hijacked agent cannot exfiltrate a credential, because the OS will not let it read the vault and will not let it run anything but the broker as hhvault. The broker also refuses loopback targets and unregistered aliases.

Every brokered command and host registration is recorded to /var/log/homelabhero-broker.log, owned by hhvault and unreadable by the agent, so a hijacked agent can neither read past activity nor erase its own tracks. The log rotates weekly (/etc/logrotate.d/homelabhero). Review it as an operator with hh audit [lines] (needs sudo; the agent cannot read it, by design).

What this protects: credential material never enters Claude's context and cannot be exfiltrated. What it does not do: restrict what Claude may run on a host it is already allowed to reach. That is handled by the approval prompts and confirm-first rule in the ops brain. Two layers, both kept.

Register hosts from a real admin shell (not the Claude web terminal) so the secrets you type never pass through an LLM-driven session.

What Claude knows

• Full platform capability catalogs (ops/capabilities/) for Proxmox, TrueNAS, and Linux, so Claude uses the whole toolset of each system, not just the basics.
• Live inventory via hh inventory: Proxmox VMs and LXCs, TrueNAS apps and pools, and Docker containers wherever they run. hh inventory --save snapshots into ops/inventory/ so state changes show up in git over time.
• Environment-specific notes about your setup in ops/infra/.

Discovery (point and click)

hh scan sweeps your subnet (auto-detected, or pass a CIDR) for live management endpoints and guesses what each is (Proxmox on 8006, SSH on 22, and so on), marking which are already registered. hh scan --add turns that into a picker: choose the numbers you want and it walks you through registering each, pre-filling the address and platform.

Adding servers from the UI

You do not have to shell in to add machines. Just ask Claude in the browser, e.g. "add my TrueNAS at 10.0.0.20". Claude runs hh provision, which registers the host and generates a keypair in the vault, then hands you the public key to paste into the target's admin UI (TrueNAS user SSH keys, Proxmox authorized_keys, or a Linux authorized_keys). No password ever passes through the chat, and the agent never sees the private key. hh test <alias> confirms it once the key is installed. Password-based onboarding stays in the shell-only hh add-host for an admin, since a password can't be handled safely in an LLM session.

Auto-updates and health

One command does everything. A weekly cron job (/etc/cron.d/homelabhero, Sundays at 04:00) runs hh update, logging to /var/log/homelabhero-update.log. Edit that one file to change the schedule, or delete it to turn auto-update off. Run it any time with hh update.

hh update does three things in order:

1. Update HomelabHero itself (see below).
2. Update the OS packages (apt).
3. Run a health check (hh doctor).

Staying up to date with HomelabHero itself

For step 1, hh update git pulls the release you installed from and re-runs the installer non-interactively - so an update produces exactly what a fresh install does: the hh CLI and broker, the shipped skills / CLAUDE.md / capability docs, Node and npm at the latest LTS, the Claude Code + claudecodeui packages (reinstalled with the correct --allow-scripts set so their native modules always build), and the systemd unit. Improvements and fixes pushed to the repo reach existing boxes on their own; nobody has to re-run the installer by hand.

Because it re-runs the real installer, there is no "