Skip to content

📖 runbooks: document shipped tmux check in /v1/health #154

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
hivecommons-hive merged 2 commits into from
Nov 12, 2026
Merged

📖 runbooks: document shipped tmux check in /v1/health #154

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6461cb
📖 runbooks: document shipped tmux check in /v1/health
hivecommons-hive[bot] Nov 12, 2026
f676623
docs(runbooks): fix tmux health row for 503 case
hivecommons-hive[bot] Nov 12, 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
8 changes: 4 additions & 4 deletions runbooks/agent-not-working.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,17 +17,17 @@ curl --unix-socket "$CRUX_SOCKET" http://localhost/v1/health

`/v1/health` returns `version`, `agents`, `started_at` and `uptime_seconds`,
plus `background` (the in-process loops the server runs) and `hive_callback`
when configured. A `tmux` field (where tmux resolves on PATH) is proposed in
hive#17382 but has not shipped; no current server reports it, so its absence
is expected and not a problem.
when configured, and `tmux` (where tmux resolves on PATH). When tmux cannot be
found the endpoint answers 503 with `error` and `code` set, so a failing
health check can mean agents cannot start.

| Observation | Meaning | Action |
| --- | --- | --- |
| Connection refused / no socket | `crux serve` is not running | Restart it; check its stderr for a config load error (`crux: ...`) |
| `uptime_seconds` keeps resetting | The supervisor is restart-looping the server | Read the server's stderr; fix the config it reports; do not just keep restarting |
| `agents` lower than expected | The `--config` file defines fewer agents than you think | Check the file and `CRUX_SOCKET`: you may be talking to a different server |
| `background` missing or empty on a server meant to run it | The credential and session refresh loops (`StartAgentTokenRefresh`, `StartCredentialWatchdog`, `StartCopilotSessionRefresh`, `StartTranscriptActivityRefresh`) are not running, so agent credentials will not be refreshed | The host embedding the server must set `Server.Background`; do not treat a 200 from `/v1/health` as proof they are running |
| `tmux` present but empty in `/v1/health` (only once hive#17382 ships) | tmux is missing from the server's PATH, so no agent can start | Install tmux or fix the PATH the server runs with, then restart it. Until then, check `which tmux` by hand |
| `/v1/health` returns 503 with an `error` starting with `tmux not found on PATH:` and an empty `tmux` field | tmux is missing from the server's PATH, so no agent can start | Install tmux or fix the PATH the server runs with, then restart it |
| 401 / 403 | Missing or wrong bearer token | Pass the token the server was started with |

## 2. Is the hive callback reachable?
Expand Down
Loading