# millerson.name Nix Overlay A custom Nix overlay and flake providing additional packages not found in upstream nixpkgs, built using [numtide/blueprint](https://github.com/numtide/blueprint) for streamlined flake development. ## Features - **Custom packages** - Additional software packaged for Nix - **Two overlay strategies** - Choose between binary-cache-friendly or dependency-sharing overlays - **Blueprint-based** - Uses modern Nix flake patterns with `numtide/blueprint` ## Available Packages | Package | Description | Category | |---------|-------------|----------| | `agnix` | Linter for AI agent config files (CLAUDE.md, AGENTS.md, SKILL.md, hooks, MCP), ships `agnix`, `agnix-lsp` and `agnix-mcp` | AI Coding Agents | | `awg-tool` | CLI for AmneziaWG self-hosting — generates 1.0/1.5/2.0/3.0 obfuscation parameters, exports .conf and vpn:// configs, installs servers over SSH | Networking | | `awgen` | Offline CLI for AmneziaWG configurations — harmonises native .conf and vpn:// inputs, generates client participants and tunnels, and analyses obfuscation | Networking | | `aionui` | Free, open-source, Cowork app with AI Agents | AI Coding Agents | | `codeaf` | Coding harness and software factory for open models: hand work off, then watch every project from one terminal | AI Coding Agents | | `codex-api-proxy` | Local OpenAI-compatible HTTP proxy backed by Codex/OpenAI credentials | AI LLM Gateway | | `codex-oauth-proxy` | Local proxy exposing a ChatGPT Codex account through OpenAI-compatible APIs | AI LLM Gateway | | `container-use` | Containerized environments for coding agents | AI Coding Agents | | `desloppify` | Multi-language codebase health scanner and technical debt tracker for AI agents | AI Coding Agents | | `ds4` | DeepSeek 4 Flash and PRO local inference engine for ROCm (Strix Halo) | AI Inference | | `freebuff` | The world's strongest free coding agent | AI Coding Agents | | `freetoken` | Local MoE-offload LLM inference runtime with OpenAI- and Anthropic-compatible APIs | AI Inference | | `graphify` | Turn any folder of code, docs, papers, images, or videos into a queryable knowledge graph | AI Coding Agents | | `g3` | AI coding agent that writes code and executes commands, with multi-provider LLM support, context compaction, and desktop automation | AI Coding Agents | | `haivemind` | Multi-model AI consensus, aggregation, and fusion runner for popular AI CLIs | AI Coding Agents | | `hipengine` | ROCm-native local LLM inference engine with torch-free runtime for AMD RDNA GPUs | AI Inference | | `magg` | MCP aggregator / meta-MCP server that aggregates, proxies and manages other MCP servers so agents can discover and manage tools at runtime, ships `magg` and `mbro` | MCP Servers | | `marmel` | Autonomous agentic coding assistant with Manager + specialist subagent orchestration over any OpenAI-compatible LLM backend | AI Coding Agents | | `mcp-gateway` | Universal Model Context Protocol gateway that sits between AI client and MCP tools/servers | MCP Servers | | `memdoor` | Coding and automation agent in one CLI binary: runs locally or over SSH, with YAML workflows and a decision model in front of the chat model | AI Coding Agents | | `nftables-analyzer` | Analyze nftables firewall rules and evaluate traffic queries | Networking | | `nftablesbuilder` | Web interface to manage nftables rules with drag-and-drop rule creation | Networking | | `shardr` | Decentralized LLM repository: content-addressed model store, BitTorrent-based sync, OpenAI-compatible serving via llama-server | AI Inference | | `skillsmcp` | MCP server that exposes Agent Skills to AI agents via the Model Context Protocol | MCP Servers | | `kubernetes-mcp-server` | Model Context Protocol (MCP) server for Kubernetes and OpenShift | MCP Servers | | `kyojin` | Upstream Kyojin 1.8.10 with AMD ROCm SDK wheels and a host C compiler for Triton JIT | AI Inference | | `hipfire` | AMD RDNA inference engine with TheRock compiler wrappers and quantization tools | AI Inference | | `hipfire-kernels` | Precompiled hipfire kernels for gfx1151 | AI Inference | | `gufo` | Gufo with XDNA2 NPU support and the Unsloth UD 3.1 compatibility patch | AI Inference | | `xrt-amdxdna` | XRT with the amdxdna plugin, built against gufo's nixpkgs | AI Inference | | `therock-rocm` | Locally maintained TheRock 10.1 SDK for gfx1151 | AI Inference | | `strata` | Strata inference engine, API server and CPU vision encoder with ROCm 10 HIP support for gfx1151 | AI Inference | | `crucible-strix-halo` | Crucible EXL3 inference engine and OpenAI-compatible server for gfx1151 with the ROCm 10 runtime | AI Inference | | `strixite` | Source-built HIP inference engine and OpenAI-compatible server for gfx1151 / Zen 5 with ROCm 10 | AI Inference | | `pwilkin-llama-cpp` | pwilkin llama.cpp fork with ROCm for gfx1151 | AI Inference | | `strix-llama-cpp` | halo-box llama.cpp fork with Vulkan | AI Inference | | `loop` | Corporate messenger for your team | Communication | | `radar` | Modern Kubernetes visibility — topology, event timeline, service traffic, resource browsing, Helm management, and GitOps support | Kubernetes | | `omniroute` | Unified AI router with 160+ providers, auto fallback, MCP/A2A, OpenAI-compatible APIs | AI LLM Gateway | | `open-code-review` | AI-powered code review CLI combining deterministic pipelines with an LLM agent for line-level review comments | AI Coding Agents | | `pilotdeck` | Task-oriented AI Agent productivity platform (source-built Electron desktop app, plus a headless server command) with WorkSpace isolation, white-box memory, and smart routing | AI Agents | | `pdfcraft` | PDF reader and editor written from scratch in Rust — comments, forms, page organizing, redaction — plus a headless `pdfcraft-cli` with an opt-in MCP server | PDF Tools | | `relay-free-llm` | RESTful API to route user prompts to various AI model providers with automatic failover and intent-based routing | AI LLM Gateway | | `stakpak` | DevOps AI agent that generates infrastructure code, debugs Kubernetes, configures CI/CD, and automates deployments | AI Agents | | `traycer` | Open-source AI orchestration app for agentic coding | AI Coding Agents | ## Usage ### As a Flake Add to your `flake.nix` inputs: ```nix inputs.millerson-nix-overlay.url = "git+https://git.millerson.name/alex/millerson-overlay.nix.git"; ``` Then use in your outputs: ```nix outputs = { nixpkgs, millerson-nix-overlay, ... }: { nixosConfigurations.your-host = nixpkgs.lib.nixosSystem { system = "x86_64-linux"; modules = [ millerson-nix-overlay.nixosModules.default # ... your other modules ]; }; }; ``` ### As an Overlay #### Option 1: Default Overlay (Binary Cache Friendly) Uses the packages built against this flake's nixpkgs revision. Binary cache hits work best when using the same nixpkgs revision. ```nix nixpkgs.overlays = [ millerson-nix-overlay.overlays.default ]; ``` #### Option 2: Shared Nixpkgs Overlay (Dependency Sharing) Builds packages against your system's nixpkgs, sharing dependencies with the rest of your system. No second nixpkgs evaluation, but binary cache only hits when your nixpkgs revision matches ours. ```nix nixpkgs.overlays = [ millerson-nix-overlay.overlays.shared-nixpkgs ]; ``` ### Installing Packages With flakes enabled: ```bash # Try a package nix run git+https://git.millerson.name/alex/millerson-overlay.nix.git#mcp-gateway # Install permanently nix profile install git+https://git.millerson.name/alex/millerson-overlay.nix.git#mcp-gateway ``` ### Inference Engines The engine packages target AMD Strix Halo (`gfx1151`) on `x86_64-linux`. `nixpkgs-engine` pins the shared engine toolchain independently of the other packages. Gufo and Kyojin retain their upstream nixpkgs pins. Kyojin uses the upstream 1.8.10 flake with its AMD ROCm SDK wheels. The serving wrappers also set `CC` for Triton's runtime C compilation. The upstream derivation still reports version `1.5.8`; the source pin is the `v1.8.10` tag. `kyojin.tests.jit` and `kyojin.tests.cpu` expose the upstream HIP compiler smoke check and CPU tests. The former nixpkgs PyTorch/ROCm package and its `jitRocmSdk` override have been removed. Hipfire exports `kernels`, `hipcc`, `rocm`, `llvmReadobj` and `llvmObjdump` as package attributes. Set the model directory with `hipfire.override { modelDir = "/path/to/models"; }`. The upstream service module is available as `nixosModules.hipfire`, and its ROCm overlay as `overlays.hipfire`. Neither is enabled by the default module. Gufo exports its matching `xrt`, `npuDir` and `fabricClock` as package attributes. The consumer must configure NPU power and fabric clocks before using the NPU. TheRock uses this repository's own SDK recipe and a pinned official AMD tarball. The 10.1.0 archive's internal package stamp is `10.1.0rc3`. See [TheRock maintenance notes](docs/therock-rocm.md) for the source, update procedure and nixpkgs migration context. XRT still uses an individual recipe from the pinned `nix-strix-halo` source tree; its flake and Thunderbolt dependencies are not loaded. Strata ships `strata` (the HIP engine), `strata-server` (the OpenAI/Anthropic HTTP server, also the default for `nix run .#strata`) and `strata-vision` (CPU image encoder). It uses the shared TheRock ROCm 10.1 SDK, compiles GPU kernels only for `gfx1151`, and uses upstream's portable AVX2 CPU baseline. Model weights and vision projectors are supplied separately. Run `nix run .#strata -- --help` for server options, or invoke the engine directly with `nix shell .#strata -c strata --help`. For inference, pass `strata-server --engine strata --config /path/to/strata.json`; the upstream [server configuration](https://github.com/Niko1221/Strata/blob/v0.2.13/serve/server.py) uses `exe`, `args`, `cwd`, `tokenizer` and `model_name`. Set `exe` to the packaged `strata` executable and use writable model/log paths outside the Nix store. The ROCm 7.14.1 hipBLASLt tuning table from the reference recipe is not enabled with ROCm 10; the engine falls back to hipBLAS when no matching table is supplied. Crucible ships `crucible-server` (also `nix run .#crucible-strix-halo`) and `crucible-engine`. Upstream built the release engine with ROCm 7.2.4 and tested it with ROCm 10.1. This package uses the overlay's TheRock ROCm 10.1 runtime and the Python server from the matching tag. The package targets the Ryzen AI Max+ 395 / Radeon 8060S (`gfx1151`) with 128 GB RAM. Supply a compatible Qwen3.8-Flash-Next EXL3 pack separately: ```bash nix run .#crucible-strix-halo -- /path/to/exl3-pack --ctx 32768 ``` Use `--help` for serving options; the default endpoint is `http://127.0.0.1:8790`. Automatic release checks are disabled by default; update through Nix. The upstream checkout-management CLI (`setup`, `update`, and service installation) is not included. Model downloads and conversation state belong outside the Nix store. See the upstream [setup guide](https://github.com/jaedync/crucible-strix-halo/blob/v0.37.0/docs/QUICKSTART.md) for GPU memory configuration and model requirements. Strixite builds from source with the shared TheRock ROCm 10.1 SDK for `gfx1151` and the Zen 5 host CPU. It ships `strix_server` (the default entry point), `convert_qwen4exp`, `convert_ngram_table`, `transcode_ngram_table`, `inspect_strixw` and `check_stream_calls`. Supply the upstream `.strixw` weights, tokenizer and n-gram table separately, following the [model setup](https://github.com/shawnshekari/strixite/tree/v0.7.0#quick-start). ```bash STRIX_MODELS_DIR=/path/to/models nix run .#strixite -- --host 127.0.0.1 ``` The default port is 5300. `strix_server --help` lists all settings; the commented upstream configuration is installed at `share/strixite/strix-server.conf`. Model and prompt-cache paths stay outside the Nix store. The upstream defaults assume a dedicated 128 GB machine; see its [memory guide](https://github.com/shawnshekari/strixite/blob/v0.7.0/docs/memory.md) when sharing the GPU with a desktop or another model. `nix run .#strixite.tests.gpu` builds and runs the upstream kernel tutorial's CPU/GPU correctness checks on a machine with GPU access. ### nftablesbuilder Runtime Notes `nftablesbuilder` is a web interface for managing nftables. It consists of a root-launcher (`nftablesbuilder`) that spawns the unprivileged `webserver` binary and pipes encrypted commands between it and the `nft` binary. Before running it you must: 1. Copy the settings template to `/etc/nftablesbuilder` (the only fixed path): ```bash nix build .#nftablesbuilder cp result/share/nftablesbuilder/settings.example /etc/nftablesbuilder ``` Adjust paths inside (html, webserver, nft, savepath, TLS files). 2. Create a TLS key/certificate pair at the paths referenced by `tlskey`/`tlscert` (e.g. `openssl req -x509 -newkey rsa:2048 -nodes ...`). 3. Run the launcher as root (it needs to write `/etc/nftables.conf` and run `nft`); the web interface listens on `https://:1969`. Note: upstream publishes the GUI only as a prebuilt tarball on nftablesbuilder.eu (served with a self-signed certificate, hence the `curlOpts = "-k"` in the derivation); the source repository is missing the `settings` crate, which this overlay patches in. ### OpenCodeReview OpenCode Plugin (Home Manager) The `open-code-review` package bundles its OpenCode plugin (the plugin file plus runtime `node_modules`) as `passthru.opencode-plugin`, built from the same source revision as the CLI. A Home Manager module symlinks it into `~/.config/opencode/plugins/` and puts the `ocr` CLI on PATH: ```nix inputs.millerson-nix-overlay.url = "git+https://git.millerson.name/alex/millerson-overlay.nix.git"; inputs.home-manager.url = "github:nix-community/home-manager"; ``` ```nix # in your home-manager configuration imports = [ millerson-nix-overlay.homeManagerModules.default ]; programs.open-code-review = { enable = true; opencode.enable = true; # symlink plugin into ~/.config/opencode }; ``` Without Home Manager, symlink manually: ```bash plugin=$(nix build --print-out-paths \ git+https://git.millerson.name/alex/millerson-overlay.nix.git#open-code-review.passthru.opencode-plugin) mkdir -p ~/.config/opencode/plugins ln -sf $plugin/share/open-code-review/opencode/open-code-review.ts ~/.config/opencode/plugins/ ln -sfn $plugin/share/open-code-review/opencode/node_modules ~/.config/opencode/plugins/node_modules ``` Note: the `node_modules` symlink is shared across everything in the plugins directory; other manually-installed plugins with conflicting npm dependencies cannot coexist with it. ### Codex OAuth Proxy (systemd user service) On Linux with a running systemd user manager, the package provides `lib/systemd/user/codex-oauth-proxy.service`. Installing the package alone does not enable or start it. To use the packaged unit without Home Manager: ```bash package=$(nix build --no-link --print-out-paths \ git+https://git.millerson.name/alex/millerson-overlay.nix.git#codex-oauth-proxy) systemctl --user enable --now "$package/lib/systemd/user/codex-oauth-proxy.service" systemctl --user status codex-oauth-proxy.service ``` Keep the selected package in a Nix profile or another garbage-collection root while using its unit. To stop it and remove its enablement links: ```bash systemctl --user disable --now codex-oauth-proxy.service ``` Do not manage the same unit with both this procedure and Home Manager. #### Home Manager Import the module and make the package available in Home Manager's `pkgs`: ```nix imports = [ millerson-nix-overlay.homeManagerModules.default ]; nixpkgs.overlays = [ millerson-nix-overlay.overlays.default ]; programs.codex-oauth-proxy.enable = true; ``` The module installs the package and manages the user unit and its `default.target` link. Its package default selects `pkgs.millerson-nix-overlay.codex-oauth-proxy`, falling back to `pkgs.codex-oauth-proxy`. Importing `homeManagerModules.default` does not add an overlay. Supply the overlay to the actual Home Manager package set, or set `programs.codex-oauth-proxy.package` explicitly to this flake's package for your system. Apply the configuration with your normal Home Manager activation. Enabling starts this service without changing `systemd.user.startServices`. To stop and disable a previously module-managed service, keep the import and apply: ```nix programs.codex-oauth-proxy.enable = false; ``` Removing the import also removes the cleanup hook, so first activate with `enable = false`. A fresh disabled configuration leaves a manually managed same-named service untouched. Starting or stopping a module-managed service requires an available user manager; activation reports failure if it is unavailable. The module does not enable lingering or change the global service activation policy. #### State and security Both units use persistent OAuth state at `%S/codex-oauth-proxy/auth.json`, normally `~/.local/state/codex-oauth-proxy/auth.json` in a user manager. The state directory has mode `0700` and the service umask is `0077`. Upstream may migrate existing credentials when the destination is absent, and refreshes rewrite the credential file. Keep it writable and outside the Nix store and immutable Home Manager files. Disabling the service does not delete this credential state. Missing credentials do not prevent startup, but successful upstream requests require valid credentials. The server binds all interfaces on port `9879` by default, not just loopback. Restrict access with your network/firewall configuration. The service does not add TLS or network access controls. `ADMIN_API_KEY` protects upstream's admin endpoints. No default key is generated. If unset or empty, protected requests return HTTP 500; the server can still start. The packaged unit does not set this variable; a user-manager environment can supply it. Home Manager has an optional literal setting (placeholder only): ```nix programs.codex-oauth-proxy.admin_api_key = "REPLACE_WITH_NON_SECRET_PLACEHOLDER"; ``` The default `null` omits the assignment. A non-null value must contain printable ASCII; an empty string explicitly supplies an empty value. **A literal key in this option is public in the Nix store, retained generations, and systemd introspection. Do not put a confidential production key here.** This option is not a runtime secret-delivery mechanism. Both units discard stdout and stderr because upstream logs token previews and other potentially sensitive request/response data. Production mode does not establish redaction. Application logs are therefore unavailable in the journal; systemd status and exit diagnostics remain. Do not override these output settings without first addressing upstream token logging. ### PdfCraft (Home Manager) `pdfcraft` is built from source (no upstream binaries are downloaded). A Home Manager module installs both programs it ships: ```nix # in your home-manager configuration imports = [ millerson-nix-overlay.homeManagerModules.default ]; programs.pdfcraft.enable = true; ``` That puts `pdfcraft` (the desktop app) and `pdfcraft-cli` (headless tool runner and the opt-in MCP server, `pdfcraft-cli mcp`) on PATH. The module adds `programs.pdfcraft.package` to `home.packages`; the default is `pkgs.millerson-nix-overlay.pdfcraft`, so `nixpkgs.overlays` must carry this flake's overlay, or set `package` yourself. The package ships the two OCR models under `share/pdfcraft/models`, where the app looks beside its own `bin/` — `pdfcraft-cli run ocr_status` reports `"available": true`. The optional `craft-fonts` build input is not used, so Japanese interface text falls back to an installed system font. ## Development ### Prerequisites - Nix with flakes enabled - [treefmt-nix](https://github.com/numtide/treefmt-nix) for formatting (optional) ### Building Packages ```bash # Build all packages for current system nix build .#packages # Build specific package nix build .#mcp-gateway # Enter development shell nix develop ``` ### Project Structure ``` nix-overlay/ ├── flake.nix # Flake definition ├── treefmt.toml # Code formatting configuration (nixfmt) ├── overlays/ # Overlay implementations │ ├── default.nix # Binary-cache-friendly overlay │ └── shared-nixpkgs.nix # Dependency-sharing overlay ├── packages/ # Package definitions │ ├── agnix/ # Linter for AI agent config files (CLI + LSP + MCP server) │ ├── awg-tool/ # AmneziaWG parameter generation and SSH deployment CLI │ ├── awgen/ # Offline AmneziaWG configuration harmoniser and generator │ ├── aionui/ # AionUi - AI Cowork desktop app │ ├── codeaf/ # Coding harness and software factory for open models │ ├── container-use/ # Containerized environments for coding agents │ ├── default/ # Meta-package listing all packages │ ├── desloppify/ # Codebase health scanner for AI agents │ ├── ds4/ # DeepSeek V4 Flash/PRO inference engine (ROCm) │ ├── flake-inputs/ # Utility for caching flake inputs │ ├── freebuff/ # Free coding agent (Codebuff) │ ├── freetoken/ # Local MoE inference runtime (NVIDIA CUDA) │ ├── graphify/ # Knowledge graph generator for code folders │ ├── g3/ # AI coding agent (g3 + g3-studio) │ ├── haivemind/ # Multi-model AI consensus runner │ ├── hipengine/ # ROCm-native LLM inference engine for AMD GPUs │ ├── kubernetes-mcp-server/ # MCP server for Kubernetes and OpenShift │ ├── kyojin/ # ExLlamaV3-based inference engine for Strix Halo (gfx1151) │ ├── loop/ # Corporate messenger for your team │ ├── mcp-gateway/ # MCP protocol gateway │ ├── omniroute/ # Unified AI router with 160+ providers │ ├── open-code-review/ # AI code review CLI (deterministic + LLM agent) │ ├── pilotdeck/ # Task-oriented AI Agent platform (source-built Electron desktop app) │ ├── pdfcraft/ # PDF reader and editor in Rust, with pdfcraft-cli │ ├── radar/ # Kubernetes UI (topology, timeline, Helm, GitOps) │ ├── relay-free-llm/ # AI model provider routing gateway │ ├── skillsmcp/ # MCP server for Agent Skills │ ├── stakpak/ # DevOps AI agent for infrastructure automation │ └── traycer/ # AI orchestration desktop app (agentic coding) └── README.md ``` ### Adding New Packages 1. Create a new directory under `packages//` 2. Add a `package.nix` with the package definition 3. Create a `default.nix` that imports `package.nix` with proper arguments 4. The package will be automatically picked up by blueprint Example structure: ``` packages/my-package/ ├── default.nix # Import wrapper └── package.nix # Actual package definition ``` ## License See [LICENSE](LICENSE) file for details. ## Contributing Contributions are welcome! Please feel free to submit a Pull Request.