Files
coder/docs/reference/cli/config-ssh.md
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

4.9 KiB
Generated

title, description
title description
`coder config-ssh` Add an SSH Host entry for your workspaces "ssh workspace.coder".

Add an SSH Host entry for your workspaces "ssh workspace.coder"

Usage

coder config-ssh [flags]

Description

  - 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

--ssh-config-file

Property Value
Type string
Environment $CODER_SSH_CONFIG_FILE
Default ~/.ssh/config

Specifies the path to an SSH config.

--coder-binary-path

Property Value
Type string
Environment $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.

-o, --ssh-option

Property Value
Type string-array
Environment $CODER_SSH_CONFIG_OPTS

Specifies additional SSH options to embed in each host stanza.

-n, --dry-run

Property Value
Type bool
Environment $CODER_SSH_DRY_RUN

Perform a trial run with no changes made, showing a diff at the end.

--use-previous-options

Property Value
Type bool
Environment $CODER_SSH_USE_PREVIOUS_OPTIONS

Specifies whether or not to keep options from previous run of config-ssh.

--ssh-host-prefix

Property Value
Type string
Environment $CODER_CONFIGSSH_SSH_HOST_PREFIX

Override the default host prefix.

--hostname-suffix

Property Value
Type string
Environment $CODER_CONFIGSSH_HOSTNAME_SUFFIX

Override the default hostname suffix.

--wait

Property Value
Type yes|no|auto
Environment $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.

--disable-autostart

Property Value
Type bool
Environment $CODER_CONFIGSSH_DISABLE_AUTOSTART
Default false

Disable starting the workspace automatically when connecting via SSH.

--no-wildcard

Property Value
Type bool
Environment $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.

--force-unix-filepaths

Property Value
Type bool
Environment $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 '/').

-y, --yes

Property Value
Type bool

Bypass confirmation prompts.