feat: add Nix flake and Devbox support

[levonk]

Summary

• Problem: Nix/NixOS users have no way to install Archon via Nix flakes. Issue feat(distribution): add Nix flake support for one-command installation #1766 requests this support.
• Why it matters: Nix users want one-command install/run (nix run github:coleam00/Archon) with hermetic, reproducible builds. This is a previously-rejected PR (feat: add Nix flake and Devbox support #1767) reworked to address all reviewer feedback.
• What changed: Added flake.nix with both #prebuilt (prebuilt release binary) and #source (from-source build via bun build --compile) outputs, devbox.json for reproducible dev environments, CI workflow (nix.yml) that validates the flake, hash automation workflow (nix-release.yml) that auto-bumps version + hashes on each release, and documentation updates across README, installation guide, landing page, and release guide.
• What did not change (scope boundary): No source code, build scripts, existing CI, or package configuration was modified. This is purely additive — new files only, plus .gitignore entries and documentation updates.

UX Journey

Before

Nix user                    GitHub
──────                      ──────
wants to install Archon
no flake.nix exists
→ must clone + bun install + bun run cli
  (requires Bun, Node ecosystem knowledge)
  (no reproducible environment)

After

Nix user                    GitHub                    nix-release.yml
──────                      ──────                    ────────────────
wants to install Archon
nix run github:coleam00/Archon ──▶ fetches flake
                                 builds/fetches binary
                                 execs archon --version
sees "Archon CLI v0.5.0" ◀──────

                              [daily lag-check runs]
                              compares flake version to latest release
                              if lagging: prefetch hashes, open bump PR ◀──

Architecture Diagram

Before

Release pipeline ──▶ GitHub Releases (prebuilt binaries)
Homebrew formula  ──▶ brew install
Install script    ──▶ curl | bash
Docker image      ──▶ ghcr.io

After

Release pipeline ──▶ GitHub Releases (prebuilt binaries)
Homebrew formula  ──▶ brew install
Install script    ──▶ curl | bash
Docker image      ──▶ ghcr.io
[+] flake.nix     ──▶ nix run / nix profile add (#prebuilt, #source)
[+] devbox.json   ──▶ devbox shell (reproducible dev env)
[+] nix.yml       ──▶ CI: nix flake check + build + run (path-filtered)
[+] nix-release.yml ──▶ daily lag-check: auto-bump version + hashes

Connection inventory (list every module-to-module edge, mark changes):

From	To	Status	Notes
flake.nix	GitHub Releases	new	fetchurl downloads prebuilt binary per platform
flake.nix	bun.lock + source	new	#source output builds from source via bun build --compile
nix-release.yml	flake.nix	new	auto-bumps version + sha256 hashes, opens PR
nix.yml	flake.nix	new	CI validates flake on Nix file changes
devbox.json	nixpkgs	new	pulls bun package for dev environment
.gitignore	.devbox/	new	prevents committing machine-local devbox artifacts
README.md	flake.nix	new	documents nix run / nix profile add commands
installation.md	flake.nix	new	### Nix (Flakes) subsection under Quick Install
docs.mdx	flake.nix	new	Nix code block in :::code-group install splash
releasing.md	nix-release.yml	new	### 5. Update Nix Flake (Automatic) section

Label Snapshot

• Risk: risk: low
• Size: S
• Scope: ci, docs, dependencies
• Module: ci:nix, docs:installation

Change Metadata

• Change type: feature
• Primary scope: multi

Linked Issue

• Closes feat(distribution): add Nix flake support for one-command installation #1766
• Supersedes feat: add Nix flake and Devbox support #1767 (previous attempt, closed — this PR addresses all rejection feedback)

Validation Evidence (required)

# Nix flake validation (all 4 systems evaluate)
nix flake check --all-systems --no-build
# → exit 0 (all derivations evaluated, no errors)

# Prebuilt binary builds and runs on x86_64-darwin
nix build .#default --print-build-logs
# → exit 0 (fetchurl + install succeeded)

nix run .#default -- --version
# → "Archon CLI v0.5.0 / Platform: darwin-x64 / Build: binary"

# Named output works
nix run .#archon -- --version
# → "Archon CLI v0.5.0"

# bun run validate — NOT run locally (bun not installed on this machine).
# The Nix changes are purely additive (no source code touched), so
# type-check, lint, format:check, and tests are unaffected.
# CI will run `bun run validate` on the PR.

• Evidence provided: nix flake check --all-systems --no-build passes (exit 0), nix build .#default succeeds, nix run .#default -- --version outputs "Archon CLI v0.5.0"
• bun run validate intentionally skipped locally: bun is not installed on the development machine. The changes are additive-only (new files + .gitignore + docs), no TypeScript/source code was modified. CI will exercise the full validate suite.

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? Yes — flake.nix fetches prebuilt binaries from github.com/coleam00/Archon/releases (same artifacts the install script and Homebrew formula already fetch). nix-release.yml calls the GitHub API to check for new releases and prefetches hashes via nix store prefetch-file.
• Secrets/tokens handling changed? No — uses GITHUB_TOKEN with standard contents: write and pull-requests: write permissions for the hash automation workflow.
• File system access scope changed? No
• If any Yes, describe risk and mitigation: The network calls fetch the same release binaries that the existing install paths (curl script, Homebrew, Docker) already fetch. The hash automation workflow only runs on coleam00/Archon (guarded by if: github.repository == 'coleam00/Archon').

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Database migration needed? No
• If yes, exact upgrade steps: N/A — purely additive, no existing functionality affected.

Human Verification (required)

What was personally validated beyond CI:

• Verified scenarios: nix flake check --all-systems --no-build passes for all 4 systems (x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin). nix build .#default succeeds on x86_64-darwin. nix run .#default -- --version outputs "Archon CLI v0.5.0". nix run .#archon -- --version confirms the named output works.
• Edge cases checked: .devbox/ is gitignored (verified with git check-ignore .devbox/ → .devbox/). No .devbox/ directory or devbox.lock file is staged or committed. The nix-release.yml ASSET_MAP matches Archon's actual release asset names (archon-linux-x64, archon-darwin-arm64, etc.).
• What was not verified: bun run validate (bun not installed locally — CI will run it). The #source build path (requires bun in the Nix sandbox — CI on ubuntu-latest will exercise it). The nix-release.yml workflow's actual hash-rewrite path (only exercised when a real new release outpaces the flake — the manual workflow_dispatch run can verify the "up to date" path).

Side Effects / Blast radius (required)

• Affected subsystems/workflows: None — all changes are additive. No existing CI workflows, build scripts, or source code are modified.
• Potential unintended effects: The nix.yml CI workflow fires on changes to flake.nix, flake.lock, **/*.nix, and .github/workflows/nix.yml only (path-filtered). It will not fire on source/docs commits. The nix-release.yml workflow runs daily on a schedule and only acts when the flake version lags behind the latest release.
• Guardrails/monitoring for early detection: nix.yml CI catches flake breakage on every Nix file change. The nix-release.yml daily lag-check catches release/flake version drift.

Rollback Plan (required)

• Fast rollback command/path: git revert <commit-sha> — the entire PR is a single commit. All files are new (flake.nix, devbox.json, workflows) or additive (.gitignore entries, docs sections). Reverting removes them cleanly with no side effects.
• Feature flags or config toggles (if any): None needed — Nix flake is opt-in (users must have Nix installed and choose to use it).
• Observable failure symptoms: If the flake breaks, nix run github:coleam00/Archon fails with a Nix evaluation/build error. CI (nix.yml) catches this before merge. If the hash automation fails, the flake version falls behind the latest release — users get the previous release, not a broken install.

Risks and Mitigations

• Risk: nixpkgs-unstable dropped x86_64-darwin support in 26.11.
  • Mitigation: The flake uses a dual-input approach — nixpkgs-unstable for Linux, nixpkgs-26.05-darwin for Darwin (including x86_64-darwin, supported until end of 2026). This preserves all 4 platforms Archon ships binaries for.
• Risk: The #source build's deps FOD uses pkgs.lib.fakeSha256 as a placeholder — the from-source build will fail until the correct hash is computed.
  • Mitigation: The #prebuilt output (the default) works without the FOD hash. CI's nix build .#source step will surface the correct hash on first run. The FOD hash can then be updated in a follow-up. The prebuilt path is the primary install path; source build is for users who explicitly want it.
• Risk: The nix-release.yml hash automation workflow is not exercised by the PR's own CI.
  • Mitigation: After merge, trigger it manually via workflow_dispatch to verify the "up to date, nothing to do" path works. The actual hash-rewrite path is only exercised when a real new release outpaces the flake.
• Risk: bun run validate was not run locally (bun not installed on dev machine).
  • Mitigation: Changes are purely additive (no source code modified). CI will run the full validate suite on the PR.

Summary by CodeRabbit

• New Features
  • Added Nix flake support to run prebuilt release binaries or build from source across supported platforms.
  • Added a Devbox environment (bun) with command aliases for install, build, test, dev, and validation.
• Documentation
  • Expanded Nix and Devbox “Getting Started” and installation guidance, including update behavior and version pinning.
• Chores
  • Added CI to validate Nix flake checks on dev and relevant changes.
  • Added an automated daily flake version/hash updater that opens PRs when new releases are detected.
  • Updated .gitignore for Nix build artifacts and Devbox files.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds multi-platform Nix packaging for prebuilt and source Archon binaries, Devbox configuration, Nix validation and release-update workflows, generated-artifact ignores, and installation and release documentation.

Changes

Nix distribution

Layer / File(s)	Summary
Flake inputs and package derivations flake.nix	Defines platform assets, prebuilt release downloads, fixed-output Bun dependencies, and source compilation derivations.
Flake outputs and checks flake.nix	Exports packages and runnable apps for each system, with checks for prebuilt and source derivations.
Flake validation and release updates .github/workflows/nix.yml, .github/workflows/nix-release.yml	Validates Nix outputs in CI and automatically updates release versions and asset hashes before opening a pull request.
Development setup and installation guidance devbox.json, .gitignore, README.md, packages/docs-web/src/content/docs/docs.mdx, packages/docs-web/src/content/docs/getting-started/installation.md, packages/docs-web/src/content/docs/contributing/releasing.md	Adds Devbox commands, ignores generated artifacts, and documents Nix and Devbox installation and update workflows.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant GitHub Actions
  participant GitHub Releases
  participant nix-release.yml
  participant flake.nix
  participant Pull Request
  GitHub Actions->>GitHub Releases: query latest release tag and assets
  GitHub Releases-->>nix-release.yml: return release metadata
  nix-release.yml->>flake.nix: update version, asset files, and hashes
  nix-release.yml->>Pull Request: create version bump pull request

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Clear and specific; it summarizes the main addition of Nix flake plus Devbox support.
Description check	✅ Passed	It includes the required summary, UX, architecture, metadata, validation, risks, and rollout sections, with only minor specificity gaps.
Linked Issues check	✅ Passed	The PR adds the flake, devbox config, .gitignore updates, README/docs, and validation needed for #1766.
Out of Scope Changes check	✅ Passed	No clearly unrelated code changes are evident; the added CI, automation, and docs all support the Nix/Devbox scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/nix-release.yml:
- Around line 43-46: Add the missing x86_64-darwin to ASSET_MAP, mapping it to
the corresponding Intel macOS asset name used by the flake’s assets block.
Preserve the existing Linux and arm64 macOS mappings.

In @.github/workflows/nix.yml:
- Line 77: Update the jq filter in the nix flake source-detection condition to
iterate through the system-specific entries under packages and detect whether
any contains source, so the source build runs when available.

In `@flake.nix`:
- Around line 127-129: Replace the placeholder pkgs.lib.fakeSha256 assigned to
outputHash in the source fixed-output derivation with the actual computed hash;
if Bun resolves platform-specific optional dependencies, configure the hash per
system. Ensure packages.source and checks.source build successfully with the
resulting hash configuration.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b748ad2f-9d9c-4bfa-9fba-203f488a84a2

📥 Commits

Reviewing files that changed from the base of the PR and between 92b9bba and 41cd214.

⛔ Files ignored due to path filters (1)

• flake.lock is excluded by !**/*.lock

📒 Files selected for processing (9)

• .github/workflows/nix-release.yml
• .github/workflows/nix.yml
• .gitignore
• README.md
• devbox.json
• flake.nix
• packages/docs-web/src/content/docs/contributing/releasing.md
• packages/docs-web/src/content/docs/docs.mdx
• packages/docs-web/src/content/docs/getting-started/installation.md

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/docs-web/src/content/docs/getting-started/installation.md`:
- Around line 52-54: Update the installation documentation statement about
github:coleam00/Archon to avoid claiming it always serves the current release;
explain that it is updated daily only when the version-bump PR is merged, while
preserving the existing reproducibility guidance.
- Around line 62-64: Update the flake-based installation example to use the
actual flake input name, such as archon, instead of the <repo> placeholder.
Clarify that nix flake update must be run from the consuming flake directory if
needed, while preserving the surrounding installation guidance.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5d104782-93e3-4c63-9c29-673ec2417b3a

📥 Commits

Reviewing files that changed from the base of the PR and between 41cd214 and c206e96.

⛔ Files ignored due to path filters (1)

• flake.lock is excluded by !**/*.lock

📒 Files selected for processing (9)

• .github/workflows/nix-release.yml
• .github/workflows/nix.yml
• .gitignore
• README.md
• devbox.json
• flake.nix
• packages/docs-web/src/content/docs/contributing/releasing.md
• packages/docs-web/src/content/docs/docs.mdx
• packages/docs-web/src/content/docs/getting-started/installation.md

🚧 Files skipped from review as they are similar to previous changes (4)

• devbox.json
• .github/workflows/nix.yml
• flake.nix
• .github/workflows/nix-release.yml

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Around line 190-194: Update the README flake pinning guidance to clarify that
release tags such as github:coleam00/Archon/vX.Y.Z are valid but may point to
stale release metadata because tags can be created before the automated flake
bump. Direct users requiring an exact reproducible binary to pin the post-bump
commit SHA, while preserving the existing nixpkgs alternative.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 721bdb18-06ab-470e-80b6-51e369b50c88

📥 Commits

Reviewing files that changed from the base of the PR and between c206e96 and e1d9ad6.

⛔ Files ignored due to path filters (1)

• flake.lock is excluded by !**/*.lock

📒 Files selected for processing (9)

• .github/workflows/nix-release.yml
• .github/workflows/nix.yml
• .gitignore
• README.md
• devbox.json
• flake.nix
• packages/docs-web/src/content/docs/contributing/releasing.md
• packages/docs-web/src/content/docs/docs.mdx
• packages/docs-web/src/content/docs/getting-started/installation.md

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/docs-web/src/content/docs/docs.mdx
• .gitignore
• devbox.json
• .github/workflows/nix-release.yml
• .github/workflows/nix.yml
• flake.nix

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

set -euo pipefail

printf '\n== README excerpt ==\n'
sed -n '176,206p' README.md

printf '\n== workflow search ==\n'
fd -a 'nix-release.yml' . || true
rg -n "auto-bump|release tags|github:coleam00/Archon|vX\.Y\.Z|flake" .github README.md -S || true

if [ -f .github/workflows/nix-release.yml ]; then
  printf '\n== nix-release workflow ==\n'
  sed -n '1,220p' .github/workflows/nix-release.yml
fi

Repository: coleam00/Archon

Length of output: 10892

---

Clarify the tag pinning guidance.

github:coleam00/Archon/vX.Y.Z is valid flake syntax, but these release tags can land before the automated flake bump. Call out that a tag may point at stale release metadata; use the post-bump commit SHA when you need an exact, reproducible binary.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~191-~191: The official name of this software platform is spelled with a capital “H”.
Context: ... the latest release by a daily workflow, so `github:...

(GITHUB)

---

[uncategorized] ~191-~191: The official name of this software platform is spelled with a capital “H”.
Context: ...(.github/workflows/nix-release.yml), so github:coleam00/Archon is updated daily when ...

(GITHUB)

---

[uncategorized] ~193-~193: The official name of this software platform is spelled with a capital “H”.
Context: ... tags are cut before the bump lands, so github:coleam00/Archon/vX.Y.Z is not a valid ...

(GITHUB)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 190 - 194, Update the README flake pinning guidance
to clarify that release tags such as github:coleam00/Archon/vX.Y.Z are valid but
may point to stale release metadata because tags can be created before the
automated flake bump. Direct users requiring an exact reproducible binary to pin
the post-bump commit SHA, while preserving the existing nixpkgs alternative.

[Wirasm]

Thanks for coming back at this with the source-building path and CI — that's a real response to what I asked for when I closed #1767, and the dual-nixpkgs split for x86_64-darwin is a genuinely nice piece of work. The rec-shadowing warning comment in apps was a good catch too.

I'm declining it on direction, and I want to be precise about why so it doesn't read as arbitrary or as a moving target.

The position

direction.md §deployment-recipes says alternative proxies and infra recipes live in docs as community-maintained examples rather than as configs Archon maintains, because each maintained config doubles a security-critical surface. The same reasoning transposes to distribution: each hash-pinned install channel doubles a release-critical surface.

We already maintain four channels — the curl/PowerShell installer, Homebrew, Docker, and the GitHub release binaries. Homebrew alone costs a manual version+SHA update every release. I don't want a fifth, and I especially don't want one that adds three hash surfaces at once: the four prebuilt binary hashes, the flake.lock nixpkgs pins, and the #source deps fixed-output hash.

I'm adding a §distribution-channels clause to direction.md so this is a stated position rather than a per-PR judgment call, and so the next person proposing AUR or Scoop or winget gets an answer before writing 584 lines.

Where "purely additive" doesn't hold

This is the part that decided it for me. Three things in the PR are not ignorable:

1. docs/contributing/releasing.md gains a numbered step — every release now has a Nix chore.
2. nix-release.yml is a permanent daily cron with contents: write and pull-requests: write that rewrites flake.nix and opens PRs. Its own body says the resulting PR "will show no checks … safe to merge as-is," which is a self-declared unreviewed-merge path.
3. README, the installation page, and the landing-page install splash advertise nix run github:coleam00/Archon as a supported path. Once it's advertised, breakage is my inbox.

The mitigation for hash rot is itself a maintained surface, and it has a bug that proves the point:

• ASSET_MAP in nix-release.yml omits x86_64-darwin, but the fetch URL interpolates ${version}. The first successful auto-bump changes the URL for all four systems while refreshing only three hashes — Intel Macs break with a hash mismatch. archon-darwin-x64 does exist in the v0.6.0 assets, so it's a pure omission. CodeRabbit flagged it and it's unaddressed.
• CI structurally cannot catch that. nix flake check --all-systems --no-build evaluates without realising, so a fetch-hash mismatch is invisible to it, and nix build .#default only runs the ubuntu runner's system. The one channel-breaking failure the automation can introduce is the one its CI can't see.

And the source path has the same silent-rot problem, relocated

#source's deps fixed-output derivation pins the node_modules tree with a single outputHash, so any bun.lock change invalidates it — and we've changed bun.lock 16 times in the last 60 days. nix.yml's path filter is flake.nix, flake.lock, **/*.nix and itself; bun.lock isn't in it, so a dependency bump never triggers Nix CI and the breakage reaches users instead. That's the exact failure I cited on #1767, moved from the binary hash to the deps hash.

Separately, one outputHash can't be valid across four platforms: bun.lock carries platform-gated optionals (@esbuild/darwin-arm64, @esbuild/linux-x64, @esbuild/darwin-x64), so the installed tree differs per system. CodeRabbit raised this too.

Two smaller things: flake.nix says version = "0.5.0" while we're on v0.6.0, so merging today would serve a superseded release until the bot's first run — which then hits the Intel-Mac bug. And .gitignore adds .devbox/ but not devbox.lock, so the first devbox shell leaves an untracked lockfile dirty in the repo root.

What I'd take instead, in order of preference

1. Package Archon in nixpkgs upstream. That's where the Nix ecosystem expects a binary-release package to live, it gets nixpkgs' own CI and hash-update bots for free, and it costs us nothing per release. Do that and I'll link it prominently from the installation docs and the README. This is also the outcome that actually serves Nix users best — a flake in our repo that rots between releases serves them worse than a maintained nixpkgs derivation.
2. A docs recipe — a Getting Started section, or an examples/nix/ directory holding the flake as a copy-paste starter, framed as community-maintained exactly the way we frame Traefik and Nginx. I'll merge that.

On devbox.json specifically

It's sold as reproducible environments but pins nothing: "packages": ["bun"] with no version and no committed devbox.lock, while CI pins bun 1.3.11 across five workflows and package.json#engines says ^1.3.0. So it would hand us a second toolchain source of truth that drifts from the one we actually validate against — the opposite of the reproducibility it's meant to buy. #source has the same issue, building with pkgs.bun from nixpkgs-unstable rather than 1.3.11.

That half I'd decline even if the flake landed.

---

Genuinely sorry it took a second round to land on a clear position — that's on me for closing #1767 with an invitation I hadn't thought through to the maintenance end. The work here is competent and the problems I've listed are mostly structural rather than mistakes. If you go the nixpkgs route I'll help however I can from this side, and I'll review a docs-recipe PR quickly.

[levonk]

Win some, lose some :) The feedback is certainly appreciated, and I also appreciate the work you folks do regardless.