Keep SSH sessions alive: Wardterm documentation

Reconnect automatically

When a connection drops, the app tries again and opens a new shell. It waits a little longer after each try, for about seven minutes. It stops if the server's key changed or the server needs a login.

Turn it on or off in Settings, Sessions: Reconnect automatically.
While it waits, the session says Trying again in 4 s. Nothing you type is sent. Try now tries at once.

A reconnected shell is a new one. To keep the same session, see below.

Keep This Session

When the network drops, on a train or when the phone changes network, a kept session keeps running on the server with the programs in it, an AI tool included. When the network is back, Wardterm attaches to the same session on its own.

Open the menu of the session: ... on iPhone and iPad, the menu of the tab or Session in the menu bar on Mac. Choose Keep This Session, then Continue.
The session moves into tmux on the server, in the same tab. A program that already runs stays in its shell: if something runs there, that shell stays open in the tab beside.
When you start an AI tool (Claude Code, Codex, Gemini CLI and others) in a plain session, Wardterm asks first: Start As Is, or Start and Keep, which keeps the session and starts the tool in it. Don't ask again for this server turns the question off on that device.
The menu of a kept session says that it is kept. To end it, close it in Active Sessions, in the menu of the server, or type exit in its shell.

It is part of every plan. The server needs tmux.

What you see

A mark on the tab of the session: This session keeps running on the server if the connection drops.
When the connection drops: Connection lost. The session keeps running on the server., then the state of the reconnection
When it is back: Back in your session. Nothing was lost.
On the Lock Screen of iPhone and iPad: Reconnecting… while the network is away, or Session ended on the server.
If the command or the AI tool ended in the meantime, its alert arrives. See Session alerts, part of Pro.

A server without tmux

The session stays as it is, and a notice says: To keep sessions running if the connection drops, this server needs tmux.

Install tmux types the install command of the server's system in the terminal, without pressing Return. You confirm it, with the sudo password if asked.
Before an AI tool starts, Install tmux types the command in a new session on the same server, and Start As Is starts the tool without keeping the session.
Not now closes the notice.

Once tmux is there, the session is kept.

Your own tmux

If your shell starts tmux when you sign in, or you start tmux yourself, your tmux keeps the session. The menu of the session says Your tmux keeps this session.

A session closed elsewhere

If the session is closed from another device while you are offline, or the server restarts, the tab says Session ended on the server., with Close and New Session.

Keepalive

Keepalive sends a small signal at regular intervals, so that a connection that died is noticed, and so that routers do not close a quiet one.

For every server: Settings, Sessions, Show more: Keepalive, Off or 15, 30, 60 or 120 seconds.
For one server or group: Show more, Connection, Keepalive.

The same with OpenSSH, in ~/.ssh/config:

ServerAliveInterval 15

Mosh

With Mosh, a session survives a change of network and the sleep of the device. See Mosh.

On iPhone and iPad

With Keep sessions open in background on, in Settings, Sessions, your open sessions stay connected while you use other apps or lock the screen. It is on from the start. To close them all, remove the Live Activity from the Lock Screen.

With it off, the system pauses the app after a short while and its connections close. With reconnection on and the session kept in tmux, you find your work again when you come back. See Sessions drop when I leave the app.

In the same place:

Show on Lock Screen and Dynamic Island shows your open sessions there, with their state.
Hide server names shows Session 1, Session 2 instead.
In the Dynamic Island chooses what it shows while small: Session count or Minimal, and with Pro Agents waiting. Touch and hold the island to see your sessions.

Keep sessions alive