| --- |
| title: Settings Reference |
| --- |
| |
| # Settings Reference |
|
|
| Koharu's Settings screen currently exposes six main areas: |
|
|
| - `Appearance` |
| - `Engines` |
| - `API Keys` |
| - `Keybinds` |
| - `Runtime` |
| - `About` |
|
|
| 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. |
|
|
| ## Engines |
|
|
| The `Engines` tab selects the backend used for each pipeline stage: |
|
|
| - `Detector` |
| - `Bubble Detector` |
| - `Font Detector` |
| - `Segmenter` |
| - `OCR` |
| - `Translator` |
| - `Inpainter` |
| - `Renderer` |
|
|
| These values are stored in the shared app config and save immediately when changed. |
|
|
| ## API Keys |
|
|
| The `API Keys` tab currently covers these built-in providers: |
|
|
| - `OpenAI` |
| - `Gemini` |
| - `Claude` |
| - `DeepSeek` |
| - `DeepL` |
| - `Google Cloud Translation` |
| - `Caiyun` |
| - `OpenAI Compatible` |
|
|
| 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. |
|
|
| ## Keybinds |
|
|
| 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](keyboard-shortcuts.md). |
|
|
| ## Runtime |
|
|
| The `Runtime` tab groups restart-required settings that affect the shared local runtime: |
|
|
| - `Data Path` |
| - `HTTP Connect Timeout` |
| - `HTTP Read Timeout` |
| - `HTTP Max Retries` |
|
|
| 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 |
|
|
| ## About |
|
|
| The `About` tab currently shows: |
|
|
| - the current app version |
| - whether a newer GitHub release exists |
| - the author link |
| - the repository link |
|
|
| In packaged app mode, the version check compares the local app version against the latest GitHub release for `mayocream/koharu`. |
|
|
| ## Persistence model |
|
|
| 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. |
|
|
| ## Related pages |
|
|
| - [Use OpenAI-Compatible APIs](../how-to/use-openai-compatible-api.md) |
| - [Models and Providers](../explanation/models-and-providers.md) |
| - [HTTP API Reference](http-api.md) |
|
|
