We've received numerous issues about confusion with our getting started experience.

• Unable to connect to Docker workspaces #3292
• docker run / docker-compose up fail on postgres connection refused #3644
• Agent hangs on 'connecting' when deploying using local docker #3513
• Agent hangs on 'connecting' when deploying using code-server docker template #3514
• Failed to download coder agent when running docker #3402

The primary complaint is that our Docker experience doesn't explicitly state that dialing the host is required, and our web UI doesn't indicate an error; it just says "Connecting" forever.

I've also found it confusing to have numerous Docker examples because the user is trying to optimize for "does it work," not "is it featureful?"

Step 1. Separate example templates from quickstarts

We should have a single template for each unique infrastructure type. e.g.

• Virtual Machines on Azure
• Virtual Machines on Google Cloud
• Virtual Machines on Digital Ocean
• Containers on AWS ECS
• Containers on Docker
• Containers on Kubernetes

Examples can be more bespoke and have additional features like dotfiles, but quickstarts should be simple and straight-forward.

Step 2. Add a getting-started HTTP server to advertise workspace applications

Instead of installing code-server in every template (which can easily get outdated or maybe just not work if the prospect is air-gapped), we should have a default application in every quickstart that displays what the user can do next. Tailscale does this nicely:

This would be called "Get Started" and display as a normal workspace application, but when opened a screen like this might appear:

This looks brutal, but you get the point.

Step 3. Add a timeout parameter to the coder_agent resource

After the specified duration of inactivity, the UI and CLI would display that something wrong happened. Templates can define a debug_url parameter in their front-matter that can direct users to a help page.