# Koshi 0.6.0 — Logging and crash reports (/docs/v0.6/using/logging)



Logging is off by default. When enabled, koshi writes these files in `logs/`
below its platform state directory:

```text
logs/koshi-log-<uuid>.log     # one per session
logs/koshi-log-router.log     # the router
```

A session's name carries its **bare** UUID, without the `session-` prefix the
id prints with. It holds the lines of the session server and of each client
attached to the session. The router's file holds the router's lines, such as a
failed restart into a new koshi. Disabled logging creates no file.

Every koshi process reads this block for its own log file. The router reads it
when it starts and each time it restarts.

A line that takes a file over `max-log-file-size-in-mb` moves it to
`<name>.1`, replacing the `.1` file before it, and the next line starts a new
file. Each start of a session server deletes the files of old sessions, logging
on or off; it keeps its own, the router's, and those of the 20 sessions written
last.

A failure that ends the router or a session server is written to its log file
at `error` level.

## Configure [#configure]

```kdl title="koshi.kdl"
version 2

logging {
    enabled #true
    level "warning"
    format "pretty"
    max-log-file-size-in-mb 4
}
```

| Setting                   | Values                             | Default     |
| ------------------------- | ---------------------------------- | ----------- |
| `enabled`                 | `#true` / `#false`                 | `#false`    |
| `level`                   | `"info"` / `"warning"` / `"error"` | `"warning"` |
| `format`                  | `"pretty"` / `"json"`              | `"pretty"`  |
| `max-log-file-size-in-mb` | `1` to `1024`                      | `4`         |

`info` includes normal lifecycle events. `warning` adds recoverable problems.
`error` keeps only failures that stop koshi. Each level includes more severe
events.

`pretty` is human-readable. `json` writes one JSON object per line for tools to
parse.

## Crash reports [#crash-reports]

A crash report is separate from the log file. No setting turns it on or off.

If koshi panics while you have a session open, it restores your terminal first
and then writes a report to the data directory:

```text
crash-<seconds-since-1970>.txt
```

| Platform | Data directory                        |
| -------- | ------------------------------------- |
| Linux    | `~/.local/share/koshi`                |
| macOS    | `~/Library/Application Support/koshi` |
| Windows  | `%APPDATA%\koshi\data`                |

A panic at 2026-08-08 12:00:00 UTC writes `crash-1786190400.txt`. Attach that
file to a bug report.

The file holds the koshi version, the operating system and processor, the time,
the panic message, the source line that panicked, and the stack. koshi reads
only those from the panic.

## Privacy [#privacy]

Logs include ids, lifecycle events, errors, and byte counts. Crash reports
include the panic and the stack. Neither stores pane content, scrollback, typed
input, or copied text.

Remove old logs and crash reports with the platform cleanup steps on the
[Uninstall](/docs/v0.6/uninstall) page.