Configuration
Data directory
Section titled “Data directory”All persistent state lives under one directory:
| Source | Path |
|---|---|
| Default | ~/.keyledger/ |
| Override | $KEYLEDGER_HOME environment variable |
The directory contains:
| File / Folder | Purpose |
|---|---|
keyledger.db | SQLite database — provider config, encrypted credentials, snapshots |
snapshots/ | JSON snapshot files written by dump and watch |
debug.log | Error log written when provider errors occur |
Settings
Section titled “Settings”Settings are edited via the TUI (g key) or read-only from the database. There is no hand-editable config file — all values are stored in SQLite.
| Setting | Default | Description |
|---|---|---|
snapshot_dir | ~/.keyledger/snapshots | Directory where JSON snapshot files are written |
timeout | 30 (seconds) | Per-provider API request timeout |
parallel | 4 | Maximum concurrent provider queries |
max_key_age_days | 90 | Keys older than this get a warning risk score |
max_idle_days | 30 | Keys unused for longer than this get a warning risk score |
critical_age_days | 365 | Keys older than this get a critical risk score |
Risk scoring thresholds
Section titled “Risk scoring thresholds”| Risk | Condition |
|---|---|
| ok | Age ≤ 90 days, used recently |
| warning | Age > 90 days, OR idle > 30 days, OR active and never used (after 7-day grace period) |
| critical | Age > 365 days, OR active and never used beyond 365 days |
Provider configuration
Section titled “Provider configuration”Each provider stores two kinds of data:
- Credentials — stored encrypted in the SQLite database
- Config fields — provider-specific settings (e.g. project lists, boolean toggles) stored as JSON in the database
Both are managed through the Providers screen in the TUI (p key).
Credential storage
Section titled “Credential storage”Credentials are stored in the enc_credentials table inside keyledger.db, encrypted with AES-256-GCM using a key derived from a password you set on first use (scrypt, N=131072). The store must be unlocked with your password at the start of each session before KeyLedger can read credentials.
Environment variables
Section titled “Environment variables”The following environment variables auto-populate credentials:
| Variable | Provider | Field |
|---|---|---|
OPENAI_API_KEY or OPENAI_ADMIN_KEY | OpenAI | admin_key |
ANTHROPIC_API_KEY or ANTHROPIC_ADMIN_KEY | Anthropic | admin_key |
GOOGLE_APPLICATION_CREDENTIALS or GCP_SERVICE_ACCOUNT_JSON | service_account_json | |
AWS_ACCESS_KEY_ID | AWS | access_key_id |
AWS_SECRET_ACCESS_KEY | AWS | secret_access_key |
AWS_SSO_PROFILE | AWS | sso_creds |
When an environment variable is detected, it appears as an auto-discovery candidate in the TUI credential picker. You can select it to store it permanently in the encrypted store, or ignore it.