Customization
Configure Kunai through config.json: provider relay, mpv forwarding, download paths, posters, keybindings, and the settings that survive an upgrade.
Kunai stores preferences locally. Most settings are editable from /settings or /setup inside the shell. Advanced users can edit JSON directly.
Config locations
| File | Purpose |
|---|---|
~/.config/kunai/config.json | User preferences, provider priority, language profiles, presence, downloads |
~/.config/kunai/install.json | Install channel metadata (binary / npm / bun) |
config.json
The main config file is created on first run or after kunai --setup. Kunai merges saved values with defaults on load, so you do not need every key present.
Mode and providers
| Key | What it controls |
|---|---|
defaultMode | Startup catalog: series (default), anime, or youtube |
provider | Default movie/series provider for new sessions |
animeProvider | Default anime provider |
providerPriority | Fallback order for movie/series providers (empty = registry default) |
animeProviderPriority | Fallback order for anime providers |
titleProviderPreferences | Per-title provider override chosen explicitly by the user |
youtubeProvider | Default YouTube-mode provider (default youtube) |
youtubeProviderPriority | Fallback order for YouTube-mode providers (default ["youtube"]) |
Unknown provider ids in priority arrays are ignored. Providers not listed remain available after configured entries.
More on fallback behavior: Providers.
YouTube metadata and cookies
{
"youtubeMetadata": {
"cookiesFromBrowser": "firefox",
"cookiesFile": "/absolute/path/to/cookies.txt"
}
}cookiesFromBrowser: optional browser profile name for yt-dlp (no default).cookiesFile: optional absolute path to a cookie file (no default).- Never paste cookie contents into issues or chat. Review redacted
/export-diagnosticsbundles before sharing. - Kunai does not bypass DRM or YouTube access controls; cookies only help yt-dlp with content your account can already play.
See Providers → YouTube.
Provider relay
providerRelay is optional. Leave baseUrl empty for direct provider fetches
only. Set it when you run your own relay for provider metadata APIs that are
geo-blocked from your network.
{
"providerRelay": {
"baseUrl": "https://your-relay.example",
"token": "same-secret-as-the-relay-server",
"fallbackToDirect": true,
"providers": {
"allanime": { "enabled": true }
}
}
}Internet relay deployments require a bearer token configured on both the relay
server and Kunai. A token is optional only for the local development server when
it is bound to numeric loopback (127.0.0.1 or ::1).
KUNAI_RELAY_BASE_URL and KUNAI_RELAY_TOKEN override local config for smoke
tests and temporary sessions. The relay is metadata-only. Stream URLs always
stay direct, and unknown legacy video-relay keys are ignored.
Language and media profiles
Kunai uses separate profiles for anime, series, movies, and YouTube:
During kunai --setup, the language screen also exposes a YouTube profile.
Tab/Shift+Tab cycle Shows, Movies, Anime, and YouTube; ←/→ switch
between audio and subtitles; ↑/↓ choose a value; and a copies the active
profile to all four lanes. Playback defaults (autoplay, intro skip, and credit
skip) start off. Press s for the recommended all-on defaults. The final setup
screen summarizes every choice before saving.
Example (not the shipped defaults; those use audio: "original" and quality: "best"):
{
"animeLanguageProfile": { "audio": "ja", "subtitle": "en", "quality": "1080p" },
"seriesLanguageProfile": { "audio": "en", "subtitle": "en", "quality": "best" },
"movieLanguageProfile": { "audio": "en", "subtitle": "en", "quality": "best" }
}animeTitlePreference: display English, romaji, native, or provider-native titles.favoriteSources: pin preferred source/server names to the top of pickers.
See Media selection for how profiles flow into resolution and mpv.
Playback and recovery
| Key | What it controls |
|---|---|
autoNext | Autoplay next episode when available |
autoplayRecommendations | YouTube-style continue into top recommendation when caught up |
skipIntro, skipRecap, skipPreview, skipCredits | Auto-skip segments when timing metadata exists |
recoveryMode | guided, fallback-first, or manual |
resumeStartChoicePrompt | Resume vs start-over overlay when resuming mid-episode |
quitNearEndBehavior | What happens when you quit mpv near the natural end |
quitNearEndThresholdMode | When "near the end" starts: credits-or-90-percent (default), or a fixed percentage |
continueSourcePreference | Where Continue Watching resumes from: auto (default), local, stream, or ask |
Shell density and chrome
| Key / flag | Effect |
|---|---|
zenMode / --zen | Single-column, minimal chrome; all features still key-reachable |
minimalMode / --minimal | Collapse companion pane and dim header status |
footerHints | detailed or minimal footer guidance |
discoverShowOnStartup | Faint discover hint in browse footer when history exists |
discoverMode | What /discover mixes: auto (default), unified, anime-only, or series-only |
discoverItemLimit | Rows the Discover tray shows (default 24) |
powerSaverMode | Suppress background network and speculative work |
powerSaverAllowManualArtwork | Still fetch artwork you ask for by hand while power saver is on (default true) |
recommendationRailEnabled | Show the recommendation rail after playback (default true) |
Kunai ships with the Sakura design system baked into the terminal UI. There is no separate theme picker today; density modes (zen, minimal) are how you reduce visual chrome.
Downloads and offline
| Key | What it controls |
|---|---|
downloadsEnabled | Gate for download features (off until opted in) |
downloadPath | Custom download directory (empty = app data default) |
maxConcurrentDownloads | Parallel download jobs (clamped 1–5) |
offlineFreeSpaceReserveBytes | Reserved disk space before accepting new downloads |
defaultDownloadQuality | Shared quality floor for new download jobs |
offlineMode | Persistent local-only shell posture (separate from --offline launch) |
autoCleanupWatched | Surface watched downloads as cleanup candidates |
autoCleanupGraceDays | Days a watched download is kept before it becomes a cleanup candidate (default 7) |
offlineArtworkCacheEnabled | Cache poster artwork alongside downloads for offline browsing (default true) |
Sync integrations (opt-in)
{
"sync": {
"anilist": { "enabled": false, "trackWatched": false, "syncList": false },
"tmdb": { "enabled": false, "trackWatched": false, "syncList": false }
}
}Tokens are stored separately. Sync is experimental and fail-closed: nothing leaves the machine until you enable it in Settings › Sync. Pending mutations sit in a local outbox and retry; auth failure holds the row until you re-authenticate. Failed-closed rows do not invent progress on AniList/TMDB.
Provider domains
Provider domains for the media (movie/TV and anime) providers are compiled in; changing a media-provider domain requires a code change and rebuild, not a config file. Exception: YouTube metadata endpoints are configurable via youtubeMetadata.instanceUrl and youtubeMetadata.pipedApiUrl in settings or config.json, no rebuild needed.
To reach provider metadata APIs through a different network, configure your own relay with providerRelay.baseUrl in /settings or config.json. See Provider relay. This changes the network path, not the provider domain; video stays direct.
mpv flags and bridge options
Kunai always launches mpv for playback. You can forward diagnostic flags for a single run:
| Flag | Effect |
|---|---|
--mpv-debug | Verbose mpv logging |
--mpv-clean | Minimal mpv config for isolation testing |
--no-user-mpv-config | Ignore user mpv.conf for this run |
--mpv-log-file <path> | Write mpv log to a specific file |
These are process flags; see CLI Reference.
Persistent mpv bridge settings
Config keys tune the Kunai Lua bridge script:
| Key | Purpose |
|---|---|
mpvKunaiScriptPath | Custom path to kunai-bridge.lua (empty = auto-resolve) |
mpvKunaiScriptOpts | --script-opts entries for the bridge (e.g. margin_bottom, chip_width). An entry whose key or value contains , or = is dropped; mpv's option list cannot represent one |
mpvInProcessStreamReconnect | Reload same URL after network-read-dead stalls |
mpvInProcessStreamReconnectMaxAttempts | Max reload attempts per playback cycle (clamped 0–1; 0 disables reconnect) |
Example mpvKunaiScriptOpts:
{
"mpvKunaiScriptOpts": {
"margin_bottom": "130",
"prompt_seconds": "8"
}
}Kunai still passes provider-required headers (referrer, user-agent) and subtitle attachments automatically. Do not expect arbitrary mpv CLI passthrough from config today; use the flags above for debugging.
Discord presence setup
Discord Rich Presence is off by default and local-only.
Choose provider and privacy
- Set Presence to
discord. - Set Presence privacy to
full(title/episode detail) orprivate(generic activity).
Discord desktop, then connect
The Discord desktop app must be running (local IPC). Kunai ships a default application client id; you do not need to create a Discord app for the default path. Override in Settings › Presence or KUNAI_DISCORD_CLIENT_ID only if you want your own application. Presence stays off until you set the provider to discord.
Connect and verify
Use Connect Discord now in Settings. Kunai connects through Discord's local IPC (Unix socket on Linux/macOS, named pipe on Windows), no cloud relay.
While playing, Kunai updates episode cards and progress timestamps. Paused playback shows static text; activity clears after a configurable idle delay.
Diagnostics record presence connect/clear failures. Check /diagnostics if Discord shows unavailable or error.
More: Diagnostics and reporting.
Editing config safely
Use /settings or /setup for guided changes. Settings persist immediately to config.json.
Reset without uninstall
Delete config.json to reset preferences. Use kunai uninstall --purge only when you want config, history, cache, and default downloaded videos removed together (Linux: ~/.local/share/kunai/downloads, or $XDG_DATA_HOME/kunai/downloads). Custom/external download directories outside Kunai's config, data, and cache directories are preserved. See Install and update for all platform paths.
Last updated on
Provider status
Daily live check on every registered provider, covering upstream reachability, resolve health, lane counts, and known gate reasons.
Runtime Feedback
Read Kunai's live playback health, memory, and network panels, and understand what each diagnostic signal is telling you while a session is still running.