# Why your SSH session dies when the iPhone locks — and how to stop it

iOS suspends apps, phones change networks, and plain SSH survives neither. The fix is two tools doing two different jobs: mosh for the connection, tmux for the work.

*updated 2026-08-25*

Everyone who uses a terminal on a phone hits this within a day. You start something
that takes a while, the screen locks, you come back, and the session is gone — along
with whatever it was doing.

It is not a bug in the app you're using. It's two separate facts about mobile
devices colliding with an assumption SSH made in 1995.

## The two problems

**iOS suspends apps.** When you leave a terminal app or the screen locks, iOS
freezes it and, before long, may terminate it. The app cannot keep a socket alive
through that. This is not something an app can opt out of; it is how the platform
manages battery and memory.

**Phones change networks.** SSH ties a session to a TCP connection, and a TCP
connection to an IP address. Walk out of the house, Wi-Fi hands off to cellular,
your address changes, and the connection is dead by definition.

These need different fixes, which is why partial solutions feel unreliable — people
try one, see it fail for the other reason, and conclude nothing works.

## Fix one: tmux, for the work

`tmux` runs on the **server**. It holds your shell — and anything running in it —
in a session that belongs to the server rather than to your connection.

```sh
tmux new -A -s main
```

`-A` means "attach if it exists, otherwise create," so the same command is safe
every time. Now everything you start lives inside that session. Your phone
disconnecting, suspending, running out of battery, or falling in a river makes no
difference to it. Reconnect and:

```sh
tmux attach -t main
```

You are back, mid-command, with the scrollback intact.

**This is the important half.** If you only do one thing, do this one.

In Tessera you can set a host to attach automatically on connect, so opening the
app is the reattach — there is no command to remember. Because Tessera speaks
[tmux control mode](/docs/tmux/), your tmux windows come back as real tabs and your
panes as real split views rather than as drawn characters.

## Fix two: mosh, for the connection

tmux protects the work, but you still have to reconnect, and on a flaky train
connection reconnecting constantly is miserable.

[mosh](/docs/mosh/) fixes the transport. It authenticates over SSH, then hands the
session to a UDP protocol that keys the session to a cryptographic identity rather
than to your IP address. Change networks and the next datagram simply arrives from
somewhere new. Sleep the device and it picks up when you wake it. It also echoes
your keystrokes locally, so typing feels immediate even on a bad link.

The requirement is that `mosh-server` is installed on the host and a UDP port range
is reachable — usually `60000–61000`.

One caveat people hit: plain mosh has no scrollback worth the name. Tessera gives
mosh sessions real, searchable scrollback, which removes the main reason people
avoid it.

## Use both

They solve different halves and compose cleanly:

| | Survives network change | Survives app suspension | Survives device reboot |
|---|---|---|---|
| SSH alone | no | no | no |
| SSH + tmux | reconnect needed | **yes** | **yes** |
| mosh alone | **yes** | partly | no |
| **mosh + tmux** | **yes** | **yes** | **yes** |

Connect with mosh, land in tmux, and the only thing that ends your session is you
ending it.

## Things that don't work

- **Keep-alives.** `ServerAliveInterval` helps a connection survive a brief stall.
  It does nothing about the app being frozen or your IP changing.
- **Leaving the app open.** iOS still suspends it. Backgrounding audio or location
  to stay awake is an App Store violation and a battery disaster.
- **`nohup` and `&`.** These keep a *process* alive, which is useful, but you lose
  the terminal — no output, no interaction. For an interactive program, or an agent
  that will ask you a question, that isn't enough.
- **`screen`.** Works fine, and if you already use it, keep using it. tmux is more
  actively developed and its control mode is what lets a client render real panes.

## Questions

### Why does my SSH session disconnect when my iPhone screen locks?

Because iOS suspends the app, and a suspended app cannot hold the connection open.
The fix is not to keep the app awake — it is to move the work onto the server with
tmux, so the session survives the app being suspended or killed.

### How do I keep a terminal session running on iPad?

Run tmux on the server and attach to it: `tmux new -A -s main`. Everything inside
survives disconnection. Add mosh for the connection itself if you move between
Wi-Fi and cellular. Tessera can attach to your tmux session automatically each time
it connects.

### Does mosh replace tmux?

No — they solve different problems. Mosh keeps the *connection* alive across
roaming and sleep. tmux keeps the *work* alive when the connection ends anyway, or
when iOS kills the app. Use both.

### What port does mosh need?

mosh authenticates over SSH on port 22, then uses UDP, conventionally in the range
60000–61000. If SSH connects but mosh hangs, that UDP range is almost always what
is blocked.

### Can I get my scrollback back after reattaching?

With tmux, yes — the scrollback lives in the tmux session on the server. Plain mosh
does not preserve scrollback usefully, which is a common complaint; Tessera gives
mosh sessions real, searchable scrollback of their own.