Remote sessions & sharing

A session lives on the machine that owns the panes. Reaching it is SSH's job, and SSH does it well.

A session on another machine

A session's socket lives on the machine running the panes, so "remote" means SSH — and it works with nothing extra installed or configured:

ssh -t server termdock new -s work        # create it there, and attach
ssh -t server termdock attach -t work     # come back from any other machine
ssh -t server termdock attach -t work -r  # attach as a read-only observer

The -t is doing real work: it asks SSH for a pty, which the client needs in order to draw.

Detach with Ctrl-B d and the panes keep running on the server exactly as they would locally. Close the laptop, open another one, attach again. This is the client/server split earning its keep: your terminal was never where the work lived.

Letting someone watch

-r is a real read-only attach. Every frame streams to that client, and every key and mouse event it sends is dropped by the server before it reaches the session. That is enforced on the daemon's side, not by asking the client to behave, so a modified or scripted client cannot type either. An observer's terminal size does not resize the shared session, so a smaller window on their end disturbs nobody.

Any number of normal and read-only clients can attach at once.

Without giving away your account

The socket is 0600 inside a 0700 directory, so attaching means being you on that machine. Handing a colleague your login so they can watch is not sharing; it is handing over the keys.

SSH solves this properly, with a forced command. Put their public key in your ~/.ssh/authorized_keys, restricted to exactly one thing:

restrict,pty,command="/usr/local/bin/termdock attach -t work -r" ssh-ed25519 AAAAC3Nz... alice

Now ssh server from Alice's machine drops her straight into watching that session, read-only, and nothing else. restrict denies port forwarding, agent forwarding, X11 and user rc files; pty puts back the one capability the client actually needs. Delete the line to end the sharing.

Why this is SSH's job

Authentication and encryption are the parts that must not be got wrong, and OpenSSH has had decades of scrutiny on exactly them. A bespoke listener in termdock with a hand-rolled token would be a downgrade wearing the word "feature".

It compares well, too. tmux users reach for wemux, which only works between accounts on one machine, or tmate, which relays your terminal through someone else's servers.

Driving a session from a script

Sessions can be operated without a client attached at all, which is what makes them usable from CI, cron, or a setup script:

termdock new-window -t work -n logs
termdock split-window -t work -v
termdock send-keys -t work:1 'tail -f /var/log/app.log' Enter
termdock select-window -t work:1
termdock select-pane -t work:1 -R
termdock list-windows -t work
termdock list-panes -t work:1

A target is SESSION[:WINDOW[.PANE]], where PANE is the number shown in the pane's title bar.