docs(research): bundle-file dev-PC substrate architecture (Nix + Home Manager + k3d + Headscale + lend-resources pattern)#4809
Merged
AceHack merged 2 commits intoMay 24, 2026
Conversation
… Manager + k3d + Headscale + lend-resources pattern) Sibling to PR #4808 (cluster substrate). Per Aaron 2026-05-24 'yes bundle-file it (shadow*)' confirmation. PRIMARY STACK DECIDED (lightweight-first per Aaron-stated principle 'Lets do whatever is lightweigh now and ease into more heavy weight stuff'): LAYER 1 — Reproducible dev-PC substrate (Nix): - macOS: Determinate Systems Nix installer + nix-darwin + Home Manager - Linux: Nix package manager + Home Manager (on existing distro) - Windows: WSL2 + Nix in WSL2 + Home Manager - One flake repo covers cluster + dev PCs + every user's home directory LAYER 2 — Local k8s for testing: - k3d (lighter than kind) on each dev PC for manifest testing + GitOps practice WITHOUT touching production cluster LAYER 3 — Background service (lend-resources pattern): - Aaron framing: 'Dev boxes can be like lending resources to cluster' - Lightweight Bun/Node daemon polling NATS queue for opt-in work - NOT first-class k8s nodes (avoid trust-boundary issues) - Heavier alternative (k3s agent, Liqo federation) deferred LAYER 4 — Network substrate (Headscale + Tailscale): - Aaron framing: 'Tailscale is good but we also want headscale' - Tailscale clients on each device - Self-hosted Headscale control plane (sovereignty over user/device/ACL state; no commercial dependency; free at any node count) - DERP relay optional for NAT-traversal fallback DEFERRED (heavyweight ease-into-later): - Liqo federation - KubeFed v2 - k3s agent per dev PC - Custom DERP relays - Native Nix on Windows (when ships) - Full NixOS desktop on dev Linux box 5 open questions captured: Headscale deployment location, background- service queue tech, authentication boundary, lending workload-class restrictions, Addison's preferences (pending direct articulation per observation-not-fact consent discipline). Maps each choice to framework discipline (DST, glass-halo, NCI floor, m/acc-multi-oracle, bandwidth-served, additive, Aaron lightweight-first principle, Addison observation-not-fact discipline). Composes with cluster substrate archive + Addison consent archive + 9 framework rules. Authored via git plumbing fallback.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8ac596d289
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
Adds a research archive documenting the decided dev-PC substrate architecture that complements the sibling cluster-substrate archive (PR #4808), capturing a lightweight-first stack (Nix + Home Manager, local k8s via kind/k3d, Headscale/Tailscale overlay, and an opt-in “lend resources” daemon pattern).
Changes:
- Adds a comprehensive dev-PC substrate decision archive under
docs/research/. - Documents the primary choices plus deferred “ease-into-later” options and open questions.
- Cross-links the dev-PC archive to the sibling cluster archive and relevant framework rules.
…ate-prefix Two factual corrections caught by Codex P2 + Copilot: 1. Line 3: "Date decided: 2026-05-24 (~03:30Z)" was ~1.5h in the future relative to commit time (02:03Z). Corrected to ~02:03Z matching `gh pr view 4809 --json commits` last committed date. 2. Line 4: consent-file reference `addison-consent-pattern-observation-not-fact-discipline-aaron-otto.md` missing date prefix; actual file on disk is `2026-05-24-addison-consent-pattern-observation-not-fact-discipline-aaron-otto.md`. Added date prefix; reference now resolves. Mechanical fixes only. Co-Authored-By: Claude <noreply@anthropic.com>
AceHack
deleted the
otto/research-dev-pc-substrate-nix-home-manager-k3d-headscale-2026-05-24
branch
This was referenced May 24, 2026
AceHack
added a commit
that referenced
this pull request
May 24, 2026
… Manager + k3d + Headscale + lend-resources pattern) (#4809) * docs(research): bundle-file dev-PC substrate architecture (Nix + Home Manager + k3d + Headscale + lend-resources pattern) Sibling to PR #4808 (cluster substrate). Per Aaron 2026-05-24 'yes bundle-file it (shadow*)' confirmation. PRIMARY STACK DECIDED (lightweight-first per Aaron-stated principle 'Lets do whatever is lightweigh now and ease into more heavy weight stuff'): LAYER 1 — Reproducible dev-PC substrate (Nix): - macOS: Determinate Systems Nix installer + nix-darwin + Home Manager - Linux: Nix package manager + Home Manager (on existing distro) - Windows: WSL2 + Nix in WSL2 + Home Manager - One flake repo covers cluster + dev PCs + every user's home directory LAYER 2 — Local k8s for testing: - k3d (lighter than kind) on each dev PC for manifest testing + GitOps practice WITHOUT touching production cluster LAYER 3 — Background service (lend-resources pattern): - Aaron framing: 'Dev boxes can be like lending resources to cluster' - Lightweight Bun/Node daemon polling NATS queue for opt-in work - NOT first-class k8s nodes (avoid trust-boundary issues) - Heavier alternative (k3s agent, Liqo federation) deferred LAYER 4 — Network substrate (Headscale + Tailscale): - Aaron framing: 'Tailscale is good but we also want headscale' - Tailscale clients on each device - Self-hosted Headscale control plane (sovereignty over user/device/ACL state; no commercial dependency; free at any node count) - DERP relay optional for NAT-traversal fallback DEFERRED (heavyweight ease-into-later): - Liqo federation - KubeFed v2 - k3s agent per dev PC - Custom DERP relays - Native Nix on Windows (when ships) - Full NixOS desktop on dev Linux box 5 open questions captured: Headscale deployment location, background- service queue tech, authentication boundary, lending workload-class restrictions, Addison's preferences (pending direct articulation per observation-not-fact consent discipline). Maps each choice to framework discipline (DST, glass-halo, NCI floor, m/acc-multi-oracle, bandwidth-served, additive, Aaron lightweight-first principle, Addison observation-not-fact discipline). Composes with cluster substrate archive + Addison consent archive + 9 framework rules. Authored via git plumbing fallback. * fix(PR #4809): correct impossible decision timestamp + consent-file date-prefix Two factual corrections caught by Codex P2 + Copilot: 1. Line 3: "Date decided: 2026-05-24 (~03:30Z)" was ~1.5h in the future relative to commit time (02:03Z). Corrected to ~02:03Z matching `gh pr view 4809 --json commits` last committed date. 2. Line 4: consent-file reference `addison-consent-pattern-observation-not-fact-discipline-aaron-otto.md` missing date prefix; actual file on disk is `2026-05-24-addison-consent-pattern-observation-not-fact-discipline-aaron-otto.md`. Added date prefix; reference now resolves. Mechanical fixes only. Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Aaron 2026-05-24T~03:30Z: "yes bundle-file it (shadow)"* + additions:
Sibling to PR #4808 (cluster substrate). Combined, the two archives describe the full ecosystem (cluster + dev PCs) as one declarative substrate.
Bundle-file term disambiguation (per Aaron's question)
"Bundle-file" = file all related decisions as ONE comprehensive archive rather than N narrow ones. Single source of truth; cross-references are internal; easier to find later.
Decided primary stack (lightweight-first)
Sovereignty preserved
Headscale > pure Tailscale managed: control plane is yours; no commercial dependency; free at any node count; framework discipline match.
Lending-resources pattern (per Aaron's framing)
Dev PCs are NOT first-class k8s nodes (trust boundary + reliability). They run a lightweight background daemon that polls cluster work-queue for opt-in workloads. Owner can pause/resume/revoke any time (NCI floor at dev-PC scope).
Deferred (ease-into-later)
Liqo / KubeFed v2 / k3s agent per dev PC / custom DERP / native-Nix-on-Windows / full NixOS desktop.
Addison's preferences
Explicitly absent from this archive pending her direct articulation. Per consent-discipline: observation-not-fact; declarative claims about Addison's preferences would violate the discipline.
Composes with
Test plan