homelab/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Purpose

This is the management container (VMID 102) for Mikkel's homelab infrastructure. Claude Code operates here to assist with homelab management, automation, and maintenance tasks.

Environment

• Container: LXC on Proxmox VE (core.georgsen.dk)
• Network Access: vmbr1 (10.5.0.0/24 internal), Tailscale
• SSH Keys: Pre-installed for accessing other containers/VMs
• User: mikkel (UID 1000, group georgsen GID 1000)
• Python venv: ~/venv (activate with source ~/venv/bin/activate)
• Helper scripts: ~/bin (pve, npm-api, dns)
• Git repos: ~/repos

Living Documentation

homelab-documentation.md is the authoritative reference for all infrastructure details. This file must be kept current:

• Update when infrastructure changes are made
• Update when new services/containers are added
• Update when configurations change
• Update IP addresses, ports, and service mappings as they evolve

Network Topology

Internet ─► vmbr0 (65.108.14.165) ─► NPM (10.5.0.1) ─► Internal services
                                                    ├─ vmbr1: 10.5.0.0/24
                                                    └─ vmbr2: 10.9.1.0/24 (Hetzner vSwitch)
Tailscale mesh connects: PBS, Synology NAS, pve01, pve02, dev containers

Key Infrastructure

Service	IP	Access
NPM (reverse proxy)	10.5.0.1	Admin :81
DNS (Technitium)	10.5.0.2	:5380 or dns.georgsen.dk
PBS (backups)	10.5.0.6	:8007 or pbs.georgsen.dk
Dockge (docker mgmt)	10.5.0.10	:5001
Forgejo (git)	10.5.0.14	:3000 or git.georgsen.dk
Tailscale relay	10.5.0.x	Routes to 10.9.0.0/16

PVE API Access

The ~/bin/pve helper script provides API access to Proxmox:

~/bin/pve list                    # List all VMs/containers
~/bin/pve status <vmid>           # Show status
~/bin/pve start <vmid>            # Start VM/container
~/bin/pve stop <vmid>             # Stop VM/container
~/bin/pve create-ct <vmid> <hostname> <ip> <disk_gb>  # Create container

NPM API Access

The ~/bin/npm-api script manages Nginx Proxy Manager:

~/bin/npm-api --host-list                              # List proxy hosts
~/bin/npm-api --host-search <domain>                   # Search by domain
~/bin/npm-api --host-create <domain> -i <ip> -p <port> # Create proxy host
~/bin/npm-api --host-delete <id>                       # Delete proxy host
~/bin/npm-api --cert-list                              # List SSL certs

Note: SSL cert generation requires manual setup via web UI (http://10.5.0.1:81)

DNS API Access

The ~/bin/dns script manages Technitium DNS (internal zone: lab.georgsen.dk):

~/bin/dns list                     # List all zones
~/bin/dns records [zone]           # List records in zone
~/bin/dns add <name> <ip> [zone]   # Add A record (e.g., dns add myhost 10.5.0.50)
~/bin/dns delete <name> [zone]     # Delete A record
~/bin/dns lookup <name>            # Query DNS

Beszel Dashboard Access

The ~/bin/beszel script manages the server monitoring dashboard:

~/bin/beszel list                        # List all systems
~/bin/beszel status                      # Show system metrics (CPU, RAM, disk)
~/bin/beszel add <name> <host> [port]    # Add a system
~/bin/beszel delete <id>                 # Delete a system

Dashboard URL: https://dashboard.georgsen.dk

Uptime Kuma API Access

The ~/bin/kuma script manages Uptime Kuma monitors:

~/bin/kuma list                           # List all monitors
~/bin/kuma info <id>                      # Show monitor details
~/bin/kuma add-http <name> <url>          # Add HTTP monitor
~/bin/kuma add-port <name> <host> <port>  # Add TCP port monitor
~/bin/kuma add-ping <name> <host>         # Add ping monitor
~/bin/kuma delete <id>                    # Delete monitor
~/bin/kuma pause <id>                     # Pause monitor
~/bin/kuma resume <id>                    # Resume monitor

Common SSH Targets

ssh root@10.5.0.1      # NPM
ssh root@10.5.0.2      # DNS
ssh root@10.5.0.6      # PBS
ssh root@10.5.0.10     # Dockge
ssh root@10.5.0.14     # Forgejo
ssh mikkel@10.5.0.111  # dev container

Important IPs

• Home IP: 83.89.248.247 (static, used for NPM access lists)
• Public IP: 65.108.14.165 (core.georgsen.dk)

Security

• Home IP: 83.89.248.247 (whitelisted everywhere)
• NPM Access List "home_only" (ID 1): Restricts access to home IP only
  • Applied to: dns.georgsen.dk, dockge.georgsen.dk, pbs.georgsen.dk
• Fail2ban: Running on PVE host (core) and Forgejo
  • SSH jail on core, forgejo jail on Forgejo
  • Bans after 5 failed attempts for 24 hours
  • Whitelisted: 127.0.0.1, 10.5.0.0/24, 83.89.248.247
• Firewall (core vmbr0): Blocked ports: 53, 111, 3128, 8006, 8008 (home IP allowed)

Container Management

Update NPM:

ssh root@10.5.0.1 'cd /opt/npm && docker compose pull && docker compose up -d'

Enable ping in unprivileged containers:

Unprivileged LXC containers drop cap_net_raw capability, causing ping to fail with "Operation not permitted". Fix by granting the capability to the ping binary:

# Run inside the container as root
setcap cap_net_raw+ep /bin/ping

# Or from PVE host
ssh root@10.5.0.254 'pct exec <vmid> -- setcap cap_net_raw+ep /bin/ping'

Note: Must be re-applied after iputils-ping package upgrades.

User Preferences

• Python and Batch for scripting
• 256-color terminal retro aesthetic for UIs
• Ask clarifying questions rather than making assumptions
• Prefer understanding root causes over workarounds