Keyring Storage

Clawdius can securely store API keys in your operating system's native keyring, keeping them out of config files and environment variables.

Overview

The keyring feature uses the keyring crate to interface with platform-specific secret storage:

Enabling Keyring

The keyring feature must be enabled at compile time:

cargo install clawdius --features keyring

Or when building from source:

cargo build --features keyring

CLI Commands

Store an API Key

clawdius auth set anthropic
# Prompts securely for the key (input is hidden)

Retrieve a Stored Key

clawdius auth get anthropic
# Shows first 8 characters: sk-ant-a...

Delete a Stored Key

clawdius auth delete anthropic

Supported Providers

API Key Priority

When Clawdius resolves an API key, it checks sources in order:

1. Environment variable (e.g., ANTHROPIC_API_KEY)
2. System keyring (via clawdius auth set)
3. Config file api_key field (least secure)

If a key is found in an earlier source, later sources are not checked.

Programmatic API

#![allow(unused)]
fn main() {
use clawdius_core::config::KeyringStorage;

let storage = KeyringStorage::global();

// Store
storage.set_api_key("anthropic", "sk-ant-...")?;

// Retrieve
if let Some(key) = storage.get_api_key("anthropic")? {
    println!("Key found: {}***", &key[..8]);
}

// Delete
storage.delete_api_key("anthropic")?;
}

The KeyringStorage::global() method returns a lazily-initialized singleton, so you can call it from anywhere without managing lifetimes.

Security Notes

• Keys are stored in the OS keyring, which is encrypted at rest
• Keys are never written to log files or traces
• Keys are never exposed to sandboxed processes or WASM modules
• The clawdius auth get command masks the key, showing only the prefix

Troubleshooting

"Failed to access keyring"

On Linux, ensure a secret service is running:

# GNOME
gnome-keyring-daemon --start

# KDE
# Wallet should auto-start; check kwalletmanager5

On headless Linux servers without a desktop environment, you may need:

# Install and configure gnome-keyring
sudo apt install gnome-keyring

Feature not available

Ensure the keyring feature is compiled in:

clawdius auth set anthropic
# If this fails with "unknown command", rebuild with --features keyring