Collecting diagnostics
What to gather before asking for help — status, peers, logs and a paired diagnostic bundle — and what to redact before you share it.
- troubleshooting
- diagnostics
- logs
- support
A good report answers three questions: what did you expect, what happened, and what does the machine say about itself.
The minimum
roomler status
roomler peers
roomler --versionFor a connectivity problem, gather BOTH ends
One side's output is half the picture
Connectivity is a property of a pair. A report from one machine cannot show whether the other agrees about the path, and disagreement between the two ends is itself a diagnosis.
roomler diag pair <other-device>That runs a paired diagnostic and reports what each end sees.
For one machine on its own:
roomler diag hostDiagnostics live in the CLI, not in the agent
Which means a new probe reaches you in a CLI update rather than requiring a
fleet-wide agent rollout. If someone asks you to run a diag subcommand you do
not have, update the CLI.
Logs
roomler logs --tail 200Or the service log directory under %PROGRAMDATA%\roomler\logs.
roomler logs --tail 200 # the user half
sudo roomler logs --tail 200 # the root halfjournalctl -u roomler -n 200 --no-pager # system unit
journalctl --user -u roomler -n 200 --no-pager # per-user unit`roomler logs --grep` reads only a recent tail
It searches a bounded slice of the end of the log, not the whole thing. A negative result is not proof of absence — if you are looking for something older, read the log directly.
Turning up the detail
Raise the log level, reproduce the problem, then put it back. Verbose logging is for a reproduction, not for permanent operation.
What to redact before sharing
Logs and config can contain credentials
config.tomlholds the agent token and, with SSH enabled, the SSH host private key. Do not paste it.- Enrollment tokens may appear in shell history and installer output.
- Log lines can contain a credential. Command output is redacted before it leaves a machine, but a log you export by hand has had no such pass.
If a token does end up in something you shared, remove the device and re-enroll it. That revokes the credential — which is exactly why removal is immediate.
Machine names, mesh addresses and versions are generally safe and are usually the useful part.
Where to send it
github.com/gjovanov/roomler-ai/issues. Include:
- What you expected to happen.
- What happened instead, with the exact message.
roomler statusfrom the affected machine — and from both, for a connectivity problem.- Operating system and version, on each end.
- Whether it is the hosted service or self-hosted.
- Whether it ever worked, and what changed if so.
Point 6 is the one most often omitted and most often decisive.