docs: add Agent Relay docs by mattvollmer · Pull Request #28786 · coder/coder

mattvollmer · 2026-08-31T19:16:42Z

What this adds

Two new docs pages for Agent Relay, a feature that connects a supported cloud-hosted AI agent provider's hosted sessions to self-hosted Coder workspaces. The provider's orchestration and AI inference stay cloud-hosted; a worker process inside the workspace executes the agent's tool calls.

docs/ai-coder/agent-relay/index.md — top-level overview: what it is, what it does, what it is and isn't, business value, current state, and supported providers.
docs/ai-coder/agent-relay/cursor.md — the Cursor-specific child page, naming Cursor Cloud Agents and Cursor's own bring-your-own-machine (BYOM) terminology.

Both pages are tagged "state": ["early access"] in the manifest and state the feature is in closed preview with select customers, pointing readers to their Coder account team or [email protected] for access.

Also included

docs/user-guides/workspace-management.md: broadened the workspace definition to include coding agents alongside developers.
docs/reference/glossary.md: added an Agent Relay entry (alphabetized between Agent Firewall and AI Gateway) and added it to the existing "agent" term-disambiguation callout, since it's easy to conflate with Coder Agents.

Scope note for reviewers

Agent Relay itself (the underlying service, config, and worker implementation) lives in a separate, non-public repository. I don't have access to that source from this environment, so I deliberately kept both pages high-level and didn't invent specifics like CLI flags, config file structure, or exact command syntax. Before this goes further, someone with access to that repo should verify the mechanics described here (workspace-per-session lifecycle, provider pool mapping, worker connection model) against the real implementation, and a follow-up PR should add a step-by-step "Getting started" section once the feature moves past closed preview to something self-serve.

Validation

docs/manifest.json is valid JSON.
markdownlint-cli2: 0 issues across all changed/added Markdown files.
vale --no-exit: 0 errors on every changed/added file (a handful of pre-existing gerund-heading warnings on workspace-management.md and glossary.md predate this branch and aren't touched here).
scripts/check_emdash.sh: passes.
Confirmed every relative link target in the new pages resolves to a real file in the repo.

Decision log

Dropped an "air-gap capable" claim and a "Coder AI Gateway" claim that would have been present in an earlier draft: the integration requires the in-workspace worker to hold an outbound connection to the cloud provider for inference/orchestration, so true air-gapping isn't possible, and Coder's AI Gateway isn't in the inference path for this feature.
Named the specific Cursor product as Cursor Cloud Agents and linked Cursor's own "bring-your-own-machine (BYOM)" terminology (cursor.com/docs/cloud-agent/bring-your-own-machine) rather than inventing Coder-specific naming for the same concept.
Kept "workspace" lowercase per the existing style guide (workspace is the documented generic-concept casing, distinct from named features like "Workspace Proxy"), while still linking the term to the Workspace Management page.
Used "closed preview with select customers" rather than "Preview," and removed a blanket "not feature-complete or stable" disclaimer sentence per explicit direction.

🤖 This PR was created by Coder Agents on behalf of @mattvollmer.

Add Agent Relay to the manifest as a new top-level entry after Coder Agents, with a child page for Cursor, both tagged early access. Agent Relay connects a supported cloud-hosted AI agent provider's hosted sessions to self-hosted Coder workspaces. The provider's orchestration and inference stay cloud-hosted; a worker process inside the workspace executes the agent's tool calls. Cursor Cloud Agents (Cursor's own bring-your-own-machine, or BYOM, terminology) is the first supported provider. Both pages state the feature is in closed preview with select customers and point readers to their Coder account team or [email protected] for access. Also: - Broaden the workspace definition on the Workspace Management page to include coding agents alongside developers. - Add glossary entries for Agent Relay, including it in the existing "agent" term-disambiguation callout alongside Coder Agents.

github-actions · 2026-08-31T19:16:51Z

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

nickvigilante

LGTM with a few nits. Can you ask your agent to use semantic line breaks for this PR (one sentence per line)?

Co-authored-by: Nick Vigilante <[email protected]>

…r line)

nickvigilante

LGTM 🚀

coderagents · 2026-09-01T00:43:37Z

Documentation Check

This is a docs-only PR that adds the Agent Relay pages. The changes are well-formed: manifest.json is valid JSON, the early access state matches existing entries, the glossary entry is alphabetized correctly and cross-referenced in the "agent" disambiguation callout, all relative links and anchors resolve, the diagram asset exists, and there are no emdash/style violations.

Updates Needed

docs/ai-coder/index.md - Addressed in 1a9e822: the overview now has a dedicated Agent Relay section and lists it among the agent execution options, with links to ./agent-relay/index.md. New links/anchors verified (#template-builder, extending-templates/index.md, in-page section anchors).

No new documentation needs in the latest push.

Automated review via Coder Agents

matifali · 2026-09-01T04:12:47Z

docs/ai-coder/index.md - The AI-coder overview landing page curates the other AI features (Coder Agents, AI Governance → AI Gateway, Agent Firewall) but doesn't mention Agent Relay. The new feature is only reachable via the nav manifest. Consider adding a short section or link so readers can discover it from the overview.

@matthew, is this intentional?

mattvollmer · 2026-09-01T13:42:04Z

docs/ai-coder/index.md - The AI-coder overview landing page curates the other AI features (Coder Agents, AI Governance → AI Gateway, Agent Firewall) but doesn't mention Agent Relay. The new feature is only reachable via the nav manifest. Consider adding a short section or link so readers can discover it from the overview.

@matthew, is this intentional?

Agree - I want to update this page. If it's not part of this PR, then as a follow-up.

nickvigilante · 2026-09-01T14:42:09Z

Follow-up PR is good with me; I won't block this PR on discoverability.

…elay and template modules

Emyrk · 2026-09-01T15:06:08Z

+## Agents in workspace templates
+
+Template admins can install terminal-based coding agents, such as Claude Code or Codex, directly into a workspace template using a [registry module](https://registry.coder.com).
+Pick from a curated list of agent modules in the [template builder](../admin/templates/creating-templates.md#template-builder), or add a module directly in Terraform:
+
+```tf
+module "claude-code" {
+  source   = "registry.coder.com/coder/claude-code/coder"
+  version  = "~> 5.2"
+  agent_id = coder_agent.main.id
+}
+```
+
+Visit the [Coder Registry](https://registry.coder.com) for the full list of available agent modules.


We have not published the required module for agent-relay yet

We have not published the required module for agent-relay yet

This section is unrelated to Agent Relay, but either way, we won't merge this PR until the registry is ready for Agent Relay.

mattvollmer · 2026-09-01T15:42:00Z

Follow-up PR is good with me; I won't block this PR on discoverability.

@nickvigilante this commit updates the AI Coder index page and outlines the 4 common ways of running agents with Coder.

david-fraley

just 1 nit

david-fraley · 2026-09-01T15:57:57Z

+> [!NOTE]
+> Agent Relay for Cursor is in [early access](../../install/releases/feature-stages.md#early-access-features) and is currently in closed preview with select customers.
+
+[Agent Relay](./index.md) connects [Cursor Cloud Agents](https://cursor.com/cloud) to self-hosted Coder workspaces.


Suggested change

[Agent Relay](./index.md) connects [Cursor Cloud Agents](https://cursor.com/cloud) to self-hosted Coder workspaces.

[Agent Relay](./index.md) connects [Cursor Cloud Agents](https://cursor.com/cloud) to self-hosted Coder Workspaces.

Should this and other instances technically have workspaces as capitalized? Def a nit

I'll sync with Nick. I think we might need to check the style guide.

I'm a firm believer that there's a difference between Workspaces as a product, which should have the capital W, and an instance of the feature known as a workspace, with a lowercase w. My preference here is self-hosted Coder workspaces.

github-actions Bot assigned mattvollmer Aug 31, 2026

docs(ai-coder/agent-relay): remove border from architecture diagram

c930c67

mattvollmer requested a review from nickvigilante August 31, 2026 19:20

mattvollmer assigned Shelnutt2 Aug 31, 2026

mattvollmer requested a review from matifali August 31, 2026 19:20

docs(ai-coder/agent-relay): use inline style to remove image border

bc598ff

mattvollmer changed the title ~~docs(ai-coder/agent-relay): add Agent Relay docs~~ docs: add Agent Relay docs Aug 31, 2026

nickvigilante reviewed Aug 31, 2026

View reviewed changes

Comment thread docs/ai-coder/agent-relay/cursor.md Outdated

Comment thread docs/ai-coder/agent-relay/index.md Outdated

Comment thread docs/ai-coder/agent-relay/index.md Outdated

mattvollmer and others added 4 commits August 31, 2026 16:25

Update docs/ai-coder/agent-relay/index.md

5e9b434

Co-authored-by: Nick Vigilante <[email protected]>

Update docs/ai-coder/agent-relay/index.md

da4ead9

Co-authored-by: Nick Vigilante <[email protected]>

Update docs/ai-coder/agent-relay/cursor.md

31cb023

Co-authored-by: Nick Vigilante <[email protected]>

docs(ai-coder/agent-relay): use semantic line breaks (one sentence pe…

7486435

…r line)

mattvollmer requested a review from nickvigilante August 31, 2026 20:47

nickvigilante approved these changes Aug 31, 2026

View reviewed changes

mattvollmer marked this pull request as ready for review September 1, 2026 00:41

matifali reviewed Sep 1, 2026

View reviewed changes

Comment thread docs/ai-coder/agent-relay/index.md

Comment thread docs/ai-coder/agent-relay/cursor.md

Comment thread docs/manifest.json

mattvollmer assigned david-fraley Sep 1, 2026

docs(ai-coder): outline agent execution options with links to Agent R…

1a9e822

…elay and template modules

Emyrk reviewed Sep 1, 2026

View reviewed changes

david-fraley approved these changes Sep 1, 2026

View reviewed changes

matifali approved these changes Sep 2, 2026

View reviewed changes

mattvollmer merged commit cb6c981 into main Sep 2, 2026
29 checks passed

mattvollmer deleted the matt/add-agent-relay-docs branch September 2, 2026 13:19

github-actions Bot locked and limited conversation to collaborators Sep 2, 2026

nickvigilante added the backport label Sep 2, 2026

	[Agent Relay](./index.md) connects [Cursor Cloud Agents](https://cursor.com/cloud) to self-hosted Coder workspaces.
	[Agent Relay](./index.md) connects [Cursor Cloud Agents](https://cursor.com/cloud) to self-hosted Coder Workspaces.

Uh oh!

Conversation

mattvollmer commented Aug 31, 2026

What this adds

Also included

Scope note for reviewers

Validation

Uh oh!

github-actions Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docs preview

Uh oh!

nickvigilante left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nickvigilante left a comment

Choose a reason for hiding this comment

Uh oh!

coderagents Bot commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Check

Updates Needed

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matifali commented Sep 1, 2026 • edited by mattvollmer Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mattvollmer commented Sep 1, 2026

Uh oh!

nickvigilante commented Sep 1, 2026

Uh oh!

Emyrk Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

mattvollmer Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

mattvollmer commented Sep 1, 2026

Uh oh!

david-fraley left a comment

Choose a reason for hiding this comment

Uh oh!

david-fraley Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

mattvollmer Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

nickvigilante Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

github-actions Bot commented Aug 31, 2026 •

edited

Loading

coderagents Bot commented Sep 1, 2026 •

edited

Loading

matifali commented Sep 1, 2026 •

edited by mattvollmer

Loading