Self-hosted environments reference changedself-hosted-environments-reference
Nearest release: v2.1.311, published 4 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 26 Oct 2026 23:50 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 27 Oct 2026 00:07 UTC.
Upstream edited
Recorded here
Lines+25added
Lines−1removed
From line
310
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits28to this page, all time
#### Alert when the orchestrator is down
The whole hunk
from line 310, old and new numbered
/
from line 310
310310
311311### Alert on lost runners and waiting sessions
312312
313On a [fixed fleet](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#scale-the-fleet), load `ClaudeRunnersBelowFloor`. With [on-demand runners](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners), load `ClaudeOrchestratorSessionsWaiting` and `ClaudeOrchestratorQueueWaitHigh` instead.
313To be alerted when runners are lost, sessions wait, or the orchestrator is down, load these Prometheus alert rules beside the [sample alert rules](#sample-alert-rules):
314314
315* **[Fixed fleet](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#scale-the-fleet)**: `ClaudeRunnersBelowFloor`
316* **[On-demand runners](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners)**: `ClaudeOrchestratorSessionsWaiting`, `ClaudeOrchestratorQueueWaitHigh`, and `ClaudeOrchestratorAbsent`
317
315318#### Alert when a fixed fleet loses runners
316319
317320`ClaudeRunnersBelowFloor` fires when fewer registered, scraped runners than the floor are left for 10 minutes:
from line 370
367370
368371* **Threshold**: if some session is always waiting, raise the `> 0` in `ClaudeOrchestratorSessionsWaiting` above the number you usually see
369372* **`ClaudeOrchestratorDisconnected`**: keep it loaded from the [sample alert rules](#sample-alert-rules), because `ClaudeOrchestratorSessionsWaiting` stops firing about 2 minutes after the last orchestrator in the namespace disconnects
373
374#### Alert when the orchestrator is down
375
376To learn that the [orchestrator](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners) itself is down, load `ClaudeOrchestratorAbsent`. It fires when no orchestrator in the namespace has been scraped for 5 minutes:
377
378```yaml theme={null}
379groups:
380 # On-demand runners only. Replace claude-runners with the orchestrator's namespace.
381 - name: claude-code-self-hosted-on-demand-orchestrator
382 rules:
383 - alert: ClaudeOrchestratorAbsent
384 expr: absent(claude_code_self_hosted_orchestrator_connected{namespace="claude-runners"})
385 for: 5m
386 labels: {severity: critical}
387 annotations:
388 summary: "No orchestrator has been scraped for 5 minutes. If it's down, no on-demand runner starts, and sessions wait. Check the orchestrator workload first, then its scrape target if it's running."
389```
390
391* **Namespace**: replace `claude-runners` with the orchestrator's namespace, and copy the alert for each further namespace that runs an orchestrator. If your targets have no `namespace` label, remove the matcher, or the alert fires after 5 minutes and stays on.
392* **Prometheus servers that don't scrape the orchestrator**: leave the alert out of their rule files, because on such a server it fires after 5 minutes and stays on
393* **Don't rely on the orchestrator's other alerts**: they read metrics that the orchestrator itself serves. `ClaudeOrchestratorSessionsWaiting`, `ClaudeOrchestratorQueueWaitHigh`, and the orchestrator's [sample alert rules](#sample-alert-rules) all stop firing within about 10 minutes of the orchestrator going down.
370394
371395### Pass through session-child metrics
372396
No line in this hunk matches that.