One Command, Every Subsystem
You’ve now built a Hermes deployment spanning models (Module 2), tools and MCP servers (Module 3), memory and skills (Module 4), a terminal backend (Module 5), and possibly a messaging gateway (Module 6) with guardrails layered on top (Lessons 19-20). When something breaks, you need a systematic way to find out where, not a fresh investigation strategy for each subsystem.
hermes doctoris that unified first step, and it’s why this course has pointed to it repeatedly rather than introducing a different diagnostic per module. It checks:
- Provider credentials and reachability (Module 2)
- MCP server connectivity, both stdio and HTTP (Lesson 9)
- Terminal backend availability, Docker daemon, SSH host/user vars, Modal/Daytona auth (Module 5)
- Gateway adapter status per platform (Module 6)
- Configuration file validity (
config.yamlsyntax, required fields)
When Doctor Passes but Something’s Still Wrong
hermes doctor validates configuration and connectivity, it can’t catch every behavioral issue, particularly ones that only show up in a specific model exchange. For those, go to the raw session trace:
hermes sessions list
hermes sessions show <session-id> --rawThe raw trace shows you the actual <tool_call> and <tool_response> exchanges (Lesson 7.2), which is exactly what you need for the self-hosted tool-call-parser failure mode from Lesson 7.4: doctor confirms the model endpoint is reachable, but only the raw trace shows you the model emitted a tool call as plain text instead of a properly parsed structure.
Symptom-to-Module Map
A quick-reference table for triaging where to look, before diving into logs:
| Symptom | Likely module | First check |
|---|---|---|
| ”Auth error” or “unreachable model” | Module 2 (Providers) | hermes doctor, check .env for the active provider |
| Tool call emitted as plain text, not parsed | Lesson 7.4 (Function-calling) | Inference server’s --tool-call-parser flag (Lesson 5) |
| “Agent seems to forget things mid-task” | Lesson 6 (Context) or Module 4 (Memory) | context_length setting vs. actual model limit |
MCP tool missing from hermes tools | Lesson 9 (MCP) | tools.include/exclude filters, server reachability |
| Skill not triggering automatically | Lesson 11 (Skills) | Skill’s description field specificity |
| Docker backend “container not found” | Lesson 13 (Terminal backends) | docker version, container may have expired past its sleep window |
| One messaging platform down, others fine | Lesson 16 (Gateway) | hermes gateway status for that specific adapter |
| Cron job never fires | Lesson 17 (Cron) | hermes cron list, check schedule syntax and cron logs |
| Approval gate blocking an unattended job | Lesson 20 (Guardrails) | Job’s toolset likely needs tightening, not the gate removing |
A Recovery Checklist
For a deployment that’s gone fully unresponsive, work through these in order rather than reaching for the most drastic fix first:
hermes doctor, rule out configuration and connectivity issues.hermes gateway status(if using messaging platforms), isolate whether it’s a specific adapter or the whole gateway.hermes sessions show <id> --rawon the most recent failing session, look for a malformed tool call or unexpected model response.- Check
hermes cron logsif the failure correlates with a scheduled job’s run time. - Only after the above: restart the specific failing component (one gateway adapter, the terminal backend), not the entire installation, restarting everything discards the diagnostic trail you just built and disrupts anything that was working fine.
Common pitfall: reaching for a full reinstall or
rm -rf ~/.hermesas a first response to a confusing failure. That destroys your memory store, skills, and configuration, exactly the accumulated state that makes a well-used Hermes installation valuable (Lesson 1). Work the checklist above first; a full reset should be a last resort, not a reflex.
Exercise: deliberately break something, misconfigure an MCP server’s
commandfield, or set an invalidcontext_length, and practice the recovery checklist above to find and fix it without guessing. Then restore the correct configuration and confirmhermes doctorpasses clean.