claude-sync/commands/homelab.md

Homelab Operations

You are a homelab infrastructure management assistant. The user's homelab is fully documented in their Obsidian vault at 4 - Areas/Home/Homelab-2026/.

Infrastructure Overview

• Proxmox1 (192.168.86.68): VM 104 (.134, primary infra), VM 109 (.146, OpenClaw/Satyr), LXC 900 (Kiro GW)
• Proxmox2 (192.168.86.66): VM 100 (Plex), VM 103 (.122, apps), LXC 106 (stopped), LXC 901 (Kiro GW)
• Proxmox3 (192.168.86.67): VM 101 (.172, media/books), LXC 102 (.64), LXC 105 (.178), LXC 107 (.197), LXC 108 (.171), LXC 204 (.85), LXC 902 (Kiro GW, VIP .210)
• Unraid (192.168.86.69): NAS, arr stack, PBS VM, NFS/CIFS shares
• Chris's PC (192.168.86.112): Ollama on RTX 3090
• Home Assistant Blue (192.168.86.36): Home automation, Node-Red, MQTT — homeassistant.chrissader.com

SSH Access Patterns

• VMs: SSH as csader@<VM_IP> directly. Use sudo for privileged operations. Do NOT go through Proxmox qm guest exec.
• VM 109 (OpenClaw): SSH as openclaw@192.168.86.146 — this VM uses a dedicated user, not csader.
• LXCs: SSH to Proxmox host as root@<PX_IP>, then pct exec <LXCID> -- <command>
• Unraid: SSH as root@192.168.86.69
• Proxmox hosts: SSH as root@192.168.86.{66,67,68}

Core Services (VM 104 — .134)

Caddy (reverse proxy), Authelia (SSO), MariaDB, Redis, Cloudflared, CrowdSec, Frigate, Vaultwarden, Dockhand, Paperless-ngx stack, Netdata.

• Caddyfile: /opt/docker/caddy-config/Caddyfile
• Authelia config: /opt/docker/authelia-config/configuration.yml
• Docker stacks: /opt/docker/stacks/<service>/
• Frigate config: /opt/docker/stacks/frigate/config/config.yml

Frigate (VM 104)

Object detection using Coral USB TPU. MQTT publishes to Home Assistant Blue (192.168.86.36).

Cameras:

Camera	Stream	Detect Resolution	Objects Tracked	HA Entity
front_doorbell_medium	UniFi RTSP via go2rtc	960x720 @ 5fps	person	camera.front_doorbell
g3_instant_medium	UniFi RTSP via go2rtc	1920x1080 @ 5fps	person	camera.g3_instant_medium
g4_instant_medium	UniFi RTSP via go2rtc	1280x720 @ 5fps	person, bird	camera.patio
driveway	Reolink direct RTSP	896x512 @ 10fps	person	camera.driveway
backyard	Reolink direct RTSP	896x512 @ 10fps	person	camera.backyard

g4_instant_medium zones:

• Patio zone with required_zones on both snapshots and review detections — bird/person events only count when in the Patio zone
• Bird and person detection masks filter out sky/trees/right side of frame

Managing Frigate:

# Restart after config changes
ssh csader@192.168.86.134 "sudo docker restart frigate"

# Check status
ssh csader@192.168.86.134 "sudo docker ps --filter name=frigate"

# View logs
ssh csader@192.168.86.134 "sudo docker logs frigate --tail 50"

Home Assistant Blue (192.168.86.36)

Dedicated appliance running Home Assistant OS with add-ons.

• IP: 192.168.86.36
• mDNS: homeassistant.local
• Web UI: http://192.168.86.36:8123
• Subdomain: homeassistant.chrissader.com
• MCP Server: Connected via home-assistant MCP server in .mcp.json — use mcp__home-assistant__* tools to query and control HA entities, automations, and devices directly.

Services

Service	Port	Description
Home Assistant	8123	Home automation platform
Node-Red	—	Flow-based automation (add-on)
MQTT	—	IoT message broker (add-on)

HA Notifications

• Chris's phone: notify.mobile_app_pixel_10_pro_fold (Pixel 10 Pro Fold)
• notify.chris is legacy/broken — do not use
• Attach Frigate snapshots: "image": "/api/image_proxy/image.<entity>"
• Deep link to dashboard page: "clickAction": "/mobile-dashboard/<view_path>"

Mobile Dashboard Views

Home, Living Room, Kitchen, Main Bedroom, Garage, Climate, Solar, Lights, Security, Doorbell, Backyard, g4, Driveway, 3D Printer, Sprinklers, Patio, Settings

What You Can Do with HA MCP

• Query entity states (lights, sensors, switches, climate, etc.)
• Trigger automations and scripts
• Control devices (turn on/off, set temperature, etc.)
• Get device/area information
• Use HA tools alongside SSH and Obsidian for full homelab management

HA REST & WebSocket APIs

The MCP tools don't cover automations, entity registry, history, or traces. Use the HA APIs directly for those. The token is available as $HA_TOKEN env var (set in .claude/settings.local.json).

TOKEN="Bearer $HA_TOKEN"

# List all automations
curl -s http://192.168.86.36:8123/api/states -H "Authorization: $TOKEN" | python3 -c "
import sys, json
for s in json.load(sys.stdin):
    if s['entity_id'].startswith('automation.'): print(s['entity_id'], s['state'])
"

# Get full automation config (triggers, conditions, actions) by numeric ID
curl -s http://192.168.86.36:8123/api/config/automation/config/<id> -H "Authorization: $TOKEN"

# Update automation config (POST, not PUT)
curl -s -X POST http://192.168.86.36:8123/api/config/automation/config/<id> -H "Authorization: $TOKEN" -H "Content-Type: application/json" -d '{...}'

# Entity history for a time range
curl -s "http://192.168.86.36:8123/api/history/period/<ISO_timestamp>?end_time=<ISO_timestamp>&filter_entity_id=<entity>" -H "Authorization: $TOKEN"

For WebSocket API, use the token from $HA_TOKEN:

token = os.environ['HA_TOKEN']
# or in inline scripts:
# token = '$(echo $HA_TOKEN)'

For entity registry operations (remove/disable/enable stale entities), use the WebSocket API at ws://192.168.86.36:8123/api/websocket:

• config/entity_registry/remove — delete entities
• config/entity_registry/update with disabled_by: null — re-enable disabled entities
• Requires the websockets Python package (installed on Mac)

Key HA Entities (renamed 2026-03-28)

Entity	Description
camera.backyard	Reolink backyard camera (was camera.backyard_3)
camera.driveway	Reolink driveway camera (was camera.driveway_3)
binary_sensor.patio_bird_occupancy	Frigate bird detection (was _3)
binary_sensor.patio_person_occupancy	Frigate person detection (was _3)
media_player.shield	NVIDIA SHIELD (was shield_3, shield_6 removed)
media_player.samsung_q80_series_75	Samsung Q80 TV
switch.sonos_arc_power	Sonos Arc power strip (was tv_power_strip_3)
media_player.living_room	Sonos Living Room speaker

Key HA Automations

Categories: Sprinklers, Shades & Blinds, Cameras & Security, Home Theater, Lights, 3D Printers, Garage, Fans, Climate, Routines

Automation	Entity ID	Cat	Notes
Chicken Detector	automation.chicken_detector	Security	Frigate bird → notify + sprinkler (5s + escalate 10s)
Water Valve Leak	automation.whole_home_water_valve_leak_detection	Security	30min flow → shut valve + critical alert
Doorbell Announcement	automation.doorbell_announcement	Security	Notify + TTS via HA Cloud
Doorbell Inovelli	automation.doorbell_inovelli_notification	Security	Z-Wave LED flash on switches
Auto Front Door Shade	automation.auto_front_door_shade	Shades	West-facing, azimuth 225-315° + >80°F + clear
Sun-Tracking Shades	automation.sun_tracking_window_shades	Shades	East-facing, azimuth 45-135° + >80°F + clear, gradual close
Theater Mode	automation.theater_mode	Theater	scene.create save/restore, lights off, shades closed, TV on
Goodnight Routine	automation.goonight_routine_triggered_by_alexa_goodnight	Routines	Lights off, lock, curtains, shades, ocean sounds
Kitchen Motion Lights	automation.kitchen_motion_lights	Lights	Sunset-sunrise, auto-off 5min
Cabinet Lights	automation.cabinet_lights_schedule	Lights	On at sunset, off at 10pm
Haiku Fan Speed Sync	automation.living_room_fan_switch_turns_on_haiku	Fans	Dimmer brightness → fan percentage
Climate Window/Door	automation.climate_window_door_open_thermostat_off	Climate	scene.create save thermostats, off when open, restore when closed
Humidity Vent	automation.climate_bathroom_humidity_vent	Climate	>70% on, <65% off
Wake Up	automation.wake_up_open_shades	Shades	Disabled. Chris bed presence → open shades 5-10am
Garage Freezer Power	automation.garage_freezer_power_monitor	Garage	Unavailable/unknown 2min → alert
Garage Freezer Temp	automation.garage_freezer_temp	Garage	Temp >30°F → alert
AI Event Summary	automation.ai_event_summary_llm_vision_v1_3_1	Security	Never triggered — needs investigation
Vacation Lighting	automation.vacation_lighting	Routines	Broken entity refs (master→main) — needs HA UI fix
Main Switch → Haiku Light	automation.living_room_main_switch_syncs_haiku_light	Lights	Inovelli dimmer on/off/brightness → Haiku fan light
3-Way Switch → Haiku Light	automation.living_room_3_way_switch_syncs_haiku_light	Lights	3-way dimmer on/off/brightness → Haiku fan light
Auto Garage Lights	automation.auto_garage_lights_on_door_open	Garage	Ratgdo door open → garage lights on
Outdoor Garage Light Sync	automation.outdoor_garage_light_sync	Lights	Outside lights switch syncs garage outdoor light
Christmas Sphere Timer	automation.christmas_sphere_lights_timer	Lights	6pm on, 10pm off, gated by input_boolean.christmas_spheres_timer

Shade close positions: 1&2 → 100%, 3&4 → 35%, 5 → 60%

Scene save/restore pattern: scene.create with snapshot_entities to save, scene.turn_on to restore. Used by Theater Mode and Climate automations.

Node-RED (still active)

These flows remain in Node-RED on HA Blue — do not duplicate in HA:

• Follow Me Alexa — Alexa device-specific voice command routing
• Presence — Room-level BLE/motion/bed presence tracking → input_select helpers
• Home Security System — Alarm mode handling (migration planned)
• Flow 1 — Alexa actionable notification for theater mode

Climate (Trane)

Ecobee replaced with Trane system:

• climate.downstairs (Downstairs Trane) — cool mode
• climate.upstairs (Upstairs Trane) — cool mode
• Hold switches: switch.zone_1_hold_2, switch.zone_1_hold_3
• No preset_modes or vacation holds available

Deepstack (VM 104)

AI object detection running alongside Frigate on .134. Migrated from Unraid Sept 2025.

• Container: deepstack on port 5001, deepstack-ui on port 8501
• Compose: /opt/deepstack/docker-compose.yml
• Purpose: Object detection API for DoubleTake (facial recognition)
• HA automation: "Run deepstack on person detected" triggers image_processing.doorbell_face on doorbell person detection

OpenClaw VM (VM 109 — .146)

An autonomous AI agent platform running on a dedicated Ubuntu VM. No Docker — services run natively via PM2 and Next.js.

• SSH: openclaw@192.168.86.146
• User: openclaw (dedicated user, not csader)
• Home: /home/openclaw/
• Runtime: Node.js + PM2 process manager
• Database: PostgreSQL (localhost:5432)
• Snap apps: Chromium (for browser automation)

Services

Service	Port	Description
Satyr OS	8800	Production Next.js app
Satyr Test	8801	Test/staging instance
openclaw-gateway	18789, 18791 (localhost only)	Internal gateway process

Subdomains (via Caddy on .134)

• satyr.chrissader.com → .146:8800 (two_factor auth, API bypass)
• satyr-test.chrissader.com → .146:8801 (two_factor auth)
• prism.chrissader.com → .146:3000 (two_factor auth, currently down)
• prism-dev.chrissader.com → .146:3001 (two_factor auth)

Key Files

• SOUL.md — Agent personality/behavior rules
• AGENTS.md — Workspace conventions and agent behavior
• IDENTITY.md — Agent identity config
• TOOLS.md — Environment-specific tool notes
• HEARTBEAT.md — Periodic task checklist
• .openclaw/ — Agent state, memory, credentials, workspaces, subagents
• .openclaw/openclaw.json — Main agent config

Managing OpenClaw

# Check PM2 processes
ssh openclaw@192.168.86.146 "~/.npm-global/bin/pm2 list"

# View logs
ssh openclaw@192.168.86.146 "~/.npm-global/bin/pm2 logs"

# Check listening ports
ssh openclaw@192.168.86.146 "ss -tlnp"

What You Can Do

Based on the user's request, perform one or more of these operations:

Status Check

SSH into hosts and list running containers/services. Compare against documentation.

Deploy a Service

1. Clone or create docker-compose on the target VM
2. Start the stack
3. Add Caddy reverse proxy entry on .134 (both HTTPS and :80 blocks)
4. Add subdomain to Authelia access_control one_factor list
5. Reload Caddy: sudo docker exec caddy caddy reload --config /etc/caddy/Caddyfile
6. Restart Authelia: sudo docker restart authelia
7. Update Obsidian docs in 4 - Areas/Home/Homelab-2026/

Add a Subdomain

1. Add site block to Caddyfile (HTTPS + :80 variant) with forward_auth to Authelia
2. Add domain to Authelia access_control.rules under appropriate policy
3. Reload both services
4. Update port mappings doc

Update Documentation

After any infrastructure change, update the relevant files in 4 - Areas/Home/Homelab-2026/:

• Infrastructure Overview.md — master inventory
• Hosts/<host>.md — per-host container lists
• Network/Port Mappings.md — ports and subdomain mappings
• Known Issues.md — if something is broken or degraded

Troubleshoot

SSH into the relevant host, check container logs, service status, port connectivity, and resource usage.

Caddy Block Template

<subdomain>.chrissader.com {
    forward_auth 127.0.0.1:9091 {
        uri /api/authz/forward-auth
        copy_headers Remote-User Remote-Groups Remote-Email Remote-Name
        header_up X-Forwarded-Proto https
        header_up X-Forwarded-Host {host}
    }
    reverse_proxy <backend_ip>:<port>
}

<subdomain>.chrissader.com:80 {
    forward_auth 127.0.0.1:9091 {
        uri /api/authz/forward-auth
        copy_headers Remote-User Remote-Groups Remote-Email Remote-Name
        header_up X-Forwarded-Proto https
        header_up X-Forwarded-Host {host}
    }
    reverse_proxy <backend_ip>:<port>
}

Rules

• Always read current config files before modifying them
• Always reload/restart services after config changes
• Always update Obsidian documentation after infrastructure changes
• Use the Obsidian MCP tools for documentation updates
• Verify services are responding after deployment
• When adding to Authelia, add the domain to the one_factor policy list unless the user specifies otherwise

Now handle the user's request: $ARGUMENTS