Problem Description

The current connection experience for external IDEs configured via coder_app with URLs like zed://ssh:myworkspace.coder lacks necessary setup guidance. Users only see a basic button to open the IDE, with no information about prerequisites like:

• Installing and configuring the Coder CLI (coder config-ssh)
• Using Coder Desktop with Coder Connect

This results in confusion, failed connections, and a poor user experience for first-time users.

Additionally, there is no way for template authors to control when a more guided connection experience is shown explicitly.

Desired Solution

Introduce a new optional property on coder_app resources to enable the improved, guided connection experience:

resource "coder_app" "my-app" {
  ...
  url               = "zed://ssh:myworkspace.coder"
  connection_helper = true
  external          = true
  ...
}

When connection_helper = true is set:

• The UI displays:
  • A clear explanation of connection options (Coder CLI or Coder Desktop)
  • Download links for required tools
  • Step-by-step instructions for setup
  • CLI command examples (e.g., coder config-ssh)
  • Action button to launch the IDE
• If connection_helper is omitted or set to false, current behavior (basic launch button only) is preserved.

Implementation Requirements

• Configuration

  • Add a new connection_helper boolean property to the coder_app resource
  • Default to false to maintain backward compatibility

• UI

  • When connection_helper = true:

    • Show enhanced, guided connection UI with:

      • Connection method explanation (Coder CLI & Coder Desktop)
      • Download links for required tools
      • CLI instructions
      • IDE launch button
      • Optional contextual tips for new users

• Documentation

  • Update coder_app resource documentation to describe connection_helper
  • Add user documentation for the improved connection flow

Related Issues

• Add Optional Tooltip Support for coder_app Buttons #18431