`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. 🧑💻
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)
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"
/>
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.
This change reduces the CPU consumption of --help by ~50%.
Also, this change removes ANSI escape codes from our golden files. I
don't think those were worth the inability to parallelize golden file tests and
global state fragility.
This change will improve over CLI performance and "snappiness" as well as
substantially reduce our test times. Preliminary benchmarks show
`coder server --help` times cut from 300ms to 120ms on my dogfood
instance.
The inefficiency of lipgloss disproportionately impacts our system, as all help
text for every command is generated whenever any command is invoked.
The `pretty` API could clean up a lot of the code (e.g., by replacing
complex string concatenations with Printf), but this commit is too
expansive as is so that work will be done in a follow up.