Help
How Termavox looks after your sessions, what each status and notice means, and where everything is.
On this page
The essentials
The session lives in Termavox, not in the browser. Termavox keeps every session open on its own server. The browser only shows it: close the tab, shut the laptop or switch to your phone, and the terminal is exactly as you left it when you come back, with vim or htop still running.
Your browser
Shows the session
Your connection
Termavox
Your sessions live here
The session's connectionProtection covers this one
Your server
Runs the shell, inside tmux when protected
- Closing doesn't end anything
- Closing a tab, a pane or the browser only detaches the view. The session keeps running until you use End.
- Protected sessions ride out drops
- With tmux on the server, a session survives network drops and Termavox restarts. The shield next to it says whether it is protected.
- tmux stays invisible
- Termavox uses tmux underneath, with no status bar and no prefix key. Scrolling, selection and copy are the browser's own.
What happens when…
Two sessions on the same server can react differently to the same drop. It depends on whether the session is protected (filled shield) or not protected.
| Situation | Protected | Not protected |
|---|---|---|
| You close the tab, the browser or the laptop | ProtectedKeeps runningThe session goes on. When you come back, the same screen, at once. | Not protectedKeeps runningThe same: closing the browser never affects a session. |
| Your internet connection drops | ProtectedKeeps runningA strip says “Offline, retrying”. When the connection is back, the screen catches up. | Not protectedKeeps runningThe same: the session runs in Termavox, not on your computer. |
| The connection between Termavox and the server drops | ProtectedKeeps running“Reconnecting…”: Termavox reconnects and rebuilds the same screen and history. The programs never stopped on the server. | Not protectedNew shellThe shell and its programs are lost. A new shell opens in the same terminal, below a notice line, with the earlier history still visible. |
| Termavox restarts or is updated | ProtectedKeeps running“Restoring…” for a few seconds, then the same screen is back. | Not protectedNew shellThe shell and the earlier screen are lost. A new shell opens with a notice line. |
| The server reboots | ProtectedNew shelltmux doesn't survive a reboot. The reconnect starts a new shell, and the pane says “The server restarted”. | Not protectedNew shellLike a dropped connection: a new shell, with a notice line. |
The session's tmux dies on the server (pkill tmux, out of memory) | ProtectedEndsWhile the session is connected, it moves to Ended with “The shell exited.”; Reopen starts another shell. If it was disconnected, the return brings a new shell and the notice “The server restarted”. | Not protectedDoesn't applyUnprotected sessions don't use tmux. |
You type exit, or the shell exits | ProtectedEndsThe session moves to Ended. Reopen starts a new shell. | Not protectedEndsThe same. |
| You use End | ProtectedEndsThe shell and every program stop on the server, and the session's tmux is removed. This can't be undone. | Not protectedEndsThe shell and every program stop on the server. |
Protected sessions
A protected session runs inside a tmux on the server, which Termavox drives without showing it. If the connection drops or Termavox restarts, tmux holds on to the shell and its programs, and Termavox rebuilds the screen from it.
The shield next to each session says which case it is; hover it to read:
- Filled: “Protected: survives restarts and network drops”.
- Struck through: “Not protected: the shell is lost if the connection drops”. The session keeps running with the browser closed; what it can't survive is losing its connection to the server.
- Dashed: “Protection is decided when the session starts”.
To protect its sessions, the server needs tmux 3.2 or newer and a UTF-8 locale, with Session protection set to Auto (the default) on the server's page. Under Diagnostics → Test connection, the server's page shows what it has and what is missing.
Statuses and reconnecting
| Status | Means |
|---|---|
| Connecting… | MeansFirst connection: signing in to the server and starting the shell. |
| Restoring… | MeansComing back to a session that was connected before, after a drop, a restart or Retry. |
| Connected | MeansReady to use. |
| Action required | MeansThe server is waiting for you: to trust a host key, or to answer a sign-in prompt such as a verification code. |
| Reconnecting… | MeansThe connection to the server dropped and Termavox is trying again on its own. The pane shows when the next attempt is. |
| Disconnected | MeansThe attempts ran out, you pressed Stop, or the problem won't fix itself (a rejected credential, a different host key). Nothing retries until you ask. The reason is in Messages and what to do. |
| Ended | MeansThe session is over. Reopen starts a new shell. |
Two different connections
- Your connection (browser ⇄ Termavox). When it drops, a strip says “Offline, retrying”. Sessions feel nothing; the screen catches up when it is back.
- The session's connection (Termavox ⇄ server). When it drops, the pane shows “Reconnecting…”. This is the one protection covers.
When the session's connection drops:
- A session that never connected tries a few times and stops: it is almost always a wrong address, port or credential. Fix it on the server's page and use Retry; the fix is used by the next attempt.
- A session that was connected keeps trying for up to 30 minutes; the pane shows until when. After that it is Disconnected.
- Retry now skips the wait. Stop ends the attempts.
Close, end, reopen and remove
- Closing a tab or a pane only detaches the view. The session stays in the list, running.
- End… (the session's menu) stops the shell and every program on the server. If the server is down, the session ends at once and its tmux is ended by the next connection to that server.
- End all sessions…, at the foot of the list, does the same for every running session.
- Reopen brings an ended session back with a new shell, keeping its name.
- Remove from list… (ended sessions only) deletes the session and its history. Remove all ended… does that in one go.
One session in several places
Open the same session on your laptop, another computer and your phone at the same time: they all see the same screen and they can all type.
The terminal's size follows the window where someone last typed or clicked. The others show the session scaled down or letterboxed, with “Sized by another window. Click to fit.”
Workspace and shortcuts
- The list on the left groups sessions by status. The button right under New session collapses the list into a column of icons.
- Split a tab with Split right and Split down, and drag the divider to adjust. Open in a new tab is in the session's menu.
- Rename a session from its menu, or double-click its tab. Everyone who sees the session sees the new name.
- Tabs, splits and sizes are stored in Termavox and come back in any browser you sign in to.
| Shortcut | Does |
|---|---|
| Ctrl+K or ⌘+K | DoesFind a session or start a new one (with the focus outside the terminal). |
| Ctrl+Shift+K or ⌘+⇧+K | DoesThe same, from inside a terminal, where Ctrl+K belongs to the shell. |
| ↑ ↓ Enter Esc | DoesIn the finder: move, open, close. |
Copy, paste and links
Under Settings → Terminal:
- Copy on select (off by default): selected text goes to the clipboard right away.
- Paste with right click (off): right click pastes instead of opening the browser menu.
- Confirm before opening links (on): a link clicked in the terminal shows its full address before it opens in a new tab.
On a phone
- The session list fills the screen; a session opens full screen, and Sessions goes back to the list.
- The key bar has Esc Tab Ctrl Alt, the arrows, the pipe and Paste.
- Ctrl and Alt stay armed for the next key: tap Ctrl, then c, to send Ctrl+C.
- If the browser doesn't let the bar paste, long-press the terminal.
- You can install Termavox as an app from the browser's menu (“Add to Home screen”).
File panel
The Files button on a session's pane opens the server's files beside the terminal. It uses the session's own SSH connection, as the same user: no second sign-in and nothing installed on the server. That is also why it works only while the session is connected.
- Upload several files at once, or drag and drop them on the panel. Download, Rename and Delete act on the selected items; New folder is at the top.
- When a file already exists: Replace (keeps the current file's permissions), Keep both or Skip these.
- Go to the terminal's folder exists in protected sessions only.
- Whole folders can't be uploaded or downloaded yet: select the files inside them.
- A folder with more than 10,000 entries (fewer when the names or link targets are long) is listed only in part, and the panel says so.
- Delete stops once it has read more than 100,000 entries, or past 64 levels of nested folders: “This folder is too large for the panel to delete. Delete it from the terminal (for example with
rm -r).” What it deleted by then stays deleted. - A download the browser leaves paused for more than two minutes stops: download the file again.
- An upload cut off because the connection to the server dropped, or because the server stopped answering, can leave a hidden file named
.<name>.tv-<id>.partin that folder. You can delete it from the panel. - A name with invisible or control characters (a right-to-left override, a zero-width space, a line break, a space at either end, an unusual space anywhere in it, such as a no-break space, the narrow one of French typography or the wide one of Japanese) shows
�in place of each one; hover over the name to see it written out, such asreport\u202Efdp.exe. The panel still acts on the real name. - Keyboard: the arrows move, Space selects, Enter opens a folder, F2 renames, Delete deletes.
Servers and credentials
- A server holds everything an
ssh user@addressneeds: the address, port, user name, credential and the session options. The same machine with another user is another server; Duplicate helps. - Changes to a server apply to new sessions. The running ones keep the address they started with.
- To sign in, prefer Generate a new key: the private key never leaves Termavox, and you install the public key on the server. You can also paste a key, use a password, or choose None (the server asks for the password in the terminal).
- Under Advanced: protection, startup command, environment variables, keepalive, scrollback lines and reopening unprotected sessions.
- Termavox runs in Docker on the same machine you want to reach? Use Add this Docker host.
Host keys and server sign-in
- On the first connection Termavox asks Trust this host key?. Compare the fingerprint with the server's (there,
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub) before you trust it. - The decision applies to the address: every one of your servers at that address, and only for you.
- To trust a key before the first session, use Test connection or Paste expected fingerprint on the server's page.
- Servers that ask for a code (2FA) or a password show the question in the pane. Answers go to the server and are never stored. If the prompt expires, use Retry.
Sessions left running on a server
A protected session's tmux keeps running on its server while Termavox is down. That is on purpose: when Termavox is back, it reconnects to it. It is only left behind when Termavox forgets it: another Termavox installation, or this one after its database was reset.
- The workspace says Sessions found on… when it sees one of these while connecting.
- On the server's page, Sessions on this server → Check now lists them. Adopt brings one into the workspace, with the same screen; End… stops its programs.
- Sessions you had already ended that were still running there are ended automatically.
Account and administration
- Password (Settings → Account): changing it signs out your other browsers. Forgot it? Ask an administrator for a temporary password.
- Two-step verification: a code from an authenticator app at every sign-in. An administrator can make it required.
- Language: in the account menu, under Language….
- Version: the last line of the account menu shows the version running, such as “Termavox 0.1.0”. Include it when you report a problem in the project's issues on GitHub. A security problem goes privately instead, as the security policy explains.
- Activity shows what happened to your sessions. Terminal input and output are never recorded.
- Administrators create users, can require two-step verification, cap the running sessions per user (default: 50), turn the file panel on or off and read the audit log.