murk-secrets

Python bindings for murk — an encrypted secrets manager for developers.

murk stores encrypted secrets in a single .murk file safe to commit to git. This package lets Python apps read those secrets at runtime.

Prerequisites

You need the murk CLI to create and manage vaults. This package only reads them.

# Install the CLI first
brew tap interrupted-sh/murk && brew install murk

# Initialize a vault and add secrets
murk init
murk add DATABASE_URL
murk add API_KEY

Then add the Python package to your project:

pip install murk-secrets

Quick start

# Load your key (created by murk init)
source .env

import murk

# Load the vault (reads MURK_KEY from environment)
vault = murk.load()

# Get a single secret
db_url = vault.get("DATABASE_URL")

# Get all secrets as a dict
secrets = vault.export()

# Dict-style access
api_key = vault["API_KEY"]

API

murk.load(vault_path=".murk") -> Vault

Load and decrypt a murk vault. Reads MURK_KEY or MURK_KEY_FILE from the environment.

murk.get(key, vault_path=".murk") -> str | None

One-liner: load the vault and get a single value.

murk.export_all(vault_path=".murk") -> dict[str, str]

One-liner: load the vault and export all secrets as a dict.

murk.has_identity() -> bool

Whether a decryption identity (MURK_KEY / MURK_KEY_FILE) is available — i.e. whether load() can decrypt. This is not a check for whether a secret exists; use key in vault / vault.keys() for that.

Vault

Scoped (per-user) overrides are applied automatically — if you have a scoped value for a key, it takes priority over the shared value.

Memory hygiene

Every decrypted value murk returns is a plain Python string. murk zeroes plaintext from its own memory when a value is dropped, but that guarantee ends at the FFI boundary: once a value crosses into Python the interpreter owns it, and its garbage collector — not murk — controls its lifetime. This is inherent to reading secrets into a process (see the threat model); avoid holding decrypted values longer than you need them.

Agent policy

When the loaded key is an agent grant (minted with murk agent grant), the vault's agent policy is enforced on read, the same way the CLI enforces it at murk agent exec: get() and export() raise RuntimeError if the policy forbids a key. Operator keys are unaffected. This makes a policy vault strict from every entry point — though an agent already cannot decrypt out-of-scope secrets at all, since its ephemeral key is not a recipient of them.

Environment

Set one of:

• MURK_KEY — your age secret key directly
• MURK_KEY_FILE — path to your key file (created by murk init)

The easiest setup is source .env in your project directory after running murk init.

Requirements

• Python >= 3.9
• murk CLI installed (to create and manage vaults)
• A .murk vault file in your project (created with murk init)
• MURK_KEY or MURK_KEY_FILE in the environment (created by murk init, loaded via source .env)

License

MIT OR Apache-2.0