agentleFS
seayniclabsseayniclabs/homelab-infra-mcp/skills/homelab-troubleshooting/SKILL.md

homelab-troubleshooting

Skill0 starsChanged 21 days agoMITView on GitHub

Find the root cause of a failing homelab service in a fixed order: state the symptom, run the per-hop checks, gather evidence, test one hypothesis at a time, then verify against the live service. Use when a service is down, returns errors, reports healthy but does not work, has a broken name or certificate, or a container keeps restarting.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 5 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write two lines before any call:

    line 15
  2. Distinctive:

    Keep "the health check passes" out of the observed line.

    line 20
  3. Distinctive:

    Run these three in order. Each is read only.

    line 24
  4. Very specific:

    If diagnose_service names a fix for the first failing hop, verify that fix's claim before you apply it.

    line 30
  5. Distinctive:

    Read the evidence. Write one sentence that names the cause and the proof.

    line 46
  6. Very specific:

    Write the cause as one sentence: "The proxy forwards to localhost:8080, which is the proxy's own port, so every request returns 502."

    line 67
  7. Very specific:

    Run diagnose_service for the domain again.

    line 74
  8. Distinctive:

    If the service is reachable from outside your network, check it from outside.

    line 76
  9. Very specific:

    Ask what else uses the same proxy host, DNS record, certificate, network or image.

    line 82
  10. Very specific:

    Write the symptom, cause, fix and the evidence line into the service's runbook.

    line 86

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Troubleshoot a homelab service

A green signal often hides the fault. A container in state running, a health endpoint that returns 200, or an empty error list can all be true while the service fails for the user. Find the cause before you change anything, and prove it with evidence from the failing service.

1. State the symptom

Write two lines before any call:

  • Observed: what you or the user saw, in their words. Example: "https://wiki.example.com returns 502 from a phone on cellular."
  • Expected: what should happen. Example: "the wiki page loads."

Keep "the health check passes" out of the observed line. It is a signal, not the user's outcome.

2. Run the first checks

Run these three in order. Each is read only.

  1. homelab_health: which modules can reach their services. A failed module stops the investigation there. Report the module's error and its Fix: line.
  2. diagnose_service with domain set to the failing name. It checks each hop of the path and returns one row per hop, with the first failing hop and its fix. Read the rows in order. The first failing hop is the first suspect.
  3. service_status for the service name. It gives one view of the container, proxy hosts and DNS records.

If diagnose_service names a fix for the first failing hop, verify that fix's claim before you apply it. The hop check is a probe, and a probe can be wrong.

3. Gather evidence for one suspect

Pick the single most likely cause from the first checks. Collect evidence for it only.

SuspectEvidence to collectTool
Container stopped or restartingState, restart count, last 100 log linesdocker_containers with get and logs
Container running, service deadLogs for errors; resource usedocker_containers with logs and stats
Proxy points at the wrong placeForward host and port of the proxy hostproxy_hosts with get
Name does not resolve or points elsewhereRecord name, type and targetdns_records with list or get
Certificate missing or expiredExpiry date and domain listproxy_certificates with list
Access blocked by a listAccess lists on the proxyproxy_access_lists with list
Redirect loop or wrong redirectRedirectionsproxy_redirections with list

Read the evidence. Write one sentence that names the cause and the proof. If the proof does not fit the symptom, drop that hypothesis and pick the next suspect. Test one hypothesis at a time.

4. Check the usual suspects

Most failures in a homelab match one of these patterns. Check the matching row before you invent a new cause.

PatternTellCheck
Liveness passes, function failsContainer running, HTTP 200 on a status page, but the app shows errorsMake a real request to the function and read the body
Forward target is localhostThe proxy returns 502 or 504From inside the proxy's network, the target must be the container name or the host address, not localhost
Stale DNS or wrong targetThe name resolves to an old address, or to nothingCompare the record's target with the current public address; check the record was saved
Certificate expired or not issuedBrowser warning, or SSL error at the edgeproxy_certificates list: check the expiry date and the domain list
Old image still runningFix is deployed but the symptom continuesCompare the container's start time and image with the last deploy; restart the container
Paged list read as completeContainer or record missing from resultsRepeat the list with offset; a page full to limit has more rows
Crash loopRestart count climbs; the same startup lines repeatdocker_containers logs; the first line of the loop shows the cause
Missing secret or settingA tool returns homelab.<module>.<code>Pass the Fix: line on as written
Scheduled job runs and does nothingExit code 0, no outputRead the job's own logs and the environment it runs in
Misleading nameA proxy host or record name suggests a role it does not haveRead the forward target before you act on the name

5. Fix the cause

  1. Write the cause as one sentence: "The proxy forwards to localhost:8080, which is the proxy's own port, so every request returns 502."
  2. Plan the fix as the change tool call and its dry_run result.
  3. Apply it after the user agrees in chat. The person approves the change in the MCP client.
  4. A retry, a restart or a longer timeout without a stated cause is a patch. Use it only as a test, and say so.

6. Verify against the original symptom

  1. Run diagnose_service for the domain again. Every hop must pass.
  2. Repeat the request that failed. Use the same name, the same path and, where the user saw it, the same client.
  3. If the service is reachable from outside your network, check it from outside. A check from inside the LAN can pass while the public path still fails.

Report the symptom as observed, the cause, the change, and the result of the repeated request.

7. Check the blast radius

Ask what else uses the same proxy host, DNS record, certificate, network or image. List those services with proxy_hosts list and docker_containers list. Fix them or name them in the report.

8. Record the cause

Write the symptom, cause, fix and the evidence line into the service's runbook. Use the runbook skill to create one when none exists. Record only confirmed causes. A guess in the record misleads the next person.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.