Skip to content

docs: warn that ag init requires server restart for auth keys (#3342) #3387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aegis-gh-agent merged 2 commits into from
May 14, 2026
Merged

docs: warn that ag init requires server restart for auth keys (#3342) #3387

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c045110
fix(cli): prevent EADDRINUSE when server already running (#3346)
OneStepAt4time May 14, 2026
b19ea6b
docs: warn that ag init requires server restart for auth keys (#3342)
OneStepAt4time May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ npm install -g @onestepat4time/aegis
ag init
```

> **Warning:** Running `ag init` a second time overwrites `.aegis/config.yaml`. Restart the server to apply changes. Use `ag init --force` to skip confirmation prompts.
> **Warning:** Running `ag init` a second time overwrites `.aegis/config.yaml` and regenerates auth keys. **You must restart the server** for the new keys to take effect — the running server does not hot-reload keys from disk. Without a restart, CLI commands will return `401 Unauthorized` with the new token.
>
> `ag init` now supports conversational onboarding with `--model` and `--name` flags for non-interactive setup. Use `--model <provider/model>` to set the default model and `--name <name>` to set a display name for the session.

Expand Down Expand Up @@ -399,6 +399,7 @@ See the [Worktree Guide](./worktree-guide.md) for detailed setup instructions.
| Claude not authenticated | Run `claude login` first. Sessions created without auth produce no output. `ag doctor` checks this |
| `Claude Code CLI not found` | Install Claude Code: `npm install -g @anthropic-ai/claude-code` and run `claude` to authenticate |
| `401 Unauthorized` | Set `AEGIS_AUTH_TOKEN` or include `Authorization: Bearer <token>` header |
| `401` after `ag init` | Restart the server — it does not hot-reload keys. Kill the process and run `ag` again |
| Session stuck on `stalled` | Send an interrupt: `curl -X POST http://localhost:9100/v1/sessions/:id/interrupt` |
| Session shows `pending` | Initial state — connecting to ACP runtime. Wait a moment and re-poll |
| Session shows `killed` | Terminal state — stopped via API. Session retained for audit, cannot be resumed |
Expand Down
7 changes: 5 additions & 2 deletions src/startup.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,8 +168,11 @@ export async function listenWithRetry(
console.error(`EADDRINUSE on port ${port} - attempting recovery (attempt ${attempt + 1}/${maxRetries})`);
const killed = await killStalePortHolder(port, stateDir);
if (!killed) {
console.error(`EADDRINUSE recovery failed: no stale process found on port ${port}`);
throw err;
// #3346: Better error message when a peer Aegis is already running
console.error(`EADDRINUSE: another Aegis server is already running on port ${port}`);
console.error(` If you want to use the running server, no action needed — just connect to it.`);
console.error(` If you want to restart it, stop the existing server first: ag stop`);
process.exit(1);
}
}
}
Expand Down
Loading