Agenix Secrets

Create age-encrypted secrets and wire them into NixOS modules.

Repo Secret Layout

hosts/<host>/secrets/
├── secrets.nix          # Public key → .age file mapping (NOT imported into NixOS)
├── my-secret.age        # Encrypted secret file
└── restic/              # Subdirectories supported
    └── repo.age
hosts/shared/secrets/
├── secrets.nix          # Shared cross-host secrets
└── host-keys.nix        # Maps hostname → public key for filtering

Auto-Wiring

modules/agenix.nix auto-generates age.secrets from secrets.nix:

Each "name.age" entry becomes age.secrets.<name> (.age suffix stripped)
Default owner = config.user.name (via mkDefault — overridable)
Default file points to hosts/<host>/secrets/<name>.age
Decrypted to /run/agenix/<name> at activation time

You do NOT need to set age.secrets.<name>.file — only override owner/group/mode when the default user shouldn't own it.

Workflow: Add a New Secret

1. Add entry to secrets.nix

# hosts/<host>/secrets/secrets.nix
let
  edmundmiller = "ssh-ed25519 AAAAC3...";
  nuc = "ssh-ed25519 AAAAC3...";
in {
  "my-secret.age".publicKeys = [ edmundmiller nuc ];
}

Both user and host keys are needed — user key to encrypt/edit, host key to decrypt on deploy.

2. Create the encrypted file

cd hosts/<host>/secrets

# Pipe content (non-interactive)
printf 'SECRET_VALUE' | age \
  -r "ssh-ed25519 AAAA...user" \
  -r "ssh-ed25519 AAAA...host" \
  -o my-secret.age

# Verify decryption
age -d -i ~/.ssh/id_ed25519 my-secret.age

The agenix -e CLI requires an interactive editor. For agent workflows, use age directly with -r for each recipient public key from secrets.nix.

3. Reference in NixOS module

# Simple: file path reference (most common)
services.myapp.environmentFile = config.age.secrets.my-secret.path;

# Override owner when service runs as different user
age.secrets.my-secret = {
  owner = "myapp";
  group = "myapp";
};

4. Deploy

# Stage by directory — NOT by filename (staging a .age path directly is blocked by the sandbox)
git add hosts/<host>/secrets/
git commit -m "secrets: add my-secret"
git push && hey nuc

Sandbox note: The pi sandbox blocks git add (and any bash command) that explicitly references a .age file path. Staging the parent directory avoids this — git add hosts/<host>/secrets/ stages all changes in the dir without naming .age files directly.

Pattern: HA secrets.yaml via !secret

Home Assistant's YAML supports !secret key references. The nixpkgs HA module post-processes generated YAML to unquote ! tags (sed converts '!secret foo' → !secret foo).

# In HA module config:
services.home-assistant.config.homeassistant = {
  latitude = "!secret latitude";    # Unquoted by nixpkgs sed post-processor
  longitude = "!secret longitude";
};

# Decrypt with correct owner and symlink into HA config dir:
age.secrets.hass-secrets = {
  owner = "hass";
  group = "hass";
};
systemd.tmpfiles.settings."10-hass-nix-yaml" = {
  "${config.services.home-assistant.configDir}/secrets.yaml" = {
    L.argument = config.age.secrets.hass-secrets.path;
  };
};

The .age file contains standard HA secrets.yaml format:

latitude: 33.083423
longitude: -96.820367

Pattern: Update Existing .age File

Decrypt → modify → re-encrypt. Common when adding vars to an existing env file.

# Decrypt to temp
age -d -i ~/.ssh/id_ed25519 hosts/<host>/secrets/my-env.age > /tmp/my-env.txt

# Modify
echo "NEW_VAR=value" >> /tmp/my-env.txt

# Re-encrypt (overwrites existing .age)
age \
  -r "ssh-ed25519 AAAA...user" \
  -r "ssh-ed25519 AAAA...host" \
  -o hosts/<host>/secrets/my-env.age /tmp/my-env.txt

# Clean up
rm /tmp/my-env.txt

# Verify
age -d -i ~/.ssh/id_ed25519 hosts/<host>/secrets/my-env.age

Pattern: 1Password + Agenix (Login Credentials)

For services needing a username/password — store in both 1Password (human access) and agenix (machine access).

# 1. Generate creds and store in 1Password
PASSWORD=$(op item create \
  --category=login \
  --title="MyService" \
  --vault="Private" \
  --url="http://nuc:8080" \
  --generate-password="32,letters,digits" \
  username="emiller" \
  --format=json | jq -r '.fields[] | select(.id == "password") | .value')

# 2. Create agenix env file
printf 'MYSERVICE_USER=emiller\nMYSERVICE_PASSWORD=%s' "$PASSWORD" | age \
  -r "ssh-ed25519 AAAA...user" \
  -r "ssh-ed25519 AAAA...host" \
  -o hosts/<host>/secrets/myservice-env.age

# 3. Add to secrets.nix, wire environmentFile, set owner (see below)

Pattern: Service Environment File with Owner Override

Most NixOS services run as a dedicated user (not emiller). Override the secret owner so the service can read it.

# In host config (e.g., hosts/nuc/default.nix):
modules.services.myservice = {
  enable = true;
  environmentFile = config.age.secrets.myservice-env.path;
};

# Override default owner (emiller) → service user
age.secrets.myservice-env.owner = "myservice";

The service username typically matches the service name. Check with grep -r "DynamicUser\|User=" /etc/systemd/system/<service>* on the target host if unsure.

Key public keys

Read from hosts/<host>/secrets/secrets.nix — don't hardcode. The file defines edmundmiller (user SSH key) and host-specific keys (e.g., nuc).

Common Pitfalls

Never builtins.readFile a secret path — leaks plaintext to world-readable Nix store
agenix -e fails in non-interactive shells — use age -r directly instead
Forgot host key in publicKeys — secret won't decrypt on target machine
Wrong owner — service can't read /run/agenix/<name> (default owner is config.user.name)
Shared secrets need entry in hosts/shared/secrets/secrets.nix AND host key in host-keys.nix

agenix-secrets