# How remote access works (/docs/v0.4/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.4/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          |
| **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 [#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 [#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
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.4/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 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 [#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.4/using/other-users).

## Next [#next]

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

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

  <Card title="Saved servers" href="/docs/v0.4/remote/servers" description="Names, addresses, pinned certificates, and rotating a secret." />

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