feat: disabling keyring using --no-keyring (#308)

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

@@ -141,3 +141,27 @@ koharu.exe --debug
 ```
 
 On Windows, debug and headless runs also influence how Koharu attaches to or creates a console window.
+
+## Running without keyring
+
+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.
+
+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.

docs/en-US/reference/cli.md

@@ -31,6 +31,7 @@ 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
@@ -41,6 +42,7 @@ Some flags change more than just 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:
 
@@ -85,3 +87,9 @@ Start with explicit debug logging:
 ```bash
 koharu --debug
 ```
+
+Use without keyring
+
+```bash
+KOHARU_OPENAI_API_KEY=[key] koharu --no-keyring
+```

koharu-llm/src/providers/mod.rs

@@ -1,6 +1,7 @@
 use std::future::Future;
 use std::pin::Pin;
 use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
 
 use anyhow::Context;
 use keyring::Entry;
@@ -16,12 +17,33 @@ pub mod openai_compatible;
 
 const API_KEY_SERVICE: &str = "koharu";
 
+static NO_KEYRING: AtomicBool = AtomicBool::new(false);
+
+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)),
@@ -31,6 +53,16 @@ pub fn get_saved_api_key(provider: &str) -> anyhow::Result<Option<String>> {
 }
 
 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() {

koharu/src/app.rs

@@ -51,6 +51,12 @@ struct Cli {
         default_value_t = false
     )]
     headless: bool,
+    #[arg(
+        long,
+        help = "Disable keyring and read API keys from environment variables instead (e.g. KOHARU_OPENAI_API_KEY)",
+        default_value_t = false
+    )]
+    no_keyring: bool,
     #[arg(
         long,
         help = "Enable debug mode with console output",
@@ -356,9 +362,14 @@ pub async fn run() -> Result<()> {
         cpu,
         port,
         headless,
+        no_keyring,
         debug,
     } = Cli::parse();
 
+    if no_keyring {
+        koharu_llm::providers::disable_keyring();
+    }
+
     initialize(headless, debug)?;
 
     if download {