Keyrings

Hefty can store your API keys, tokens, and other sensitive values in your operating system's native credential manager instead of encrypted files on disk. On desktop installs this is the default and works automatically in most cases.

How It Works

At startup, Hefty probes your OS keyring with a quick write-read-delete round trip. If the probe succeeds, the keyring becomes the active secret store. If it fails — or if auto-detection decides keyrings aren't appropriate — Hefty falls back to AES-256-GCM encrypted files, so nothing breaks.

The resolution order is:

Keyring disabled in configuration → encrypted file store.
Auto-detect is on and a container environment (Docker / Kubernetes) is detected → encrypted file store.
OS keyring probe succeeds → keyring backend.
Fallback → encrypted file store.

OS Support

macOS Keychain Access

Uses the built-in security CLI. Works out of the box — no extra packages needed.

Linux GNOME Keyring / KDE Wallet

Requires secret-tool (part of libsecret-tools on Debian/Ubuntu, libsecret on Fedora). A running keyring daemon (gnome-keyring, kwallet) must be unlocked.

Windows Credential Manager

Uses cmdkey and PowerShell. Available on all modern Windows versions.

Configuration

Keyring settings live under the hefty.secrets block in your application.conf file. You'll find this file inside your data directory (default ~/.hefty).

Default Configuration

hefty {
  secrets {
    keyring {
      enabled = true
      auto-detect = true
      service-name = "hefty"
    }
    encryption-passphrase = ""
  }
}

Settings Reference

Setting	Default	Description
`enabled`	`true`	Master switch for keyring integration. Set to `false` to always use the encrypted file store.
`auto-detect`	`true`	When `true`, Hefty automatically skips the keyring inside containers (Docker, Kubernetes) and falls back gracefully if the keyring probe fails. Set to `false` if you want Hefty to attempt the keyring unconditionally and log a warning on failure.
`service-name`	`"hefty"`	The service name used to namespace entries in the OS keyring. Change this if you run multiple Hefty instances on the same machine and want their secrets kept separate.
`encryption-passphrase`	`""`	Passphrase for the encrypted file fallback store. When empty, Hefty derives a machine-local key automatically. Only relevant when the keyring is not used.

Common Scenarios

Disable the keyring entirely

If you prefer secrets stored as encrypted files on disk — for example, to make backups easier — set enabled = false:

hefty.secrets.keyring {
  enabled = false
}

Linux: install the keyring tools

On Debian and Ubuntu, install the secret-tool binary:

sudo apt install libsecret-tools

On Fedora:

sudo dnf install libsecret

Make sure a keyring daemon is running and unlocked. On headless servers without a desktop session, the keyring is generally unavailable, so Hefty will auto-detect and fall back to file storage.

Multiple instances with separate secrets

If you run more than one Hefty instance on the same machine (e.g. production and staging), give each a unique service-name so their secrets don't collide:

hefty.secrets.keyring {
  service-name = "hefty-bot"
}

Force keyring in a container

By default, Hefty skips the keyring when it detects a container environment. If your container has a keyring available (e.g. a sidecar agent or mounted credential store), disable auto-detection so Hefty attempts the probe regardless:

hefty.secrets.keyring {
  enabled = true
  auto-detect = false
}

Warning

When auto-detect is false, a probe failure is logged as a warning rather than an info message. The fallback to the file store still works.

Where Secrets Live

When the keyring is active, secrets are stored as individual entries in the OS credential manager. Each entry is namespaced by a hash of the user's public key, so different Hefty users on the same machine get separate secret namespaces. Entries appear under the service name hefty (or your custom service-name).

When using the encrypted file fallback, secrets are stored in .enc files inside the data directory (default ~/.hefty/secrets/).

Tip

You can check which backend is active by looking at Hefty's system logs at startup. Look for "Secret store backend: OS keyring" or "Secret store backend: encrypted file store".