FAQ

When you switch away, Term asks the system for a short background grant and holds the connection for up to 55 seconds — come back inside that window and the session is untouched, so glancing at another app will not disconnect you. The system may allow less than that (its own window is capped at around three minutes, or about a minute on low battery), and Term hands the grant back the moment you return. Past the window, to save power, HarmonyOS suspends apps that stay in the background, and the connection closes with them: the SSH session ends, and whatever was running inside it stops.

Here are three ways to keep a session alive — simplest first, sturdiest last.

As long as Term is on screen, the session stays alive. Put it in a floating window or split screen and it still counts as foreground — so you can use another app without dropping the connection.

1. Floating window: swipe up from the bottom of the screen and pause to open Recents, then tap the floating window icon on the Term card. The terminal shrinks to a small draggable window.
2. Split screen: from the same Recents view, tap the split screen icon on the Term card and pick a second app to sit alongside it.
3. Leave the session running while you look something up or reply to a message, then carry on typing — the connection never dropped.

Run tmux (or screen, or zellij) on the server, ideally over a mosh connection. mosh survives network changes and reconnects by itself, while the multiplexer keeps your programs running on the server — disconnect whenever, come back whenever, pick up exactly where you were.

1. Install tmux on the server: sudo apt install tmux (Debian/Ubuntu) or sudo dnf install tmux (Fedora).
2. Connect to the host from Term and start a named session: tmux new -s work.
3. Work inside it as usual — the session stays on the server even if the phone locks, backgrounds Term, or loses the network.
4. Reattach after reconnecting: tmux attach -t work, and everything is as you left it.
5. Going further: set a new host’s transport to mosh (the server needs mosh-server) and roaming between Wi-Fi and cellular stops dropping you.

# start a named session
tmux new -s work

# reattach after reconnecting
tmux attach -t work

Let long jobs run detached from the terminal: start them inside tmux/screen, or use nohup … &. The job finishes on the server even if the app disconnects — reconnect afterwards to check the result.

# run detached, output to out.log
nohup ./long-task.sh > out.log 2>&1 &

# check progress after reconnecting
tail -f out.log

Start a named session and Term notices that tmux is the foreground program, then swaps the key bar above the soft keyboard for a tmux set — esc, the ^B prefix, the four arrows, and a row of prefix combos that go out on one tap. It recognises tmux from the command shell integration reports, which is on by default, so leave that switch alone.

1. Connect to the host and start a named session: tmux new -s work.
2. The key bar switches to the tmux set: ^B[ for copy mode (this is how you scroll back), ^Bz to zoom a pane, ^B% and ^B" to split, ^Bc for a new window, ^Bn / ^Bp for the next and previous window, ^Bw for the window list, ^Bd to detach — with ^C and ^R still there, because underneath it is still a shell prompt.
3. The set is built in and follows the foreground program — there is nothing to configure. For any other control key, tap ctrl at the left end of the key bar: it arms the modifier for the next key you press (alt and shift work the same way).
4. Detach with ^Bd when you leave — the session, and everything running in it, stays on the server.
5. Reattach next time with tmux attach -t work and it is all as you left it.

Install mosh on the server first — what Term needs out of it is the mosh-server binary. Then edit the host and set Connection to Mosh; the hint under the control already says it: the sign-in still goes over SSH, and only then is the session handed to UDP. Which is why the server side also has to let UDP 60000–61000 through — or, if only a few UDP ports are open to you, pin mosh to those in the host editor. Once you are on it, switching between Wi-Fi and cellular or losing signal will not drop you — the session reconnects itself, and the background rule above does not apply to it.

1. Install it on the server: sudo apt install mosh (Debian/Ubuntu) or sudo dnf install mosh (Fedora).
2. Edit the host in Term → Connection → Mosh. Host, port and username stay exactly as they were for SSH, because the sign-in is still SSH.
3. Open UDP 60000–61000 on the server and anywhere in between — left to itself, mosh picks a port inside that range. If only certain ports are open to you, name them in UDP port or range (optional) under Connection: one port (60000) or a range (60000:61000). Blank keeps the automatic behaviour.
4. To confirm you really are on mosh, run ps -o args= -p $PPID: the shell’s parent should print as mosh-server, not sshd.

# install mosh — what Term needs is the mosh-server binary
sudo apt install mosh
sudo dnf install mosh

# confirm the parent process really is mosh-server
ps -o args= -p $PPID

Going further: Customizing mosh — ports, session timeout, init script

Because mosh repaints the screen rather than streaming every line, so there is no history for Term to scroll — that is mosh’s design, not a limit in Term. If you want scrollback, run tmux (or screen, or zellij) on the server and use its own: in tmux that is copy mode, ^B[ on the key bar (see the tmux section above). The app says the same thing in place — as a first-run mosh tip, and as a toast the first time you drag upward in a mosh session.

Yes. Closing a mosh tab shuts the remote session down: Term sends mosh’s shutdown datagrams to end it, and if those never arrive it goes back in over SSH to clean up the stranded mosh-server — so a mosh-server does not get left behind on the host. If you want to come back to it later, leave the tab open. And if the work has to outlive the tab, that is exactly what tmux is for: run it inside the mosh session, and closing the tab only detaches you.

mosh signs in over SSH first and then hands the session to UDP — these two messages are the two halves failing, and Term tells you which one you hit. The failure screen keeps the raw error and its E_ code underneath, which is what to paste into a bug report, and offers Edit host and Retry.

1. Connected, but mosh-server didn't start. The sign-in worked and the binary is what is missing — install mosh on the server, or switch this host back to SSH.
2. Connected over SSH, but mosh's UDP session didn't get through. mosh-server started and the datagrams never arrived — open UDP 60000–61000 on the server and anywhere in between.

Yes, with two lines in your tmux.conf. Term decodes sixel, the kitty graphics protocol and iTerm2’s imgcat (OSC 1337) natively — PNG, JPEG and the first frame of a GIF — and composites the image underneath the text. To get through tmux, images use kitty’s Unicode-placeholder scheme, where the image id rides in a cell’s truecolor foreground. So tmux has to do two things: pass the escape sequence through, and keep truecolor inside the session. Without the second, tmux downsamples the id-carrying colour to 256 colours, the id is corrupted, and the image breaks. Both lines need tmux 3.3a or newer — an older tmux answers "unknown option" on start and the images silently never appear.

# let the image escape sequences through
set -g allow-passthrough on

# keep truecolor inside tmux, or the image id is corrupted
set -as terminal-features ",*:RGB"

mosh sessions are unaffected — they survive the background and reconnect on their own, so the background warning does not apply to them. The app says the same thing in place: the background-session banner on the host page opens a "keep sessions alive" help page.

References: mosh.org · tmux — getting started · zellij · GNU screen · nohup(1)