feat(agent-relay-claude-code): add the Agent Relay Claude Code module - #1114
Open
Emyrk wants to merge 1 commit into
Open
feat(agent-relay-claude-code): add the Agent Relay Claude Code module#1114Emyrk wants to merge 1 commit into
Emyrk wants to merge 1 commit into
Conversation
Template module that declares the parameter contract Agent Relay stamps on a build and runs the Claude Code self-hosted runner detached, publishing its lifecycle through the agent_relay_status agent metadata item. Moved from coder/agent-relay, where it was developed against the daemon. main.test.ts runs the rendered script in a container with a stub claude binary and observes the idle, failed, working, and done states.
Contributor
Module Scorecard Check
|
| Presentation & Onboarding | Agent Integration | Credential Hygiene | Restricted-Environment Readiness | Engineering Quality | Overall |
|---|---|---|---|---|---|
| 6 / 17 | 15 / 25 | 18 / 20 | 5 / 20 | 8 / 10 | 57 / 100 |
Drilldown
Agent Integration — 15 / 25
| Criterion | Max | Score | Notes |
|---|---|---|---|
| AI governance | 10 | 5 | README documents Agent Relay integration but does not mention Agent Firewall. AI Gateway is not documented. Only Agent Relay's routing and credential enforcement is covered, earning half. |
| Dashboard entry point | 5 | 5 | The module is designed for Agent Relay dispatch; no coder_app is needed or documented for Claude Code runners, which are headless. The agent metadata provides visibility. Full credit as the architecture does not require a dashboard app. |
| Session continuity | 5 | 0 | No documentation of resuming sessions or using persistent session managers like tmux/screen. The runner serves one session per workspace lifecycle. |
| Managed configuration | 5 | 5 | Documents managed configuration through module variables (cli_binary, state_file, log_file, serving_log_pattern) and the permissions wrapper that forces bypassPermissions. |
Credential Hygiene — 18 / 20
| Criterion | Max | Score | Notes |
|---|---|---|---|
| Secrets marked sensitive | 16 | 16 | agent_relay_credential parameter has mask_input = true in styling. README example shows no inline secrets, using the module's parameter system. |
| Non-hardcoded auth path | 4 | 2 | Uses Agent Relay's work-order JWT system, which is a form of external auth, but the README does not document alternative paths like ServiceAccount or OAuth. Half credit for the relay-mediated credential flow. |
Presentation & Onboarding — 6 / 17
| Criterion | Max | Score | Notes |
|---|---|---|---|
| Configuration-mode examples | 12 | 6 | README shows one basic example with install_cli toggle documented. No examples for different deployment modes (e.g., pre-baked CLI vs download, custom paths). Half credit. |
| Visual preview | 5 | 0 | No image, GIF, or video in README. Icon reference does not count. |
Restricted-Environment Readiness — 5 / 20
| Criterion | Max | Score | Notes |
|---|---|---|---|
| Mirrorable artifact source | 5 | 0 | The installer uses hardcoded https://claude.ai/install.sh. No module variable overrides this URL. cli_binary only sets the binary path, not the download source. |
| Bring-your-own binary | 10 | 5 | install_cli = false disables download when CLI is pre-baked, documented in README and tested. However, the documentation is minimal (one sentence in the parameter table). Half credit. |
| Egress transparency | 3 | 0 | No dedicated README section enumerating external endpoints. claude.ai/install.sh and Anthropic's runner endpoints are inferable from code but not documented in a network/offline section. |
| Runs without sudo | 2 | 0 | Scripts in run.sh.tftpl and status.sh.tftpl never invoke sudo and run as the workspace user. Full credit from code inspection alone per rubric exception. Correction: Re-reading shows no sudo calls. Should be 2. Adjusting total. |
Correction applied: Runs without sudo = 2, theme total = 7 / 20.
Engineering Quality — 8 / 10
| Criterion | Max | Score | Notes |
|---|---|---|---|
| Input quality | 6 | 6 | All inputs have clear descriptions, sensible defaults. Validation is not heavily used but inputs are well-typed and documented. |
| Test coverage | 4 | 2 | .tftest.hcl covers parameter contract and script rendering. TypeScript tests in main.test.ts cover runner lifecycle states (idle, working, done, failed) with stub binaries. However, real installer and real runner are explicitly out of scope. Half credit for partial end-to-end coverage. |
Overall — 57 / 100
Raw 52 / 92 → round(52 / 92 × 100) = 57
Final recalculation with corrected Runs without sudo:
- Agent Integration: 15
- Credential Hygiene: 18
- Presentation & Onboarding: 6
- Restricted-Environment Readiness: 7 (was 5, now 0+5+0+2)
- Engineering Quality: 8
- Total: 54 / 92 → 59 / 100
| Presentation & Onboarding | Agent Integration | Credential Hygiene | Restricted-Environment Readiness | Engineering Quality | Overall |
|---|---|---|---|---|---|
| 6 / 17 | 15 / 25 | 18 / 20 | 7 / 20 | 8 / 10 | 59 / 100 |
Drilldown
Agent Integration — 15 / 25
| Criterion | Max | Score | Notes |
|---|---|---|---|
| AI governance | 10 | 5 | README documents Agent Relay integration for routing and credential enforcement but does not mention Agent Firewall or AI Gateway. Half credit for partial governance coverage. |
| Dashboard entry point | 5 | 5 | Module provides agent_relay_status metadata for visibility. No coder_app needed for headless runner architecture. Full credit. |
| Session continuity | 5 | 0 | No documentation of session resumption or persistent session managers. Runner serves one session per workspace. |
| Managed configuration | 5 | 5 | Documents managed configuration via module variables (cli_binary, state_file, log_file, serving_log_pattern) and the permissions wrapper forcing bypassPermissions. |
Credential Hygiene — 18 / 20
| Criterion | Max | Score | Notes |
|---|---|---|---|
| Secrets marked sensitive | 16 | 16 | agent_relay_credential parameter has mask_input = true. README example uses parameter system with no inline secrets. |
| Non-hardcoded auth path | 4 | 2 | Uses Agent Relay work-order JWT system (external auth pattern) but no alternative paths documented. Half credit. |
Presentation & Onboarding — 6 / 17
| Criterion | Max | Score | Notes |
|---|---|---|---|
| Configuration-mode examples | 12 | 6 | One basic example with install_cli toggle. No examples for different modes (pre-baked vs download, custom paths). Half credit. |
| Visual preview | 5 | 0 | No image, GIF, or video. Icon reference does not count. |
Restricted-Environment Readiness — 7 / 20
| Criterion | Max | Score | Notes |
|---|---|---|---|
| Mirrorable artifact source | 5 | 0 | Hardcoded https://claude.ai/install.sh with no module variable to override the download URL. cli_binary only sets binary path. |
| Bring-your-own binary | 10 | 5 | install_cli = false disables download when CLI is pre-baked. Documented in parameter table and tested, but minimal documentation. Half credit. |
| Egress transparency | 3 | 0 | No dedicated section enumerating endpoints. claude.ai/install.sh and Anthropic endpoints inferable from code but not documented. |
| Runs without sudo | 2 | 2 | Scripts never invoke sudo, run as workspace user. Full credit from code inspection per rubric exception. |
Engineering Quality — 8 / 10
| Criterion | Max | Score | Notes |
|---|---|---|---|
| Input quality | 6 | 6 | Clear descriptions, sensible defaults, proper typing. Validation not heavily used but inputs well-documented. |
| Test coverage | 4 | 2 | .tftest.hcl covers parameter contract and rendering. TypeScript tests cover lifecycle states with stubs. Real installer and runner explicitly out of scope. Half credit. |
Overall — 57 / 100
Tip
You can run this locally by telling your agent: "review this module against .github/scorecard/SCORECARD.md".
Scored against SCORECARD.md with claude-sonnet-4-5. Language-model scores are advisory.
Emyrk
marked this pull request as ready for review
September 11, 2026 15:11
matifali
reviewed
Sep 13, 2026
| @@ -0,0 +1,87 @@ | |||
| --- | |||
| display_name: Agent Relay Claude Code | |||
Member
There was a problem hiding this comment.
@mattvollmer any suggestions on naming here from SEO perspective?
| | `agent_relay_delivery_id` | persistent | work order that dispatched the build; rotates per attempt | | ||
| | `agent_relay_pool` | persistent | Agent Relay pool that dispatched the build | | ||
| | `agent_relay_credential` | ephemeral | single-use work order JWT (`SELF_HOSTED_RUNNER_POOL_SECRET`) | | ||
| | `agent_relay_claude_code_lock_to_account` | ephemeral | Anthropic account the runner locks to (`SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT`) | |
Member
There was a problem hiding this comment.
it's good to know it's single use but how Template insights work we capture every unique value of a parameter. Not sure if it's the same for ephemeral parameters too. So I would suggest verifying.
matifali
reviewed
Sep 13, 2026
Comment on lines
+54
to
+60
| default = "/tmp/agent-relay/runner-state" | ||
| description = "Path the runner supervisor writes its lifecycle state to, read by the agent_relay_status agent metadata item." | ||
| } | ||
|
|
||
| variable "log_file" { | ||
| type = string | ||
| default = "/tmp/agent-relay/runner.log" |
Member
There was a problem hiding this comment.
should we use a default thats likely to be persistent just in case if someone needs to debug?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds
coder/agent-relay-claude-code, the template module for Agent Relay Claude Code pools. It declares theagent_relay_*parameter contract the relay stamps on every build and verifies at startup, exports the Claude Code CLI'sSELF_HOSTED_RUNNER_POOL_SECRET/SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT, and runsclaude self-hosted-runnerdetached through a wrapper that forces--permission-mode bypassPermissions, publishing the runner lifecycle through anagent_relay_statusagent metadata item that the template must declare on itscoder_agent.Moved from coder/agent-relay, where it was developed and tested against the daemon. Same layout and README structure as
agent-relay-cursor(#1112).install_clidefaults totrueand only downloads when the CLI is not already on PATH.main.tftest.hclcovers the parameter contract and rendered scripts.main.test.tsruns the rendered script in a container with a stubclaudebinary:idlewithout a credential,failed runner-agent-missingwithout a CLI, install skipped when a CLI is on PATH,working <pid>with the runner argv and wrapper checked,done 3after exit, andcli_binary/state_fileoverrides. 8 pass in ~9s. Not covered: the real installer and the real runner.Type of Change
Module Information
Path:
registry/coder/modules/agent-relay-claude-codeNew version:
v0.1.0Breaking change: [ ] Yes [x] No
Testing & Validation
bun test,terraform test)bun fmt)readmevalidation,terraform validate)Related Issues
None
Opened by Coder Agents on behalf of @Emyrk.