## Summary **Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`). Adds a front-matter `title` to every navigable docs page whose title can be migrated **mechanically**, with no editorial judgment. This is the content step that Phase 1 (renderers prefer front-matter title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware, `DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged and live. **Rendered no-op.** The renderers already resolve the page title from the manifest and hide the leading body H1 (Phase 1), so no page changes visually. This just moves the title into front matter where Fumadocs and the migrated tooling can read it. ## What's in this batch Dry-run on `main` (464 navigable pages) splits into: | category | count | this PR | |----------|-------|---------| | already has front-matter title (Reference, from Phase 2 generators) | 196 | skipped (idempotent) | | **mechanical** — leading body H1 equals the manifest label | 138 | ✅ add front-matter `title`, drop the duplicate H1 | | **no body H1** — renders under the manifest label only | 4 | ✅ add front-matter `title` only | | **mismatch** — body H1 differs from the manifest label | 126 | ⏭️ deferred (needs an editorial decision, see below) | 142 files changed, all under `docs/`. ## Deliberately out of scope: the 126 mismatches Pages where the body H1 is richer than the short sidebar label (e.g. label **Modules** / H1 *Contributing modules*, label **Install** / H1 *Installing Coder*) need a canonical-title decision, not a script. A few even look like the body H1 is the redundant one (`install/cli.md` and `install/index.md` both carry the H1 *Installing Coder*). These will land in follow-up batches **by nav section** once the policy is set, so each gets real review. ## Verification AI was the primary author of this PR (see disclosure below); per the [AI Contribution Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) here is the manual verification. - Every added front-matter block parses as YAML and its `title` round-trips to the manifest label (checked programmatically across all 142 files). - Every removed line is a leading `# H1` that equalled the manifest title; no body prose was reflowed. Front matter is correctly hoisted above pre-existing `<!-- markdownlint-disable -->` comments on the two pages that had them. - `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in Phase 4); `MD025` is not tripped because the duplicate body H1s are removed. ``` $ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main) Linting: 142 file(s) Summary: 0 error(s) ``` Linear: DOCS-484 > This PR was created with AI assistance (Coder Agents).
5.7 KiB
title
| title |
|---|
| Improving Agent Resiliency |
Coder's agent can automatically lower the scheduling priority and raise the OOM (out-of-memory) kill score of user processes so the agent itself stays alive under resource pressure.
Prerequisites
-
Linux — The feature is ignored on other operating systems.
-
CAP_SYS_NICE— Required if the agent needs to lower the nice value below its current value. In Kubernetes, add it to the container's security context:container { security_context { capabilities { add = ["CAP_SYS_NICE"] } } }
Environment variables
Configure the feature with environment variables in the
environment that launches the agent binary. These must be set
on the workspace container or host, not in the coder_agent
resource's env block — the agent reads them from its own
process environment at startup.
| Variable | Required | Default | Description |
|---|---|---|---|
CODER_PROC_PRIO_MGMT |
Yes | — | Set to enable the feature. The agent checks whether the variable is present, not its value — even an empty string enables it. Use 1 by convention. To disable, unset the variable entirely. |
CODER_PROC_OOM_SCORE |
No | Computed from agent's score | Explicit oom_score_adj value for child processes. Range: -1000 to 1000. |
CODER_PROC_NICE_SCORE |
No | Agent nice + 5 (capped at 19) | Explicit nice value for child processes. Range: -20 to 19 (higher = lower priority). |
OOM score defaults
If you do not set CODER_PROC_OOM_SCORE, the agent computes a
value based on its own oom_score_adj:
Agent's oom_score_adj |
Child score | Rationale |
|---|---|---|
| Negative (< 0) | 0 |
Children are treated as normal processes. |
| >= 998 | 1000 |
Children get the maximum score (killed first). |
| Any other value | 998 |
Children get a near-maximum score. |
The goal is for the kernel's OOM killer to target child processes before the agent, keeping remote connectivity alive even when a workspace runs out of memory.
Nice score defaults
If you do not set CODER_PROC_NICE_SCORE, the agent sets
children to its own nice value plus 5, capped at 19. This
gives the agent more CPU scheduling priority than user
workloads.
Example
The following Kubernetes template snippet enables process priority management on the workspace container:
resource "kubernetes_deployment" "workspace" {
# ... other configuration
spec {
template {
spec {
container {
name = "dev"
image = "codercom/example-base:ubuntu"
env {
name = "CODER_AGENT_TOKEN"
value = coder_agent.main.token
}
env {
name = "CODER_PROC_PRIO_MGMT"
value = "1"
}
env {
name = "CODER_PROC_OOM_SCORE"
value = "10"
}
env {
name = "CODER_PROC_NICE_SCORE"
value = "1"
}
security_context {
capabilities {
add = ["CAP_SYS_NICE"]
}
}
}
}
}
}
}
CODER_PROC_OOM_SCORE=10gives child processes a slightly elevated OOM score while keeping them well below the maximum.CODER_PROC_NICE_SCORE=1gives children a mildly lower CPU priority than the agent.CAP_SYS_NICEallows the agent to set nice values.
Troubleshooting
OOM score adjustment fails
If you see failed to adjust oom score in stderr but the
process still starts, the agent likely lacks permission to
write to /proc/self/oom_score_adj. Ensure the process is
dumpable — this is handled automatically by the agent, but
can fail if the container runtime restricts prctl calls.
Nice value is not applied
If you see failed to adjust niceness in stderr, nice values
can only be increased (lowered in priority) without
CAP_SYS_NICE. If your template sets a CODER_PROC_NICE_SCORE
lower than the agent's current nice value, add the capability
to the container's security context.
Environment variables leak to nested Coder agents
The agent strips all CODER_PROC_* variables from child
environments automatically. This prevents interference in
"Coder on Coder" development scenarios where a workspace
runs another Coder agent.
Verifying the feature is enabled
The agent logs whether process priority management is active at startup. Look for these lines in the agent log:
"process priority management enabled"
"process priority management not enabled (linux-only)"
The log entry includes the CODER_PROC_PRIO_MGMT value and
the operating system. Check the agent log file at
<log-dir>/coder-agent.log or stderr output.
Feature has no effect on macOS or Windows
Process priority management is Linux-only. Setting
CODER_PROC_PRIO_MGMT on other operating systems is safe
but has no effect.