Monitoring Your Coder Deployment with Vigilmon

Coder turns any cloud VM or Kubernetes cluster into a fleet of remote development environments. Developers open their IDE, connect to a workspace, and never think about laptop specs again — but only when Coder itself is healthy.

When Coder's web UI is unreachable, provisioners stall, or workspace agents lose connectivity, your whole engineering team loses their dev environments simultaneously. That's the opposite of a localised outage. External monitoring that catches these problems before developers hit them is essential.

This tutorial covers:

• The /healthz endpoint and what it tells you
• HTTP uptime monitoring with Vigilmon
• Workspace provisioner health
• Code-server agent connectivity
• SSL certificate alerts

Step 1: Verify the Coder health endpoint

Coder exposes a built-in health endpoint at /healthz. It requires no authentication and returns a JSON object summarising subsystem health:

curl https://coder.yourdomain.com/healthz

A healthy response looks like:

{
  "time": "2024-01-15T10:30:00Z",
  "healthy": true,
  "severity": "ok",
  "coder_version": "2.x.x",
  "access_url": { "healthy": true },
  "database": { "healthy": true },
  "derp": { "healthy": true },
  "websocket": { "healthy": true },
  "workspace_proxy": { "healthy": true }
}

When any subsystem is unhealthy, healthy flips to false and severity changes to warning or error. The subsystem-level detail tells you whether it's the database, the DERP relay, or access URL configuration that's broken.

Point your primary monitor at this endpoint — it's designed exactly for external health checks.

Step 2: Set up HTTP monitoring in Vigilmon

1. Sign up at vigilmon.online
2. Click New Monitor → HTTP
3. Enter https://coder.yourdomain.com/healthz
4. Set check interval: 1 minute (paid) or 5 minutes (free)
5. Under Response validation, set expected status to 200 and add a keyword match for "healthy":true
6. Save

The keyword match is important: Coder returns HTTP 200 even when degraded, but the JSON body will contain "healthy":false. A keyword check catches degraded states that a status-code-only check would miss.

Add a second monitor for the web UI itself:

• URL: https://coder.yourdomain.com/login
• Keyword match: Sign in to Coder (or whatever text appears on your login page)

This catches the case where /healthz passes but the frontend is broken.

Step 3: Monitor workspace provisioner health

Coder uses Terraform-based provisioners to create and destroy workspaces. If provisioners go offline, workspace creation fails silently from a user's perspective — they just see "pending" forever.

Coder exposes provisioner daemon status in the admin API. You can create a lightweight health endpoint using a cron job or a small script that polls the API and exposes a simple HTTP status:

#!/bin/bash
# /usr/local/bin/coder-provisioner-health
# Runs as a cron job every minute, writes result to a small HTTP server

CODER_URL="https://coder.yourdomain.com"
TOKEN="${CODER_API_TOKEN}"

result=$(curl -s -H "Coder-Session-Token: $TOKEN" \
  "$CODER_URL/api/v2/provisionerdaemons" | \
  jq '.[] | select(.status == "idle" or .status == "busy") | .id' | \
  wc -l)

if [ "$result" -gt 0 ]; then
  echo "healthy: $result provisioner(s) available"
  exit 0
else
  echo "unhealthy: no provisioners online"
  exit 1
fi

A simpler approach: use Vigilmon's heartbeat monitor. Configure your Coder provisioner host to ping a heartbeat URL after each successful provisioning job. If workspaces stop being created (or destroyed), the heartbeat stops arriving and Vigilmon alerts you.

In Vigilmon:

1. Click New Monitor → Heartbeat
2. Set expected interval to match your busiest provisioning window (e.g., 5 minutes during business hours)
3. Copy the ping URL
4. Add the ping call to your provisioner health check script

Step 4: Monitor code-server agent connectivity

Each Coder workspace runs an agent (the coder agent process) that proxies IDE connections. If the agent loses its connection to the Coder control plane, the workspace appears online but the developer's VS Code or JetBrains session freezes.

Monitor agent connectivity by checking the workspace status API from outside:

# Check that a known long-running workspace reports "running" agent status
curl -s -H "Coder-Session-Token: $TOKEN" \
  "https://coder.yourdomain.com/api/v2/workspaces?q=owner:me" | \
  jq '.workspaces[] | {name: .name, agent_status: .latest_build.resources[].agents[]?.status}'

For production monitoring, create a dedicated "canary" workspace — a minimal workspace template that starts quickly and stays running. Monitor it with a heartbeat: the workspace's startup script pings Vigilmon, confirming both provisioner success and agent connectivity in one check.

# In your canary workspace startup script (main.tf)
curl -fsS "${VIGILMON_HEARTBEAT_URL}" > /dev/null 2>&1 || true

Step 5: SSL certificate monitoring

Coder's browser-based IDE (and agent WebSocket connections) break immediately on certificate expiry — developers get a security error before they can even connect. Add an SSL certificate monitor to catch expiry before it happens.

In Vigilmon:

1. Go to New Monitor → SSL Certificate
2. Enter coder.yourdomain.com
3. Set alert threshold: 30 days before expiry (Coder's agent connections need extra buffer)
4. Save

If you expose Coder over multiple domains (e.g., *.coder.yourdomain.com for wildcard workspace URLs), add a certificate monitor for each:

coder.yourdomain.com          # main UI
*.coder.yourdomain.com        # workspace subdomains
coder-wss.yourdomain.com      # WebSocket relay if separate

Step 6: Alerts via Slack

In Vigilmon, go to Notifications → New Channel → Slack and paste your Slack incoming webhook URL.

Enable the Slack channel on your Coder monitors. When /healthz returns a degraded state, Vigilmon sends:

🔴 DOWN: coder.yourdomain.com/healthz
Keyword "healthy":true not found in response
Detected from: EU-West, US-East
3 minutes ago

Configure alert routing so Coder alerts go to your #platform-oncall channel rather than a general alerts channel — developers will ping that channel when their workspaces stop working, and you want the oncall engineer to have context before the first message arrives.

Step 7: Status page

Create a status page so your team can self-diagnose before filing tickets:

1. Go to Status Pages → New Status Page in Vigilmon
2. Add all your Coder monitors: web UI, /healthz, SSL certificate
3. Name it something like "Coder Development Platform"
4. Copy the public URL and post it in your engineering Slack channel topic

When a developer messages "Coder is broken," the first response is "check the status page" — which saves you 10 minutes of repeated diagnostics on every incident.

What you've built

| What | How | |------|-----| | Health endpoint monitoring | Vigilmon HTTP monitor → /healthz with keyword check | | Web UI availability | HTTP monitor → /login with keyword check | | Provisioner health | Heartbeat monitor via canary provisioning job | | Agent connectivity | Canary workspace heartbeat on startup | | SSL certificate alerts | Vigilmon SSL monitor, 30-day threshold | | Slack alerts | Vigilmon Slack notification channel | | Team status page | Vigilmon public status page |

Coder removes laptop constraints for your engineers. Vigilmon removes the constraint of finding out about Coder problems from developers, not your monitoring stack.

Next steps

• Add response time monitoring to catch slow workspace creation before it reaches the timeout threshold
• Create separate monitors per Coder region if you run multi-region deployments
• Use Vigilmon's incident history to correlate Coder outages with upstream provider incidents (cloud VM availability, Kubernetes node issues)
• Set tighter alert windows for the provisioner heartbeat during business hours and looser ones overnight

Get started free at vigilmon.online.