coder · mattvollmer · Sep 2, 2026 · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026
diff --git a/docs/ai-coder/agent-relay/cursor.md b/docs/ai-coder/agent-relay/cursor.md
@@ -0,0 +1,38 @@
+---
+title: Agent Relay for Cursor
+---
+
+> [!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.
-[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.
-[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.
+Cursor also refers to this self-hosted worker model as [bring-your-own-machine (BYOM)](https://cursor.com/docs/cloud-agent/bring-your-own-machine).
+Developers keep using the Cursor client and cloud agent workflow they already know.
+The agent's tool calls run inside a Coder workspace on infrastructure you control instead of a Cursor-managed environment.
+
+Cursor's agent orchestration and AI inference remain cloud-hosted.
+Coder doesn't proxy or observe model inference.
+Coder provides the workspace where the agent executes, and logs that correlate the Cursor session and user to that workspace.
+
+## How it works
+
+1. A developer selects a Cursor worker pool mapped to a Coder organization and workspace template, then starts a Cursor agent session.
+1. Agent Relay claims the pending Cursor request and asks the Coder control plane to provision a workspace from the mapped template for that user.
+1. A Cursor worker process inside the workspace connects to the corresponding Cursor cloud session and executes the agent's tool calls.
+1. When the session ends, Agent Relay manages workspace teardown.
+
+Each Cursor agent session gets its own ephemeral workspace.
+
+## Requirements
+
+- A licensed Coder deployment
+- A Cursor Enterprise plan
+
+## Get started
+
+Talk to your [Coder account team](https://coder.com/contact) or email [[email protected]](mailto:[email protected]) to get access to Agent Relay for Cursor.
+
+## Learn more
+
+- [Agent Relay](./index.md)
+- [Architecture](../../admin/infrastructure/architecture.md)
diff --git a/docs/ai-coder/agent-relay/index.md b/docs/ai-coder/agent-relay/index.md
@@ -0,0 +1,56 @@
+---
+title: Agent Relay
+---
+
+Agent Relay connects a cloud-hosted AI coding agent's hosted sessions to self-hosted [Coder workspaces](../../user-guides/workspace-management.md).
+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.
+
+<img src="../../images/guides/ai-agents/agent-relay-stack.png" alt="Agent Relay architecture diagram" style="border: none;">
+
+## 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](../agents/index.md), 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](../../install/releases/feature-stages.md#early-access-features) and is in closed preview with select customers.
+
+## Supported providers
+
+[Cursor](./cursor.md) 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](https://coder.com/contact) or email [[email protected]](mailto:[email protected]).
+
+## Learn more
+
+- [Agent Relay for Cursor](./cursor.md)
+- [Coder Agents](../agents/index.md)
+- [Architecture](../../admin/infrastructure/architecture.md)
diff --git a/docs/ai-coder/index.md b/docs/ai-coder/index.md
@@ -2,53 +2,70 @@
 title: Run AI Coding Agents in Coder
 ---
 
-Learn how to run & manage coding agents with Coder, both alongside existing
-workspaces and for background task execution.
+Learn how to run & manage coding agents with Coder, both alongside existing workspaces and for background task execution.
 
-## Agents in the IDE
-
-Coder [integrates with IDEs](../user-guides/workspace-access/index.md) such as
-Cursor, Devin Desktop, and Zed that include built-in coding agents to work alongside
-developers. Additionally, template admins can
-[pre-install extensions](https://registry.coder.com/modules/coder/vscode-web)
-for agents such as GitHub Copilot.
+Coder supports several ways to run and [govern](#govern-ai-activity-with-ai-governance) coding agents, depending on how much control you need over execution and orchestration:
 
-These agents work well inside existing Coder workspaces as they can simply be
-enabled via an extension or are built-into the editor.
+- [Coder Agents](#coder-agents), self-hosted AI workflow infrastructure best suited for headless, automated background tasks and parallel agentic development in a conversational UI.
+- [Agent Relay](#agent-relay), best suited for preserving the cloud agent experience developers already know while running execution in self-hosted Coder workspaces.
+- [Agents in the IDE](#agents-in-the-ide), best suited for in-editor code assist use cases alongside a developer's existing workflow.
+- [Agents in workspace templates](#agents-in-workspace-templates), best suited for developers who want to pair one-on-one with an agent like Claude Code or Codex in a workspace.
 
 ## Coder Agents
 
-In cases where the IDE is secondary, such as prototyping, research, or
-long-running background jobs, [Coder Agents](./agents/index.md) is the
-recommended way to delegate development work to coding agents in your Coder
-deployment.
+In cases where the IDE is secondary, such as prototyping, research, or long-running background jobs, [Coder Agents](./agents/index.md) is the recommended way to delegate development work to coding agents in your Coder deployment.
 
-Coder Agents is a native AI coding agent built into Coder. The agent loop runs
-in the Coder control plane on your infrastructure rather than inside the
-workspace, so workspaces can be completely network isolated. Developers
-interact with agents through the web UI or the REST API.
+Coder Agents is a native AI coding agent built into Coder.
+The agent loop runs in the Coder control plane on your infrastructure rather than inside the workspace, so workspaces can be completely network isolated.
+Developers interact with agents through the web UI or the REST API.
 
 ![Coder Agents chat interface with git diff sidebar](../images/agents-hero-image.png)
 
-[Learn more about Coder Agents](./agents/index.md) for architecture details,
-supported LLM providers, and how to get started.
+[Learn more about Coder Agents](./agents/index.md) for architecture details, supported LLM providers, and how to get started.
+
+## Agent Relay
+
+[Agent Relay](./agent-relay/index.md) 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.
+[Cursor Cloud Agents](https://cursor.com/cloud) is the first supported provider.
+
+Agent Relay is in [early access](../install/releases/feature-stages.md#early-access-features) and is in closed preview with select customers.
+
+[Learn more about Agent Relay](./agent-relay/index.md) for architecture details and supported providers.
+
+## Agents in the IDE
+
+Coder [integrates with IDEs](../user-guides/workspace-access/index.md) such as Cursor, Devin Desktop, and Zed that include built-in coding agents to work alongside developers.
+Additionally, template admins can [pre-install extensions](https://registry.coder.com/modules/coder/vscode-web) for agents such as GitHub Copilot.
+
+These agents work well inside existing Coder workspaces as they can simply be enabled via an extension or are built-into the editor.
+
+## 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.
+
+[Learn more about extending templates](../admin/templates/extending-templates/index.md).
 
 ## Govern AI activity with AI Governance
 
-AI coding tools are quickly becoming core to how engineering teams ship
-software. As adoption grows, platform teams want a clear picture of how AI is
-being used, consistent guardrails across teams, and predictable cost controls
-so they can confidently scale AI tooling to the whole organization.
-
-[AI Governance](./ai-governance.md) is included with a Premium license and adds
-observability, management, and policy controls for AI tooling across your
-Coder deployment. It includes:
-
-- [AI Gateway](./ai-gateway/index.md) for centralized authentication, audit
-  trails of prompts and tool invocations, and policy enforcement against
-  upstream LLM providers.
-- [Agent Firewall](./agent-firewall/index.md) for process-level network and
-  command policies that restrict what agents can reach and do inside a
-  workspace.
-[Learn more about AI Governance](./ai-governance.md) for use cases, entitlements,
-and how to enable it in your deployment.
+AI coding tools are quickly becoming core to how engineering teams ship software.
+As adoption grows, platform teams want a clear picture of how AI is being used, consistent guardrails across teams, and predictable cost controls so they can confidently scale AI tooling to the whole organization.
+
+[AI Governance](./ai-governance.md) is included with a Premium license and adds observability, management, and policy controls for AI tooling across your Coder deployment.
+It includes:
+
+- [AI Gateway](./ai-gateway/index.md) for centralized authentication, audit trails of prompts and tool invocations, and policy enforcement against upstream LLM providers.
+- [Agent Firewall](./agent-firewall/index.md) for process-level network and command policies that restrict what agents can reach and do inside a workspace.
+
+[Learn more about AI Governance](./ai-governance.md) for use cases, entitlements, and how to enable it in your deployment.
diff --git a/docs/images/guides/ai-agents/agent-relay-stack.png b/docs/images/guides/ai-agents/agent-relay-stack.png
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -1135,6 +1135,20 @@
 						}
 					]
 				},
+				{
+					"title": "Agent Relay",
+					"description": "Connect supported cloud-hosted AI agents to self-hosted Coder workspaces with Agent Relay.",
+					"path": "./ai-coder/agent-relay/index.md",
+					"state": ["early access"],
+					"children": [
+						{
+							"title": "Agent Relay for Cursor",
+							"description": "Run Cursor's cloud agent sessions inside self-hosted Coder workspaces with Agent Relay.",
+							"path": "./ai-coder/agent-relay/cursor.md",
+							"state": ["early access"]
+						}
+					]
+				},
 				{
 					"title": "AI Governance",
 					"description": "Govern AI usage at scale with AI Governance: Agent Firewall, AI Gateway, and reporting.",

diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
@@ -9,6 +9,7 @@
 > Several Coder terms share the word "agent" but mean different things:
 >
 > - [Coder Agents](#coder-agents) is the AI product for delegating development work to coding agents.
+> - [Agent Relay](#agent-relay) connects a cloud-hosted AI agent provider's hosted sessions to self-hosted workspaces. It is not Coder Agents.
 > - A [workspace agent](#workspace-agent) is the process that runs inside a workspace to provide SSH, port forwarding, the web terminal, and other services.
 > - [`coder_agent`](#coder_agent) is the Terraform resource in a template that declares a workspace agent.
 
@@ -26,6 +27,13 @@
 This feature requires a Premium license.
 Refer to [Agent Firewall](../ai-coder/agent-firewall/index.md).
 
+### Agent Relay
+
+A feature that connects a supported cloud-hosted AI agent provider's hosted sessions to self-hosted [workspaces](#workspace).
+The provider's orchestration and AI inference stay cloud-hosted; a worker process inside the workspace executes the agent's tool calls.
+In [early access](../install/releases/feature-stages.md#early-access-features).
+Refer to [Agent Relay](../ai-coder/agent-relay/index.md).
+
 ### AI Gateway
 
 An LLM gateway in `coderd` that authenticates users, forwards traffic to providers such as OpenAI and Anthropic, audits prompts and tool invocations, and centralizes MCP administration.
@@ -148,7 +156,7 @@
 The Go SDK that the CLI and dashboard use and that you can use for automation.
 Refer to the [`codersdk` package](https://pkg.go.dev/github.com/coder/coder/v2/codersdk).

 ### Coding agent

 An AI agent that reads and writes code on a developer's behalf, such as Claude Code or Coder Agents.
 Refer to [AI in Coder](../ai-coder/index.md).

diff --git a/docs/user-guides/workspace-management.md b/docs/user-guides/workspace-management.md
@@ -1,15 +1,14 @@
 # Workspaces
 
-A workspace is the environment that a developer works in. Developers in a team
-each work from their own workspace and can use
-[multiple IDEs](./workspace-access/index.md).
+A workspace is the environment where a developer or a coding agent works.
+Developers and agents in a team each work from their own workspace and can use [multiple IDEs](./workspace-access/index.md).
 
 A developer creates a workspace from a
 [shared template](../admin/templates/index.md). This lets an entire team work in
 environments that are identically configured and provisioned with the same
 resources.

 ## Creating workspaces

 You can create a workspace in the UI. Log in to your Coder instance, go to the
 **Templates** tab, find the template you need, and select **Create Workspace**.
@@ -78,7 +77,7 @@
  `include_agent_metadata:cpu_usage`. Repeat the key to request multiple
  metadata items. Keys match case-insensitively.

 ## Updating workspaces

 After updating the default version of the template that a workspace was created
 from, you can update the workspace.
@@ -88,7 +87,7 @@
 If the workspace is running, Coder stops it, updates it, then starts the
 workspace again.

 ### Updating via the CLI

 Update a workspace through the command line:

@@ -123,7 +122,7 @@

 ![Bulk workspace actions](../images/user-guides/workspace-bulk-actions.png)

 ## Starting and stopping workspaces

 By default, you manually start and stop workspaces as you need. You can also
 schedule a workspace to start and stop automatically.
@@ -150,7 +149,7 @@
 though the exact behavior depends on the template. For more information, see
 [Resource Persistence](../admin/templates/extending-templates/resource-persistence.md).

 ## Repairing workspaces

 Use the following command to re-enter template input variables in an existing
 workspace. This command is useful when a workspace fails to build because its