Skip to content

docs: add missing options to the Agent Relay configuration reference - #31986

Merged
nickvigilante merged 4 commits into
mainfrom
docs/agent-relay-config-reference
Nov 12, 2026
Merged

nickvigilante merged 4 commits into
mainfrom
docs/agent-relay-config-reference

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Brings configuration.md closer to Agent Relay v0.15.0 and answers review questions about repo-scoped Cursor pools.

  • The Cursor repo_url pool field. The row says the template clones the repository before the worker starts, and links to Source control in cursor.md.
  • cursor.md Source control: when to set repo_url, a two-pool example, and a link to Cursor's any-repo pools docs for routing, which Cursor decides.
  • Helm values: a commented YAML example with defaults replaces the table.
  • Removes the HTML source comment at the top of configuration.md, which named the private repository, internal paths, and a Linear issue.

Per review, this PR no longer documents the status page, its TLS options, or --dangerous-allow-parameter-credential-transport.

Verification notes:

  • repo_url: agent-relay internal/services/servicecursorworkers/cursorworkers.go (repoOwnerName, RegisterPool) and dispatch.go (buildParameters), plus the agent-relay-cursor module README, which says the template must clone agent_relay_cursor_repo_url.
  • Helm defaults: helm/coder-agent-relay/values.yaml.
  • reapStartupGrace is covered in 2/5. reapDelay has no Helm value (see 2/5).

Stack 4/6. Review and merge in order:

Refs DOCS-1171

Generated by Coder Agents.

@nickvigilante nickvigilante added the community Pull Requests and issues created by the community. label Nov 10, 2026
@nickvigilante nickvigilante self-assigned this Nov 10, 2026
@linear-code

linear-code Bot commented Nov 10, 2026

Copy link
Copy Markdown

DOCS-1171

@BobbyHo BobbyHo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! just left a minor comment

Each pool maps to one template.
Use separate pools when repositories need different templates or credentials.

To give one repository a template of its own, such as an image that has the repository cloned and its toolchain installed, set [`repo_url`](./configuration.md#cursor-pool-fields) on a pool for that repository.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just wondering, does the worker need to start in the cloned repo? The module doesn't pass --worker-dir, so it defaults to the agent's directory (usually home), which may be outside the repo.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, good catch. The worker runs sessions in the directory it starts in, and Cursor derives a repo-backed worker's repo label from that directory's Git remote. The module's start.sh.tftpl runs agent worker with no --worker-dir, so without a change the worker would start in the agent's directory.

Fixed in afbafed:

  • cursor.md Source control now says to start the worker in the clone for a repo-backed pool, with a coder_agent dir example. The example/templates/cursor template in agent-relay v0.16.0 does the same thing. The alternative is additional_args = ["--worker-dir", "<clone>"], which the module's additional_args validation allows.
  • The repo_url row in configuration.md now ends with "and start the worker in the clone".

Generated by Coder Agents on behalf of @nickvigilante.

nickvigilante added a commit that referenced this pull request Nov 12, 2026
Agent Relay v0.15.0 made the reaper's 15-minute startup window
configurable
([agent-relay#152](coder/agent-relay#152)) and
added a reap delay
([agent-relay#134](coder/agent-relay#134)).

- `configuration.md`: add `--reap-startup-grace` (Helm
`reapStartupGrace`) and `--reap-delay`, plus the per-pool `reap_delay`
field, under an intro that says how the two options differ. The Cursor
`dispatch_deadline: 0` row now points at the startup grace.
- `setup.md`: fix the script-ordering note and **Workspace lifecycle**,
which hardcoded 15 minutes and said failed builds are deleted "on the
next sweep". **Workspace lifecycle** now states the 30-second gap
between sweeps, and **Choose cleanup settings** maps each goal to its
setting.
- `cursor.md`: fix the **Build deadline** bullet and the `pending`
lifecycle row.
- `troubleshooting.md`: the "session ended but its workspace remains"
row mentions the reap delay.
- `monitoring/index.md`: add the `delayed` verdict to
`agent_relay_reaper_verdicts_total` and define it as a wait before
`delete` or `failed`.

Verification notes:
- The chart has **no `reapDelay` value** at v0.15.0 (only
`reapStartupGrace`; checked `values.yaml` and `templates/_helpers.tpl`),
so the docs say to set `CODER_AGENT_RELAY_REAP_DELAY` through
`extraEnv`.
- Pending or starting builds wait `max(grace, dispatch_deadline)`. A
finished build whose runner reports `pending` or nothing fails after the
grace alone (`workspacereaper/lifecycle.go`).
- The reap delay counts from the latest build's `Job.CompletedAt`, not
from the worker's exit, so a session that ran longer than the delay gets
no extra time (`reapDeadline` in `workspacereaper/reaper.go`).
- `delayed` is only a metric label. A sweep records it when the verdict
is `delete` or `failed` but the delay hasn't passed. The `Verdict` type
has only `keep`, `delete`, `failed`, and `stuck`.
- The reaper sleeps 30 seconds after it sweeps every pool, rather than
running on a fixed ticker (`sweepLoop` in `servicereaper/reaper.go`).

Stack 2/6. Review and merge in order:
- #31834 (merged)
- #31984
- #31985
- #31986
- #31987
- #32094

Refs DOCS-1171

> Generated by Coder Agents.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Bobby Ho <bobby@coder.com>
nickvigilante added a commit that referenced this pull request Nov 12, 2026
Updates `monitoring/siem.md` to the log messages Agent Relay v0.15.0
writes.

| Old `msg` | v0.15.0 `msg` |
|---|---|
| `workspace ready, runner handoff` | `workspace built, runner handoff`
([agent-relay#154](coder/agent-relay#154)) |
| `workspace build passed the session deadline, reporting retryable and
deleting` | `workspace build passed the session deadline, reporting
failure` (also lists `workspace build succeeded after the session
deadline`) |
| `workspace build failed, reporting retryable and deleting` |
`workspace build failed` |
| `delete workspace failed, leaving for reconciliation` | `delete
workspace failed, leaving it for the reaper` |

The PR also adds the `agent_lifecycle` field, which appears on the
handoff record and on reaper records.

Verification notes:
- Every other quoted `msg` in `siem.md` was checked by grepping
`internal/` at `9b96578` and still matches.
- `leaving for reconciliation` doesn't exist at v0.15.0. Its replacement
comes from `Dispatcher.deleteWorkspace`.

Stack 3/6. Review and merge in order:
- #31834 (merged)
- #31984
- #31985
- #31986
- #31987
- #32094

Refs DOCS-1171

> Generated by Coder Agents.

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Base automatically changed from docs/agent-relay-siem-messages to main November 12, 2026 18:14
@github-actions

Copy link
Copy Markdown
Contributor


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


1 out of 2 committers have signed the CLA.
✅ (nickvigilante)[https://github.com/nickvigilante]
❌ @coder[bot]
You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

coder Bot and others added 3 commits November 12, 2026 13:39
Document the status page, TLS, and parameter credential transport options, the Cursor repo_url pool field, and the statusUI and tls Helm values, and update the source note to Agent Relay v0.15.0.
…t Relay config reference

Replace the Helm values table with a commented YAML example.
…rom Agent Relay docs

Review feedback on #31837 asked how repo-scoped Cursor pools differ from
pools without a repository and why someone would set repo_url. Cursor
decides that routing, so link Cursor's any-repo pools section instead of
restating it, and add a two-pool example to Source control. The
repo_url row now says the template clones the repository, matching the
module README, rather than requiring it in the image.

Remove the HTML comment at the top of the configuration reference. It
named a private repository, internal paths, and a Linear issue, none of
which belong in published docs.

Refs DOCS-1171
@nickvigilante
nickvigilante force-pushed the docs/agent-relay-config-reference branch from afbafed to 6203aee Compare November 12, 2026 18:39
@nickvigilante
nickvigilante enabled stacked auto-merge (squash) November 12, 2026 18:39
@nickvigilante
nickvigilante merged commit af41767 into main Nov 12, 2026
27 of 29 checks passed
@nickvigilante
nickvigilante deleted the docs/agent-relay-config-reference branch November 12, 2026 18:44
@nickvigilante
nickvigilante temporarily deployed to main November 12, 2026 18:44 — with GitHub Actions Inactive
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 12, 2026

This branch was previously deployed

1 inactive deployment
main — 6203aee5 Deployed Nov 12, 2026 by nickvigilante via cla #255201
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

community Pull Requests and issues created by the community.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants