From 32b624783a2b26d12b38d94c8e0aba4b412295c0 Mon Sep 17 00:00:00 2001
From: Ciphercat <78522797+0xrsydn@users.noreply.github.com>
Date: Mon, 16 Mar 2026 00:46:23 +0000
Subject: [PATCH] docs: add golden paths for supported deployment topologies

---
 docs/golden-paths.md | 105 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 docs/golden-paths.md

diff --git a/docs/golden-paths.md b/docs/golden-paths.md
new file mode 100644
index 0000000..6b44332
--- /dev/null
+++ b/docs/golden-paths.md
@@ -0,0 +1,105 @@
+# Golden Paths
+
+nix-hermes-agent is opinionated: **there should be one obvious way to deploy**.
+
+A **Golden Path** is a supported topology + defaults + docs that:
+
+- is secure by default
+- is reproducible (pinned inputs)
+- avoids manual state drift
+- has a clear boundary between **Nix-managed config** and **runtime state**
+
+If your setup doesn't match a Golden Path, it may still work — but you're on your own.
+
+---
+
+## GP1: Single NixOS Server ⭐ (recommended)
+
+**Who it's for:** always-on server running gateway + agent on one box. Simplest and most battle-tested.
+
+- Gateway: NixOS (systemd service)
+- Terminal: local execution
+- Networking: direct or Tailscale
+
+```nix
+services.hermes-agent = {
+  enable = true;
+  config.terminal.backend = "local";
+  environmentFiles = [ config.sops.secrets."hermes/env".path ];
+};
+```
+
+**This is what we run.** If you're unsure, start here.
+
+## GP2: NixOS Gateway + Remote Execution
+
+**Who it's for:** gateway on a lightweight VPS, heavy commands run on a separate machine via SSH or Docker.
+
+- Gateway: NixOS VPS (systemd service)
+- Terminal: SSH backend to a beefy box, or Docker container
+- Networking: **Tailscale tailnet** (private, no public exposure)
+
+```nix
+services.hermes-agent = {
+  enable = true;
+  config.terminal = {
+    backend = "ssh";
+    ssh_host = "gpu-box";  # Tailscale hostname
+    ssh_user = "agent";
+    ssh_key = "/run/secrets/hermes-ssh-key";
+    timeout = 300;
+  };
+};
+```
+
+### Why Tailscale?
+
+- Private-by-default connectivity
+- MagicDNS stable hostnames (no IP chasing)
+- Easy to lock down with ACLs
+- Already works with NixOS `services.tailscale`
+
+## GP3: NixOS Gateway + macOS Node (future)
+
+**Who it's for:** always-on gateway with macOS-only capabilities (screenshots, Accessibility, Spotlight, etc.).
+
+- Gateway: NixOS (systemd service)
+- Node: macOS (launchd service via darwin module)
+- Networking: Tailscale
+
+⚠️ **Not yet implemented.** Requires the darwin module (roadmap item). Use GP1 or GP2 for now.
+
+## GP4: Laptop Dev
+
+**Who it's for:** local experimentation, not always-on.
+
+- Gateway: laptop (NixOS or `nix run`)
+- Expect downtime, sleep, network changes
+- Good for testing before deploying to GP1/GP2
+
+```bash
+nix run github:0xrsydn/nix-hermes-agent -- gateway
+```
+
+---
+
+## Runtime State vs Nix-Managed Config
+
+| Layer | Managed by | Survives rebuild? | Examples |
+|-------|-----------|-------------------|----------|
+| **Nix-managed** | `nixos-rebuild` | Overwritten | cli-config.yaml, SOUL.md, AGENTS.md, systemd unit |
+| **Secrets** | sops-nix | Overwritten (from encrypted source) | API keys, OAuth tokens, SSH keys |
+| **Runtime state** | Agent | ✅ Persists | Skills, memory, sessions, logs, cron jobs |
+
+Key principle: Nix manages the **shape** of the system. The agent manages its own **state**.
+
+---
+
+## Roadmap
+
+- [x] GP1: Single NixOS server
+- [x] GP2: Remote execution (SSH/Docker backends)
+- [ ] GP3: Darwin module for macOS
+- [ ] Binary cache (garnix/cachix)
+- [ ] Template flake (`nix flake init -t`)
+- [ ] Structured skills option with package dependencies