Remote Terminal Sessions over TLS
Attach to a persistent Koshi session on another machine over TLS with a checked certificate fingerprint, scoped access tokens, and reconnect support.
A session runs on one machine. koshi attach --remote <server> puts your
terminal on it from another machine, over TLS.
Nothing is reachable until you say so. A fresh install listens on no port, grants no token, and dials no server.
The two sides
Read this page once, then follow the setup walkthrough.
| Side | Runs | Does |
|---|---|---|
| Server — the machine holding the sessions | remote-listen in koshi.kdl, then koshi share grant | Opens the port, hands out access tokens, prints the certificate fingerprint |
| Client — the machine you sit at | koshi remote new or koshi attach --remote <server> --certificate-fingerprint … | Saves the server and its fingerprint, attaches |
The four koshi share verbs — grant, open, revoke, and list — run on
the server. Everything else —
koshi remote, koshi attach --remote, koshi list-sessions --remote — runs
on the client.
The three pieces
An address. remote-listen "0.0.0.0:7654" in the server's koshi.kdl
names where the listener binds. Writing that line opens no port on its own.
A token. koshi share grant alice on the server prints one token, once.
The client stores it as that server's secret. Without a token, a connection is
refused.
A certificate fingerprint. The server prints the sha256 of its certificate
in each connect command. The first connection gives it with
--certificate-fingerprint, and the client saves it. Every connection must
meet that certificate, or it is refused before the secret is sent, with both
fingerprints named.
Both machines speak TLS 1.3 only.
What a token gives away
A token is full access to every session it reaches. Typing into a shell of one of those sessions acts as the user who runs the session — the same as sitting at that machine and typing there. Hand a token to somebody only when you would hand them that account.
koshi share grant alice reaches every session on the server, including the
sessions started after the grant. koshi share grant alice --session S-quiet-lake reaches that one session.
A grant stops working after 24h unless --expires says otherwise, and
koshi share revoke stops it sooner. See Access tokens.
What the server stores
The token store on the server holds the sha256 of each token it granted, never the token itself. A token nobody kept cannot be read back out — grant again to get a fresh one.
The client's store holds the address, the secret, the certificate fingerprint, and
the saved name. It lives on the client and is readable only by its owner.
koshi remote list never prints a secret.
Secrets never reach a command line
Every argument after the program name is readable by the other users of the
machine, so no koshi flag takes a secret. koshi reads the secret from
KOSHI_REMOTE_SECRET, and with that unset asks for it at the terminal without
printing what is typed.
What --remote accepts
--remote takes attach, list-sessions, and the action verbs — the verbs
that open, close, resize, focus, and type into panes and tabs, and the lock
verbs. It never creates a session. Every other verb is refused, including
koshi share --remote and koshi doctor --remote:
--remote works with `attach`, `list-sessions`, and the action verbs, such as `koshi attach --remote <server>`Remote access is not same-machine sharing
remote-listen is about another machine. allow-other-users is about the
other users logged in to this machine. Neither key turns the other on. See
Sharing with other users.
Next
Logging and crash reports
Enable per-session and router logs in pretty or JSON form, cap their size, and find the crash file koshi writes after a panic — neither records terminal input or copied text.
Setup walkthrough
Step by step, on both machines — open the port, grant a token, save the server with its certificate fingerprint, and attach to a session on another machine.