Files
coder/cli/testdata/coder_config-ssh_--help.golden
Atif Ali fb6d287528 fix: write agent host entries with config-ssh --no-wildcard (#31192)
`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. 🧑💻
2026-11-05 10:01:33 +05:00

67 lines
2.5 KiB
Plaintext

coder v0.0.0-devel
USAGE:
coder config-ssh [flags]
Add an SSH Host entry for your workspaces "ssh workspace.coder"
- You can use -o (or --ssh-option) so set SSH options to be used for all
your
workspaces:
$ coder config-ssh -o ForwardAgent=yes
- You can use --dry-run (or -n) to see the changes that would be made:
$ coder config-ssh --dry-run
OPTIONS:
--coder-binary-path string, $CODER_SSH_CONFIG_BINARY_PATH
Optionally specify the absolute path to the coder binary used in
ProxyCommand. By default, the binary invoking this command ('config
ssh') is used.
--disable-autostart bool, $CODER_CONFIGSSH_DISABLE_AUTOSTART (default: false)
Disable starting the workspace automatically when connecting via SSH.
-n, --dry-run bool, $CODER_SSH_DRY_RUN
Perform a trial run with no changes made, showing a diff at the end.
--force-unix-filepaths bool, $CODER_CONFIGSSH_UNIX_FILEPATHS
By default, 'config-ssh' uses the os path separator when writing the
ssh config. This might be an issue in Windows machine that use a
unix-like shell. This flag forces the use of unix file paths (the
forward slash '/').
--hostname-suffix string, $CODER_CONFIGSSH_HOSTNAME_SUFFIX
Override the default hostname suffix.
--no-wildcard bool, $CODER_CONFIGSSH_NO_WILDCARD (default: false)
Generate an individual host entry for each workspace and its known
agents instead of a wildcard host block. This allows third-party tools
and SSH clients to discover workspaces by reading the config file.
--ssh-config-file string, $CODER_SSH_CONFIG_FILE (default: ~/.ssh/config)
Specifies the path to an SSH config.
--ssh-host-prefix string, $CODER_CONFIGSSH_SSH_HOST_PREFIX
Override the default host prefix.
-o, --ssh-option string-array, $CODER_SSH_CONFIG_OPTS
Specifies additional SSH options to embed in each host stanza.
--use-previous-options bool, $CODER_SSH_USE_PREVIOUS_OPTIONS
Specifies whether or not to keep options from previous run of
config-ssh.
--wait yes|no|auto, $CODER_CONFIGSSH_WAIT (default: auto)
Specifies whether or not to wait for the startup script to finish
executing. Auto means that the agent startup script behavior
configured in the workspace template is used.
-y, --yes bool
Bypass confirmation prompts.
———
Run `coder --help` for a list of global options.