# Sessions and clients (/docs/v0.4/using) A **session** runs in a process of its own. It owns tabs, each tab owns a layout of panes, and each pane owns one process with its own terminal screen and scrollback. A **client** is one terminal attached to that session. The client draws what the session sends and forwards your keys. It owns nothing but its view. ``` session (its own process) ├── tab │ └── pane ── process, screen, scrollback └── client ── one attached terminal ``` Because the session is not your terminal, closing the terminal does not close the work. See [Attach and detach](/docs/v0.4/using/attach-and-detach). The client can sit on another machine. See [Remote sessions](/docs/v0.4/remote). ## Start one [#start-one] ```bash koshi # one tab, one shell pane, this terminal attached koshi --profile dev # tabs and panes from profile/dev.kdl koshi --headless # a session with nothing attached; prints its id # the same, reachable by the other users of this machine koshi --headless --allow-other-users ``` `--headless` prints `[SESSION ID]: session-` and returns to the shell. Nothing is drawn. Attach to it later. ## What the session owns, and what your terminal owns [#what-the-session-owns-and-what-your-terminal-owns] | The session owns | Your terminal owns | | ------------------------------------------ | ------------------------------------------------- | | Tabs, panes, and their processes | Which tab it is looking at | | Scrollback and its size limits | Which pane is focused, and which is fullscreened | | `TERM`, `COLORTERM`, and the default shell | Its scroll position and text selection | | `auto-close-session` | Its theme, keybindings, and image-support setting | | `allow-other-users` | Its lock mode and mouse-selection mode | Two terminals on one session can therefore sit in different tabs, wear different colours, and use different keys. They cannot disagree about what is in a pane. See [Your keys, your view](/docs/v0.4/using/per-client). Each terminal reads its own `koshi.kdl`, `themes/.kdl`, and `keybinding.kdl` when it attaches. The session took its own copy of the session-owned settings when it started, so a terminal attaching later cannot change them. `allow-other-users` is the exception: the session re-reads it for every connection and every request, so turning it off shuts other users out without a restart. See [Whose setting is it](/docs/v0.4/configuration#whose-setting-is-it). ## Names and ids [#names-and-ids] Every session, tab, pane, and client has a printed id. Sessions and tabs also have a generated name. ```text session-3f2a… tab-91c4… pane-77bd… client-0e5a… ``` Anywhere a command takes `NAME_OR_ID`, either works. A value that reads as an id is always used as an id — it never falls back to a name lookup. A name that several targets share is refused, and the error lists every matching id. Pane and client flags take ids only. ## See what is running [#see-what-is-running] Every list and inspect command takes `--format table` (default) or `--format json`. ```bash koshi list-sessions koshi list-tabs koshi list-panes koshi list-clients ``` `koshi list-sessions` names each session's machine in its `server` column: `local` for a session on this machine, else the saved server it runs on. ```bash koshi inspect session koshi inspect tab koshi inspect pane koshi inspect client ``` ## Targeting [#targeting] Inside koshi, a command with no target uses the current session, tab, pane, or client. Outside koshi, give a target unless exactly one session is running — in that case koshi uses it. Zero or several running sessions fail rather than guess. Create commands print the ids they made: `new-pane` and `run` print one pane id, `new-tab` prints its tab id and root pane id, `--headless` prints its session id. Those ids are what you feed back into `--pane`, `--tab`, and `--session`. ## Missed events [#missed-events] A client that misses an event resyncs from the session instead of drawing a stale view. You do not have to do anything; the view catches up. ## Terminal images [#terminal-images] Programs in a pane can draw images using Kitty, iTerm2, or Sixel. Each terminal selects its own supported protocol, so two terminals attached to one session may use different image output. Images keep their placement through scrolling, scrollback, resizing, and screen switches. Set `image-support #false` to keep the text and the image placeholders without sending native image output. See [Terminal images](/docs/v0.4/using/images). ## End one [#end-one] ```bash koshi kill-session # the only running session koshi kill-session # a named one ``` `kill-session` ends the session whatever else is attached to it, and skips the wait for programs to stop. Closing the last pane in a tab closes the tab. Closing the last tab ends the session. Leaving a session does not — that is [detaching](/docs/v0.4/using/attach-and-detach).