Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 60 additions & 36 deletions docs/agent-relay/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,6 @@
title: Agent Relay configuration reference
---

<!--
Source: coder/agent-relay at v0.15.0 (commit 9b9657817e):
docs/configuration.md (generated by scripts/docgen), README.md, and
helm/coder-agent-relay/values.yaml.
This page is copied by hand for the beta.
DOCS-1426 tracks automating the sync.
-->

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](./setup.md).

Expand Down Expand Up @@ -139,10 +131,11 @@ Use `secret_env` to keep the secret out of configuration files and Helm values.

### Cursor pool fields

| Field | Required | Description |
|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `cursor_pool_name` | Yes | The pool name that workers register under in Cursor and that developers select. It's separate from `name`, which only labels the pool in Agent Relay. |
| `dispatch_deadline` | No | The longest time from claim to a ready workspace, as a duration such as `10m`. Defaults to `10m`, with a maximum of `15m`. `0` turns off the deadline, but Agent Relay still deletes a workspace that is building after the [startup grace](#--reap-startup-grace), 15&nbsp;minutes by default. |
| Field | Required | Description |
|---------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `cursor_pool_name` | Yes | The pool name that workers register under in Cursor and that developers select. It's separate from `name`, which only labels the pool in Agent Relay. |
| `repo_url` | No | Ties the pool to one repository, such as `https://github.com/coder/coder`. The URL path must end in `<owner>/<repo>`. Agent Relay registers the pool in Cursor with this repository, and sets `agent_relay_cursor_repo_url` to it on builds for requests that don't name a repository. The template must clone the repository and provide Git credentials before the worker starts, for example in the image or in a [script that runs before the module](./setup.md#start-the-worker-after-workspace-setup), and start the worker in the clone. Leave it unset for a pool that isn't tied to a repository. For when to set it, refer to [Source control](./cursor.md#source-control). |
| `dispatch_deadline` | No | The longest time from claim to a ready workspace, as a duration such as `10m`. Defaults to `10m`, with a maximum of `15m`. `0` turns off the deadline, but Agent Relay still deletes a workspace that is building after the [startup grace](#--reap-startup-grace). |

Agent Relay refuses to start if:

Expand Down Expand Up @@ -396,30 +389,61 @@ Set it with [`extraEnv`](#helm-values).
## Helm values

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

| Value | Default | Description |
|----------------------------------------------------------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `image.repository` | `ghcr.io/coder/agent-relay` | The Agent Relay image. |
| `image.tag` | The chart's `appVersion` | The image tag. Set it to pin an image independently of the chart. |
| `image.pullPolicy` | `IfNotPresent` | The image pull policy. |
| `image.pullSecrets` | `[]` | Secrets for pulling the image. The published image is public. |
| `secretEnv` | `[]` | Pool secrets, one entry per `secret_env`. Each entry has a `name`, `secretName`, and `key`, and becomes an environment variable read from a Kubernetes secret. |
| `prometheus.annotations` | `true` | Add the `prometheus.io/*` pod annotations that annotation-based service discovery uses. |
| `extraEnv` | `[]` | More environment variables, added last. Use it for options without a dedicated value. |
| `service.enable` | `false` | Create a Service for the metrics port. Annotation-based scraping targets pods directly and doesn't need it. |
| `service.type` | `ClusterIP` | The Service type. |
| `service.annotations` | `{}` | Annotations for the Service. |
| `serviceAccount.create` | `true` | Create a Kubernetes service account. Agent Relay doesn't call the Kubernetes API, so the chart binds it to no roles. |
| `serviceAccount.name` | `coder-agent-relay` | The name of the Kubernetes service account to create or use. |
| `serviceAccount.annotations` | `{}` | Annotations for the Kubernetes service account. |
| `podAnnotations` | `{}` | More pod annotations, merged over the `prometheus.io/*` annotations. |
| `podLabels` | `{}` | More pod labels. |
| `resources` | `{}` | Resource requests and limits. |
| `nodeSelector`, `tolerations`, `affinity`, `priorityClassName` | Empty | Standard pod scheduling settings. |
| `podSecurityContext` | Non-root user `65532` with the `RuntimeDefault` seccomp profile | The pod security context. |
| `securityContext` | Read-only root filesystem, no privilege escalation, and all capabilities dropped | The container security context. |
| `terminationGracePeriodSeconds` | `60` | The shutdown grace period. Agent Relay stops claiming sessions as soon as it receives a shutdown signal. |
The chart also accepts these values.
The example shows the values you're most likely to change, with their defaults:

```yaml
image:
repository: ghcr.io/coder/agent-relay
# Defaults to the chart's appVersion. Set it to pin an image
# independently of the chart.
tag: ""
pullPolicy: IfNotPresent
# The published image is public, so this is normally empty.
pullSecrets: []

# Pool secrets, one entry per secret_env. Each entry becomes an
# environment variable read from a Kubernetes secret.
secretEnv: []
# - name: BYOC_PROD_SECRET
# secretName: agent-relay-pools
# key: byoc-prod

prometheus:
# Add the prometheus.io/* pod annotations that annotation-based
# service discovery uses.
annotations: true

# More environment variables, added last. Use it for options without a
# dedicated value.
extraEnv: []

service:
# Create a Service for the metrics port. Annotation-based scraping
# targets pods directly and doesn't need it.
enable: false
type: ClusterIP
annotations: {}

serviceAccount:
# Agent Relay doesn't call the Kubernetes API, so the chart binds the
# service account to no roles.
create: true
name: coder-agent-relay
annotations: {}

# Merged over the prometheus.io/* annotations.
podAnnotations: {}
podLabels: {}
resources: {}

# Agent Relay stops claiming sessions as soon as it receives a shutdown
# signal.
terminationGracePeriodSeconds: 60
```

The chart also accepts the standard pod settings `nodeSelector`, `tolerations`, `affinity`, and `priorityClassName`, which are empty by default.
By default, `podSecurityContext` runs as the non-root user `65532` with the `RuntimeDefault` seccomp profile, and `securityContext` sets a read-only root filesystem, disables privilege escalation, and drops all capabilities.

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

Expand Down
41 changes: 41 additions & 0 deletions docs/agent-relay/cursor.md
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@

1. **Cursor must see the repository.**
Connect every repository developers will select to your Cursor team's source control integration.
1. **The workspace must be able to clone and push.**

Check warning on line 306 in docs/agent-relay/cursor.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.StepLength

This step's instruction has more than 20 words. Shorten it, split the step, or move the explanation to a paragraph below the instruction. Refer to procedural-writing.md#keep-steps-short.
Coder can supply each developer's Git credentials through external authentication, but the template must declare the provider.
The worker token that Agent Relay provides authenticates to Cursor only.

Expand All @@ -328,6 +328,47 @@
Each pool maps to one template.
Use separate pools when repositories need different templates or credentials.

To give one repository a template of its own, such as an image that has the repository cloned and its toolchain installed, set [`repo_url`](./configuration.md#cursor-pool-fields) on a pool for that repository.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just wondering, does the worker need to start in the cloned repo? The module doesn't pass --worker-dir, so it defaults to the agent's directory (usually home), which may be outside the repo.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, good catch. The worker runs sessions in the directory it starts in, and Cursor derives a repo-backed worker's repo label from that directory's Git remote. The module's start.sh.tftpl runs agent worker with no --worker-dir, so without a change the worker would start in the agent's directory.

Fixed in afbafed:

  • cursor.md Source control now says to start the worker in the clone for a repo-backed pool, with a coder_agent dir example. The example/templates/cursor template in agent-relay v0.16.0 does the same thing. The alternative is additional_args = ["--worker-dir", "<clone>"], which the module's additional_args validation allows.
  • The repo_url row in configuration.md now ends with "and start the worker in the clone".

Generated by Coder Agents on behalf of @nickvigilante.

Cursor calls this a repo-backed pool.
A pool without `repo_url` is an any-repo pool, which serves sessions for any repository, so its workspaces get the repository in one of the ways described earlier in this section.
For how Cursor routes sessions to each kind of pool, refer to [Cursor's any-repo pools documentation](https://cursor.com/docs/cloud-agent/self-hosted/pool#any-repo-pools).

In a repo-backed pool, start the worker in the clone.
The worker runs sessions in the directory it starts in, and the module doesn't pass `--worker-dir`, so the worker starts in the agent's directory, which is usually the home directory.
Set `dir` on `coder_agent` to the clone's path:

```tf
resource "coder_agent" "main" {
os = "linux"
arch = "amd64"
# The path the template or image clones the repository into.
dir = "/home/coder/repo"
}
```

The directory must exist before the worker starts, so clone into it in the image or in a [script that runs before the module](./setup.md#start-the-worker-after-workspace-setup).
To start the worker in a different directory than the agent, pass `additional_args = ["--worker-dir", "/home/coder/repo"]` to the module instead.

For example, these two pools share one API key:

```yaml
# Under cursorWorkerPools in config.yaml, or pools.cursor in values.yaml.
- name: coder-repo
secret_env: CURSOR_SERVICE_ACCOUNT_KEY
cursor_pool_name: coder-repo
organization: coder
# The image has coder/coder cloned and its toolchain installed.
template: cursor-coder
repo_url: https://github.com/coder/coder
- name: any-repo
secret_env: CURSOR_SERVICE_ACCOUNT_KEY
cursor_pool_name: any-repo
organization: coder
template: cursor-relay
```

In the Cursor dashboard, `coder-repo` appears under the `coder/coder` repository, and `any-repo` appears under **Any repo**.

## Workspace lifecycle

The module reports the worker's state through `agent_relay_status`, and Agent Relay's reaper acts on it:
Expand Down
Loading