The Homelab Agent
An unattended Claude Code agent that keeps my media pipeline healthy. Cheap checks run every 15 minutes, and only when something is wrong does the agent wake up, fix it inside hard guardrails, check its own work and add what it learned to the runbook.
- U1
Detect
read-only checks, every 15 min
- U2
Snapshot
configs, before any change
- U3
Agent
runbook first, then fix
- U4
Gate
command filter + quarantine
- U5
Verify
re-check, commit the journal
A media server has a long chain of services between “requested” and “watchable”, and things stall quietly in the middle: an import that never happened, post-processing that stopped, a file that looks finished but isn’t. One stall went unnoticed for three months. I didn’t want alerts to triage. I wanted the problems fixed.
How it runs
- Detection is plain code. A cron job runs read-only Python checks every 15 minutes: stuck imports, paused or backed-up processing, stale working folders, containers down, cache filling up. When everything is fine, no model is called at all.
- The agent only wakes for an anomaly. It snapshots the configuration, reads the runbook, works the problem, then the checks run again to confirm the fix.
- It backs off. A repeat of the same anomaly waits from one hour up to a day before the next attempt, with a cap on runs per day.
- A daily discovery run looks for kinds of failure the checks don’t cover yet, and adds checks for them.
Guardrails that don’t depend on the prompt
- Its own user, no sudo, and an SSH key that reaches exactly one account on the media server.
- A command gate. Every command arrives through a forced command that refuses deletes, truncation, raw disk writes, filesystem changes, container removal, reboots and database shells, scans piped scripts too, and logs everything. It stops honest mistakes; it isn’t sold as a security boundary.
- Quarantine instead of delete. Anything the agent would remove moves to a dated folder and is purged a week later.
- A configuration snapshot before every session, so any change can be rolled back.
It writes its own runbook
The runbook has playbooks for each known failure: blocked imports, stale working folders, checking that a media file is complete, a paused queue, a processing backlog, a container down, a cache over 80%. After every run the agent updates it and commits it with a journal of what it did.
On its first run it cleared ten stale working folders and caught three files that the library said were imported but were truncated. It then wrote the lesson, “compare sizes before trusting the library”, into its own runbook. Since then it has fixed four files whose foreign-language titles the library couldn’t parse, without being asked.
My media request app, Saga, can hand a problem straight to the agent and stream its steps back into the page.