ragenix

ragenix is a Rust-based tool that provides age-encrypted secrets for NixOS systems. These secrets live in the Nix store and are decrypted during system activation. It is designed as a drop-in replacement for agenix, aiming for full compatibility with the agenix flake while providing more robust CLI parsing, validation, plugin support, and shell completions.

Note: Unlike agenix, ragenix focuses exclusively on supporting Nix Flakes.

The ragenix CLI is used to create, edit, and rekey age-encrypted secrets. It follows a similar command-line pattern to agenix.

Core Commands:

• --edit <FILE>: Edits an age-encrypted file using your configured $EDITOR.
• --rekey: Re-encrypts all secrets with the recipients specified in your rules.
• --schema: Prints the JSON schema that your rules must conform to.

# Edit a secret file
ragenix --edit ./secrets/my-secret.age

# Re-key secrets using defined rules
ragenix --rekey

# View the JSON schema for rules
ragenix --schema

Ragenix relies on a Nix binary to parse and evaluate rules files. You must ensure the path to your Nix binary is provided via the RAGENIX_NIX_BIN_PATH environment variable. The application uses this binary to execute nix eval --json on your rules files to convert Nix attribute sets into JSON for processing.

export RAGENIX_NIX_BIN_PATH=/path/to/your/nix

If you are running tests or environments that require nix to run within itself (such as during CI or specific local development setups), you must enable the recursive-nix feature in your NixOS configuration.

{
  nix = {
    extraOptions = ''
      experimental-features = nix-command flakes recursive-nix
    '';
    systemFeatures = [ "recursive-nix" ];
  };
}

To install ragenix, replace any references to github.com/ryantm/agenix with github.com/yaxitech/ragenix in your existing agenix setup. The ragenix package provides aliases for both the agenix package and the agenix binary to ensure compatibility.

You can install it using one of the following methods:

• Nix Profile: nix profile install github:yaxitech/ragenix
• NixOS: Add to environment.systemPackages in your configuration.
• Home Manager: Add to home.packages.

Rules are defined in a Nix expression file (typically secrets.nix) that maps secret file paths to the public keys of authorized recipients.

Rule Resolution:

• Each secret file string in the Nix expression is considered relative to the parent directory of the rules file.
• If the --rules option is omitted, ragenix looks for the RULES environment variable. If that is unset, it looks for secrets.nix in the current working directory.

Example secrets.nix structure:

{
  "secret.txt.age".publicKeys = [
    "age1g4eapz2lkdvrevsg443yx8rhxklhyz4sa8w0jdfyh8sgx3azhftsz8zu07"
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKrb9ne3nZjw6DW..."
  ];
}

ragenix supports age plugins. If plugin binaries are present in your PATH, ragenix will pick them up automatically.

To ensure plugins are always available (e.g., when using ragenix within a Nix derivation), use the plugins argument in the ragenix.override function to wrap the binary with an extended PATH.

# Example: Making the age-plugin-yubikey available via Nix
{ ragenix, age-plugin-yubikey }: 

ragenix.override { 
  plugins = [ age-plugin-yubikey ]; 
}

The -r or --rekey option decrypts all secrets defined in your rules configuration file and re-encrypts them using the specified public keys. This is primarily used to grant new recipients access to existing secrets.

Key behaviors:

• In-memory processing: To ensure security, ragenix does not write any plaintext data to disk during a rekey operation; all processing happens in-memory.
• Existing files: If a secret file defined in the rules does not exist on disk, it is ignored.
• Identities: If --identity is not provided, it uses default SSH private keys.

# Rekey all secrets defined in ./secrets.nix using a specific age identity
ragenix -i ~/.age/ragenix.key -r

You can configure several ragenix behaviors using environment variables to avoid passing them as flags every time:

• EDITOR: Sets the command used to edit files when using the --edit action.
• RULES: Sets the path to the Nix file that specifies recipient public keys (defaults to ./secrets.nix).