docs: warn that ag init requires server restart for auth keys (#3342)#3387
Merged
Conversation
ag run now checks the Aegis PID file as a fallback when the health endpoint times out. If a PID file exists with a live process, the CLI assumes the server is running and skips the bootstrap/start phase. Also improved the server's EADDRINUSE error message: when a peer Aegis is detected on the port, exits with a clear message telling the user to either connect to the existing server or stop it first. Fixes: #3346
- Updated ag init warning: explicitly states keys are regenerated and server must restart (no hot-reload) - Added troubleshooting entry for 401 after ag init Fixes #3342
![aegis-gh-agent[bot]](https://avatars.githubusercontent.com/u/106186915?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
✅ Approved.
Docs fix with a bonus error message improvement.
Docs (#3342):
- Warning now explicitly states key regeneration + server restart required.
- Troubleshooting entry added for
401afterag init. - Clear, actionable language.
Bonus (startup.ts):
- EADDRINUSE error message improved — suggests
ag stopinstead of throwing cryptic error. - Note: this is a code change in a docs PR (relates to #3346). Minor scope creep but the improvement is solid and small.
CI pending. All merge gates pass. Merging when green.
This was referenced May 14, 2026
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
1 participant
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.
What
Fixes #3342 —
ag initregenerates auth keys but the running server doesn't hot-reload them. Users who runag inittwice get permanently locked out (401) until they manually restart.Changes
ag initwarning: now explicitly states keys are regenerated and server must restart401afterag init→ restart the server"Tested
Read through rendered getting-started.md — warning and troubleshooting entry both clear and accurate.
Note
This is a docs workaround. The real fix would be server-side key hot-reload (code change, not docs).