Hermes Logs for Agent and Gateway Troubleshooting

Useful troubleshooting starts with the log produced by the component that actually failed. Hermes separates agent, gateway, error, desktop, and update records, and profiles can have independent runtime paths.

Official documentation: https://hermes-agent.nousresearch.com/docs/reference/cli-commands

Match component, profile, and time

Use hermes logs to view, follow, and filter the known log surfaces rather than searching an entire home directory blindly. A desktop boot failure belongs in the desktop log; a messaging reconnect problem belongs in the gateway log; a disconnected terminal during update can be reconstructed from the update log.

When several profiles run on one machine, select the profile that owns the failed gateway or session. Record the exact retry time so browser, client, and server entries can be correlated.

Troubleshooting checklist

Reproduce the smallest failing action once.
Record profile, source platform, session, and timestamp.
Open the component-specific log for that same window.
Preserve redaction and avoid copying secrets into tickets.
Separate expected validation errors from unexpected server failures.
Check process status alongside logs.
Apply one fix at a time.
Re-run the user path and inspect a delayed log window.

Pitfalls

Reading only the default profile’s gateway log.
Searching old logs without a fresh reproduction timestamp.
Treating a client-side message as the server root cause.
Publishing raw logs that contain private prompts or paths.
Declaring success before delayed serverless or gateway errors arrive.

Verification steps

Run hermes status --all and identify the owning profile and component.
Reproduce one harmless failure or health request.
Use hermes logs with the relevant stream and follow mode.
Confirm one timestamped entry corresponds to the reproduction.
Apply the narrow correction and restart only the affected component.
Repeat the exact action.
Wait briefly, then confirm no new unexpected error appears.