KeePass install and setup

Set up a KeePass vault so Loom can resolve keepass:// secrets at runtime. By the end of this guide you will have a configured vault alias, working credential indirection, and a validated workflow reference.

What you will configure

Component	Purpose
Database alias	Stable name used in keepass:// URIs
LOOM_KEEPASS_DB_<KEY>_PATH	Points Loom to the .kdbx file
LOOM_KEEPASS_DB_<KEY>_PASSWORD_ENV / _KEYFILE_ENV	Names the env vars that hold vault credentials
Credential env vars	Hold the actual master password and/or keyfile path

Prerequisites

• A KeePass .kdbx database file (or you will create one with the CLI in step 4).
• A master password and/or keyfile for the database.
• Loom CLI installed and available in your workspace.

1. Choose a database alias

Pick a stable, memorable alias for your vault. The alias appears in every keepass:// reference, so keep it short and environment-specific.

Good aliases: local, team, prod, staging.

You can also use path-based aliases like group/project/repo — Loom converts them to environment variable keys automatically (see alias key conversion).

keepass://local/main#services/loom/deploy:password
         ^^^^^
         alias

2. Set the database path

Tell Loom where the .kdbx file lives. The environment variable name follows the pattern LOOM_KEEPASS_DB_<KEY>_PATH, where <KEY> is your alias converted to uppercase with non-alphanumeric characters replaced by _.

For alias local (key = LOCAL):

export LOOM_KEEPASS_DB_LOCAL_PATH="$HOME/.config/loom/secrets/local.kdbx"

For alias group/project/repo (key = GROUP_PROJECT_REPO):

export LOOM_KEEPASS_DB_GROUP_PROJECT_REPO_PATH="/opt/secrets/repo.kdbx"

3. Configure credential indirection

Loom uses a two-layer indirection model for vault credentials. You set environment variables that contain the names of other environment variables — this keeps master credentials out of Loom configuration and CI system settings.

Step A — Tell Loom which env vars hold the credentials:

export LOOM_KEEPASS_DB_LOCAL_PASSWORD_ENV="KEEPASS_LOCAL_PASSWORD"
export LOOM_KEEPASS_DB_LOCAL_KEYFILE_ENV="KEEPASS_LOCAL_KEYFILE"

Step B — Set the actual credential values:

export KEEPASS_LOCAL_PASSWORD="your-master-password"
export KEEPASS_LOCAL_KEYFILE="$HOME/.config/loom/secrets/local.key"

At least one credential source must resolve. You can use password only, keyfile only, or both:

Mode	Variables required
Password only	_PASSWORD_ENV → credential env var
Keyfile only	_KEYFILE_ENV → credential env var
Password + keyfile	Both _PASSWORD_ENV and _KEYFILE_ENV

tip

In CI environments, set the LOOM_KEEPASS_DB_* variables in your CI system's secret/variable configuration. The indirection model means Loom config only stores env var names, never credential values.

4. Create a vault (optional)

If you do not have an existing .kdbx file, create one with the CLI:

export KEEPASS_PASSWORD="my-master-password"

loom secrets keepass vault create \
  --password-from-env KEEPASS_PASSWORD

This creates a .kdbx file at the default location (.loom/keepass/<alias>.kdbx) and registers it under the alias derived from your Git origin path. To override the alias or file path:

loom secrets keepass vault create \
  --vault-path local \
  --database-path "$HOME/.config/loom/secrets/local.kdbx" \
  --password-from-env KEEPASS_PASSWORD

See CLI reference — vault create for all flags.

5. Add secrets to the vault

export DB_SECRET="s3cret-value"

loom secrets keepass item create \
  --item-path services/loom/deploy \
  --field password \
  --value-from-env DB_SECRET

Repeat for each secret your workflows need. See CLI reference — item create for all flags.

6. Reference secrets in a workflow

Add keepass:// references to per-job secrets blocks:

deploy:
  stage: ci
  target: linux
  secrets:
    DATABASE_PASSWORD:
      ref: keepass://local/main#services/loom/deploy:password
  script:
    - ./scripts/deploy.sh

The variable DATABASE_PASSWORD defaults to file injection (file: true). Scripts read the value with cat "$DATABASE_PASSWORD". For more patterns, see KeePass in workflows.

7. Validate and run

Check that all references resolve before running:

loom check

Then execute:

loom run --local --workflow .loom/workflow.yml

If validation fails, check the error codes in the troubleshooting section below.

Complete environment setup example

All variables for alias local using password-only authentication:

# Alias mapping
export LOOM_KEEPASS_DB_LOCAL_PATH="$HOME/.config/loom/secrets/local.kdbx"

# Credential indirection (names of env vars, not values)
export LOOM_KEEPASS_DB_LOCAL_PASSWORD_ENV="KEEPASS_LOCAL_PASSWORD"

# Actual credential
export KEEPASS_LOCAL_PASSWORD="your-master-password"

Troubleshooting

Symptom	Likely cause	Fix
SECRETS_PROVIDER_UNAVAILABLE	Missing or incorrect LOOM_KEEPASS_DB_<KEY>_* variables	Verify alias key conversion and all three env var tiers
SECRETS_REF_NOT_FOUND	Entry path or field does not exist in the .kdbx file	Run loom secrets keepass item list to check available entries
SECRETS_REF_INVALID	Malformed URI or ambiguous entry path	Check URI format; add more path segments to disambiguate
SECRETS_REQUIRED_MISSING	Required secret unresolved at runtime	Fix provider config or set required: false for optional secrets
Credential indirection fails	The env var named by _PASSWORD_ENV or _KEYFILE_ENV is unset	Verify both tiers: the pointer var and the credential var it references

Security checklist

• Never place KeePass master credentials in workflow YAML files.
• Prefer file: true injection (the default) to reduce leakage risk from shell tracing and ps output.
• Disable CI_DEBUG_TRACE for jobs with file: false secrets.
• Store .kdbx files outside version control or encrypt them with a CI-only keyfile.

Next steps

• KeePass provider overview — URI format, resolution model, and error codes.
• CLI reference — Full command reference for loom secrets keepass.
• Workflow integration — Injection modes, optional secrets, and advanced patterns.
• Secrets security — Threat model and operational guardrails.