Commit 2d16f59

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.

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;">

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.

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

Agent Relay is in [early access](../../install/releases/feature-stages.md#early-access-features) and is in closed preview with select customers.

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

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

- [Agent Relay for Cursor](./cursor.md)

- [Coder Agents](../agents/index.md)

- [Architecture](../../admin/infrastructure/architecture.md)

Learn how to run & manage coding agents with Coder, both alongside existing workspaces and for background task execution.

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:

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

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.

[Learn more about Coder Agents](./agents/index.md) for architecture details, supported LLM providers, and how to get started.

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

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.

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:

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

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.

{

"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"]

}

]

},

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

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