Remote commands
Every koshi share and koshi remote command, and the --remote flag that runs one invocation against another machine.
Command reference only. The guide is Remote sessions, and the step-by-step setup is the setup walkthrough.
--remote
--remote <SERVER> runs one invocation against the machine SERVER names,
either as host:port or as the name it was saved under.
koshi attach --remote work S-quiet-heron
koshi list-sessions --remote work
koshi new-pane --remote work --direction rightIt 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 refuses it, koshi share --remote
and koshi doctor --remote included:
--remote works with `attach`, `list-sessions`, and the action verbs, such as `koshi attach --remote <server>`A bare koshi --remote work names nothing to run and is refused the same way.
--certificate-fingerprint <FINGERPRINT> goes with --remote on each of those
verbs. It is needed for a server this machine has not saved: sha256:
followed by 64 lowercase hex characters, as koshi share grant prints it on
that machine. A saved server takes the fingerprint it holds and refuses any
other.
Tokens — run on the machine holding the sessions
| Command | Result |
|---|---|
koshi share grant <IDENTITY> [--session <SESSION>] [--expires <DURATION>] | Grant an identity a remote access token |
koshi share open | Open the port remote clients connect to, and print the commands that connect. Mints no token |
koshi share revoke <IDENTITY> [--session <SESSION>] | Revoke the tokens an identity holds |
koshi share list [--session <SESSION>] [--format table|json] | List the tokens granted on this machine |
--expires defaults to 24h and takes a count with one unit letter — 30s,
15m, 24h, 7d, at most 36500d — or the word never.
An absent --session reads one way on grant and another on revoke. A grant
with no --session reaches every session on this machine. A revoke with no
--session stops every grant that identity holds.
Details, output, and the refusals: Access tokens.
Saved servers — run on the machine you sit at
| Command | Result |
|---|---|
koshi remote new | Save a server, asking for its name, address, certificate fingerprint and secret |
koshi remote edit <SERVER> | Change one saved server's name, address, certificate fingerprint or secret |
koshi remote list [--format table|json] | List the servers this machine has saved |
koshi remote forget <SERVER> | Drop one saved server |
koshi remote set-secret <SERVER> | Replace the secret of one saved server |
koshi remote list prints the name, address, fingerprint, and last-used time
of each saved server, and never a secret.
Details: Saved servers.
Attaching
koshi attach --remote laptop.local:7654 --certificate-fingerprint sha256:3f6a0c2e9b8d4f17a5c3e1d0b9f8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0 --save-as work S-quiet-heron # first time
koshi attach --remote work S-quiet-heron # after thatThe first connection saves the address, the fingerprint, and the secret.
--save-as <NAME> saves them under a short name. A saved server that has
another name refuses --save-as.
Secrets
No koshi flag takes a secret — every argument after the program name is
readable by the other users of the machine. koshi reads the secret from
KOSHI_REMOTE_SECRET, and with that unset asks for it at the terminal without
printing what is typed.