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)
• Pangolin VPS (pangolin.troglodyteconsulting.com)
• 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 Pangolin if a public webhook endpoint is needed

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. seedbox-sync.sh (every 15 min) pulls to /nvmepool/ingest/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 or via Pangolin tunnel for remote access
• 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)
• Shelfmark is also exposed as a Pangolin private resource — accessible remotely without opening a local port
• 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)

What it is: Self-hosted file sync, sharing, and collaboration platform. Runs with a MariaDB backend.

Notes:

• Database container (nextcloud-db) must be running for Nextcloud to function — they share a Docker network
• Desktop sync client points to http://192.168.8.100:8280
• For remote access, expose via Pangolin — do not open port 8280 to the public internet directly
• Run occ commands via: docker exec -u www-data nextcloud php occ <command>

What it is: The remote access stack running on the SSDNodes VPS. Pangolin manages tunnels and access control, Gerbil handles WireGuard, and Traefik is the reverse proxy.

Architecture:

• VPS runs Pangolin + Gerbil (WireGuard) + Traefik
• Proxmox host (192.168.8.221) runs Newt as a systemd service — creates outbound WireGuard tunnel to VPS
• All LAN devices reachable through the tunnel as Pangolin resources
• Farm Proxmox (192.168.0.191) runs its own Newt for the 192.168.0.x subnet

Private resources (accessible without exposing local ports):

• Proxmox Web UI
• Mac Studio
• Router
• Shelfmark

Notes:

• Newt on Proxmox is a systemd service: systemctl status newt on 192.168.8.221
• To add a new resource: Pangolin Dashboard → Sites → Proxmox → Add Resource
• Pangolin version: Community Edition 1.16.2 — check GitHub releases for updates

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.100:9443), Uptime Kuma (192.168.0.100:3001), and Gotify (192.168.0.100: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

Hugo is a static site generator — it reads Markdown files from content/ and produces a complete HTML site. The dev server watches for file changes and rebuilds automatically, so editing any _index.md shows up in the browser within a second.

Hugo runs as a persistent launchd agent that starts at login and restarts automatically if it crashes.

Service commands:

# Check status
launchctl list | grep hugo

# Stop
launchctl unload ~/Library/LaunchAgents/com.beedifferent.hugo-hub.plist

# Start
launchctl load ~/Library/LaunchAgents/com.beedifferent.hugo-hub.plist

# Restart
launchctl unload ~/Library/LaunchAgents/com.beedifferent.hugo-hub.plist && \
launchctl load ~/Library/LaunchAgents/com.beedifferent.hugo-hub.plist

# View logs
tail -50 ~/Library/Logs/hugo-hub.log
tail -20 ~/Library/Logs/hugo-hub.err.log

Note: Hugo’s dev server caches hugo.toml. Changes to the menu (adding/removing nav tabs) require a service restart to appear. Content changes (_index.md files) hot-reload automatically.

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.

The dev server serves content dynamically — no build step needed for day-to-day editing.

To regenerate the static /public/ folder:

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

The /public/ folder is included in the Mac Studio SYNC directory and gets pulled to Proxmox /nvmepool/sync/ by the nightly sync-mac.sh rsync job.

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.

Network: 192.168.0.x — separate from home (192.168.8.x). Not directly bridged. Access via Pangolin tunnel or physical presence.

Farm connects to the Pangolin VPS via its own Newt instance running as a systemd service on Farm Proxmox (192.168.0.191).

Check tunnel status (when on Farm network or via Proxmox SSH):

ssh root@192.168.0.191 "systemctl status newt"

If tunnel is down:

ssh root@192.168.0.191 "systemctl restart newt"

Farm resources are configured as a separate site in the Pangolin dashboard at pangolin.troglodyteconsulting.com.

Home Assistant is the automation hub for the Farm — smart plugs, sensors, automations, and the weather station feed.

Update HA: Portainer → home-assistant container → Recreate with latest image (or use HA Settings → System → Updates).

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

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.

DHCP range: .100–.249. Static reservations: .180 (Mac Studio) and .221 (Proxmox).

Farm runs on 192.168.0.x (separate from home’s 192.168.8.x). Connected via Pangolin WireGuard tunnel through VPS.

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

Last updated: 2026-03-24

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.

These run as local processes spawned by Claude Desktop via stdio transport.

These are connected via the Claude.ai interface and available in web/desktop sessions.

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Template structure:

{
  "mcpServers": {
    "life-archive": {
      "url": "http://192.168.8.180:8901/mcp"
    },
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"]
    },
    "tana-local": {
      "command": "npx",
      "args": ["-y", "tana-local"],
      "env": {
        "TANA_API_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

After editing, restart Claude Desktop to reload servers.

Tana Local MCP server requires OAuth origin to be set to http://127.0.0.1 (not localhost) in Tana settings → API & Integrations → MCP.

If Tana tools return auth errors, check:

1. OAuth origin is http://127.0.0.1 (not localhost — they’re treated as different origins)
2. API token in config matches the one in Tana settings
3. Restart Claude Desktop after config changes

Known issue: search_nodes has a persistent JSON serialization bug. Workaround: use get_children to navigate nodes instead.

The Life Archive MCP server runs on the Mac Studio and is accessible from any network via Pangolin VPN:

Add to any MCP client config (Claude Code, Cowork, custom) pointing at the appropriate URL.

Server not appearing in Claude:

• Check JSON syntax in config file (no trailing commas, valid quotes)
• Restart Claude Desktop completely (Quit from menu bar, relaunch)
• Check Claude Desktop logs: ~/Library/Logs/Claude/

Life Archive MCP not responding:

launchctl list | grep beedifferent
curl http://localhost:8901/mcp

Tana connection refused:

• Verify tana-local npm package is installed: npm list -g tana-local
• Check API token is correct in config
• OAuth origin must be http://127.0.0.1 in Tana settings

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

Home uses 192.168.8.x, Farm uses 192.168.0.x — separate subnets connected via Pangolin WireGuard tunnels through VPS. Newt runs as a bare-metal systemd service on each site’s Proxmox PVE host (not in Docker).

Managed via Portainer. Running on Proxmox LXC Container 100 (Ubuntu 24.04, 4 cores, 8 GB RAM).

Note: Pangolin Newt no longer runs in Docker on CT 100. It runs as a systemd service on the Proxmox PVE host (192.168.8.221).

Shelfmark networking: All search/download traffic exits via Netherlands seedbox (ismene.usbx.me / 46.232.210.50) through a persistent SOCKS5 tunnel (autossh systemd service seedbox-socks.service on CT 100, port 1080). Shelfmark docker-compose sets PROXY_MODE=socks5 and SOCKS5_PROXY=socks5://172.25.0.1:1080. Accessible remotely only via Pangolin VPN (private resource, not public).

Managed via Portainer. Running on Farm Proxmox LXC Container 100 at 192.168.0.191. Farm subnet is 192.168.0.x (separate from home’s 192.168.8.x).

Note: Pangolin Newt runs as a systemd service on the Farm Proxmox PVE host (192.168.0.191), not in Docker. Home Assistant runs on a separate device at 192.168.0.50.

Requires Pangolin VPN connection for all except VPS direct access. Home uses 192.168.8.x, Farm uses 192.168.0.x. Mac Studio also runs Pangolin client for farm resource access.

VPS

Home (Proxmox Site)

Farm (Brownsville — 192.168.0.x)

Retired (Apr 2026): BIGGIE (Seagate 5TB USB), Big (932GB SSD), Birch (3×4TB RAIDZ1 — pool destroyed, seedbox sync moved to nvmepool/ingest). Nextcloud removed.

Dataset breakdown (nvmepool):

Dataset breakdown (Biggest):

Speedy, TimeMachineOne, Ichabod/Sort, Amigo/delgross, Amigo/Youtube, Possible Delete — all deleted (Apr 7 and Apr 16 2026). Special vdev (Optane 110GB) and cache SSD (465GB) removed from pool.

Dataset breakdown (offsite):

The offsite pool is a single 18.2 TB drive that travels intermittently to the farm for geographic redundancy. Manual sync before each departure.

CT 100 — docker-host (primary media/apps container)

Bind mounts into CT 100:

CT 101 — immich (dedicated Immich photo management host, created Apr 18 2026)

Bind mounts into CT 101:

Docker-specific notes: IPv6 disabled in /etc/docker/daemon.json (required — ghcr.io was causing connection resets because CT101 has no IPv6 default route). DNS set to 8.8.8.8 + 1.1.1.1.

Immich is a self-hosted photo and video management platform (Google Photos alternative). Deployed as a 4-container stack on CT 101 via Docker Compose at /opt/immich/. External library points at /nvmepool/photos (1.4 TB, ~134K files) in read-only mode so originals are never modified. Immich’s own data (uploads, thumbnails, transcoded video, Postgres DB, ML model cache) lives in /nvmepool/container-data/immich/. Admin account created on first web access. DB password stored in /opt/immich/.env. Image tag locked to :release.

Plex serves movies, music, photos, video, and audiobooks from nvmepool. Plexamp (iOS/Mac client) connects to it for music. Uses network_mode: host.

Radarr manages the movie library at /mnt/movies (nvmepool/movies). Searches via Prowlarr indexers, downloads via seedbox, auto-renames and organizes movies for Plex. API key: b117993eb50f465ea485654bc0118861. Compose at /opt/radarr/docker-compose.yml.

Filebot (v5.2.1) is installed as a system package on CT100 (/bin/filebot) for ad-hoc movie/media renaming. Not containerized.

Calibre-Web Automated (CWA) serves the book library from /mnt/books (nvmepool/books). Auto-ingests books dropped into /mnt/books/ingest, auto-converts 28 formats to epub, fetches metadata, detects duplicates. Calibre bundled. Default login: admin / admin123. Image: crocodilestick/calibre-web-automated:latest.

Kiwix serves offline reference content (Wikipedia, Stack Exchange, Project Gutenberg, etc.) from /mnt/kiwix (Biggest/Kiwix — zstd compressed, 5.6TB available). ZIM files are downloaded manually from library.kiwix.org. A cron-based watcher (/usr/local/bin/kiwix-watcher.sh, every 5 min) detects new/changed ZIMs via MD5 hash of the file list and restarts the container to pick them up. Compose at /opt/kiwix/docker-compose.yml. Starter ZIM: wikipedia_en_simple_all_nopic_2026-02.zim (922 MB).

Wallabag is a self-hosted read-it-later service (alternative to Pocket/Instapaper). Stack: Wallabag app + MariaDB 11 (wallabag-db) + Redis 7 (wallabag-redis), all on dedicated wallabag-net bridge network. Compose at /opt/wallabag/docker-compose.yml. Secrets (DB password, Symfony secret) saved in /opt/wallabag/credentials.txt (root-only, chmod 600). Data persisted in named Docker volumes (wallabag-db, wallabag-redis, wallabag-images). Default admin account needs to be created on first visit. Browser extensions for Firefox/Chrome and mobile apps (iOS/Android) support direct capture.

ConvertX is a self-hosted file converter supporting 1000+ formats via FFmpeg, Pandoc, LibreOffice, GraphicsMagick, Inkscape, and more. Compose at /opt/convertx/docker-compose.yml. Data persisted in named volume convertx-data. Account registration disabled after first account creation (ACCOUNT_REGISTRATION=false). Converted files auto-delete after 24 hours (AUTO_DELETE_EVERY_N_HOURS=24). HTTP_ALLOWED=true set for local HTTP access.

All shares configured in /etc/samba/smb.conf (no registry shares). valid users = bee, ownership standardized to bee:bee across all datasets. Apple vfs objects = fruit streams_xattr for macOS compatibility.

Mac Finder access: smb://192.168.8.221/<share_name> or via Network → PVE (Avahi/mDNS advertised).

The seedbox is a remote Usenet server at ismene.usbx.me (IP 46.232.210.50). NZBGet runs on the seedbox and downloads to categorized folders. Two SSH tunnels on Proxmox expose the seedbox UIs locally, and cron scripts pull completed files down.

Data flow:

1. Lidarr/Radarr request albums/movies → send to NZBGet on seedbox
2. NZBGet downloads and sorts into completed/Music/, completed/Books/, etc.
3. seedbox-sync.sh (every 15 min) pulls Music, Books, and general completed downloads to /nvmepool/ingest/
4. Lidarr/Beets process and move finished files to nvmepool/music
5. Plex/Navidrome serve from nvmepool

Mac Studio Sync:

Backups:

Offsite Backup:

A 20TB Seagate Exos (ST20000NM002C, serial ZXA0FLHC) in an ASMT105x USB 3.2 enclosure serves as the offsite backup drive. Formatted as ZFS pool offsite with zstd compression, atime=off, xattr=sa, ashift=12. Negotiates USB 3.2 Gen 2 (10 Gbps SuperSpeed Plus) on Bus 6 Port 1 — critical to plug into the correct USB-A port: the other USB-A ports on the Minisforum Venus are USB 2.0 and will bottleneck transfers to ~42 MB/s. On the USB 3 port, rsync hits ~200 MB/s sustained (bottlenecked by spinning disk sequential write).

Script: /usr/local/bin/offsite-backup.sh — rsync with --delete for incremental updates. Workflow: connect drive → zpool import offsite → offsite-backup.sh → zpool export offsite → disconnect and take offsite.

Health Monitoring (v2, updated Apr 18 2026):

Script: /usr/local/bin/system-health-check.sh — runs every 15 min via /etc/cron.d/system-health-check. Pushes alerts to Gotify. Checks: root disk space, all 4 active ZFS pools (nvmepool, Biggest, backups, offsite — health + suspended + capacity + removed/faulted vdevs), backup age/location, USB hub errors and pool suspension events, snapshot counts, key services (pveproxy, pvedaemon, smbd). Daily summary at 7 AM.

ZFS Maintenance:

Uptime Kuma (http://192.168.8.100:3001) — 61 monitors covering:

Notification chain: Uptime Kuma → Gotify → Telegram bridge → @beenetworkbot

Gotify-Telegram Bridge (Docker, /opt/gotify-telegram/): Polls Gotify every 10 seconds for new messages and forwards to Telegram with priority-based emojis (🔴 critical, 🟡 warning, 📢 info). All Gotify sources are forwarded — Uptime Kuma alerts, health check script alerts, and any other Gotify notifications.

Health Check Script (/usr/local/bin/system-health-check.sh): Runs every 15 min via cron. Monitors root disk space, all 4 ZFS pools (nvmepool, Biggest, backups, offsite — health/suspended/capacity/vdevs), backup age, USB hub errors, snapshot counts, key services. Daily summary at 7 AM. Alerts via Gotify → Telegram. Updated Apr 18 2026.

The Pangolin client on your laptop creates a WireGuard tunnel to the Pangolin VPS. Through that tunnel you can reach every service on the home and farm LANs using their normal IP addresses — nothing is exposed to the public internet.

Laptop (hotel/airport) → WireGuard → Pangolin VPS (172.93.50.184)
    → Newt (Proxmox PVE 192.168.8.221)  → Home LAN (192.168.8.x)
    → Newt (Farm PVE 192.168.0.191)     → Farm LAN (192.168.0.x)

Pangolin uses resource-based access control — clients can only reach resources that an admin has explicitly defined in the dashboard, not entire subnets. This keeps everything private: no public URLs, no open ports on the home router.

At home, disconnect the Pangolin client. It routes 192.168.8.0/24 through the tunnel, which conflicts with direct LAN access. Only connect when you’re away (see At Home vs. Away below).

The Pangolin client is already installed on the MacBook. To connect:

pangolin

Credentials are saved in ~/Library/Application Support/olm-client/config.json from the first run. No need to re-enter them.

Verify it’s working:

ping 192.168.8.180    # Mac Studio
ping 192.168.8.100    # Docker CT 100
ping 192.168.0.50     # Farm Home Assistant

If pings work, open any service URL in a browser. You’re on the network.

Once connected, use the same LAN URLs you’d use at home.

Mac Studio (192.168.8.180)

Docker — CT 100 (192.168.8.100)

Proxmox (192.168.8.221)

Farm — Brownsville (192.168.0.x)

To use Life Archive tools from Claude on your laptop while away, add the MCP HTTP server to your Claude config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Claude Code (~/.claude/settings.json):

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

This gives you life_archive_search, life_archive_entity_lookup, life_archive_temporal_search, and life_archive_stats — same as at home. Requires the Pangolin client to be connected.

Navidrome speaks the Subsonic API. Use a Subsonic-compatible app on your phone with the Pangolin client running.

iOS apps: play:Sub, Amperfy, iSub

Requires the Pangolin client running on the phone (if available) or on the same network as a device running it.

Do this before leaving:

• Disconnect Pangolin client on laptop (don’t need it at home)
• Verify all services are running: http://192.168.8.100:3001 (Uptime Kuma)
• Verify Pangolin Dashboard shows Proxmox Home site Online
• Verify Pangolin Dashboard shows Farm Brownsville site Online
• Add Life Archive MCP config to Claude on laptop (see section above)
• Bookmark this page: http://192.168.8.180:1313/homelab/remote-access/

Once in KC:

• Connect Pangolin client: pangolin
• Test: ping 192.168.8.180
• Open any service URL to confirm

The Pangolin client routes 192.168.8.0/24 through the WireGuard tunnel because the Proxmox Home site defines that as its network. This is by design — it’s how clients reach home services when they’re away.

When you’re already on the home LAN, this creates a conflict: traffic to 192.168.8.x goes through the tunnel instead of staying local. There is no split-tunnel or local-network-detection feature in Pangolin yet (community request pending).

The rule is simple:

• At home (laptop): Disconnect the Pangolin client. You’re already on the LAN.
• Away (KC, travel, anywhere else): Connect the Pangolin client. Everything works by LAN IP through the tunnel.
• Mac Studio: Runs its own Pangolin client permanently so it can reach farm resources (192.168.0.x) from the home LAN. This is separate from the laptop client.

Managed via Portainer. Running on Proxmox LXC Container 100 (Ubuntu 24.04, 4 cores, 16 GB RAM).

Two Seagate 20TB drives (ST20000NE000) in ZFS mirror in the ORICO 9858T3 Thunderbolt 3 enclosure. Special vdev (Optane) and cache SSD removed Apr 7 2026. Pool is now a clean 2-drive mirror. Currently at 89% capacity (16.2 TB used).

Deleted Apr 7: Speedy, TimeMachineOne (4.3TB), Ichabod/Sort (232GB), Amigo/delgross (4TB), Amigo/Youtube (148GB). Pool went from 90% → 41%.

Services on the seedbox are accessed via SSH tunnels through Proxmox (192.168.8.221) and CT 100 (192.168.8.100).

NZBHydra2 runs on the seedbox at port 13033 internally, exposed via SSH tunnel to Proxmox port 15076. Auth: user delgross. The /nzbhydra2 base path is required for all access — bare http://192.168.8.221:15076 returns 404. API key for Lidarr/external access: BM7BCBP0RNBFIIRTJ32LGN9G4M.

Farm runs on the 192.168.0.x subnet (separate from home’s 192.168.8.x). Pangolin routes via WireGuard tunnel through VPS. Farm Proxmox is at 192.168.0.191, Docker CT 100 at 192.168.0.100.

Pangolin Newt runs as a systemd service on Farm Proxmox PVE (192.168.0.191), not in Docker.

Docker volumes:

Previously /books pointed to /opt/shelfmark/books (isolated from Readarr). Changed 2026-03-31 to /mnt/seedbox/Books so Shelfmark downloads land directly in the seedbox Books folder where Readarr can see them.

Docker environment:

PROXY_MODE=socks5
SOCKS5_PROXY=socks5://172.25.0.1:1080
NO_PROXY=localhost,127.0.0.1,192.168.8.*,172.25.0.*
TZ=America/New_York
PUID=0
PGID=0

PUID/PGID set to 0 (root): The seedbox Books folder receives files via rsync with UID 1040, which Shelfmark’s default appuser (UID 1000) cannot write to. Running as root prevents “destination not writable” errors during post-processing. Changed 2026-04-02.

Shelfmark routes all search and download traffic through the seedbox to avoid region-based restrictions. The chain is:

Shelfmark (CT 100 Docker)
    ↓ SOCKS5 to 172.25.0.1:1080 (Docker bridge → CT 100 host)
seedbox-socks.service (autossh, CT 100 systemd)
    ↓ SSH tunnel to delgross@46.232.210.50
ismene.usbx.me (Netherlands exit, UltraSeedbox)
    ↓
Book search sources (Anna's Archive, Libgen, etc.)

Check proxy tunnel status:

# SSH into CT 100 first
ssh root@192.168.8.221
pct exec 100 -- bash
# Then:
systemctl status seedbox-socks.service

Restart proxy tunnel:

systemctl restart seedbox-socks.service

If Shelfmark searches fail or time out: The SOCKS5 tunnel is almost always the culprit. Check the service status above. The tunnel reconnects automatically via autossh, but occasionally needs a manual restart after seedbox connectivity issues.

Prowlarr runs on CT100 as an indexer aggregator, providing Usenet-based book search as an additional release source alongside the direct download sources (Anna’s Archive, Libgen, etc.). Prowlarr routes all traffic through the same SOCKS5 seedbox tunnel as Shelfmark.

Indexers configured:

Shelfmark connection: Enabled in Shelfmark Settings → Prowlarr with auto-expand search on. When Shelfmark searches for a book, it queries both direct_download and prowlarr sources simultaneously. Prowlarr found 115 additional books that direct download sources couldn’t locate.

Note: Prowlarr’s Docker network (prowlarr_default) uses gateway 172.26.0.1, which is different from Shelfmark’s network (shelfmark_default, gateway 172.25.0.1). Both reach the same SOCKS tunnel on 0.0.0.0:1080 on the CT100 host, just via different Docker bridge IPs.

A Python script at ~/Sync/ED/homelab/book_library/kindle_to_shelfmark.py automates bulk importing from the Kindle library into Shelfmark. It reads the Kindle NZB results JSON (1,773 books with titles, authors, and ASINs) and for each book: searches Shelfmark’s Hardcover metadata provider, finds downloadable releases, and queues the best epub for download.

First full run (2026-03-31):

Usage:

cd ~/Sync/ED/homelab/book_library

# Dry run — search only, don't download
python3 kindle_to_shelfmark.py --dry-run --skip-existing

# Full run — queue all downloads
python3 kindle_to_shelfmark.py --skip-existing --delay 5

# Resume after interruption
python3 kindle_to_shelfmark.py --skip-existing --resume

# Process in batches
python3 kindle_to_shelfmark.py --skip-existing --limit 50

Files:

How the script works:

1. For each Kindle book, search Shelfmark metadata API (/api/metadata/search) using title + author
2. Find best match by title word overlap (≥40% threshold)
3. Search for downloadable releases (/api/releases) using the matched provider/book_id
4. Score releases — prefer epub format, reasonable file size (0.5–100 MB)
5. Queue the best release via /api/releases/download
6. Save state after every 20 books for resume capability

Shelfmark has no authentication enabled (auth_mode: none). All API endpoints are accessible without credentials.

Shelfmark searches multiple sources in priority order until a download succeeds.

Fast sources (tried first):

Slow sources (fallback):

Additional sources:

Anna’s Archive donator key is configured in Settings → Download Sources. This unlocks the AA Fast Downloads tier with dedicated servers instead of the free mirrors that crawl at 3-10 KB/s.

DNS-over-HTTPS (DoH) is disabled in Shelfmark’s network config (/opt/shelfmark/config/plugins/network.json, USE_DOH: false). DoH via Quad9 was returning 400 errors for several domains when routed through the SOCKS tunnel, causing all post-processing to fail. System DNS resolution works correctly as a fallback.

Shelfmark is configured as a Pangolin private resource — it’s reachable remotely without opening any public ports. Connect via the Pangolin VPN client and access it at http://192.168.8.100:8084 as if you’re on the home network.

It does not have a public subdomain — intentionally kept private since it’s a search aggregation tool.

Shelfmark is one of three book-related services in the stack:

All three share the seedbox Books folder (nvmepool/ingest → /mnt/seedbox/Books on CT 100). Shelfmark downloads to it, Readarr imports from it, and the existing library of ~512 books lives there.

Syncthing provides real-time, encrypted, peer-to-peer file synchronization without relying on cloud services. It replaces iCloud Drive sync for app configuration files (Typinator, BetterTouchTool, etc.) which proved unreliable — iCloud aggressively evicts files, struggles with frequently-updated small configs, and silently creates conflict copies instead of merging.

Topology: Hub-and-spoke

Both Macs sync exclusively to Proxmox. They do not connect to each other directly. This means changes sync even when one Mac is asleep or powered off — Proxmox holds the canonical copy and relays changes when the other Mac comes online.

Data flow:

Mac Studio  ←→  Proxmox (always-on hub)  ←→  MacBook
                     ↓
              /nvmepool/sync/SyncConfigs
              (canonical copy on ZFS)

Device IDs:

All devices have autoAcceptFolders: true to simplify adding new shared folders.

Folder paths per device:

All folders use Send & Receive mode — changes on any device propagate to all others via Proxmox.

Proxmox (Debian):

Start/stop/restart:

systemctl start syncthing@root
systemctl stop syncthing@root
systemctl restart syncthing@root
systemctl status syncthing@root

Mac Studio (macOS):

Start/stop/restart:

brew services start syncthing
brew services stop syncthing
brew services restart syncthing
brew services list | grep syncthing

MacBook (macOS):

Same brew services commands as Mac Studio.

Syncthing uses three ports. All were opened on Proxmox via UFW:

On the Macs, no firewall changes are needed — macOS will prompt on first run and Syncthing only listens on localhost for the web UI.

Global discovery and relaying are enabled by default but not needed on the LAN. All devices are configured with explicit tcp://IP:22000 addresses for direct LAN connections. Global discovery and relaying serve as fallback if a device connects from outside the home network.

The primary use case is syncing app configs between both Macs, replacing unreliable iCloud sync.

Typinator:

1. Quit Typinator on both Macs
2. Open Typinator Preferences → Advanced → Data Folder
3. Point it at ~/Sync/SyncConfigs/Typinator/
4. Do the same on the other Mac
5. Relaunch — configs now sync via Syncthing

BetterTouchTool:

1. Open BTT Preferences → Sync
2. Set the sync folder to ~/Sync/SyncConfigs/BTT/
3. Repeat on the other Mac

Adding new apps:

For apps with a built-in “data folder” or “sync folder” setting, point it at a subfolder inside ~/Sync/SyncConfigs/. For apps without a custom path setting, use a symbolic link:

# Quit the app first, then:
mv ~/Library/Application\ Support/AppName ~/Sync/SyncConfigs/AppName
ln -s ~/Sync/SyncConfigs/AppName ~/Library/Application\ Support/AppName

Note: Sandboxed App Store apps may not follow symlinks. Check that the app works after symlinking before relying on it.

Syncthing is included in the Proxmox health monitoring system. The system-health-check.sh script (runs every 15 minutes, pushes to Gotify) monitors:

• ZFS pool health for nvmepool (where SyncConfigs lives)
• Disk space on all pools
• Proxmox service availability

The Syncthing web UIs on each device also show connection status, sync progress, and any file conflicts.

Gotify alert configuration:

Device shows “Disconnected”:

1. Check if Syncthing is running on the remote device (brew services list | grep syncthing or systemctl status syncthing@root)
2. Verify the device address is set to tcp://IP:22000 (not just dynamic)
3. Check UFW on Proxmox: ufw status | grep -E '22000|21027'
4. Restart Syncthing: brew services restart syncthing or systemctl restart syncthing@root

Files not syncing:

1. Check the Syncthing web UI for errors or conflicts
2. Verify the folder path exists on both devices
3. Check folder type is “Send & Receive” on all devices
4. Look for .stignore files that might be filtering content

Conflict files:

Syncthing creates .sync-conflict-YYYYMMDD-HHMMSS files when the same file is modified on multiple devices simultaneously. Resolve by keeping the correct version and deleting the conflict copy.

Reset a device’s Syncthing config:

# Mac (will regenerate on next start)
brew services stop syncthing
rm -rf ~/Library/Application\ Support/Syncthing/
brew services start syncthing

# Proxmox
systemctl stop syncthing@root
rm -rf /root/.local/state/syncthing/
systemctl start syncthing@root

After resetting, you’ll need to re-add devices and shared folders.

Problem: Typinator and BetterTouchTool configuration files were not syncing reliably between Mac Studio and MacBook despite using their built-in iCloud sync. iCloud Drive was identified as the root cause — it aggressively evicts files to free local storage, handles frequently-updated small files poorly, and creates silent conflict copies.

Solution: Syncthing was deployed with Proxmox as the always-on hub. This provides: real-time LAN sync without cloud dependency, no file eviction, proper conflict detection with visible conflict files, and ZFS-backed storage on the hub with automatic snapshots every 15 minutes.

Why not direct Mac-to-Mac sync: Both Macs would need to be powered on simultaneously for sync to occur. With Proxmox as the hub, one Mac can be off — changes queue on Proxmox and sync when the other Mac comes online.

Installed: March 27, 2026.