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

In the pursuit of running a self-hosted agent organization, an operator without coding experience installed a self-hosted agent gateway on a Mac from scratch in a single sitting. Throughout the process, eleven issues arose that prevented the successful functioning of the system.

1. Homebrew required an Administrator account due to the installation path falling through to Homebrew, which needed administrative access. Fixing this meant avoiding granting admin privileges and instead installing Node from the official .pkg file in a non-privileged account.

2. Copy-pasting did not work across macOS user accounts because the clipboard is per-session. The fix involved using /Users/Shared as the sole transfer path, with everything moving as a file.

3. The npm install -g command failed with EACCES due to the default prefix being /usr/local, which the non-privileged account could not write to. The solution was to configure npm to use a user-specific prefix.

4. After the installation, the command was not found, directly resulting from the previous issue. The fix entailed adding one line to the ~/.zshrc file to include the new prefix's bin directory in the PATH.

5. The installation script prompted for scripts to be run, but the --allow-scripts flag did not persist. The fix was to set the user location instead of passing the flag each time, addressing the chain of issues from 3 to 5.

6. Typos occurred due to instructions being provided as screenshots. The operator had to manually retyping the instructions, resulting in errors like "is for ls" and "protobyfjs for protobufjs." The solution was to stop sending text to be retyped and instead provide an executable file in a shared folder for the operator to double-click.

7. The CLI's first screen was a theme picker, which appeared to freeze as it waited for a preference. The operator struggled to understand if the app was hung or not. The fix was simple: press Enter to proceed.

8. A fake @BotFather was discovered while searching for the bot inside the messenger, leading to impersonators appearing near the top of the results. The fix was to use the canonical t.me link and verify the username rather than the display name, as usernames are unique while display names are not.

9. The default text editor, TextEdit, saved files in rich text format. The file appeared correct on screen but contained formatting bytes unreadable by programs. The solution was to format the file as plain text before saving it.

10. Files in the shared folder could not be deleted due to the sticky bit, which only allowed the creating account to remove its own files. The fix was to delete the files from the account that created them, rather than attempting to remove them due to permission issues.

11. The gateway initially came up and worked correctly, sending and receiving messages. However, the subscription-based credentials expired in seven hours, requiring an interactive terminal for renewal. The measured ceiling for unattended operation was seven hours, and the daily human cost amounted to three logins. The bottleneck was never the plumbing but rather the credential lifetime.

The author advises future self-hosters to move parts, not privileges; avoid retying instructions from screenshots; ship double-clickable files; assume that documentation often stops one step early; budget for the step after the one being read; verify usernames, not display names; and measure the runtime before celebrating successful unattended operation.