# koshi.kdl (/docs/v0.4/configuration/koshi-kdl)



`koshi.kdl` holds the app settings. It sits directly in the
[config directory](/docs/v0.4/configuration#where-the-files-go). `version` is
required; everything else is optional. `theme`, `image-support`,
`allow-beta-features`, `allow-other-users`, `remote-listen`, `remote-reconnect`,
`shared-sessions-dir`, and `auto-close-session` are top-level; the rest are
grouped into blocks.

<Callout>
  A bad field is skipped at startup, keeps its default, and is logged — the rest
  of the file still applies. The exception is `update`: a bad value there drops
  the whole file for that launch. `koshi config check` rejects bad fields
  outright.
</Callout>

Each section says who reads it: the **session**, which took its copy when it
started, or your **terminal**, which reads its own file every time it attaches.
See [Whose setting is it](/docs/v0.4/configuration#whose-setting-is-it).

## theme [#theme]

**Read by your terminal.** Two terminals showing one session can wear different
colours.

`theme "midnight"` loads `themes/midnight.kdl`. A missing, invalid, or omitted
theme — or `"default"` — uses the built-in colours. See
[Themes](/docs/v0.4/configuration/themes).

| Key     | Value                                                   | Default     | Since   |
| ------- | ------------------------------------------------------- | ----------- | ------- |
| `theme` | string — the `themes/<name>.kdl` to use, without `.kdl` | `"default"` | ≥ 0.1.0 |

## pane [#pane]

**Read by the session.** Panes are the session's, so every terminal sees the
same sizes.

| Key        | Value                                                                                                                 | Default | Since   |
| ---------- | --------------------------------------------------------------------------------------------------------------------- | ------- | ------- |
| `min-cols` | integer — smallest width a pane may shrink to                                                                         | `2`     | ≥ 0.1.0 |
| `min-rows` | integer — smallest height a pane may shrink to                                                                        | `1`     | ≥ 0.1.0 |
| `gap`      | integer — blank cells between two panes that meet along a horizontal or vertical split; stacked panes stay contiguous | `0`     | ≥ 0.4.0 |

## scrollback [#scrollback]

**Read by the session**, including `scroll-on-input`, so every attached
terminal gets the same answer.

| Key               | Value                                                                        | Default             | Since   |
| ----------------- | ---------------------------------------------------------------------------- | ------------------- | ------- |
| `max-lines`       | integer — lines of history kept per pane (negative means `0`: no scrollback) | `10000`             | ≥ 0.1.0 |
| `max-bytes`       | integer — byte ceiling on that history (negative means `0`)                  | `33554432` (32 MiB) | ≥ 0.1.0 |
| `scroll-on-input` | boolean — typing while scrolled up snaps the view back to the newest line    | `#true`             | ≥ 0.1.0 |

`scroll-on-input #false` keeps the view parked while the input still goes
through. Only the primary screen follows; the alternate screen is left to the
full-screen program on it.

## layout [#layout]

**Read by your terminal.** Two terminals viewing one session can differ.

| Key                  | Value                                                                                              | Default   | Since   |
| -------------------- | -------------------------------------------------------------------------------------------------- | --------- | ------- |
| `new-pane-direction` | `"left"` \| `"right"` \| `"up"` \| `"down"` — where a new pane opens when the command does not say | `"right"` | ≥ 0.1.0 |

The `new-pane-<side>` keybindings and an explicit `--direction` name their own
side and ignore this.

## mouse [#mouse]

**Read by your terminal** — the mouse is its own.

| Key             | Value                                     | Default               | Since   |
| --------------- | ----------------------------------------- | --------------------- | ------- |
| `border-resize` | boolean — drag a pane border to resize it | `#true`               | ≥ 0.1.0 |
| `scroll-lines`  | integer — lines per wheel notch           | `3`                   | ≥ 0.1.0 |
| `wheel`         | `"scroll-scrollback"` \| `"ignore"`       | `"scroll-scrollback"` | ≥ 0.1.0 |

## copy [#copy]

**Read by your terminal** — the copy is made where the selection was dragged.

| Key                        | Value                                            | Default | Since   |
| -------------------------- | ------------------------------------------------ | ------- | ------- |
| `trim-trailing-whitespace` | boolean — drop trailing blanks from copied lines | `#true` | ≥ 0.1.0 |

## terminal [#terminal]

**Read by the session** — it starts the programs in the panes, so it decides
what they are told.

| Key             | Value                                             | Default                                | Since   |
| --------------- | ------------------------------------------------- | -------------------------------------- | ------- |
| `term`          | string — the `TERM` value child programs see      | `"xterm-256color"`                     | ≥ 0.1.0 |
| `colorterm`     | string — the `COLORTERM` value child programs see | `"truecolor"`                          | ≥ 0.1.0 |
| `default-shell` | string — the shell to launch                      | your `$SHELL` (`%COMSPEC%` on Windows) | ≥ 0.1.0 |

## logging [#logging]

**Read by every koshi process** for its own log file. koshi writes
`logs/koshi-log-<uuid>.log` below the state directory, named by the session's
bare UUID. Disabled logging
creates no file at all.

| Key       | Value                                                          | Default     | Since   |
| --------- | -------------------------------------------------------------- | ----------- | ------- |
| `enabled` | boolean — write a log file at all                              | `#false`    | ≥ 0.1.0 |
| `level`   | `"info"` \| `"warning"` \| `"error"` — lowest severity written | `"warning"` | ≥ 0.1.0 |
| `format`  | `"pretty"` \| `"json"`                                         | `"pretty"`  | ≥ 0.1.0 |

`info` includes normal lifecycle events, `warning` recoverable problems, and
`error` failures that stop koshi. Each level includes the more severe ones.
Logs store ids and byte counts — never typed or copied text. Crash reports are
separate and always on; see
[Logging and crash reports](/docs/v0.4/using/logging).

## update [#update]

**Read by every installed koshi** for itself.

<Callout type="warn">
  A bad value in this block drops the whole `koshi.kdl` for that launch, not just
  the field.
</Callout>

| Key                   | Value                                               | Default  | Since   |
| --------------------- | --------------------------------------------------- | -------- | ------- |
| `auto-check`          | boolean — check GitHub for a newer koshi at startup | `#true`  | ≥ 0.1.0 |
| `check-interval-days` | integer — days between checks                       | `14`     | ≥ 0.1.0 |
| `allow-prerelease`    | boolean — offer pre-release builds too              | `#false` | ≥ 0.1.0 |

## allow-beta-features [#allow-beta-features]

**Read by every koshi process** when it starts, so the interactive session and
the `koshi` commands you type all get the same answer.

Some features are finished code that has not been used enough to be turned on
for everyone. They are off unless you say otherwise. Turning this on runs all
of them; there is no per-feature switch.

A beta feature you have not turned on refuses and says so, naming itself and
the line to add:

```text
koshi: `koshi <command>` is a beta feature and did nothing; add a top-level
`allow-beta-features #true` line to koshi.kdl to run it
```

Nothing crashes and nothing is lost; the command exits non-zero having done
nothing.

<Callout>
  **0.4.0 marks no feature beta.** Every command in this release runs whether the
  setting is on or off. `koshi`, `koshi attach`, and `koshi --headless` were beta
  before 0.2.0 and are now on for everyone. The setting stays for the features
  marked beta next.
</Callout>

| Key                   | Value                                    | Default  | Since   |
| --------------------- | ---------------------------------------- | -------- | ------- |
| `allow-beta-features` | boolean — run features still marked beta | `#false` | ≥ 0.2.0 |

## image-support [#image-support]

**Read by your terminal.** Each terminal probes its own capabilities and chooses
Kitty, iTerm2, or Sixel output when the setting is on. A terminal with none of
those protocols keeps the text and the `terminal image unavailable` placeholder.

| Key             | Value                                              | Default | Since   |
| --------------- | -------------------------------------------------- | ------- | ------- |
| `image-support` | boolean — send native image output to the terminal | `#true` | ≥ 0.4.0 |

## auto-close-session [#auto-close-session]

**Read by the session**, from the `koshi.kdl` it saw when it started. A
terminal attaching later cannot change it.

A terminal leaving a session normally leaves the session running with nothing
attached, so `koshi attach` can rejoin it later. Turning this on ends the
session once the last terminal leaves.

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.

Every way of leaving counts: the quit keybinding (<kbd>\<C-q></kbd> by
default), `koshi detach`, closing the terminal, and moving the terminal to
another session with `koshi attach <session>` from inside a pane.

| Key                  | Value                                                   | Default  | Since   |
| -------------------- | ------------------------------------------------------- | -------- | ------- |
| `auto-close-session` | boolean — end the session when its last terminal leaves | `#false` | ≥ 0.2.0 |

## remote-listen [#remote-listen]

**Read by every koshi process** on the machine holding the sessions.

`remote-listen "0.0.0.0:7654"` names the address the remote listener binds, and
does nothing else.

<Callout type="warn">
  Writing this line opens no port and makes this machine reachable by nobody. The
  port opens the first time you run `koshi share grant` and answer yes to the
  offer it makes, and on every start after that.
</Callout>

`allow-other-users` is a separate switch, about other users logged in to this
same machine. Neither key turns the other on.

| Key             | Value                                              | Default               | Since   |
| --------------- | -------------------------------------------------- | --------------------- | ------- |
| `remote-listen` | string — `host:port` the remote TLS listener binds | unset — nothing binds | ≥ 0.3.0 |

See [Remote sessions](/docs/v0.4/remote).

## remote-reconnect [#remote-reconnect]

**Read by your terminal.** It applies only to a terminal viewing a session on
another machine, reached with `koshi attach --remote`.

On, a link that drops dials that machine again — after 1 second, then 2, 4, 8,
and 8 before every dial after that — for up to 120 seconds. While it waits, the
tab strip reads a tag shaped like `RECONNECTING (attempt 4, retry in 8s)`.
Joining again puts back the tab you were on, the focused pane of each tab, the
fullscreened pane of each tab, and the scroll offset of each pane. Keys typed
while the link is down are dropped; a resize is kept.

A refusal no dial can change stops the dialing at once. Off, a dropped link
ends the terminal, printing how to attach again by hand. A link to a session on
this machine ends the terminal either way.

| Key                | Value                                                                 | Default | Since   |
| ------------------ | --------------------------------------------------------------------- | ------- | ------- |
| `remote-reconnect` | boolean — dial a session on another machine again when the link drops | `#true` | ≥ 0.3.0 |

See [Reconnecting](/docs/v0.4/remote/servers#reconnecting).

## allow-other-users [#allow-other-users]

**Read by the session for every connection and every request**, and by every
`koshi` command as it runs — so turning it off shuts those users out without a
restart.

Your sessions are yours alone unless you say otherwise. Turning this on lets
every other user logged in to the same machine list your sessions, attach to
them, and kill them.

Both files have to say so. Your `koshi.kdl` opens your sessions to other users;
their own `koshi.kdl` makes their `koshi` look for sessions that are not
theirs.

<Callout type="warn">
  The programs inside a session keep running as the user who started it, whoever
  attaches. Attaching never hands anyone your account; it hands them a view of,
  and typing into, panes that still run as you.
</Callout>

Turning it on reaches the sessions you start after the change. A running
session keeps the socket it already has until it restarts, and `koshi update`
restarts every session it finds. A session started with `koshi --headless --allow-other-users` keeps other users for its whole life and never reads this
key.

| Key                 | Value                                                         | Default  | Since   |
| ------------------- | ------------------------------------------------------------- | -------- | ------- |
| `allow-other-users` | boolean — let other users of this machine reach your sessions | `#false` | ≥ 0.3.0 |

See [Sharing with other users](/docs/v0.4/using/other-users).

## shared-sessions-dir [#shared-sessions-dir]

**Read by every koshi process** for itself.

Where the session sockets other users reach are kept. Set it to a directory
every user who shares the machine can enter, such as `/var/run/koshi`. Leave it
out and koshi uses the machine-wide directory for the platform: `/tmp/koshi` on
Linux and macOS, `%ProgramData%\koshi` on Windows.

Every user who shares the machine has to name the same directory. A user whose
file names a different one looks in that one and finds nobody.

This only says where the sockets go. Nobody else reaches them until
`allow-other-users` is on.

| Key                   | Value                                                 | Default                                        | Since   |
| --------------------- | ----------------------------------------------------- | ---------------------------------------------- | ------- |
| `shared-sessions-dir` | string — directory the shared session sockets live in | `/tmp/koshi`, `%ProgramData%\koshi` on Windows | ≥ 0.3.0 |

## Every setting at its default [#every-setting-at-its-default]

`default-shell`, `remote-listen`, and `shared-sessions-dir` are commented out —
they have no fixed default. `default-shell` comes from `$SHELL` or `%COMSPEC%`,
`remote-listen` is unset, and the shared sessions directory is `/tmp/koshi` on
Linux and macOS, `%ProgramData%\koshi` on Windows.

```kdl title="koshi.kdl"
// koshi.kdl — the complete default configuration.
version 1

theme "default"
image-support #true
allow-beta-features #false
allow-other-users #false
// remote-listen "0.0.0.0:7654"  // sets the address; opens no port on its own
// shared-sessions-dir "/var/run/koshi"  // optional override
auto-close-session #false
remote-reconnect #true

pane {
    min-cols 2
    min-rows 1
    gap 0
}

scrollback {
    max-lines 10000
    max-bytes 33554432       // 32 MiB
    scroll-on-input #true
}

layout {
    new-pane-direction "right"
}

mouse {
    border-resize #true
    scroll-lines 3
    wheel "scroll-scrollback"
}

copy {
    trim-trailing-whitespace #true
}

terminal {
    term "xterm-256color"
    colorterm "truecolor"
    // default-shell "/bin/zsh"  // optional override
}

logging {
    enabled #false
    level "warning"
    format "pretty"
}

update {
    auto-check #true
    check-interval-days 14
    allow-prerelease #false
}
```