Locke — Python

Unified credentials framework — encrypted config, OS keystore, Vaultwarden and OpenBao integration.

Install

For local development from this repository:

cd python
pip install -e ".[dev]"

From the repository root on macOS, install the public Locke CLI/package locally:

python3 -m pip install -e ./python
locke --version

The locke executable is installed into the active Python environment's bin directory, so make sure that directory is on your PATH.

Usage

Library

import locke

# Load and decrypt config → flat env vars
env = locke.load_config(".locke/config.encrypted.json")
# env["MONGO_URI"], env["SENTRY_DSN"], etc.

# Resolve a single credential
cred = locke.resolve_credential("LOCKE_ENCRYPTION_KEY")

# Get or set a vault secret
secret = locke.get_vault_secret("myproject/staging/api_key")
locke.set_vault_secret("myproject/staging/api_key", "new-value")

# Check Locke-owned setup placeholders ("FILL_ME")
if locke.is_placeholder(secret):
    raise RuntimeError("vault secret still needs a real value")

CLI

# Decrypt + flatten → shell exports
eval $(locke env)

# Decrypt to stdout
locke decrypt

# Encrypt plaintext config
locke encrypt

# Manage OS keystore
locke keystore set LOCKE_ENCRYPTION_KEY --prompt
locke keystore get LOCKE_ENCRYPTION_KEY

# Get vault secret
locke vault get myproject/staging/api_key

# Create missing vault entries from locke.json, then fill them interactively
locke vault setup
locke vault setup --interactive

# Get/set an OpenBao KV secret
locke openbao get myproject/staging/api_key
locke openbao set myproject/staging/api_key --password "new-value"

# Initialize project
locke init --project myproject --tenant staging

OpenBao KV

Locke can also read/write secrets from an OpenBao KV v1/v2 mount, using the same shape as the Vaultwarden client (get_secret/set_secret, get_secret_pair/set_secret_pair):

secret = locke.get_openbao_secret("myproject/staging/api_key")
locke.set_openbao_secret("myproject/staging/api_key", "new-value")

Connects via LOCKE_OPENBAO_ADDR/OPENBAO_ADDR/VAULT_ADDR and LOCKE_OPENBAO_TOKEN/OPENBAO_TOKEN/VAULT_TOKEN. See locke/openbao.py for the full env var list (mount, KV version).

Vault placeholders

Locke uses locke.PLACEHOLDER_VALUE ("FILL_ME") for vault entries that are known but not filled yet. Use locke.is_placeholder(value) instead of hard-coding the sentinel. VaultClient.get_secret() warns when it returns a placeholder; VaultClient.set_secret(path, None) or an empty value writes a placeholder and warns.

Environment Variables

Testing

cd python
pip install -e ".[dev]"
pytest