The remote agent

A plain SSH session ends when the connection drops. If you lock your phone, lose signal or switch networks, anything running in that session dies.

The Termphin agent keeps your session alive on the server. When you reconnect, you pick up where you left off.

What the agent is

The agent is a small program that runs on your server. It holds your shell open so closing the app or losing signal does not kill what you were running.

The first time you connect to a machine with the agent on, Termphin uploads the binary over SSH. That first connection takes longer than later ones. There is no separate install step.

If the agent cannot run on a server, Termphin falls back to a plain shell rather than failing the connection.

What it does on the server

• Runs on Linux, Windows and macOS servers, on x86_64 or arm64.
• Keeps one shell per session alive and replays what you missed when you reconnect.
• Opens no network port. It is reachable only through a Unix socket in your home directory, created with mode 0600.
• Runs as your user. No root, nothing installed system-wide, no service or cron entry.
• Lives entirely under ~/.cache/termphin/sessions. Ending a session removes its directory.
• Recent output is buffered for replay under that same session directory, deleted along with everything else when the session ends.
• Termphin checks the binary's SHA-256 checksum before uploading it, and again against the copy already on the server.
• It is open source, so you can read exactly what it does.

When the connection drops

Because the shell is still alive on the server, Termphin retries the transport on its own rather than telling you about it. It makes up to five attempts - the first after five seconds, the rest ten seconds apart - counting down on the tab as it waits. On reattaching it replays what you missed.

A plain SSH session gets none of this: there is nothing left on the server to return to, so it reports the error instead of retrying.

Having no signal at all is treated separately. There is nothing to retry against, so no attempt is spent - the tab says it is waiting for a network and picks up where it left off once there is one.

What it does not do

The agent does not survive a server reboot. If the server itself reboots, the shell is gone. Termphin reattaches into a fresh one in the same directory and tells you: "The remote shell was restarted - reattached in the same directory, previous shell state gone."

Using it from a terminal

The agent is an ordinary command-line program, so you are not limited to driving it from the app. Once it is on a server - whether Termphin put it there or you installed it yourself - you can run it from any shell on that machine, including a plain ssh session from a laptop.

Termphin uploads it to:

~/.local/lib/termphin/termphin-agent

On Windows it is termphin-agent.exe in the same place. That directory is not on PATH, so call it by its full path or add it yourself.

These are the commands Termphin itself runs, so they are the ones to rely on:

# List the sessions running on this machine.
~/.local/lib/termphin/termphin-agent list

# Attach to one by name.
~/.local/lib/termphin/termphin-agent attach work

# Attach and replay the output you missed.
~/.local/lib/termphin/termphin-agent attach --replay work

# Rename a session.
~/.local/lib/termphin/termphin-agent rename work deploy

# End a session and everything running in it.
~/.local/lib/termphin/termphin-agent kill work

list prints one session per line, tab-separated: name, window count, creation time, and whether something is currently attached.

A session started from the terminal is the same kind of session the app attaches to, so the two can be used interchangeably - start something over SSH from a laptop and pick it up on the phone later, or the other way round.

Turning the agent off

In Settings, under Connection, the "Termphin agent" switch is on by default. Turning it off means new sessions connect as plain SSH with no persistence. It does not remove anything already on a server.

What you can do with a session backed by the agent

• Detach it to leave it running on the server.
• Re-attach later to pick up where you left off.
• Rename it or end it, which kills it on the server.