KeePass provider

Resolve encrypted secrets from local .kdbx vaults — no cloud service required.

The KeePass provider gives Loom workflows access to secrets stored in standard KeePass databases. Vault credentials stay in the runtime environment; workflow YAML stores only keepass:// references. Loom resolves values at execution time, injects them into jobs, and redacts them at every output boundary.

When to use KeePass

Scenario	KeePass is a good fit	Consider an alternative
Local development and CI on self-hosted runners	Yes — vault file lives on disk, no external dependency	—
Air-gapped or offline environments	Yes — no network calls required	—
Centralized team secret management with audit logs	—	1Password (op://) offers shared vaults with audit trails
Secrets that must rotate automatically	—	Use a provider with rotation APIs

URI format

keepass://<database-alias>#<entry-path>:<field>

Component	Description	Example
database-alias	Alias mapped to a .kdbx file via runtime env vars. Can be a simple name or a path.	local, team, group/project/repo
entry-path	KeePass group/entry hierarchy using / separators. Matched by suffix, so you only need enough path segments to uniquely identify the entry.	services/loom/deploy
field	Field name on the entry.	password, token, username

Full example:

secrets:
  DATABASE_PASSWORD:
    ref: keepass://local/main#services/loom/deploy:password

How resolution works

Workflow YAML         Loom runtime              KeePass .kdbx
──────────────        ─────────────             ─────────────
ref: keepass://...  → parse alias, path, field
                    → resolve alias → env vars → open database
                    → walk entries (suffix match) → read field
                    → inject value (file or env)
                    → redact at output boundaries

Step-by-step:

1. Parse — Loom extracts database-alias, entry-path, and field from the ref URI.
2. Alias resolution — The alias is converted to an uppercase key (lowercase letters uppercased, non-alphanumeric characters replaced with _). Loom reads LOOM_KEEPASS_DB_<KEY>_PATH to locate the .kdbx file.
3. Credential indirection — LOOM_KEEPASS_DB_<KEY>_PASSWORD_ENV and LOOM_KEEPASS_DB_<KEY>_KEYFILE_ENV each point to the name of an environment variable that holds the actual credential. This two-layer design keeps master credentials out of Loom config.
4. Database open — The .kdbx file is opened and decrypted using the resolved password, keyfile, or both.
5. Entry lookup — Loom walks the KeePass group/entry tree and matches entries by path suffix. If the path matches exactly one entry, the requested field is read.
6. Injection — The resolved value is injected into the job environment as a file path (file: true, the default) or as a raw value (file: false).
7. Redaction — All resolved values are redacted before Loom writes to console output, receipts, or error messages.

Alias key conversion

Loom converts a database alias to an environment variable key using these rules:

Character type	Conversion
Lowercase letter (a–z)	Uppercased (A–Z)
Uppercase letter or digit	Kept as-is
Everything else (/, -, ., etc.)	Replaced with _

Examples:

Alias	Key	Env var prefix
local	LOCAL	LOOM_KEEPASS_DB_LOCAL_*
team	TEAM	LOOM_KEEPASS_DB_TEAM_*
group/project/repo	GROUP_PROJECT_REPO	LOOM_KEEPASS_DB_GROUP_PROJECT_REPO_*

Runtime environment variables

For a given alias key <KEY>:

Variable	Required	Purpose
LOOM_KEEPASS_DB_<KEY>_PATH	Yes	Absolute path to the .kdbx database file
LOOM_KEEPASS_DB_<KEY>_PASSWORD_ENV	No*	Name of the env var containing the KeePass master password
LOOM_KEEPASS_DB_<KEY>_KEYFILE_ENV	No*	Name of the env var containing the path to the KeePass keyfile

*At least one credential source must resolve. Both can be set for combined password + keyfile authentication.

Entry path matching

Entry paths use suffix matching. You do not need to specify the full path from the KeePass root group — only enough trailing segments to uniquely identify the entry.

Database structure	entry-path in ref	Result
Root / services / loom / deploy	services/loom/deploy	Matches (exact suffix)
Root / services / loom / deploy	loom/deploy	Matches (shorter suffix)
Root / v1 / deploy and Root / v2 / deploy	deploy	Fails — ambiguous (SECRETS_REF_INVALID)

If a path matches zero entries, resolution fails with SECRETS_REF_NOT_FOUND. If it matches more than one, resolution fails with SECRETS_REF_INVALID.

Error codes

All errors cause the job to fail closed (no fallback, no empty injection).

Code	Cause	Fix
SECRETS_PROVIDER_UNAVAILABLE	Alias env vars missing, credentials invalid, or .kdbx file unreadable	Verify LOOM_KEEPASS_DB_<KEY>_* variables and database path
SECRETS_REF_INVALID	Malformed URI or ambiguous entry path	Check URI format; add more path segments to disambiguate
SECRETS_REF_NOT_FOUND	Entry path or field does not exist in the database	Confirm the entry and field exist in the .kdbx file
SECRETS_REQUIRED_MISSING	A required: true secret could not be resolved	Fix provider config or set required: false for optional secrets
SECRETS_UNSAFE_DEBUG_TRACE	CI_DEBUG_TRACE=true with file: false injection	Remove debug trace or switch the secret to file: true

Security model

The KeePass provider enforces three boundaries:

1. References only in YAML — Workflow files store keepass:// URIs. Credential material never appears in committed files.
2. Credential indirection — Vault master passwords and keyfile paths are referenced by env var name, not by value. The _PASSWORD_ENV / _KEYFILE_ENV variables contain names, not secrets.
3. No read/show CLI commands — The loom secrets keepass CLI intentionally omits any command that would print secret values to stdout. All output is limited to metadata (alias, path, field names).

Resolved values are redacted at every output boundary. Even with redaction active, avoid printing secret-bearing variables in scripts.

Credential combinations

The KeePass provider supports three authentication modes when opening a .kdbx database:

Mode	Config required	Use case
Password only	_PASSWORD_ENV set	Simplest setup for local development
Keyfile only	_KEYFILE_ENV set	Automated environments where a keyfile is provisioned
Password + keyfile	Both set	Highest security — requires both factors

Limitations

• No remote vaults — the .kdbx file must be accessible on the local filesystem at runtime.
• No automatic rotation — credential updates require running loom secrets keepass vault update or editing the database externally.
• Single-user locking — KeePass databases do not support concurrent writes. Avoid parallel jobs that mutate the same vault.

Get started

1. Install and setup — Configure a vault alias and runtime credentials.
2. CLI reference — Create vaults and manage entries with loom secrets keepass.
3. Workflow integration — Use keepass:// references in job definitions.

For the broader secrets system, see the Secrets overview.