coder · mafredri · May 27, 2025 · May 27, 2025 · May 27, 2025 · May 27, 2025
diff --git a/agent/agent_test.go b/agent/agent_test.go
@@ -2226,7 +2226,7 @@ func TestAgent_DevcontainerRecreate(t *testing.T) {
 	// devcontainer, we do it in a goroutine so we can process logs
 	// concurrently.
 	go func(container codersdk.WorkspaceAgentContainer) {
-		err := conn.RecreateDevcontainer(ctx, container.ID)
+		_, err := conn.RecreateDevcontainer(ctx, container.ID)
 		assert.NoError(t, err, "recreate devcontainer should succeed")
 	}(container)
 

diff --git a/agent/agentcontainers/api.go b/agent/agentcontainers/api.go
@@ -403,6 +403,7 @@ func (api *API) processUpdatedContainersLocked(ctx context.Context, updated code
 	// Check if the container is running and update the known devcontainers.
 	for i := range updated.Containers {
 		container := &updated.Containers[i] // Grab a reference to the container to allow mutating it.
+		container.DevcontainerStatus = ""   // Reset the status for the container (updated later).
 		container.DevcontainerDirty = false // Reset dirty state for the container (updated later).
 
 		workspaceFolder := container.Labels[DevcontainerLocalFolderLabel]
@@ -465,16 +466,25 @@ func (api *API) processUpdatedContainersLocked(ctx context.Context, updated code
 	for _, dc := range api.knownDevcontainers {
 		switch {
 		case dc.Status == codersdk.WorkspaceAgentDevcontainerStatusStarting:
+			if dc.Container != nil {
+				dc.Container.DevcontainerStatus = dc.Status
+				dc.Container.DevcontainerDirty = dc.Dirty
+			}
 			continue // This state is handled by the recreation routine.
 
 		case dc.Status == codersdk.WorkspaceAgentDevcontainerStatusError && (dc.Container == nil || dc.Container.CreatedAt.Before(api.recreateErrorTimes[dc.WorkspaceFolder])):
+			if dc.Container != nil {
+				dc.Container.DevcontainerStatus = dc.Status
+				dc.Container.DevcontainerDirty = dc.Dirty
+			}
 			continue // The devcontainer needs to be recreated.
 
 		case dc.Container != nil:
 			dc.Status = codersdk.WorkspaceAgentDevcontainerStatusStopped
 			if dc.Container.Running {
 				dc.Status = codersdk.WorkspaceAgentDevcontainerStatusRunning
 			}
+			dc.Container.DevcontainerStatus = dc.Status
 
 			dc.Dirty = false
 			if lastModified, hasModTime := api.configFileModifiedTimes[dc.ConfigPath]; hasModTime && dc.Container.CreatedAt.Before(lastModified) {
@@ -608,6 +618,9 @@ func (api *API) handleDevcontainerRecreate(w http.ResponseWriter, r *http.Reques
 	// Update the status so that we don't try to recreate the
 	// devcontainer multiple times in parallel.
 	dc.Status = codersdk.WorkspaceAgentDevcontainerStatusStarting
+	if dc.Container != nil {
+		dc.Container.DevcontainerStatus = dc.Status
+	}
 	api.knownDevcontainers[dc.WorkspaceFolder] = dc
 	api.recreateWg.Add(1)
 	go api.recreateDevcontainer(dc, configPath)
@@ -680,6 +693,9 @@ func (api *API) recreateDevcontainer(dc codersdk.WorkspaceAgentDevcontainer, con
 		api.mu.Lock()
 		dc = api.knownDevcontainers[dc.WorkspaceFolder]
 		dc.Status = codersdk.WorkspaceAgentDevcontainerStatusError
+		if dc.Container != nil {
+			dc.Container.DevcontainerStatus = dc.Status
+		}
 		api.knownDevcontainers[dc.WorkspaceFolder] = dc
 		api.recreateErrorTimes[dc.WorkspaceFolder] = api.clock.Now("recreate", "errorTimes")
 		api.mu.Unlock()
@@ -695,10 +711,12 @@ func (api *API) recreateDevcontainer(dc codersdk.WorkspaceAgentDevcontainer, con
 	// allows the update routine to update the devcontainer status, but
 	// to minimize the time between API consistency, we guess the status
 	// based on the container state.
-	if dc.Container != nil && dc.Container.Running {
-		dc.Status = codersdk.WorkspaceAgentDevcontainerStatusRunning
-	} else {
-		dc.Status = codersdk.WorkspaceAgentDevcontainerStatusStopped
+	dc.Status = codersdk.WorkspaceAgentDevcontainerStatusStopped
+	if dc.Container != nil {
+		if dc.Container.Running {
+			dc.Status = codersdk.WorkspaceAgentDevcontainerStatusRunning
+		}
+		dc.Container.DevcontainerStatus = dc.Status
 	}
 	dc.Dirty = false
 	api.recreateSuccessTimes[dc.WorkspaceFolder] = api.clock.Now("recreate", "successTimes")

diff --git a/agent/agentcontainers/api_test.go b/agent/agentcontainers/api_test.go
@@ -477,6 +477,8 @@ func TestAPI(t *testing.T) {
 				require.NoError(t, err, "unmarshal response failed")
 				require.Len(t, resp.Devcontainers, 1, "expected one devcontainer in response")
 				assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusStarting, resp.Devcontainers[0].Status, "devcontainer is not starting")
+				require.NotNil(t, resp.Devcontainers[0].Container, "devcontainer should have container reference")
+				assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusStarting, resp.Devcontainers[0].Container.DevcontainerStatus, "container dc status is not starting")
 
 				// Allow the devcontainer CLI to continue the up process.
 				close(tt.devcontainerCLI.continueUp)
@@ -503,6 +505,8 @@ func TestAPI(t *testing.T) {
 					require.NoError(t, err, "unmarshal response failed after error")
 					require.Len(t, resp.Devcontainers, 1, "expected one devcontainer in response after error")
 					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusError, resp.Devcontainers[0].Status, "devcontainer is not in an error state after up failure")
+					require.NotNil(t, resp.Devcontainers[0].Container, "devcontainer should have container reference after up failure")
+					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusError, resp.Devcontainers[0].Container.DevcontainerStatus, "container dc status is not error after up failure")
 					return
 				}
 
@@ -525,7 +529,9 @@ func TestAPI(t *testing.T) {
 				err = json.NewDecoder(rec.Body).Decode(&resp)
 				require.NoError(t, err, "unmarshal response failed after recreation")
 				require.Len(t, resp.Devcontainers, 1, "expected one devcontainer in response after recreation")
-				assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, resp.Devcontainers[0].Status, "devcontainer is not stopped after recreation")
+				assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, resp.Devcontainers[0].Status, "devcontainer is not running after recreation")
+				require.NotNil(t, resp.Devcontainers[0].Container, "devcontainer should have container reference after recreation")
+				assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, resp.Devcontainers[0].Container.DevcontainerStatus, "container dc status is not running after recreation")
 			})
 		}
 	})
@@ -620,6 +626,7 @@ func TestAPI(t *testing.T) {
 					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, dc.Status)
 					require.NotNil(t, dc.Container)
 					assert.Equal(t, "runtime-container-1", dc.Container.ID)
+					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, dc.Container.DevcontainerStatus)
 				},
 			},
 			{
@@ -660,12 +667,14 @@ func TestAPI(t *testing.T) {
 					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusStopped, known2.Status)
 					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, runtime1.Status)
 
-					require.NotNil(t, known1.Container)
 					assert.Nil(t, known2.Container)
-					require.NotNil(t, runtime1.Container)
 
+					require.NotNil(t, known1.Container)
 					assert.Equal(t, "known-container-1", known1.Container.ID)
+					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, known1.Container.DevcontainerStatus)
+					require.NotNil(t, runtime1.Container)
 					assert.Equal(t, "runtime-container-1", runtime1.Container.ID)
+					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, runtime1.Container.DevcontainerStatus)
 				},
 			},
 			{
@@ -704,10 +713,12 @@ func TestAPI(t *testing.T) {
 					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusStopped, nonRunning.Status)
 
 					require.NotNil(t, running.Container, "running container should have container reference")
-					require.NotNil(t, nonRunning.Container, "non-running container should have container reference")
-
 					assert.Equal(t, "running-container", running.Container.ID)
+					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, running.Container.DevcontainerStatus)
+
+					require.NotNil(t, nonRunning.Container, "non-running container should have container reference")
 					assert.Equal(t, "non-running-container", nonRunning.Container.ID)
+					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusStopped, nonRunning.Container.DevcontainerStatus)
 				},
 			},
 			{
@@ -743,6 +754,7 @@ func TestAPI(t *testing.T) {
 					assert.NotEmpty(t, dc2.ConfigPath)
 					require.NotNil(t, dc2.Container)
 					assert.Equal(t, "known-container-2", dc2.Container.ID)
+					assert.Equal(t, codersdk.WorkspaceAgentDevcontainerStatusRunning, dc2.Container.DevcontainerStatus)
 				},
 			},
 			{
@@ -811,9 +823,14 @@ func TestAPI(t *testing.T) {
 
 				logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true}).Leveled(slog.LevelDebug)
 
+				mClock := quartz.NewMock(t)
+				mClock.Set(time.Now()).MustWait(testutil.Context(t, testutil.WaitShort))
+				tickerTrap := mClock.Trap().TickerFunc("updaterLoop")
+
 				// Setup router with the handler under test.
 				r := chi.NewRouter()
 				apiOptions := []agentcontainers.Option{
+					agentcontainers.WithClock(mClock),
 					agentcontainers.WithLister(tt.lister),
 					agentcontainers.WithWatcher(watcher.NewNoop()),
 				}
@@ -838,6 +855,15 @@ func TestAPI(t *testing.T) {
 
 				ctx := testutil.Context(t, testutil.WaitShort)
 
+				// Make sure the ticker function has been registered
+				// before advancing the clock.
+				tickerTrap.MustWait(ctx).MustRelease(ctx)
+				tickerTrap.Close()
+
+				// Advance the clock to run the updater loop.
+				_, aw := mClock.AdvanceNext()
+				aw.MustWait(ctx)
+
 				req := httptest.NewRequest(http.MethodGet, "/devcontainers", nil).
 					WithContext(ctx)
 				rec := httptest.NewRecorder()

diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/coderd/workspaceagents.go b/coderd/workspaceagents.go
@@ -956,7 +956,7 @@ func (api *API) workspaceAgentRecreateDevcontainer(rw http.ResponseWriter, r *ht
 	}
 	defer release()
 
-	err = agentConn.RecreateDevcontainer(ctx, container)
+	m, err := agentConn.RecreateDevcontainer(ctx, container)
 	if err != nil {
 		if errors.Is(err, context.Canceled) {
 			httpapi.Write(ctx, rw, http.StatusRequestTimeout, codersdk.Response{
@@ -977,7 +977,7 @@ func (api *API) workspaceAgentRecreateDevcontainer(rw http.ResponseWriter, r *ht
 		return
 	}
 
-	httpapi.Write(ctx, rw, http.StatusNoContent, nil)
+	httpapi.Write(ctx, rw, http.StatusAccepted, m)
 }
 
 // @Summary Get connection info for workspace agent

diff --git a/coderd/workspaceagents_test.go b/coderd/workspaceagents_test.go
@@ -1483,7 +1483,7 @@ func TestWorkspaceAgentRecreateDevcontainer(t *testing.T) {
 
 				ctx := testutil.Context(t, testutil.WaitLong)
 
-				err := client.WorkspaceAgentRecreateDevcontainer(ctx, agentID, devContainer.ID)
+				_, err := client.WorkspaceAgentRecreateDevcontainer(ctx, agentID, devContainer.ID)
 				if wantStatus > 0 {
 					cerr, ok := codersdk.AsError(err)
 					require.True(t, ok, "expected error to be a coder error")

diff --git a/codersdk/workspaceagents.go b/codersdk/workspaceagents.go
@@ -450,6 +450,10 @@ type WorkspaceAgentContainer struct {
 	// Volumes is a map of "things" mounted into the container. Again, this
 	// is somewhat implementation-dependent.
 	Volumes map[string]string `json:"volumes"`
+	// DevcontainerStatus is the status of the devcontainer, if this
+	// container is a devcontainer. This is used to determine if the
+	// devcontainer is running, stopped, starting, or in an error state.
+	DevcontainerStatus WorkspaceAgentDevcontainerStatus `json:"devcontainer_status,omitempty"`
 	// DevcontainerDirty is true if the devcontainer configuration has changed
 	// since the container was created. This is used to determine if the
 	// container needs to be rebuilt.
@@ -518,16 +522,20 @@ func (c *Client) WorkspaceAgentListContainers(ctx context.Context, agentID uuid.
 }
 
 // WorkspaceAgentRecreateDevcontainer recreates the devcontainer with the given ID.
-func (c *Client) WorkspaceAgentRecreateDevcontainer(ctx context.Context, agentID uuid.UUID, containerIDOrName string) error {
+func (c *Client) WorkspaceAgentRecreateDevcontainer(ctx context.Context, agentID uuid.UUID, containerIDOrName string) (Response, error) {
 	res, err := c.Request(ctx, http.MethodPost, fmt.Sprintf("/api/v2/workspaceagents/%s/containers/devcontainers/container/%s/recreate", agentID, containerIDOrName), nil)
 	if err != nil {
-		return err
+		return Response{}, err
 	}
 	defer res.Body.Close()
-	if res.StatusCode != http.StatusNoContent {
-		return ReadBodyAsError(res)
+	if res.StatusCode != http.StatusAccepted {
+		return Response{}, ReadBodyAsError(res)
 	}
-	return nil
+	var m Response
+	if err := json.NewDecoder(res.Body).Decode(&m); err != nil {
+		return Response{}, xerrors.Errorf("decode response body: %w", err)
+	}
+	return m, nil
 }
 
 //nolint:revive // Follow is a control flag on the server as well.

diff --git a/codersdk/workspacesdk/agentconn.go b/codersdk/workspacesdk/agentconn.go
@@ -389,18 +389,22 @@ func (c *AgentConn) ListContainers(ctx context.Context) (codersdk.WorkspaceAgent
 
 // RecreateDevcontainer recreates a devcontainer with the given container.
 // This is a blocking call and will wait for the container to be recreated.
-func (c *AgentConn) RecreateDevcontainer(ctx context.Context, containerIDOrName string) error {
+func (c *AgentConn) RecreateDevcontainer(ctx context.Context, containerIDOrName string) (codersdk.Response, error) {
 	ctx, span := tracing.StartSpan(ctx)
 	defer span.End()
 	res, err := c.apiRequest(ctx, http.MethodPost, "/api/v0/containers/devcontainers/container/"+containerIDOrName+"/recreate", nil)
 	if err != nil {
-		return xerrors.Errorf("do request: %w", err)
+		return codersdk.Response{}, xerrors.Errorf("do request: %w", err)
 	}
 	defer res.Body.Close()
 	if res.StatusCode != http.StatusAccepted {
-		return codersdk.ReadBodyAsError(res)
+		return codersdk.Response{}, codersdk.ReadBodyAsError(res)
 	}
-	return nil
+	var m codersdk.Response
+	if err := json.NewDecoder(res.Body).Decode(&m); err != nil {
+		return codersdk.Response{}, xerrors.Errorf("decode response body: %w", err)
+	}
+	return m, nil
 }
 
 // apiRequest makes a request to the workspace agent's HTTP API server.

diff --git a/docs/reference/api/agents.md b/docs/reference/api/agents.md