SSH hints across the CLI, dashboard and docs used different, sometimes
broken, workspace names. This makes them consistent with minimal,
non-breaking changes and no new syntax:
- Plain `ssh` hostnames: `<agent>.<workspace>.<owner>.<suffix>` (or
`<workspace>.<suffix>` for single-agent workspaces). Works with
`config-ssh` (with or without `--no-wildcard`) and Coder Connect.
- `coder` CLI arguments: `[<owner>/]<workspace>[.<agent>]`, with the
owner unless the workspace was given by its bare name.
Built on #31192, which is now merged into `main`.
## Changes
- **`coder ping` multi-agent error**: now suggests `coder ping
<workspace>.<agent>` instead of listing agents without a runnable
command. Owner-qualified and UUID inputs retain `<owner>/<workspace>`.
JSON-mode errors leave stdout empty, and ping still does not autostart
stopped workspaces.
- **`coder ssh` multi-agent error**: when run directly (no
`--ssh-host-prefix`/`--hostname-suffix`), it suggested `ssh
coder.dogfood.matifali`, which never resolves without a matching SSH
config entry or Coder Connect. For an agent named `dev`, it now suggests
`coder ssh dogfood.dev`, or `coder ssh bob/dogfood.dev` if the workspace
was given as `owner/name` or by ID. Here `.dev` selects the agent; it is
not an SSH hostname suffix. The ProxyCommand path used by `config-ssh`
and the IDE plugins still suggests the full hostname.
- **`coder show` / `coder create`**: the access column dropped the
owner, so `coder show bob/dogfood` or `coder show <id>` suggested `coder
ssh dogfood.dev`. It now keeps the owner unless the workspace was given
by its bare name.
- **`coder config-ssh`**: the example `ssh <workspace>.coder` is
ambiguous for multi-agent workspaces. It now names an agent, `ssh
<agent>.<workspace>.<owner>.coder`, reading a stopped workspace’s known
agents from its latest successful start using the same template version.
With `--no-wildcard`, the hint reuses the workspace snapshot and
resources used to write the Host entries.
- **Dashboard "Connect via SSH"**: rendered `...<owner>.undefined` when
the deployment has no hostname suffix. It now falls back to `coder ssh
<owner>/<workspace>` for single-agent workspaces, or `coder ssh
<owner>/<workspace>.<agent>` otherwise. With a hostname suffix, owned
single-agent workspaces show `ssh <workspace>.<suffix>` unless that
hostname collides with the deployment’s legacy prefix block. Prefix
collisions, shared workspaces and multi-agent workspaces retain the full
agent/workspace/owner hostname. The count includes agents across all
resources and devcontainers. Commands remain undefined while the SSH
config loads, with a spinner instead of a premature fallback. If the
initial load fails, it displays the error while keeping the CLI command
available.
- **Docs**: workspace access docs said `config-ssh` prints `ssh
coder.<workspace>`; it prints `ssh <workspace>.coder`. Added the
multi-agent hostname, noted it in the Desktop docs, and updated the
Gateway host and the networking page to `<workspace>.coder`.
## Before / after
```console
$ coder ssh dogfood
error: multiple agents found, please specify the agent name, available agents: [coder dev]
Try running:
$ ssh dev.dogfood.matifali # before: does not resolve
$ coder ssh dogfood.dev # after: dev is the agent name
```
## Compatibility
Hostname parsing (`findWorkspaceAndAgentByHostname`,
`normalizeWorkspaceInput`) is unchanged, so every hostname that resolves
today still does. The VS Code, JetBrains Gateway and Toolbox plugins
write their own `Host` entries and run `coder ssh --stdio
--ssh-host-prefix <prefix>`, so they don't reach the changed hints.
`TestSSH_AgentHostnames` connects with their
`<prefix>--<owner>--<workspace>.<agent>` form, and with the
`<agent>.<workspace>.<owner>` forms used by `config-ssh` and the
dashboard.
## Verification
CLI/resource race tests pass, including the complete original `TestSSH`
suite and the new agent-hostname round trips. `TestConfigSSH_Example`
checks running two-agent and stopped one-/two-agent workspaces whose
import defaults differ, with and without `--no-wildcard`. It verifies
the hint has a matching generated Host entry and reuses workspace
history once per stopped workspace. `TestShow` covers bare names,
owner-qualified names and UUIDs; `TestCreate/CreateForOtherUser` checks
the owner-qualified preview. Mutation checks confirmed the new
assertions fail when the protected behavior is removed.
`TestPing_AgentSuggestions` covers bare names, owner-qualified names,
UUIDs and JSON-mode errors with a shared fixture. The tests fail without
the new hints; an owner-omission control also fails the qualified/UUID
cases. The original network-heavy `TestPing` suite remains unchanged and
passes its normal race run.
Normal and strict new-code Go lint, frontend checks/lint/typechecking,
all eleven SSHButton stories, and docs checks pass. Browser checks
verified copied SSH/CLI commands and keyboard dismissal; screenshots
were visually inspected. The single-agent follow-up adds 25 command-copy
cases covering ownership, agents across resources, subagents, and
zero/unknown counts. All 53 affected SSHButton, AgentRow, and
AgentDevcontainerCard stories pass, with browser validation of both real
callers and regression/mutation controls for the command-selection
guards.
<details>
<summary>CI follow-up and validation commands</summary>
After #31192 merged, the parent commits were dropped and the remaining
eleven commits were rebased onto the merge commit `fb6d287528`.
Range-diff and full-tree comparisons confirm no implementation changes.
Revalidated the complete SSH/ping/config race suite and strict lint
after that rebase.
Latest rebase preserves the implementation and carries the docs edits to
main’s renamed `docs/workspaces/` paths. The SSHButton documentation
links and preview URL use the new routes. Revalidated the full
SSH/ping/config CLI race suite, strict lint, 25 frontend tests, 53
stories, and docs/manifest/redirect checks. The local shell’s Oh My Zsh
update prompt interrupted the first race run; the unchanged suite passed
with `DISABLE_AUTO_UPDATE=true` scoped to the test process.
Latest review follow-up: connection commands remain undefined during
initial loading, and each instruction is gated on its own command. A
cached SSH suffix remains usable after a failed refetch; a story
captures that state. Rebased directly onto `main` at `fb6d287528` after
#31192 merged. The P2 follow-up preserves native hostnames that collide
with legacy prefix blocks, uses workspace-specific history for stopped
agents, and retains safe precreated devcontainer names.
Earlier stress runs of the unmodified `TestSSH` suite exceeded the 6,144
MiB guard under 35-repeat stress. Its existing scenarios remain
unchanged. The three added agent-qualified hostname cases have
independent full SSH round-trip coverage in `TestSSH_AgentHostnames`,
with a shared fixture. The current top-PR changed-test selector chooses
seven tests without the unrelated `TestSSH` scenarios, and the complete
selected set passes 35 repetitions at parallelism 16 with the same
memory guard. No test cases, repetitions, parallelism or memory checks
were removed.
```sh
go test -race -tags=testsmallbatch ./cli ./cli/cliui -run '^TestSSH$|^TestSSH_AgentHostnames$|TestPing|TestConfigSSH|TestShow|TestCreate|Test_agentSSHSuggestion|Test_suggestWithOwner|TestWorkspaceResources|Test_noWildcardHostNames|Test_previousStartResources|TestCommandHelp' -count=1 -parallel=4
GOMEMLIMIT=6GiB golangci-lint run --allow-serial-runners --concurrency=4 --new-from-rev=origin/main ./cli/...
GOMEMLIMIT=6GiB make lint/go/new-code GO_LINT_CONCURRENCY=4
CODER_TEST_MEMORY_LIMIT_MIB=6144 TS_DEBUG_DISCO=true TS_DEBUG_DERP=true go test -tags=testsmallbatch -p=4 -count=35 -parallel=16 -shuffle=1 -timeout=10m -run '^(TestConfigSSH_Example|TestCreate|TestPing_AgentSuggestions|TestSSH_AgentHostnames|TestShow|Test_agentSSHSuggestion|Test_suggestWithOwner)(/.*)?$' ./cli
cd site
pnpm check
pnpm lint
pnpm test src/modules/resources/SSHButton/SSHButton.test.tsx
pnpm test:storybook src/modules/resources/SSHButton/SSHButton.stories.tsx src/modules/resources/AgentRow.stories.tsx src/modules/resources/AgentDevcontainerCard.stories.tsx --run
```
</details>
Follow-up to #19943. Tracks
[CLI-67](https://linear.app/codercom/issue/CLI-67/fix-coder-ssh-suggestions-for-multi-agent-workspaces).
Preview:
https://coder.com/docs/@fix%2Fssh-multi-agent-hint/workspaces/workspace-access
> 🤖 This PR was created with the help of Coder Agents, and has been
reviewed by my human. 🧑💻
`coder config-ssh --no-wildcard` writes one `Host` entry per workspace
and none per agent. OpenSSH only applies exact `Host` matches, so with
`--no-wildcard` (and without Coder Desktop):
- `ssh <agent>.<workspace>.<owner>.coder`, the hostname the dashboard's
**Connect via SSH** button shows and Coder Connect serves, doesn't
resolve.
- Agents in multi-agent workspaces can't be reached with plain `ssh`;
`ssh <workspace>.coder` hits "multiple agents found".
Before wildcard hosts (#14986), `config-ssh` wrote an entry per agent.
`--no-wildcard` (#26753) brought back per-workspace entries only.
## Change
With `--no-wildcard`, also write an `<agent>.<workspace>.<owner>` entry
for each agent, using the same prefix/suffix as workspace entries:
```
Host dogfood.coder # unchanged
Host coder.dogfood.matifali.coder # new
Host dev.dogfood.matifali.coder # new
```
`coder ssh --stdio` already parses `agent.workspace.owner`, so no
ProxyCommand changes are needed.
- **Non-breaking**: existing `<workspace>` entries are unchanged; agent
entries are added after them. Without `--no-wildcard` the config is
unchanged.
- **Workspaces without agents on their latest build** (stopped, or a
start that is pending or failed): known agents come from that
workspace’s most recent successful start using the same template
version, not template-import defaults. Lookups are cached per workspace
and bounded to eight concurrent requests. Missing or incompatible
history leaves only the workspace entry; lookup failures also produce a
warning.
- **Devcontainers**: while a workspace runs, its sub-agents get entries
too.
- **Validation**: workspace and owner names retain `codersdk.NameValid`
checks. Agent components permit safe ASCII letters, digits, underscores
and hyphens, preserving Terraform-precreated names such as `dev_box`
while rejecting SSH syntax, leading options and doubled-hyphen
delimiters. Workspace entries are written as before, including legacy
names (related: SEC-378).
The flag description, generated CLI reference/help, and workspace access
and Gateway tips describe known agents. The guide explains when stopped
workspaces have only a workspace entry and how to populate their agent
entries.
## Verification
`TestConfigSSH_NoWildcard` verifies two stopped workspaces sharing a
template version but having different actual agents, import defaults
that differ from both, a precreated `dev_box` agent, and injection
rejection. History tests cover pagination, failed/newer builds, version
changes and request failures. Regression controls failed before the
fixes and passed afterward. Race tests, strict Go lint and docs checks
pass on the refreshed stack.
<details>
<summary>Validation commands</summary>
Latest rebase preserves the implementation and carries the docs edits to
main’s renamed `docs/workspaces/` paths. The SSHButton documentation
links and preview URL use the new routes. Revalidated the full
SSH/ping/config CLI race suite, strict lint, 25 frontend tests, 53
stories, and docs/manifest/redirect checks. The local shell’s Oh My Zsh
update prompt interrupted the first race run; the unchanged suite passed
with `DISABLE_AUTO_UPDATE=true` scoped to the test process.
Review decision: use workspace-specific build history because template
imports cannot represent chosen workspace parameters. Preserve the
last-start template-version boundary rather than inventing agents when
no compatible history exists. Both stack branches are rebased onto
`main` at `63b5c4d64a`.
```sh
go test -race -tags=testsmallbatch ./cli -run 'TestConfigSSH|Test_noWildcardHostNames|Test_previousStartResources|TestCommandHelp' -count=1 -parallel=4
GOMEMLIMIT=6GiB make lint/go/new-code GO_LINT_CONCURRENCY=4
```
Docs validation also passed emdash, HTML-table and manifest checks,
targeted markdownlint, table formatting and Vale.
</details>
Fixes
[CLI-68](https://linear.app/codercom/issue/CLI-68/config-ssh-no-wildcard-does-not-write-host-entries-for-workspace).
#31188 is stacked on this PR.
Preview:
https://coder.com/docs/@fix%2Fconfig-ssh-no-wildcard-agents/workspaces/workspace-access
> 🤖 This PR was created with the help of Coder Agents, and has been
reviewed by my human. 🧑💻
## Problem
`coder config-ssh --ssh-host-prefix=""` (or the matching env var,
`CODER_CONFIGSSH_SSH_HOST_PREFIX=`) was silently ignored, and the
deprecated `Host coder.*` block was written to the SSH config anyway.
The
merge logic that decides whether to fall back to the server's default
prefix checked `user.userHostPrefix == ""`, which is true both when the
flag was never passed and when it was explicitly set to empty, so there
was no way to distinguish the two. The same issue applied to
`--hostname-suffix`.
## How this affects users
Anyone who wants to opt out of the legacy prefix-based SSH aliases
(`ssh coder.myworkspace`) in favor of the newer suffix-based ones
(`ssh myworkspace.coder`) had no way to do so, the `Host coder.*`
wildcard
block kept reappearing on every `config-ssh` run regardless of the flag.
Because that wildcard matches any hostname starting with `coder.`, not
just Coder workspaces, it can silently intercept SSH connections to
unrelated hosts that happen to share that prefix.
It got worse on top of that: even after passing `--ssh-host-prefix=""`,
running `config-ssh --use-previous-options` in a later session, a normal
way to refresh local config without retyping every flag, would silently
bring the block back, because the empty choice was never persisted to
the
file in the first place.
## Solution
Track whether each option (`--ssh-host-prefix`, `--hostname-suffix`) was
explicitly set by the user, as opposed to left at its zero value, and
only
fall back to the server default (or skip persisting the option) when it
was genuinely never set.
## How it works
Two new fields on `sshConfigOptions`, `userHostPrefixExplicit` and
`hostnameSuffixExplicit`, carry this information:
- **Live invocation**: they're set from `userSetOption(inv, ...)`, which
inspects serpent's `Option.ValueSource` for the flag, right after
`header`/`headerCommand` are set in the `Handler`, before any
`--use-previous-options`/prompt logic can replace the struct wholesale
from a prior run's saved options.
- **Persistence**: `sshConfigWriteSectionHeader` now writes the
`# :ssh-host-prefix=` comment line even when the value is empty, as long
as it was explicit, and `sshConfigParseLastOptions` sets the field back
to `true` whenever it parses that line on a later run, regardless of
value.
`mergeSSHOptions`'s fallback condition changed from
`user.userHostPrefix == ""` to
`user.userHostPrefix == "" && !user.userHostPrefixExplicit` (and the
mirror for suffix). `equal()` and `asList()` were extended to include
the
two new fields so the `--dry-run` diff and "options differ, use new
ones?"
prompt stay accurate.
## Why implemented this way
- Reuses `userSetOption` (`cli/util.go`), an existing helper already
used
for this exact "distinguish zero value from unset" problem elsewhere in
the CLI (`cli/templateedit.go`), instead of inventing new machinery.
- Storing the "explicit" bit as a plain field on `sshConfigOptions`,
rather
than as extra parameters to `mergeSSHOptions`, keeps that function
dependency-free (still plain data in, plain data out, no
`serpent.Invocation` coupling), while letting the same bit flow
naturally
through the SSH config's persisted-options comment, solving the
live-flag
case and the `--use-previous-options` persistence case with one
mechanism instead of two.
- A sentinel-value approach was considered and rejected: a self-tracking
custom `serpent.Value` doesn't work because serpent applies a flag's
default through the same `Value.Set()` call used for real input, so it
can't tell the two apart; a plain sentinel string would work but leak
into several other code paths (equality checks, diff/prompt text, the
persisted comment) that would all need to filter it out.
Closes https://github.com/coder/internal/issues/1208
## Manual verification
Every step below was run against a local dev server
(`./scripts/develop.sh`
+ `./scripts/coder-dev.sh`), pointed at a throwaway `--ssh-config-file`,
never a real `~/.ssh/config`.
### 1. Baseline: unchanged behavior with no flags
```sh
./scripts/coder-dev.sh config-ssh --yes --ssh-config-file "$TEST_SSH_CONFIG"
cat "$TEST_SSH_CONFIG"
```
Both `Host coder.*` and `Host *.coder` are written, unchanged from
before this fix (both server defaults are non-empty out of the box).
<details>
<summary>Output</summary>
```text
Updated "/tmp/tmp.9Y7VIeuQoY"
You should now be able to ssh into your workspace.
For example, try running:
$ ssh myworkspace.coder
# ------------START-CODER-----------
# This section is managed by coder. DO NOT EDIT.
#
# You should not hand-edit this section unless you are removing it, all
# changes will be lost when running "coder config-ssh".
#
Host coder.*
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
ProxyCommand .../coder-slim ... ssh --stdio --ssh-host-prefix coder. %h
Host *.coder
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
Match host *.coder !exec ".../coder-slim connect exists %h"
ProxyCommand .../coder-slim ... ssh --stdio --hostname-suffix coder %h
# ------------END-CODER------------
```
</details>
### 2. Explicit empty `--ssh-host-prefix` omits the legacy block (the
core fix)
```sh
./scripts/coder-dev.sh config-ssh --yes --ssh-config-file "$TEST_SSH_CONFIG" --ssh-host-prefix ""
cat "$TEST_SSH_CONFIG"
```
`Host coder.*` is gone, only `Host *.coder` remains. The choice is now
also persisted (`# :ssh-host-prefix=`).
<details>
<summary>Output</summary>
```text
Updated "/tmp/tmp.9Y7VIeuQoY"
You should now be able to ssh into your workspace.
For example, try running:
$ ssh myworkspace.coder
# ------------START-CODER-----------
# This section is managed by coder. DO NOT EDIT.
#
# You should not hand-edit this section unless you are removing it, all
# changes will be lost when running "coder config-ssh".
#
# Last config-ssh options:
# :ssh-host-prefix=
#
Host *.coder
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
Match host *.coder !exec ".../coder-slim connect exists %h"
ProxyCommand .../coder-slim ... ssh --stdio --hostname-suffix coder %h
# ------------END-CODER------------
```
</details>
### 3. Same, via the environment variable instead of the flag
```sh
CODER_CONFIGSSH_SSH_HOST_PREFIX="" ./scripts/coder-dev.sh config-ssh --yes --ssh-config-file "$TEST_SSH_CONFIG"
grep -c "Host coder" "$TEST_SSH_CONFIG"
```
Confirms the fix isn't flag-only, `userSetOption` checks `ValueSource`,
set the same way for `ValueSourceFlag` and `ValueSourceEnv`.
<details>
<summary>Output</summary>
```text
Updated "/tmp/tmp.9Y7VIeuQoY"
You should now be able to ssh into your workspace.
For example, try running:
$ ssh myworkspace.coder
0
```
</details>
### 4. Explicit empty prefix combined with an explicit suffix
```sh
./scripts/coder-dev.sh config-ssh --yes --ssh-config-file "$TEST_SSH_CONFIG" --ssh-host-prefix "" --hostname-suffix mytest
cat "$TEST_SSH_CONFIG"
```
Only `Host *.mytest` is written. Both options are correctly recorded in
the persisted comment.
<details>
<summary>Output</summary>
```text
Updated "/tmp/tmp.9Y7VIeuQoY"
You should now be able to ssh into your workspace.
For example, try running:
$ ssh myworkspace.mytest
# ------------START-CODER-----------
# This section is managed by coder. DO NOT EDIT.
#
# You should not hand-edit this section unless you are removing it, all
# changes will be lost when running "coder config-ssh".
#
# Last config-ssh options:
# :ssh-host-prefix=
# :hostname-suffix=mytest
#
Host *.mytest
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
Match host *.mytest !exec ".../coder-slim connect exists %h"
ProxyCommand .../coder-slim ... ssh --stdio --hostname-suffix mytest %h
# ------------END-CODER------------
```
</details>
### 5. The explicitly-empty choice survives `--use-previous-options`
with no flag repeated
This is the persistence half of the fix: confirms the "omit this block"
choice, once persisted, doesn't get lost on a later run that reuses
previous options without repeating `--ssh-host-prefix`. Before this fix,
this exact sequence would bring `Host coder.*` back.
```sh
./scripts/coder-dev.sh config-ssh --yes --ssh-config-file "$TEST_SSH_CONFIG" --ssh-host-prefix ""
./scripts/coder-dev.sh config-ssh --yes --ssh-config-file "$TEST_SSH_CONFIG" --use-previous-options
cat "$TEST_SSH_CONFIG"
```
<details>
<summary>Output</summary>
```text
Updated "/tmp/tmp.9Y7VIeuQoY"
You should now be able to ssh into your workspace.
For example, try running:
$ ssh myworkspace.coder
No changes to make.
# ------------START-CODER-----------
# This section is managed by coder. DO NOT EDIT.
#
# You should not hand-edit this section unless you are removing it, all
# changes will be lost when running "coder config-ssh".
#
# Last config-ssh options:
# :ssh-host-prefix=
#
Host *.coder
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
Match host *.coder !exec ".../coder-slim connect exists %h"
ProxyCommand .../coder-slim ... ssh --stdio --hostname-suffix coder %h
# ------------END-CODER------------
```
</details>
The second command printed `No changes to make.`, and critically, `Host
coder.*` did **not** reappear even though that run passed no
`--ssh-host-prefix` flag at all, only `--use-previous-options`.
### 6. `--use-previous-options` still wins over this run's explicit
empty flag (unaffected by this fix)
Confirms this fix didn't change the pre-existing, intentional precedence
of `--use-previous-options`: a previously-saved *non-empty* value still
wins over an explicit empty flag passed on a later run.
```sh
./scripts/coder-dev.sh config-ssh --yes --ssh-config-file "$TEST_SSH_CONFIG" --ssh-host-prefix "custom-test."
./scripts/coder-dev.sh config-ssh --yes --ssh-config-file "$TEST_SSH_CONFIG" --use-previous-options --ssh-host-prefix ""
cat "$TEST_SSH_CONFIG"
```
<details>
<summary>Output</summary>
```text
Updated "/tmp/tmp.9Y7VIeuQoY"
You should now be able to ssh into your workspace.
For example, try running:
$ ssh myworkspace.coder
No changes to make.
# ------------START-CODER-----------
# This section is managed by coder. DO NOT EDIT.
#
# You should not hand-edit this section unless you are removing it, all
# changes will be lost when running "coder config-ssh".
#
# Last config-ssh options:
# :ssh-host-prefix=custom-test.
#
Host custom-test.*
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
ProxyCommand .../coder-slim ... ssh --stdio --ssh-host-prefix custom-test. %h
Host *.coder
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
Match host *.coder !exec ".../coder-slim connect exists %h"
ProxyCommand .../coder-slim ... ssh --stdio --hostname-suffix coder %h
# ------------END-CODER------------
```
</details>
`Host custom-test.*` is preserved verbatim, `--use-previous-options`
correctly overrides the explicit empty flag when the saved value is
non-empty, the mirror image of step 5's explicit-empty saved value.
### 7. End-to-end sanity check with a real workspace
```sh
./scripts/coder-dev.sh config-ssh --yes --ssh-config-file "$TEST_SSH_CONFIG" --ssh-host-prefix "" --hostname-suffix mytest
ssh -F "$TEST_SSH_CONFIG" -o ConnectTimeout=15 myworkspace.mytest echo ok
```
<details>
<summary>Output</summary>
```text
Updated "/tmp/tmp.9Y7VIeuQoY"
You should now be able to ssh into your workspace.
For example, try running:
$ ssh myworkspace.mytest
ok
```
</details>
`ok` came back from a real, running workspace, confirming the
ProxyCommand and Match/exec wiring generated by the suffix-only config
actually establishes a working SSH session end-to-end, not just a
text-generation check.
Add `--no-wildcard` (`CODER_CONFIGSSH_NO_WILDCARD`) to `coder
config-ssh` that generates an individual `Host` entry per workspace
instead of a single wildcard block (`Host *.coder`).
The wildcard approach cannot be enumerated by third-party SSH clients,
the VS Code Remote-SSH sidebar, or scripts that parse `~/.ssh/config` to
discover hosts. With `--no-wildcard`, each workspace gets its own entry
so those tools work without Coder-specific extensions.
The flag is persisted in the config section header so re-running without
it prompts the user about the option change. Workspaces are fetched with
pagination before writing so the diff shows actual hostnames.
## Manual testing
**Unit tests (no server needed):**
```sh
go test ./cli/ -run TestSSHConfigOptions_writeToBuffer -v
go test ./cli/ -run TestConfigSSH_NoWildcard -v
```
**End-to-end with a dev server:**
1. Build: `go build -o ./coder .`
2. Start dev server in a separate terminal: `./scripts/develop.sh`
3. Log in: `./coder login http://localhost:3000`
4. Create two workspaces
5. Run both variants into temp files:
```sh
./coder config-ssh --no-wildcard --hostname-suffix coder --ssh-config-file /tmp/test-ssh-config --yes
./coder config-ssh --hostname-suffix coder --ssh-config-file /tmp/test-ssh-config-wildcard --yes
diff /tmp/test-ssh-config-wildcard /tmp/test-ssh-config
```
<details>
<summary>Output: <code>--no-wildcard</code></summary>
```
# ------------START-CODER-----------
# This section is managed by coder. DO NOT EDIT.
#
# You should not hand-edit this section unless you are removing it, all
# changes will be lost when running "coder config-ssh".
#
# Last config-ssh options:
# :hostname-suffix=coder
# :no-wildcard=true
#
Host coder.myworkspace
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
ProxyCommand <coder> --global-config <config> ssh --stdio --ssh-host-prefix coder. %h
Host coder.myworkspace2
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
ProxyCommand <coder> --global-config <config> ssh --stdio --ssh-host-prefix coder. %h
Host myworkspace.coder
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
Match host myworkspace.coder !exec "<coder> connect exists %h"
ProxyCommand <coder> --global-config <config> ssh --stdio --hostname-suffix coder %h
Host myworkspace2.coder
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
Match host myworkspace2.coder !exec "<coder> connect exists %h"
ProxyCommand <coder> --global-config <config> ssh --stdio --hostname-suffix coder %h
# ------------END-CODER------------
```
</details>
<details>
<summary>Output: wildcard (default)</summary>
```
# ------------START-CODER-----------
# This section is managed by coder. DO NOT EDIT.
#
# You should not hand-edit this section unless you are removing it, all
# changes will be lost when running "coder config-ssh".
#
# Last config-ssh options:
# :hostname-suffix=coder
#
Host coder.*
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
ProxyCommand <coder> --global-config <config> ssh --stdio --ssh-host-prefix coder. %h
Host *.coder
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
Match host *.coder !exec "<coder> connect exists %h"
ProxyCommand <coder> --global-config <config> ssh --stdio --hostname-suffix coder %h
# ------------END-CODER------------
```
</details>
<details>
<summary>diff wildcard → --no-wildcard</summary>
```diff
8a9
> # :no-wildcard=true
10c11
< Host coder.*
---
> Host coder.myworkspace
17c18
< Host *.coder
---
> Host coder.myworkspace2
21a23
> ProxyCommand <coder> ssh --stdio --ssh-host-prefix coder. %h
23c25,31
< Match host *.coder !exec "<coder> connect exists %h"
---
> Host myworkspace.coder
> ConnectTimeout=0
> StrictHostKeyChecking=no
> UserKnownHostsFile=/dev/null
> LogLevel ERROR
>
> Match host myworkspace.coder !exec "<coder> connect exists %h"
```
</details>
Closes https://github.com/coder/coder/issues/17153 (Phase 1: CLI flag)
- Adds server-side and client-side validation for
CODER_CONFIGSSH_HOSTNAME_SUFFIX and CODER_SSH_CONFIG_OPTIONS.
- **Server-side breaking change:** invalid values for either of these will cause `coderd` to exit with an error.
- Client-side: `coder config-ssh` will exit with an error if it detects invalid config.
- Adds tests for the above
Local smoke-testing: ran `develop.sh --env-file <path to an env file
containing badness>`. Validated that server startup failed as expected.
> 🤖 Generated by Coder Agents with supervision from a human.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Fixes all our Go file imports to match the preferred spec that we've _mostly_ been using. For example:
```
import (
"context"
"time"
"github.com/prometheus/client_golang/prometheus"
"golang.org/x/xerrors"
"gopkg.in/natefinch/lumberjack.v2"
"cdr.dev/slog/v3"
"github.com/coder/coder/v2/codersdk/agentsdk"
"github.com/coder/serpent"
)
```
3 groups: standard library, 3rd partly libs, Coder libs.
This PR makes the change across the codebase. The PR in the stack above modifies our formatting to maintain this state of affairs, and is a separate PR so it's possible to review that one in detail.
Refactors the CLI to create the `*codersdk.Client` in the handlers. This is groundwork for changing the `rootCmd.InitClient()` to use the new `ClientOption`s.
It also improves variable locality, scoping the Client to the handler. This makes misuse less likely and reduces the memory allocations to just the command being executed, rather than allocating a Client for every command regardless of whether it is executed.
fixes#18199
Corrects handling of paths with spaces in the `Match !exec` clause we
use to determine whether Coder Connect is running. This is handled
differently than the ProxyCommand, so we have a different escape
routine, which also varies by OS.
On Windows, we resort to a pretty gnarly hack, but it does work and I
feel the only other option would be to reduce functionality such that we
could not detect the Coder Connect state.
Refactor the workspace SSH command syntax across the project to use the
"workspace.coder" format instead of "coder.workspace". This standardizes
the SSH host entries for better consistency and clarity.
This is a follow-up from #17445 and recommends using the suffix-based
format for all new Coder versions.
<img width="418" alt="image"
src="https://github.com/user-attachments/assets/3893f840-9ce1-4803-a013-736068feb328"
/>
fixes#16828
With all the recent changes, I believe it is now safe to change the Call to Action for `config-ssh` to use the hostname suffix rather than prefix if it was set.
relates to #16828
Changes SSH config so that suffixes only match if Coder Connect is not running / available. This means that we will use the existing Coder Connect tunnel if it is available, rather than creating a new tunnel via `coder ssh --stdio`.
Adds a new hidden subcommand `coder connect exists <hostname>` that checks if the name exists via Coder Connect. This will be used in SSH config to match only if Coder Connect is unavailable for the hostname in question, so that the SSH client will directly dial the workspace over an existing Coder Connect tunnel.
Also refactors the way we inject a test DNS resolver into the lookup functions so that we can test from outside the `workspacesdk` package.
Wires up `config-ssh` command to use a hostname suffix if configured.
part of: #16828
e.g. `coder config-ssh --hostname-suffix spiketest` gives:
```
# ------------START-CODER-----------
# This section is managed by coder. DO NOT EDIT.
#
# You should not hand-edit this section unless you are removing it, all
# changes will be lost when running "coder config-ssh".
#
# Last config-ssh options:
# :hostname-suffix=spiketest
#
Host coder.* *.spiketest
ConnectTimeout=0
StrictHostKeyChecking=no
UserKnownHostsFile=/dev/null
LogLevel ERROR
ProxyCommand /home/coder/repos/coder/build/coder_config_ssh --global-config /home/coder/.config/coderv2 ssh --stdio --ssh-host-prefix coder. --hostname-suffix spiketest %h
# ------------END-CODER------------
```
Adds `hostname-suffix` as a Config SSH option that we get from Coderd, and also accept via a CLI flag.
It doesn't actually do anything with this value --- that's for PRs up the stack, since we need the `coder ssh` command to be updated to understand the suffix first.
- Update go.mod to use Go 1.24.1
- Update GitHub Actions setup-go action to use Go 1.24.1
- Fix linting issues with golangci-lint by:
- Updating to golangci-lint v1.57.1 (more compatible with Go 1.24.1)
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <claude@anthropic.com>
The experimental functions in `golang.org/x/exp/slices` are now
available in the standard library since Go 1.21.
Reference: https://go.dev/doc/go1.21#slices
Signed-off-by: Eng Zer Jun <engzerjun@gmail.com>
Rather than create a separate `Host` entry for every workspace,
configure a wildcard such as `coder.*` which can accomodate all of a
user's workspaces.
Depends on #16088.
* chore: add /v2 to import module path
go mod requires semantic versioning with versions greater than 1.x
This was a mechanical update by running:
```
go install github.com/marwan-at-work/mod/cmd/mod@latest
mod upgrade
```
Migrate generated files to import /v2
* Fix gen
* feat: Use Tailscale networking by default
Removal of WebRTC code will happen in another PR, but it
felt dangerious to default and remove in a single commit.
Ideally, we can release this version and collect final
thoughts and feedback before a full commitment.
* Remove UNIX forwarding
Tailscale doesn't support this, and adding support
for it shouldn't block our rollout. Customers can
always forward over SSH.
* Update cli/portforward_test.go
Co-authored-by: Dean Sheather <dean@deansheather.com>
Co-authored-by: Dean Sheather <dean@deansheather.com>
* fix: Use smarter quoting for ProxyCommand in config-ssh
This change takes better into account how OpenSSH executes
`ProxyCommand`s and applies quoting accordingly.
This supercedes #3664, which was reverted.
Fixes#2853
* fix: Ensure `~/.ssh` directory exists