feat: coder-attach: add support for external workspaces #19178

kacpersaw · 2025-08-05T11:07:30Z

Depends on: coder/terraform-provider-coder#424

This pull request introduces support for external workspace management, allowing users to register and manage workspaces that are provisioned and managed outside of the Coder.

CLI changes

coder external-workspaces create - Creates a new external workspace (this command extends coder create)
- Example: coder external-workspaces create ext-workspace --template=externally-managed-workspace -y
- Checks if template has coder_external_agent resource before creating a workspace
coder external-workspaces list - Lists all external workspaces
coder external-workspaces agent-instructions <workspace name> <agent name> - Retrieves agent connection instruction
- Example: coder external-workspaces agent-instructions ext-workspace main --output=json

coderd changes

GET /api/v2/init-script - Gets the agent initialization script
- By default, it returns a script for Linux (amd64), but with query parameters (os and arch) you can get the init script for different platforms
GET /api/v2/workspaces/{workspace}/external-agent/{agent}/credentials - Gets credentials for an external agent

Database changes

Added has_external_agent field to workspace builds and template versions
Updated queries to filter workspaces/templates by the has_external_agent field

provisioner changes

Added support for coder_external_agent terraform resource
Updated provisioner to detect and track external agents in workspace builds

Frontend changes

Added a new component AgentExternal which shows instructions for connecting external agents.
Added redacted fields to CodeExample so you can now hide specific parts of the code instead of the full line
Hides workspace actions if workspace is using external agent.

…nt credential

…ils, extend CodeExample to redact parts of the code

…attach # Conflicts: # cli/create.go # coderd/database/queries.sql.go # docs/admin/security/audit-logs.md # provisionersdk/proto/provisioner.pb.go

…attach # Conflicts: # codersdk/workspaces.go

johnstcn

I would highly recommend breaking this PR down by domain. Right now it's extremely large.

Suggested breakpoints:

Database
API/protobuf
CLI
UI

johnstcn · 2025-08-05T14:42:22Z

provisionersdk/proto/provisioner.proto

When adding a new field to a protobuf, we increment the minor version in provisionerd/proto/version.go.

aslilac · 2025-08-06T01:36:05Z

site/src/components/CodeExample/CodeExample.tsx

+	actions: {
+		display: "flex",
+		alignItems: "center",
+		gap: 4,
+	},


pls use tailwind for new styles

aslilac · 2025-08-06T01:39:48Z

site/src/components/CodeExample/CodeExample.tsx

@@ -19,7 +30,31 @@ export const CodeExample: FC<CodeExampleProps> = ({
 	// Defaulting to true to be on the safe side; you should have to opt out of
 	// the secure option, not remember to opt in
 	secret = true,
+
+	// Redact parts of the code if the user doesn't want to obfuscate the whole code


I know there was already a bad pattern here, but these comments will be much more helpful on the type definition in JSDoc format so that the language server will actually recognize them

aslilac · 2025-08-06T01:39:56Z

site/src/components/CodeExample/CodeExample.tsx

+	redactPattern,
+	redactReplacement = "********",
+
+	// Show a button to show the redacted parts of the code


aslilac · 2025-08-06T01:45:23Z

site/src/components/CodeExample/CodeExample.tsx

+	redactReplacement = "********",
+
+	// Show a button to show the redacted parts of the code
+	redactShowButton = false,


this is a really confusing name. it kind of sounds like by setting it to true you're "redacting the show button" which doesn't really make sense. just showButton would also be confusing. what button are we showing and why?

I think these are usually called "reveal" buttons. maybe showRevealButton or enableRevealButton?

Suggested change

redactShowButton = false,

redactShowButton,

also you don't need the default. undefined is treated like false when used as a boolean.

aslilac · 2025-08-06T01:47:18Z

site/src/modules/resources/AgentExternal.tsx

+const styles = {
+	externalAgentSection: (theme) => ({
+		fontSize: 16,
+		color: theme.palette.text.secondary,
+		paddingBottom: 8,
+		lineHeight: 1.4,
+	}),
+} satisfies Record<string, Interpolation<Theme>>;


pls use tailwind for new styles

…attach # Conflicts: # coderd/database/queries/templateversions.sql

deansheather

BE review 👍

deansheather · 2025-08-06T07:02:16Z

cli/external_workspaces.go

+		cliui.ChangeFormatterData(cliui.TextFormat(), func(data any) (any, error) {
+			agent, ok := data.(externalAgent)
+			if !ok {
+				return "", xerrors.Errorf("expected externalAgent, got %T", data)
+			}
+
+			var output strings.Builder
+			_, _ = output.WriteString(fmt.Sprintf("Please run the following commands to attach agent %s:\n", cliui.Keyword(agent.AgentName)))
+			_, _ = output.WriteString(fmt.Sprintf("%s\n", pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("export CODER_AGENT_TOKEN=%s", agent.AuthToken))))
+			_, _ = output.WriteString(pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("curl -fsSL %s | sh", agent.InitScript)))
+
+			return output.String(), nil
+		}),


This chunk of code seems to be used multiple times, can you not reuse printExternalAgents()?

deansheather · 2025-08-06T07:06:02Z

cli/external_workspaces.go

+		template, err := client.TemplateByName(inv.Context(), organization.ID, templateName.Value.String())
+		if err != nil {
+			return xerrors.Errorf("get template by name: %w", err)
+		}


A lot of these queries are going to be repeated by the original handler, could we change the createHandler function into a model where the queries get run once, then a "validate" function that gets swapped for coder create or coder external-workspaces create gets executed (and all the queried objects get passed in), then the workspace gets created.

workspace, workspaceBuild, err := createHandler(ctx, inv, createOptions{ beforeCreate: func(ctx context.Context, template codersdk.Template, ...) error {}, })

deansheather · 2025-08-06T07:07:32Z

cli/root.go

@@ -127,6 +127,9 @@ func (r *RootCmd) CoreSubcommands() []*serpent.Command {
 		r.update(),
 		r.whoami(),

+		// External Workspace Commands


I'd just group this with workspaces tbh

deansheather · 2025-08-06T07:08:21Z

cli/external_workspaces.go

+
+	cmd := &serpent.Command{
+		Use:   "external-workspaces [subcommand]",
+		Short: "External workspace related commands",


Suggested change

Short: "External workspace related commands",

Short: "Create or manage external workspaces",

deansheather · 2025-08-06T07:09:42Z

cli/external_workspaces.go

+	)
+
+	cmd := &serpent.Command{
+		Use:        "agent-instructions [workspace name] [agent name]",


Other commands use [user/]workspace[.agent] syntax for selecting an agent, defaulting to the only agent in the workspace if the agent is unspecified and there's only one. I believe there's a helper function in cli to resolve these for you.

deansheather · 2025-08-06T07:19:18Z

coderd/init_script.go

+		return
+	}
+	script = strings.ReplaceAll(script, "${ACCESS_URL}", api.AccessURL.String()+"/")
+	script = strings.ReplaceAll(script, "${AUTH_TYPE}", "token")


Shouldn't auth type be configurable e.g. with an query parameter var? Defaulting the value to "token" is fine, though.

Phase 1 assumes token-based auth, so I think it can stay as it is. In the future, we can extend this to include other types of auth.

How would that look like on the init script endpoint? A query parameter defaulting to token perhaps?

Yep, that's the plan 👍

deansheather · 2025-08-06T07:21:11Z

coderd/provisionerdserver/provisionerdserver.go

@@ -1731,7 +1731,17 @@ func (s *server) completeTemplateImportJob(ctx context.Context, job database.Pro
 		if err != nil {
 			return xerrors.Errorf("update template version external auth providers: %w", err)
 		}
-
+		err = db.UpdateTemplateVersionExternalAgentByJobID(ctx, database.UpdateTemplateVersionExternalAgentByJobIDParams{


Could probably be merged with the above query.

deansheather · 2025-08-06T07:21:20Z

coderd/provisionerdserver/provisionerdserver.go

+				break
+			}
+		}
+		err = db.UpdateWorkspaceBuildExternalAgentByID(ctx, database.UpdateWorkspaceBuildExternalAgentByIDParams{


deansheather · 2025-08-06T07:28:31Z

coderd/workspaceagents.go

+
+	for _, agent := range agents {
+		if agent.Name == agentName {
+			httpapi.Write(ctx, rw, http.StatusOK, codersdk.ExternalAgentCredentials{


If the external agent uses a different authentication strategy than "token" we should probably return a 404 or something else that the frontend can detect.

deansheather · 2025-08-06T07:34:09Z

site/src/modules/resources/AgentExternal.tsx

+				{workspace.name} workspace:
+			</p>
+			<CodeExample
+				code={`CODER_AGENT_TOKEN="${externalAgentToken}" curl -fsSL "${initScriptURL}" | sh`}


Maybe the generation of the command should be moved to the backend and returned from the API, so we can keep it all in one place. This will need to eventually vary by OS/arch (curl | sh doesn't work on windows).

We can extend the credentials endpoint and add another field for the ready-to-go command. Unless you have a different idea?

That sounds good to me!

…estions

…ernalAgentByJobID into one query

…attach # Conflicts: # coderd/database/dump.sql # coderd/database/modelqueries.go # coderd/database/queries.sql.go # coderd/database/queries/templates.sql # coderd/searchquery/search.go # coderd/searchquery/search_test.go

…ecks for new endpoint

…lAgentByID

deansheather

Backend looks good, would like to see a few quick changes then I'll stamp

cli/external_workspaces.go

coderd/database/migrations/000358_external_agents.down.sql

deansheather · 2025-08-08T14:00:55Z

coderd/database/queries/templateversions.sql

@@ -234,3 +225,13 @@ FROM
 WHERE
 	template_versions.id IN (archived_versions.id)
 RETURNING template_versions.id;
+
+-- name: UpdateTemplateVersionAITaskAndExternalAgentByJobID :exec


Maybe UpdateTemplateVersionFlagsByJobID? The name might get even crazier if we add more of these post-build flag columns.

deansheather · 2025-08-08T14:01:08Z

coderd/database/queries/workspacebuilds.sql

@@ -253,3 +244,13 @@ WHERE
 	AND pj.job_status = 'failed'
 ORDER BY
 	tv.name ASC, wb.build_number DESC;
+
+-- name: UpdateWorkspaceBuildAITaskAndExternalAgentByID :exec


deansheather · 2025-08-08T14:02:09Z

coderd/init_script.go

+
+	script, exists := provisionersdk.AgentScriptEnv()[fmt.Sprintf("CODER_AGENT_SCRIPT_%s_%s", os, arch)]
+	if !exists {
+		rw.WriteHeader(http.StatusBadRequest)


You should probably write a message here too, using httpapi.Write(..., codersdk.Response{}) is probably fine.

Unknown os/arch: %s/%s

deansheather · 2025-08-08T14:04:01Z

coderd/init_script_test.go

+		client := coderdtest.New(t, nil)
+		script, err := client.InitScript(context.Background(), "windows", "amd64")
+		require.NoError(t, err)
+		require.NotEmpty(t, script)


Should test the replacements as well, probably search for substrings like $env:CODER_AGENT_AUTH_TYPE="token" (or whatever it's supposed to look like) etc.

deansheather · 2025-08-08T14:06:30Z

coderd/workspaceagents_test.go

+	client, db := coderdtest.NewWithDatabase(t, nil)
+	user := coderdtest.CreateFirstUser(t, client)
+
+	t.Run("Success", func(t *testing.T) {


Should check the returned command matches what you expect for both non-windows and windows in separate tests.

deansheather · 2025-08-08T14:08:16Z

codersdk/init_script.go

@@ -0,0 +1,28 @@
+package codersdk


nit: This file should probably be renamed just initscript.go to match other files in the dir like provisionerdaemons.go. Files ending with _xyz.go are usually for showing stuff similar build tags in the filename

deansheather · 2025-08-08T14:08:35Z

cli/external_workspaces.go

@@ -1,6 +1,7 @@
 package cli


nit: Maybe this should be externalworkspaces.go too

Co-authored-by: Dean Sheather <dean@deansheather.com>

aslilac · 2025-08-08T20:01:15Z

I would highly recommend breaking this PR down by domain. Right now it's extremely large.

quoting @johnstcn, I think this still needs to be addressed. I did a cursory review but it's really hard to actually feel comfortable approving a diff this large. I think this should probably be broken into at least like three chunks before it gets merged.

kacpersaw added 9 commits July 23, 2025 11:10

Add attach command and API endpoints for init-script and external age…

3ea541e

…nt credential

add has_external_agents column to template_versions table

4818df1

add external workspace creation and agent instruction commands to cli

4bfdb83

add has_external_agent to workspace builds

1044051

add list command for external workspaces

fd2458b

add AgentExternal component to display external agent connection deta…

0c39f50

…ils, extend CodeExample to redact parts of the code

Merge remote-tracking branch 'origin/main' into kacpersaw/feat-coder-…

23e555a

…attach # Conflicts: # cli/create.go # coderd/database/queries.sql.go # docs/admin/security/audit-logs.md # provisionersdk/proto/provisioner.pb.go

add tests

f9f5be1

Delete coder attach golden

e281f0e

kacpersaw requested a review from deansheather August 5, 2025 11:07

github-actions bot assigned kacpersaw Aug 5, 2025

kacpersaw changed the title ~~feat(coder-attach): add support for external workspaces~~ feat: coder-attach: add support for external workspaces Aug 5, 2025

kacpersaw added 2 commits August 5, 2025 11:43

Hide agent apps when connecting & is external agent

d77522d

Merge remote-tracking branch 'origin/main' into kacpersaw/feat-coder-…

451c806

…attach # Conflicts: # codersdk/workspaces.go

kacpersaw marked this pull request as ready for review August 5, 2025 11:44

kacpersaw requested review from aslilac, spikecurtis and johnstcn as code owners August 5, 2025 11:44

Reformat code

f9274fe

johnstcn reviewed Aug 5, 2025

View reviewed changes

aslilac reviewed Aug 6, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into kacpersaw/feat-coder-…

00b6f26

…attach # Conflicts: # coderd/database/queries/templateversions.sql

deansheather reviewed Aug 6, 2025

View reviewed changes

kacpersaw added 7 commits August 6, 2025 09:00

bump provisionerd proto version to v1.9

c019a31

Add beforeCreate and afterCreate to create handler, apply review sugg…

7d07857

…estions

Refactor init-script endpoint to use path params instead of query params

c462a69

Refactor init-script endpoint, apply review suggestions for db

2d2dfec

Apply FE review suggestions

387fc04

Return 404 if workspace agent is authenticated through instance id

c2588ea

Merge UpdateTemplateVersionAITaskByJobID and UpdateTemplateVersionExt…

33dd778

…ernalAgentByJobID into one query

kacpersaw added 9 commits August 7, 2025 13:14

update external agent credentials to include command in response

c413479

Bump terraform-provider-coder to v2.10.0

3c1d694

Regenerate sql

7cc6861

Fix lint & tests

da68c20

Regenerate dump.sql

2e24741

Fix provision test

682ea60

update external agent credentials summary and adjust authorization ch…

51967a5

…ecks for new endpoint

merge UpdateWorkspaceBuildAITaskByID with UpdateWorkspaceBuildExterna…

f060324

…lAgentByID

kacpersaw requested a review from deansheather August 8, 2025 13:52

deansheather reviewed Aug 8, 2025

View reviewed changes

kacpersaw and others added 2 commits August 8, 2025 16:20

Apply suggestions from code review

ff6e8fa

Co-authored-by: Dean Sheather <dean@deansheather.com>

Apply review suggestions

e2a7182

kacpersaw requested a review from deansheather August 8, 2025 14:41

Merge branch 'main' into kacpersaw/feat-coder-attach

141bc54

deansheather approved these changes Aug 8, 2025

View reviewed changes

kacpersaw requested a review from aslilac August 8, 2025 14:44

make gen

a75c1f4

	Short: "External workspace related commands",
	Short: "Create or manage external workspaces",

feat: coder-attach: add support for external workspaces #19178

Are you sure you want to change the base?

feat: coder-attach: add support for external workspaces #19178

Conversation

kacpersaw commented Aug 5, 2025

CLI changes

coderd changes

Database changes

provisioner changes

Frontend changes

Uh oh!

johnstcn left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deansheather left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deansheather left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

johnstcn left a comment •

edited

Loading