# Attach and detach (/docs/v0.4/using/attach-and-detach)



A session runs in its own process, so a terminal can leave it and come back.
Every pane keeps running in between.

## Leave a session [#leave-a-session]

Three things do the same job:

| How                                   | Where         |
| ------------------------------------- | ------------- |
| <kbd>\<C-q></kbd> — the quit shortcut | Inside a pane |
| `koshi detach`                        | Inside a pane |
| Closing the terminal window           | Anywhere      |

The session keeps running with its panes untouched. Quit never ends a session
on its own.

From outside koshi, name what to detach:

```bash
koshi detach client-0e5a…        # one attached terminal
koshi detach session-3f2a…       # that session's client
koshi detach amber-fox           # the same, by session name
koshi detach --all amber-fox     # every terminal of that session
```

## Come back [#come-back]

```bash
koshi attach amber-fox                # by name
koshi attach session-3f2a…            # by id
koshi attach --remote work web        # a session on another machine
```

With no argument, koshi lists the sessions running for this user and the
sessions on every saved server that answered, numbers them, and reads your
answer. A session on a saved server carries `(remote: <server>)`:

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

A listing of exactly one session, on this machine, is attached without asking.
Every other listing asks, one session on a saved server included, whose prompt
reads `attach to which session? [1]`.

Attaching to a machine you have not saved yet is
[Remote sessions](/docs/v0.4/remote).

## Move a terminal between sessions [#move-a-terminal-between-sessions]

Run `koshi attach <session>` **inside** a koshi pane and the terminal you are
sitting at moves to that session. It leaves the one it was in, which counts as
leaving for `auto-close-session`.

## Start a session with nothing attached [#start-a-session-with-nothing-attached]

```bash
koshi --headless
[SESSION ID]: session-3f2a…
```

Nothing is drawn and the shell comes straight back. Use the printed id to
attach, or to drive the session with the ordinary commands.

## Several terminals, one session [#several-terminals-one-session]

More than one terminal can attach to a session at once. Each keeps its own:

* focused pane, current tab, and fullscreened pane;
* scroll position and text selection;
* theme, keybindings, and lock mode;
* mouse-selection mode.

They share the panes, the processes, and the scrollback. A pane's size is
shared too: a tab solves against the smallest terminal viewing it on each axis.

A terminal that misses an event resyncs instead of drawing a stale view.

Your keys are resolved on your own machine and reach the session as action
names, never as keys. See [Your keys, your view](/docs/v0.4/using/per-client).

## When an empty session ends [#when-an-empty-session-ends]

By default it does not. A session with no terminal attached keeps running until
you end it:

```bash
koshi kill-session <NAME_OR_ID>
```

Set `auto-close-session #true` in `koshi.kdl` to end a session once its last
terminal leaves:

```kdl title="koshi.kdl"
version 1
auto-close-session #true
```

koshi counts the terminals after the one that left is gone. If any are still
attached, the session keeps running; only an empty session ends.

Ending it asks every program in the session to stop, waits up to three seconds,
then kills whatever has not exited — long enough for a shell to write its
history and an editor its swap file. On Windows a program cannot be asked to
stop, so everything is killed at once. `koshi kill-session` skips the wait
either way.

<Callout>
  The session reads `auto-close-session` from the `koshi.kdl` it saw when it
  started. A terminal attaching later cannot change it from its own file. See
  [Whose setting is it](/docs/v0.4/configuration#whose-setting-is-it).
</Callout>

## Version compatibility [#version-compatibility]

The terminal and the session speak a protocol with a version. Each build speaks
a range of versions. When the two ranges do not overlap, the connection is
refused with an error naming what each side speaks — nothing is drawn and
nothing is changed.

It matters when you upgrade koshi while a session started by the old binary is
still running, and when the two machines of a remote connection run different
releases. Install the same koshi release on both sides.

Since 0.3.0, `koshi update` moves the running sessions for you: each session
replaces its own program while keeping its panes, the programs in them, and
their scrollback. A session that refuses the restart is named on standard error
and keeps the old build — end it and start it again. `koshi server-version`
shows which sessions moved. See [Update](/docs/v0.4/cli/update).

## Commands [#commands]

| Command                                    | Result                                              |
| ------------------------------------------ | --------------------------------------------------- |
| `koshi list-sessions`                      | List running sessions                               |
| `koshi attach [NAME_OR_ID]`                | Attach this terminal, or move it to another session |
| `koshi detach [CLIENT_OR_SESSION]`         | Detach one terminal                                 |
| `koshi detach --all [NAME_OR_ID]`          | Detach every terminal of one session                |
| `koshi kill-session [NAME_OR_ID]`          | End the session                                     |
| `koshi --headless`                         | Start a session with nothing attached               |
| `koshi attach --remote <SERVER> [SESSION]` | Attach to a session on another machine              |

Full flags and exit codes: [Session commands](/docs/v0.4/cli/sessions).