What it is: Web UI for managing Docker containers, images, volumes, and networks. The control plane for everything running in CT 100.

Notes:

• Use Portainer to inspect container logs, restart services, and update images (pull → recreate)
• All other Docker services are deployed via docker-compose files in /opt/docker/ on CT 100
• Portainer itself is started via a standalone docker run command, not compose

What it is: Self-hosted uptime monitoring dashboard. Pings services on a schedule and alerts via Gotify when something goes down.

Monitored services:

• Proxmox Web UI (192.168.8.221:8006)
• Portainer (192.168.8.100:9443)
• Gotify (192.168.8.100:8070)
• N8N (192.168.8.100:5678)
• Mac Studio ping (192.168.8.180)

Notes:

• Notifications route to Gotify (push to phone)
• Add new monitors from the dashboard — no config file needed

What it is: Self-hosted push notification server. Uptime Kuma and other services send alerts here; the Gotify app on your phone receives them.

Notes:

• Install the Gotify app on iPhone and point it at http://192.168.8.100:8070
• Each sending service (Uptime Kuma, N8N, etc.) needs its own application token — create in the Gotify web UI under Apps
• Messages are stored and browsable in the web UI

What it is: Visual workflow automation engine — think self-hosted Zapier/Make. Connects services together via trigger → action workflows.

Notes:

• Workflows are stored in the data volume — back this up before updating the image
• Can trigger on webhooks, schedules, or incoming messages
• Integrates with Gotify for sending alerts from custom workflows
• Accessible externally via NetBird mesh if a webhook endpoint is needed from off-LAN; for true public webhooks, route via the VPS Caddy at edge01

What it is: Self-hosted music streaming server, Subsonic/OpenSubsonic-compatible. Serves your music library to Feishin on Mac and any Subsonic-compatible app on mobile.

Clients:

• Desktop: Feishin (connects via OpenSubsonic API)
• Mobile: DSub, Symfonium, or any Subsonic app

Notes:

• Library rescans automatically when files change in /mnt/music
• New music lands via the seedbox pipeline: Lidarr → NZBGet → sync-seedbox.sh → /nvmepool/music
• Last.fm scrobbling configured in Navidrome user settings

What it is: Automated music collection manager. Monitors wanted artists/albums, finds them on Usenet via NZBHydra2, and sends download requests to NZBGet on the seedbox.

Pipeline:

1. Daily 4am cron triggers MissingAlbumSearch — Lidarr actively searches all monitored missing albums
2. Lidarr queries Headphones VIP indexer (primary — proper t=music support) and NZBHydra2 (broken for music — altHUB doesn’t support t=music)
3. Matched releases sent to NZBGet on seedbox (tunnel at 192.168.8.221:16789)
4. NZBGet downloads to completed/Music/ on seedbox at ~70 MB/s
5. sync-seedbox.sh (every 2 min) pulls to /BIGGIE/Seedbox/Music/ on Proxmox
6. Lidarr import picks up files and moves to /mnt/music (requires ≥80% MusicBrainz match)
7. Navidrome rescans and adds to library

Notes:

• Image: lscr.io/linuxserver/lidarr:nightly (nightly required for plugin support)
• Quality profile: Lossless (FLAC) preferred
• Release profile blocks: Greatest Hits, Best Of, Collection, Anthology, etc. (prevents import loop)
• 114 monitored artists, ~3,819 missing albums (March 2026)
• Plugins planned: Tidal (TrevTV), Tubifarry (TypNull)
• See Music Pipeline page for full detail

What it is: Self-hosted audiobook and podcast server with a polished web UI and mobile apps.

Notes:

• iOS app available — connects to the local URL on LAN or via NetBird mesh for remote access (use audiobookshelf.edmd.me)
• Supports progress sync across devices
• Podcast feeds can be added directly — no separate podcast app needed
• Metadata fetched from Audible and Google Books automatically

What it is: Book tracking and discovery app — think self-hosted Goodreads backed by the Hardcover catalog.

Notes:

• Uses the Hardcover API for book metadata and cover art
• Track read/reading/want-to-read status
• Separate from Audiobookshelf — this is for physical/ebook tracking, not audio playback

What it is: Book and audiobook search tool that aggregates sources. Proxied outbound through the seedbox SOCKS5 tunnel for exit via Netherlands IP.

Notes:

• The SOCKS5 proxy is provided by seedbox-socks.service (autossh systemd service on CT 100)
• Remote access via NetBird mesh using shelfmark.edmd.me — no port forwarding required
• If searches fail, check that seedbox-socks.service is running: systemctl status seedbox-socks.service on CT 100

What it is: Self-hosted RSS feed aggregator with a clean web UI and API support for mobile clients.

Notes:

• Compatible with Fever and Google Reader APIs — most RSS apps on iOS connect via one of these
• OPML import/export supported for migrating feeds
• Feeds refresh on a configurable schedule (default every hour)

Retired April 2026. Nextcloud on CT100 was decommissioned along with the MariaDB backend container. File-sync is now handled by Syncthing (peer-to-peer, no central server); file-sharing by the SMB share at files.edmd.me (Samba on the VPS, NetBird-only).

The Docker volumes are gone. If you find a reference somewhere to http://192.168.8.100:8280, it’s stale — flag and remove.

Retired April 19, 2026. The Pangolin/Gerbil/Traefik stack on the SSDNodes VPS was decommissioned and replaced by NetBird mesh (/homelab/netbird/). All Newt services on hpve and fpve are gone, the VPS dashboard at pangolin.troglodyteconsulting.com is offline, and the VPS itself has been repurposed for the SMB share at files.edmd.me.

See Pangolin tombstone and the NetBird docs for the current remote-access pattern.

Services running directly on macOS — not containerized.

Notes:

• Hugo Hub serves the bee-hub documentation site during development; rebuild with hugo to update /public
• Life Archive API and MCP server start via launch agents or manual scripts — check ~/scripts/ for startup commands
• Embed server (LM Studio or custom) must be running for Life Archive RAG embeddings to work

Remote Usenet server accessed via SSH tunnels on Proxmox.

Tunnel management: Both NZBGet and NZBHydra2 tunnels run as systemd services on Proxmox (nzbget-tunnel.service, nzbhydra2-tunnel.service). Check with systemctl status nzbget-tunnel on 192.168.8.221.

What it is: Lightweight web-based server management UI — CPU, memory, disk, storage, logs, services, terminal, and updates all in one browser tab. Runs on both Proxmox and the VPS.

Notes:

• Cockpit is socket-activated — cockpit.service shows inactive until you open the URL, which is normal. cockpit.socket is always listening on port 9090.
• Login with the system root credentials
• Useful for checking logs (journalctl), restarting services, monitoring disk/CPU, and running a quick terminal session without SSH
• Self-signed cert — browser will warn on first visit, just accept

What it is: Open-source smart home automation platform. Runs at the Farm (Brownsville, 192.168.0.x subnet).

Remote access:

• Exposed via Pangolin tunnel from Farm Proxmox (192.168.0.191)
• Farm Proxmox runs its own Newt as a systemd service (not Docker)
• Accessible at ha.troglodyteconsulting.com when the Farm tunnel is up

Notes:

• Farm Proxmox (192.168.0.191) is on a separate network and not always reachable from home — use Pangolin remote URL when off-site or if LAN route is unavailable
• Farm also runs its own Portainer (192.168.0.6:9443), Uptime Kuma (192.168.0.6:3001), and Gotify (192.168.0.6:8070)
• HA configuration lives in the Docker data volume on Farm CT 100 — back up before updates

What it is: Self-hosted document management system with OCR, auto-tagging, and full-text search. Runs on the Mac Studio via Docker.

Start/stop:

cd ~/paperless-ngx/docker
docker compose up -d
docker compose down

Consume folder: Drop files into ~/paperless-ngx/consume/ to ingest. Paperless OCRs, tags, and indexes automatically.

Key volumes:

Notes:

• paperless-ai container is stopped — was used for AI auto-tagging, disabled after memory issues
• Integrated with Life Archive — Paperless documents are a source for the RAG pipeline
• Admin login: delgross / see secure notes

flowchart TD
    Client[Client device
Mac / iPhone / iPad]
    NetBird[NetBird mesh
WireGuard P2P + relays]
    OPNsense[OPNsense router
192.168.8.1]
    Pihole[Pi-hole DNS
CT102 192.168.8.53]
    Unbound[Unbound recursive
CT100 :5335]
    Caddy[Caddy reverse proxy
CT103 192.168.8.54]
    Services[Services on CT100
192.168.8.100]
    Immich[CT101 Immich
192.168.8.103]
    Roon[CT105 Roon
192.168.8.105]

    Client -->|DNS query *.edmd.me| Pihole
    Client -->|HTTPS request| OPNsense
    Pihole --> Unbound
    Unbound -->|forward *.edmd.me| Pihole
    OPNsense -->|192.168.8.54| Caddy
    Caddy -->|reverse_proxy| Services
    Caddy -->|reverse_proxy| Immich
    Caddy -->|reverse_proxy| Roon

    Client -.->|off-LAN| NetBird
    NetBird -.->|via hpve subnet route| OPNsense

When DNS is broken, every .edmd.me URL fails. Check Pi-hole first, then Unbound. When DNS works but a specific service is unreachable, the issue is in Caddy or the service itself.

flowchart LR
    subgraph home["Home LAN — 192.168.8.0/24"]
        hpve[hpve
Proxmox]
        homeCTs[CT100-CT105]
        studio[Mac Studio]
        hpve --> homeCTs
    end
    subgraph farm["Farm LAN — 192.168.0.0/24"]
        fpve[fpve
Proxmox]
        farmCTs[CT100-CT103]
        ha[Home Assistant
192.168.0.10]
        fpve --> farmCTs
    end
    subgraph mesh["NetBird mesh"]
        nb[NetBird cloud]
    end

    hpve -.->|peer 100.123.31.199
routes 192.168.8.0/24| nb
    fpve -.->|peer 100.123.49.175
routes 192.168.0.0/24| nb
    studio -.->|peer 100.123.217.253| nb
    nb -.->|advertised routes| studio

Failure pattern: when fpve falls off the mesh, the farm LAN becomes unreachable from home — even though fpve itself is fine inside the farm LAN. The dependency is on fpve being NetBird-connected, not on it being alive.

flowchart TD
    JPR[Just Press Record
Watch / iPhone]
    iCloud[iCloud Drive]
    Studio[Mac Studio]
    Whisper[Whisper large-v3
mlx-whisper]
    Parse[parse-dictation.py
dash-command parser]
    Tasks[TASKS.md]
    Diary[~/Sync/ED/dictation/diary/]
    Tana[Tana #interaction nodes]

    JPR --> iCloud
    iCloud -->|brctl download| Studio
    Studio --> Whisper
    Whisper --> Parse
    Parse --> Tasks
    Parse --> Diary
    Parse --> Tana

    Briefing[daily-briefing
Cowork 04:00]
    ArrHelper[arr-briefing-data.py]
    BackupHelper[homelab-backup-status.py]
    Snapshot[~/.homelab-snapshot.json]
    Email[Gmail msmtp]
    Drafts[Drafts note]
    BriefMd[morning-briefing.md]

    Briefing --> ArrHelper
    Briefing --> BackupHelper
    Briefing --> Snapshot
    Briefing --> Tasks
    Briefing --> Diary
    Briefing --> BriefMd
    Briefing --> Email
    Briefing --> Drafts

    DocSync[doc-sync
launchd 03:00]
    Key[~/.config/anthropic-api-key]
    Transcripts[Yesterday's Claude transcripts]
    Report[~/Sync/ED/.doc-sync-log/.md]

    DocSync --> Key
    DocSync --> Transcripts
    DocSync -->|patches| Tasks
    DocSync -->|patches| Diary
    DocSync --> Report

The briefing reaches 5+ data sources. If any single source is unavailable, the SKILL is hardened to print [source unavailable] and continue — no single failure kills the whole briefing.

These don’t show on the diagrams but matter when something breaks:

• ~/.homelab-snapshot.json is written by com.bee.homelab-snapshot.plist every few minutes. If the launchd job is dead, the snapshot ages out and the briefing’s homelab-health section falls back to live SSH (which is slower and brittle if pve is busy).
• Time synchronization (NTP) matters everywhere — backup timestamps, log alignment between hpve and Mac Studio, doc-sync’s “yesterday” calculation. macOS handles it automatically; pve uses systemd-timesyncd.
• Cloudflare is implicit upstream for DNS resolution outside the LAN, wildcard TLS cert issuance for Caddy, and the edmd.me domain. A Cloudflare account outage breaks new cert renewals (existing certs survive for ~30 days).
• Anthropic API is implicit upstream for doc-sync, the briefing’s prompt assembly, dictation parsing, and most of Cowork. An outage cascades to most automation.
• Syncthing relay infrastructure (run by the Syncthing project) is implicit upstream when home and MacBook can’t establish a direct P2P link. Default-on, free, but if it goes down sync degrades silently.

Authentik provides centralized authentication for homelab services. Instead of each service managing its own login, Caddy checks with Authentik before allowing access. If you’re not authenticated, you get redirected to the Authentik login page at auth.edmd.me. After login, a session cookie valid across all *.edmd.me services keeps you authenticated everywhere.

The authentication flow works like this:

1. User requests https://grafana.edmd.me/
2. Caddy (CT103) sends a forward-auth subrequest to Authentik (CT100:9100) at /outpost.goauthentik.io/auth/caddy
3. Authentik’s embedded outpost checks for a valid session cookie
4. If authenticated: Returns 200 with user identity headers → Caddy proxies to the backend
5. If not authenticated: Returns 302 redirect → user sees the Authentik login at auth.edmd.me
6. After login, Authentik sets a cookie on .edmd.me and redirects back to the original URL
7. Subsequent requests to any *.edmd.me service reuse the same cookie — no re-login needed

Key components:

To protect a service with Authentik, add the forward_auth block before the reverse_proxy in that service’s Caddy handle on CT103:

@grafana host grafana.edmd.me metrics.edmd.me
handle @grafana {
    forward_auth 192.168.8.100:9100 {
        uri /outpost.goauthentik.io/auth/caddy
        copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Entitlements X-Authentik-Email X-Authentik-Name X-Authentik-Uid X-Authentik-Jwt X-Authentik-Meta-Jwks X-Authentik-Meta-Outpost X-Authentik-Meta-Provider X-Authentik-Meta-App X-Authentik-Meta-Version
        trusted_proxies private_ranges
    }
    reverse_proxy 192.168.8.100:3200
}

Adding auth to a new service — step by step:

1. SSH into CT103: ssh root@192.168.8.221 then pct exec 103 -- bash
2. Edit /etc/caddy/Caddyfile
3. Find the service’s handle block
4. Add the forward_auth block (copy from above) immediately before reverse_proxy
5. Validate: caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
6. Reload: caddy reload --config /etc/caddy/Caddyfile
7. Test: visit the service URL — you should get redirected to auth.edmd.me

The copy_headers line passes user identity downstream. Backend services can read X-Authentik-Username, X-Authentik-Email, etc. to know who’s logged in without implementing their own auth.

The trusted_proxies private_ranges line tells Caddy to trust forwarded headers from private IPs (the Authentik server).

The forward_domain mode is what allows a single provider to protect all *.edmd.me services. It sets a cookie on the .edmd.me domain, so once authenticated at any service, you’re authenticated everywhere.

Located at /opt/authentik/docker-compose.yml on CT100:

services:
  authentik-redis:
    image: redis:alpine
    container_name: authentik-redis
    restart: unless-stopped
    command: --save 60 1 --loglevel warning
    volumes:
      - /mnt/container-data/authentik/redis:/data
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 3s
    networks:
      - authentik

  authentik-server:
    image: ghcr.io/goauthentik/server:2025.4
    container_name: authentik-server
    restart: unless-stopped
    command: server
    environment:
      AUTHENTIK_SECRET_KEY: "<redacted>"
      AUTHENTIK_REDIS__HOST: authentik-redis
      AUTHENTIK_POSTGRESQL__HOST: 192.168.8.100
      AUTHENTIK_POSTGRESQL__PORT: 5432
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: "<redacted>"
      AUTHENTIK_HOST: "https://auth.edmd.me"
      AUTHENTIK_HOST_BROWSER: "https://auth.edmd.me"
    volumes:
      - /mnt/container-data/authentik/media:/media
      - /mnt/container-data/authentik/custom-templates:/templates
    ports:
      - "9100:9000"
      - "9444:9443"
    depends_on:
      authentik-redis:
        condition: service_healthy
    networks:
      - authentik

  authentik-worker:
    image: ghcr.io/goauthentik/server:2025.4
    container_name: authentik-worker
    restart: unless-stopped
    command: worker
    environment:
      AUTHENTIK_SECRET_KEY: "<redacted>"
      AUTHENTIK_REDIS__HOST: authentik-redis
      AUTHENTIK_POSTGRESQL__HOST: 192.168.8.100
      AUTHENTIK_POSTGRESQL__PORT: 5432
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: "<redacted>"
      AUTHENTIK_HOST: "https://auth.edmd.me"
      AUTHENTIK_HOST_BROWSER: "https://auth.edmd.me"
    volumes:
      - /mnt/container-data/authentik/media:/media
      - /mnt/container-data/authentik/custom-templates:/templates
      - /mnt/container-data/authentik/certs:/certs
    depends_on:
      authentik-redis:
        condition: service_healthy
    networks:
      - authentik

networks:
  authentik:
    driver: bridge

Important environment variables:

All on /mnt/container-data/authentik/ (nvmepool on CT100):

Ownership matters: Authentik runs as UID 1000, Redis as UID 999. Wrong ownership causes crashes.

Admin interface: https://auth.edmd.me/if/admin/

Common tasks:

API token (for automation scripts): Stored in Vaultwarden. Create new tokens at Admin → Directory → Tokens & App Passwords.

Useful debug commands:

# Check outpost health (from CT100)
docker exec authentik-server ak healthcheck

# View server logs
docker logs --tail 50 authentik-server

# Check outpost endpoint directly
curl -s http://localhost:9100/outpost.goauthentik.io/auth/caddy
# Should return 200 (when called from localhost)

# Test from Caddy's perspective (from CT103)
curl -s -o /dev/null -w '%{http_code}' \
  -H "Host: auth.edmd.me" \
  -H "X-Forwarded-Host: grafana.edmd.me" \
  -H "X-Forwarded-Proto: https" \
  -H "X-Forwarded-Uri: /" \
  http://192.168.8.100:9100/outpost.goauthentik.io/auth/caddy
# Should return 401 (unauthenticated) or 302 (redirect to login)

These are the issues encountered during deployment (May 2026) so they don’t bite again:

1. Brand domain must match external URL. Authentik’s brand/tenant domain field must be set to auth.edmd.me. The default is authentik-default which causes 404s on the outpost.

2. AUTHENTIK_HOST env var is required. Without it, the embedded outpost doesn’t know its external URL and can’t construct redirect URLs. Set it in docker-compose, not just the outpost config.

3. Provider mode matters. forward_single requires one provider per service and matches on the Host header. forward_domain handles all subdomains with one provider using a cookie domain — use this for *.edmd.me.

4. Restart after config changes. The outpost caches its configuration. After changing brand domain, provider mode, or outpost config via API, always docker restart authentik-server.

5. Port 9100 not 9000. Authentik listens on 9000 internally, but we map to 9100 externally because Roon Server uses 9100-9200 on CT105 (no conflict since different container, but avoids confusion with the standard port).

6. PostgreSQL via host IP. The authentik containers run on a custom bridge network (authentik). They can’t resolve other containers by name on the default bridge. Use CT100’s host IP 192.168.8.100 for PostgreSQL since port 5432 is published on all interfaces.

7. Don’t add header_up Host to forward_auth. In forward_domain mode, the outpost needs to see the original Host header to know which domain is being accessed. Caddy’s forward_auth correctly passes it through.

To protect additional services, add the forward_auth block from the Caddy Integration section to their Caddy handle.

Recommended candidates for protection:

• Portainer (admin access to all containers)
• Proxmox web UI (hypervisor control)
• N8N (automation with full system access)
• Prometheus (infrastructure metrics)
• Dozzle (container logs)

Services to leave unprotected:

• Plex (has its own auth, used by Plexamp on mobile)
• Immich (has its own auth, used by mobile app)
• Vaultwarden — retired May 2026; CT104 destroyed. Credentials live in ~/Sync/ED/SECRETS.md. See Vaultwarden tombstone.

deploy-vps.sh runs these steps in order — any failure before Hugo aborts the deploy without touching the live trees:

1. Validate TASKS.md (~/scripts/validate-tasks.sh) — structural check, abort on error.
2. Validate skills (~/scripts/validate-skills.sh) — every SKILL.md frontmatter parses.
3. Regenerate BEE_HUB_INDEX.md (scripts/build-index.py) — walks content/, emits the ~76 KB greppable map at ~/Sync/ED/BEE_HUB_INDEX.md. Also writes content/recent/_index.md with the 40 most recently-edited pages, sorted by mtime descending.
4. Refresh the home-page status block (scripts/build-status.py) — reads ~/Sync/ED/.homelab-snapshot.json, TASKS.md, the doc-sync logs, and the deploy log, then patches the <!-- STATUS-START -->/<!-- STATUS-END --> block in content/_index.md with current state (last deploy, briefing freshness, doc-sync status, active task count, ZFS pool capacities, container counts).
5. Build Ed’s dashboard (content/ed/build-ed-page.sh) — pulls latest briefing + diary + active tasks into content/ed/_index.md.
6. Hugo build in strict mode (--panicOnWarning --printPathWarnings) — aborts deploy on any error (unclosed shortcode, frontmatter parse, missing partial). Previous stale public/ survives if the new build fails.
7. Pagefind indexes public/ into public/pagefind/ — drives the search box in the top-right.
8. rsync to VPS + CT103 — only if all the above succeeded.

• Frontmatter: title: required; subtitle: if it’s a section landing; page_links: for top-of-page nav (label + url, plus external: true for off-site).
• Sidebar: sections use sidebar_sections: for a flat list, or sidebar_groups: for categorized groups (each with title + items: [{url, name}]). The home page (/homelab/) demonstrates sidebar_groups.
• Section shortcode: wrap discrete content blocks in section shortcodes with an id and title. The id becomes the anchor; the title is what shows in the sidebar’s section list.
• Mermaid diagrams: fenced mermaid blocks render on the client. Use sparingly — see /homelab/architecture/ for an example.
• Taxonomies (new): tags: [foo, bar] and status: active|retired|planned in frontmatter generate /tags/<name>/ and /status/<name>/ index pages automatically. Opt-in per page.
• “Last substantive update”: file mtime lies (auto-commits, typo fixes bump it). When a page gets a real content change worth signaling, add a last_substantive_update: YYYY-MM-DD frontmatter field — future Recently Updated views can prefer that signal over mtime.

The site is deployed to two places from the same source tree. Each is independently reachable:

Deployment is one command and updates both in sequence. If one target is unreachable (VPS routing is occasionally flaky), the other still updates.

cd ~/Sync/ED/homelab/bee_hub
bash deploy-vps.sh

What it does:

1. hugo --quiet builds the static site into public/
2. tar czf - public/ streams the build to each target
3. Extracts to /var/www/bee-hub/ on each host
4. Logs to ~/Library/Logs/bee-hub-deploy.log

Automatic deploys: cron runs the script every 30 minutes.

*/30 * * * * /Users/bee/Sync/ED/homelab/bee_hub/deploy-vps.sh

Targets are configured in the script at TARGETS=(...). To add a new target, add user@host:/path to the array. SSH keys are pre-shared via ~/.ssh/id_ed25519.

All content is plain Markdown with YAML frontmatter. Edit any _index.md file and save. The next deploy (manual or the 30-min cron) ships the change to both live hosts.

A persistent Hugo dev server runs on the Mac Studio via launchd, providing live-preview at all times (rebuilds within ~1s on save):

This is separate from the deployed versions at hub.edmd.me and troglodyteconsulting.com. Use it for active authoring and verification; deploy-vps.sh pushes to production.

# Restart the local preview server
launchctl kickstart -k gui/$(id -u)/com.bee.hugo-beehub

# Check status
launchctl print gui/$(id -u)/com.bee.hugo-beehub

# View logs
tail -f /tmp/hugo-beehub.log

Every page is a directory containing an _index.md file. The top-level nav is defined in hugo.toml:

Content tree (homelab section example):

content/homelab/
├── _index.md              — Category landing (sidebar list)
├── proxmox/_index.md      — Proxmox VE reference
├── services/_index.md     — Services directory
├── music-pipeline/_index.md
├── life-archive/_index.md
├── mcp-servers/_index.md
├── bee-hub/_index.md      — This page
└── shelfmark/_index.md

Category landing page — has a sidebar with sub-page links:

title: "Homelab"
subtitle: "Infrastructure, services, and remote access"
sidebar_sections:
  - { url: "/homelab/proxmox/", name: "Proxmox VE" }
sidebar_links:
  - { name: "External Link", url: "https://example.com" }

Individual page — has quick-access link buttons at top:

title: "Music Pipeline"
page_links:
  - { label: "Lidarr", url: "http://192.168.8.100:8686", external: true }
  - { label: "Internal Link", url: "/homelab/services/", external: false }

The bee-theme provides shortcodes for structuring content. All shortcode files live in themes/bee-theme/layouts/shortcodes/.

The app-card shortcode supports a docs parameter that renders a 📖 Docs ↗ link directly on the card — already used throughout the Mac Apps pages.

Edit an existing page: Open content/section/page/_index.md in any editor (BBEdit, VS Code, Obsidian). Hugo hot-reloads within ~1 second.

Add a new page:

mkdir -p ~/Sync/ED/homelab/bee_hub/content/homelab/new-page
# Create _index.md with frontmatter and content
# Add to parent _index.md sidebar_sections list

Add a new nav tab:

1. Create content/new-section/_index.md
2. Add entry to hugo.toml with a name, url, and weight
3. Restart the Hugo service — menu changes need a restart, content changes do not

Can I edit in Obsidian? Yes — all Hugo content is plain Markdown. Open ~/Sync/ED/homelab/bee_hub/content/ as an Obsidian vault. The YAML frontmatter block must stay intact. Hugo shortcodes show as raw text in Obsidian’s preview but edit safely.

For day-to-day edits, deploy-vps.sh handles builds automatically.

To regenerate the static /public/ folder without deploying:

cd ~/Sync/ED/homelab/bee_hub
hugo
# Output goes to /public/

The script reads /Users/bee/tmp-immich-stack/caddy-ct103-Caddyfile, extracts every @matcher host ... entry, and rebuilds a flat alphabetical list inside a folder named edmd.me Services in Brave’s bookmarks bar.

The script quits Brave before editing (Brave overwrites the file in memory), makes a timestamped backup, removes any existing folder with that name, rebuilds it, and relaunches Brave.

To keep bookmarks auto-updated without manual runs, add to crontab -e:

0 */6 * * * /usr/bin/python3 /Users/bee/tmp-immich-stack/sync-bookmarks.py --no-restart >> ~/Library/Logs/sync-bookmarks.log 2>&1

That runs every 6 hours. The --no-restart flag means Brave isn’t interrupted — the bookmarks file is edited in place and Brave picks up the changes on its next read (typically the next launch, or within a minute for the current session).

1. Add the @matcher host newservice.edmd.me + handle @matcher block to /Users/bee/tmp-immich-stack/caddy-ct103-Caddyfile
2. Push to CT103: scp caddy-ct103-Caddyfile root@192.168.8.221:/tmp/ && ssh root@192.168.8.221 'pct push 103 /tmp/caddy-ct103-Caddyfile /etc/caddy/Caddyfile && pct exec 103 -- systemctl reload caddy'
3. Add the Cloudflare A record (script at /Users/bee/tmp-immich-stack/add-cf-records.sh handles multiple at once)
4. Run python3 /Users/bee/tmp-immich-stack/sync-bookmarks.py — or let the cron catch it within 6 hours

• Brave’s bookmark file is Chrome’s format — this same script works unchanged against Chrome/Chromium/Arc with only the path changed
• Brave assigns its own guid and checksum values on load, so the script doesn’t generate them — it lets Brave rebuild them
• IDs are allocated by scanning the entire JSON for the max existing ID and incrementing from there
• Timestamps use Chrome’s “microseconds since 1601-01-01 UTC” format — the script converts Unix epoch to this
• If you manually rearrange/delete items in the folder, the next sync run will wipe your changes and rebuild from the Caddyfile. The folder is machine-managed — use other bookmark folders for ad-hoc bookmarks

Both use the same custom Caddy build: v2.11.2 + github.com/caddy-dns/cloudflare module, built via xcaddy.

Every LAN service has a clean HTTPS URL with real Let’s Encrypt certs. Accessible from any device on the LAN or via NetBird mesh; DNS A records in Cloudflare point *.edmd.me → 192.168.8.54.

Media & Arr Stack — plex.edmd.me, calibre.edmd.me, lidarr.edmd.me, sonarr.edmd.me, radarr.edmd.me, prowlarr.edmd.me, bookshelf.edmd.me, audiobookshelf.edmd.me (alias: audiobooks.edmd.me), navidrome.edmd.me (alias: music.edmd.me), kiwix.edmd.me (alias: wiki.edmd.me)

Automation & Monitoring — n8n.edmd.me, kuma.edmd.me (alias: uptime.edmd.me), gotify.edmd.me (alias: notify.edmd.me), grafana.edmd.me (alias: metrics.edmd.me), prometheus.edmd.me, dozzle.edmd.me (alias: logs.edmd.me)

Reading & Content — freshrss.edmd.me (alias: rss.edmd.me), wallabag.edmd.me (alias: read.edmd.me), immich.edmd.me (alias: photos.edmd.me), shelfmark.edmd.me, aurral.edmd.me

Utilities — convertx.edmd.me (alias: convert.edmd.me), flaresolverr.edmd.me, homepage.edmd.me (alias: home.edmd.me)

Infrastructure Admin — portainer.edmd.me, proxmox.edmd.me (aliases: hpve.edmd.me, pve.edmd.me), cockpit.edmd.me, pihole.edmd.me (alias: dns.edmd.me)

Identity & Auth — auth.edmd.me (Authentik SSO — forward-domain auth for all services above)

Total: 42 service URLs (26 primary hostnames + 16 aliases).

Uses a single wildcard site block *.edmd.me with named matchers (@service) and handle directives. One wildcard cert covers every subdomain, so adding a new service is three lines:

@newservice host newservice.edmd.me
handle @newservice {
    reverse_proxy 192.168.8.100:PORT
}

Then add an A record newservice.edmd.me → 192.168.8.54 in Cloudflare and systemctl reload caddy. Cert is already covered by the existing wildcard.

Multi-host matchers use space-separated hostnames (not commas — Caddy treats the comma as part of the name):

@kuma host kuma.edmd.me uptime.edmd.me

Backends with self-signed certs (Portainer on 9443, Proxmox on 8006, Cockpit on 9090) require tls_insecure_skip_verify:

reverse_proxy https://192.168.8.100:9443 {
    transport http {
        tls_insecure_skip_verify
    }
}

Caddy is the single reverse proxy fronting public-facing services on the VPS. It handles:

• Automatic HTTPS — cert issuance and renewal via Let’s Encrypt. No certbot, no cron jobs, no manual work forever.
• Static file serving — hosts the Bee Hub at troglodyteconsulting.com.
• Reverse proxy — routes subdomains to LAN services via NetBird mesh (once NetBird is set up).
• HTTP/3 support — out of the box on port 443/udp.
• Cloudflare DNS-01 challenge — for wildcard certs on *.edmd.me (via the custom build with the Cloudflare DNS module).

When you add a site block to the Caddyfile:

n8n.troglodyteconsulting.com {
    reverse_proxy 192.168.8.100:5678
}

On systemctl reload caddy, Caddy:

1. Notices the domain is public and has no cert yet
2. Contacts Let’s Encrypt via ACME
3. Proves ownership — HTTP-01 challenge (default) or DNS-01 (for wildcards)
4. Receives and installs the cert
5. Starts serving HTTPS on 443
6. Redirects HTTP → HTTPS automatically

All of that in seconds. Renewals (at 30 days remaining) happen silently in the background. You never touch certs again.

What Caddy handles forever:

• Initial cert request
• Automatic renewal
• OCSP stapling
• Fallback from Let’s Encrypt to ZeroSSL if LE is down
• Modern TLS (1.3, correct ciphers, HSTS)
• Certificate hot-reload without dropping connections

Every site block is independent. The starter Caddyfile looks like:

{
    # Global options
    email doctor@edwarddelgrosso.com
}

# Main Bee Hub site — static files
troglodyteconsulting.com, www.troglodyteconsulting.com {
    root * /var/www/bee-hub
    file_server
    encode gzip zstd
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        -Server
    }
}

# Subdomain reverse-proxy (requires NetBird mesh)
# n8n.troglodyteconsulting.com {
#     reverse_proxy 192.168.8.100:5678
# }

# Wildcard via Cloudflare DNS-01 (needs CF_API_TOKEN)
# *.edmd.me {
#     tls {
#         dns cloudflare {env.CF_API_TOKEN}
#     }
#     @lidarr host lidarr.edmd.me
#     handle @lidarr { reverse_proxy 192.168.8.100:8686 }
# }

# Catch-all 404 for unknown Host headers
:80, :443 {
    respond "Not configured" 404
}

Adding a new service is three lines:

newservice.troglodyteconsulting.com {
    reverse_proxy 192.168.8.100:PORT
}

Then: systemctl reload caddy. Cert issued within seconds, service live.

For *.edmd.me wildcard certs, Caddy uses DNS-01 challenge via Cloudflare’s API.

1. API Token lives in /etc/caddy/cloudflare.env as CF_API_TOKEN=... (mode 600, caddy:caddy ownership)
2. Scope — Edit zone DNS on both edmd.me and troglodyteconsulting.com zones
3. Referenced in Caddyfile as {env.CF_API_TOKEN} inside the tls block:

*.edmd.me {
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
    # ... site blocks ...
}

Creating a new token — dash.cloudflare.com/profile/api-tokens, pick “Edit zone DNS” template, select the target zones.

Rotation — after replacing the token, systemctl reload caddy picks up the new env file.

Test config before reload (always):

caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile

Reload (graceful, no dropped connections):

systemctl reload caddy

Watch cert issuance in real time:

journalctl -u caddy -f | grep -iE 'cert|acme|tls'

List loaded modules (including cloudflare):

caddy list-modules | grep -iE 'cloudflare|dns'

Certificates stored in: /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/

Common troubleshooting:

• No certbot, ever. Caddy manages all ACME interactions internally. Any certbot tutorial you find online does not apply.
• Port 80 must be open for HTTP-01 challenge. UFW allows it on edge01.
• Cloudflare proxy (orange cloud) is OK — DNS-01 doesn’t require the domain to resolve directly to the VPS. HTTP-01 requires it though, so prefer DNS-01 when Cloudflare proxy is on.
• Caddyfile syntax is indentation-loose but block braces matter. Always caddy validate before reload.
• Env vars in Caddyfile use {env.VAR_NAME} syntax — note the dot separator, not underscore.
• Reverse-proxying to LAN services (192.168.8.x) only works over NetBird. Without the mesh, the VPS can’t reach LAN IPs.
• HTTP/3 works out of the box once port 443/udp is open in UFW. No extra config.
• systemctl reload vs restart — always prefer reload. Restart drops in-flight connections; reload does graceful handoff.
• Deploy from Mac uses /Users/bee/Sync/ED/homelab/bee_hub/deploy-vps.sh — now targeting root@172.93.50.184:/var/www/bee-hub. Cron runs every 30 min.
• Cloudflare token rotation after any suspected exposure. Template: Edit zone DNS, both zones.

Chose Caddy because edge01 is primarily a reverse proxy for a handful of LAN services plus the static Bee Hub site. Caddy’s zero-config HTTPS eliminates the certbot-renewal maintenance burden that plagued the previous Traefik/Pangolin setup.

The goal: open a Cowork session on either machine and get the same experience — same skills, same MCPs, same context bundle, same memory graph, same tasks. No “Claude doesn’t know what I’m talking about” on the MacBook.

Six layers that must stay in sync:

Layers 1–5 are fully automatic. Layer 6 requires running sync-cowork-snapshot.sh on the Mac Studio after editing skills — it pushes to the MacBook if reachable.

Four Syncthing folders handle the Mac-to-Mac sync (all bidirectional, no Proxmox relay):

Device IDs:

API keys (for programmatic Syncthing management):

The Claude Desktop app reads its MCP server configuration from ~/Library/Application Support/Claude/claude_desktop_config.json. To keep this in sync, the actual file lives in the Syncthing’d directory and both machines symlink to it:

~/Library/Application Support/Claude/claude_desktop_config.json
  → ~/Sync/ED/config/claude_desktop_config.json  (symlink)

This file defines three MCP servers:

All paths use /Users/bee/.mcp-servers/ (with leading dot). Both machines have the same username (bee) so paths are identical.

All custom MCP servers live in ~/.mcp-servers/. Source code syncs via Syncthing; venvs are built locally per-machine.

Python version requirement: MCP SDK requires Python 3.10+. The MacBook’s system Python is 3.9 (Xcode). All venvs are built with /opt/homebrew/bin/python3 (currently 3.14).

Venv auto-rebuild (MacBook only):

A launchd agent watches ~/.mcp-servers/ and rebuilds venvs when Syncthing delivers new code:

The script only rebuilds venvs that are missing or have a requirements.txt newer than the existing .venv/. It maps server names to their dependencies (farm-data → asyncpg, homelab-snapshot → fastmcp, etc.).

Skills source lives in ~/Sync/ED/skills/ (synced via claude-ed). The plugin is registered as bee-farm-skills in ~/.claude/settings.json with source type directory.

The snapshot problem: Cowork doesn’t read skills from the source directory at session start. It reads from a per-account snapshot cached at:

~/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin/
  8d800cde-a725-4eaf-a5d9-0c44525af93d/
    3364911c-2ed9-4d54-8786-41d805a22426/
      skills/

This snapshot is keyed on stable account+plugin UUIDs and is NOT refreshed by restarting Claude Desktop or reinstalling the plugin. The only way to update it is sync-cowork-snapshot.sh.

After editing any SKILL.md:

~/scripts/sync-cowork-snapshot.sh

This script validates all skills, rsyncs from source to snapshot, and (as of 2026-05-19) pushes the snapshot to the MacBook if it’s reachable. Then open a new Cowork session on both machines.

These files are critical for Claude context and must be present on both machines:

If setting up Claude on a new Mac from scratch:

1. Install prerequisites: brew install syncthing python node
2. Configure Syncthing: Add the four folder syncs (claude-config, claude-ed, mcp-servers, farm-data-sync) pointing to the Mac Studio
3. Wait for initial sync to complete (check Syncthing UI)
4. Symlink the Desktop config:

   ln -sf ~/Sync/ED/config/claude_desktop_config.json \
     ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

5. Build MCP venvs: ~/scripts/rebuild-mcp-venvs.sh
6. Install the venv rebuild launchd agent:

   cp ~/scripts/com.bee.rebuild-mcp-venvs.plist ~/Library/LaunchAgents/
   launchctl load ~/Library/LaunchAgents/com.bee.rebuild-mcp-venvs.plist
   

7. Push the Cowork snapshot: Run sync-cowork-snapshot.sh on the Mac Studio
8. Restart Claude Desktop (Cmd+Q, reopen)

Alternatively, run the all-in-one setup script:

bash ~/Sync/ED/setup-macbook-claude.sh

This handles steps 4–6 automatically (assuming Syncthing is already configured).

“Claude has no MCPs” on the MacBook:

1. Check Syncthing is running: brew services list | grep syncthing
2. Verify ~/Sync/ED/.claude-context.md exists (Syncthing working?)
3. Check ~/.mcp-servers/farm-data/.venv/ exists (venvs built?)
4. Verify the Desktop config symlink: ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json
5. Restart Claude Desktop (Cmd+Q, reopen)

Skills missing in Cowork:

1. Check ~/Sync/ED/skills/ has content (Syncthing working?)
2. Run sync-cowork-snapshot.sh on the Mac Studio
3. Open a NEW Cowork session (existing sessions can’t be fixed mid-flight)

MCP server fails to start:

1. Check the venv exists: ls ~/.mcp-servers/SERVER_NAME/.venv/
2. Check Python version: .venv/bin/python3 --version (must be 3.10+)
3. Rebuild: cd ~/.mcp-servers/SERVER_NAME && rm -rf .venv && ~/scripts/rebuild-mcp-venvs.sh
4. Check network: nc -z 192.168.8.100 5432 (for farm-data — needs CT100 reachable)

Syncthing sync stuck:

1. Check both Syncthing UIs for errors
2. Verify folder IDs match on both machines
3. Check .stignore isn’t filtering the missing files
4. Force rescan: curl -X POST http://localhost:8384/rest/db/scan -H "X-API-Key: KEY" -d 'folder=FOLDER_ID'

Status: Not started — ready to build

Audiobookshelf already supports podcasts natively. Needs a dedicated library directory and podcast feeds configured.

Setup steps:

1. Create podcast storage: nvmepool/podcasts dataset on Proxmox (or subdirectory of existing audiobookshelf mount)
2. Bind mount into CT100 and add to Audiobookshelf docker-compose
3. Create “Podcasts” library in Audiobookshelf UI
4. Add RSS feeds — auto-download new episodes, configurable retention

Podcast feeds to start with (by interest area):

Beekeeping & Pollinators:

• Beekeeping Today Podcast
• Two Bees in a Podcast (UF/IFAS)
• The Bee Informed Podcast
• Pollinator Partnership

Permaculture & Farming:

• The Permaculture Podcast
• The Small Farms Podcast
• Farmer to Farmer
• No-Till Growers
• Growing Farmers

Self-Hosting & Homelab:

• Self-Hosted (Jupiter Broadcasting)
• Homelab Rat
• The Changelog
• Linux Unplugged

Woodworking:

• The Wood Whisperer
• Shop Talk Live (Fine Woodworking)
• The Woodworking Podcast

Nature & Science:

• Ologies (Alie Ward)
• In Defense of Plants
• The Native Plant Podcast

Infrastructure notes:

• Audiobookshelf mobile app supports offline podcast playback
• Episodes auto-delete after configurable retention period
• Can set per-feed download limits (last N episodes)
• Podcast library is separate from audiobook library in Audiobookshelf

Status: Partial — PostGIS farm DB is live (Farm DB docs); downloading the external GIS sources below into it is the remaining work.

Downloadable geospatial data for the 93-acre Brownsville property (Monroe County, Ohio, Zone 6b). All sources are free. Data should be stored and eventually loaded into PostGIS for spatial queries.

Data sources:

How this fits the architecture:

• Download GIS data → Store on nvmepool
• Load into PostGIS (when farm DB is built)
• Overlay with planting zones, sensor locations
• Query: “what soil type is under Zone 3?”
• Grafana GeoJSON panels for visual maps

Storage plan: Create nvmepool/gis dataset or store under nvmepool/sync/ED/farm/gis/. Estimated total: 5-15 GB depending on resolution choices.

Immediate value even before PostGIS:

• Soil survey tells you pH, drainage, and organic matter by location — critical for planting decisions
• Aerial imagery gives you a basemap for planning bed layouts and infrastructure
• LiDAR reveals drainage patterns and slope — important for erosion control and irrigation

Status: Not started — needs Plex library + sourcing strategy

Plex can serve educational video content in a dedicated library separate from movies/TV.

Setup steps:

1. Create nvmepool/courses dataset on Proxmox
2. Bind mount into CT100 → /mnt/courses
3. Add “Courses” library in Plex (type: Other Videos or Movies)
4. Organize by topic: courses/Woodworking/Course Name/, courses/Permaculture/Course Name/, etc.

Content areas:

Woodworking: Hand tool techniques, joinery, finishing, lathe turning, carving, shop setup and tool maintenance.

Permaculture & Land Management: Permaculture Design Certificate (PDC) courses, keyline design, swale construction, food forest establishment, holistic land management.

Beekeeping: Beginning to advanced beekeeping, queen rearing, splits, swarm management, integrated pest management, honey processing and value-added products.

Homesteading / Self-Sufficiency: Fruit tree grafting and pruning, mushroom cultivation, fermentation and food preservation.

Sourcing: Manual acquisition — video courses aren’t handled well by automated tools like the *arr stack. Download, organize into folder structure, drop into the courses library. Plex serves them with metadata, progress tracking, and multi-device playback.

Naming convention:

/mnt/courses/
  Woodworking/
    Hand Tool Essentials/
      01 - Sharpening Fundamentals.mp4
      02 - Basic Joinery.mp4
  Permaculture/
    PDC Course Name/
      01 - Introduction to Permaculture.mp4

Status: Low priority — easy to do anytime

Current Kiwix has only wikipedia_en_simple_all_nopic_2026-02.zim (922 MB). The Biggest/Kiwix mount has plenty of space.

High-value ZIMs to add:

Download from library.kiwix.org. Drop ZIMs into Biggest/Kiwix/, the cron watcher auto-restarts Kiwix to pick them up.

Directus connects to your existing PostgreSQL tables and presents them as editable collections in a polished admin UI. Unlike NocoDB, which is more spreadsheet-shaped, Directus is more form/admin-shaped — better for:

• Editing one record at a time with proper field types
• Managing relationships between tables (foreign keys auto-detected)
• File uploads attached to records
• Role-based access if you want to give helpers read-only or limited-edit access

It does NOT replace your data — it sits on top of farmdb. The Farm MCP server, direct psql, and any other tool see the same tables and the same edits.

All 34 farm tables registered. Top-level collections have proper icons, colors, display templates, and sort orders configured via the Directus API on Apr 30:

The 19 species_* type-specific subtables (annual, aquatic, berry, biennial, bulb, cover_crop, fern, fruit_tree, grass, groundcover, herb, mushroom, nut_tree, perennial, rose, shrub, tree, vegetable, vine) are grouped under “species” in the navigation sidebar with the category icon, so they collapse together and don’t dominate the nav.

• Two UIs editing the same data: Directus and NocoDB both edit farmdb. Don’t use them long-term simultaneously — pick one after a few days of comparison.
• directus_* system tables in farmdb: 30 internal tables sit alongside your 14 farm tables. Mostly harmless but visible in any direct psql session.
• Bootstrap email is in container env: ADMIN_EMAIL=delgross@edwarddelgrosso.com is in the compose env but only matters for first-run user creation. The actual user record was updated to doctor@edwarddelgrosso.com via API and is durable. If the database is ever wiped, the env var would recreate with the old email.

Router/Switch: TP-Link Omada ER8411 (router) + Omada Controller at 192.168.0.2. ISP: Starlink in Bypass Mode; native IPv6 delegated via DHCPv6-PD (/56) to Omada.

All of these have DHCP reservations in Omada (Settings → Wired Networks → LAN → Address Reservation).

Host: 192.168.0.191 (also reachable via NetBird mesh as fpve.netbird.cloud / 100.123.49.175).

LXCs:

SSH: ssh root@192.168.0.191 (on LAN) or ssh root@100.123.49.175 (via NetBird).

Replaced Pangolin on April 19, 2026. Current peers (8 total): hpve, fpve, vps, studio, macbook, iphone, ipad, roon (CT105). See Remote Access for the full peer table with NetBird IPs.

Subnet routes (NetBird dashboard → Networks):

• 192.168.0.0/24 → via fpve (farm LAN)
• 192.168.8.0/24 → via hpve (home LAN)

Distribution group: BeeDifferent (contains all peers allowed cross-site access).

Check fpve status:

ssh root@192.168.0.191 "netbird status"

Restart if needed:

ssh root@192.168.0.191 "systemctl restart netbird"

HA is the automation hub for the Farm — smart plugs, sensors, the Tempest weather station, Zigbee/Z-Wave devices, and Reolink cameras.

Zigbee/Z-Wave coordinators (SLZB over Ethernet):

IPv6 is fully enabled end-to-end at the farm.

• Starlink delegates a /56 to Omada (currently 2605:59ca:2b5f:d300::/56)
• Omada LAN advertises SLAAC+RDNSS for 2605:59ca:2b5f:d300::/64 on vmbr0-equivalent
• fpve picks up a global v6 address via RA

⚠️ Proxmox sysctls are NOT persistent across reboots. After any fpve reboot, manually run:

sysctl -w net.ipv6.conf.vmbr0.accept_ra=2
sysctl -w net.ipv6.conf.vmbr0.autoconf=1
sysctl -w net.ipv6.conf.vmbr0.accept_ra_defrtr=1
sysctl -w net.ipv6.conf.vmbr0.accept_ra_pinfo=1

Or add to /etc/sysctl.d/99-ipv6.conf to make persistent.

Infrastructure projects: solar-powered PoE for remote sensors, Meshtastic nodes for off-grid communication coverage across the property.

On Debian/Proxmox the fd binary is named fdfind to avoid a name collision with another package. On macOS Homebrew installs it as fd.

plocate rebuilds its index nightly via systemd timer.

Config at /etc/updatedb.conf. Timer override at /etc/systemd/system/plocate-updatedb.timer.d/override.conf. Initial run took ~41-53 seconds; subsequent updates are incremental.

To run a fresh index manually: sudo updatedb.

Filename search (instant, uses indexed DB)

locate TASKS.md                   # all matches anywhere
locate -c .mp3                    # count matches only
locate /nvmepool/music            # all paths under one tree
locate -i README                  # case-insensitive
locate -r '\.docker-compose\.ya?ml$'  # regex

Real-time filename search

fd pattern /path                  # macOS — basic search
fdfind pattern /path              # Debian — same, different name
fd -e mkv                         # all .mkv files
fd -t d node_modules              # directories named node_modules
fd -H pattern                     # include hidden files
fd -I pattern                     # ignore .gitignore
fd --max-depth 3 pattern          # limit depth

Content search inside files

rg "TODO" /path                   # find text
rg -i "error" /var/log            # case-insensitive
rg --type yaml "image:"           # only yaml files
rg --type-list                    # see all known types
rg -l "pattern"                   # only print filenames
rg -B 2 -A 5 "pattern"            # 2 lines before, 5 after match
rg --hidden                       # search hidden files

macOS Spotlight (when re-enabled)

mdfind "TASKS"                                  # Spotlight search
mdfind -onlyin /Users/bee/Sync TASKS            # scoped to one folder
mdfind "kMDItemDisplayName == '*music*'cd"      # case-insensitive contains
mdfind "kind:pdf modified:today"                # rich queries
mdutil -s /                                     # check indexing status
sudo mdutil -i on /                             # re-enable indexing

• Looking for a file by name on Linux: locate — sub-second, but up to 24h stale
• Looking for a file you just created: fd — real-time, ignores nothing important
• Looking for text inside files: rg — fast, knows file types, ignores binary
• Looking on macOS: fd for files, rg for content. mdfind only if Spotlight is on
• Filenames with special characters: prefer fd over locate (regex feels nicer)

• hpve: 41-second initial index of nvmepool + mediapool. locate -c container-data returns 778,550 matches in 2.25 seconds. Working.
• CT100: 53-second initial index. locate seedbox-sync.sh returns instantly. Working.
• Mac Studio: fd and rg installed. Spotlight indexing is disabled at the volume level — mdutil -s / reports “Indexing disabled.” mdfind returns no results until Spotlight is re-enabled with sudo mdutil -i on /. fd works fine without it.

FreshRSS aggregates RSS/Atom feeds into a single web-based reader. The instance runs as a Docker container on CT 100 alongside a Readability service for full-text content extraction. Feeds are checked every 30 minutes via built-in cron.

Compose file lives at /opt/freshrss/docker-compose.yml on CT 100. Both services share the freshrss_default network so FreshRSS can reach the Readability container by hostname.

services:
  freshrss:
    image: freshrss/freshrss:latest
    container_name: freshrss
    restart: unless-stopped
    ports:
      - "8180:80"
    volumes:
      - freshrss_data:/var/www/FreshRSS/data
      - freshrss_extensions:/var/www/FreshRSS/extensions
    environment:
      - TZ=America/New_York
      - CRON_MIN=1,31

  readability:
    image: phpdockerio/readability-js-server
    container_name: readability
    restart: unless-stopped

volumes:
  freshrss_data:
  freshrss_extensions:

Volumes:

By default, many RSS feeds only include a truncated summary. FreshRSS uses the Article Full Text (Af_Readability) extension to fetch the complete article content from the original website when new articles arrive. This runs the Fivefilters Readability.php library directly inside the FreshRSS container — no external service required.

How it works:

1. FreshRSS fetches a feed and finds new articles (every 30 min via cron)
2. For each new article in an enabled category, the extension makes an HTTP request to the article’s original URL
3. Readability.php extracts the main article content, stripping navigation, ads, and other clutter
4. The extracted full text replaces the truncated summary in FreshRSS

Configuration: All 5 categories are enabled for full-text extraction. The config is stored in /var/www/FreshRSS/data/users/delgross/config.php as:

'ext_af_readability_categories' => '{"1":true,"2":true,"3":true,"4":true,"5":true}',

Important notes:

• Only applies to new articles fetched after the extension is enabled. Existing truncated articles are not retroactively updated.
• Some websites rate-limit rapid requests. The extension fetches each article URL sequentially without delay, so high-volume feeds from a single site may occasionally have missing content.
• To reprocess old articles for a feed: delete the feed’s articles in FreshRSS, then let the next cron cycle refetch them.

A standalone readability-js-server container is also deployed alongside FreshRSS. This is used by the xExtension-Readable extension (installed but not currently active) and provides an alternative full-text extraction backend via a Node.js API.

This service is available if you want to switch from the built-in Readability.php library to the external readability-js parser. To activate: enable the Readable extension in FreshRSS settings, set the Readability Host to http://readability:3000, and select which feeds/categories to process.

Extensions are stored in the freshrss_extensions Docker volume (host path: /var/lib/docker/volumes/freshrss_freshrss_extensions/_data/).

To install new extensions, clone or copy the extension folder into the extensions volume on CT 100:

cd /var/lib/docker/volumes/freshrss_freshrss_extensions/_data/
git clone https://github.com/<author>/<extension>.git

Total: 7 feeds across 5 categories.

Updating FreshRSS:

cd /opt/freshrss
docker compose pull
docker compose up -d

Backup: User data (config, database, extension settings) lives in the freshrss_data named volume. Back up /var/lib/docker/volumes/freshrss_freshrss_data/_data/ before major updates.

OPML export: FreshRSS supports OPML import/export from the web UI under Settings → Import/Export. Feed URLs remain clean (no rewriting) since full-text retrieval is handled by the extension, not URL manipulation.

Adding full-text to a new category: If you add a new category in FreshRSS, update the ext_af_readability_categories value in /var/www/FreshRSS/data/users/delgross/config.php (inside the container) to include the new category ID, or toggle it on from the extension’s configuration page in the FreshRSS web UI under Settings → Extensions → Article Full Text.

The ha-mcp add-on runs inside Home Assistant OS and exposes 85 tools to Claude Desktop via the Model Context Protocol. Claude can query devices, control entities, manage automations, inspect integrations, and more — all without leaving the chat.

• Add-on: addon_81f33d0f_ha_mcp (v7.5.0)
• URL: http://192.168.0.10:9583/private_<secret-path>
• Auth model: Secret-path-in-URL (no Bearer token). The secret path is generated on first install and persists at /data/secret_path.txt inside the add-on container across restarts.
• Tools: 85 (discovery, device/integration mgmt, state control, CRUD, templates, traces, history, addons, HACS, system, blueprints, camera, todo, bundled docs)

The config block lives in ~/Sync/ED/config/claude_desktop_config.json (symlinked to ~/Library/Application Support/Claude/claude_desktop_config.json on both Mac Studio and MacBook).

"ha-mcp": {
  "command": "npx",
  "args": [
    "-y", "mcp-remote",
    "http://192.168.0.10:9583/private_<secret-path>",
    "--transport", "http-only",
    "--allow-http"
  ]
}

Critical: The --allow-http flag is required because mcp-remote refuses non-HTTPS URLs without it. This was the blocker on initial MacBook setup (2026-05-23).

Claude Desktop (Mac Studio / MacBook)
  → NetBird mesh VPN
  → fpve.netbird.cloud (100.123.49.175)
     routes 192.168.0.0/24 (farm LAN)
  → Home Assistant at 192.168.0.10:9583

HA does not run NetBird itself. Reachability from any NetBird peer goes through fpve’s advertised route for the 192.168.0.0/24 subnet. Both Mac Studio and MacBook must have that route enabled in their NetBird client (NetBird app → Routes → confirm 192.168.0.0/24 is selected).

On the farm LAN (MacBook at Brownsville), HA is reachable directly at 192.168.0.10:9583 — no NetBird needed.

To rotate the secret path:

1. SSH into HA: ssh ha (user delgross, port 22, key ~/.ssh/ha_id_ed25519)
2. Delete the secret file inside the add-on container (path varies by supervisor version)
3. Restart the add-on — it regenerates a new secret path
4. Update claude_desktop_config.json with the new URL on both machines
5. Restart Claude Desktop on both Studio and MacBook

Full consumer map entry in ~/Sync/ED/SECRETS.md.

Claude Desktop log: ~/Library/Logs/Claude/mcp-server-ha-mcp.log

Common issues:

• “HTTPS required” error → missing --allow-http flag in config args
• Connection refused → NetBird route for 192.168.0.0/24 not enabled, or HA is down
• Timeout → fpve (farm Proxmox) is offline or NetBird mesh not converged
• 403 / auth error → secret path changed; check /data/secret_path.txt on HA

Smoke test prompt: “List the areas in Home Assistant” — should return 13 areas (Barn, Garage, Kitchen, etc.)

Replaced the GL.iNet GL-MT3000 (Beryl AX) on April 29, 2026 with OPNsense 25.7.11_9 on dedicated x86 hardware. See the OPNsense page for full configuration.

WAN double-NAT (ISP gateway → OPNsense WAN at 192.168.254.65) blocks IPv6 and inbound UDP 51820 forwarding to NetBird. Both upstream limitations, not OPNsense’s.

DHCP range: .150–.242. Mac Studio is the only static reservation.

LAN client
    │
    ▼
OPNsense Unbound (192.168.8.1:53)
    ├─ edmd.me → forwards to Pi-hole (192.168.8.53)
    └─ everything else → public roots (with DoT)

NetBird peer (mesh)
    │
    ▼
NetBird magic DNS (100.123.255.254)
    └─ forwards everything to Pi-hole (192.168.8.53)

Pi-hole (CT102, 192.168.8.53)
    ├─ ad blocking (StevenBlack list)
    ├─ short names (hpve, portainer, immich, etc.)
    ├─ *.edmd.me → 192.168.8.54 (Caddy)  [via /etc/dnsmasq.d/03-edmd-wildcard.conf]
    └─ everything else → Cloudflare (1.1.1.1) + Quad9

The OPNsense → Pi-hole forward was added to Unbound on Apr 29 2026 to handle clients that query the router directly (some Mac/iOS DNS resolvers do). Without this, those queries would fail because Unbound’s <privateaddress> filter rejects RFC1918 answers from public DNS — see the Pi-hole docs.

See Caddy for full URL aliases. See Services for the master directory.

CT100 outbound traffic exits via WireGuard tunnel to UltraCC NL (added Apr 29 2026). Public IP from CT100’s perspective is 45.86.221.26. The kill-switch firewall blocks all egress if the tunnel drops. See WireGuard tunnel for details.

NetBird daemon runs as netbird.service on hpve, advertising 192.168.8.0/24 to the mesh.

Eeros run in bridge mode behind OPNsense — they handle WiFi only, OPNsense handles routing/DHCP/DNS.

Pangolin was retired Apr 19 2026 and replaced with NetBird mesh. The VPS no longer hosts a Pangolin dashboard.

Farm runs on 192.168.0.x (separate subnet from home’s 192.168.8.x). Connected via NetBird mesh — fpve peer at 192.168.0.191 advertises the 192.168.0.0/24 subnet to the mesh.

See Farm for the full farm inventory.

Life Archive is a full RAG (Retrieval-Augmented Generation) pipeline that indexes ~278K personal records spanning decades — Evernote notes, emails, magazine archives, Tana nodes, and Paperless-NGX documents — into a searchable knowledge base. It runs entirely on the Mac Studio using local embeddings (gte-Qwen2-7B on Apple MPS) and LanceDB for vector storage.

What it answers: “What did I write about X?”, “When did I meet Y?”, “What happened during Z trip?” — any question against a lifetime of personal documents.

Key paths:

Data flow:

1. Source extraction — Raw documents parsed from Evernote exports, email archives, magazine PDFs, Tana JSON, Paperless-NGX API
2. Enrichment — Text cleaning, section splitting, paragraph chunking, QA pair generation
3. Embedding — gte-Qwen2-7B encodes text into dense vectors (local, MPS-accelerated)
4. Storage — LanceDB tables for docs, sections, paragraphs, QA pairs; SQLite for knowledge graph
5. Query — Multi-strategy retrieval with fusion and reranking

Retrieval strategies (all run in parallel per query):

Results from all strategies are fused via Reciprocal Rank Fusion (RRF), then reranked with a cross-encoder model for final ordering.

Four persistent services on Mac Studio, all managed via launchd:

All launchd plists are in ~/Library/LaunchAgents/.

API endpoints (port 8900):

MCP endpoint (port 8901): http://192.168.8.180:8901/mcp — Streamable HTTP transport for Claude Desktop, Claude Code, or any MCP client.

Remote access:

LanceDB (as of 2026-03-12):

Knowledge Graph:

Entity types: person (92,377) · org (85,519) · thing (52,346) · location (46,106)

Source breakdown:

The Life Archive is also available as MCP tools inside Claude Code and Cowork, enabling natural-language queries without the HTTP API.

Two transport modes:

Remote MCP client config (Claude Desktop / Claude Code):

"mcpServers": {
    "life-archive": {
        "url": "http://100.96.128.20:8901/mcp"
    }
}

All scripts live in ~/Sync/ED/life_archive/:

Check service status:

launchctl list | grep beedifferent

Restart embed server:

launchctl kickstart -k gui/$(id -u)/com.beedifferent.embed-server

Restart Life Archive API:

launchctl kickstart -k gui/$(id -u)/com.beedifferent.life-archive-api

Test API health:

curl http://localhost:8900/health

Run a search via API:

curl -X POST http://localhost:8900/search \
  -H "Content-Type: application/json" \
  -d '{"query": "beekeeping notes from 2023"}'

View logs:

tail -f ~/Sync/ED/life_archive/http_api.stdout.log
tail -f ~/Sync/ED/life_archive/http_api.stderr.log

Load new data into LanceDB:

cd ~/Sync/ED/life_archive
.venv/bin/python load_lancedb.py --source <source_name>

Rebuild knowledge graph:

cd ~/Sync/ED/life_archive
.venv/bin/python load_knowledge_graph.py

The knowledge graph is exposed as a live API that any client can query — Claude, Obsidian, Tana, local LLMs, browsers, scripts. Three endpoints provide entity exploration, multi-hop traversal, and search, all with source document links back to the original archive content.

Live endpoints (port 8900):

Web explorer: http://192.168.8.180:1313/kg/ — interactive D3.js force-directed graph backed by the live API.

Example: Explore an entity

curl -X POST http://192.168.8.180:8900/graph/explore \
  -H "Content-Type: application/json" \
  -d '{"entity": "thomas brown", "max_connections": 20, "max_sources": 5}'

Returns: entity info, all connections with relationship labels, source documents with titles and summaries, total document count.

Example: Traverse the graph (2 hops from Colorado)

curl -X POST http://192.168.8.180:8900/graph/traverse \
  -H "Content-Type: application/json" \
  -d '{"entity": "colorado", "depth": 2, "max_per_hop": 15}'

Returns: full subgraph of nodes and edges reachable within N hops. Each node tagged with hop distance from root.

Example: Search entities

curl -X POST http://192.168.8.180:8900/graph/search \
  -H "Content-Type: application/json" \
  -d '{"query": "brown", "entity_type": "person", "limit": 10}'

MCP tools (same functionality): life_archive_graph_explore, life_archive_graph_traverse, life_archive_graph_search — available via stdio and HTTP MCP servers. Any Claude session or MCP-compatible LLM can call these.

Client compatibility:

Key files:

The knowledge graph can be exported to GEXF format for interactive exploration in Gephi or Cosmograph.

Export script: ~/Sync/ED/life_archive/export_kg_gexf.py

Pre-built exports (in ~/Sync/ED/life_archive/exports/):

Color scheme:

Node sizes scale logarithmically by mention count.

Viewing in Gephi:

1. Install: brew install --cask gephi
2. File → Open → choose a .gexf export
3. Layout → ForceAtlas 2 → Run (let settle 30–60 sec) → Stop
4. Appearance → Nodes → Color → Partition → entity_type
5. Statistics → Modularity → Run → then color by modularity class to see communities
6. Use Data Laboratory tab to search/filter entities by name

Viewing in Cosmograph:

1. Go to cosmograph.app
2. Drag and drop the .gexf file
3. WebGL renders instantly — supports the full 276K-node graph

Custom exports:

cd ~/Sync/ED/life_archive

# Only people and orgs
python3 export_kg_gexf.py --types person org

# Entities mentioned 5+ times
python3 export_kg_gexf.py --min-mentions 5

# Top 10,000 by mention count
python3 export_kg_gexf.py --top 10000

Snapshot is from late March 2026; the contextual re-embedding work in particular has been quiet — check ~/Sync/ED/TASKS.md for any newer status before acting on the pending items.

Contextual re-embedding is the most important pending item. All existing embeddings were generated without document-level context prefixed to chunks. New runpod_embed.py adds this (35-50% retrieval improvement). Previous RunPod run (2026-03-17 to 2026-03-21) failed at source 3/7 with OOM. Scripts fixed 2026-03-21 — ready for new pod.

See ~/Sync/ED/TASKS.md for step-by-step next actions.

Some Blu-Ray rips arrive as BDMV folder structures rather than .mkv files. Radarr can’t import these — it only handles single-file containers. MakeMKV converts BDMV folders to .mkv files that Radarr can ingest.

Workflow:

1. BDMV folder lands in /mnt/seedbox/movies/ (e.g. BLENDED/, Inherit.the.Wind.1960.MULTi.COMPLETE.BLURAY-OLDHAM/)
2. Open MakeMKV web UI: File → Open Files → navigate to /storage/
3. Select the main feature title (usually the longest)
4. Output to /output/
5. Move resulting .mkv into /mnt/seedbox/movies/ for Radarr import

The jlesage/makemkv image defaults MAKEMKV_KEY=BETA, which on container start tries to fetch a fresh beta key from forum.makemkv.com. This fetch hangs indefinitely over the WireGuard tunnel (CT100’s outbound goes through UltraCC NL), and the container never finishes initializing.

Fix: explicitly set MAKEMKV_KEY: "" in compose. Empty string skips the key-fetch logic entirely and the container boots normally. The 30-day eval license is fine for occasional use.

services:
  makemkv:
    image: jlesage/makemkv:latest
    container_name: makemkv
    environment:
      MAKEMKV_KEY: ""        # CRITICAL — prevents beta-key fetch hang
      USER_ID: 0
      KEEP_APP_RUNNING: 1
    ports:
      - 5800:5800
    volumes:
      - /mnt/container-data/makemkv/config:/config
      - /mnt/seedbox/movies:/storage:ro
      - /mnt/container-data/makemkv/output:/output

These thirteen are configured and load when Claude Desktop launches. Tools-by-server count is approximate; check each MCP’s list_tools for the live list.

These have working server code but aren’t in claude_desktop_config.json. Wire them up when needed — most have been deferred either because the upstream is redundant (HA covers weather) or because the API costs money.

In addition to the locally-configured 12, each Cowork session ships with a set of “connected” integrations the user has authorized via Cowork — Gmail, Google Calendar, GitHub, Spotify, Drafts, Read/Send iMessages, PDF Tools, Claude in Chrome, Control your Mac (osascript), and others. These appear as deferred tools at session start; load their schemas with ToolSearch before calling.

These are managed by Cowork and not in claude_desktop_config.json.

Path: ~/Library/Application Support/Claude/claude_desktop_config.json Symlink target: ~/Sync/ED/config/claude_desktop_config.json (Syncthing-replicated, so Studio and MacBook share one source of truth).

After editing, Quit Claude Desktop fully (Cmd-Q from the menu bar, not just close the window) and relaunch to reload servers. MCP venvs auto-rebuild on the MacBook via com.bee.rebuild-mcp-venvs.plist when ~/.mcp-servers/ changes.

Health monitor: ~/scripts/check-mcp-health.py runs 6×/day (06:15, 09:15, 12:15, 15:15, 18:15, 21:15) via com.bee.mcp-health-check.plist. Scans each MCP’s log in ~/Library/Logs/Claude/mcp-server-<name>.log for Server transport closed unexpectedly, connect-timeout, fetch-failed, [error] lines in the last 6 hours; pushes a Gotify alert on any failure.

• Claude — surfaces overview
• Claude multi-machine setup — how config syncs between Studio + MacBook
• Tana — tana-local MCP detail
• Farm database — farm-data MCP backing store

Music flows through a fully automated chain: Lidarr searches for wanted albums via Headphones VIP indexer, sends grabs to NZBGet on the remote seedbox, rsync pulls completed downloads to Proxmox, Lidarr imports and organizes them, and Navidrome serves the final library for streaming.

Data flow:

Indexers:

Download client: NZBGet at 192.168.8.221:16789 (SSH tunnel to seedbox port 13036).

Quality profiles: Any, Lossless (preferred), Standard. Set artists to Lossless for FLAC.

Release profile — ignored terms (compilations and greatest hits are blocked to prevent import loop):

• Greatest Hits, Best Of, The Essential, The Very Best
• Collection, Definitive, Complete, Anthology, Ultimate
• YouTube rip, SoundCloud rip, ytrip, camrip, Rock Mix, Rancho Texicano

Track naming format: {Album Title} ({Release Year})/{Artist Name} - {Album Title} - {track:00} - {Track Title}

Lidarr has no built-in scheduled MissingAlbumSearch — this is a known design gap. The RSS sync (every 15 min) only grabs random new releases from the Headphones VIP feed, not library-specific missing albums. A Proxmox cron job compensates:

Trigger MissingAlbumSearch manually:

curl -s -X POST 'http://192.168.8.100:8686/api/v1/command?apikey=3dc17d20ca664be4ac90fb89004f91b8' \
  -H 'Content-Type: application/json' -d '{"name":"MissingAlbumSearch"}'

Beets 2.7.1 is installed on CT 100 at /usr/local/bin/beet. Config at /root/.config/beets/config.yaml. Primary use is importing new music from the seedbox and handling compilations that Lidarr’s 80% threshold rejects.

Plugins: musicbrainz, fetchart, embedart, lastgenre, scrub, chroma

Pipeline script: /usr/local/bin/beet-full-pipeline.sh — DISABLED as of April 13, 2026. The initial bulk import is complete: 2,112 albums / 33,654 tracks / 1.4 TiB across 197 artists. The 30-minute cron was removed because the import had finished but was re-scanning 2,662 folders of duplicates/junk every 3 hours in an infinite loop. 134 potential hi-res/deluxe keepers were preserved in /mnt/seedbox/Music-Duplicates/ for manual review; 658 non-keepers and 1,870 junk-only folders were deleted.

Pipeline behavior:

1. Checks for new files in /mnt/seedbox/Music
2. If found, runs beet import -q /mnt/seedbox/Music to match, tag, and move to /mnt/music
3. Cleans up empty directories left behind
4. If no new files, exits immediately

Manual maintenance commands (run on CT 100 only when needed, not scheduled):

# Fetch missing cover art for albums without artwork
/usr/local/bin/beet fetchart

# Embed cover art into audio file metadata
/usr/local/bin/beet embedart

# Tag genres from Last.fm
/usr/local/bin/beet lastgenre

# Re-catalog any files in /mnt/music not yet in beets DB
/usr/local/bin/beet import -qA /mnt/music

Using beets for compilations (albums blocked by Lidarr’s release profile):

# SSH into CT 100 and run:
/usr/local/bin/beet import /downloads/Music/SomeAlbum/

Beets matches with 15% threshold, auto-fetches art, tags genre from Last.fm, moves to Compilations/ folder. Navidrome picks up automatically.

Two Lidarr plugins are planned to supplement the Usenet pipeline. Both require the nightly branch (already active).

Installing a plugin: System → Plugins in Lidarr UI → paste GitHub URL → Install → Restart.

Tidal auth flow (quirky): Add indexer → enter data path → Test (will error) → Cancel → refresh page → re-open Tidal indexer → copy the OAuth URL → log into Tidal in browser → copy the redirect URL → paste back into Lidarr. Redirect URLs are single-use.

Seedbox state (as of 2026-04-13):

• completed/Music/: Active — consolidated seedbox-sync.sh runs every 15 min, pulls from both nzbget and general complete paths
• NZBGet: idle when queue is empty, average ~70 MB/s when downloading
• Beets import complete — /mnt/seedbox/Music/ is empty and ready for new Lidarr grabs

Pangolin was a single-VPS hub architecture — every packet routed through the VPS. That was fine for admin but meant latency compounded and a VPS outage killed remote access entirely. NetBird gives us:

• Direct P2P between peers whenever network conditions allow
• Relay fallback only when necessary
• Subnet routing — one peer on each LAN advertises the whole LAN to the mesh
• Zero public port exposure — no open ports on the home router required
• Clean client apps for every OS

To add more peers (iPad, MacBook, phone), invite from the dashboard or use a setup key.

Linux (Debian/Ubuntu):

curl -fsSL https://pkgs.netbird.io/install.sh | bash
netbird up --management-url https://api.netbird.io --hostname <peer-name>

You’ll get a one-time auth URL in the terminal — open it in a browser to authorize.

Or with a setup key (for headless provisioning):

netbird up --setup-key <KEY> --hostname <peer-name>

macOS / Windows / iOS / Android: download from netbird.io/download. Sign in with the same account.

Pi-hole on CT102 is registered as a NetBird nameserver, so mesh peers get local DNS automatically:

• *.edmd.me → 192.168.8.54 (Caddy)
• Short names (hpve, portainer, immich, etc.) → resolve directly
• *.netbird.cloud → resolved by NetBird client locally (peer names)

Peers appended netbird.cloud as a search domain, so typing just hpve in a browser reaches hpve.netbird.cloud (the hpve peer’s mesh address).

The hpve peer advertises 192.168.8.0/24 to the mesh. The fpve peer advertises 192.168.0.0/24. Any peer connected can reach any host on either LAN by its local IP address.

Routes are configured in the NetBird dashboard under Network Routes and must be selected on each peer (netbird routes select <route-id>).

NetBird tries paths in this order:

1. Direct P2P over IPv6 — fastest, no NAT issues. Requires IPv6 on both ends.
2. Direct P2P over IPv4 via STUN/ICE — works through most NATs, can fail with strict CGNAT (Starlink).
3. Relayed through NetBird relay servers — always works, adds 30-80ms latency.

Check which path is being used: netbird status --detail shows each peer’s connection_type as P2P or Relayed.

In an ideal home network, two improvements would help direct P2P:

• Enable IPv6 at both ends. Bypasses IPv4 NAT issues entirely.
• Port-forward UDP 51820 on the home router → 192.168.8.221 (hpve). Gives the home peer a stable public endpoint.

At our current home, neither is feasible — the ISP gives OPNsense a private WAN IP (192.168.254.65) behind their managed gateway. We can’t get IPv6 through the upstream gateway, and we can’t open inbound ports on the upstream we don’t control. Until the ISP service tier changes, peers fall back to STUN-punched UDP4 (which works for most paths) or relayed (small latency cost).

In practice this means: peers that are both on residential ISPs with reasonable NAT will reach each other directly via STUN; mobile peers on cellular often relay. Both are functional.

• Auth secret at /opt/nocodb/secrets.env (NC_AUTH_JWT_SECRET, random hex 48). Should be moved to Vaultwarden.
• Telemetry disabled: NC_DISABLE_TELE=true
• Public URL: NC_PUBLIC_URL=https://nocodb.edmd.me set so links emitted by NocoDB use the right domain.
• Critical for private-network DBs: NC_ALLOW_LOCAL_EXTERNAL_DBS=true — without this, NocoDB’s SSRF protection (tightened in v0.301.4 March 2026) blocks connections to RFC1918 addresses like 192.168.8.100:5432. Symptom: “Forbidden host name or IP address” when adding a Data Source. The deprecated SSRF_ALLOWED_DOMAINS env var no longer works.

NocoDB presents a more spreadsheet-shaped UI compared to Directus’s form-shaped admin UI. Strengths:

• Airtable-style grid view with inline editing, sorting, filtering
• Multiple views per table (grid, gallery, kanban, calendar)
• Easier to scan many records at once
• More familiar to non-technical users

Like Directus, it sits on top of farmdb without restructuring data. Edits made in NocoDB are visible in Directus, the Farm MCP, and direct psql.

• License: NocoDB switched to “Sustainable Use License” — fine for personal/homelab use, less open than it was. Directus is BSL but free under usage threshold.
• Two UIs editing the same data: Don’t run Directus and NocoDB long-term simultaneously. Decision deadline: ~1 week of side-by-side use, then commit to one.
• directus_* tables visible: When connecting NocoDB to farmdb, deselect the 30 directus_* system tables during schema import to avoid sidebar clutter.

OPNsense uses Dnsmasq for DHCP, not Kea or ISC dhcpd. (Kea was upgraded 2.x → 3.0.2 during the firmware update but isn’t enabled.)

Why almost nothing has a static reservation

Mac Studio is the only host with a DHCP reservation. We deliberately did NOT add reservations for hpve, the CTs (Pi-hole, Caddy, docker-host, Immich, vaultwarden), or any other LAN device. Reasoning:

• CTs use static IPs configured at the Proxmox level, not via DHCP. CT100 = 192.168.8.100, CT101 = .103, CT102 = .53, CT103 = .54, CT105 = .105 (Roon). (CT104 was retired May 2026.) These are baked into the LXC config (/etc/pve/lxc/<vmid>.conf), so they survive across reboots and don’t depend on the DHCP server at all. Adding a reservation for them would be redundant and only adds a place where the IP could be defined inconsistently.
• hpve uses a static IP configured in /etc/network/interfaces (192.168.8.221). Same reasoning — the host doesn’t ask DHCP for an address.
• Eero mesh nodes are in bridge mode and get whatever DHCP gives them. They’ve never moved off their initial leases (.123, .140, .169, .203, .212), so they’re effectively stable. If they ever do roam, no service depends on a specific eero IP.
• Smart-home devices (Sonos, WiiM Ultra, YouTube TV, Brother printers, Homey, Weather Station) all keep stable leases through normal DHCP renewal. Most have hostnames in mDNS/Bonjour anyway, so we use names not IPs to reach them.

Mac Studio is the exception because it has services bound to a specific IP (Hugo Hub, Paperless-NGX, LM Studio, Life Archive API/MCP) that other hosts and the Bee Hub site link to by IP. Drifting onto a different IP would break those references.

When to revisit: any time we add a service on a non-CT host that other systems reference by IP, the host should get a reservation.

OPNsense’s Unbound is the DNS resolver on port 53. Dnsmasq does DHCP only.

Critical config: Unbound has a <privateaddress> filter that blocks RFC1918 answers from public DNS (default behavior). Cloudflare’s wildcard *.edmd.me → 192.168.8.54 would normally be filtered out and clients would get NXDOMAIN.

The fix is a forward override added Apr 29 2026:

edmd.me → 192.168.8.53:53 (Pi-hole)

Configured via the OPNsense Unbound model (<unboundplus><dots><dot type="forward">). UUID 27b78f0f-57b1-40f7-9169-69cfd6d1d467. Pi-hole then returns the right answer for *.edmd.me.

Without this, Mac/iOS clients that route edmd.me queries to OPNsense (because of the search-domain hint) would fail to resolve — even though Pi-hole has the correct entry.

ssh root@192.168.8.1
configctl firmware poll       # Check for available
configctl firmware update     # Apply all pending updates
# NOTE: NOT 'firmware upgrade' — that's for major version bumps with named target

The Apr 29 firmware run applied 135 packages including:

• Kea: 2.6.3 → 3.0.2 (DHCP — not used; we run Dnsmasq)
• acme.sh: 3.1.1 → 3.1.2
• openssl: → 3.0.18
• bind-tools, krb5, glib, dpinger, filterlog

Reboots automatically when needed. The system regenerates SSH host keys on upgrade — clear ~/.ssh/known_hosts for 192.168.8.1 after upgrades. Authorized keys for root are wiped and must be re-added via web UI: System → Access → Users → root → Authorized keys.

Pre-update XML config backup is saved on the Mac Studio at:

~/homelab-backups/opnsense-orchard-preupdate-YYYYMMDD-HHMMSS.xml

Take a backup before every firmware update:

ssh root@192.168.8.1 'cp /conf/config.xml /tmp/opnsense-config.xml'
scp root@192.168.8.1:/tmp/opnsense-config.xml ~/homelab-backups/opnsense-orchard-$(date +%Y%m%d-%H%M%S).xml