Servers

A server is a saved connection: where the machine is, who you are on it, and how to log in.

On the start page, the button under Open a folder… reads Add a server while you have none and Manage servers once you have one. The Servers heading below it has the same two as icons: the plus opens the form for a new server, and the sliders open the list.

The page lists your saved servers. Add a server opens the form under the list, a row's Edit opens the same form for that server, and Close puts it away. An existing server shows its id instead of letting you edit it, because the id cannot change once saved.

A green dot before a server's name means it is connected. Beside Edit and Delete, New terminal (a terminal with a plus) opens a new terminal on that server; it is hidden while a form is open. A server with terminals you left open (see Keep in the terminal) lists them under its row, after Open terminals, as numbered chips: a green dot for one that is running, an amber dot and ended for one whose shell has ended. Tap a chip to go back to that terminal; on a desktop, one in a window of its own is listed too, and its chip brings that window forward.

Delete on a row removes the server from this device, with its saved password or passphrase, and closes its connection and any terminals you left open on it. It asks first; nothing on the server itself changes.

A server's folders

A server's folder is browsed like one on this device (see Tree and sidebar). Its header has New folder and Upload, which takes files from the system's picker, on a desktop and on Android, and never replaces a folder with a file. Each row's ⋯ has Delete…; a file's also has Download, and what this device keeps of it (see Files offline).

A folder whose connection has dropped connects again on its own when you next use it. On a phone that happens often: Android cuts the network a few seconds after the app leaves the screen, including while you choose files to upload. A download cut off that way picks up where it stopped once the app is back.

The free edition and Pro

A copy installed from an app store is the free edition, which saves a few servers: two from Google Play, four from the Microsoft Store. Where the store sells it, Unlock Pro saves as many as you like, for one payment with no subscription, and Restore purchase gets it back on a new device or after a reinstall. Google Play sells Pro; the Microsoft Store does not yet, so a copy from there keeps its four.

A copy downloaded as a file, such as the Windows .exe or an APK, has no store to buy from and no limit.

Past the limit, servers you already have keep working and can still be edited and deleted; only adding another needs Pro, where the store sells it. The free edition also keeps that many terminals running after you leave them (see Keep in the terminal); keeping more running needs Pro too, where the store sells it. Files, the terminal and keys are free either way.

Moving servers to another device

Export… on the list shows a QR image for another device running Telechore to scan. Tick what to include: which servers, their host keys, the passwords and passphrases saved on this device, and any key this app made that those servers use. A key this app did not make is never included in a configuration code, and the sheet names any server that will arrive without its key.

The meter shows how much fits. It measures size, not servers: a short host name with no host key takes a third of the room of a long one with a key. The limit is well below what a QR image can hold, because a denser image is harder to scan.

The password beside Export encrypts the code, and you type the same one on the other device. It is optional, and any length will do. A code with only servers and host keys hardly needs one: all it reveals is host names and user names. For a code that carries a password, a passphrase or a key, the sheet warns you when the box is empty or short, but still lets you go ahead. When there is no password, the sheet says so: anyone who photographs the QR image has what is inside.

The QR image stays on screen for a minute; closing the sheet removes it sooner. The other device can read the code for three minutes if it was scanned, and for fifteen if it was pasted as text, since text is usually sent by email or message. Nothing is written to disk on either device. The time limit stops the code being used again later, but it does not help against a photo someone has already taken: a photo can be turned back into text and pasted. Against that, only the password protects you.

Copy as text is beside the QR image on every device. The QR image is for a device in front of you; the text is for one that is not, and it is the only way to get a code from a phone to a desktop. It is the same code, and the same password opens it.

Import… reads a code. Paste it or scan it, and before anything is saved the next screen shows what the code holds: one row per server, with its state, then the host keys, secrets and keys that came with them. Untick anything you do not want.

Each server row has a state:

• new: this device does not have the server. It is saved as it arrived.
• already here: the id is taken. A free one is offered, such as prod-web-2, to keep both; or type the old name back to overwrite the one you have.
• arrives without its key: the server uses a key the other device did not make, so the key is not in the code. The server is saved with a password login; give it a key on the Auth tab afterwards. If it overwrites a server already here, it keeps that server's key.

A row can be both already here and without its key; the label shows the first and the note under it the second.

Host keys are imported only for hosts this device has no key for yet. A host you have already verified keeps its key, whatever the code says.

If a key in the code has the same name as a different key on this device, it is saved under a free name, and the servers that use it are pointed at the new name. The same key arriving twice is saved only once.

In the free edition, servers over the limit arrive unticked. A renamed server counts as new; overwriting an existing one does not.

Nothing is saved until you press Import, and Cancel discards the code.

The form

The form has three tabs: Server, Auth and Terminal. The label and the id sit above them, and Save, Test, Disconnect and Close below. On a phone this keeps what you are typing into on screen above the keyboard.

If Save finds a problem, it opens the tab with the problem, so pressing Save with no host from the Terminal tab takes you to Server. A tab shows a dot while it holds a message you have not seen.

The fields

Above the tabs:

• Label is the name you see. Id is the name the app uses internally. It starts out based on the host, or on the SSH alias when that is all there is, and it cannot change once saved: a new id would make a second server.

On the Server tab:

• Host is what you would type after ssh.
• User may be empty on a desktop, and then your local user name is used, as with ssh host. On Android it is required, since a phone has no user name to fall back on.
• Port is usually best left empty. That lets an alias in ~/.ssh/config set the port; otherwise 22 is used, which is what the greyed 22 means.
• Initial path is where browsing and a terminal start. ~ suits most accounts.
• SSH alias fills in any empty host, user and port from ~/.ssh/config. Values you type here take priority. Desktop only, since a phone has no ~/.ssh/config.
• Cache this server's files keeps what you open on this server on this device, with how much it takes and Clear cache… below it. It is on by default; see Files offline.

On the Terminal tab:

• Size is one of three.
  • Fit the screen: programs get whatever fits, about 33 columns on a phone held upright, too narrow for tmux or htop.
  • Fixed at a number of columns and rows, with 80×24, 100×30 and 132×43 a tap away. Programs always see that size; you zoom and pan around it.
  • Fixed columns: the columns fill the width, and programs get as many rows as fit at that size. The rows change when the screen does (the keyboard, turning the phone) and when you zoom. You can pan and zoom across, never up or down: the rows always fill the screen.
• Start by decides how the terminal opens, and where Reset view goes:
  • Fit: the whole grid in view, one side meeting the screen's edges and room left on the other.
  • Fill (Fixed only): the screen covered, one side meeting its edges and the other cropped. For Fixed columns fit and fill are the same picture, so it is not offered.
  • Type at a size in pixels, to pan around. Fit is the default.
• Position says where the terminal sits when it opens and when Reset view puts it back: where it rests when it leaves room on the screen, and which part shows when it is cropped: Top, Middle or Bottom, and Left, Center or Right. With Fixed columns the rows fill the screen, so up and down only places what is left below one row. Bottom left is the default, which keeps the last line next to the keyboard. With Bottom, spare room goes above the terminal, and a crop takes off the top. With Middle or Center it's split evenly. It does not limit where you can pan.
• Follow the cursor keeps the cursor on screen for a short while after you type, so you see the answer. A cursor a program moves on its own leaves the view where you put it.
• Send taps to programs that ask for a mouse decides what one finger does where a program is listening for clicks. When it is off, one finger always selects and scrolls. The extra keys send keys either way.
• Keyboard opens this many rows up sets how many shell rows stay visible below the app's keyboard when it opens. Raise it to keep a tmux status line or a wrapped prompt in view. You can drag the keyboard from there; its position is remembered on that device.
• Keep new terminals running when you leave them turns on Keep for every new terminal on this server, so leaving one does not close it. Off by default. It applies to new terminals only; Keep, in a terminal's header, changes it for that one terminal.
• Scrollback is how many lines of history are kept.
• Remote command runs in the terminal instead of your shell. Browsing files does not use it.

Under Advanced on that tab: TERM, the keepalive in seconds, and the environment variables for the server, one NAME=value per line.

These settings are sent along when you export the server. How the terminal uses them is in the terminal.

How a server logs in

The Auth tab lists every key on this device, and three rows that are not keys:

• Password: picking it switches the server to a password login, and shows the password box.
• Path to an SSH key (desktop only): picking it switches the server to a key file on this machine, given by its path, with Browse beside the box.
• Add a key…: for a key that is not on the list yet.

Picking a key only shows it; the server switches to it when you test, install or choose to use it (see Keys, below). A key with a passphrase shows a passphrase box.

Each key in the list shows what kind it is:

• A key this app made: kept in the app's own storage. It is the only kind included when you export servers.
• A key you imported: a copy of a key file, often a .pem from a cloud provider, kept in the app's own storage under its file name. It is never included when you export servers, but it can be sent on its own as a key code.
• A key file on this machine, such as ~/.ssh/id_ed25519: used where it is and never copied. Desktop only.

A path must start with / or ~, or be the name of a key you imported. Relative paths such as keys/mine are refused.

On a phone, a server that came from a desktop with a key path shows that row greyed out, since a phone has no such file. The same goes for a server whose key is no longer on this device. You can still pick the row to see why, but Save and Test stay disabled, with the reason beside them, until you choose a login this device can use.

Moving a server to another key does not delete the old key: it stays in the list until you remove it with Remove key "name".

Unlike ssh, the app does not use IdentityFile from ~/.ssh/config (choose the key here instead), and does not support ssh-agent.

A server that takes only keys says so when you connect, instead of asking for a password it would refuse. Choose a key for it. A server that wants a key and then a password (OpenSSH's AuthenticationMethods publickey,password) offers only the key at first, so it reads the same way: with a key chosen, the password is asked for after the key is accepted.

Where passwords are kept

Never in servers.toml, the list of servers. The form tells you where before you type anything:

• On a desktop: in the system keyring (Keychain, Credential Manager or Secret Service). A key's passphrase is saved once for every server that uses that key, and Forget it forgets it for all of them.
• On Android: encrypted with the Android Keystore. On a phone where the Keystore will not open, in a file only this app can read, not encrypted, and excluded from backups and device transfers; anyone who can unlock or root that phone can read it. The form says which, where you type.
• Where there is no keyring (a Linux machine without Secret Service, or WSL): a secret is kept until the app closes, and asked for again next time.

If you leave the box empty, you are asked when connecting. That box has two buttons: Connect uses the secret once, and Save and connect also keeps it. Pressing Enter is Connect, so it never saves anything. Save and connect is not offered where there is nowhere to keep a secret, or for a one-time code.

A secret that works is also held in memory until the app closes, so a connection that has to reconnect does not ask again. One used with Connect and not saved shows as held until the app closes in the form, not as stored.

Forget it appears beside a saved secret. It removes the secret from this device and closes the connection it opened, so it cannot keep working. The box then says it will ask when connecting, since a saved secret is never shown.

Keys

Picking a key in the list only shows it: its public key, and what you can do with it. The server keeps logging in as before. A newly generated key is shown the same way.

To make a key the login, use one of the buttons in the key's card:

• Test "name" tries one login with this key. Nothing is saved. If it works, the form switches to the key; press Save to keep it. If it fails, the note names the refused key: the server does not have its public key yet, so install it or add it yourself.
• Install it now adds the public key to the server's ~/.ssh/authorized_keys, logging in the way that works today (a password, or a key that already works), then switches the server to the new key. It asks only for what that login needs: the password, or the current key's passphrase, or nothing if it is saved. It also saves your other changes to the server. If the install fails, the server still logs in as before.
• Use "name" for this server is for when you know the server already has the key. The app does not check.

While a key is not yet the working login, its card is outlined in amber and says how the server logs in instead. In the list, the row the server is saved with has a current tag, and a key you picked but have not saved has a chosen tag. A saved key that nothing has logged in with yet shows not installed.

You can save at any time. Saving keeps the key you chose, and also keeps the current password or passphrase until something has logged in with the new key.

Under Add a key…:

• Generate a key makes a new key on this device. It first asks for a name and a passphrase; leaving the passphrase blank is fine, since only this app can read the key file. A passphrase you type is saved with the key, for every server that uses it. Making a key does not switch the server to it.

  To replace a key, generate a new one: it is named beside the old one, such as laptop-2, and the old key stays the login until the new one is installed. Remove the old key from its row when you are ready.

• Import a key file… copies a key into the app. On a phone it is the only way to use a key file, since access to a picked file does not last. If the file has a passphrase, you are asked for it: an encrypted .pem cannot be read without it, and for other keys you can choose to save it.

• Paste a key code… receives a key from another device running Telechore. It shows what arrived and the name it will be saved under; Keep the key saves it. Its passphrase, if any, comes with it. You can then test, install or use it as with any key; a key from another device is usually not on this server yet.

• Browse…, on the Path to an SSH key row, uses a key file where it is and copies nothing. That suits ~/.ssh/id_ed25519. For a provider's .pem in Downloads, Import is the better choice. Desktop only.

Beside the public key:

• Copy Public Key copies it to the clipboard, for adding to a server yourself. If the clipboard cannot be used, select the key by hand.
• Copy Private Key… offers two ways to take the private key off this device:
  • Show it as a QR image, for another device running Telechore to scan. You can set a password for it, of any length or none, and type the same one on the other device. The password is the only protection if someone photographs the QR image, and the box says so when it is empty. A saved passphrase for the key goes with it.
  • Copy it to this device's clipboard, only for a key this app made. The key is not encrypted, and clipboards may keep a history or sync to other devices, so use the QR image to reach another device. This is for pasting into a program on this machine.
• Remove key "name" deletes the key from this device and cannot be undone. It is offered only for keys this app made or imported, never for a key file on this machine, and not while another server still uses the key.

A key code can carry a key you imported; a configuration code never does. Exporting servers sends only keys this app made, while a key code is one key you chose to send. Neither can carry a key file on this machine. A key keeps its kind on the other device: a key this app made can be sent on again, and an imported one is still never included when exporting servers.

Test and Disconnect

Test at the bottom of the form logs in once with the settings as they are on the form, including unsaved edits, and says what happened. It saves nothing, so a working test still needs Save. It always makes a fresh connection, so the answer is about what is on screen now.

Disconnect appears when the server is connected. It closes the connection, and any terminal or file view using it stops; the next thing that needs the server logs in again. Terminals you left open stay listed, marked ended, and Reconnect in one starts a new shell. A connection also closes when its secret is replaced or forgotten, or when you change which key the server uses.

Host keys

The server's identity is checked as in any SSH client. A new host asks you once. A host whose key has changed is refused, and the message shows the old key.

New hosts are saved in the app's own file; the one ssh uses is never changed. On a desktop, ~/.ssh/known_hosts is also read, so a host you have used from the command line does not ask again. A phone has no ~/.ssh, so every host is new the first time. Hashed host names, the default on Debian and Ubuntu, are read too.

Two kinds of line are treated specially:

• A key marked @revoked is refused. If the revocation is out of date, remove that line from the file that holds it.
• @cert-authority lines are not used, because this app does not check host certificates, and an import does not copy them.

A host with two keys of the same type on file, which is normal after a server is re-keyed, is accepted with either one.

The file behind the list

The list is servers.toml, in the app's configuration folder beside known_hosts and the keys. It is TOML, starting with version = 1, with one [[server]] block per server. You can edit it by hand, or copy it to another computer, since it holds no secrets.

It includes the [server.terminal] table from the Terminal tab, which holds only the settings you changed. Anything the app does not recognise, such as a misspelt name or a newer setting, is kept when the editor saves.