This page goes from a fresh install to an attached remote session. Run the server steps on the machine holding the sessions. Run the client steps on the machine you sit at.

Throughout, the server listens on laptop.local:7654 and the client saves it as work. Substitute your own.

Install the same koshi release on both machines. Two builds that share no protocol version refuse each other and name both version ranges.

Server · 1. Have a session to attach to

Remote access reaches sessions that already run. Start one if there is none:

koshi --headless

[SESSION ID]: session-3f2a…

koshi list-sessions

Server · 2. Name the listen address

Add one top-level line to the server's koshi.kdl:

koshi.kdl

version 1

remote-listen "0.0.0.0:7654"

0.0.0.0 binds every interface. Bind one interface instead — for example remote-listen "10.0.0.4:7654" — when only one network should reach it.

This line opens no port. It only says where the listener would bind. The port opens at the next step, and only if you answer yes.

koshi config path prints the directory the file goes in.

Server · 3. Grant a token and open the port

koshi share grant alice

With an address set and remote access still off, the command offers to switch it on:

remote access is off.
turn it on and open 0.0.0.0:7654? [y/N]

Type y. The port opens now, and opens again on every start after that. Any other answer leaves it shut and still prints the token.

The token prints once, followed by the command that connects with it:

anyone holding this token can run anything you can.
<the secret, printed here and nowhere else>
connect from another machine:
  koshi attach --remote 0.0.0.0:7654 --save-as alice [SESSION]
set KOSHI_REMOTE_SECRET to the secret above, or paste it when asked.

The address in that printed command is whatever remote-listen holds. 0.0.0.0 means "every interface on this machine" and reaches nothing from outside it, so dial the server's own reachable name or address instead — laptop.local:7654 below.

Copy the token from that one printing. The server stores only its sha256 and can never print it again. Lost it? Run koshi share grant alice again — the new grant replaces the old one.

Narrowing or extending the grant

--session and --expires belong on the grant you make, not on a second one after it:

koshi share grant alice --session quiet-lake --expires 7d

Do not run these as extra commands after the grant above. An identity holds at most one grant per scope, so a second koshi share grant alice mints a fresh host-wide token and stops the one you just copied. Decide the scope and the expiry first, then grant once and copy that token.

Full rules: Access tokens.

Run koshi share from a terminal outside koshi. Inside a koshi pane the verb is refused while anyone is attached to that session from another machine, because the session paints that pane onto their screen too.

Server · 4. Check what the machine now offers

koshi doctor

Read the two remote rows:

remote access       ok  koshi.kdl names the remote listen address 0.0.0.0:7654, and this machine holds 1 standing grant
remote connections  ok  this machine holds 0 open connections from another machine

Also open port 7654 in the machine's firewall, and in any cloud security group in front of it. koshi does not touch either.

Client · 5. Get the secret into the environment

The secret never goes on a command line. Either export it:

export KOSHI_REMOTE_SECRET='<the secret the grant printed>'

Or leave it unset and let koshi ask for it at the terminal — it prints nothing while you type. Every step below works either way.

Client · 6. Save the server

koshi remote new

It asks three questions in turn, then dials the server once to check the secret:

$ koshi remote new
every answer is needed. Ctrl-C stops without saving.
name: work
address: laptop.local:7654
secret:
checking laptop.local:7654 …
saved work at laptop.local:7654.

A check that passes pins the certificate the server presented. Ctrl-C at any question saves nothing.

A check that does not pass is named, and the last question is whether to save what was typed anyway:

checking laptop.local:7654 …
koshi: IPC unavailable: laptop.local:7654 refused the connection: nothing is listening on that port. if remote access is not enabled on that machine, run `koshi share grant` there and answer yes to the offer to open the port
save it anyway? [y/N]: y
saved work at laptop.local:7654; its certificate is pinned on the first connection.

koshi remote new is optional. koshi attach --remote laptop.local:7654 --save-as work web saves the server and attaches in one go — see step 8.

Client · 7. List what is running over there

koshi list-sessions --remote work

id             name         server
session-91c4…  quiet-heron  work

A bare koshi list-sessions sweeps every saved server as well as this machine. Local rows read local in the server column. The sweep waits two seconds in total, not two seconds per server, so one unreachable machine cannot slow it down.

Client · 8. Attach

koshi attach --remote work quiet-heron

Or, without saving the server first:

koshi attach --remote laptop.local:7654 --save-as work quiet-heron

Your terminal is now on that session. Your own keybinding.kdl, themes/, and view settings still apply — they are read on the machine you sit at and never on the server. See Your keys, your view.

A bare koshi attach lists this machine's sessions and every reachable saved server's sessions together, and asks:

koshi attach
1) amber-fox session-3f2a…
2) quiet-heron session-91c4… (remote: work)
attach to which session? [1-2]

Client · 9. Drive it from another shell

The action verbs take --remote too:

koshi new-pane --remote work --direction right
koshi input --remote work --pane pane-77bd… "cargo test"
koshi focus-tab --remote work --index 2

--remote takes attach, list-sessions, and the action verbs only. It never creates a session, and every other verb refuses it — the list-* verbs other than list-sessions, inspect, debug, detach, kill-session, share, remote and doctor included.

Leaving and coming back

koshi detach          # inside a pane — the remote session keeps running
koshi attach --remote work quiet-heron

A dropped link dials again on its own for up to two minutes, unless you turn remote-reconnect off. See Saved servers.

Turning it off

On the server, stop the tokens:

koshi share revoke alice

That ends the connections alice's tokens opened, at once, attached or not.

Remove the remote-listen line from the server's koshi.kdl to stop the listener binding on the next start.

On the client, drop the saved server, its secret, and its pinned fingerprint:

koshi remote forget work

The whole flow

#	Machine	Command
1	server	`koshi --headless`
2	server	`remote-listen "0.0.0.0:7654"` in `koshi.kdl`
3	server	`koshi share grant alice` → answer `y` → copy the token
4	server	`koshi doctor`, then open the port in the firewall
5	client	`export KOSHI_REMOTE_SECRET='<the secret>'`
6	client	`koshi remote new`
7	client	`koshi list-sessions --remote work`
8	client	`koshi attach --remote work quiet-heron`

Something refused you? Troubleshooting names every refusal and what fixes it.

Setup walkthrough