How remote access works
koshi attaches a terminal to a session on another machine over TLS, with a pinned certificate and an access token — what each side runs, and what a token gives away.
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 |
| Client — the machine you sit at | koshi remote new, then koshi attach --remote <server> | Saves the server, pins its certificate, attaches |
The three koshi share verbs 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 pinned certificate. The client records the sha256 of the certificate the server presented on the first connection. Every later connection must meet the same certificate, or it is refused with both fingerprints named.
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 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 pinned 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 pretty or JSON logs, 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, pin the certificate, and attach to a session on another machine.