Set up Agent Relay

Create a service accountCopy Anchor Link

Agent Relay needs no site-wide role. At startup, it checks that its service account has the permissions that its pools need.

In every organization that a pool names, the service account needs these permissions:

On every template that a pool names, the service account needs read and use. By default, a new template grants use, which includes read, to its organization's Everyone group, so a service account in the organization already has both. Grant them in the template's permissions only if the template doesn't give the Everyone group access.

The organization-admin role in each organization covers all of these permissions. To grant less, create an organization-scoped custom role with only the permissions above.

1. Create the service account in the organization that Agent Relay serves:

   Copy Text

   coder users create --service-account --username agent-relay --org <org>

2. Add the service account to every other organization that a pool names.

3. Assign the organization-admin role, or your custom role, in each of those organizations.

4. Create a long-lived token for the service account:

   Copy Text

   RELAY_TOKEN=$(coder tokens create --user agent-relay --name agent-relay-token --lifetime 8760h)

5. If you install with Helm, store the token in a Kubernetes secret:

   Copy Text

   kubectl create secret generic agent-relay-coderd \
     --namespace coder \
     --from-literal=session-token="$RELAY_TOKEN"

   The Helm chart doesn't accept the token as a plain value.

Agent Relay verifies organization permissions at startup. A missing organization permission stops the daemon. For example, a service account without the workspace_secret create permission stops it with missing coderd capabilities [set-workspace-secrets[<org id>]]. Agent Relay verifies template permissions per pool. A missing template permission degrades only that pool, and the pool recovers when you fix the template.

Why Agent Relay needs some of these permissions:

• workspace update lets it extend the autostop deadline of workspaces with an active session. It checks for this permission in every organization at startup, even if no template uses keepalive.
• workspace_secret create lets it deliver each session's provider credential to the workspace as an ephemeral workspace build secret. Agent Relay checks the Coder version once, at startup, to decide how to deliver credentials, so restart Agent Relay after you upgrade Coder.

Provision capacity for Agent RelayCopy Anchor Link

Agent Relay builds run on your Coder provisioners, and time spent waiting for a free provisioner counts against each session's build deadline. We recommend dedicated external provisioners for Agent Relay templates, so relay builds don't compete with human workspace builds.

Each provider page explains how to size capacity for its pools:

• Claude Code provisioner capacity
• Cursor provisioner capacity

To run a dedicated set of provisioners on Kubernetes:

1. Create a provisioner key with a tag for Agent Relay:

   Copy Text

   coder provisioner keys create relay-key --org <org> --tag workload=agent-relay

   Copy the key from the output. Coder shows it once.

2. Store the key in a Kubernetes secret:

   Copy Text

   kubectl create secret generic agent-relay-provisioner-key \
     --namespace coder \
     --from-literal=key="<provisioner-key>"

3. Create a provisioner-values.yaml file:

   Copy Text

   coder:
     env:
       - name: CODER_URL
         value: "https://coder.example.com"
     # One provisioner runs one build at a time.
     replicaCount: 10
   provisionerDaemon:
     pskSecretName: ""
     keySecretName: agent-relay-provisioner-key
     keySecretKey: key

   The provisioners pick up the workload=agent-relay tag from the key.

4. Install the coder-provisioner Helm chart with a version that matches your Coder server version:

   Copy Text

   helm install coder-provisioner coder-v2/coder-provisioner \
     --namespace coder \
     --version <coder-version> \
     --values provisioner-values.yaml

5. When you push an Agent Relay template, use the same tag:

   Copy Text

   coder templates push <template> --provisioner-tag workload=agent-relay

If no provisioner with a matching tag is online, relay builds stay pending.

These coder-provisioner chart values affect Agent Relay:

The chart can install more than once under different release names, so you can run one set of provisioners for people and a tagged set for Agent Relay.

Prepare a workspace templateCopy Anchor Link

Each pool builds from one template. Every Agent Relay template must:

• Include the provider's Agent Relay module from the Coder Registry: coder/agent-relay-claude-code or coder/agent-relay-cursor.
• Declare the module's agent_relay_status metadata item on its coder_agent resource. Agent Relay reads this value to decide when to delete the workspace. If you rename or omit the key, Agent Relay never deletes the workspace.
• Set allow_user_cancel_workspace_jobs = true. Agent Relay cancels in-flight builds when it rebuilds or tears down a workspace. Without this setting, the pool degrades.
• Provide a default for every template parameter, or set a value in the pool's template_parameters.

The provider pages show the module block for each provider.

We also recommend that you:

• Use a dedicated template. Relay workspaces are ephemeral and machine-driven. A separate template keeps quotas, access control, and activity policy for people from interfering.
• Use quotas to control spend. Relay builds count against the session owner's quota, the same as any other workspace. Coder enforces quota during the build, so a build that exceeds the owner's quota fails and Agent Relay deletes the workspace. Cursor shows the build error in the developer's chat. Claude Code doesn't show it, so the reason appears only in Agent Relay's logs.
• Keep builds fast. Pre-pull images, avoid persistent volumes, and bake the provider CLI into the image with install_cli = false.
• Own your workspace image. ghcr.io/coder/agent-relay-workspace:latest is a reference image: codercom/enterprise-base:ubuntu with both provider CLIs, rebuilt weekly. Use it as the base of your own image and add your tooling.
• Restrict workspace egress. Agent sessions run unattended. Allow only the hosts on the provider page and the internal services that sessions need.
• Configure Git credentials in the template. Coder can supply each session owner's Git credentials through external authentication, but the template must declare the provider. Refer to the source control section on each provider page.

Start the worker after workspace setupCopy Anchor Link

Agent Relay hands a workspace to the provider as soon as its build succeeds, not when the workspace agent is ready. The provider module starts the worker right away, so the agent can run commands while your startup scripts are still cloning repositories or installing tools.

To make the worker wait, put the setup that sessions need in coder_script resources or modules. Then add a coder_script_order rule that runs the Agent Relay module after them:

resource "coder_script" "setup" {
  agent_id     = coder_agent.main.id
  display_name = "Workspace setup"
  run_on_start = true
  timeout      = 300
  script       = file("${path.module}/setup.sh")
}

data "coder_script_order" "relay_worker" {
  rule {
    phase = "start"
    # Use module.claude_code_runner for Claude Code.
    run   = ["module.cursor_worker"]
    after = ["coder_script.setup"]
  }
}

• Set phase = "start", because the module also has a shutdown script.
• Script ordering requires the Coder Terraform provider v2.20.0 or later.
• Script ordering also requires Coder v2.39.0 or later for the control plane, provisioners, and workspace agents. On earlier versions, Coder ignores the rule without an error, and the worker starts right away.
• Coder can't order the startup_script attribute of coder_agent. Move setup steps that the worker depends on into coder_script resources.
• If a prerequisite fails, Coder skips the module's scripts and the worker never starts. To start the worker even when setup fails, set requires = "completion" on the rule.
• The session waits while prerequisites run. Set a timeout on each prerequisite, and keep setup well under 15 minutes, after which Agent Relay deletes a workspace whose worker hasn't started.

Configure provider poolsCopy Anchor Link

Follow the steps on the provider page to create the provider credential, add the module to your template, and write the pool configuration:

• Configure a Claude Code pool
• Configure a Cursor pool

Then return to this page to install Agent Relay.

Install Agent RelayCopy Anchor Link

Both are public and need no pull credentials. For every option and Helm value, refer to the Agent Relay configuration reference.

Agent Relay release binaries for running as a systemd service aren't published yet.

Verify the deploymentCopy Anchor Link

Agent Relay fails fast at startup. An invalid token, an unlicensed deployment, an unsupported Coder version, or a missing organization permission stops the daemon with an explicit message.

1. Read the daemon's logs:

   Copy Text

   # Kubernetes
   kubectl logs -n coder deploy/coder-agent-relay
   
   # Docker
   docker logs <container>

2. Confirm that the authenticated against coderd log line shows build_secrets=true.

3. Confirm that each pool logs that it's ready.

   A Claude Code pool logs template verified, polling, and a Cursor pool logs pool verified, serving.

4. Confirm that Agent Relay is ready. With Helm, the pod becomes Ready only after at least one pool passes verification. With Docker, run curl -sS http://localhost:2112/readyz, which prints ok when a pool is serving and lists any pool that is still verifying or has failed.

5. Start a session from the provider's client and select the pool.

6. In Coder, confirm that a workspace is created for your user.

7. End the session and confirm that Agent Relay deletes the workspace.

For logs, metrics, and troubleshooting, refer to Monitor Agent Relay.