Files
Atif Ali ae6b1faea3 fix: make SSH connection hints consistent across CLI, dashboard and docs (#31188)
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. 🧑💻
2026-11-05 10:19:38 +05:00

116 lines
3.7 KiB
Go

package cli
import (
"fmt"
"sort"
"sync"
"time"
"github.com/google/uuid"
"golang.org/x/xerrors"
"github.com/coder/coder/v2/agent/agentcontainers"
"github.com/coder/coder/v2/cli/cliui"
"github.com/coder/coder/v2/codersdk"
"github.com/coder/serpent"
)
func (r *RootCmd) show() *serpent.Command {
var details bool
return &serpent.Command{
Use: "show <workspace>",
Short: "Display details of a workspace's resources and agents",
Options: serpent.OptionSet{
{
Flag: "details",
Description: "Show full error messages and additional details.",
Default: "false",
Value: serpent.BoolOf(&details),
},
},
Middleware: serpent.Chain(
serpent.RequireNArgs(1),
),
Handler: func(inv *serpent.Invocation) error {
client, err := r.InitClient(inv)
if err != nil {
return err
}
buildInfo, err := client.BuildInfo(inv.Context())
if err != nil {
return xerrors.Errorf("get server version: %w", err)
}
workspace, err := client.ResolveWorkspace(inv.Context(), inv.Args[0])
if err != nil {
return xerrors.Errorf("get workspace: %w", err)
}
// Keep the owner in suggested commands when needed, so they still
// resolve for workspaces owned by someone else.
workspaceName := workspace.Name
if suggestWithOwner(inv.Args[0], workspace) {
workspaceName = workspace.FullName()
}
options := cliui.WorkspaceResourcesOptions{
WorkspaceName: workspaceName,
ServerVersion: buildInfo.Version,
ShowDetails: details,
Title: fmt.Sprintf("%s/%s (%s since %s) %s:%s", workspace.OwnerName, workspace.Name, workspace.LatestBuild.Status, time.Since(workspace.LatestBuild.CreatedAt).Round(time.Second).String(), workspace.TemplateName, workspace.LatestBuild.TemplateVersionName),
}
if workspace.LatestBuild.Status == codersdk.WorkspaceStatusRunning {
// Get listening ports for each agent.
ports, devcontainers := fetchRuntimeResources(inv, client, workspace.LatestBuild.Resources...)
options.ListeningPorts = ports
options.Devcontainers = devcontainers
}
return cliui.WorkspaceResources(inv.Stdout, workspace.LatestBuild.Resources, options)
},
}
}
func fetchRuntimeResources(inv *serpent.Invocation, client *codersdk.Client, resources ...codersdk.WorkspaceResource) (map[uuid.UUID]codersdk.WorkspaceAgentListeningPortsResponse, map[uuid.UUID]codersdk.WorkspaceAgentListContainersResponse) {
ports := make(map[uuid.UUID]codersdk.WorkspaceAgentListeningPortsResponse)
devcontainers := make(map[uuid.UUID]codersdk.WorkspaceAgentListContainersResponse)
var wg sync.WaitGroup
var mu sync.Mutex
for _, res := range resources {
for _, agent := range res.Agents {
wg.Add(1)
go func() {
defer wg.Done()
lp, err := client.WorkspaceAgentListeningPorts(inv.Context(), agent.ID)
if err != nil {
cliui.Warnf(inv.Stderr, "Failed to get listening ports for agent %s: %v", agent.Name, err)
}
sort.Slice(lp.Ports, func(i, j int) bool {
return lp.Ports[i].Port < lp.Ports[j].Port
})
mu.Lock()
ports[agent.ID] = lp
mu.Unlock()
}()
if agent.ParentID.Valid {
continue
}
wg.Add(1)
go func() {
defer wg.Done()
dc, err := client.WorkspaceAgentListContainers(inv.Context(), agent.ID, map[string]string{
// Labels set by VSCode Remote Containers and @devcontainers/cli.
agentcontainers.DevcontainerConfigFileLabel: "",
agentcontainers.DevcontainerLocalFolderLabel: "",
})
if err != nil {
cliui.Warnf(inv.Stderr, "Failed to get devcontainers for agent %s: %v", agent.Name, err)
}
mu.Lock()
devcontainers[agent.ID] = dc
mu.Unlock()
}()
}
}
wg.Wait()
return ports, devcontainers
}