Introduction

This repository is a Nix Flakes-based dotfiles and system configuration, managing NixOS systems and Home Manager user environments across multiple machines.

It uses the nixos-unified framework with autowire for automatic module discovery and composition.

Repository Structure

flake.nix                          # Entry point, declares all inputs
  → modules/flake/toplevel.nix     # Flake-level glue (formatter, packages)
  → modules/{home,nixos}/          # Reusable modules (autowired)
  → mixins/{home,nixos}/           # Platform/version-specific configs
  → configurations/{home,nixos}/   # Per-host final configurations

modules/ — Core reusable NixOS/Home Manager modules
mixins/ — Platform-specific (linux/darwin) and version-specific configuration layers
configurations/ — Per-host configs that compose modules + mixins
overlays/ — Nixpkgs overlays and custom packages
secrets/ — SOPS-encrypted secrets (age keys, per-host)
private/ — Host-specific private configs (gitignored, present on deployed machines)

Architecture

Autowiring Pattern

Most default.nix files contain a single line:

{flake, ...}: flake.inputs.autowire.default ./.

This auto-discovers and composes all .nix files in the same directory into a merged NixOS/Home Manager module. Adding a new .nix file to an autowired directory automatically includes it — no manual imports needed.

Layered Composition

Configuration is built up in layers:

flake.nix — Declares all inputs; outputs are generated via nixos-unified
modules/flake/ — Flake-level glue (formatter, packages, apps). Each .nix file here is a flake-parts module auto-included by the framework
modules/{home,nixos}/ — Reusable Home Manager / NixOS modules, autowired
mixins/{home,nixos}/ — Platform-specific layers (linux, darwin) and host/container-specific config
configurations/{home,nixos}/ — Per-host final configurations that compose modules + mixins

Custom Options

modules/home/options.nix defines the me option set used throughout Home Manager modules:

me.username
me.fullname
me.email

These are set in each host’s configuration file (e.g., configurations/home/yjpark.nix).

Overlays and Custom Packages

overlays/default.nix autowires from ./, picking up packages.nix in the overlays directory. Custom packages are automatically available as nixpkgs overlays throughout the configuration.

Key Commands

Tasks are defined in mise.toml. Use mise tasks to list all available tasks.

Daily Use

# Home Manager activation (applies user-level config)
mise run _activate-home

# Build NixOS config for current host (builds without switching by default)
mise run build-host

# Switch NixOS config (applies system-level config, requires sudo)
mise run _switch-host

Flake Maintenance

# Update all flake inputs
mise run flake-update

# Update specific inputs
mise run flake-update nixpkgs home-manager

# Show flake outputs
mise run show

# Format Nix files (uses nixpkgs-fmt)
nix fmt

Documentation

# Serve docs locally (hot-reload)
mise run docs-serve

# Build static docs site
mise run docs-build

Nix Directly

# Activate Home Manager (same as mise run _activate-home)
nix run

# Build a specific package
nix build .#docs

Home Manager

User Profiles

Two user profiles exist in this configuration:

Username	Used On	Base Config	State Version
`yjpark`	Physical hosts	`configurations/home/yjpark.nix`	`25.05`
`yj`	Containers	`configurations/home/yj.nix`	`26.05`

Host and Container Mixins

Host-specific configurations live in:

mixins/home/hosts/ — One .nix file per physical host
mixins/home/containers/ — One .nix file per container

Adding a .nix file to either directory automatically registers a new host or container via the autowire pattern — no manual imports needed.

Activation Logic

modules/flake/activate-home.nix defines how mise run _activate-home resolves the correct Home Manager configuration:

Matches current hostname against known hosts → activates yjpark@<host>
Matches current hostname against known containers → activates yj@<host>
Falls back to <username>@ for unknown hosts (the trailing @ is required by nixos-unified for bare username fallback configs)

Configuration Generation

modules/flake/home-configs.nix generates username@host entries for each host/container mixin, plus a bare username fallback (without host suffix). This populates homeConfigurations in the flake outputs.

Secrets

Secrets are managed with SOPS-nix using age encryption.

Setup

Each host has its own age key
Encrypted secret files live in secrets/ directories and any files matching secret.*
The .sops.yaml file at the repo root defines which age keys can decrypt which secrets

Usage

Encrypted files are automatically decrypted at activation time by sops-nix and made available to NixOS/Home Manager modules as paths under /run/secrets/.

Refer to the sops-nix documentation for creating and editing secrets.

Flake Inputs

All inputs are declared in flake.nix. This page documents the purpose of each.

Core / Framework

Input	Purpose
`nixpkgs`	nixos-unstable — the primary package set
`home-manager`	User environment management
`flake-parts`	Flake composition framework
`nixos-unified`	Opinionated wrapper around flake-parts for NixOS + HM
`autowire`	Custom fork (`github:yjpark/autowire.nix`) — auto-discovers and composes `.nix` files in a directory

Software

Input	Purpose
`sops-nix`	Declarative secret management with SOPS + age
`nixvim`	Neovim configured via Nix
`flox`	Developer environments
`nixidy`	Kubernetes GitOps (k8s manifest generation)
`nixos-vscode-server`	VS Code remote server support on NixOS
`solaar`	Logitech device manager
`llm-agents`	LLM agent tools

Desktop / UI

Input	Purpose
`claude-desktop`	Claude desktop application
`niri`	Wayland compositor
`xremap-flake`	Key remapper for Wayland/X11
`antigravity`	(UI tool)
`jjui`	TUI for the `jj` (Jujutsu) VCS

Active Tasks

In Progress

Setup code on incus (flakes-6zwu)

Task · normal

Todo

Bug · normal

Setup quartz to preview and publish oxide projects (flakes-k391)

Task · normal

Check MCPVault, to see whether it’s a better option for the markdowns (flakes-k3pr)

Task · normal

Features

Project-wise pane configuration in Zellij (flakes-1zlj) — Done
Deploy OneCLI as credential proxy for yolo container (flakes-2aqm) — Done
Host Caddy LAN proxy for Incus container services (flakes-68h7) — Done
Incus container ingress auto-discovery (flakes-7ckd) — Done
Ingress hub page: service dashboard with iframe embedding (flakes-bti9) — Done
Change Zellij pane background color based on project path (flakes-dkc4) — Done
Zellij WASM plugin for dynamic tab naming (flakes-je55) — Draft
Niri config: declarative host-based mixin (flakes-p2qs) — Archived
Add mdBook documentation site (flakes-px5o) — Done
Zellij per-project auto-layouts on cd (flakes-u0yw) — Done

Tasks

Disable terminal bell sound (flakes-0u0f) — Done
Create mise-run-or-just fish function (flakes-0ycg) — Done
Enhance tv-mise-tasks to handle tasks with arguments (flakes-14he) — Done
Make j abbreviation expand conditionally to mise run or just (flakes-1cc9) — Done
Tidy up the shell title when running zellij (flakes-2fpy) — Archived
Remove stateVersion mixin pattern, use defaults instead (flakes-5pbu) — Archived
Restructure home config host/container registration (flakes-6n5b) — Archived
Setup code on incus (flakes-6zwu) — In Progress
Resolve username from host/container dir in activate-home.nix (flakes-7aac) — Archived
Setup markdown-oxide (flakes-7ih3) — Archived
Automate OneCLI CA push to containers on boot (flakes-aurl) — Done
Set up Incus across machines (flakes-bxl7) — Archived
Auto-trigger tab completion after j abbr expands to mise run _ (flakes-c03b) — Done
Unify terminal theme to Tokyo Night (flakes-hncv) — Done
Set up firewalld as NixOS service and migrate existing firewall rules (flakes-jvmx) — Archived
Setup quartz to preview and publish oxide projects (flakes-k391) — Todo
Check MCPVault, to see whether it’s a better option for the markdowns (flakes-k3pr) — Todo
Update CLAUDE.md to reflect current state (flakes-nyvs) — Archived
Setup colima with incus (flakes-o04s) — Archived
Add edit-in-place script (flakes-oh4v) — Done
Add GitHub token via OneCLI + container git config (flakes-oi2x) — Done
Refactor ai.nix into ai/ directory (flakes-ojyn) — Done
Configure jjui theme for readability with Pencil Dark terminal theme (flakes-p7hc) — Done
Integrate Home Manager as a NixOS module (flakes-rg27) — Archived
Migrate from just to mise for task running (flakes-rg2j) — Archived
Full jjui theme with terminal-independent hex colors (flakes-sk2r) — Done
Inhibit idle/sleep during audio/video playback (flakes-va02) — Done
Dynamic per-host Home Manager configs via flake module (flakes-vaiq) — Archived
Add rtk-rewrite.sh hook to claude module with home-manager linking (flakes-y887) — Done
Replace CopyQ with cliphist (Wayland-native clipboard manager) (flakes-yyox) — Archived
Add mdbook-beans tasks section to docs (flakes-zvh8) — Done

Bugs

Fix Ctrl+Shift+C in wezterm clobbering zellij clipboard (flakes-5oyz) — Archived
Hub toolbar URL tracking for iframe navigation (flakes-dya3) — Todo
Fix mise.toml var args bug (flakes-m3r8) — Archived
Fix git push auth inside Incus container via OneCLI proxy (flakes-nz9y) — Done

Drafts

Zellij WASM plugin for dynamic tab naming (flakes-je55) — Draft

Features

Project-wise pane configuration in Zellij (flakes-1zlj) — Done
Deploy OneCLI as credential proxy for yolo container (flakes-2aqm) — Done
Host Caddy LAN proxy for Incus container services (flakes-68h7) — Done
Incus container ingress auto-discovery (flakes-7ckd) — Done
Ingress hub page: service dashboard with iframe embedding (flakes-bti9) — Done
Change Zellij pane background color based on project path (flakes-dkc4) — Done
Zellij WASM plugin for dynamic tab naming (flakes-je55) — Draft
Niri config: declarative host-based mixin (flakes-p2qs) — Archived
Add mdBook documentation site (flakes-px5o) — Done
Zellij per-project auto-layouts on cd (flakes-u0yw) — Done

Project-wise pane configuration in Zellij (flakes-1zlj)


Status	Done
Type	Feature
Priority	normal

Configure Zellij pane/tab naming to visually identify projects in multi-project sessions.

Design

State Management

State file: /tmp/zellij-tab-{ZELLIJ_SESSION_NAME} — one line per pane: {PANE_ID}={project_name}
Session root: Capture $PWD at shell init as ZELLIJ_SESSION_PROJECT — the “home” project for the session
Project name: Git repo root basename (git rev-parse --show-toplevel | basename), fallback to basename $PWD

Pane Name Behavior

Condition	Pane name
PWD is within session’s starting project	`{command}` (current behavior)
PWD is in a different project	`<{project}> {command}`
Idle (no running command)	`<{project}>` or empty (current behavior)

Updated in fish_preexec (command starts) and on PWD change.

Tab Name Behavior

On every PWD change in any pane:

Write/update own entry in the state file
Read all entries, collect unique project names
If only one unique project: rename-tab "{project}" (same as today)
If multiple: rename-tab "{project1} | {project2} | ..."

Cleanup

fish_exit event: Remove own pane entry from state file, rebuild tab name
Shell init: Prune entries whose pane IDs are no longer in the state file

Tasks

Add helper to resolve project name (git root basename, fallback to basename PWD)
Capture session project on shell init ($ZELLIJ_SESSION_PROJECT)
Implement state file writes (per-pane project tracking)
Update pane name logic: <project> command format when outside session project
Update tab name logic: aggregate unique projects from state file
Add cleanup on fish_exit
Add stale entry pruning on shell init (simplified: natural overwrite on pane ID reuse)

Index	Hex	Tint
0	`#2e1a1a`	Red
1	`#1a2e1a`	Green
2	`#1a1a2e`	Blue
3	`#2e2e1a`	Yellow
4	`#2e1a2e`	Magenta
5	`#1a2e2e`	Cyan
6	`#2e241a`	Orange
7	`#1a2e24`	Teal


Status	Archived
Type	Task
Priority	normal
Tags	tweaks


Status	Archived
Type	Task
Priority	high
Tags	tools

File	Current rules	Migration approach
`mixins/nixos/lan/my/firewall.nix`	Open ports 1000-65535 for `10.0.0.0/8` (iptables)	Create a zone (e.g., “lan”) with these rules, assign LAN interface
`mixins/nixos/lan/cn/firewall.nix`	Same as above	Same zone approach
`mixins/nixos/dev/ports.nix`	TCP ranges 3000-3999, 8000-8999, 29000-29999	Add port ranges to appropriate zone
`modules/nixos/services/airplay.nix`	TCP 7000,7001,7100 + UDP 6000,6001,7011	firewalld service definition or rich rules
`modules/nixos/services/clash-verge.nix`	TCP ports for clash	firewalld service or zone rules
`modules/nixos/services/zerotierone.nix`	UDP port for zerotier	firewalld service or zone rules
`mixins/nixos/ext4/k3s.ext4.nix`	k3s TCP ports + ranges	firewalld zone for k3s
`mixins/nixos/zfs/k3s.zfs.nix`	k3s TCP ports + ranges	firewalld zone for k3s
`configurations/nixos/alienware-13/ports.nix`	TCP 2342 (photoprism)	firewalld service or zone rule

Keyboard shortcuts

YJ Park's NixOS and Home Manager Configuration