Logging and crash reports

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

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

version 2

logging {
    enabled #true
    level "warning"
    format "pretty"
    max-log-file-size-in-mb 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

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:

crash-<seconds-since-1970>.txt

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

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 page.