feat(agent): populate subagent ID for terraform-defined devcontainers by DanielleMaywood · Pull Request #21942 · coder/coder

DanielleMaywood · 2026-02-05T10:25:07Z

Completes the final piece of the puzzle. Support the pre-creation flow from the agent side.

Update the manifest API in coderd to populate the subagent_id field for devcontainers, enabling the agent to receive devcontainer resource definitions with pre-assigned IDs and use them when creating sub-agents. This allows Terraform-defined devcontainers to: - Have stable subagent IDs across workspace rebuilds - Prevent accidental deletion/recreation of managed subagents - Prevent UI-initiated rebuilds of terraform-managed containers

coder-tasks · 2026-02-05T13:55:12Z

Documentation Check

Updates Needed

docs/admin/integrations/devcontainers/integration.md - Document the new Terraform-defined devcontainer feature with pre-assigned subagent IDs

Details

This PR introduces an important new capability for the coder_devcontainer resource: Terraform-defined devcontainers with pre-assigned subagent IDs. This feature needs to be documented in the existing Dev Containers integration guide.

What should be documented:

New Capability: Explain that coder_devcontainer resources now create devcontainers with stable, pre-assigned subagent IDs that persist across workspace rebuilds
Behavioral Differences: Document the distinction between:
- Dynamically-created devcontainers (discovered via project discovery): Can be rebuilt from the UI, IDs may change
- Terraform-defined devcontainers (via coder_devcontainer resource): Cannot be rebuilt from UI, stable IDs, managed by template updates
UI Limitations: Explain that Terraform-defined devcontainers show a disabled rebuild button with a tooltip explaining they must be updated via template changes
Benefits:
- Stable subagent IDs across workspace rebuilds
- Prevents accidental deletion/recreation of managed subagents
- Prevents UI-initiated rebuilds that could conflict with Terraform state

Suggested location: Add a new section in docs/admin/integrations/devcontainers/integration.md after the "Configure Automatic Dev Container Startup" section, perhaps titled "Terraform-Managed Dev Containers" or "Stable Subagent IDs"

Example content structure:

## Terraform-Managed Dev Containers

Dev Containers defined using the `coder_devcontainer` resource are managed by Terraform 
and have stable subagent IDs that persist across workspace rebuilds...

### Benefits
- Stable subagent IDs prevent disruption during workspace updates
- Resources attached to subagents remain consistent
- Template changes are the single source of truth

### UI Behavior
Terraform-managed dev containers cannot be rebuilt from the Coder UI. Users will see a 
disabled rebuild button with a tooltip...

Automated review via Coder Tasks

johnstcn

Partial review, will post more comments later.

agent/agentcontainers/api.go

codersdk/workspaceagents_test.go

johnstcn

Nice work! I don't need to review again.

agent/agentcontainers/subagent_test.go

johnstcn · 2026-02-05T21:14:00Z

agent/agentcontainers/subagent_test.go

+	})
+}
+
+func TestSubAgent_EqualConfig(t *testing.T) {


It feels unfortunate to need to define two separate equality methods for two very similar structs.

mafredri · 2026-02-06T09:51:17Z

agent/agentcontainers/api.go

+		api.mu.Unlock()
+		httpapi.Write(ctx, w, http.StatusConflict, codersdk.Response{
+			Message: "Cannot rebuild Terraform-defined devcontainer",
+			Detail:  fmt.Sprintf("Devcontainer %q has resources defined in Terraform and cannot be rebuilt from the UI. Update the workspace template to modify this devcontainer.", dc.Name),


Why do we want to block recreation of a devcontainer (docker container) here? Perhaps it's justified but it could use an explanation.

Ultimately the agent will just be restarted, unmodified. (Or perhaps display apps updated.)

Oh that's a good point, silly me 🤦‍♀️

I'll get a test added to ensure rebuilding works as we expect then (restart unmodified other than picking up the new container).

Addressed in 25120cc

agent/agentcontainers/api.go

- Allow re-building terraform managed dev containers - Add a test to confirm we upsert, not delete & create - Update the frontend to reflect this change - Update the frontend to indicate a dev container is terraform managed

coder-tasks · 2026-02-06T10:47:23Z

Documentation Check

Previous Feedback

Partially addressed - The implementation has been refined (terraform-managed devcontainers can now be rebuilt via upsert), but documentation is still needed.

Updates Needed

docs/admin/integrations/devcontainers/integration.md - Document the Terraform-defined devcontainer feature with stable subagent IDs

Details

The latest commits refined the implementation:

Terraform-managed devcontainers now support rebuilding (via upsert, not delete/recreate)
The UI now shows "(terraform)" indicator for managed devcontainers
Stable subagent IDs persist across rebuilds

Documentation should cover:

Stable Subagent IDs: When using coder_devcontainer resource, subagents get pre-assigned IDs that persist across workspace rebuilds
Behavioral Differences:
- Project Discovery: Dynamically discovered devcontainers, can be rebuilt from UI, IDs may change
- Terraform-Defined (coder_devcontainer resource): Stable IDs, can be rebuilt (config updates via upsert), UI shows "(terraform)" label
Benefits:
- Stable subagent IDs enable attaching Terraform resources to specific devcontainers
- Prevents accidental ID changes during workspace updates
- Config changes (apps, display settings) update without deleting the agent

Suggested location: Add a new section in docs/admin/integrations/devcontainers/integration.md after "Configure Automatic Dev Container Startup" (line 73), perhaps titled "Terraform-Managed Dev Containers" or "Stable Subagent IDs"

Automated review via Coder Tasks

mafredri

A few more minor things, and checking whether or not display apps should be updated on re-create. I think they should, since we support updating, but reading the code/tests it doesn't seem like we do?

agent/agentcontainers/api.go

site/src/modules/resources/AgentDevcontainerCard.tsx

agent/agentcontainers/api_test.go

coder-tasks · 2026-02-06T15:34:55Z

Documentation Check

Updates Needed

docs/admin/integrations/devcontainers/integration.md - Document Terraform-managed devcontainers with stable subagent IDs

Details

This PR introduces an important new capability for the coder_devcontainer resource: stable, pre-assigned subagent IDs for Terraform-defined devcontainers. This feature needs to be documented in the existing Dev Containers integration guide.

What should be documented:

Stable Subagent IDs: When using coder_devcontainer resource, subagents get pre-assigned IDs that persist across workspace rebuilds. This enables attaching Terraform resources (like coder_app, coder_script) to specific devcontainer subagents.
Behavioral Differences: Document the distinction between:
- Project Discovery: Dynamically discovered devcontainers, can be rebuilt from UI, IDs may change between rebuilds
- Terraform-Managed (via coder_devcontainer resource): Stable IDs that never change, can be rebuilt (config updates via upsert), UI shows "(terraform agent)" label
Benefits:
- Stable subagent IDs enable attaching Terraform resources to specific devcontainers
- Prevents accidental ID changes during workspace updates
- Config changes (apps, display settings) update without deleting the agent
- Terraform remains the single source of truth for managed devcontainers
UI Indicators: The UI now shows "dev container (terraform agent)" for Terraform-managed devcontainers with a tooltip explaining limited configurability.

Suggested location: Add a new section in docs/admin/integrations/devcontainers/integration.md after the "Configure Automatic Dev Container Startup" section (around line 73), perhaps titled:

Terraform-Managed Dev Containers with Stable IDs

Example content structure:

## Terraform-Managed Dev Containers with Stable IDs

Dev Containers defined using the `coder_devcontainer` resource have stable subagent IDs 
that persist across workspace rebuilds. This differs from dynamically discovered Dev Containers, 
which may receive new IDs when rebuilt.

### Benefits

- **Attach Terraform resources**: Stable IDs allow you to attach `coder_app`, `coder_script`, 
  and other Terraform resources directly to devcontainer subagents
- **Predictable behavior**: Subagent IDs never change during workspace rebuilds or template updates
- **Config updates without disruption**: Changes to apps and display settings update the existing 
  agent without deletion

### Usage

The subagent ID is automatically assigned and managed by Terraform when you create a 
`coder_devcontainer` resource. You can reference it in other resources...

Note: This addresses the limitation mentioned in lines 150-162 of the current documentation, where it states that Terraform resources cannot be attached to dev container sub-agents because they're "created dynamically after workspace provisioning." With this PR, Terraform-managed devcontainers now have stable IDs that CAN have resources attached.

Automated review via Coder Tasks

site/src/modules/resources/AgentDevcontainerCard.tsx

matifali · 2026-02-18T11:03:23Z

@DanielleMaywood, any plan to put this in dogfood? It would help to capture any unforeseen issues before the release.

github-actions bot assigned DanielleMaywood Feb 5, 2026

DanielleMaywood force-pushed the danielle/devcontainer-resources/agent branch 4 times, most recently from db0350c to c128b81 Compare February 5, 2026 13:22

DanielleMaywood force-pushed the danielle/devcontainer-resources/agent branch from c128b81 to bca517e Compare February 5, 2026 13:35

DanielleMaywood marked this pull request as ready for review February 5, 2026 13:53

DanielleMaywood requested review from johnstcn and mafredri and removed request for mafredri February 5, 2026 13:53

johnstcn reviewed Feb 5, 2026

View reviewed changes

agent/agentcontainers/api.go Outdated Show resolved Hide resolved

agent/agentcontainers/api.go Outdated Show resolved Hide resolved

johnstcn reviewed Feb 5, 2026

View reviewed changes

agent/agentcontainers/api.go Show resolved Hide resolved

codersdk/workspaceagents_test.go Outdated Show resolved Hide resolved

codersdk/workspaceagents_test.go Outdated Show resolved Hide resolved

johnstcn approved these changes Feb 5, 2026

View reviewed changes

DanielleMaywood added 8 commits February 5, 2026 21:40

refactor: copy then modify through pointer

14b5f97

refactor: test table overkill

22677d9

refactor: assert.Equal(zero) -> assert.Zero

b07e265

refactor: match friend test in pattern

aea30c9

chore: Forbidden -> Conflict

eb1cbe5

chore: map to slice

4c0f954

chore: simplify deleteSubAgent check and add log

3f61531

chore: oops, forgot t.Parallel

6652229

mafredri reviewed Feb 6, 2026

View reviewed changes

DanielleMaywood added 2 commits February 6, 2026 10:42

chore: we can use WaitGroup.Go now

9f54496

chore: allow re-building terraform managed dev containers

25120cc

- Allow re-building terraform managed dev containers - Add a test to confirm we upsert, not delete & create - Update the frontend to reflect this change - Update the frontend to indicate a dev container is terraform managed

DanielleMaywood requested a review from mafredri February 6, 2026 14:04

mafredri reviewed Feb 6, 2026

View reviewed changes

agent/agentcontainers/api.go Outdated Show resolved Hide resolved

agent/agentcontainers/api.go Outdated Show resolved Hide resolved

site/src/modules/resources/AgentDevcontainerCard.tsx Outdated Show resolved Hide resolved

agent/agentcontainers/api_test.go Show resolved Hide resolved

DanielleMaywood added 5 commits February 6, 2026 15:19

chore: improve frontend description

64cc832

chore: improve readability

d98c5db

chore: improve log message

361f199

chore: fix storybook story

bada8c7

chore: run formatter

6d8df73

mafredri approved these changes Feb 6, 2026

View reviewed changes

site/src/modules/resources/AgentDevcontainerCard.tsx Outdated Show resolved Hide resolved

chore: add agent

bfa277c

DanielleMaywood merged commit 6ccd20d into main Feb 6, 2026
29 of 32 checks passed

DanielleMaywood deleted the danielle/devcontainer-resources/agent branch February 6, 2026 15:52

github-actions bot locked and limited conversation to collaborators Feb 6, 2026

matifali linked an issue Feb 18, 2026 that may be closed by this pull request

Tasks should run within devcontainers #21134

Closed

2 tasks

Conversation

DanielleMaywood commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coder-tasks bot commented Feb 5, 2026

Documentation Check

Updates Needed

Details

Uh oh!

johnstcn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

johnstcn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

johnstcn Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

mafredri Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

DanielleMaywood Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

DanielleMaywood Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coder-tasks bot commented Feb 6, 2026

Documentation Check

Previous Feedback

Updates Needed

Details

Uh oh!

mafredri left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coder-tasks bot commented Feb 6, 2026

Documentation Check

Updates Needed

Details

Terraform-Managed Dev Containers with Stable IDs

Uh oh!

Uh oh!

Uh oh!

matifali commented Feb 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

DanielleMaywood commented Feb 5, 2026 •

edited

Loading