Files
coder/docs/ai-coder/agent-relay/index.md
T
Matt VollmerandNick Vigilante cb6c98147f docs: add Agent Relay docs (#28786)
## 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 `sales@coder.com` 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.

<details>
<summary>Decision log</summary>

- 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.

</details>

---

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

---------

Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
2026-09-02 09:19:49 -04:00

2.9 KiB

title
title
Agent Relay

Agent Relay connects a cloud-hosted AI coding agent's hosted sessions to self-hosted Coder workspaces. Developers keep the cloud agent's client and workflow. Coder provides the workspace where the agent's tool calls run.

What Agent Relay does

Agent Relay watches for pending agent sessions from a supported provider. When a session starts, Agent Relay provisions a Coder workspace from a mapped template and connects the session to a worker process inside that workspace. The worker executes the agent's tool calls, such as reading files, running commands, and using development tools, against the resources available in that workspace. Agent Relay manages the workspace for the life of the session and tears it down when the session ends.

Agent Relay architecture diagram

What Agent Relay is and isn't

Agent Relay changes where a cloud agent's tool calls execute. It doesn't change where the agent's orchestration or AI inference run. Those stay with the cloud provider.

Agent Relay is not:

  • A replacement for Coder Agents, Coder's own AI workflow infrastructure that runs its native agent loop inside the Coder control plane and calls out to your configured LLM provider for inference.
  • A proxy or observability layer for a provider's AI inference. Coder has no access to model selection or token usage for sessions that run through Agent Relay.
  • A self-hosted deployment of a cloud provider's control plane. The provider's orchestration stays cloud-hosted.

Business value

  • Developers keep using the cloud agent client and workflow they already know.
  • Platform and security teams control the infrastructure where agent sessions execute and which internal resources those sessions can reach.
  • Agent sessions run in workspaces built from the same templates, networking, and governance controls as the rest of your Coder deployment.
  • Each session gets its own workspace, provisioned on demand and deleted when the session ends.

Current state

Agent Relay is in early access and is in closed preview with select customers.

Supported providers

Cursor is the first provider Agent Relay supports. Coder built Agent Relay to support additional cloud-hosted agent providers as they add support for self-hosted execution.

Get started

If you want access to Agent Relay or want updates on the support status for your cloud-hosted agent provider of choice, talk to your Coder account team or email sales@coder.com.

Learn more