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
4 changes: 3 additions & 1 deletion docs/agent-relay/claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@
Use the latest module version from the registry.

> [!NOTE]
> Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release, and receive the credential as a workspace build secret.
> Module version 1.0.0 and later need Coder 2.39 or later and Agent Relay v0.16.0 or later, and receive the credential as a workspace build secret.
> Do not set `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` in the template yourself.
> To upgrade from an early access module version, refer to [Upgrade from early access](./setup.md#upgrade-from-early-access).

Expand Down Expand Up @@ -218,6 +218,8 @@
If no runner starts within the budget, Anthropic offers the session again.
- The budget starts when Anthropic issues the session's work order, so time in Anthropic's queue and time waiting for a provisioner both count.
- When a build misses the budget, Agent Relay reports the failure to Anthropic, cancels the build if it's still running, and deletes the workspace.
- When a build succeeds but the runner never starts, Agent Relay v0.16.0 or later lets Anthropic retry the session only on its first delivery, and only within `dispatch_deadline` of the build's creation.
Otherwise, it fails the session, so a broken template doesn't rebuild in a loop.

For templates where the image pull and build regularly take longer than 5 minutes, raise `dispatch_deadline`.

Expand Down Expand Up @@ -288,7 +290,7 @@

1. **Claude Code must see the repository.**
Claude Code only offers repositories that the Claude GitHub app can reach.
1. **The workspace must be able to clone and push.**

Check warning on line 293 in docs/agent-relay/claude-code.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.
The runner clones the selected repository with the Git credentials in the workspace.
Coder can supply each developer's credentials through external authentication, but a template admin must configure the template to provide them.

Expand Down
2 changes: 2 additions & 0 deletions docs/agent-relay/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -303,6 +303,8 @@ Must be positive.

- If a build is still pending or starting after the longer of this grace and the pool's `dispatch_deadline`, the reaper deletes the workspace.
- A workspace where the build succeeded but the worker still reports no status, or `pending`, fails after this grace.
In Agent Relay v0.16.0 or later, a workspace whose agent reports that startup scripts failed or timed out fails sooner, about a minute after the agent reports it.
Refer to [Start the worker after workspace setup](./setup.md#start-the-worker-after-workspace-setup).
- A short grace can fail workspaces where the agent connects slowly or the worker starts slowly.
Unless you run an isolated test deployment, keep the default.
- When the template orders the worker after setup scripts, this is the budget those scripts share with the build.
Expand Down
2 changes: 1 addition & 1 deletion docs/agent-relay/cursor.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@
Use the latest module version from the registry.

> [!NOTE]
> Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release, and receive the credential as a workspace build secret.
> Module version 1.0.0 and later need Coder 2.39 or later and Agent Relay v0.16.0 or later, and receive the credential as a workspace build secret.
> Do not set `AGENT_RELAY_CURSOR_TOKEN` in the template yourself.
> To upgrade from an early access module version, refer to [Upgrade from early access](./setup.md#upgrade-from-early-access).

Expand Down 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 Down
2 changes: 1 addition & 1 deletion docs/agent-relay/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ One Agent Relay process can serve pools for both providers.

## Requirements

Agent Relay requires a Premium license, Coder 2.39 or later, the latest Agent Relay release, and a plan with a [supported provider](#supported-providers).
Agent Relay requires a Premium license, Coder 2.39 or later, Agent Relay v0.16.0 or later, and a plan with a [supported provider](#supported-providers).
For the full list, refer to [Before you begin](./setup.md#before-you-begin).

## Known limitations
Expand Down
14 changes: 9 additions & 5 deletions docs/agent-relay/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
You need:

- A Coder deployment with a Premium license, on version 2.39 or later.
- The latest Agent Relay release.
- Agent Relay v0.16.0 or later.
- Somewhere to run the Agent Relay container: a Kubernetes cluster that you can reach with `kubectl` and `helm`, or a Docker host.
- The [Coder CLI](https://coder.com/downloads), signed in as an `owner`.
- An account with the provider you want to serve.
Expand Down Expand Up @@ -248,10 +248,10 @@
- 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 or times out, Coder skips the module's scripts and the worker never starts.
Agent Relay newer than v0.15.0 fails the session about a minute later.
Agent Relay v0.16.0 or later fails the session about a minute later.
A Cursor request fails at that point.
For Claude Code, Agent Relay hands the work order back to Anthropic once, rebuilds the workspace when Anthropic redelivers it, and fails the session if the second setup fails too.
Agent Relay v0.15.0 and older wait out the [startup grace](./configuration.md#--reap-startup-grace) before failing a Cursor request, 15 minutes by default, and hand a Claude Code work order back as retryable every time, so each redelivery runs the same setup again.
Agent Relay skips that retry when the failure comes later than the pool's `dispatch_deadline` after the build was created.
On a claimed prebuild, the status item keeps reporting the prebuild's `idle`, so Agent Relay neither fails the session nor deletes the workspace.
To start the worker even when setup fails, set `requires = "completion"` on the rule.
- The session waits while prerequisites run, so set a `timeout` on each prerequisite.
Expand Down Expand Up @@ -289,7 +289,7 @@

### Kubernetes

1. Create a `values.yaml` file with your Coder URL, the token secret from step 1, and the pools and secrets from the provider page:

Check warning on line 292 in docs/agent-relay/setup.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.

```yaml
coderd:
Expand Down Expand Up @@ -386,7 +386,7 @@

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

1. Confirm that Agent Relay is ready.

Check warning on line 389 in docs/agent-relay/setup.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.
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.

Expand All @@ -413,10 +413,14 @@
| The worker exited normally | Deletes the workspace. |
| The worker failed or disappeared | Reports the failure to the provider, then deletes the workspace. |
| The build succeeded, but the worker hasn't started within the startup grace | Reports the failure to the provider, then deletes the workspace. |
| The worker hasn't started, and the agent reports that startup scripts failed or timed out | Reports the failure to the provider, then deletes the workspace. |
| The build failed or was canceled | Deletes the workspace. |
| The build is still running after the longer of the startup grace and the pool's `dispatch_deadline` | Cancels the build, then deletes the workspace. |

The startup grace is 15 minutes by default and starts when the latest build is created.
For failed or timed-out startup scripts, Agent Relay v0.16.0 or later doesn't wait for the startup grace.
After the agent reports `start_error` or `start_timeout`, the reaper waits for two `pending` reads of the worker status, the second from a newer status sample than the first.
Refer to [Start the worker after workspace setup](#start-the-worker-after-workspace-setup).
If you set a [reap delay](./configuration.md#--reap-delay), the reaper waits for it before it deletes a workspace or reports a failure, except in the cases that the option's reference lists.
If a delete fails three times in a row, the reaper stops and leaves the workspace for you to remove.
Refer to [A workspace is never deleted](./troubleshooting.md#a-workspace-is-never-deleted).
Expand Down Expand Up @@ -484,7 +488,7 @@

## Upgrade from early access

Current Agent Relay releases and module version 1.0.0 deliver provider credentials as workspace build secrets, which need Coder 2.39 or later.
Agent Relay v0.16.0 or later and module version 1.0.0 deliver provider credentials as workspace build secrets, which need Coder 2.39 or later.
Early access module versions, `agent-relay-claude-code` 0.4.0 or earlier and `agent-relay-cursor` 0.7.0 or earlier, don't support build secrets.
Upgrade Coder, Agent Relay, and every Agent Relay template in the same maintenance window.
If you need help planning the upgrade, contact Coder.
Expand All @@ -500,7 +504,7 @@

`0` still turns off idle release.

1. Upgrade Agent Relay to the latest release.
1. Upgrade Agent Relay to v0.16.0 or later.

1. Update every Agent Relay template to module version 1.0.0.

Expand Down
5 changes: 2 additions & 3 deletions docs/agent-relay/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,13 +102,12 @@

Agent Relay hands off the workspace when its build succeeds, and the module starts the worker without waiting for startup scripts.
Order the module after your setup scripts, as described in [Start the worker after workspace setup](./setup.md#start-the-worker-after-workspace-setup).
With the rule in place, Agent Relay newer than v0.15.0 notices a failed setup about a minute after the agent reports `start_error`, or `start_timeout` when a setup script reaches its `timeout`.
With the rule in place, Agent Relay v0.16.0 or later notices a failed setup about a minute after the agent reports `start_error`, or `start_timeout` when a setup script reaches its `timeout`.
Cursor fails the request then, and Claude Code retries once on a new workspace before failing the session.
Claude Code skips the retry when the failure comes later than the pool's `dispatch_deadline` after the build was created.
In the relay logs, the reaper's `session did not finish cleanly, reporting and deleting` line carries `agent_lifecycle=start_error` with `reason="the workspace agent's startup scripts failed"`, or `agent_lifecycle=start_timeout` with `reason="the workspace agent's startup scripts timed out"`.
Only Claude Code sessions receive the reason in their error.
Cursor users see a fixed message that the worker stopped before serving the request.
Agent Relay v0.15.0 and older wait out the startup grace instead, 15 minutes by default, and then fail a Cursor request because the worker never started.
Those versions hand a Claude Code work order back as retryable every time, so each redelivery runs the same setup again.
On a claimed prebuild, the status item keeps reporting the prebuild's `idle` after a failed setup, so Agent Relay neither fails the session nor deletes the workspace.

## Claude Code sessions
Expand Down Expand Up @@ -164,7 +163,7 @@
|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Claude doesn't reply, or no `cc-` workspace appears | The channel resolves to another environment, the thread started before the change, a Slack guest is in the channel, or the Tag pool isn't serving. |
| Claude Tag channel sessions are rejected | The pool has no `claude_tag_channel_user`, the relay wasn't restarted after the change, or the value isn't `me` or the UUID of an active member of the organization. |
| A Tag pool workspace is owned by a person | Someone selected the Tag environment in the environment picker, or a Slack DM landed on it. |

Check warning on line 166 in docs/agent-relay/troubleshooting.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.AbbreviationFirstUse

Expand 'DM' on its first use on the page, in the form 'Expanded Form (ABBR)'. Refer to accessibility-and-inclusion.md#expand-abbreviations-on-first-use.
| Claude can't reach a repository or service | Claude Tag connections don't apply in self-hosted sessions, or the template's Tag user UUID doesn't match `claude_tag_channel_user`. |
| Cursor shows an `agent-relay:` account error | The person's Cursor email doesn't match an active member of the pool's organization, or a service account started the agent. |
| A Cursor mention doesn't run on the Agent Relay pool | **Allow Self-Hosted Machines** is off, the message overrides the pool, no default pool applies, or the person's own default worker takes priority. |
Expand Down
Loading