XFiles
XFiles Keep terminal sessions running

Keep terminal sessions running

On iPhone and iPad, an SSH connection does not survive you leaving the app. Anything running in that shell stops with it. A terminal multiplexer on your server fixes this, and XFiles reattaches to it for you every time you connect.

This guide explains why it happens, helps you pick tmux, Zellij or Herdr, install it, switch it on in XFiles, and use it from a phone keyboard. It applies to the SSH terminal of SFTP locations in XFiles Pro for iOS.

Quick start (two minutes)

  1. Install tmux on the server, for example on Debian or Ubuntu: sudo apt install tmux.
  2. In XFiles: Settings → Network locations, tap ⓘ next to your SFTP location, then Keep sessions running. Pick tmux and go back. Tap Save.
  3. Open the terminal. From now on you can switch apps, lock the phone or lose signal; when you come back, XFiles reconnects to the same screen.

1. Why the shell stops on iPhone

iOS does not let apps keep running in the background. Soon after you switch to another app, lock the screen, take a call, walk out of Wi‑Fi range or hand over to mobile data, iOS suspends XFiles and the SSH connection closes.

On the server, the shell you were using belongs to that connection. When the server notices the connection is gone, it hangs up the terminal: the shell receives a hangup signal, exits, and takes every program started from it along. A half-finished apt upgrade, an rsync, a build, a training run, or an AI coding agent such as Claude Code or Codex stops in the middle.

XFiles reconnects automatically when you return, but a new connection can only start a new shell. No app, on any phone, can bring a terminal back once the server has closed it. The fix has to live on the server.

2. What a multiplexer does

A terminal multiplexer is a program that runs on the server and owns your shells. Your SSH connection becomes a window into it: close the window and the room is still there, with everything still running inside. Reconnect and you see the same screen, including output that scrolled by while you were away.

You also get extras that are handy on a small screen: several windows or tabs in one connection, split panes, a scrollback you can search, and the option to look at the same session from your computer.

3. What XFiles does for you

Once a multiplexer is chosen for a location, you never type attach commands. On every connection, including automatic reconnects, XFiles:

4. tmux, Zellij or Herdr?

tmuxZellijHerdr
Good forEveryone. The safe default.Newcomers: the keys are always shown at the bottom.Running several AI coding agents side by side.
InstallIn every package manager.Homebrew, Arch, Alpine; a single download elsewhere.An install script or Homebrew.
Keysctrl b, then a key.ctrl + a letter opens a mode; hints on screen.ctrl b, then a key; mouse-first.
Swipe to scroll in XFilesAfter set -g mouse on.Works out of the box.Works out of the box.

Not sure? Choose tmux. If one of them is already installed, that one is the easiest choice: XFiles checks the server for you and marks it Recommended.

5. Step 1: Install it on the server

Run one of these on the server. If you have no other way in, open the XFiles terminal for that location (a plain shell is fine), paste the command and press return. Commands that start with sudo ask for your password.

Not sure what is installed? XFiles checks in step 2, or run command -v tmux zellij herdr.

tmux

SystemCommand
Debian, Ubuntu, Raspberry Pi OSsudo apt update && sudo apt install -y tmux
Fedora, RHEL, Rocky, Almasudo dnf install -y tmux
Arch, Manjarosudo pacman -S tmux
Alpinesudo apk add tmux
openSUSEsudo zypper install tmux
FreeBSDsudo pkg install tmux
macOS (Homebrew)brew install tmux

Zellij

Debian, Ubuntu and Fedora have no official package, so use the single-file download. It needs no administrator rights and installs into your home folder, where XFiles looks for it:

mkdir -p ~/.local/bin && curl -fsSL https://github.com/zellij-org/zellij/releases/latest/download/zellij-$(uname -m)-unknown-linux-musl.tar.gz | tar -xz -C ~/.local/bin

That covers 64-bit Linux on Intel/AMD (x86_64) and ARM (aarch64). Elsewhere:

SystemCommand
Archsudo pacman -S zellij
Alpinesudo apk add zellij
macOS or Linux with Homebrewbrew install zellij
Anything with Rustcargo install --locked zellij

Herdr

Linux (x86_64, arm64) and macOS. The script installs into ~/.local/bin without administrator rights:

curl -fsSL https://herdr.dev/install.sh | sh

With Homebrew: brew install herdr. See herdr.dev for other options.

6. Step 2: Turn it on in XFiles

  1. Open Settings → Network locations.
  2. Tap ⓘ next to your SFTP location. (No location yet? Tap + and add one with the server address and your SSH login.)
  3. Under SSH terminal, tap Keep sessions running.
  4. XFiles signs in and checks the server. Each option then shows Installed with its version, or Not installed, and one is marked Recommended.
  5. Tap the one you want. If it is not installed, the screen shows the install command for that exact server, with a copy button.
  6. Go back and tap Save.

From the terminal. When a location still uses a plain shell, XFiles shows a card the first time you open its terminal, and again right after a dropped connection replaced your shell. Set up opens the same screen; after you save, XFiles offers to reconnect so the change takes effect right away.

7. Step 3: The one-minute test

  1. Open the terminal. You should see the multiplexer: tmux draws a green status line at the bottom; Zellij shows tabs at the top and key hints at the bottom. The first time, XFiles also confirms with Kept running by tmux (or Zellij, Herdr).
  2. Start something that takes a while, for example a counter:
    for i in $(seq 1 600); do echo "$i"; sleep 1; done
  3. Switch to another app, or lock the phone, for a minute.
  4. Come back to XFiles. It reconnects by itself and the counter is still counting. The numbers printed while you were away are in the scrollback.

If instead the counter is gone and you see a fresh prompt, the multiplexer did not start. XFiles shows a yellow card in that case; see Troubleshooting.

8. Typing multiplexer keys on a phone

Multiplexers are driven with ctrl and alt combinations. XFiles adds a two-row key bar above the keyboard:

ctrl, alt and ⇧ (Shift) are blue here. ✋ switches swipe mode; ⌨ swaps the keyboard for a panel of symbols. Swipe the bar sideways for symbols, F1–F12 and page keys; Settings → Terminal Key Bar rearranges it.

To leave, you never need a multiplexer key: close the terminal or switch apps. Everything keeps running.

9. tmux cheat sheet

Every tmux shortcut starts with the prefix ctrl b: press it, let go, then press the key in the table.

ToPress
Open a new windowctrl b then c
Next / previous windowctrl b then n / p
Pick a window from a listctrl b then w
Split side by sidectrl b then %
Split top and bottomctrl b then "
Move between panesctrl b then an arrow key
Zoom a pane to full screen and backctrl b then z
Close a pane or windowtype exit
Scroll backctrl b then [, move with arrows or pgup, q to stop
Rename the windowctrl b then ,
Show every shortcutctrl b then ? (q to close)

Swipe to scroll. tmux ignores the touch screen until mouse support is on. Run this once on the server:

echo 'set -g mouse on' >> ~/.tmux.conf && tmux source-file ~/.tmux.conf

Now a swipe scrolls the history and a tap selects a pane.

ctrl b then d detaches. You do not need it in XFiles: after a detach the terminal shows Disconnected until you tap ↻ Reconnect.

10. Zellij cheat sheet

Zellij uses modes. ctrl plus a letter switches mode, and the bar at the bottom always lists what you can press next. esc or return goes back to normal.

ToPress
New panealt n
Pane mode: new, split right or down, close, full screenctrl p, then n, r, d, x or f
Move between panesctrl p, then arrow keys, then esc
New tabctrl t then n
Go to tab 1–9ctrl t then the number
Scroll back and searchctrl s, arrows or pgup, s to search, esc to stop
Session managerctrl o then w
Pass every key to the program inside (vim, htop…)ctrl g locks; ctrl g again unlocks

ctrl q quits Zellij and ends the session, with everything running in it. To leave, just close the XFiles terminal.

The first time it starts, Zellij may show a short setup screen to pick a key preset. Default is fine. If its ctrl keys clash with a program you use a lot, choose the Unlock-First preset in the configuration screen (ctrl o then c).

11. Herdr cheat sheet

Herdr is made for watching several coding agents at once and is mouse-first: tap panes, tabs and workspaces to focus them. Its keyboard prefix is ctrl b.

ToPress
New tabctrl b then c
Next / previous tabctrl b then n / p
Split right / downctrl b then v / -
Workspacesctrl b then w
Scroll back (copy mode)ctrl b then [
Show every shortcutctrl b then ?

12. Several devices, one session

There is no session name to set. Every device that connects to the same server and user lands in the same session, so you can start on one and continue on another:

The same session is reachable from your computer:

Attach from a computerLeave it running there
tmuxtmux attachctrl b then d
Zellijzellij attach (with several sessions, zellij ls shows their names)ctrl o then d
Herdrherdrctrl b then q

When two screens of different sizes share one tmux window, tmux sizes it for the smaller one. set -g window-size latest in ~/.tmux.conf makes it follow whichever device you used last.

13. Ending a session for good

Type exit in every window or pane, or run one of these on the server (tmux ls and zellij ls show the names):

tmux kill-session -t NAME
zellij kill-session NAME && zellij delete-session NAME
herdr server stop

When the last shell inside the session exits, the multiplexer ends and the XFiles terminal shows Disconnected. Tap ↻ Reconnect to start a fresh session.

14. Troubleshooting

XFiles says it isn't installed, but it is

XFiles looks for the program the way a login shell does. If you installed it somewhere unusual and only added that folder to PATH in ~/.bashrc, a login shell does not see it. Add the folder in ~/.profile (or ~/.bash_profile, ~/.zprofile) instead. To test what XFiles will see, run this from any computer:

ssh you@server 'sh -lc "command -v tmux"'

Then tap Check again in Keep sessions running.

The session is gone after the server restarted

Multiplexer sessions live in memory, so a reboot ends them. XFiles creates a new one on the next connection. Plugins such as tmux-resurrect, or Zellij's session resurrection, can restore the layout.

The session disappears every time I disconnect

Some servers end all of a user's processes at logout (KillUserProcesses=yes in /etc/systemd/logind.conf; most distributions ship no). Ask the administrator to turn it off, or start the multiplexer in its own scope as described in man systemd-run. Shared hosting that forbids background processes cannot keep sessions at all.

Swiping doesn't scroll in tmux

Turn on mouse support (see the tmux section), or use ctrl b then [ and pgup. Also check that the hand icon on the key bar is on.

Zellij takes over keys I need

Press ctrl g to lock Zellij: every key goes to the program inside until you press ctrl g again. Or switch to the Unlock-First preset.

The screen looks garbled after rotating or opening the keyboard

XFiles resizes the remote screen whenever the space changes. If a program does not redraw by itself, press ctrl l.

I typed exit and now it says Disconnected

exit closed the last shell in the session, which ended it. Tap ↻ Reconnect for a new one. To step away without ending anything, close the terminal instead.

Can't XFiles just stay connected in the background?

No iOS app can: the system suspends background apps and closes their connections. Something on the server has to keep your work alive, and that is exactly what a multiplexer is for. nohup keeps a single command running, but you cannot get back to its screen; a multiplexer gives you the whole terminal back.

15. What XFiles runs on your server

There is no XFiles server in between; see the XFiles Pro privacy policy.