feat: add Nix flake and Devbox support

.github/workflows/nix-release.yml

@@ -0,0 +1,123 @@
+name: Update Nix flake
+
+# Checks whether flake.nix lags behind the latest GitHub release. If it does,
+# prefetches the new release's per-platform SRI hashes, rewrites flake.nix,
+# and opens a PR.
+#
+# Runs on a schedule instead of release: published because releases are created
+# with GITHUB_TOKEN (via softprops/action-gh-release), which does not start new
+# workflow runs. A daily lag-check is fully decoupled from how releases are
+# created and needs no PAT.
+
+on:
+  schedule:
+    - cron: "17 6 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: nix-flake-release
+  cancel-in-progress: true
+
+jobs:
+  update-flake:
+    name: Bump flake version + hashes if lagging
+    runs-on: ubuntu-latest
+    if: github.repository == 'coleam00/Archon'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+
+      - name: Check for lag and rewrite flake.nix
+        env:
+          # system|asset-substring — one per line. The substring must uniquely
+          # match the release asset filename for that system.
+          ASSET_MAP: |
+            x86_64-linux|archon-linux-x64
+            aarch64-linux|archon-linux-arm64
+            aarch64-darwin|archon-darwin-arm64
+        run: |
+          set -euo pipefail
+          tag=$(curl -fsSL -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/releases/latest" \
+            | python3 -c 'import json,sys; print(json.load(sys.stdin)["tag_name"])')
+          latest="${tag#v}"
+          current=$(python3 -c 'import re; s=open("flake.nix").read(); m=re.search(r"version = \"([^\"]*)\";", s); print(m.group(1))')
+          echo "flake.nix version: $current  |  latest release: $latest (tag $tag)"
+          if [ "$current" = "$latest" ]; then
+            echo "flake.nix is up to date; nothing to do."
+            echo "LAGGING=no" >> "$GITHUB_ENV"
+            exit 0
+          fi
+          echo "LAGGING=yes" >> "$GITHUB_ENV"
+          echo "VERSION=$latest" >> "$GITHUB_ENV"
+          export TAG="$tag"
+          python3 <<'PYEOF'
+          import json, os, re, subprocess, urllib.request
+          tag = os.environ["TAG"]
+          version = tag.lstrip("v")
+          repo = os.environ["GITHUB_REPOSITORY"]
+          with urllib.request.urlopen(
+              f"https://api.github.com/repos/{repo}/releases/latest") as r:
+              release = json.load(r)
+          # Drop sibling checksum files so a binary substring does not also
+          # match its companion checksum file.
+          names = {a["name"] for a in release["assets"]
+                   if not a["name"].endswith(".sha256")}
+          asset_map = {}
+          for line in os.environ["ASSET_MAP"].splitlines():
+              line = line.strip()
+              if not line or line.startswith("#"):
+                  continue
+              sys_, sub = line.split("|", 1)
+              asset_map[sys_.strip()] = sub.strip()
+          src = open("flake.nix").read()
+          src, n = re.subn(r'version = "[^"]*";', f'version = "{version}";', src, count=1)
+          if n != 1:
+              raise SystemExit('could not find version = "..." in flake.nix')
+          for sys_, sub in asset_map.items():
+              match = next((n for n in names if sub in n), None)
+              if not match:
+                  raise SystemExit(f"no asset for {sys_} ({sub}) in {tag}; have: {sorted(names)}")
+              url = f"https://github.com/{repo}/releases/download/{tag}/{match}"
+              out = json.loads(subprocess.check_output(
+                  ["nix", "store", "prefetch-file", "--json", "--hash-type", "sha256", url]))
+              sri = out["hash"]
+              pat = re.compile(r'("' + re.escape(sys_) + r'" = \{[^}]*\})', re.S)
+              def repl(m):
+                  b = m.group(1)
+                  b = re.sub(r'file = "[^"]*";', f'file = "{match}";', b, count=1)
+                  b = re.sub(r'sha256 = "[^"]*";', f'sha256 = "{sri}";', b, count=1)
+                  return b
+              src, n = pat.subn(repl, src, count=1)
+              if n != 1:
+                  raise SystemExit(f"could not find assets block for {sys_} in flake.nix")
+          open("flake.nix", "w").write(src)
+          print(f"bumped flake.nix to {version}: {list(asset_map)}")
+          PYEOF
+
+      - name: Open PR
+        if: env.LAGGING == 'yes'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "chore(nix): bump flake to v${{ env.VERSION }}"
+          title: "chore(nix): bump flake to v${{ env.VERSION }}"
+          branch: chore/nix-flake-v${{ env.VERSION }}
+          base: dev
+          body: |
+            Auto-generated by the `Update Nix flake` workflow (daily lag-check).
+            The latest GitHub release is v${{ env.VERSION }} but `flake.nix` was
+            pinned to an older version. This PR bumps `version` and refreshes the per-platform SRI
+            hashes by prefetching the new release assets.
+
+            Note: PRs opened by `GITHUB_TOKEN` do not trigger downstream workflow runs (e.g. CI),
+            so this PR will show no checks. The diff is a 5-line hash bump with no source changes —
+            safe to merge as-is.

.github/workflows/nix.yml

@@ -0,0 +1,81 @@
+name: Nix flake
+
+# Validates the flake (flake.nix). For most nixify targets Nix is a side
+# concern, so this job is path-filtered to the flake files — it fires only
+# when they change, not on every source/docs commit.
+#
+# Steps, in order of what they catch:
+#   1. nix flake check --all-systems  — every system's outputs evaluate
+#      (including darwin on an ubuntu runner).
+#   2. nix build .#default            — fetchurl + autoPatchelf + install
+#      layout actually realises for the runner's system.
+#   3. nix run .#default -- --version — the patched binary actually execs.
+#      This is the only step that catches the `let ... in rec` shadowing
+#      class of bug (passes flake check, fails nix run). Do NOT drop it.
+#   4. nix build .#source (if #source output exists) — the from-source
+#      build path realises for the runner's system. Skip if the flake
+#      does not expose a #source output.
+
+on:
+  push:
+    branches: [dev]
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - "**/*.nix"
+      - ".github/workflows/nix.yml"
+  pull_request:
+    branches: [dev]
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - "**/*.nix"
+      - ".github/workflows/nix.yml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: nix-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: nix flake check
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install Nix
+        # DeterminateSystems/nix-installer-action installs Nix natively on the
+        # runner so `nix build` / `nix run` work directly (a Docker-container
+        # approach can run `nix flake check` but is awkward for build+smoke).
+        uses: DeterminateSystems/nix-installer-action@v16
+
+      - name: nix flake check --all-systems
+        # --no-build: evaluate every system's outputs (including darwin on
+        # ubuntu) without realising them. Without --no-build, `nix flake
+        # check` builds every derivation in `checks`, which fails for
+        # non-native systems (darwin stdenv can't run on linux). The
+        # build/run steps below handle realisation for the runner's system.
+        run: nix flake check --all-systems --no-build
+
+      - name: nix build .#default
+        run: nix build .#default --print-build-logs
+
+      - name: nix run .#default -- --version
+        run: nix run .#default -- --version
+
+      - name: nix build .#source (if exists)
+        # Exercises the from-source build path. Skip if the flake does not
+        # expose a #source output (source-build-only flakes use #default).
+        run: |
+          if nix flake show --json 2>/dev/null | jq -e 'any(.packages[]?; has("source"))' >/dev/null 2>&1; then
+            nix build .#source --print-build-logs
+          else
+            echo "No #source output — skipping"
+          fi

.gitignore

@@ -120,3 +120,9 @@ packages/server/.env
 skills-lock.json
 test-results/
 .archon/ralph/
+
+# Nix build result symlinks
+/result
+/result-*
+# Devbox generated artifacts
+.devbox/

README.md

@@ -171,6 +171,49 @@ irm https://archon.diy/install.ps1 | iex
 brew install coleam00/archon/archon
 ```
 
+### Nix
+
+The project provides optional Nix flake outputs for users who already use Nix. The flake exposes the prebuilt release binary as `#prebuilt` (also `#default`) and a from-source build as `#source`.
+
+```bash
+# Run without installing (prebuilt binary, default)
+nix run github:coleam00/Archon
+
+# Install into your profile
+nix profile add github:coleam00/Archon
+
+# Explicitly choose prebuilt or source
+nix run github:coleam00/Archon#prebuilt
+nix run github:coleam00/Archon#source
+```
+
+The flake tracks the default branch and is auto-bumped to the latest release by a
+daily [workflow](.github/workflows/nix-release.yml), so `github:coleam00/Archon`
+is updated daily when the version-bump PR is merged. (Release tags are cut before
+the bump lands, so `github:coleam00/Archon/vX.Y.Z` is not a valid pin — use the
+nixpkgs package or a specific commit SHA if you need reproducibility.)
+
+### Devbox
+
+For reproducible development environments, use Devbox:
+
+```bash
+# Install Devbox first (if not already installed)
+curl -fsSL https://get.jetify.dev/devbox | bash
+
+# Initialize the environment
+devbox shell
+
+# Build the project
+devbox run build
+```
+
+Or install Devbox via Homebrew:
+
+```bash
+brew install jetify-com/devbox/devbox
+```
+
 > **Compiled binaries need a `CLAUDE_BIN_PATH`.** The quick-install binaries
 > don't bundle Claude Code. Install it separately, then point Archon at it:
 >

devbox.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.12.0/.schema/devbox.schema.json",
+  "packages": [
+    "bun"
+  ],
+  "shell": {
+    "init_hook": [
+      "echo 'Welcome to the Archon Devbox environment!'"
+    ],
+    "scripts": {
+      "install": "bun install",
+      "build": "bun run build",
+      "test": "bun run test",
+      "dev": "bun run dev",
+      "validate": "bun run validate"
+    }
+  }
+}