Getting Started with NixOS

This guide walks you through setting up nixos-artifacts-agenix for NixOS machine-level secrets from start to finish.

Prerequisites

Before you begin:

  1. Host SSH keys — NixOS machines have these at /etc/ssh/ssh_host_ed25519_key.pub

Step 1: Add Flake Inputs

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nixos-artifacts.url = "github:mrVanDalo/nixos-artifacts";
    nixos-artifacts-agenix.url = "github:mrVanDalo/nixos-artifacts-agenix";
  };

  outputs = inputs@{ self, nixpkgs, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        inputs.nixos-artifacts.nixosModules.default
        inputs.nixos-artifacts-agenix.nixosModules.default
        ./hosts/your-host
      ];
    };
  };
}

Step 2: Get Your Public Keys

You need the host’s public key to encrypt secrets that the machine can decrypt.

Retrieve from the target machine:

ssh-keyscan your-host | grep ssh-ed25519

Example output:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... hostname

Optionally, add your user key for development access:

cat ~/.ssh/id_ed25519.pub

Step 3: Configure the Backend

In your host configuration (hosts/your-host/default.nix):

{ config, ... }:

{
  networking.hostName = "your-host";

  artifacts.default.backend.serialization = "agenix";

  artifacts.config.agenix = {
    # Required: Path where encrypted files are stored
    flakeStoreDir = ./secrets;

    # Required: Host's public key for encryption
    publicHostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...";

    # Optional: Additional keys (e.g., your user key for development)
    publicUserKeys = [
      "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... user@laptop"
    ];
  };
}

Step 4: Define an Artifact

Create an artifact definition with a generator that creates the secret:

{ config, pkgs, ... }:

{
  artifacts.store.my-service = {
    generator = pkgs.writeShellScript "generate-my-service" ''
      export PATH="${pkgs.lib.makeBinPath [ pkgs.xkcdpass ]}:$PATH"
      xkcdpass --numwords 10 > "$out/password"
    '';
    files = {
      password = {
        path = "/var/lib/my-service/password";
        owner = "my-service";
        group = "my-service";
        mode = "0400";
      };
    };
  };
}

Step 5: Generate Secrets

Run the artifacts TUI to generate and serialize your secrets:

nix run github:mrVanDalo/nixos-artifacts-agenix

Navigate the TUI to select your machine and artifacts. After the TUI finishes, encrypted secrets are created at:

secrets/
└── per-machine/
    └── your-host/
        └── my-service/
            └── password.age

Step 6: Use Secrets in Configuration

Access secrets via the artifacts store:

{ config, ... }:

{
  services.my-service = {
    enable = true;
    passwordFile = config.artifacts.store.my-service.files.password.path;
  };
}

Step 7: Deploy and Verify

# Add encrypted files to version control
git add secrets/

# Build and deploy
nixos-rebuild switch --flake .#your-host

# Verify the secret was decrypted
sudo cat /var/lib/my-service/password

Next Steps