Skip to content

Managing Secrets

Jump to bottom
NullString1 edited this page May 29, 2026 · 3 revisions

Managing Secrets

How to securely manage sensitive data in your NullOS configuration using sops-nix.

Overview

NullOS configuration is stored in Git, but information like passwords, API keys, and tokens should remain private. NullOS uses sops-nix to securely encrypt secrets directly inside the git repository.

Architecture

NullOS stores secrets per-machine in: machines/{hostname}/secrets.yaml

These files are encrypted with SOPS using an age key.

When the system builds, sops-nix decrypts these files and places them securely in /run/secrets/.

The Age Key

The encryption is tied to an age key, which should be located at: ~/.config/sops/age/keys.txt

The public key is defined in .sops.yaml at the root of the repo.

Adding or Editing Secrets

1. Prerequisite: Age Key

Ensure your age key is present at ~/.config/sops/age/keys.txt.

2. Editing the Secrets File

To add or modify a secret for a specific machine (e.g., nslapt), run:

nix-shell -p sops --run "sops machines/nslapt/secrets.yaml"

This will decrypt the file into your default editor. You can add key-value pairs like:

githubToken: ghp_xxxxxxxxxxxxxxxxxxxx
resticRepository: sftp:user@server.com:/backups
resticPassword: super_secret_password
nextdnsServerName: your_nextdns_id

Save and close the editor. SOPS will automatically encrypt the file.

3. Using Secrets in Nix Modules

Secrets are configured in the machine's configuration or common modules.

First, ensure sops.secrets is defined in the NixOS config for that secret:

# In machines/{hostname}/default.nix or a module
sops.secrets."githubToken" = { };

To access the secret at runtime (e.g., in a service), use the path to the decrypted file:

services.restic.backups.nsdata = {
  passwordFile = config.sops.secrets."resticPassword".path;
};

Note: Secrets are not evaluated at Nix evaluation time. They are decrypted at runtime. You cannot use secrets in builtins.readFile or pass them as variables to other Nix modules directly.

Common Secrets in NullOS

NullOS currently expects the following secrets depending on the enabled features:

  • githubToken: Used for private flake inputs or GitHub CLI authentication.
  • resticRepository and resticPassword: Used if enableRestic or backup features are enabled.
  • nextdnsServerName, nextdnsStamp, nextdnsIpUpdateUrl: Used if NextDNS is configured.

Setting up a New Machine

  1. Generate an age key if you don't have one:
nix-shell -p age --run "age-keygen -o ~/.config/sops/age/keys.txt"
  1. Get the public key (starts with age1...) and add it to .sops.yaml in the repo root.
  2. Create the machine's secret file:
sops machines/newmachine/secrets.yaml

Next Steps

Clone this wiki locally