Skip to content
kōan
Contents

Start

Server

Library

Playback

Automation

Reference

Protocol

Configuration

Four sources are merged, each overriding the one before it:

Defaults -> config.toml -> config.local.toml -> KOAN_* env vars
(lowest)                                       (highest priority)
Layer Path Purpose
Defaults (built-in)
config.toml ~/.config/koan/config.toml Shared settings -- safe to commit to dotfiles
config.local.toml ~/.config/koan/config.local.toml This machine only, gitignored, 0600
Environment KOAN_* vars Containers and one-off overrides

Run koan config to see the merged result, the files it came from and which KOAN_* env vars are active.

Which file a setting goes in

You can put any setting in either file by hand -- the merge does not care. What the split decides is where kōan writes when it changes a setting itself, and that matters because config.toml is meant to be committed.

Three kinds of setting are machine-scoped and always land in config.local.toml:

Kind Settings
Secrets remote.password/api_key/device_key, subsonic.password, auth.refresh_token, lastfm.api_key, lastfm.secret
This machine's paths, disk, hardware and account library.folders, remote.enabled/url/username/server_url, remote.cache_dir, remote.cache_limit, remote.download_ahead, remote.play_queue, server.url, auth.server, playback.output_device/renderer/renderer_name/renderers/muted/rate_switch_lead_in_ms, subsonic.enabled/port/username/transcode/ffmpeg, devices.nearby/discoverable/port/addresses/nearby_control/refused/keep_running, updates.auto, appearance.text_size, everything under dsp
Volatile UI state -- flipped by a keypress or a mouse drag playback.art_size/art_graphics/tui_theme/queue_grouped, visualizer.enabled, visualizer.mode, visualizer.matrix_overlay, visualizer.bass_shake, appearance.rainbow

Everything else is taste, travels between machines, and goes in config.toml.

Writing a setting also clears any copy of it from the other file, because config.local.toml wins the merge: a shared write left shadowed by a local copy would silently do nothing. In the other direction it drains machine-scoped keys out of the file you commit, which is how a config.toml polluted by an older kōan cleans itself up as you use the app.

What is not in the config files

The desktop app's own view state -- the window's bounds, whether the sidebar shows, whether the queue is grouped -- lives in desktop-window in its state directory, not in config.toml. None of it means anything to the CLI or the TUI, and a setting that travels between machines in a committed dotfile should be one that makes sense on all of them.

Environment variable overrides

Any config field can be overridden via environment variables using the KOAN_ prefix with __ (double underscore) as the section separator:

KOAN_<SECTION>__<FIELD>=<value>

Examples:

# Remote server password (avoids writing secrets to files)
export KOAN_REMOTE__PASSWORD="hunter2"

# Change GraphQL API port
export KOAN_GRAPHQL__PORT=8080

# Bind API to all interfaces
export KOAN_GRAPHQL__BIND="0.0.0.0"

# Override render FPS
export KOAN_PLAYBACK__TARGET_FPS=30

# Enable the GraphiQL playground
export KOAN_GRAPHQL__PLAYGROUND=true

# Set ReplayGain mode
export KOAN_PLAYBACK__REPLAYGAIN=track

Field names match the TOML key in SCREAMING_SNAKE_CASE. Nested sections use __:

koan config init

Creates the config directory at ~/.config/koan/ with everything kōan needs to run:

koan config init

What it creates:

File Purpose
config.toml Commented template -- all defaults shown as comments for reference, uncomment to customize
config.local.toml Template for machine-specific settings (library folders, remote server)
.gitignore Ignores *.log, *.db, config.local.toml, cache/
koan.db SQLite database (created if missing)
cache/ Download cache directory
thumbs/ The TUI's album thumbnails, kept to 256 MB with the least recently used dropped first; safe to delete

Running koan config init on an existing setup is safe -- it merges new defaults without touching values you've changed, and skips config.local.toml if it exists.

Machine-scoped settings are left out of the config.toml template entirely -- listing them, even commented out, invites them into a dotfiles repo. That means you can commit ~/.config/koan/ and share playback, visualizer and organize settings across machines while library paths, credentials and window sizes stay local.


[playback]

[playback]
replaygain = "off"          # off | track | album
pre_amp_db = 0.0            # dB gain on top of ReplayGain (default: 0.0)
fade_on_pause = true        # fade out on pause, back in on resume (default: true)
target_fps = 60             # TUI render rate in Hz (default: 60)
show_fps = false            # FPS counter overlay in top-right corner (default: false)

# config.local.toml -- this machine's hardware and terminal
art_size = 24               # album art width in terminal columns (default: 24)
art_graphics = true         # draw covers with the terminal's graphics protocol (default: true)
tui_theme = "koan"          # koan | ansi (default: koan)
queue_grouped = true        # the TUI's queue in album runs rather than a row per track (default: true)
output_device = "My DAC"    # audio output device name (default: system default)
rate_switch_lead_in_ms = 1000 # silence after a sample rate change (default: 1000)
renderers = true            # look for UPnP renderers on the network (default: true)
muted = false               # play silence (default: false)

renderer and renderer_name record the UPnP renderer last chosen as the output; kōan returns to it at launch when it is on the network, and otherwise plays on output_device. They are written by the Output menu rather than by hand.

ReplayGain

ReplayGain normalizes loudness across tracks. kōan reads standard ReplayGain tags (embedded by tools like loudgain, r128gain, foobar2000) at decode time and applies gain with peak limiting to prevent clipping.

Mode Description
off No gain adjustment. Original signal untouched
track Per-track normalization. Every track plays at the same perceived loudness. Best for shuffled playlists
album Per-album normalization. Preserves dynamic range within an album (quiet intros, loud climaxes) while normalizing between albums. (recommended)

pre_amp_db adds a fixed gain on top of the ReplayGain adjustment. Positive values make everything louder (risk of clipping), negative values quieter. Useful if your ReplayGain-tagged library feels too quiet at the target level.

Fade on pause

With fade_on_pause, pause ramps the output down over 150ms before the audio unit stops, and resume ramps it back up. The ramp is applied in the render callback and only while it runs; at full level samples are copied unmodified. The position rests on the last sample that was audible, not on audio consumed during the fade and discarded. Off, pause and resume cut immediately.

Rate switch lead-in

When a track needs the output device at a different sample rate, the device relocks its clock, and many interfaces mute until it has. koan cannot see that happen: CoreAudio reports the new rate as soon as it is accepted, and no property says when the clock has locked. Audio sent in that window is lost, so the start of the track goes missing.

rate_switch_lead_in_ms plays that much silence first, through the running output so devices that only relock on a live stream do so, and the playhead stays at the start until the track itself is heard. Only a rate change adds it; a resume clears it. How long the relock takes depends on the device, so the setting lives in config.local.toml. 0 turns it off.

Render FPS

target_fps controls how often the TUI redraws. 30, 60, or 120 are typical values. Higher values give smoother visualizer and seek bar updates but use more CPU.

Album art size

art_size sets the width in terminal columns. Height is always art_size / 2 (square in half blocks, where each cell is 2 pixels tall). The default of 24 columns = 24x12 cells = a 24x24 pixel-equivalent square. Drag the hairline above the transport bar to change it; the new size is saved to config.local.toml, since it is a property of the terminal you are sitting at.

Cover graphics

With art_graphics on, the TUI asks the terminal at startup whether it draws images (the kitty or iTerm2 protocol; sixel is not used) and uses them for covers and album tiles.

While the album grid scrolls its tiles are half blocks, turning back into images when it stops: terminals draw a kitty image as a placeholder in every cell, and a screen of those moving every frame is slow. iTerm2-protocol terminals keep their images. Covers are shaped by the cell size the terminal reports.

Terminals that do not answer get half blocks, which is also what art_graphics = false gives, and skips the question. I in the TUI switches for the session and saves the choice. It lives in config.local.toml: whether images work is a property of the terminal at hand.

TUI palette

tui_theme = "koan" draws the kōan theme in 24-bit colour where the terminal reports it, with the accent taken from the playing cover. "ansi" uses the terminal's own sixteen colours. No background is painted either way. Also in config.local.toml.

Output device

output_device selects an audio output by name. Press D in the TUI to browse available devices and switch live. The choice is saved to config.local.toml -- your DAC is not the next machine's. If the named device isn't available at startup, kōan falls back to the system default.

Run koan devices to list available audio outputs.

Automated runs

muted zeroes every sample in the render callback, so playback carries on, with its position, queue and gapless handover, but nothing is heard. renderers = false stops kōan looking for UPnP renderers, so none appears under Output and none can be played to. The app UI tests set both, as KOAN_PLAYBACK__MUTED and KOAN_PLAYBACK__RENDERERS, because they run on a machine someone is using, whose speakers and network renderers are theirs.


[appearance]

How the macOS, iOS, tvOS and Android apps are drawn. The theme is read once as an app opens, so a change of theme shows the next time it starts; the others apply at once.

[appearance]
theme = "koan"     # "koan": the site's look throughout (the default); "system": the platform's own
theme_icons = true # in the kōan theme, icons beside labels; false for labels alone
record_colours = true # the record playing colours the wash and the accent; false for neither
wash_tint = 100       # kōan theme: how far the wash is held to the theme's contrast limit, 0–100; 0 keeps the sleeve's own colours
wash_drift = 100      # kōan theme: how fast the wash drifts while music plays, in percent of its own pace, 0–200; 0 holds it still
wash_turn = 3         # kōan theme: how far the wash turns either way as it drifts, in degrees, 0–10
wash_window = true    # provisional. Mac and desktop app, kōan theme: the wash under the whole window; false gives panels their own grounds
text_size = 100       # Mac, kōan theme: text size in percent, 80–130 in steps of 5; spacing follows at half the rate. In config.local.toml

Settings → Appearance → Theme chooses between them on every app, and Show icons, shown while the kōan theme is chosen, sets theme_icons. On the Mac in the kōan theme, Text size (and View → Bigger, Smaller and Actual Size, ⌘+, ⌘− and ⌘0) sets text_size, applied at once; 100 % draws the theme's type as large as the system's. The kōan theme draws its own icon set, thin square-ended lines; the system look always draws its icons, which are Apple's SF Symbols. Colours from the record sets record_colours: off, there is no wash behind the window and the accent is koan's mint, in either theme. On, they come from the record playing, except while a record's page shows, which wears its own sleeve. In the desktop app an artist's page wears the artist's photo when there is one; Now Playing always wears the playing record. Theme tint, shown in the kōan theme while colours come from the record, sets wash_tint: at 100 the wash is darkened in dark mode, or lightened in light, far enough that muted text over it keeps its contrast; lower lets more of the sleeve's own colour through, and 0 none of the hold at all. Text over a bright sleeve can then lose contrast, which is the trade. Drift and Turn (the desktop app, kōan theme) set wash_drift, how fast the wash breathes and travels while music plays (100 its own pace, 0 still), and wash_turn, how far it turns either way as it does, in degrees. wash_window (the Mac and the desktop app, kōan theme only, and only with the record's colours on) is provisional, there to live with both looks while one is chosen, and likely to go: on, the sidebar, toolbar and lyrics are drawn clear over one wash, and the transport keeps its ground beneath them all; off, they keep grounds of their own. The graphics level is separate, and governs what the wash costs rather than whether it takes colour; the playing bars move at every level, held still only by Reduce Motion. The theme's design is docs/design/koan-theme.md.

[library]

# config.local.toml (this machine's paths)
[library]
folders = ["/Volumes/Music/library", "/Users/me/Music"]

One or more directories to scan for music. Subdirectories are scanned recursively.

While kōan runs it watches the folders and indexes what changes in them, rather than scanning on a timer. A folder on a network share (NFS, SMB, AFP, or any FUSE mount) is scanned whole every fifteen minutes as well, because a file another machine writes there raises no event on this one. A folder added in the apps, the TUI, the web UI or by editing the file is watched at once, and a folder that does not exist yet is watched as soon as it is created.

None by default: kōan reads no folder you have not named. Looking in ~/Music unasked meant reading the Apple Music library inside it, and macOS asking whether kōan may. Versions before 0.61.1 used ~/Music when no folder was set; if your library was indexed from there, the first newer kōan to open it writes ~/Music into config.local.toml, so nothing is lost. A folders key in either file, an empty list included, is left as it is.

public_playlists = true (KOAN_LIBRARY__PUBLIC_PLAYLISTS) makes the playlists read from .m3u, .m3u8 and .nsp files in the library public, so every account on a server sees them, read-only. Off by default: they are the first admin's alone, as Navidrome imports them. It applies at each scan to every file's playlist, those read before included; playlists made in kōan keep their own setting.


[remote]

# config.local.toml (credentials should stay local)
[remote]
enabled = true
url = "https://music.example.com"
username = "admin"
# password is prompted by `koan remote login` and saved here

# config.local.toml -- this machine's disk
cache_limit = "50GB"             # max cache size, LRU eviction at startup and as downloads land; "0" keeps only what plays next (default: unlimited)
download_ahead = 3               # tracks past the playing one to fetch; 0 gives up gapless (default: the whole queue, up to 250)
cache_dir = "/custom/path"       # explicit cache dir (default: ~/.config/koan/cache)
play_queue = false               # keep this device's queue on the server (default: false)

# config.toml
[remote]
download_workers = 5             # parallel download threads (default: 5)
auto_sync = true                 # check the server for changes on a timer (default: true)
auto_sync_interval_mins = 60     # minutes between checks; 0 checks once at startup (default: 60)

A server that links (a kōan server) tells the app when its library changes, so the interval applies only to other Subsonic servers. Auto-sync runs again as soon as its settings change, in the apps or in the file.

cache_limit takes a size such as "500MB" or "50GB"; unset or empty is unlimited. "0" keeps only what the queue is about to play, the downloads asked for and favourite albums, deleting each track once it has played. download_ahead counts tracks past the playing one: 1 is the least that keeps playback gapless, and 0 fetches each track only when it starts. Both are Settings → Downloads in the apps; see Cache management.

Signing in also writes api_key (the key an invite or pairing stores, used instead of a password), device_key (the keypair this device proves itself with to the account's other devices on the local network) and server_url (the address the server says it is reached at, which devices compare to tell whether they share a server). All three are kept in config.local.toml and dropped at sign-out.

auto_sync is for servers that cannot say when their library changes; a kōan server tells its apps itself. A check walks the library only if the server reports a change since the last walk. play_queue is the Settings → Devices switch described in The play queue on the server.

See Remote Servers for the full setup guide.

Where credentials live

Every secret kōan holds -- the remote password, the Subsonic shared secret, the refresh token for a kōan server -- is written to config.local.toml, which is gitignored and created 0600.

Not the OS keychain: a keychain item is bound to the reading binary's code signature, which changed with every build, so macOS asked for the password after every update. A Subsonic client has to keep something password-equivalent in any case, and a 0600 file is the same bargain ~/.netrc and gh's hosts.yml make.

[auth]

Credentials for a remote kōan server this machine signs in to -- the other direction from [graphql], which configures the server kōan is.

# config.local.toml
[auth]
server = "http://localhost:4000"   # written by `koan auth login`
refresh_token = "..."              # exchanged for short-lived access tokens

Written by koan auth login and cleared by koan auth logout, which also revokes the token at the server. koan play --server reads it, and rewrites refresh_token each time it refreshes, since the server revokes the old one. Unlike a password this is revocable, so losing it costs you one session rather than the account.

See Authentication.


[visualizer]

[visualizer]
fps = 60                      # analysis thread update rate in Hz (default: 60)
scale = "bark"                # frequency scale (default: bark)
amplitude_scale = "aweight"   # amplitude scale (default: aweight)
bar_decay_ms = 50             # bar drop half-life in ms (default: 50)
peak_decay_ms = 180           # peak marker linger half-life in ms (default: 180)
palette = "theme"             # theme (follows the UI), rainbow, mono, fire, neon (default: theme)
reactivity = 1.0              # animation reactivity 0.0..2.0 (default: 1.0)
reactive_bg = false           # beat-reactive background on braille modes (default: false)

# config.local.toml -- the keybind toggles, saved as you press them
enabled = true                # show visualizer in transport area (default: true)
mode = "bars"                 # visualizer mode (default: bars). Press `V` to pick.
bass_shake = true             # camera jitter on bass hits for braille modes (default: true)
matrix_overlay = false        # replace characters with matrix glyphs (default: false)

Also accepts [visualiser] spelling.

enabled, mode, bass_shake and matrix_overlay have keybinds (V picks off or a mode, M cycles modes, S, X) and are written back the moment you press one, so they live in config.local.toml. The rest are hand-edited taste and travel with config.toml.

22 modes available: bars, oscilloscope, radial, particles, lissajous, spectrogram, stereo waveform, VU meter, flame, plasma, tunnel, wireframe, metaballs, starfield, terrain, moire, kaleidoscope, julia, spiral, interference, wormhole, matrix. Press V in the TUI to open the picker with live preview.

The visualizer renders above the transport text when album art is present. 48-band FFT with sub-cell resolution using Unicode block characters, peak hold markers, and smooth exponential decay. The FFT runs on a dedicated thread so the UI is never blocked.

Frequency scales (scale)

Controls how FFT bins map to bars (the X axis):

Scale Description
bark Bark psychoacoustic scale -- 24 critical bands, matches how your ears group frequencies. Best for music. (default)
mel Mel perceptual pitch scale -- similar to Bark, widely used in speech/music analysis
log Logarithmic -- equal spacing per octave. Familiar if you read spectrograms
linear Linear -- equal Hz per bar. Bass is cramped, treble dominates. Analytical use

Amplitude scales (amplitude_scale)

Controls how magnitudes map to bar height (the Y axis):

Scale Description
aweight A-weighted (IEC 61672). Reflects perceived loudness -- bass and extreme treble attenuated to match human hearing. (default)
perceptual A-weighting + gentle gamma curve. Same frequency correction with a boost to quiet signals
sqrt Square root curve -- gentle boost to quiet bands, no frequency correction
linear Raw dB-normalized magnitude. No correction. Technically accurate

[organize]

[organize]
default = "standard"      # pattern selected by default in the TUI modal
move_ancillary = true     # cover art, cue sheets and logs move with the music (default: true)

[organize.patterns]
standard = "%album artist%/(%date%) %album%/%tracknumber%. %title%"
va-aware = "%album artist%/$if($stricmp(%album artist%,Various Artists),,['('$left(%date%,4)')' ])%album% '['%codec%']'/[$num(%discnumber%,2)][%tracknumber%. ][%artist% - ]%title%"
flat = "%artist% - %title%"

Named patterns for organize, in format string syntax. See File organization.


[graphql]

[graphql]
enabled = false               # serve the API beside the TUI (default: false; headless always serves)
port = 4000                   # API port (default: 4000)
bind = "127.0.0.1"            # bind address (default: 127.0.0.1)
playground = false            # enable GraphiQL IDE at GET /graphql (default: false)
auth_enabled = true           # JWT authentication (default: true)
access_token_ttl = "15m"      # access token lifetime (default: 15m)
refresh_token_ttl = "30d"     # refresh token lifetime (default: 30d)
cors_origins = []             # origins allowed to call the API from a browser
allowed_hosts = []            # extra Host: values to answer to (see below)
cookie_secure = false         # mark cookies Secure — only with HTTPS in front
proxy_auth_header = ""        # header an authenticating proxy names the user in
proxy_auth_from = []          # addresses or ranges that proxy connects from
allow_organize = false        # expose the organize* mutations, which move files
setup_wizard = true           # headless: web UI /setup makes the first admin while there is none

The TUI serves the API only when asked: enabled = true, or one of --api, --port, --bind, --subsonic or --playground. Before 0.66 it served on 127.0.0.1:4000 unasked; set enabled = true to keep that.

Auth is enabled by default. Until an account exists, the web UI's setup page makes the first admin; koan auth setup does the same from a shell. setup_wizard = false turns the page off, since whoever reaches it first becomes the admin. The page is only offered in headless mode: an API served beside the TUI has a shell to hand, so its first admin comes from koan auth setup. Set auth_enabled = false if you only use localhost and don't need auth.

Browser access

cors_origins is empty by default, which means no web page may read the API cross-origin. Add the origin your web client is served from — ["https://music.example.com"] — to allow it.

allowed_hosts names the hostnames this server answers to, on top of localhost and any bare IP address. A request arriving with any other Host is refused: without that check, a page whose DNS flips to 127.0.0.1 after loading reaches the API as same-origin and CORS stops applying. Set it if you reach kōan through a name like koan.lan.

cookie_secure should stay false unless clients reach kōan over HTTPS. Browsers discard Secure cookies delivered over plain http:// to anything but localhost, so setting it on a LAN deployment silently breaks cookie auth.

proxy_auth_header and proxy_auth_from sign the web UI in through an authenticating reverse proxy. Both are set or neither: the server refuses to start with only one, with an entry it cannot parse, or with a range covering every address. See Behind an authenticating proxy.

allow_organize gates organizePreview, organizeExecute and organizeUndo. They rename and move files on disk, which is not something a network API should offer by default.


[subsonic]

kōan's Subsonic API, served at /rest/*. Clients sign in with a kōan account; see Authentication.

# config.local.toml -- which machine serves Subsonic
[subsonic]
enabled = false               # serve /rest/* on the main port (default: false)
port = 4040                   # also serve it on a port of its own (default: none)
username = "koan"             # the shared secret's username (default: koan)
transcode = true              # transcode stream for clients that ask (default: true)
ffmpeg = "ffmpeg"             # the ffmpeg transcoding runs, on PATH or a path (default: ffmpeg)

koan subsonic setup enables it and generates a shared secret, written to config.local.toml and printed once. The secret signs in as username with user rights, for a client that has no account of its own; koan play --server streams with it. It is generated rather than chosen because Subsonic token auth sends md5(secret + salt) with every request, and a captured digest of a human-chosen password can be cracked offline.

A client that asks stream for a maxBitRate below the file's bitrate, or for format=opus, format=mp3 or format=aac (also m4a), gets a transcode made by ffmpeg: Opus unless another format was asked for, at the requested bitrate or 128 kbps (Opus) and 192 kbps (MP3, AAC). AAC is AAC-LC from ffmpeg's built-in encoder, sent as ADTS (audio/aac); a file already in the requested format and within the limit is sent as it is. format=raw, and download, always return the original.

A transcode has no length until it ends, so it is sent without one, unless the client passes estimateContentLength=true (the body is then cut or padded to the bitrate times the duration), and without Range support; clients seek with timeOffset, offered as the OpenSubsonic transcodeOffset extension.

The server runs at most one transcode per CPU core and three per account; beyond that, and whenever ffmpeg produces nothing, the original is served. Where ffmpeg does not run or has none of libopus, libmp3lame and aac, the server logs it once at startup and serves originals. The container image includes it.


[server]

# config.local.toml -- this machine's address
[server]
url = "https://music.example.com"

The one address clients and strangers reach the server at (KOAN_SERVER__URL). On the desktop app sharing its own library, Settings → Server writes it from Invite phones to (below). A server answers on several (a LAN address, localhost, a domain) and cannot tell which of them another device can reach, so share links, the invites it makes, MCP's OAuth and the Last.fm callback are all built on this one. koan --headless refuses to start without it. Signed-in apps are told it by ping and know the server by it rather than by the address they typed, so devices that reach one server at different addresses still recognise each other.

An address with a path (https://host.example/koan) serves kōan under that path, behind a proxy that forwards it or strips it; see Under a path.

sharing.public_url, which this replaces, is still read while server.url is unset, with a warning in the log. It will be removed in a later release.

demo = true (KOAN_SERVER__DEMO) makes the server a public demo, as demo.koan.rocks is. It makes a user account named demo with the password demo when there is none, fills both in on the web UI's sign-in page, and refuses the requests one visitor could use to take the shared account from the others: changing its password, revoking its API keys and app passwords, connecting a scrobbling account, and managing accounts. Wiping the state on a schedule is left to whatever runs the server.


[share]

# config.local.toml -- whether this machine serves its library
[share]
enabled = true
port = 4000
invite_to = "tailnet"

The desktop app sharing its own library (Sharing your Mac), written by Settings → Server. enabled serves whenever the app is open; port is where, on every interface, and is refused when another process holds it on loopback. invite_to is where invites send phones: "tailnet", the machine's Tailscale name; "network", its local address; "funnel", its address on the internet through Tailscale Funnel, which is published whenever it serves; "custom", a tunnel's address. Each falls back to the tailnet name, then the local address, while it has nothing.

Funnel's address and a custom one are kept in server.url, this machine's one public address, which invites and share links are both built on, so the two always agree; a path in it is served as for a headless server (Under a path). Versions before 0.71 kept it in share.url, which the app moves into server.url once, at launch, unless server.url is already set. funnel records the Funnel kōan published ([443, 4000], Funnel's port and the local one), so it takes down its own and none set up by hand. Settings writes all of these through the engine. [graphql], the terminal UI's and the headless server's listener, is separate, though its sign-in settings apply here too.


[lastfm]

# config.local.toml -- both are secrets
[lastfm]
api_key = "..."
secret  = "..."

The API account the server scrobbles to Last.fm through. Last.fm gives one key and shared secret to each application, so the server's admin registers kōan at https://www.last.fm/api/account/create and sets both here, or as KOAN_LASTFM__API_KEY and KOAN_LASTFM__SECRET. Every account on the server then connects its own Last.fm. Without both, Last.fm is not offered.

Connecting also needs server.url (above), since Last.fm sends the person back to <server.url>/scrobbling/lastfm/return/.... See Scrobbling.


[mcp]

[mcp]
redirect_hosts = ["claude.ai", "claude.com"]

The hosts an MCP client may register to return to, besides this machine. Empty allows any HTTPS host, and each approval rests on the person recognising the host the consent page names. See MCP integration.


[push]

Push notifications to kōan's iOS app, for a server whose linked phones should stay reachable once iOS has suspended the app.

[push]
enabled = true    # false: no push, and phones are asked for no notifications

A linked app is reached over its WebSocket. iOS suspends a backgrounded app that is not playing, and the socket goes with it. With push on, the server then sends the app a background push, which wakes it to link and take what waits in its outbox (syncs, evictions), and turns a request to play on it into a notification the person taps: iOS does not let a suspended app start playing on its own. The notification carries only a claim; tapping it opens the app, which hands the claim back over its link, and the server runs what it kept for it. GraphQL's playOnClient says which happened.

Apple accepts pushes to the app only under the key of the team that ships it, so the server sends them through kōan's push relay, which holds that key. The server holds handles the app gave it, never a device token, and the relay decides what a phone shows: its own text, never the server's. What the relay sees and keeps, and why, is in Push and the relay, and its API in the push relay protocol. The relay is not configurable: the app registers with kōan's, the only one holding that key, and the server must push where the app registered.

With enabled = false the server does not use the relay at all: it does not list the koanPush extension, apps signed in to it ask for no notifications and give it no handles, and phones are reached only while linked; anything sent while a phone is suspended is applied when the app next opens.


[devices]

Controlling this device from koan apps on the same network, and reaching devices on networks that do not announce them. Devices on the same account reach each other through the server whatever this says. See Playing on another device.

# config.local.toml -- whether a machine is open to its network is its own business
[devices]
nearby = true                       # take part in the local network at all; false reaches others only through the server
discoverable = true                 # listen, and announce this device (and its server's address) over Bonjour
port = 5626                         # fixed, so a typed address keeps working
addresses = ["mac-mini:5626"]       # dialled directly: for a tailnet, which carries no Bonjour
nearby_control = "full"             # "full" or "playback": what devices on the network may do here
refused = ["192.168.1.40"]          # addresses whose connections are hung up at once; Settings → Devices → Refuse
keep_running = false                # the desktop app keeps running with its window closed

A discoverable device can be seen and controlled by any koan app on the network, whoever is signed in there, never with this device's account's powers: nothing reaches the library, the files on disk, or the account's playlists, favourites or history. nearby_control = "full", the default, is for a household network: they may also choose the output, the preset and the volume, and move the music here or away. "playback" is for a network shared with strangers: play and the queue only, and a hand-off that stays on the network. If the port is taken, koan listens on another and announces that one, so only typed addresses miss it.


[updates]

How the desktop app keeps itself up to date. It checks GitHub for a newer release at launch and once a day after.

# config.local.toml -- how this machine's copy was installed decides what an update can do
[updates]
auto = true                         # fetch each new release and install it when kōan quits

A DMG install on macOS and an AppImage on Linux update themselves: the release is downloaded, checked against the digest GitHub publishes for it (and on macOS against the Developer ID the running app is signed with), and put in place when kōan quits. Installs a package manager keeps, the Homebrew cask and the .deb, and builds from source never replace themselves; Settings → Devices says when a newer version is out.


[dsp]

Corrections, EQs and presets, each correction for the output devices it names. They describe the listening setup, so all of [dsp] belongs to the machine. See Equalisation and convolution.

# config.local.toml
[dsp]
enabled = true                      # false, from before Flat, makes every device flat at start

[[dsp.profiles]]
name = "Living room"
devices = ["Topping E30"]           # as `koan devices` names them
impulses = ["dsp/living-room/48000.wav"]  # WAV or Convolver .cfg per rate; relative to this directory
# preamp_db = -6.0                  # unset: derived from the filters' peak gain
filters = [
    { type = "peaking", freq = 20.0, gain_db = -1.3, q = 2.0 },
    { type = "gain", freq = 1000.0, gain_db = -2.0, channels = [1] },  # channels from 0; unset is all
]

They are normally made by importing (koan dsp import, or Settings in the apps), which reads every format the guide lists and keeps the result under dsp/ here.


File paths

File Default location
Config (base) ~/.config/koan/config.toml
Config (local) ~/.config/koan/config.local.toml
Database ~/.config/koan/koan.db
Download cache ~/.config/koan/cache/
TUI thumbnails ~/.config/koan/thumbs/
Log file ~/.config/koan/koan.log