Quick start
You’ve been invited to a project that uses murk for secrets. Here’s how to get set up. Starting a project of your own? See Start a new vault.
-
Install murk
Section titled “Install murk”Terminal window brew install interrupted-sh/tap/murkOr use
cargo install murk-cli, or download a binary from GitHub Releases. See Install & verify for every install path and how to verify a release. -
Generate your key
Section titled “Generate your key”Clone the repo and change into it. Run
murk initnext to the.murkfile. In a directory without a.murkfile,murk initcreates a new, unrelated vault.Terminal window murk initmurk generates a key for this vault, prints 24 recovery words, and prints your public key:
⚠ not authorized — share your public key to get added:age1…signing key SHA256:… — teammates confirm this on your first writeIf
MURK_KEYorMURK_KEY_FILEis already set in your shell, or murk already stores a key for this vault, murk uses that key instead of generating one. It then prints no recovery words. Unsetting the variable gives you a new key only if murk stores no key for this vault.Write the recovery words down. If you lose your key, these words are the only way to recover it. See Key recovery. Copy the
age1…line for step 3.If you lose the
age1…line, runmurk initagain in the same directory. It reuses your stored key and prints the same public key. It never replaces a key that is already stored.murk stores your key in
~/.config/murk/keys/, not in the repo. It also writes a.envfile that points at the key. Make sure.gitignorelists.envand.murk.lock(the empty lock file murk creates next to the vault on every write). -
Get authorized
Section titled “Get authorized”Send your
age1…public key to someone who can already decrypt the vault. They run:Terminal window # (run by a current recipient, not you)murk circle authorize age1… --name you@example.comThen they commit and push
.murk.Confirm your signing-key fingerprint (age keys only). Your first write after you are authorized is refused once on each teammate’s machine. It stays refused until that teammate confirms the key you sign with:
murk initprinted your fingerprint (signing key SHA256:…). To see it again, runmurk trust --print-key. It prints your signer entry on stdout and the fingerprint on stderr.- Read the fingerprint to each teammate over something other than the repo.
- Each teammate compares it with the one
murk trustshows, then accepts.
You do this once per teammate. An
ssh-ed25519key, including one added withgithub:, is its own verifying key and skips this step.Using a GitHub SSH key instead. If you have an ed25519 SSH key on GitHub, a recipient can add it without exchanging keys. They run
murk circle authorize github:YOUR_USERNAME, then commit and push.murk. murk adds your GitHub SSH public keys as recipients and skips RSA keys.
On this path your SSH key is your murk identity, so you do not need the key from step 2. murk does not look in
~/.sshon its own. After yougit pull, point murk at your SSH private key:Terminal window unset MURK_KEYexport MURK_KEY_FILE=~/.ssh/id_ed25519The key must be unencrypted (no passphrase) and readable only by you. Until murk finds it,
murk get,murk exportandmurk execfail:- With no key at all, they fail with “MURK_KEY not set”.
- With a key that is not a recipient, such as one from
murk init, they fail with “you are not a recipient of this vault”.
If your GitHub keys change later, the next
authorize github:YOUR_USERNAMErefuses and lists the added and removed keys. The recipient must review them and pass--force. -
Pull and trust the vault
Section titled “Pull and trust the vault”Once authorized:
Terminal window git pull # get the updated .murk filemurk trust # once per machine: review the signer, then acceptmurk trustprints who signed the vault and every recipient, then asks before it records anything. For the signer it shows the full key and its signing-key fingerprint. Check that fingerprint with the person who invited you, over something other than the repo. To see what changed first, rungit log -p -- .murk. On a machine that already trusts the vault,murk diff ORIG_HEAD, run right after a pull, shows what the pull changed.If you skip this step, murk refuses the first load on a machine with “not trusted on this machine yet”. murk records your answer on this machine, not in the repo. It asks again only if a later vault looks wrong: unsigned, signed by an unfamiliar key, or older than one you have already accepted. See Recipients & signatures for the rules.
Do this once on every machine, after every fresh clone, because the trust pin lives outside the repo. A CI runner has no pin and nobody to run
murk trust. SetMURK_TRUSTED_SIGNERSon it instead, next to the key. Its value is the entry that each signer’smurk trust --print-keyprints, separated by commas or newlines. See CI/CD.Set
MURK_TRUSTED_SIGNERSonly from a CI secret or the real process environment. Never set it from a file in the repository or a.envthat an app’s dotenv loader reads, because it decides which signers the machine trusts. -
Use secrets
Section titled “Use secrets”Terminal window murk ls # see what secrets are availablemurk get DATABASE_URL # print one secretmurk export # print all as shell exportsmurk exec -- ./my-script.sh # run a command with secrets in envSee the CLI reference for every command and flag.
-
Set up direnv (optional)
Section titled “Set up direnv (optional)”Terminal window murk envdirenv allowNow secrets are automatically loaded when you
cdinto the project. See direnv integration for how it works and how to keep it in sync as secrets change.
Start a new vault
Section titled “Start a new vault”Run murk init in a project directory that has no .murk file. murk asks
for your name or email and creates the vault with you as its first
recipient. It prints your recovery words: write them down. If MURK_KEY or
MURK_KEY_FILE is set, or murk already stores a key for this vault (here or
in another git worktree of the repo), murk uses that key and prints no
recovery words.
Then add secrets, keep the local files out of git, commit the vault and load
it with direnv. murk init writes no .gitignore. Its .env points at your
key, and every write creates an empty .murk.lock next to the vault.
Neither belongs in git.
murk initmurk add DATABASE_URL # prompts for the value (hidden input)printf '.env\n.murk.lock\n' >> .gitignoregit add .murk .gitignore && git commit -m "add secrets vault"murk envdirenv allowTo add a teammate, run the murk circle authorize command from step 3, then
commit and push .murk.
For separate development, staging and production secrets, create one vault
for each environment, for example murk init --vault prod.murk. murk init
offers to reuse the key you already have. See
Environments.
What to know
Section titled “What to know”- Secret names are public. Anyone with repo access can see what secrets exist
(for example
STRIPE_KEY) and their descriptions. Only values are encrypted. - Your key is your identity. Do not share it, paste it into chat or commit it.
- Your 24 recovery words rebuild your key. Anyone who has them has your key, so store them as carefully as the key itself. See Key recovery.
- Revoking someone does not erase history. A teammate who leaves can still decrypt every vault version they could read before. The team rotates those secrets after revoking them. See Offboarding.
- Trust is per machine. murk checks every vault against what your machine
has accepted, so it refuses a file copied over the vault or an older
revision. Pass
--yestomurk trustonly in scripts, after you review the vault. - A vault cannot set sensitive variables.
murk export,execandagent execrefuse a key named likePATH,LD_PRELOAD,GIT_*,HTTPS_PROXYorMURK_*, because whoever last wrote the vault chose those names. Review who added the key, then pass--allow-reservedif you mean it. See Environment variables.