Integrate with Home Manager

This guide shows how to integrate nixos-artifacts-agenix into your Home Manager configuration for user-level secrets.

Module Setup

Add the required inputs and import the modules:

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  inputs.home-manager.url = "github:nix-community/home-manager";
  inputs.nixos-artifacts.url = "github:mrVanDalo/nixos-artifacts"; (1)
  inputs.nixos-artifacts-agenix.url = "github:mrVanDalo/nixos-artifacts-agenix"; (2)

  outputs = inputs@{ self, nixpkgs, home-manager, ... }: {
    homeConfigurations.my-user = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [
        inputs.nixos-artifacts.homeModules.default (3)
        inputs.nixos-artifacts-agenix.homeModules.default (4)
        ({ config, pkgs, ... }: {
          home.username = "my-user";
          home.homeDirectory = "/home/my-user";

          artifacts.default.backend.serialization = "agenix"; (5)

          artifacts.config.agenix = {
            flakeStoreDir = ./secrets; (6)
            username = "my-user"; (7)
            identityPaths = [ (8)
              "${config.home.homeDirectory}/.ssh/id_ed25519"
            ];
            publicUserKeys = [ (9)
              "ssh-ed25519 AAAA...my-user..."
            ];
          };
        })
      ];
    };
  };
}
1 Core artifacts framework
2 Agenix backend for artifacts
3 Core artifacts Home Manager options
4 Agenix backend options (includes agenix Home Manager module)
5 Set agenix as the serialization backend
6 Path reference where encrypted secrets are stored
7 User identifier for secret paths
8 Paths to private keys for decryption
9 Public keys used to encrypt secrets
storeDir defaults to "secrets", which matches flakeStoreDir = ./secrets. Override it only if the TUI must write to a different working directory; in that case keep both options pointing at the same location, otherwise agenix will not find the encrypted files at runtime.

Standalone vs NixOS Integration

Home Manager can be used standalone or as a NixOS module:

Standalone Home Manager

homeConfigurations.my-user = home-manager.lib.homeManagerConfiguration {
  modules = [
    inputs.nixos-artifacts.homeModules.default
    inputs.nixos-artifacts-agenix.homeModules.default
    # ...
  ];
};

Home Manager within NixOS

nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
  modules = [
    inputs.home-manager.nixosModules.home-manager
    {
      home-manager.users.my-user = { config, ... }: {
        imports = [
          inputs.nixos-artifacts.homeModules.default
          inputs.nixos-artifacts-agenix.homeModules.default
        ];

        artifacts.config.agenix = {
          # Home Manager-specific configuration
        };
      };
    }
  ];
};

Module Variants

Two module variants are available:

homeModules.default

Includes the agenix Home Manager module. Use this for standard setups.

homeModules.without-agenix

Only provides nixos-artifacts integration. Use this if you already have agenix configured elsewhere in your Home Manager configuration.

Accessing Secrets at Runtime

After deserialization, secrets can be accessed in two ways:

Via nixos-artifacts

Use the artifacts path reference directly:

{ config, ... }:
{
  programs.git = {
    extraConfig = {
      credential.helper = "store --file=${config.artifacts.store.git-credentials.files.token.path}";
    };
  };
}

Via agenix

Since the agenix module is included, you can also use the standard agenix options. Each file in an artifact is exposed under age.secrets.<artifact-name>-<file-name>:

{ config, ... }:
{
  programs.git = {
    extraConfig = {
      # Artifact `git-credentials` with file `token` becomes `git-credentials-token`
      credential.helper = "store --file=${config.age.secrets.git-credentials-token.path}";
    };
  };
}

Both approaches work because nixos-artifacts-agenix maps artifacts.store to age.secrets behind the scenes. Use whichever fits your preference - the artifacts abstraction provides consistency, while the agenix options give you direct access to agenix-specific features like mode.

Key Differences from NixOS Integration

Aspect NixOS Home Manager

Directory

secrets/per-machine/<hostname>/

secrets/per-user/<username>/

Encryption keys

publicHostKey + publicUserKeys

publicUserKeys only

Decryption

Automatic (host SSH keys)

Requires identityPaths

Use case

System services, root configs

User applications, dotfiles

Next Steps