# Koshi 0.3.0 — Introduction (/docs/v0.3)



koshi is a terminal multiplexer. It runs several shells and programs inside one
terminal window and handles pane layouts, tabs, terminal emulation, scrollback,
keyboard shortcuts, mouse input, and process cleanup.

Each pane holds its own process, its own terminal screen, and its own
scrollback. Tabs hold layouts of panes. A session holds tabs.

## The session outlives the terminal [#the-session-outlives-the-terminal]

A session runs in its own process. Your terminal is a **client** attached to
it. Close the terminal, lose the SSH link, or press the quit shortcut, and the
session keeps running with every pane alive.

```bash
koshi                  # start a session and attach this terminal to it
koshi detach           # leave it running
koshi attach           # come back to it
```

Several terminals can watch one session at once, each with its own focused
pane, its own tab, and its own colours. One of them can sit on another machine.

## Your keys and your view are yours [#your-keys-and-your-view-are-yours]

The terminal you sit at reads your own `keybinding.kdl` and decides what each
key means. It sends the session the **action name**, never the key — so your
own shortcuts follow you to a session on any machine, and you never edit a
keybinding file on the other one.

The focused pane, the active tab, the fullscreened pane, the scroll position,
the selection, and the lock mode belong to your terminal too. Two people on one
session sit in different tabs and type into different panes without moving each
other's screen.

See [Your keys, your view](/docs/v0.3/using/per-client).

## Reach it from another machine [#reach-it-from-another-machine]

```bash
koshi share grant alice                  # on the machine holding the sessions
koshi attach --remote work S-quiet-heron   # from anywhere else
```

TLS, a certificate pinned on the first connection, and an access token you
grant and revoke. Nothing is reachable until you say so. See
[Remote sessions](/docs/v0.3/remote).

## What is built in [#what-is-built-in]

Panes, tabs, layouts, keybindings, themes, and saved layouts ship with the
program. There is no plugin to install before koshi becomes useful.

* **Sessions** — run in their own process, survive the terminal, and take
  several attached clients at once, each with its own keys and its own view.
* **Panes** — split left, right, up, or down; stack several in one slot;
  fullscreen one and restore the layout afterwards.
* **Tabs** — create, close, move, and switch.
* **Keyboard** — multi-key shortcuts, a leader you choose, on-screen hints, and
  conflict checks.
* **Mouse** — focus panes, drag borders, scroll, select text, copy through
  OSC 52 even over SSH.
* **Config** — four optional KDL files for settings, colours, keys, and saved
  layouts, read per terminal.
* **Control from a shell** — open panes, move tabs, send input, and inspect a
  running session from outside it, on this machine or another one.
* **Remote sessions** — attach over TLS with a pinned certificate and an access
  token, and reconnect on your own when the link drops.
* **Same-machine sharing** — let the other users of this machine list, attach
  to, and kill your sessions.
* **Update in place** — `koshi update` restarts each running session into the
  new build, keeping its panes, their programs, and their scrollback.
* **Installation check** — `koshi doctor` rates config, shell, terminal,
  directories, router, and remote access.

## Requirements [#requirements]

|                      |                                    |
| -------------------- | ---------------------------------- |
| Platforms            | Linux, macOS, Windows              |
| Architectures        | x86-64, ARM64                      |
| Terminal             | true colour and 256-colour support |
| Building from source | Rust 1.96                          |

## Next [#next]

<Cards>
  <Card title="koshi at a glance" href="/docs/v0.3/overview" description="The vocabulary, the default keys, and the three properties to know." />

  <Card title="Installation" href="/docs/v0.3/installation" description="Homebrew, Scoop, the release script, or from source." />

  <Card title="Quick start" href="/docs/v0.3/quick-start" description="One session, one split, one tab, and back out again." />

  <Card title="Your keys, your view" href="/docs/v0.3/using/per-client" description="What each attached terminal owns, and what the session owns." />

  <Card title="Remote sessions" href="/docs/v0.3/remote" description="Attach to a session on another machine, step by step." />

  <Card title="CLI" href="/docs/v0.3/cli" description="Every command and what it prints." />
</Cards>