Homelab Documentation

Documentation for Hutson's home infrastructure - two Proxmox servers running VMs and containers for home automation, media, development, and AI workloads.

🚀 Quick Start

New to this homelab? Start here:

1. CLAUDE.md - Quick reference guide for common tasks
2. SSH-ACCESS.md - How to connect to all systems
3. IP-ASSIGNMENTS.md - What's at what IP address
4. SERVICES.md - What services are running

Claude Code Session? Read CLAUDE.md first - it's your command center.

📚 Documentation Index

Infrastructure

Document	Description
GATEWAY.md	UniFi gateway monitoring, watchdog services, troubleshooting
VMS.md	Complete VM/LXC inventory, specs, GPU passthrough
HARDWARE.md	Server specs, GPUs, network cards, HBAs
STORAGE.md	ZFS pools, NFS/SMB shares, capacity planning
NETWORK.md	Bridges, VLANs, MTU config, Tailscale VPN
POWER-MANAGEMENT.md	CPU governors, GPU power states, optimizations
UPS.md	UPS configuration, NUT monitoring, power failure handling

Services & Applications

Document	Description
SERVICES.md	Complete service inventory with URLs and credentials
TRAEFIK.md	Reverse proxy setup, adding services, SSL certificates
HOMEASSISTANT.md	Home Assistant API, automations, integrations
SYNCTHING.md	File sync across all devices, API access, troubleshooting
SALTBOX.md	Media automation stack (Plex, *arr apps) (coming soon)

Access & Security

Document	Description
SSH-ACCESS.md	SSH keys, host aliases, password auth, QEMU agent
IP-ASSIGNMENTS.md	Complete IP address assignments for all devices
SECURITY.md	Firewall, access control, certificates (coming soon)

Operations

Document	Description
BACKUP-STRATEGY.md	🚨 Backup strategy, disaster recovery (CRITICAL)
MAINTENANCE.md	Regular procedures, update schedules, testing checklists
MONITORING.md	Health monitoring, alerts, dashboard recommendations
DISASTER-RECOVERY.md	Recovery procedures (coming soon)

Reference

Document	Description
EMC-ENCLOSURE.md	Storage enclosure SES commands, LCC troubleshooting
SHELL-ALIASES.md	ZSH aliases for Claude Code sessions

🖥️ System Overview

Servers

• PVE (10.10.10.120) - Primary Proxmox server

  • AMD Threadripper PRO 3975WX (32-core)
  • 128 GB RAM
  • NVIDIA Quadro P2000 + TITAN RTX

• PVE2 (10.10.10.102) - Secondary Proxmox server

  • AMD Threadripper PRO 3975WX (32-core)
  • 128 GB RAM
  • NVIDIA RTX A6000

Key Services

Service	Location	URL
Proxmox	PVE	https://pve.htsn.io
TrueNAS	VM 100	https://truenas.htsn.io
Plex	Saltbox VM	https://plex.htsn.io
Home Assistant	VM 110	https://homeassistant.htsn.io
Gitea	VM 300	https://git.htsn.io
Pi-hole	CT 200	http://10.10.10.10/admin
Traefik	CT 202	http://10.10.10.250:8080

See IP-ASSIGNMENTS.md for complete list

🔥 Emergency Procedures

Power Failure

1. UPS provides ~15 min runtime at typical load
2. At 2 min remaining, NUT triggers graceful VM shutdown
3. When power returns, servers auto-boot and start VMs in order

See UPS.md for details.

Service Down

# Quick health check (run from Mac Mini)
ssh pve 'qm list'                    # Check VMs on PVE
ssh pve2 'qm list'                   # Check VMs on PVE2
ssh pve 'pct list'                   # Check containers

# Syncthing status
curl -s -H "X-API-Key: oSQSrPnMnrEXuHqjWrRdrvq3TSXesAT5" \
  "http://127.0.0.1:8384/rest/system/connections"

# Restart a VM
ssh pve 'qm stop VMID && qm start VMID'

See CLAUDE.md for complete troubleshooting runbooks.

📞 Getting Help

Claude Code Assistant: Start a session in this directory - all context is available in CLAUDE.md

Key Contacts:

• Homelab Owner: Hutson
• Git Repo: https://git.htsn.io/hutson/homelab-docs
• Local Path: ~/Projects/homelab

🔄 Recent Changes

See CHANGELOG.md (coming soon) or the Changelog section in CLAUDE.md.

📝 Contributing

When updating docs:

1. Keep CLAUDE.md as quick reference only
2. Move detailed content to specialized docs
3. Update cross-references
4. Test all commands before committing
5. Add entries to changelog

cd ~/Projects/homelab
git add -A
git commit -m "Update documentation: <description>"
git push

---

Last Updated: 2026-01-02