# Koshi 0.6.0 — Remote Terminal Sessions over TLS (/docs/v0.6/remote)



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 [#the-two-sides]

Read this page once, then follow the
[setup walkthrough](/docs/v0.6/remote/setup).

| 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 [#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 [#what-a-token-gives-away]

<Callout type="warn">
  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.
</Callout>

`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](/docs/v0.6/remote/tokens).

## What the server stores [#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 [#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 [#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`:

```text
--remote works with `attach`, `list-sessions`, and the action verbs, such as `koshi attach --remote <server>`
```

## Remote access is not same-machine sharing [#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](/docs/v0.6/using/other-users).

## Next [#next]

<Cards>
  <Card title="Setup walkthrough" href="/docs/v0.6/remote/setup" description="Both machines, step by step, from nothing to an attached session." />

  <Card title="Access tokens" href="/docs/v0.6/remote/tokens" description="grant, revoke, list — and what each scope reaches." />

  <Card title="Saved servers" href="/docs/v0.6/remote/servers" description="Names, addresses, certificate fingerprints, and rotating a secret." />

  <Card title="Troubleshooting" href="/docs/v0.6/remote/troubleshooting" description="Every refusal, what it means, and what fixes it." />
</Cards>