Add a secret
Write the value where it’s used and tag it !secret.
env: GITHUB_TOKEN: !secret ghp_abc123nami secret seal
env: GITHUB_TOKEN: !secret ghp_abc123 GITHUB_TOKEN: !secret YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBrUnZ1T2pMcXNh…The sealed line is safe to commit. Your comments and layout stay. A file with a secret that isn’t sealed yet can’t be applied.
Secrets are encrypted with age for everyone in the repo’s .nami-recipients. nami opens one only where it’s used, never into /nix/store.
Know where secrets can go
A secret is one value, text or a number. In a settings file, seal just the setting that’s secret.
env: API_KEY: !secret sk_live_123files: ~/.config/rclone/rclone.conf: s3: type: s3 secret_access_key: !secret "has # and: in it" # quote YAML's characters ~/.netrc: content: !secret "machine example.org login ada password hunter2" mode: "0400"| File | Where |
|---|---|
~/user.nami | env: values and files: |
project.nami | env: values, and a service’s env: and exports: |
computer.nami | files: and Wi-Fi passwords, on namiOS |
In user.nami, secret variables and files are written for you alone each time you apply. A project’s secrets go only into the environment of nami shell, nami run and nami up (Projects).
Get your key
nami secret key prints your public key, and makes one if you have none.
nami secret key
made your key: /home/ada/.config/nami/age.key (back it up; it never goes into git)
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
nami also opens secrets with your SSH key, ~/.ssh/id_ed25519 or id_rsa. Back up age.key: without it, or another listed key, nobody can open your secrets.
Let someone in
Give their public key to allow, in the repo, on a computer where you can open the secrets.
nami secret allow sam age1u8fhn2k5t2f6... # their `nami secret key`
nami secret allow sam ~/sam.pub # or their SSH public key
git commit -am "sam can open the secrets" && git push
ada age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8psam age1u8fhn2k5t2f6...allow also seals every secret again, for everyone listed. --remove takes someone out, and nami lists the secrets they could open, so you can change each one.
Edit or read a secret
nami secret edit user.nami # opens with secrets shown, seals on save
nami secret show user.nami # list them
nami secret show user.nami env.GITHUB_TOKEN # print one
A secret you didn’t change keeps its sealed text, so git diff shows only your edit.
Never commit a plain secret
nami secret hook
#!/bin/sh# Refuses commits with secrets that aren't sealed (`nami secret hook`).nami=$(command -v nami || echo '/nix/var/nami/bin/nami')exec "$nami" secret check --stagedThe hook refuses a commit with an unsealed secret. In CI, nami secret check does the same.
Use secrets on namiOS
On namiOS, computer.nami’s files and Wi-Fi passwords can hold secrets. The computer opens them with its own key as it starts, into /run, so they’re never on the disk.
files: /run/nami/secrets/api-token: !secret "the-token" # root only, read-onlypackages: - namiosnami usb makes the computer’s key and lets it in, so commit and push that change:
ada age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8plaptop age1k8yq2rmr7c5hf0d3zfsvq9qnfzjd7ffq4g2s2c8k6ndzx3w0xq4qh8yvjnnami check says, for each secret, whether you and the computer can open it. More in computer.nami on namiOS.