Troubleshooting
Termuna is built to degrade loudly and recover quietly. These are the situations you might meet and what is actually happening.
The window shows a connect screen
Every failure lands on one surface: the quiet connecting screen, with the error and two actions, Retry and New session. It means nothing is attached - the daemon was unreachable, an attach was refused, or the connection dropped mid-session. Retry reattaches; your shells were owned by the daemon, so they were not harmed by the window's trouble.
My config change did nothing
A broken config.toml never blocks startup: Termuna logs a
warning and runs with defaults. If a change seems ignored, check the log
for that warning - a typo in one section falls back rather than failing.
The same applies to an invalid quake hotkey spec: it logs and stays
unregistered instead of blocking launch.
Selection and scrolling stopped working
A full-screen app (vim, htop, an agent CLI) asked for mouse reporting, so it receives your clicks - correct behavior, and the status bar tells you the first time a drag is swallowed. Hold Shift to select and scroll locally while it runs. The right-click menu always stays local.
I rebooted and my session is gone from the window
Processes do not survive a reboot; the workspace does. Open the sessions list and resurrect the session: tabs, splits, and working directories come back as fresh shells, and with sync on, the full history is in the cloud (what survives, honestly).
A viewer shows less than my desktop
After a long disconnect the relay may no longer hold the exact gap a viewer missed; the viewer then performs a full resync to the current state instead of replaying. Nothing on the host machine is affected.
I forgot my encryption passphrase
The server cannot reset it, by design. Use the recovery kit generated when you set the passphrase. Without either, encrypted history stays encrypted for everyone, including us - that is the guarantee the whole system rests on.
Reporting problems
- Bugs and questions: GitHub issues.
- Security vulnerabilities: security@termuna.com - see responsible disclosure.