Environment variables

murk is configured almost entirely through environment variables, so it composes cleanly with direnv, CI, and subprocess wrapping without needing flags on every invocation. This page documents the variables the binary actually reads and writes; run murk <command> --help for the equivalent CLI flags where one exists (--vault mirrors MURK_VAULT, for example).

Identity and vault selection

Variable	Description
MURK_KEY	Your raw age private key (AGE-SECRET-KEY-1...), inline. Convenient for scripts and CI, but the key sits in plaintext wherever this variable is set: an env file, a CI secret store, a process environment. Rejected if set to a hardware-plugin identity string (AGE-PLUGIN-...); use MURK_KEY_FILE for those.
MURK_KEY_FILE	Path to a file holding your private key: a raw age key, an SSH PEM key, or an age plugin identity file (with a # Recipient: or # public key: header). murk init writes this to .env for direnv to pick up.
MURK_VAULT	Vault filename, defaulting to .murk. Equivalent to passing --vault on every command.

murk resolves your identity in order: an explicit MURK_KEY, then MURK_KEY_FILE, then an automatic lookup at ~/.config/murk/keys/<vault-hash> (the file murk init writes). That last, automatic step is disabled whenever strict mode is active (see below), so an agent context always needs an explicit key of its own.

.env itself is a write-only convenience: murk init populates it with a MURK_KEY_FILE reference so direnv (or source .env) can export it, but murk never reads .env directly at runtime. Reading it at runtime would let a vault copied into another repo silently borrow whatever key happened to be referenced by that directory’s .env. murk avoids that by trusting only the process environment and the vault-keyed automatic lookup.

Safety and agent context

Variable	Description
MURK_STRICT	Truthy (1/true/yes) fails closed rather than let a secret touch disk: murk edit’s scratch file must live on a RAM-backed filesystem (aborting before launching the editor otherwise), export/get refuse to run with stdout pointed at a regular file, and the automatic key lookup in ~/.config/murk/keys is disabled.
MURK_AGENT	Marks the process as running on behalf of an AI agent. Forces strict mode unconditionally: there’s no way to turn strict back off from inside an agent context, even by setting MURK_STRICT=0. murk agent exec sets it (alongside MURK_STRICT=1) on its child process automatically.
MURK_SELF_SCOPE	Truthy holds your own key to the vault’s agent allow-tag policy, as if you were an agent: get, exec/agent exec, and single-key edit KEY fail closed on a non-allowed key, export withholds forbidden keys, and bulk edit is refused. Implied automatically inside an agent context; a no-op on a vault with no policy set. See Grants.
MURK_NO_SIGNER_PIN	Opts out of signer-registry pinning (TOFU) on load: an escape hatch for a deliberate signer-key change, not something to leave set. See Recipients & signatures.

Also honored

A few standard variables shape specific commands, without being murk-specific configuration:

Variable	Description
CI	If truthy (the conventional CI-runner convention), murk prints a one-line nudge in its output toward the scoped-agent path when it sees a pipeline decrypting with a personal key. Advisory only: unlike MURK_AGENT, it doesn’t change behavior on its own.
EDITOR, VISUAL	murk edit opens this editor for interactive edits, checking EDITOR then VISUAL, falling back to vi if neither is set.
XDG_RUNTIME_DIR	Preferred over /tmp as the scratch location for murk edit’s temporary file, when it exists and is a directory. It’s typically tmpfs, so the plaintext buffer never touches persistent storage.
HOME (USERPROFILE on Windows)	Base directory for murk’s own state: ~/.config/murk/keys, ~/.config/murk/agent-keys, and ~/.config/murk/signer-pins.

Where these come together

How murk works covers the identity and layering model these variables configure. Grants shows MURK_AGENT and a grant key in a real invocation. Hardware-backed keys covers pointing MURK_KEY_FILE at a plugin identity. direnv integration covers the .env / MURK_KEY_FILE handoff for automatic shell loading. For a terse, generated table of every variable, see the environment variables reference.