fix: keyring on Linux

Cargo.lock

@@ -1794,27 +1794,6 @@ version = "2.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d7a1e2f27636f116493b8b860f5546edb47c8d8f8ea73e1d2a20be88e28d1fea"
 
-[[package]]
-name = "dbus"
-version = "0.9.10"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "21b3aa68d7e7abee336255bd7248ea965cc393f3e70411135a6f6a4b651345d4"
-dependencies = [
- "libc",
- "libdbus-sys",
- "windows-sys 0.59.0",
-]
-
-[[package]]
-name = "dbus-secret-service"
-version = "4.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "708b509edf7889e53d7efb0ffadd994cc6c2345ccb62f55cfd6b0682165e4fa6"
-dependencies = [
- "dbus",
- "zeroize",
-]
-
 [[package]]
 name = "debugid"
 version = "0.8.0"
@@ -4476,7 +4455,6 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eebcc3aff044e5944a8fbaf69eb277d11986064cba30c468730e8b9909fb551c"
 dependencies = [
  "byteorder",
- "dbus-secret-service",
  "log",
  "security-framework 2.11.1",
  "security-framework 3.7.0",
@@ -4678,7 +4656,6 @@ dependencies = [
  "futures",
  "image",
  "imageproc",
- "keyring",
  "koharu-runtime",
  "libloading 0.8.9",
  "minijinja",
@@ -4860,15 +4837,6 @@ version = "0.2.185"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
 
-[[package]]
-name = "libdbus-sys"
-version = "0.2.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "328c4789d42200f1eeec05bd86c9c13c7f091d2ba9a6ea35acdf51f31bc0f043"
-dependencies = [
- "pkg-config",
-]
-
 [[package]]
 name = "libfuzzer-sys"
 version = "0.4.12"
@@ -11229,20 +11197,6 @@ name = "zeroize"
 version = "1.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
-dependencies = [
- "zeroize_derive",
-]
-
-[[package]]
-name = "zeroize_derive"
-version = "1.4.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85a5b4158499876c763cb03bc4e49185d3cccbabb15b33c627f7884f43db852e"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.117",
-]
 
 [[package]]
 name = "zerotrie"

Dockerfile

@@ -6,15 +6,15 @@ ARG DEBIAN_FRONTEND=noninteractive
 
 RUN apt-get update \
     && apt-get install -y --no-install-recommends \
-        ca-certificates \
-        curl \
-        fonts-noto-cjk \
-        libayatana-appindicator3-1 \
-        libgomp1 \
-        librsvg2-2 \
-        libssl3 \
-        libwebkit2gtk-4.1-0 \
-        libxdo3 \
+    ca-certificates \
+    curl \
+    fonts-noto-cjk \
+    libayatana-appindicator3-1 \
+    libgomp1 \
+    librsvg2-2 \
+    libssl3 \
+    libwebkit2gtk-4.1-0 \
+    libxdo3 \
     && curl -fL "https://github.com/mayocream/koharu/releases/latest/download/koharu_linux_x64" -o /usr/local/bin/koharu \
     && chmod 0755 /usr/local/bin/koharu \
     && apt-get purge -y --auto-remove curl \
@@ -29,4 +29,4 @@ WORKDIR /home/koharu
 VOLUME ["/home/koharu/.local/share/Koharu"]
 EXPOSE 4000
 
-CMD ["/usr/local/bin/koharu", "--headless", "--no-keyring", "--host", "0.0.0.0", "--port", "4000"]
+CMD ["/usr/local/bin/koharu", "--headless", "--host", "0.0.0.0", "--port", "4000"]

docs/en-US/how-to/run-gui-headless-and-mcp.md

@@ -142,26 +142,8 @@ koharu.exe --debug
 
 On Windows, debug and headless runs also influence how Koharu attaches to or creates a console window.
 
-## Running without keyring
+## Credential storage
 
-By default, Koharu stores API keys in the system keyring. In container or CI environments where there is no persistent keyring, you can pass `--no-keyring` to skip it and supply API keys through environment variables instead.
+By default, Koharu stores API keys outside `config.toml`. macOS and Windows use the system keyring. Linux uses Koharu's local filesystem credential store under the app data directory with owner-only file permissions; this Linux store relies on filesystem permissions rather than OS-level encryption.
 
-The variable name for each provider follows the pattern `KOHARU_<PROVIDER>_API_KEY`:
-
-| Provider | Environment variable |
-| --- | --- |
-| OpenAI | `KOHARU_OPENAI_API_KEY` |
-| Gemini | `KOHARU_GEMINI_API_KEY` |
-| Claude | `KOHARU_CLAUDE_API_KEY` |
-| DeepSeek | `KOHARU_DEEPSEEK_API_KEY` |
-| OpenAI-compatible | `KOHARU_OPENAI_COMPATIBLE_API_KEY` |
-
-Hyphens in provider IDs are converted to underscores in the variable name.
-
-Example for a headless container run:
-
-```bash
-KOHARU_OPENAI_API_KEY=sk-... koharu --port 9999 --headless --no-keyring
-```
-
-When `--no-keyring` is active, calls to save an API key through the UI or HTTP API are ignored.
+Headless and container runs use the same credential storage behavior as the desktop app. For containers, keep the app data directory on a persistent volume if you want saved API keys to survive container replacement.

docs/en-US/reference/cli.md

@@ -31,7 +31,6 @@ koharu.exe [OPTIONS]
 | `--cpu` | Force CPU mode even when a GPU is available |
 | `-p`, `--port <PORT>` | Bind the local HTTP server to a specific `127.0.0.1` port instead of a random one |
 | `--headless` | Run without starting the desktop GUI |
-| `--no-keyring` | Run without keyring and use environment variables instead |
 | `--debug` | Enable debug-oriented console output |
 
 ## Behavior notes
@@ -42,7 +41,6 @@ Some flags affect more than startup appearance:
 - with `--headless`, Koharu skips the Tauri window but still serves the Web UI and API
 - with `--download`, Koharu exits after dependency prefetch and does not stay running
 - with `--cpu`, both the vision stack and local LLM path avoid GPU acceleration
-- with `--no-keyring`, Koharu skips all keyring operations, API keys must be set via environment variables
 
 When a fixed port is set, the main local endpoints are:
 
@@ -87,9 +85,3 @@ Start with explicit debug logging:
 ```bash
 koharu --debug
 ```
-
-Use without keyring:
-
-```bash
-KOHARU_OPENAI_API_KEY=[key] koharu --no-keyring
-```

docs/en-US/reference/settings.md

@@ -51,14 +51,18 @@ The `API Keys` tab currently covers these built-in providers:
 
 Current behavior:
 
-- provider API keys are stored through the system keyring rather than plain text in `config.toml`
+- 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`
 - the app discovers models dynamically for `OpenAI Compatible` by querying the configured endpoint
-- clearing a key removes it from the keyring
+- 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.
+
 ## Runtime
 
 The `Runtime` tab groups restart-required settings that affect the shared local runtime:
@@ -93,7 +97,7 @@ In packaged app mode, the version check compares the local app version against t
 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 through the system keyring
+- 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.

docs/ja-JP/how-to/run-gui-headless-and-mcp.md

@@ -141,3 +141,9 @@ koharu.exe --debug
 ```
 
 Windows では、debug 実行と headless 実行の組み合わせにより、Koharu がコンソールウィンドウにアタッチするか、新しく作るかが変わります。
+
+## 認証情報ストレージ
+
+Koharu は API キーを `config.toml` の外に保存します。macOS と Windows ではシステム keyring を使います。Linux ではアプリデータディレクトリ配下の Koharu ローカルファイルシステム認証情報ストアを使い、所有ユーザーのみが読める権限を設定します。この Linux ストアは OS レベルの暗号化ではなく、ファイルシステム権限に依存します。
+
+Headless 実行やコンテナ実行でも、デスクトップアプリと同じ認証情報ストレージを使います。コンテナを置き換えた後も保存済み API キーを維持したい場合は、アプリデータディレクトリを永続 volume に置いてください。

docs/ja-JP/reference/settings.md

@@ -51,14 +51,18 @@ title: 設定リファレンス
 
 現在の挙動:
 
-- provider の API キーは `config.toml` ではなくシステム keyring に保存されます
+- provider の API キーは `config.toml` には書き込まれません
+- macOS と Windows では、provider の API キーはシステム keyring に保存されます
+- Linux では、provider の API キーはアプリデータディレクトリ配下の Koharu ローカルファイルシステム認証情報ストアに保存され、所有ユーザーのみが読める権限が設定されます
 - provider の `Base URL` は共有アプリ設定に保存されます
 - `OpenAI Compatible` ではカスタム `Base URL` が必須です
 - `OpenAI Compatible` のモデル一覧は設定済みエンドポイントへの問い合わせで動的取得されます
-- キーをクリアすると keyring から削除されます
+- キーをクリアすると認証情報ストレージから削除されます
 
 API レスポンスでは保存済みキーは生値ではなく、マスク済みの値として返されます。
 
+Linux のファイルシステム認証情報ストアは、OS レベルの暗号化ではなくローカルファイルシステム権限に依存します。
+
 ## Runtime
 
 `Runtime` タブでは、共有ローカルランタイムに影響する再起動必須の設定をまとめています。
@@ -93,7 +97,7 @@ API レスポンスでは保存済みキーは生値ではなく、マスク済
 現在の設定保存は複数の層に分かれています。
 
 - `config.toml` には `data`、`http`、`pipeline`、provider の `baseUrl` など共有設定が保存されます
-- provider API キーはシステム keyring に保存されます
+- provider API キーは、上記のプラットフォーム認証情報ストレージを通じて `config.toml` とは別に保存されます
 - テーマ、言語、描画フォントはフロントエンドの preferences 層に保存されます
 
 つまり、フロントエンドの preferences を消しても、保存済みの provider API キーや共有ランタイム設定までは消えません。

docs/pt-BR/how-to/run-gui-headless-and-mcp.md

@@ -142,26 +142,8 @@ koharu.exe --debug
 
 No Windows, execuções de debug e headless também influenciam como o Koharu anexa ou cria uma janela de console.
 
-## Rodando sem keyring
+## Armazenamento de credenciais
 
-Por padrão, o Koharu armazena API keys no keyring do sistema. Em ambientes de container ou CI onde não existe um keyring persistente, você pode passar `--no-keyring` para pular essa etapa e fornecer as API keys por variáveis de ambiente.
+Por padrão, o Koharu armazena API keys fora de `config.toml`. macOS e Windows usam o keyring do sistema. Linux usa o armazenamento local de credenciais do Koharu no diretório de dados do app com permissões somente para o usuário dono; esse armazenamento no Linux depende das permissões do filesystem em vez de criptografia em nível de sistema operacional.
 
-O nome da variável para cada provider segue o padrão `KOHARU_<PROVIDER>_API_KEY`:
-
-| Provider | Variável de ambiente |
-| --- | --- |
-| OpenAI | `KOHARU_OPENAI_API_KEY` |
-| Gemini | `KOHARU_GEMINI_API_KEY` |
-| Claude | `KOHARU_CLAUDE_API_KEY` |
-| DeepSeek | `KOHARU_DEEPSEEK_API_KEY` |
-| OpenAI-compatible | `KOHARU_OPENAI_COMPATIBLE_API_KEY` |
-
-Hífens nos IDs de provider são convertidos em underscores no nome da variável.
-
-Exemplo para uma execução headless em container:
-
-```bash
-KOHARU_OPENAI_API_KEY=sk-... koharu --port 9999 --headless --no-keyring
-```
-
-Quando `--no-keyring` está ativo, chamadas para salvar uma API key pela UI ou pela HTTP API são ignoradas.
+Execuções headless e em container usam o mesmo comportamento de armazenamento de credenciais do app desktop. Em containers, mantenha o diretório de dados do app em um volume persistente se quiser que as API keys salvas sobrevivam à substituição do container.

docs/pt-BR/reference/cli.md

@@ -31,7 +31,6 @@ koharu.exe [OPTIONS]
 | `--cpu` | Força o modo CPU mesmo quando uma GPU está disponível |
 | `-p`, `--port <PORT>` | Vincula o servidor HTTP local a uma porta `127.0.0.1` específica em vez de uma aleatória |
 | `--headless` | Executa sem iniciar a GUI desktop |
-| `--no-keyring` | Executa sem keyring e usa variáveis de ambiente no lugar |
 | `--debug` | Habilita saída de console orientada a debug |
 
 ## Notas de comportamento
@@ -42,7 +41,6 @@ Algumas flags afetam mais do que apenas a aparência inicial:
 - com `--headless`, o Koharu pula a janela do Tauri mas ainda serve a Web UI e a API
 - com `--download`, o Koharu encerra após o prefetch de dependências e não permanece em execução
 - com `--cpu`, tanto a stack de visão quanto o caminho do LLM local evitam aceleração por GPU
-- com `--no-keyring`, o Koharu pula todas as operações de keyring; as chaves de API devem ser definidas por variáveis de ambiente
 
 Quando uma porta fixa está definida, os principais endpoints locais são:
 
@@ -87,9 +85,3 @@ Iniciar com logging explícito de debug:
 ```bash
 koharu --debug
 ```
-
-Uso sem keyring:
-
-```bash
-KOHARU_OPENAI_API_KEY=[key] koharu --no-keyring
-```

docs/pt-BR/reference/settings.md

@@ -51,14 +51,18 @@ A aba `API Keys` cobre atualmente estes provedores embutidos:
 
 Comportamento atual:
 
-- as chaves de API dos provedores são armazenadas via keyring do sistema em vez de texto plano em `config.toml`
+- as chaves de API dos provedores não são escritas em `config.toml`
+- no macOS e no Windows, as chaves de API dos provedores são armazenadas pelo keyring do sistema
+- no Linux, as chaves de API dos provedores são armazenadas no armazenamento local de credenciais do Koharu sob o diretório de dados do app com permissões somente para o usuário dono
 - as base URLs dos provedores são armazenadas na config do app
 - `OpenAI Compatible` requer uma `Base URL` customizada
 - o app descobre modelos dinamicamente para `OpenAI Compatible` consultando o endpoint configurado
-- limpar uma chave a remove do keyring
+- limpar uma chave a remove do armazenamento de credenciais
 
 O response da API intencionalmente redacta as chaves salvas em vez de retornar o segredo bruto.
 
+O armazenamento local de credenciais no Linux depende das permissões do filesystem em vez de criptografia em nível de sistema operacional.
+
 ## Runtime
 
 A aba `Runtime` agrupa configurações que exigem reinicialização e afetam o runtime local compartilhado:
@@ -93,7 +97,7 @@ No modo de app empacotado, a verificação de versão compara a versão local do
 O comportamento atual das configurações é dividido em camadas de armazenamento:
 
 - `config.toml` armazena a config compartilhada do app, como `data`, `http`, `pipeline` e `baseUrl` dos provedores
-- as chaves de API dos provedores são armazenadas via keyring do sistema
+- as chaves de API dos provedores são armazenadas separadamente de `config.toml` pelo armazenamento de credenciais da plataforma descrito acima
 - as preferências de tema, idioma e fonte de renderização são armazenadas na camada de preferências do frontend
 
 Ou seja, limpar as preferências do frontend não é o mesmo que limpar as chaves de API salvas dos provedores ou a config compartilhada de runtime.

docs/zh-CN/how-to/run-gui-headless-and-mcp.md

@@ -141,3 +141,9 @@ koharu.exe --debug
 ```
 
 在 Windows 上，debug 与 headless 运行方式还会影响 Koharu 如何附加到现有控制台，或创建新的控制台窗口。
+
+## 凭据存储
+
+Koharu 会把 API key 存储在 `config.toml` 之外。macOS 和 Windows 使用系统 keyring。Linux 使用应用数据目录下的 Koharu 本地文件系统凭据存储，并设置仅所有者可访问的文件权限；这个 Linux 存储依赖文件系统权限，而不是操作系统级加密。
+
+Headless 和容器运行使用与桌面应用相同的凭据存储行为。如果你希望保存的 API key 在容器替换后继续存在，请把应用数据目录放在持久化 volume 上。

docs/zh-CN/reference/settings.md

@@ -51,14 +51,18 @@ title: 设置参考
 
 当前行为：
 
-- 提供方 API key 存储在系统 keyring 中，而不是明文写入 `config.toml`
+- 提供方 API key 不会写入 `config.toml`
+- 在 macOS 和 Windows 上，提供方 API key 存储在系统 keyring 中
+- 在 Linux 上，提供方 API key 存储在应用数据目录下的 Koharu 本地文件系统凭据存储中，并使用仅所有者可访问的文件权限
 - 提供方的 `Base URL` 保存在共享应用配置中
 - `OpenAI Compatible` 需要自定义 `Base URL`
 - `OpenAI Compatible` 的模型列表会通过查询已配置端点动态发现
-- 清除密钥会把它从 keyring 中删除
+- 清除密钥会把它从凭据存储中删除
 
 API 响应不会返回原始密钥，而是返回已遮罩的值。
 
+Linux 文件系统凭据存储依赖本地文件系统权限，而不是操作系统级加密。
+
 ## Runtime
 
 `Runtime` 标签页集中放置会影响共享本地运行时、且需要重启后生效的设置：
@@ -93,7 +97,7 @@ API 响应不会返回原始密钥，而是返回已遮罩的值。
 当前设置数据分布在多个存储层中：
 
 - `config.toml` 保存 `data`、`http`、`pipeline` 以及提供方 `baseUrl` 等共享配置
-- 提供方 API key 存储在系统 keyring 中
+- 提供方 API key 通过上文所述的平台凭据存储与 `config.toml` 分开保存
 - 主题、语言和渲染字体存储在前端 preferences 层中
 
 因此，清除前端 preferences 并不等于清除已保存的提供方 API key 或共享运行时配置。

koharu-app/src/config.rs

@@ -113,9 +113,8 @@ pub struct ProviderConfig {
     pub id: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub base_url: Option<String>,
-    /// Populated from the keyring on `load()`, never written to config.toml.
+    /// Populated from credential storage on `load()`, never written to config.toml.
     /// Serializes as `"[REDACTED]"` in API responses.
-    /// Populated from keyring on `load()`. Serializes as `"[REDACTED]"`.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     #[schema(value_type = Option<String>)]
     pub api_key: Option<RedactedSecret>,
@@ -163,7 +162,7 @@ pub fn load() -> Result<AppConfig> {
         save(&config)?;
     }
 
-    // Populate api_key from the keyring for every known provider.
+    // Populate api_key from credential storage for every known provider.
     for provider in &mut config.providers {
         if let Ok(Some(key)) = get_saved_api_key(&provider.id)
             && !key.trim().is_empty()
@@ -348,12 +347,12 @@ fn validate_engine_name(
 }
 
 // ---------------------------------------------------------------------------
-// Secret (keyring) handling
+// Secret handling
 // ---------------------------------------------------------------------------
 
-/// Sync api_key fields to the keyring.
-/// - `Some(RedactedSecret)` with value != "[REDACTED]" → save to keyring
-/// - `None` → clear from keyring
+/// Sync api_key fields to credential storage.
+/// - `Some(RedactedSecret)` with value != "[REDACTED]" → save to credential storage
+/// - `None` → clear from credential storage
 /// - `Some(RedactedSecret)` with value == "[REDACTED]" → unchanged
 pub fn sync_secrets(config: &AppConfig) -> Result<()> {
     for provider in &config.providers {

koharu-llm/Cargo.toml

@@ -62,9 +62,6 @@ keyring = { workspace = true, features = ["windows-native"] }
 [target.'cfg(target_os = "macos")'.dependencies]
 keyring = { workspace = true, features = ["apple-native"] }
 
-[target.'cfg(target_os = "linux")'.dependencies]
-keyring = { workspace = true, features = ["sync-secret-service"] }
-
 [build-dependencies]
 anyhow = { workspace = true }
 bindgen = "0.72.1"

koharu-llm/src/providers/credentials.rs

@@ -0,0 +1,247 @@
+use std::sync::Once;
+
+use keyring::Entry;
+
+const API_KEY_SERVICE: &str = "koharu";
+
+static INIT_CREDENTIAL_STORE: Once = Once::new();
+
+pub fn get_saved_api_key(provider: &str) -> anyhow::Result<Option<String>> {
+    let entry = provider_entry(provider)?;
+    match entry.get_password() {
+        Ok(value) => Ok(Some(value)),
+        Err(keyring::Error::NoEntry) => Ok(None),
+        Err(err) => Err(err.into()),
+    }
+}
+
+pub fn set_saved_api_key(provider: &str, api_key: &str) -> anyhow::Result<()> {
+    let entry = provider_entry(provider)?;
+    if api_key.trim().is_empty() {
+        return match entry.delete_credential() {
+            Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
+            Err(err) => Err(err.into()),
+        };
+    }
+
+    entry.set_password(api_key)?;
+    Ok(())
+}
+
+fn provider_entry(provider: &str) -> anyhow::Result<Entry> {
+    INIT_CREDENTIAL_STORE.call_once(configure_platform_store);
+
+    let username = format!("llm_provider_api_key_{provider}");
+    Ok(Entry::new(API_KEY_SERVICE, &username)?)
+}
+
+#[cfg(target_os = "linux")]
+fn configure_platform_store() {
+    let root = koharu_runtime::default_app_data_root()
+        .as_std_path()
+        .join("secrets")
+        .join("keyring");
+    keyring::set_default_credential_builder(Box::new(filesystem::Builder::new(root)));
+}
+
+#[cfg(not(target_os = "linux"))]
+fn configure_platform_store() {}
+
+#[cfg(any(target_os = "linux", test))]
+mod filesystem {
+    use std::fmt::Write as _;
+    use std::fs;
+    use std::path::{Path, PathBuf};
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    use keyring::credential::{Credential, CredentialApi, CredentialBuilderApi};
+    use keyring::{Error, Result};
+
+    static TEMP_ID: AtomicU64 = AtomicU64::new(0);
+
+    #[derive(Debug)]
+    pub(super) struct Builder {
+        root: PathBuf,
+    }
+
+    impl Builder {
+        pub(super) fn new(root: impl Into<PathBuf>) -> Self {
+            Self { root: root.into() }
+        }
+    }
+
+    impl CredentialBuilderApi for Builder {
+        fn build(
+            &self,
+            target: Option<&str>,
+            service: &str,
+            user: &str,
+        ) -> Result<Box<Credential>> {
+            Ok(Box::new(FileCredential {
+                root: self.root.clone(),
+                name: file_name(target, service, user),
+            }))
+        }
+
+        fn as_any(&self) -> &dyn std::any::Any {
+            self
+        }
+    }
+
+    #[derive(Debug)]
+    struct FileCredential {
+        root: PathBuf,
+        name: String,
+    }
+
+    impl FileCredential {
+        fn path(&self) -> PathBuf {
+            self.root.join(&self.name)
+        }
+
+        fn temp_path(&self) -> PathBuf {
+            self.root.join(format!(
+                "{}.tmp-{}-{}",
+                self.name,
+                std::process::id(),
+                TEMP_ID.fetch_add(1, Ordering::Relaxed)
+            ))
+        }
+    }
+
+    impl CredentialApi for FileCredential {
+        fn set_secret(&self, secret: &[u8]) -> Result<()> {
+            fs::create_dir_all(&self.root).map_err(storage_error)?;
+            set_mode(&self.root, 0o700)?;
+
+            let path = self.path();
+            let temp_path = self.temp_path();
+            fs::write(&temp_path, secret).map_err(storage_error)?;
+            set_mode(&temp_path, 0o600)?;
+
+            fs::rename(&temp_path, &path).or_else(|err| {
+                let _ = fs::remove_file(&temp_path);
+                Err(storage_error(err))
+            })?;
+            set_mode(&path, 0o600)
+        }
+
+        fn get_secret(&self) -> Result<Vec<u8>> {
+            fs::read(self.path()).map_err(|err| match err.kind() {
+                std::io::ErrorKind::NotFound => Error::NoEntry,
+                _ => storage_error(err),
+            })
+        }
+
+        fn delete_credential(&self) -> Result<()> {
+            fs::remove_file(self.path()).map_err(|err| match err.kind() {
+                std::io::ErrorKind::NotFound => Error::NoEntry,
+                _ => storage_error(err),
+            })
+        }
+
+        fn as_any(&self) -> &dyn std::any::Any {
+            self
+        }
+    }
+
+    #[cfg(unix)]
+    fn set_mode(path: &Path, mode: u32) -> Result<()> {
+        use std::os::unix::fs::PermissionsExt;
+
+        fs::set_permissions(path, fs::Permissions::from_mode(mode)).map_err(storage_error)
+    }
+
+    #[cfg(not(unix))]
+    fn set_mode(_path: &Path, _mode: u32) -> Result<()> {
+        Ok(())
+    }
+
+    fn storage_error(err: std::io::Error) -> Error {
+        Error::NoStorageAccess(Box::new(err))
+    }
+
+    fn file_name(target: Option<&str>, service: &str, user: &str) -> String {
+        let target = target
+            .map(|value| format!("some-{}", encode(value)))
+            .unwrap_or_else(|| "none".to_string());
+        format!(
+            "v1-target-{target}--service-{}--user-{}.secret",
+            encode(service),
+            encode(user)
+        )
+    }
+
+    fn encode(value: &str) -> String {
+        let mut encoded = String::with_capacity(value.len());
+        for byte in value.bytes() {
+            match byte {
+                b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' => {
+                    encoded.push(byte as char);
+                }
+                _ => {
+                    let _ = write!(&mut encoded, "%{byte:02X}");
+                }
+            }
+        }
+        encoded
+    }
+
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+
+        #[test]
+        fn round_trips_secret_across_credentials() {
+            let dir = tempfile::tempdir().unwrap();
+            let builder = Builder::new(dir.path());
+
+            let first = builder
+                .build(None, "koharu", "llm_provider_api_key_openai")
+                .unwrap();
+            assert!(matches!(first.get_secret(), Err(Error::NoEntry)));
+            first.set_secret(b"sk-test").unwrap();
+
+            let second = builder
+                .build(None, "koharu", "llm_provider_api_key_openai")
+                .unwrap();
+            assert_eq!(second.get_secret().unwrap(), b"sk-test");
+            second.delete_credential().unwrap();
+            assert!(matches!(second.get_secret(), Err(Error::NoEntry)));
+        }
+
+        #[test]
+        fn file_names_escape_path_separators() {
+            let name = file_name(Some("target/value"), "service\\name", "user name");
+
+            assert!(name.contains("target%2Fvalue"));
+            assert!(name.contains("service%5Cname"));
+            assert!(name.contains("user%20name"));
+            assert!(!name.contains('/'));
+            assert!(!name.contains('\\'));
+        }
+
+        #[cfg(unix)]
+        #[test]
+        fn writes_private_permissions() {
+            use std::os::unix::fs::PermissionsExt;
+
+            let dir = tempfile::tempdir().unwrap();
+            let builder = Builder::new(dir.path());
+            let credential = builder
+                .build(None, "koharu", "llm_provider_api_key_openai")
+                .unwrap();
+
+            credential.set_secret(b"sk-test").unwrap();
+
+            let dir_mode = fs::metadata(dir.path()).unwrap().permissions().mode() & 0o777;
+            let file_path =
+                dir.path()
+                    .join(file_name(None, "koharu", "llm_provider_api_key_openai"));
+            let file_mode = fs::metadata(file_path).unwrap().permissions().mode() & 0o777;
+
+            assert_eq!(dir_mode, 0o700);
+            assert_eq!(file_mode, 0o600);
+        }
+    }
+}

koharu-llm/src/providers/mod.rs

@@ -1,10 +1,8 @@
 use std::future::Future;
 use std::pin::Pin;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, Ordering};
 
 use anyhow::Context;
-use keyring::Entry;
 use reqwest_middleware::ClientWithMiddleware;
 
 use crate::prompt::{BLOCK_TAG_INSTRUCTIONS, system_prompt};
@@ -21,6 +19,7 @@ pub(crate) fn resolve_system_prompt(custom: Option<&str>, target_language: Langu
 pub mod caiyun;
 mod chat_completions;
 pub mod claude;
+mod credentials;
 pub mod deepl;
 pub mod deepseek;
 pub mod gemini;
@@ -28,10 +27,7 @@ pub mod google_translate;
 pub mod openai;
 pub mod openai_compatible;
 
-const API_KEY_SERVICE: &str = "koharu";
-pub const OPENAI_COMPATIBLE_ID: &str = "openai-compatible";
-
-static NO_KEYRING: AtomicBool = AtomicBool::new(false);
+pub use credentials::{get_saved_api_key, set_saved_api_key};
 
 #[derive(Debug, Clone, Copy)]
 pub struct ProviderModelDescriptor {
@@ -78,62 +74,6 @@ pub struct ProviderDescriptor {
     pub build: fn(ProviderConfig) -> anyhow::Result<Box<dyn AnyProvider>>,
 }
 
-pub fn disable_keyring() {
-    NO_KEYRING.store(true, Ordering::Relaxed);
-}
-
-fn env_key_var(provider: &str) -> String {
-    format!(
-        "KOHARU_{}_API_KEY",
-        provider.to_ascii_uppercase().replace('-', "_")
-    )
-}
-
-fn provider_key_entry(provider: &str) -> anyhow::Result<Entry> {
-    let username = format!("llm_provider_api_key_{provider}");
-    Ok(Entry::new(API_KEY_SERVICE, &username)?)
-}
-
-pub fn get_saved_api_key(provider: &str) -> anyhow::Result<Option<String>> {
-    if NO_KEYRING.load(Ordering::Relaxed) {
-        let var = env_key_var(provider);
-        return Ok(std::env::var(&var)
-            .ok()
-            .map(|v| v.trim().to_string())
-            .filter(|v| !v.is_empty()));
-    }
-
-    let entry = provider_key_entry(provider)?;
-    match entry.get_password() {
-        Ok(value) => Ok(Some(value)),
-        Err(keyring::Error::NoEntry) => Ok(None),
-        Err(err) => Err(err.into()),
-    }
-}
-
-pub fn set_saved_api_key(provider: &str, api_key: &str) -> anyhow::Result<()> {
-    if NO_KEYRING.load(Ordering::Relaxed) {
-        tracing::warn!(
-            provider,
-            "keyring is disabled; API key changes are not saved"
-        );
-        return Err(anyhow::anyhow!(
-            "keyring is disabled; API key cannot be saved"
-        ));
-    }
-
-    let entry = provider_key_entry(provider)?;
-    if api_key.trim().is_empty() {
-        match entry.delete_credential() {
-            Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
-            Err(err) => Err(err.into()),
-        }
-    } else {
-        entry.set_password(api_key)?;
-        Ok(())
-    }
-}
-
 pub async fn ensure_provider_success(
     provider: &str,
     response: reqwest::Response,
@@ -273,7 +213,7 @@ const PROVIDERS: &[ProviderDescriptor] = &[
         build: build_caiyun_mt_provider,
     },
     ProviderDescriptor {
-        id: OPENAI_COMPATIBLE_ID,
+        id: "openai-compatible",
         name: "OpenAI-compatible",
         requires_api_key: false,
         requires_base_url: true,
@@ -395,7 +335,7 @@ fn build_openai_compatible_provider(
 ) -> anyhow::Result<Box<dyn AnyProvider>> {
     Ok(Box::new(openai_compatible::OpenAiCompatibleProvider {
         http_client: Arc::clone(&config.http_client),
-        base_url: required_base_url(&config, OPENAI_COMPATIBLE_ID)?,
+        base_url: required_base_url(&config, "openai-compatible")?,
         api_key: config.api_key,
         temperature: config.temperature,
         max_tokens: config.max_tokens,
@@ -428,7 +368,7 @@ fn build_caiyun_mt_provider(config: ProviderConfig) -> anyhow::Result<Box<dyn An
 
 fn discover_openai_compatible_models(config: ProviderConfig) -> ProviderDiscoveryFuture {
     Box::pin(async move {
-        let base_url = required_base_url(&config, OPENAI_COMPATIBLE_ID)?;
+        let base_url = required_base_url(&config, "openai-compatible")?;
         let models = openai_compatible::list_models(
             config.http_client,
             &base_url,

koharu-ml/Cargo.toml

@@ -34,7 +34,6 @@ num_cpus = { workspace = true }
 rayon = { workspace = true }
 libloading = { workspace = true }
 minijinja = { workspace = true }
-keyring = { workspace = true }
 cudarc = { workspace = true, optional = true }
 objc2 = { workspace = true, optional = true }
 objc2-metal = { workspace = true, optional = true }
@@ -42,15 +41,6 @@ objc2-metal-performance-shaders = { workspace = true, optional = true }
 objc2-metal-performance-shaders-graph = { workspace = true, optional = true }
 objc2-foundation = { workspace = true, optional = true }
 
-[target.'cfg(windows)'.dependencies]
-keyring = { workspace = true, features = ["windows-native"] }
-
-[target.'cfg(target_os = "macos")'.dependencies]
-keyring = { workspace = true, features = ["apple-native"] }
-
-[target.'cfg(target_os = "linux")'.dependencies]
-keyring = { workspace = true, features = ["sync-secret-service"] }
-
 [features]
 cuda = [
     "candle-core/cuda",

koharu/src/app.rs

@@ -62,10 +62,6 @@ pub async fn run() -> Result<()> {
         .with(crate::tracing::TimingLayer::new())
         .init();
 
-    if cli.no_keyring {
-        koharu_llm::providers::disable_keyring();
-    }
-
     let config: AppConfig = app_config::load()?;
     let http = RuntimeHttpConfig {
         connect_timeout_secs: config.http.connect_timeout.max(1),

koharu/src/cli.rs

@@ -16,8 +16,6 @@ pub(crate) struct Cli {
     pub(crate) host: Option<String>,
     #[arg(long, help = "Run without GUI")]
     pub(crate) headless: bool,
-    #[arg(long, help = "Use env vars for API keys instead of keyring")]
-    pub(crate) no_keyring: bool,
     #[arg(long, help = "Enable debug console output")]
     pub(crate) debug: bool,
 }