📁 config

Self-contained NixOS system and workspace configuration repository.

Overview

This repository houses the entire declarative environment for my machines. It is designed to be cloned directly to ~/config and manages everything from core system hardware profiles to user-space tools and encrypted secrets.

Design & Architecture

• Declarative & reproducible: The entire system is fully defined and reproducible across different hardware targets, like my Framework 13.
• Secret management: Secure, key-based credential handling integrated natively via Agenix.
• Custom automation: Handcrafted operational wrapper scripts to streamline background services like Rclone and Keymapper.

Installation

Preparing Secrets (Agenix)

Agenix decrypts secrets during system activation using the host's SSH key (/etc/ssh/ssh_host_ed25519_key). This key must be listed as a recipient in secrets.nix for every secret the host needs.

If setting up a new machine, get its host key (cat /etc/ssh/ssh_host_ed25519_key.pub), add it to secrets.nix (on a machine with host key already configured), and re-encrypt all secrets with agenix -r before committing changes & pushing to GitHub. Afterwards, the new machine should be able to decrypt secrets automatically on activation (after pulling changes from the remote). Alternatively you can skip re-encrypting secrets and use an existing key instead, with the steps listed below:

1. Retrieve key from password manager, eg. "Agenix SSH (System) - Framework 13"
2. Rewrite /etc/ssh/ssh_host_ed25519_key with the retrieved key
3. Ensure the key has the correct permissions:

chmod 600 /etc/ssh/ssh_host_ed25519_key

Fresh Install

./scripts/rebuild-switch.sh framework-13 --force

Existing Install

nixos-rebuild-switch framework-13

Note: Other useful commands include nixos-rebuild-switch-logs, nixos-rebuild-test.

Post-Install

Rclone

Rclone frequently modifies the configuration file so making the config file read-only is not possible. The file should be stored in tools/rclone/rclone.conf - as that's where existing services look for it.

In order to have rclone be fully functional, we need to decrypt the configuration first. If you have successfully installed the system, you can run:

decrypt-rclone-conf

Otherwise, if this doesn't work, run:

cd ~/config/nix/secrets && agenix --decrypt rclone-conf.age > ~/config/tools/rclone/rclone.conf

To test if the config was passed correctly, run:

cat ~/config/tools/rclone/rclone.conf

Rebuilding the system might be necessary in order to ensure that systemd services use the updated configuration.

Updating the Rclone Configuration

If you need to update the rclone-configuration, run:

manage-secret rclone-conf.age

Alternatively:

cd ~/config/nix/secrets && EDITOR='zeditor --wait' agenix -e rclone-conf.age

After you finish updating the configuration, run decrypt-rclone-conf to update the local rclone configuration file.

Hosts

Home Server

The home server configuration provisions base system dependencies, firewall rules, and native storage points. Application-level services and environments are layered directly on top using the assets maintained in ./tools.

Infrastructure Run-Steps

• Coolify / Docker: Container setups are kept in ./tools/coolify and updated via the included upgrade.sh helper logic.
• Incus: Certificate at ./nix/nixos/hosts/home-server/certificates/incus used to authenticate to Incus Web UI.
• Production Backups: Background maintenance workflows execute shell operations using encrypted variables parsed straight out of Agenix (e.g., database states for platforms like Audiobookshelf and custom web apps via restic / rclone).

Framework 13

Audio Setup

In order to have good audio, we need to install Easyeffects (configured through Nix) and also the Framework DSP.

Run the installation steps detailed in the "Installing" section of the README (in the framework-dsp) repository.

Once that is completed, the profile "HifiScan+EEGuide" should be automatically selected on startup.

Secret Management

Secret management is handled by Agenix. To edit or create secrets you need your user key (~/.ssh/id_ed25519) listed as a recipient in secrets.nix (or manually specify the identity file through agenix -i).

Retrieve your user key from the password manager (e.g. "Agenix SSH - Framework 13 - e User"), copy it to ~/.ssh/id_ed25519, and run chmod 600 ~/.ssh/id_ed25519.

To update an existing secret:

manage-secret <secret-name>

Or alternatively:

cd ~/config/nix/secrets && EDITOR='zeditor --wait' agenix -e # replace zeditor as needed

Creating new secrets: add an entry to secrets.nix, then run manage-secret <secret-name>.

Secrets are not accessible in Nix configuration at nixos until committed to the repository. Reference them without the .age extension - this applies to home-manager configs too.

Tools

RClone

Service management commands:

• rclone-status - View service status (real-time)
• rclone-logs - Follow service logs
• rclone-start - Start service (timer, path watcher, service)
• rclone-stop - Stop service
• rclone-resync - Full resync (stops service, prompts confirmation, restarts)

Keymapper

Launch keymapper:

keymapper -c ~/config/tools/keymapper/configuration.conf

Misc

Nix Cache

To check if a specific Nix store path is available in a Cachix binary cache, you can use a simple curl command or specialized tools.

1. Check a Specific Path via HTTP Every cached path has a corresponding .narinfo file containing its metadata. You can check for its existence by using the store path's hash:

Run curl:

curl -I https://<your-cache-name>.cachix.org/<hash>.narinfo

Hash can be the commit hash or the store path hash

Success (200 OK): The package is cached. Failure (404 Not Found): The package is not in the cache.

Other

Notes available here