Settings Reference¶

Koharu's Settings screen currently exposes six main areas:

This page documents the current settings surface as implemented in the app.

Appearance¶

The Appearance tab currently includes:

theme: Light, Dark, or System
UI language from the bundled translation list
Rendering Font, which is used when Koharu renders translated text onto the page

Theme, language, and rendering-font changes apply immediately in the frontend.

The Engines tab selects the backend used for each pipeline stage:

These values are stored in the shared app config and save immediately when changed.

The API Keys tab currently covers these built-in providers:

Each provider appears as an accordion with a status dot:

green — ready (key saved and discovery succeeded)
amber — missing required configuration (API key or, for OpenAI Compatible, a base URL)
red — discovery failed against the configured endpoint
grey — no configuration yet

Current behavior:

provider API keys are not written to config.toml
on macOS and Windows, provider API keys are stored through the system keyring
on Linux, provider API keys are stored in Koharu's local filesystem credential store under the app data directory with owner-only file permissions
provider base URLs are stored in the app config
OpenAI Compatible requires a custom Base URL; models are discovered dynamically by calling GET /v1/models against that URL
machine-translation providers (DeepL, Google Cloud Translation, Caiyun) only need an API key; Caiyun supports a limited set of target languages
clearing a key removes it from credential storage

The API response intentionally redacts saved keys rather than returning the raw secret.

The Linux filesystem credential store relies on local filesystem permissions rather than OS-level encryption.

The Keybinds tab lets you rebind tool-switch and brush-size shortcuts plus the undo and redo bindings.

Current behavior:

defaults are V/M/B/E/R for the Select / Block / Brush / Eraser / Repair Brush tools
defaults are [ and ] for the brush size step
defaults are Ctrl + Z and Ctrl + Shift + Z (Cmd + Z and Cmd + Shift + Z on macOS) for undo and redo
the canvas zoom (Ctrl + wheel), pan (Ctrl + drag), select-all (Ctrl + A), and the legacy Ctrl + Y redo fallback are not rebindable
conflicts are highlighted in the editor; you can reset to defaults from the same screen

Keybind preferences are stored in the frontend preferences layer, not in config.toml.

For the full default list, see Keyboard Shortcuts.

The Runtime tab groups restart-required settings that affect the shared local runtime:

Current behavior:

Data Path controls where Koharu stores runtime packages, downloaded models, page manifests, and image blobs
HTTP Connect Timeout sets how long Koharu waits while establishing HTTP connections
HTTP Read Timeout sets how long Koharu waits while reading HTTP responses
HTTP Max Retries controls automatic retries for transient HTTP failures
these HTTP values are used by the shared runtime HTTP client for downloads and provider-backed requests
applying changes saves the config and restarts the desktop app because the runtime client is built at startup

The About tab currently shows:

In packaged app mode, the version check compares the local app version against the latest GitHub release for mayocream/koharu.

The current settings behavior is split across storage layers:

config.toml stores shared app config such as data, http, pipeline, and provider baseUrl
provider API keys are stored separately from config.toml through the platform credential store described above
theme, language, and rendering-font preferences are stored in the frontend preferences layer

That means clearing frontend preferences is not the same as clearing saved provider API keys or shared runtime config.