termuna

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.

SSH says authentication failed

When a host that authenticates through an agent is refused, the pane prints the facts, not a generic error: which agent socket was tried and where it was named (the environment, the host's own setting, or IdentityAgent in ~/.ssh/config), every identity the agent offered, and one sentence on the remedy. It is one of four cases.

  • The socket is dead or missing: nothing answers at that path. Start the agent, or point the host at the socket that is live. On Windows the fallback is the OpenSSH named pipe \\.\pipe\openssh-ssh-agent, and when it is absent the remedy is to start the ssh-agent service.
  • The agent holds no keys: it answered, with an empty list. The key has to be added to the agent before Termuna can offer it.
  • Every identity was refused: the pane lists exactly which keys the agent offered, so you can see which one the server was expected to accept and did not.
  • The agent is disabled for this host, by the host's own setting or by IdentityAgent none in the config, and the pane names which.

The Test button on the host's form lists what the agent holds before you connect, type, comment and touch mark included (Agents and keys that never touch disk).

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).

An SSH pane is not live

When an SSH link drops, the pane stays: its scrollback and its place in the split are untouched, and the same target is dialed again (the whole rule). Which of three things is happening is always visible on the pane. The session bar in the web dashboard, the standalone viewer and the phone says it in exactly these words; the desktop app shows the same three states in wording of its own, on the corner tag, the status bar and the seam written into the scrollback:

  • reconnecting, 3 of 8 - a dial is waiting or running. The waits go one second, two, four, eight, then fifteen, and the second number is redial_max.
  • disconnected - the attempts ran out, or the pane was never dialed again at all: a target that authenticates with an interactive password is not retried, and neither is anything when redial_max = 0. Nothing else happens until you reconnect the pane yourself.
  • host key changed - the host presented a different key. Nothing was sent to it.

While a pane is in any of those states, what you type into it is dropped, not queued. That is deliberate: a redial comes back as a new shell, and keystrokes held from before the break would land at a fresh prompt as half a command. The seam in the scrollback marks where the break was; whatever was running on the far side ended with the old connection, unless it was inside tmux or screen.

Two cases never retry. A target that authenticates with an interactive password is left alone because dialing it again means asking you for the secret again, which a background retry has no business doing. A changed host key is left alone because retrying would mean accepting a key you have not verified: check the new fingerprint, then reconnect the pane.

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.

When our cloud is unreachable

Check termuna.com/status first. Then the honest part: most of Termuna does not need us at all.

Still working

  • Every local pane, split and running command. The daemon on your machine owns the shells.
  • Your vault: hosts, keys and snippets are decrypted locally.
  • SSH straight out of the app to anything you can already reach, and the SFTP browser on that host.

Paused until we are back

  • Handoff to another device, and the dashboard at /app.
  • Shared session links, push notifications, and command history between machines.
  • Signing in, and anything under billing.

What you will see

Nothing changes in the terminal itself. The continuity panel lists no other screens for the session, the phone and the dashboard cannot attach, and the daemon keeps retrying the relay on its own: one second apart at first, a minute apart at most. There is nothing to click. Nothing is lost: when the relay answers again, the session resumes from its last acknowledged sequence number and replays the gap, so the phone catches up on everything it missed. After a long gap the viewer resyncs to the current state instead (see above).

If it is only you

If the status page says everything is normal and your machine still cannot reach the relay, it is usually something between you and us: a corporate proxy that blocks WebSocket upgrades, a captive portal, or DNS. The relay is a WebSocket on port 443 at termuna.com. If https://termuna.com/v1/config loads in a browser on that machine but the app cannot attach, the WebSocket upgrade is what is being blocked.

Reporting problems

Back to the overview