Key recovery
murk init prints 24 recovery words, a BIP39 mnemonic of the key’s 256 bits
of entropy. murk derives your age key directly from those bytes, so the same
words always give the same key.

Write the words down when you run murk init
Section titled “Write the words down when you run murk init”murk initmurk prints the 24 words once, when it generates the key. Store them in a password manager, or keep a physical copy offline, as your threat model requires. Anyone who has your 24 words has your key, so protect the phrase as you protect the key. Do not paste it into chat or commit it. Do not put a screenshot of it in a note app that syncs to the cloud before you think about who else can read that account.
Recovering a lost key
Section titled “Recovering a lost key”If the key file is gone (a new machine, a wiped disk) and you still have the
24 words, run murk restore in the project directory. It asks for the
phrase, with hidden input, and prints the key. It does not save the key. Write
it to a file that only you can read, and point MURK_KEY_FILE at that file:
mkdir -p -m 700 ~/.config/murk(umask 077 && murk restore > ~/.config/murk/restored.key)export MURK_KEY_FILE=~/.config/murk/restored.keyAdd the export line to your shell profile. When you run the command in the
project directory, murk warns you if the restored key is not a recipient of
the vault. That warning means the phrase was wrong.
murk derives the key directly from the words, so it is the key that
murk init generated. It has the same public key and is still a recipient of
every vault that authorized it. Nothing changes in the vault.
On a new machine, murk refuses the vault the first time, with “not trusted
on this machine yet”. The trust pin is local to each machine, so it did not
come back with the key. Review the vault and run murk trust once, as
described in Trusting the vault on a new
machine.
Displaying your phrase again
Section titled “Displaying your phrase again”murk recoverThis command prints the 24 words for the key that murk uses for the vault in
the current directory (MURK_KEY, MURK_KEY_FILE, or the stored key). Use
it if you did not write down the phrase at murk init. It works only for age
keys. SSH keys and hardware identities have no phrase, and murk recover
fails on them. Anyone who can read your key file can derive the phrase, so
protect both as one secret.
What recovery does and doesn’t cover
Section titled “What recovery does and doesn’t cover”Recovery restores your key, not the vault. It happens on your machine and
has no connection to git. If you lose the .murk file, the phrase does not
help. The file is in your repository, and git keeps its history.
Only age keys have a recovery phrase. SSH keys and hardware-backed identities (YubiKey, Secure Enclave, FIDO2) have none. See hardware keys for how recovery works for those.
If your key was stolen
Section titled “If your key was stolen”The phrase gives back the same key, so restoring it does not stop the attacker. Replace the key instead. Only a current recipient can change the recipient list, so the new key needs either a teammate or the old key.
-
Create the new key on a machine that you know is clean, in a new clone of the repository. Do not use a worktree of an old checkout, because
murk initthere reuses the key stored for the old checkout.murk initusesMURK_KEYorMURK_KEY_FILEbefore it looks for a stored key. An exportedMURK_KEYmakes it reuse the stolen key, and aMURK_KEY_FILEthat points at a deleted file makes it fail. So first make sure that neither variable is set:Terminal window unset MURK_KEY MURK_KEY_FILEenv | grep -c '^MURK_KEY' # must print 0murk initA shell profile, a sourced
.envor a direnv.envrccan set them again, so check in the shell where you runmurk init.When no key is stored for this vault,
murk initcreates a new key. It prints the public key and the signing-key fingerprint, and writes a.envwith aMURK_KEY_FILEline for the new key. If it says “using existing key”, it did not make a new key. Stop and find where the old key came from.If the directory already has a
.envwith a key line,murk initasks before it replaces that line. Answery. In a shell that sources.env, source it again afterwards to get the new path. -
Get the new key authorized, and added to each group that the old key was in. If you skip the groups, the new key cannot read or rotate the secrets of those groups.
-
A teammate can do it. Send them the new public key. They run
murk circle authorize <new-public-key>and, for each group,murk group add NAME --member <new-public-key>. A teammate who is a member of that group must add you to it. They commit and push. Then you pull, review the vault, and runmurk trust(see Trusting the vault on a new machine). Your new key is now a recipient, somurk trustworks with it. -
No teammate can do it (for example, you are the only recipient). Restore the old key to a file, but do not export it. Skip the
exportline of the example above, in this shell and in your shell profile:Terminal window (umask 077 && murk restore > ~/.config/murk/restored.key)Pass the old key only as a prefix on the commands that need it, so that every other command uses the new key. If you already exported it, run
unset MURK_KEY_FILEbefore the next step.If this machine has not trusted the vault yet, first review the vault and run
MURK_KEY_FILE=~/.config/murk/restored.key murk trust.murk trustneeds a key that is a recipient, and the new key is not one yet. Then runmurk circle authorize <new-public-key>andmurk group add NAME --member <new-public-key>with the sameMURK_KEY_FILE=~/.config/murk/restored.keyprefix. murk refuses to revoke the key that it runs as, so run the next step without the prefix.
-
-
With the new key, in a terminal, revoke the old key and enter a new value for each secret:
murk circle revoke <old-public-key> --rotate. See offboarding a teammate. Commit and push the vault. -
Tell your teammates your new key’s signing-key fingerprint, over a channel other than the repository.
murk initprinted it in step 1, andmurk trust --print-keyprints it again. After they pull, each of their machines refuses the vault once, because your new key signed it for the first time. They compare the fingerprint that the refusal andmurk trustshow with the one you sent, then runmurk trust. A CI runner that usesMURK_TRUSTED_SIGNERSneeds your new entry frommurk trust --print-keyin place of the old one. -
If you restored the old key, delete the restored key file. Remove every
exportline,.envline or.envrcline that still points at the old key, and open a new shell. -
Replace the real credentials at their providers. Distribute the new ones, then invalidate the old ones (in an urgent case, invalidate them first).
See the CLI reference for all the options.