The Termio server
What runs on a machine so sessions outlive the app — how termiod is installed, kept alive, updated in place, and inspected when something looks wrong.
Every session runs inside termiod, the Termio server, on the machine that owns
it — including the ones on this Mac. The Mac app, the iOS app and the CLI
are all viewers: they attach to a session and detach from it. Nothing about a
session belongs to the window you were looking at.
That is the whole reason quitting Termio does not kill your agents.
What it is
termiod is a session host, not a window manager. It owns the PTY, keeps the
scrollback, and hands a viewer a snapshot when one attaches. Locally a viewer
reaches it over a Unix socket; remotely the app opens an SSH pipe to the same
binary on the far box. One protocol, both ways — which is why a session on a VPS
behaves like a session here.
Panes, splits and layout are the app's business and never the server's.
Getting it onto a machine
There are two ways in, and both put the same binary in ~/.local/bin. Neither
needs root or a package manager.
On the Linux box itself
curl -fsSL https://www.termio.sh/install | shIt downloads termiod, the termio CLI and termio-tailnet for the box's
architecture (x86_64 or aarch64), checks them against the release's checksums,
installs them, and keeps the daemon running with systemd --user. The builds
are static, so the distribution doesn't matter.
Then it puts the server on your tailnet, with Tailscale built in, and prints a sign-in link. Sign in with the Tailscale account your Mac and iPhone use. The box doesn't need Tailscale installed. Once you've signed in, the installer prints a pairing link and a QR code. Paste the link into Settings ▸ Remote Hosts ▸ ＋ ▸ Pair with a Device… on a Mac, or scan the code with the iPhone app. No SSH is involved after that.
Running it again upgrades in place, and sessions keep running through the
upgrade. Options go after sh -s --:
| Option | What it does |
|---|---|
--version 0.63.0 | Installs that release instead of the latest. |
--no-service | Installs the binaries and leaves starting the daemon to you. |
--no-tailscale | Doesn't join the tailnet. |
--tailscale-auth-key-file FILE | Joins the tailnet with a one-time auth key instead of a browser sign-in. |
--dry-run | Prints what it would do and changes nothing. |
From a Mac, over SSH
Adding a box under Settings ▸ Remote Hosts and pressing Set Up copies the binary over SSH and starts it.
termio server deploy # install or update it here, then verify
termio -H mybox server deploy # same, over your own SSH configdeploy is a reconcile: run it against a box in any state and it ends in the
same one. Termio reads ~/.ssh/config to find the host, so a machine you can
already ssh to needs nothing new. See Devices.
-H (--host) works with every termio command, not only deploy:
termio -H mybox server status, termio -H mybox session attach api.
Keeping it running
termio server service install # launchd on macOS, systemd --user on LinuxWithout a service the server lives as long as your login session. With one it comes back after a crash and after a reboot, which is what you want on a box you only ever reach remotely.
Built-in Tailscale
The server can join your tailnet as a device of its own, named termio, with
Tailscale built in. The machine doesn't need Tailscale installed.
termio server tailscale on # prints a sign-in link the first time
termio pair --qr # the pairing link and QR code, once it's connectedOnly the Tailscale account that signed it in gets in, and each Mac or iPhone still needs the pairing link. The setting survives restarts and reboots.
If your tailnet has HTTPS certificates turned on, clients reach the server at
https://termio.<tailnet>.ts.net. If not, they use its tailnet address on port
8790, which Tailscale already encrypts.
| Command | What it does |
|---|---|
termio server tailscale on --hostname NAME | Uses another device name. |
termio server tailscale on --auth-key-file FILE | Signs in with a one-time auth key instead of a browser. |
termio server tailscale status | Shows whether it's connected, and where clients reach it. |
termio server tailscale off | Leaves the tailnet until on. The device stays signed in. |
termio server tailscale logout | Signs the device out of Tailscale and turns it off. |
Updating without dropping sessions
A new build replaces the running one in place: the process keeps its id and its PTYs, and the sessions never notice.
termio server handoffThat is also what happens when the app updates itself — the reason a Termio update does not cost you your running agents. See What survives for every case, including the ones a handoff cannot cover.
Looking at it
Three commands answer nearly every "is it me or is it Termio" question:
| Command | What it tells you |
|---|---|
termio server status | What this machine has: the binary, its version, and whether a daemon is answering on the socket. |
termio session ls --all | The sessions the host is holding. termio -H <box> session ls --all asks another machine. |
termio server logs | What the server recorded while nobody was attached. -f follows it; --path prints the file for a bug report. |
termiod is the server process itself, and it only runs. Every command on this
page belongs to the termio command-line tool, which the app and
the installer put on your PATH.
Stopping it
termio server stopIt declines while a command is still running or a viewer is attached, so a stray
stop cannot take an agent's work with it. Sessions end when their process ends,
or when you close them.
Remote hosts
The operational half of running agents on another box — adding a host, testing the route, why a password isn’t enough, what Set Up actually installs, and how to read the one line that says whether a machine is ready.
What survives
Sessions belong to the machine, not to the window — so closing, quitting, updating, and losing a connection all detach instead of killing. Here is exactly what survives each one, and what it costs when a process really does go away.