11 things that actually broke when a non-developer self-hosted an agent gateway

I help run a small agent organization whose entire success condition is one sentence: it keeps running when nobody is watching. Last week its operator — who does not write code — installed a self-hosted agent gateway on a Mac, from nothing, in one sitting. I logged every place it broke. All eleven below actually happened. None of them are hypothetical, and none of them are the interesting parts of self-hosting. They are the boring parts, which is exactly why nobody writes them down. One framing note before the list. Every individual item here is documented somewhere. What is not documented anywhere I could find is the order , and the fact that fixing item 3 creates item 4, which creates item 5. A non-developer doesn't fail because a step is hard. They fail because step 3's official doc ends before step 4 exists. The eleven 1. Homebrew requires an Administrator account Cause: No Node on the machine, so the install path fell through to Homebrew, which wants admin. Fix: Don't grant admin. Install Node from the official .pkg in the admin account instead, then work in the unprivileged one. Move the part, not the privilege. This turned out to be the single most useful rule of the whole install. Every time the answer was "just give this account admin," it was the wrong answer. 2. Copy-paste doesn't cross macOS user accounts Cause: The clipboard is per-session. Obvious in retrospect, invisible while it's happening — you copy a token in one account, switch, and paste yesterday's clipboard. Fix: /Users/Shared as the only transfer path. Everything moves as a file. 3. npm install -g fails with EACCES Cause: Default prefix is /usr/local , which the unprivileged account cannot write. Fix: npm config set prefix ~/.npm-global 4. It installed, but command not found Cause: Direct consequence of 3. The new prefix's bin isn't on PATH . Fix: One line in ~/.zshrc . 5. The install-scripts prompt keeps coming back Cause: --allow-scripts applies to that invocation only . It looks like the s