Runtime Secrets

Dubnium uses sops-nix with age for runtime service secrets. Nix declares which services consume secrets; secret values stay out of Git, module options, and the Nix store.

Secret Classes

Use separate handling for each class:

Source bootstrap: prepare a local repo archive or copied working tree before install; do not require GitHub credentials in the installer.
Runtime service tokens: encrypt with SOPS and expose to services through /run/secrets or generated environment files.
User-runtime tokens: decrypt through the user profile after install for tools such as Codex, GitHub CLIs, or agent workflows.
Host enrollment identities: enroll interactively for v1 unless a future ADR accepts unattended enrollment.
Model weights: seed local model bundles into /var/lib/dubnium/models; do not store them in Git, SOPS, or the Nix store.

Host Age Identity

Create one age identity per host and keep it on that host:

sudo mkdir -p /var/lib/sops-nix
sudo age-keygen -o /var/lib/sops-nix/key.txt
sudo chmod 0600 /var/lib/sops-nix/key.txt
sudo cat /var/lib/sops-nix/key.txt | age-keygen -y

Add the printed public recipient to .sops.yaml when the first encrypted secrets file is introduced.

Keep encrypted host secret files under an ignored or carefully reviewed path such as secrets/hosts/<host>.yaml. Commit encrypted files only after checking that the cleartext values are not present in the diff.

Example SOPS data shape:

service_name:
  token: example

vLLM Model Downloads

The default Dubnium install should not need a Hugging Face token. Dubnium points vLLM at local model bundle paths under /var/lib/dubnium/models, and the fresh install path seeds those bundles from USB.

Only add a model-provider token if you intentionally choose an online download workflow for a future host. In that case, prefer an environment file generated by sops-nix:

{ config, ... }:
{
  dubnium.secrets.defaultSopsFile = ../../secrets/hosts/workstation.yaml;

  sops.secrets.model-provider-token = {
    key = "model_provider/token";
  };
  sops.templates."vllm-model-provider.env".content = ''
    HF_TOKEN=${config.sops.placeholder.model-provider-token}
    HUGGINGFACE_HUB_TOKEN=${config.sops.placeholder.model-provider-token}
  '';

  dubnium.vllm.environmentFiles = [
    config.sops.templates."vllm-model-provider.env".path
  ];
}

Do not add provider tokens to the custom installer ISO or USB seed partition.

User Runtime Tokens

User tools are owned by the dotfiles Home Manager profile, not by Dubnium system services. Keep tokens such as these in the user SOPS file:

github_token: ghp_example
openai_api_key: sk-example

The dotfiles profile exposes secret file paths, for example GITHUB_TOKEN_PATH and OPENAI_API_KEY_PATH. It can also source a sops-generated shell fragment for interactive user sessions, so tools installed by the profile inherit variables such as OPENAI_API_KEY without per-tool wrappers and without putting plaintext values in Nix options.

Codex should get OPENAI_API_KEY this way. A later user workflow can use GITHUB_TOKEN the same way without changing the installer policy.

Rotation

Edit the encrypted SOPS file with sops.
Rebuild the target host.
Restart any service that consumes the rotated secret if activation did not already restart it.
Revoke the old token at the provider.

Checks

Before committing, inspect staged changes:

git diff --cached
git diff --check

Do not commit plaintext tokens, private keys, generated age identities, model weights, or local decrypted files.

Keyboard shortcuts

Dubnium