Install a node

Add any machine to the cluster in four steps: download, configure, start, verify.

Step 1 — Download the binary

Choose the binary for the machine you are adding. All builds are served directly from this hub — no external download needed.

macOS (Apple Silicon)

arm64

homelab-darwin-arm64 (not built yet)

1 — Download

curl -fsSL http://hub.home.browngregory.com/downloads/bin/homelab-darwin-arm64 -o homelab

2 — Install

chmod +x homelab
sudo mv homelab /usr/local/bin/homelab

3 — Verify

homelab --version

macOS (Intel)

amd64

homelab-darwin-amd64 (not built yet)

1 — Download

curl -fsSL http://hub.home.browngregory.com/downloads/bin/homelab-darwin-amd64 -o homelab

2 — Install

chmod +x homelab
sudo mv homelab /usr/local/bin/homelab

3 — Verify

homelab --version

Linux

amd64

homelab-linux-amd64 (not built yet)

1 — Download

curl -fsSL http://hub.home.browngregory.com/downloads/bin/homelab-linux-amd64 -o homelab

2 — Install

chmod +x homelab
sudo mv homelab /usr/local/bin/homelab

3 — Verify

homelab --version

Windows

amd64

homelab-windows-amd64.exe (not built yet)

1 — Download

curl -fsSL http://hub.home.browngregory.com/downloads/bin/homelab-windows-amd64.exe -o homelab.exe

2 — Install

Move-Item homelab.exe "$Env:ProgramFiles\homelab\homelab.exe"
$p = [Environment]::GetEnvironmentVariable("Path","Machine")
[Environment]::SetEnvironmentVariable("Path","$p;$Env:ProgramFiles\homelab","Machine")

3 — Verify

homelab --version

Step 2 — Configure the node

Create or edit ~/.homelab/homelab.yaml on the new machine and add the hub connection block. The API key comes from Config → API Keys.

~/.homelab/homelab.yaml

cluster:
  hub:
    host: hub.home.browngregory.com
    http_port: 42421
    key: "${HOMELAB_HUB_KEY}"   # set HOMELAB_HUB_KEY in your environment
                                 # or paste the key value directly (keep it secret)

If the hub has no API keys configured (open mode), omit the key line.

Step 3 — Start the daemon

Run once (foreground)

homelab daemon start

Useful for testing. Ctrl-C stops the daemon.

Install as a system service

homelab daemon install
# macOS  → launchd agent (starts on login)
# Linux  → see systemd snippet below
# Windows → Windows Service (starts on boot)

Linux systemd unit

# /etc/systemd/system/homelab.service
[Unit]
Description=homelab daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/homelab daemon start --foreground
Restart=on-failure
User=%i

[Install]
WantedBy=multi-user.target
# Then:
sudo systemctl daemon-reload
sudo systemctl enable --now homelab

Step 4 — Verify the node joined

From any machine on the LAN

homelab cluster status
# → mac-local   live   qwen3:8b (loaded)   VRAM 5.5/8 GB
# → gpu-server  live   idle                VRAM 0/24 GB

Or check the dashboard

The new node should appear in the Dashboard within 30 seconds of starting the daemon. If it stays stale, check that the hub address and key are correct and that port 42421 is reachable from the new machine.

Run the full cluster verify

homelab cluster verify
# Tests LLM, TTS, STT, image gen, and embeddings on every live node.

Or use the Verify page to run and watch results in the browser.

Next steps

View dashboard → Connect your tools → Run cluster verify → Manage API keys →