Koshi / remote terminal sessions
Remote Terminal Sessions with Koshi
Koshi lets a terminal attach to a persistent session on another machine over TLS. The server owns the session and its programs. The client keeps its own view, input settings, and connection state.
How remote attachment works
Enable a remote listener on the machine that holds the sessions, grant an access token, then save the server from the client machine.
A remote client can attach to sessions, list sessions, and perform the supported session actions without moving the session process to the client machine.
koshi share grant alice
koshi attach --remote work quiet-heronRead the complete remote guide →Follow the setup walkthrough →
TLS and certificate pinning
The client records the server certificate fingerprint on the first connection. A later connection with a different certificate is refused and reports both fingerprints.
This gives the client a stable identity check for the server it has saved.
Scoped access tokens
A server administrator can grant access to every session or to one named session. Tokens can expire and can be revoked before expiry.
The server stores token hashes. The client stores the remote address, secret, certificate fingerprint, and saved server name.
Reconnect and restore the client view
When the connection drops, Koshi can reconnect within the configured period and restore the client view, including its tabs, focus, and scroll position.
The session continues running while the client is disconnected.
Read about reconnect behavior →Read about attach and detach →
Install the client
Install Koshi on Linux, macOS, or Windows, then use the remote commands from the client machine. The same Koshi command line handles local and remote sessions.
Common questions
Can Koshi attach to a terminal session on another machine?
Yes. Koshi attaches to a persistent session on another machine over TLS with a pinned certificate and a scoped access token.
How does Koshi protect remote access?
Koshi uses TLS, certificate pinning, revocable access tokens, and a server that listens only after remote access is enabled.
Does the session stop when the remote client disconnects?
No. The session continues running on the server and the client can reconnect to it.