Agent Relay configuration reference

This page lists the Agent Relay options, pool fields, and Helm chart values that the beta supports. For a guided installation, refer to Set up Agent Relay.

Configuration sourcesCopy Anchor Link

Agent Relay reads each option from three sources, in this order of precedence:

1. A command-line flag, such as --log-level.
2. An environment variable, such as CODER_AGENT_RELAY_LOG_LEVEL.
3. A key in the YAML file that --config points to, such as logLevel.

The Helm chart sets options through environment variables and doesn't use a configuration file. Each option below lists its Helm value. Refer to Helm values for chart settings that aren't Agent Relay options.

Keep credentials out of the configuration file:

• Set the session token with the CODER_AGENT_RELAY_CODERD_SESSION_TOKEN environment variable. Do not put it in the configuration file.
• Set each pool's secret_env to the name of an environment variable that holds the pool's secret.

Agent Relay validates its options and pool fields at startup. An invalid value stops the daemon with an error that names the option or pool.

Coder deploymentCopy Anchor Link

--coderd-urlCopy Anchor Link

The access URL of the Coder deployment that Agent Relay serves. This flag is required.

--coderd-session-tokenCopy Anchor Link

The session token of the Agent Relay service account. This flag is required. Prefer the environment variable to the flag or the coderSessionToken configuration file key. The Helm chart reads it from a Kubernetes secret and doesn't accept it as a plain value. Refer to Step 1: Create a service account.

--configCopy Anchor Link

The path to a YAML configuration file.

PoolsCopy Anchor Link

A pool maps a provider credential to a Coder organization and template. Configure at least one pool across both providers. A provider without pools is turned off.

Set pools in the YAML file, in Helm values, or as a JSON array in the pool option's environment variable:

export CODER_AGENT_RELAY_CLAUDE_CODE_RUNNER_POOLS='[{"name":"example","secret_env":"CLAUDE_ENVIRONMENT_SECRET","organization":"coder","template":"claude-code-relay"}]'
export CODER_AGENT_RELAY_CURSOR_WORKER_POOLS='[{"name":"example","secret_env":"CURSOR_SERVICE_ACCOUNT_KEY","cursor_pool_name":"example-pool","organization":"coder","template":"cursor-relay"}]'

--claude-code-runner-poolsCopy Anchor Link

The Claude Code self-hosted environments to serve. Each pool maps an environment key to a Coder organization and template. Refer to Pool fields and Agent Relay for Claude Code.

--cursor-worker-poolsCopy Anchor Link

The Cursor self-hosted pools to serve. Each pool maps a Cursor service account API key to a Coder organization and template. Refer to Pool fields and Agent Relay for Cursor.

Pool fieldsCopy Anchor Link

Fields for every poolCopy Anchor Link

Agent Relay also accepts an inline secret field in place of secret_env. Set exactly one of the two. Use secret_env to keep the secret out of configuration files and Helm values.

Claude Code pool fieldsCopy Anchor Link

Cursor pool fieldsCopy Anchor Link

Agent Relay refuses to start if:

• More than four pools share one API key.
• Two pools that share an API key use the same cursor_pool_name.
• A dispatch_deadline is longer than 15 minutes.

Pin a template versionCopy Anchor Link

Leave template_version unset so that builds use the template's active version, and roll out changes by promoting a version in Coder. When a pool sets template_version, all of its builds use that version, including rebuilds of existing workspaces:

• If the template requires the active version, Coder refuses builds from any other version unless the Agent Relay service account has update on the template. Agent Relay marks the pool degraded before it starts serving if the account lacks that permission, but doesn't check again. If someone promotes a newer version later, every session fails at build time.
• If the version is deleted, archived, or renamed, the pool degrades and its sessions fail without retry until you fix the configuration.
• The pool doesn't pick up newly promoted versions, so module and contract changes don't reach it.

Reserved template parameter namesCopy Anchor Link

Agent Relay sets these parameters on every build to carry the session's identity. It refuses to start if a pool's template_parameters uses one of them.

Cursor request queueCopy Anchor Link

These options apply to every Cursor pool. The Helm chart has no dedicated values for them. Set them with extraEnv.

--cursor-relist-intervalCopy Anchor Link

How often each Cursor pool lists pending requests. Agent Relay also follows Cursor's event stream, but the list is the source of truth. A shorter interval makes more Cursor API calls in exchange for a more current view of the queue. Cursor expires a stream position 5 minutes after the list that issued it, so a longer interval still lists again when the position expires.

--cursor-relist-jitterCopy Anchor Link

The longest random delay that Agent Relay adds to each pool's list interval, so that pools don't list in lockstep. Set 0 to list exactly on the interval.

--cursor-api-urlCopy Anchor Link

The base URL of Cursor's fleet management API.

LoggingCopy Anchor Link

For log fields and examples, refer to Monitor Agent Relay.

--log-levelCopy Anchor Link

The minimum log level: debug, info, warn, or error.

--log-formatCopy Anchor Link

The log output format: human or json. Use json for log aggregation.

Prometheus metricsCopy Anchor Link

For the metrics that Agent Relay exports, refer to Monitor Agent Relay.

--prometheus-enableCopy Anchor Link

Serve Prometheus metrics, and the /readyz readiness endpoint, on the address in --prometheus-address. Metrics are served over plain HTTP. /readyz returns 200 once at least one pool has passed verification and 503 before that, and lists each pool that is still verifying or has failed. The Helm chart uses /readyz as the pod's readiness probe.

--prometheus-addressCopy Anchor Link

The address that the metrics listener binds to. The default binds to loopback, which isn't reachable from outside a container. In Docker, set 0.0.0.0:2112. The Helm chart always binds to 0.0.0.0 on prometheus.port.

Workspace reaperCopy Anchor Link

--reap-workersCopy Anchor Link

How many workspaces the reaper handles at the same time during each sweep. Workspace statuses and session attachment arrive with the workspace list, so this option limits only the delete, cancel, nack, and deadline extension calls that a sweep makes. The Helm chart has no dedicated value for this option. Set it with extraEnv.

--reap-keepalive-refresh-beforeCopy Anchor Link

Extends an attached workspace when its autostop deadline is less than this duration away and its attachment sample is fresh. Must be at least 5m. The sum of this option and --reap-keepalive-bump-by must be at least 31m. This option is shared by every pool and is independent of idle_release_timeout. The Helm chart has no dedicated value for this option. Set it with extraEnv. Refer to Keep attached workspaces running.

--reap-keepalive-bump-byCopy Anchor Link

Extra time beyond --reap-keepalive-refresh-before for the new deadline. Agent Relay measures the new deadline from now, not from the old deadline. Must be positive. The workspace TTL takes precedence when it's longer, and the build's maximum deadline still caps the new deadline. The Helm chart has no dedicated value for this option. Set it with extraEnv.

Helm valuesCopy Anchor Link

The chart's Agent Relay options are listed with each option above. The chart also accepts these values:

For example, to set options that have no dedicated value:

extraEnv:
  - name: CODER_AGENT_RELAY_REAP_WORKERS
    value: "10"
  - name: CODER_AGENT_RELAY_CURSOR_RELIST_INTERVAL
    value: 2m

The chart always runs one replica with the Recreate strategy. Two relays that serve the same pools both claim sessions and compete over the same workspaces.

Learn moreCopy Anchor Link

• Set up Agent Relay
• Agent Relay for Claude Code
• Agent Relay for Cursor
• Monitor Agent Relay