Getting Started with Home Manager

This guide walks you through setting up nixos-artifacts-agenix for Home Manager user-level secrets from start to finish.

Prerequisites

Before you begin:

  1. User SSH or age keys — For encrypting and decrypting secrets

Step 1: Get Your Public Key

Retrieve your public key for encryption:

From SSH key:

cat ~/.ssh/id_ed25519.pub

Or generate an age key:

age-keygen -o ~/.config/age/key.txt
cat ~/.config/age/key.txt
# Use the public key line starting with 'age1...'

Step 2: Add Flake Inputs

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

  outputs = inputs@{ self, nixpkgs, home-manager, ... }: {
    homeConfigurations.your-user = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [
        inputs.nixos-artifacts.homeModules.default
        inputs.nixos-artifacts-agenix.homeModules.default
        ./home/your-user
      ];
    };
  };
}

Step 3: Configure the Backend

In your Home Manager configuration (home/your-user/default.nix):

{ config, ... }:

{
  home.username = "your-user";
  home.homeDirectory = "/home/your-user";

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

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

    # Required: Your public key(s) for encryption
    publicUserKeys = [
      "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
    ];

    # Required: Path(s) to private key(s) for decryption at runtime
    identityPaths = [
      "${config.home.homeDirectory}/.ssh/id_ed25519"
    ];

    # Optional: Override user identifier (defaults to home.username)
    # username = "your-user";
  };
}

Step 4: Define an Artifact

Create an artifact definition with a generator:

{ config, pkgs, ... }:

{
  artifacts.store.git-credentials = {
    generator = pkgs.writeShellScript "generate-git-token" ''
      export PATH="${pkgs.lib.makeBinPath [ pkgs.openssl ]}:$PATH"
      openssl rand -hex 32 > "$out/token"
    '';
    files = {
      token = {
        path = "${config.home.homeDirectory}/.config/git/token";
      };
    };
  };
}

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 user and artifacts. After the TUI finishes, encrypted secrets are created at:

secrets/
└── per-user/
    └── your-user/
        └── git-credentials/
            └── token.age

Step 6: Use Secrets in Configuration

Access secrets via the artifacts store:

{ config, ... }:

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

Step 7: Deploy and Verify

# Add encrypted files to version control
git add secrets/

# Build and activate
home-manager switch --flake .#your-user

# Verify the secret was decrypted
cat ~/.config/git/token

Next Steps