DEV Community: Josh Hall

Deploy the Arr Stack with Docker Compose (Prowlarr, Radarr, Sonarr)

Josh Hall — Thu, 24 Sep 2026 00:47:19 +0000

The short version: put your downloads and your media library under one shared root (/data), mount that same root into every container, and run only the torrent client behind a VPN container. Get the folder layout right and every import is an instant hardlink; get it wrong and every import is a slow copy that doubles your disk usage. Everything below is one Compose file plus three connections in the web UIs.

Cross-post from Peira Labs. Full version with screenshots at every step: peira.dev/articles/arr-stack-docker-deploy

New to the stack? Start with the concepts: What Is the Arr Stack? Sonarr, Radarr, and Prowlarr Explained.

Lawful use: this automates media you have the rights to, such as your own rips, DRM-free purchases, home video, Linux ISOs, and public-domain or Creative Commons releases. Downloading copyrighted material you haven't paid for is illegal in most places, and it isn't what this guide teaches.

1. Get the folder layout right first

This is the single most important decision in the build, and the one you can't easily fix later. When downloads and media sit on the same filesystem, Radarr and Sonarr import a finished download as a hardlink: a second directory entry pointing at the same data on disk. It appears in your library instantly, costs no extra space, and the original keeps seeding. Split them into separate mounts and the containers see two filesystems, so every import falls back to copy-and-delete.

The TRaSH Guides layout uses a single /data root:

/data
├── torrents          # download client writes here
│   ├── movies
│   └── tv
└── media             # media server reads here
    ├── movies
    └── tv

Don't mount /downloads and /movies as separate volumes. Mount the parent /data into every app. Create it with the UID/GID you'll give the containers:

sudo mkdir -p /data/torrents/{movies,tv} /data/media/{movies,tv}
sudo chown -R 1000:1000 /data

2. The Compose file

Prowlarr, Radarr, and Sonarr run normally on your LAN. qBittorrent lives inside a gluetun VPN container, so the torrent traffic, and only the torrent traffic, goes through the VPN. The images are from LinuxServer.io, which share one PUID/PGID permissions model.

Make these values your own first: YOUR_WIREGUARD_PRIVATE_KEY (from your VPN provider's WireGuard config; keep it in a secret store), protonvpn and Netherlands (your provider and server country), 192.168.1.0/24 (your real LAN subnet), 1000/1000 (the UID/GID that owns /data; check with id), and the /opt/... config paths.

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add: [NET_ADMIN]
    devices: [/dev/net/tun:/dev/net/tun]
    ports:
      - "8080:8080"        # qBittorrent WebUI, published by gluetun
    environment:
      - VPN_SERVICE_PROVIDER=protonvpn
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=YOUR_WIREGUARD_PRIVATE_KEY
      - SERVER_COUNTRIES=Netherlands
      - VPN_PORT_FORWARDING=on
      - FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24
    restart: unless-stopped

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    network_mode: "service:gluetun"      # all traffic through the VPN
    environment: [PUID=1000, PGID=1000, TZ=Etc/UTC, WEBUI_PORT=8080]
    volumes:
      - /opt/qbittorrent:/config
      - /data/torrents:/data/torrents     # same path as the Arr apps
    depends_on: [gluetun]
    restart: unless-stopped

  prowlarr:
    image: lscr.io/linuxserver/prowlarr:latest
    container_name: prowlarr
    ports: ["9696:9696"]
    environment: [PUID=1000, PGID=1000, TZ=Etc/UTC]
    volumes: [/opt/prowlarr:/config]
    restart: unless-stopped

  radarr:
    image: lscr.io/linuxserver/radarr:latest
    container_name: radarr
    ports: ["7878:7878"]
    environment: [PUID=1000, PGID=1000, TZ=Etc/UTC]
    volumes:
      - /opt/radarr:/config
      - /data:/data                        # ONE shared root -> hardlinks
    restart: unless-stopped

  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    container_name: sonarr
    ports: ["8989:8989"]
    environment: [PUID=1000, PGID=1000, TZ=Etc/UTC]
    volumes:
      - /opt/sonarr:/config
      - /data:/data
    restart: unless-stopped

gluetun blocks everything except the VPN by default, so FIREWALL_OUTBOUND_SUBNETS must match your real LAN or the Arr apps can't reach qBittorrent. Bring it up and prove the tunnel works:

sudo docker compose up -d

# This MUST print a VPN IP, not your home IP:
sudo docker exec gluetun wget -qO- https://api.ipify.org ; echo

3. Wire the apps together, in this order

Register Sonarr and Radarr in Prowlarr. Copy each app's API key from its Settings → General page, then add both in Prowlarr → Settings → Apps using the container URLs (http://radarr:7878, http://sonarr:8989). Containers reach each other by service name.

Add indexers in Prowlarr only. They sync to Radarr and Sonarr automatically, so you never maintain two lists.

Add qBittorrent as the download client in Radarr and in Sonarr: Settings → Download Clients → qBittorrent at http://<host-ip>:8080 (gluetun publishes the UI on the host), with a category of radarr or sonarr so downloads land in the right subfolder.

Set each root folder to the media subpath: /data/media/movies in Radarr, /data/media/tv in Sonarr. Because qBittorrent writes to /data/torrents/... under the same mount, imports become hardlinks.

4. Prove it end to end

Add one movie in Radarr, mark it monitored, and hit Search. Radarr queries Prowlarr's indexers, picks a release by its quality settings, hands it to qBittorrent, and imports the finished file into /data/media/movies. Success looks like this: the import completes instantly and your disk usage doesn't jump by the file's size. If either is off, look at the folder layout from step 1 first.

If a download finishes but won't import, it's almost always ownership. Keep the same PUID/PGID across qBittorrent and the Arr apps, and make sure /data belongs to that user.

Go further

Copy-paste version: the Arr stack Compose playbook
The download client in depth, with kill-switch and port-forward sync: the VPN torrent stack playbook
Take it hands-off with import lists, quality profiles, and a media-server rescan: Automating the Arr Stack

Sources: TRaSH Guides: Hardlinks and Instant Moves · Servarr Docker Guide

Written by Peira Labs. Full version, with the screenshots and FAQ, at peira.dev.

Homelab Capacity Planning: What If a Node Dies Tonight?

Josh Hall — Tue, 22 Sep 2026 15:02:58 +0000

Every dashboard in my rack could tell me what was happening right now — and not one could answer the question that actually keeps me up: if one of my four nodes dies tonight, do the containers it was running fit on the three that survive, and how long until they're back? I'd been answering that with a shrug. So I built a read-only simulator that reads the real cluster, does the arithmetic, and tells me plainly when the answer is no. On day one, it told me no.

Cross-post from Peira Labs. The full version — with the diagrams and the fifteen-line packer — lives at https://peira.dev/articles/homelab-capacity-planning-node-failure/

Plan against RAM you actually use, not RAM you configured

The configured memory maximum is a ceiling you picked once, usually generously. Plan against it and your cluster looks far more full than it is. Plan against a multi-day observed peak from your metrics and you learn what the workload really needs — while the configured limit still protects the host from a runaway process. Actual usage for planning, configured limits for safety.

"Just migrate it" isn't the recovery plan

Without shared storage, Proxmox HA can't restart a guest elsewhere — it can't reach the disk. On a local-disk cluster the real recovery path is a restore from backup onto a surviving node, so the only two questions that matter are: do the survivors have room, and how long does the restore take?

Packing the survivors: first-fit decreasing

Sort the homeless containers largest-first, then drop each into the first survivor it fits in. Sorting big-first places the awkward items while there's still room — provably close to optimal, which is far more accuracy than a homelab estimate needs. Fifteen lines of Python.

Restore time: measure once, then divide

Don't borrow someone else's number. Restore one real guest, time it, divide backup size by elapsed time to get your throughput. From then on, any restore estimate is just backup-size ÷ that rate. Your disks, network, and compression make a borrowed figure confidently wrong.

The scenario with no ETA

The nastiest case: the node that dies is the one running your backup server. You lose the fast recovery path along with the node — any backup stored only there is gone with it, and recovery falls back to whatever offsite copy you keep (hours, not minutes). It's the strongest argument for a second backup tier somewhere else entirely.

The simulator told me "no" on day one — one container that wouldn't fit anywhere, and a scenario with no ETA. Both were fixable once I could see them. If you want to run the same math on your own lab, I turned it into two free tools: the node-failure simulator and a blast-radius map.

Written by Peira Labs — full walkthrough with diagrams at peira.dev.

Proxmox Datacenter Manager: One Pane Over Every Cluster

Josh Hall — Tue, 22 Sep 2026 14:59:33 +0000

Run more than one Proxmox cluster and you end up living in browser tabs — one for the office cluster, one for the box at home, one for the backup server. Proxmox Datacenter Manager (PDM) gives you one read-only pane over all of it — but only bother if you actually run more than one cluster. For a single cluster the native Proxmox VE interface already does this, and PDM is just one more thing to host and secure.

Here's how I deployed PDM 1.1 in a container and connected my clusters with tokens that can only look.

This is a cross-post from Peira Labs. The full illustrated version — with the add-remote wizard, the architecture diagram, and every gotcha — lives at https://peira.dev/articles/proxmox-datacenter-manager/

What PDM actually is

A Proxmox VE cluster fuses several nodes into one system. PDM sits a layer above: it doesn't join anything, it connects to your clusters and standalone nodes as remotes and aggregates them into one screen. Each remote stays independent and hands PDM nothing but an API token — which is the whole security story, because you decide exactly how much that token can do.

Deploy it in a container

PDM ships as Debian packages, so a plain Debian 13 ("trixie") LXC does the job (2 vCPU / 2 GB RAM is plenty). Add the no-subscription repo and install:

wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg \
  -O /usr/share/keyrings/proxmox-archive-keyring.gpg

cat > /etc/apt/sources.list.d/proxmox.sources <<'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pdm
Suites: trixie
Components: pdm-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

apt update
apt install proxmox-datacenter-manager-container-meta

The web UI comes up on port 8443. Log in as root@pam with the container's root password.

Connect a cluster so it can only look

On each cluster, create a dedicated user and a read-only token rather than handing PDM an admin login. Proxmox VE has a built-in PVEAuditor role (read access, nothing else); Proxmox Backup Server has an Audit role:

# Proxmox VE
pveum user add pdm@pve
pveum acl modify / -user pdm@pve -role PVEAuditor
pveum user token add pdm@pve pdm --privsep 0   # prints the secret ONCE

# Proxmox Backup Server
proxmox-backup-manager user create pdm@pbs
proxmox-backup-manager user generate-token pdm@pbs pdm
proxmox-backup-manager acl update / Audit --auth-id 'pdm@pbs!pdm'

In PDM, Remotes → Add, give it the node address, let it read back the certificate fingerprint (it pins it, so a swapped cert breaks the link on purpose), then paste the token. Both remotes then show up with their audit tokens:

The single pane

With both remotes connected, the dashboard finally aggregates every node, guest, and datastore across separate clusters, with combined CPU/memory/storage gauges:

Three rough edges

A 403 in the log every cycle — ignore it. PDM tries to fetch each node's available updates, which needs Sys.Modify. Your audit token doesn't have it, so you get a harmless 403 per cycle. That's least-privilege working as intended.
A pure-Audit token can't populate every tile. On my PBS remote, PDM's resource-collection call returns 403 permission check failed, so the backup node reads as offline even though the connection is fine. Decide per remote whether you want the extra read scope.
The 1.1.7 client CLI won't do password-file auth. The separate proxmox-datacenter-manager-client rejects --user root@pam --password-file even when the same credentials pass at the raw API. The UI, admin CLI, and API are all fine — use one of those.

And if you later want PDM 1.1's cross-cluster VM migration, remember these tokens can't do it (migration writes to both sides) — re-scope deliberately for that job.

For a single cluster, skip it. But the day you're logging into three Proxmox tabs to answer "is everything up?", PDM is the fix — and you can stand it up in an afternoon with credentials that can't hurt you.

Written by Peira Labs — full version with the add-remote wizard walkthrough and architecture diagram at peira.dev.

Track AI Token Spend in Grafana: Claude, Codex, and Ollama

Josh Hall — Tue, 08 Sep 2026 20:35:30 +0000

I let three different AIs work in my homelab every day — a coding assistant, a second CLI for pair-work, and a small agent that triages alerts overnight. One evening I realized I couldn't answer a basic question: what is all of this actually costing me? Two burn subscription quota I've already paid for, one spends real API dollars, and none showed up on the Grafana dashboards I'd built for everything else in the rack.

So I fixed it. Every call from every AI in the lab — tokens, latency, cache hits, and dollars — now lands in Prometheus and one Grafana dashboard. This walks through the four measurement legs, the PromQL traps that made my first dashboard lie, and the privacy scrub that makes the screenshots publishable.

Make the addresses your own. Every machine-specific value here is a placeholder: the monitoring host 10.0.0.5, agent host 10.0.0.7, Ollama nodes 10.0.0.1–10.0.0.3, exporter ports, and any /home/youradmin paths.

Why measure AI at all?

The AI layer has a genuinely weird cost structure. Two interactive CLIs run on flat subscriptions, so their "cost" is quota — a percentage of a weekly allowance. The automated agent calls a hosted API and pays per token. Same lab, three billing models. So the dashboard has two columns: quota burn (a percentage that resets) and real dollars (the metered agent).

Leg 1: Claude Code already speaks OpenTelemetry

The coding CLI needs no wrapper — it has native OpenTelemetry support. Switch it on with env vars:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://10.0.0.5:4317

Every session exports claude_code.token.usage (by type — input, output, cache read), claude_code.cost.usage in USD, and claude_code.session.count. Those arrive over OTLP, which Prometheus doesn't scrape directly — so an OpenTelemetry Collector on the monitoring host listens on :4317, applies processors, and re-exposes everything in Prometheus format on :8889.

Leg 2: tail the agent's log

The automated agent doesn't speak OTel, but it writes an honest log line per call: provider, model, token counts, latency, cache hit, and the occasional "fallback activated". A ~200-line stdlib-only Python exporter tails the log with a regex, keeps counters in memory, and serves them on :9109. It also reads the agent's task database (read-only) for queue-depth gauges — so the dashboard shows quality alongside spend: is the agent finishing work, or just burning tokens?

Leg 3: Ollama, measured from the outside

My three-node Ollama cluster was stubborn: Ollama ships no Prometheus endpoint (as of the 0.30 releases). But it leaks what you need in two places — its journald request log (status, latency, caller IP) and the documented /api/ps endpoint (which models are loaded right now). One exporter per node on :9110. The caller-IP label turned out useful: it shows who is using the local models.

Leg 4: the laptop, via Pushgateway

The second CLI (Codex) records tokens and quota in session files, but the laptop sleeps and moves, so Prometheus can't reliably scrape it. That's exactly the Pushgateway case: a systemd user timer parses the session files every 5 minutes and pushes lifetime totals plus quota percentage to :9091.

Wiring it together is four scrape jobs:

scrape_configs:
  - job_name: ai_claude_code
    static_configs: [{ targets: ["10.0.0.5:8889"] }]   # OTel Collector
  - job_name: ai_codex
    honor_labels: true
    static_configs: [{ targets: ["10.0.0.5:9091"] }]   # Pushgateway
  - job_name: ai_agent
    static_configs: [{ targets: ["10.0.0.7:9109"] }]   # log-tail exporter
  - job_name: ai_ollama
    static_configs: [{ targets: ["10.0.0.1:9110", "10.0.0.2:9110", "10.0.0.3:9110"] }]

Three PromQL traps that made v1 lie

Trap 1: per-session counters break increase(). Claude Code's counters are per-session and ephemeral; a short session leaves one sample, and range functions need two, so increase() returns nothing while a real 30k-token session sits invisible. Read the last value each session reported and sum:

sum(max_over_time(claude_code_token_usage_tokens_total[1d]))

Trap 2: composite cost math collapses on absent series. In PromQL, arithmetic with an empty operand makes the whole expression empty — so before any cache reads existed, real spend rendered as $0.00. Guard every component with or vector(0):

(sum(rate(input_tokens[1h]))  or vector(0)) * 1.00 / 1e6
+ (sum(rate(cache_tokens[1h])) or vector(0)) * 0.10 / 1e6
+ (sum(rate(output_tokens[1h])) or vector(0)) * 5.00 / 1e6

Trap 3: histogram_quantile returns literal NaN over idle windows. Documented behavior with zero observations — my latency panel drew garbage across every quiet hour. Consumers need to drop non-finite samples; Grafana panels just go sparse when the lab is idle, which is the honest picture.

The privacy scrub: make dashboards publishable

Claude Code's telemetry attaches identity by default — your email, account ids, org id — as labels on every metric. Useful in a company; radioactive on a public screenshot. Going forward, the OTel Collector deletes those before they reach Prometheus:

processors:
  attributes/scrub:
    actions:
      - { key: user.email,        action: delete }
      - { key: user.account_uuid, action: delete }
      - { key: user.account_id,   action: delete }
      - { key: user.id,           action: delete }
      - { key: organization.id,   action: delete }

Delete by key, not value, so anyone who ever exported from that laptop gets scrubbed. For history already on disk, open a temporary Prometheus admin window (--web.enable-admin-api), delete the identity-labeled series, then close it:

curl -X POST 'http://10.0.0.5:9090/api/v1/admin/tsdb/delete_series?match[]={user_email!=""}'
curl -X POST 'http://10.0.0.5:9090/api/v1/admin/tsdb/clean_tombstones'
# now remove --web.enable-admin-api from the unit and restart again

One deliberate non-deletion: I kept session_id. Dropping it merges per-session cumulative counters into one series (last write wins, totals undercount). Scrub identity; keep cardinality that's structurally load-bearing.

Don't page yourself over a sleeping laptop

My Node Down alert was up == 0. A sleeping laptop is not an outage, so it's now scoped to exclude the AI jobs — a dead AI exporter shows as a dashboard gap, real infra still pages:

up{job!~"ai_.*"} == 0

What I actually watch

Not spend — the cache-hit rate. At ~78% cached input, the agent's metered bill stays in coffee money. The day that rate drops is the day something changed in how it builds prompts, and now I'll see it the same morning. Total cost of the measurement layer: two tiny Python exporters, one collector, one gateway, and an evening.

Read the full version

Originally published on peira.dev.

Eleven Free Homelab Tools for the Questions Guides Skip

Josh Hall — Mon, 07 Sep 2026 15:20:12 +0000

Every guide I write ends in the same handful of questions. How much hardware do I actually need? What happens when one box dies? Are my backups real or just a feeling? A guide can walk you through a setup, but it can't do arithmetic about your lab — so I built eleven small tools that can, at peira.dev/tools.

They're free, none ask who you are, and seven of the eleven keep working once the page has loaded — network unplugged, laptop in a cupboard, whatever.

They share one lab profile

This is the part that makes them a set rather than eleven unrelated pages. Describe your lab once — tick your services in the sizing calculator, press Save to profile — and the others pick it up. The failure simulator opens with your nodes already modelled; the backup planner knows what data you have; the power-loss playbook knows what's plugged in. Lab doc hands the whole thing back as a Markdown file.

Nothing about that profile leaves your browser. No account, no sync, no server that could leak it — which is also why it doesn't follow you between devices. The Markdown export is how you carry it elsewhere.

Plan the build

Sizing calculator — asks what you want to run and recommends nodes, RAM, and storage. It cares most about RAM, because that's the constraint that actually bites; vCPUs overcommit happily, memory doesn't. Tick "survive one node failure" and it insists on three nodes (a two-node cluster loses quorum the moment one dies).
Node failure simulator — kill a node and see which workloads fit on the survivors. It places the critical ones first and names the stranded ones.
3-2-1 backup planner — three copies, two devices, one offsite (the rule CISA recommends). It's blunt: a snapshot on the same disk as the original is versioning, not a backup.

Fix what's broken

The overlay network diagnostic is a decision tree born from a miserable afternoon: a container couldn't reach a machine across a Tailscale subnet router, and three layers had to be right — the route in the guest, the ACL grant, and a firewall on the destination. Two fail silently. The tool walks them in order.

Four more use a language model you point them at yourself (a Claude account, an API key for a provider you choose, or a model on your own hardware — the page calls it directly from your browser, nothing touches my site):

Log triage — paste the wall of output, get the one line that matters.
Compose review — reads a Docker Compose stack for what bites on the next update, reboot, or dead disk.
Explain before you run — paste a command from a forum reply, get a plain-English breakdown and a red/amber/green "can you undo it?".
The troubleshooter — describe the symptom, get ranked causes and the commands to check them.

A Docker fact I got wrong building the compose reviewer, since half the advice online is stale: since Docker 23.0, docker system prune --volumes and docker volume prune remove only anonymous volumes, and "unused" means no container attached at all — a stopped container still protects its volume. Named volumes need docker volume prune --all. The command that genuinely deletes named volumes is docker compose down -v. That's the one that eats a database.

Survive the bad day

Blast radius mapper — map dependencies, click to kill something, watch the cascade. The ranking is the useful part: it usually shows one unglamorous box (the switch, DNS, the container host) carrying most of the lab. Your recovery plan for that box is your recovery plan for everything.
Power-loss playbook — orders machines into shutdown waves (workloads, then compute, then storage, network last, because shutdown commands travel over it) and checks whether the sequence fits inside your battery, with an honest allowance for battery age. It'll generate matching NUT settings too.
Bus factor tool — the one I'd most like people to use. If you were unavailable for a month, could the people you live with get their photos back and keep the heating on? It asks nine questions and writes a letter for someone who has never used a terminal. It never asks for a password — it asks where the credentials are and who may open them.

What it costs and needs

Nothing, and not much. No accounts, no cookies, no analytics on the tool pages. Seven are single HTML files — save the page and they work offline. Four need a model you choose; if you paste a key it stays in your browser and goes only to the provider you picked. Every tool is also a public artifact you can fork, prompts included.

They're worksheets, not oracles. Each is a model of your lab, and a model is always simpler than the thing. Use them to find the question you should be asking, then verify on your actual hardware. The only real backup test is a restore; the only real UPS test is pulling the plug.

Read the full versions

Eleven Free Homelab Tools (full post)
How they were built — the constraints, three design iterations, and bugs that got past me
Point the tools at any model

Originally published on peira.dev.

Build a Read-Only Homelab MCP Server for Your LLM

Josh Hall — Sun, 06 Sep 2026 18:28:52 +0000

I wanted to ask my AI assistant plain questions about my homelab — "are all my nodes up?", "any firing alerts?" — and get real answers from the real cluster. What I absolutely did not want was to hand a language model a button that could reboot a node or delete a VM. Convenience is lovely right up until the model confidently does the wrong thing at 2 a.m.

The fix is a read-only MCP server: a small program that exposes your homelab to an AI as query tools and nothing else, connecting with credentials that can only read. The safety isn't a promise you extract from the model — it's baked into the architecture. There is simply no tool, and no permission, to change anything. Every number below came out of my own running cluster.

Make the addresses your own. Replace 10.0.0.104 with your Prometheus host. Keep the read-only API token in your secret store and pass it via an environment variable — never paste a real token into the server file.

What MCP is, in one minute

The Model Context Protocol (MCP) is an open standard — originally from Anthropic — for connecting AI assistants to tools. An MCP server publishes typed-function tools; an MCP client (Claude Desktop, Claude Code, and a growing list) lets the model discover and call them. Instead of hallucinating your cluster's state, the model asks your server and gets the real answer.

The protocol is neutral about safety — a tool can do anything you program. Which is why the interesting decision is what you choose to expose. We expose only reads.

Build the server

I'll use Python and FastMCP, where a decorated function becomes a tool. Two tools is enough to be genuinely useful: a general Prometheus query, and a friendly "are my targets up?" summary.

import os, requests
from fastmcp import FastMCP

PROM_URL = os.environ.get("PROM_URL", "http://10.0.0.104:9090")
mcp = FastMCP("homelab-readonly")

@mcp.tool
def prometheus_query(promql: str) -> dict:
    """Run a read-only Prometheus instant query."""
    r = requests.get(f"{PROM_URL}/api/v1/query",
                     params={"query": promql}, timeout=10)
    r.raise_for_status()
    data = r.json()["data"]["result"]
    return {"query": promql, "series": len(data),
            "sample": [{"metric": s["metric"], "value": s["value"][1]}
                       for s in data[:5]]}

@mcp.tool
def cluster_targets_up() -> dict:
    """How many scrape targets are up vs down (read-only)."""
    r = requests.get(f"{PROM_URL}/api/v1/query",
                     params={"query": "up"}, timeout=10)
    r.raise_for_status()
    res = r.json()["data"]["result"]
    up = sum(1 for s in res if s["value"][1] == "1")
    return {"targets_total": len(res), "targets_up": up,
            "targets_down": len(res) - up}

if __name__ == "__main__":
    mcp.run()   # stdio transport by default

Notice what's not here: no reboot, no delete, no create. The tool surface is the security boundary.

FastMCP ships an in-memory client, so a five-line script exercises the real protocol. This is unedited output from my cluster:

tools/list -> ['prometheus_query', 'cluster_targets_up']
call cluster_targets_up  -> {'targets_total': 27, 'targets_up': 27, 'targets_down': 0}
call prometheus_query('count(smartctl_device_smart_status)')
                         -> {'series': 1, 'sample': [{'value': '8'}]}

Twenty-seven scrape targets, all up; eight disks reporting SMART. The model asked; the cluster answered; nothing changed.

Read-only by design — four layers

"Read-only" isn't one setting; it's a posture you build in layers, so a mistake at any single layer can't hand an AI the keys:

Read-only credentials — a Proxmox token bound to the built-in PVEAuditor role; a query-only DB user.
Read tools only — no write/delete tool is ever registered.
Bounded inputs — instant queries only, no admin endpoints.
Private scope — localhost / Tailscale, never the public internet.

The credential is the real lock. The single most important choice is the read-only credential. In Proxmox that's a token bound to PVEAuditor — it can read cluster state and nothing else. Even if you later fat-finger a write tool into the server, an audit token has no permission to carry it out.

Connect it to Claude

{
  "mcpServers": {
    "homelab-readonly": {
      "command": "python",
      "args": ["/opt/homelab-mcp/server.py"],
      "env": { "PROM_URL": "http://10.0.0.104:9090" }
    }
  }
}

Now you can ask, in plain English, "are all my Prometheus targets up?" and the assistant calls cluster_targets_up and tells you. I keep mine reachable only over Tailscale — available from my laptop or phone, never from the open internet.

The flourish: a fully self-hosted loop

Pair this with a local Ollama cluster behind a load-balancing endpoint and the whole loop is yours: a local LLM calling a read-only tool server to answer questions about your cluster — no cloud in the path, and no way for any of it to change a thing.

Read the full, updated versions

I keep the maintained versions of this and the surrounding series on my homelab site, documented from a working 4-node Proxmox cluster:

Originally published on peira.dev.

What Is the *arr Stack? Sonarr, Radarr, and Prowlarr Explained

Josh Hall — Sun, 06 Sep 2026 15:12:06 +0000

If you've spent any time in homelab or self-hosting circles, you've seen people mention their "Arr stack" — often written *arr, where the asterisk is a wildcard for Son*arr, Radarr, Lidarr*, and friends. It sounds like arcane jargon, but the idea is simple: a set of apps that turn "I want to watch this" into an organized file in your library without you touching a download client.

This post explains what each piece does and how they fit together — the concepts, no setup yet.

A note on use: the arr stack is just a tool. Point it only at content you have the legal right to download where you live — your own media, public-domain works, and Linux ISOs are the intended use.

The problem the Arr stack solves

Managing a media library by hand means searching a dozen indexers, squinting at release names to guess which is good, downloading, renaming the file into something your media server understands, moving it into the right folder, and refreshing the library. Then doing it again for the next episode. It starts as a hobby and quietly becomes a part-time job.

The Arr stack automates every step. You tell it what you want, and it handles the searching, grabbing, renaming, and filing, then tells your media server to rescan so the title just appears, ready to watch.

One thing I learned running this myself: "hands-off" holds right up until the auto-downloading quietly stops. Nothing errors — the library just stops growing, and because everything still looks fine, you don't catch it for a while. Build it so you'll notice when one link stops handing off to the next.

The players

Each app is a focused piece of the pipeline. All are open-source and part of the Servarr family, so they share a near-identical interface.

App	Handles	Thinks in terms of
Sonarr	TV shows	series → seasons → episodes
Radarr	Movies	single films + editions
Prowlarr	Indexers	the sources everything searches
A download client (e.g. qBittorrent)	The actual transfer	torrents / Usenet
A media server (Plex / Jellyfin)	Playback	libraries you stream

Sonarr and Radarr are essentially the same program with different logic — Sonarr understands episode numbering and air schedules, Radarr understands releases and cuts. There are siblings too: Lidarr (music), Readarr (books, now retired). Most media setups only need Sonarr and Radarr.

How Prowlarr changed the game

An indexer is a searchable catalog of available releases — a torrent tracker or a Usenet index. Before Prowlarr, you added every indexer to Sonarr and Radarr separately, kept two credential sets current, and repeated it every time an indexer changed.

Prowlarr is the indexer manager: you add each indexer once, and it syncs it into every connected Arr app automatically. Prowlarr stores the indexer definitions; Sonarr and Radarr register as "applications" and receive the synced indexers.

Prowlarr decides where to search; Sonarr and Radarr decide what to grab. Prowlarr never downloads anything — it just gives the others a shared, always-current list of places to look.

The pipeline, end to end

  You add a title  (or an import list adds it automatically)
        |
        v
  Radarr / Sonarr   -- decides it's "wanted", asks Prowlarr's indexers
        |
        v
  Prowlarr indexers -- return candidate releases, scored by quality rules
        |
        v
  Download client   -- grabs the chosen release (torrent behind a VPN)
        |
        v
  Radarr / Sonarr   -- imports: renames + moves the file into the library
        |
        v
  Media server      -- rescans; the title appears, ready to stream

Every arrow is automatic. The only human input is the first line — and even that can be automated with import lists that pull from a watchlist or "popular" feeds.

Where quality rules fit in

The Arr apps don't grab the first result they find. Each uses a quality profile — your rules for resolution, source, file size, and codecs — to score candidates and pick the best fit. The community-maintained TRaSH Guides are the reference for tuning these.

What about a VPN?

Only one piece needs one. Sonarr, Radarr, and Prowlarr move metadata and searches — no swarm traffic. The download client is what joins torrent swarms and exposes your IP, so the hardened setup routes only the torrent client through a VPN container with a kill-switch, leaving the rest on your LAN.

The wider *arr family

Bazarr watches your Sonarr and Radarr libraries and fetches subtitles automatically.
Lidarr does for music what Sonarr does for TV; Whisparr handles adult content.
For requests, Jellyseerr gives the household a streaming-style page that hands approved titles to Radarr/Sonarr.
One to skip: Readarr (books) was retired in 2025 when its metadata source broke.

Where to go next

I keep the full, continually-updated versions of these guides — deploy with Docker Compose, automation, subtitles, music, and requests — on my homelab site, documented from a working 4-node Proxmox cluster:

Originally published on peira.dev.