fix: write workspace SSH hosts to a shared glob include that ssh reads first (#1061)

Workspace SSH hosts move out of the user's config into generated files under
the platform data dir, one per editor and deployment, all behind a single
editor-agnostic Include block that moves back to the top of the config on every
connect. First value wins, so the generated options always take effect and
editors stop overwriting each other's hosts.

- Global options in the user's config, such as a catch-all `Host *`, no longer
  reach the connection; `coder.sshConfig` still overrides the generated ones.
- Drop the post-write "Unexpected SSH Config Option" abort, now redundant.
- Emit include paths inside $HOME as ~/..., quote and escape paths outside it,
  and reject characters ssh cannot read back.
- Honor remote.SSH.configFile only where ssh actually reads it; ignore the
  renamed setting on Antigravity and Windsurf, which spawn ssh without -F.
- Migrate only the historical coder-vscode authority, preserving wrappers and
  the full URI, reopening the window once; an untitled multi-root workspace
  keeps the old host behind an explanatory modal.
- Add "Coder: Open Generated SSH Configuration File", opening read-only.
- Add integration tests that run the real ssh -G against generated configs.

Closes #1055

Author: EhabY

CHANGELOG.md

@@ -5,6 +5,41 @@
      from published versions since it shows up in the VS Code extension changelog
      tab and is confusing to users. Add it back between releases if needed. -->
 
+## Unreleased
+
+### Added
+
+- Add a **Coder: Open Generated SSH Configuration File** command that opens
+  this editor's generated workspace hosts file in a read-only editor. A
+  connected window opens its own deployment's file; a local window asks which
+  deployment to open when there are several.
+
+### Changed
+
+- Write workspace SSH hosts to generated files under your platform's data
+  directory (`coder.coder-remote/ssh`) instead of into your SSH config. Your
+  config now carries only an include of that directory, which moves back to the
+  top on every connection. Because ssh uses the first value it finds for each
+  option, global options in your config, such as a catch-all `Host *`, no
+  longer change how the extension connects. To override the generated options,
+  set them in `coder.sshConfig`, which still takes precedence.
+- Generate one file per editor and deployment, all behind the same include, so
+  VS Code, Cursor, Windsurf, and other forks no longer overwrite one another's
+  workspace hosts. Each fork keeps its own SSH host prefix, and legacy
+  `coder-vscode` authorities are migrated by automatically reopening the window
+  once.
+- Stop aborting the connection with "Unexpected SSH Config Option". The include
+  now sits at the top of your config, so the generated options always take
+  effect and there is nothing left to warn about. Validation of the options
+  your deployment sends is unchanged.
+
+### Fixed
+
+- Ignore the SSH config file setting on Antigravity and Windsurf/Devin. They
+  launch ssh without pointing it at a config file, so it always reads
+  `~/.ssh/config`, and honoring the setting wrote the workspace host where the
+  connection never looked.
+
 ## [v1.16.0](https://github.com/coder/vscode-coder/releases/tag/v1.16.0) 2026-08-06
 
 ### Added

CONTRIBUTING.md

@@ -14,33 +14,62 @@ The `ssh-remote` scheme is registered by Microsoft's Remote - SSH extension and
 indicates that it should connect to the provided host name using SSH.
 
 The host name takes the format
-`coder-vscode.<domain>--<username>--<workspace>`. This is parsed by the CLI
-(which is invoked via SSH's `ProxyCommand`) to route SSH to the right workspace.
+`coder-<editor>.<domain>--<username>--<workspace>`, where `<editor>` comes from
+that product's URI scheme, such as `vscode`, `cursor`, or `windsurf`. The CLI is
+invoked through SSH's `ProxyCommand` with this prefix so it can route SSH to the
+right workspace. A legacy `coder-vscode` authority opened in another editor is
+reopened once with that editor's prefix; legacy recent-folder entries remain
+compatible when opening the same workspace.
 
 The Coder Remote extension also registers for the
 `onResolveRemoteAuthority:ssh-remote` [extension activation
 event](https://code.visualstudio.com/api/references/activation-events) to hook
 into this process, running before the Remote - SSH extension actually connects.
 
-On activation of this event, we check if `vscode.workspace.workspaceFolders`
-contains the `coder-vscode` prefix, and if so we delay activation to:
+On activation of this event, we check whether the remote authority belongs to
+the current editor, and if so we delay activation to:
 
 1. Parse the host name to get the domain, username, and workspace.
 2. Ensure the workspace is running.
 3. Download the matching server binary to the client.
 4. Configure the binary with the URL and token, asking the user for them if they
    are missing. Each domain gets its own config directory.
-5. Add an entry to the user's SSH config for `coder-vscode.<domain>--*`.
+5. Write an entry for `coder-<editor>.<domain>--*` to a per-editor,
+   per-deployment file in a data directory shared by every editor, such as
+   `~/.local/share/coder.coder-remote/ssh/cursor--dev.coder.com.conf`.
+6. Keep a shared `Include` block at the top of the user's SSH config that
+   globs the whole directory. Every editor writes the identical block, so
+   concurrent writers converge on the same content. The `CODER INCLUDE <id>`
+   marker convention lets other Coder integrations recognize the block, since
+   Coder-managed includes route disjoint hosts and are order-independent.
 
 ```text
-Host coder-vscode.dev.coder.com--*
-	ProxyCommand "/tmp/coder" --global-config "/home/kyle/.config/Code/User/globalStorage/coder.coder-remote/dev.coder.com" ssh --stdio --network-info-dir "/home/kyle/.config/Code/User/globalStorage/coder.coder-remote/net" --ssh-host-prefix coder-vscode.dev.coder.com-- %h
-	ConnectTimeout 0
-	StrictHostKeyChecking no
-	UserKnownHostsFile /dev/null
-	LogLevel ERROR
+# --- START CODER INCLUDE CODER-REMOTE ---
+# Managed by the Coder extension for VS Code and its forks.
+# Moves back to the top on connect; override options via coder.sshConfig.
+Include "~/.local/share/coder.coder-remote/ssh/*.conf"
+# --- END CODER INCLUDE CODER-REMOTE ---
 ```
 
+Each generated file contains only its own editor's host entries for one
+deployment:
+
+```text
+Host coder-cursor.dev.coder.com--*
+  ProxyCommand "/tmp/coder" --global-config "/home/kyle/.config/Cursor/User/globalStorage/coder.coder-remote/dev.coder.com" ssh --stdio --network-info-dir "/home/kyle/.config/Cursor/User/globalStorage/coder.coder-remote/net" --ssh-host-prefix coder-cursor.dev.coder.com-- %h
+  ConnectTimeout 0
+  StrictHostKeyChecking no
+  UserKnownHostsFile /dev/null
+  LogLevel ERROR
+```
+
+Which main file gains the include depends on the Remote - SSH extension.
+Microsoft's and Cursor's pass `remote.SSH.configFile` to ssh with `-F`, and
+VSCodium's parses the file itself instead of running ssh, so all three connect
+through it. Antigravity and Windsurf/Devin renamed the setting but spawn ssh
+without `-F`, so ssh reads `~/.ssh/config` regardless; we ignore the renamed
+setting there rather than add the include where the connection never looks.
+
 If any step fails, we show an error message. Once the error message is closed
 we close the remote so the Remote - SSH connection does not continue to
 connection. Otherwise, we yield, which lets the Remote - SSH continue.

eslint.config.mjs

@@ -123,6 +123,12 @@ export default defineConfig(
 					message:
 						"Do not use registerCommand('coder.*', ...) directly. Use the CommandManager class instead.",
 				},
+				{
+					selector:
+						"MemberExpression[property.name='remoteAuthority'][object.property.name='env'][object.object.name='vscode']",
+					message:
+						"env.remoteAuthority is a proposed API (resolvers) and throws through our own vscode module. Read it via vscodeProposed.env.remoteAuthority.",
+				},
 			],
 		},
 	},

package.json

@@ -478,12 +478,20 @@
 			},
 			{
 				"command": "coder.viewLogs",
-				"title": "Coder: View Logs",
+				"title": "View Logs",
+				"category": "Coder",
 				"icon": "$(list-unordered)"
 			},
+			{
+				"command": "coder.openSshConfig",
+				"title": "Open Generated SSH Configuration File",
+				"category": "Coder",
+				"icon": "$(file-code)"
+			},
 			{
 				"command": "coder.exportTelemetry",
-				"title": "Coder: Export Telemetry",
+				"title": "Export Telemetry",
+				"category": "Coder",
 				"icon": "$(save)"
 			},
 			{
@@ -616,6 +624,10 @@
 					"command": "coder.viewLogs",
 					"when": "true"
 				},
+				{
+					"command": "coder.openSshConfig",
+					"when": "true"
+				},
 				{
 					"command": "coder.exportTelemetry",
 					"when": "true"

src/commands.ts

@@ -50,7 +50,11 @@ import {
 	toRemoteLogGlobs,
 } from "./supportBundle/remoteServerDataPath";
 import { runExportTelemetryCommand } from "./telemetry/export/command";
-import { toRemoteAuthority } from "./util/authority";
+import {
+	isRemoteAuthorityCompatible,
+	parseRemoteAuthority,
+	toRemoteAuthority,
+} from "./util/authority";
 import { openInBrowser, toSafeHost } from "./util/uri";
 import { vscodeProposed } from "./vscodeProposed";
 import { parseNetcheckReport } from "./webviews/netcheck/types";
@@ -83,6 +87,9 @@ import type {
 	PongMessage,
 } from "./workspace/duplicateWorkspaceIpc";
 
+const NO_SSH_CONFIG_MESSAGE =
+	"No SSH config has been generated yet. It is written when you connect to a workspace.";
+
 interface OpenOptions {
 	workspaceOwner?: string;
 	workspaceName?: string;
@@ -565,6 +572,56 @@ export class Commands {
 		);
 	}
 
+	/** Open this editor's generated SSH config, picking a deployment when several exist. */
+	public async openSshConfig(): Promise<void> {
+		const hostname = await this.pickSshHostname();
+		if (!hostname) {
+			return;
+		}
+		try {
+			await openFile(this.pathResolver.getSshConfigPath(hostname));
+		} catch {
+			vscode.window.showInformationMessage(NO_SSH_CONFIG_MESSAGE);
+			return;
+		}
+		// The file is rewritten on every connection, so edits would be lost.
+		await vscode.commands.executeCommand(
+			"workbench.action.files.setActiveEditorReadonlyInSession",
+		);
+	}
+
+	/** A connected window resolves to its own deployment; otherwise ask. */
+	private async pickSshHostname(): Promise<string | undefined> {
+		try {
+			// remoteAuthority is a proposed API; our own vscode module may not read it.
+			const remoteAuthority = vscodeProposed.env.remoteAuthority;
+			if (remoteAuthority) {
+				const parts = parseRemoteAuthority(remoteAuthority);
+				if (parts) {
+					return parts.safeHostname;
+				}
+			}
+		} catch {
+			// Malformed Coder authority or unavailable API; fall through to the picker.
+		}
+		const hostnames = (
+			await readdirOrEmpty(this.pathResolver.getSshConfigDir())
+		)
+			.map((file) => this.pathResolver.parseSshConfigFile(file))
+			.filter((name) => name !== undefined);
+		if (hostnames.length === 0) {
+			vscode.window.showInformationMessage(NO_SSH_CONFIG_MESSAGE);
+			return undefined;
+		}
+		if (hostnames.length === 1) {
+			return hostnames[0];
+		}
+		return vscode.window.showQuickPick(hostnames, {
+			title: "Open generated SSH configuration",
+			placeHolder: "Select a deployment",
+		});
+	}
+
 	/**
 	 * View the logs for the currently connected workspace.
 	 */
@@ -1475,12 +1532,11 @@ export class Commands {
 			const output: {
 				workspaces: Array<{ folderUri: vscode.Uri; remoteAuthority: string }>;
 			} = await vscode.commands.executeCommand("_workbench.getRecentlyOpened");
-			const opened = output.workspaces.filter(
-				// Remove recents that do not belong to this connection.  The remote
-				// authority maps to a workspace/agent combination (using the SSH host
-				// name).  There may also be some legacy connections that still may
-				// reference a workspace without an agent name, which will be missed.
-				(opened) => opened.folderUri?.authority === remoteAuthority,
+			const opened = output.workspaces.filter((opened) =>
+				isRemoteAuthorityCompatible(
+					opened.folderUri?.authority,
+					remoteAuthority,
+				),
 			);
 			// openRecent will always use the most recent.  Otherwise, if there are
 			// multiple we ask the user which to use.

src/core/commandManager.ts

@@ -20,6 +20,7 @@ export const CODER_COMMAND_IDS = [
 	"coder.navigateToWorkspaceSettings",
 	"coder.refreshWorkspaces",
 	"coder.viewLogs",
+	"coder.openSshConfig",
 	"coder.exportTelemetry",
 	"coder.viewAnnouncements",
 	"coder.searchMyWorkspaces",

src/core/pathResolver.ts

@@ -1,7 +1,28 @@
+import * as os from "node:os";
 import * as path from "node:path";
 import * as vscode from "vscode";
 
 import { expandPath } from "../util";
+import { currentEditorId } from "../util/authority";
+
+/** Extension of generated SSH config files; the include glob matches on it. */
+export const SSH_CONFIG_EXT = ".conf";
+
+/** The per-user data dir of the platform, shared by every editor. */
+function platformDataDir(): string {
+	switch (process.platform) {
+		case "win32":
+			return (
+				process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming")
+			);
+		case "darwin":
+			return path.join(os.homedir(), "Library", "Application Support");
+		default:
+			return (
+				process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share")
+			);
+	}
+}
 
 export class PathResolver {
 	constructor(
@@ -42,6 +63,30 @@ export class PathResolver {
 		return path.join(this.basePath, "net");
 	}
 
+	/**
+	 * Directory of generated SSH configs, glob-included from the user's config.
+	 * Lives in the platform data dir so every editor emits the same include.
+	 */
+	public getSshConfigDir(): string {
+		return path.join(platformDataDir(), "coder.coder-remote", "ssh");
+	}
+
+	/** This editor's generated SSH config for one deployment. */
+	public getSshConfigPath(safeHostname: string): string {
+		return path.join(
+			this.getSshConfigDir(),
+			`${currentEditorId()}--${safeHostname}${SSH_CONFIG_EXT}`,
+		);
+	}
+
+	/** The deployment hostname if this editor generated the file, else undefined. */
+	public parseSshConfigFile(fileName: string): string | undefined {
+		const prefix = `${currentEditorId()}--`;
+		return fileName.startsWith(prefix) && fileName.endsWith(SSH_CONFIG_EXT)
+			? fileName.slice(prefix.length, -SSH_CONFIG_EXT.length)
+			: undefined;
+	}
+
 	/**
 	 * Return the directory where telemetry files are written.
 	 */

src/extension.ts

@@ -350,6 +350,10 @@ async function doActivate(
 		void allWorkspacesProvider.fetchAndRefresh();
 	});
 	commandManager.register("coder.viewLogs", commands.viewLogs.bind(commands));
+	commandManager.register(
+		"coder.openSshConfig",
+		commands.openSshConfig.bind(commands),
+	);
 	commandManager.register(
 		"coder.exportTelemetry",
 		commands.exportTelemetry.bind(commands),