tutorial

How to Monitor DevPod with Vigilmon (Provider Health, Workspace Latency + Alerts)

DevPod is an open-source development environment manager that gives you Codespaces-like workspaces on your own infrastructure — local Docker, Kubernetes, AWS...

DevPod is an open-source development environment manager that gives you Codespaces-like workspaces on your own infrastructure — local Docker, Kubernetes, AWS, GCP, Azure, or any SSH-accessible machine. Teams use it to eliminate "works on my machine" problems by standardising environments in .devcontainer.json files that run identically everywhere.

But DevPod's distributed nature means monitoring becomes complicated. A workspace that looks healthy in the CLI might be completely unreachable because of a misconfigured provider, a failed SSH tunnel, or a stalled dev container build. In this tutorial you'll set up comprehensive external monitoring for your DevPod infrastructure using Vigilmon — free tier, no credit card required.

Why DevPod workspaces need external monitoring

DevPod is a client-side tool. The devpod status command tells you what the DevPod daemon thinks is true — not what your developers actually experience when they try to connect.

The failure modes that external monitoring catches but the DevPod daemon misses:

  • Provider endpoint unreachable — your Kubernetes API server, AWS endpoint, or SSH host goes down; DevPod reports the workspace as running but connections fail
  • SSH tunnel broken — the container is alive but the SSH tunnel that developers use to connect has collapsed; IDE remote sessions hang silently
  • Dev container build stalled — a workspace provisioning request gets stuck mid-build because a base image layer can't be pulled or a Dockerfile command hangs
  • Proxy/gateway timeout — if you run a central DevPod proxy or gateway server, it may become overloaded or crash, blocking all workspace creation requests
  • Health endpoint silent failure — your workspace's web service is running on a mapped port but stops responding; developers get errors only when they try to use it

External monitoring from a neutral vantage point catches all of these because it doesn't trust what DevPod's daemon says — it actually makes network connections and measures what users experience.

What you'll need

  • DevPod installed and at least one provider configured (devpod provider list)
  • Workspaces exposing HTTP services on mapped ports (most web dev workflows do this)
  • A free Vigilmon account — sign up takes 30 seconds

Step 1: Expose a health endpoint from your DevPod workspace

Most DevPod workspaces run web servers during development. The first step is making sure your workspace exposes a health endpoint that Vigilmon can probe.

If you're using a .devcontainer.json with forwardPorts, your services are already accessible on the host or via the provider's network. Add a lightweight /health route to your app if it doesn't have one:

// Node.js/Express example — add to your dev server
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    workspace: process.env.DEVPOD_WORKSPACE_ID || 'unknown',
    timestamp: new Date().toISOString()
  });
});

# FastAPI/Python example
@app.get("/health")
async def health():
    return {
        "status": "ok",
        "workspace": os.getenv("DEVPOD_WORKSPACE_ID", "unknown"),
        "timestamp": datetime.utcnow().isoformat()
    }

For a Kubernetes provider, confirm port forwarding is working:

# Check your workspace's forwarded ports
devpod ssh my-workspace -- curl -s localhost:3000/health
# {"status":"ok","workspace":"my-workspace","timestamp":"2024-01-15T10:23:00Z"}

For a Docker provider with a mapped port, test directly:

# List running workspace containers
docker ps --filter "label=devpod.sh/workspace" --format "table {{.Names}}\t{{.Ports}}"

# Test the health endpoint
curl http://localhost:3000/health

Step 2: Monitor provider health via Vigilmon HTTP checks

DevPod providers expose management APIs or endpoints that you can monitor externally. The approach differs by provider type.

Kubernetes provider

If your Kubernetes provider is a remote cluster, monitor the API server's health endpoint:

# Get your cluster's API server address
kubectl cluster-info
# Kubernetes control plane is running at https://k8s.example.com:6443

In Vigilmon:

  1. Go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. URL: https://k8s.example.com:6443/healthz
  4. Interval: 1 minute
  5. Expected status code: 200
  6. Save the monitor

Kubernetes API server /healthz is an unauthenticated endpoint that returns ok when the cluster control plane is healthy.

SSH provider (remote VM)

If your provider is an SSH-accessible VM, the most reliable proxy for SSH health is whether a TCP connection succeeds on port 22:

  1. Go to Monitors → New Monitor
  2. Choose TCP Port
  3. Host: dev-vm.example.com, Port: 22
  4. Save the monitor

TCP port 22 reachability is a prerequisite for any DevPod SSH-provider workspace to function.

Docker/local provider

If you use DevPod's local Docker provider, monitor a Docker daemon health API exposed via a TCP socket. You can wrap it with a small proxy:

# Expose Docker health as HTTP on port 2376 with socat or a simple proxy
# Or use Docker's built-in TCP socket if enabled
curl --unix-socket /var/run/docker.sock http://localhost/v1.41/_ping
# OK

For a publicly accessible host, use Vigilmon to monitor http://dev-host.example.com:2376/_ping.

Step 3: Monitor workspace provisioning latency

Workspace provisioning latency is how long it takes from devpod up to a usable workspace. When this spikes above a reasonable threshold (typically 2–5 minutes for a warm workspace), developer productivity tanks.

You can track provisioning with a timed probe script that runs as a Vigilmon heartbeat:

#!/usr/bin/env bash
# devpod-provision-probe.sh — run every 10 minutes from a cron job or CI runner

WORKSPACE="probe-workspace-$(date +%s)"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID"
MAX_SECONDS=300  # 5-minute SLA

start=$(date +%s)
devpod up "$WORKSPACE" --provider docker --source git:https://github.com/yourorg/probe-repo.git 2>&1

if [ $? -ne 0 ]; then
  echo "Workspace provisioning failed"
  exit 1
fi

end=$(date +%s)
elapsed=$(( end - start ))

if [ $elapsed -gt $MAX_SECONDS ]; then
  echo "Provisioning took ${elapsed}s — exceeds ${MAX_SECONDS}s SLA"
  exit 1
fi

# Send heartbeat to Vigilmon — signals that provisioning completed within SLA
curl -s "$HEARTBEAT_URL" -d "elapsed_seconds=$elapsed"

# Clean up the probe workspace
devpod delete "$WORKSPACE" --force

Set up a cron job to run this every 10–15 minutes:

*/15 * * * * /opt/scripts/devpod-provision-probe.sh >> /var/log/devpod-probe.log 2>&1

In Vigilmon, create a Heartbeat monitor with a 20-minute grace period. If the cron job stops sending heartbeats — because provisioning failed, stalled, or the host is down — you'll get an alert.

Step 4: Monitor dev container build status

Dev container builds are the most common cause of workspace provisioning failures. A single bad layer in your devcontainer.json can stall every new workspace indefinitely.

Track build failures by monitoring a build probe endpoint:

#!/usr/bin/env bash
# Check if the last devpod build succeeded and is within acceptable age
LAST_BUILD_LOG="/var/log/devpod/last-build.log"
MAX_AGE_SECONDS=3600  # Alert if build hasn't succeeded in the last hour

if [ ! -f "$LAST_BUILD_LOG" ]; then
  echo "No build log found"
  exit 1
fi

last_build_time=$(stat -c %Y "$LAST_BUILD_LOG")
now=$(date +%s)
age=$(( now - last_build_time ))

if [ $age -gt $MAX_AGE_SECONDS ]; then
  echo "Last successful build was ${age}s ago — exceeds ${MAX_AGE_SECONDS}s threshold"
  exit 1
fi

# Check for errors in the last build log
if grep -q "ERROR\|failed\|exit code" "$LAST_BUILD_LOG"; then
  echo "Build log contains errors"
  exit 1
fi

curl -s "https://vigilmon.online/heartbeat/YOUR_BUILD_HEARTBEAT_ID"

Alternatively, expose a small build-status API alongside your workspace:

// build-status-server.js
const express = require('express');
const app = express();
const fs = require('fs');

app.get('/build-status', (req, res) => {
  const buildLog = '/tmp/devpod-build.log';
  if (!fs.existsSync(buildLog)) {
    return res.status(503).json({ status: 'no_build_log' });
  }
  const content = fs.readFileSync(buildLog, 'utf8');
  const success = !content.includes('ERROR') && !content.includes('failed');
  res.status(success ? 200 : 503).json({
    status: success ? 'ok' : 'build_failed',
    last_checked: new Date().toISOString()
  });
});

app.listen(9090);

Monitor http://dev-host.example.com:9090/build-status in Vigilmon with expected status 200.

Step 5: Configure SSH connectivity alerts

SSH connectivity is the most critical layer for DevPod workspaces — if SSH is broken, nothing works, regardless of what the container status shows.

Set up multiple layers of SSH connectivity checks:

TCP-layer check (port reachability)

  1. Go to Monitors → New Monitor
  2. Choose TCP Port
  3. Host and port for your DevPod provider VM or Kubernetes node
  4. Interval: 1 minute
  5. Save

Application-layer check (service behind SSH)

After confirming TCP works, check that services behind the SSH tunnel are reachable. If you run VS Code's remote extension server or a similar tool, it exposes a status endpoint:

  1. Go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. URL: http://workspace-proxy.example.com:2222/status (or whatever your workspace gateway exposes)
  4. Expected status: 200
  5. Save

Alert configuration

In Vigilmon, go to Alert Channels and add:

  • Email — for on-call notifications to the platform team
  • Webhook — to post alerts into your team's Slack #devops-alerts channel

Example Slack webhook payload format that Vigilmon sends:

{
  "monitor_name": "devpod-ssh-provider-vm",
  "status": "down",
  "url": "tcp://dev-vm.example.com:22",
  "started_at": "2024-01-15T10:23:00Z",
  "duration_seconds": 45
}

Configure your Slack app to format this into a clear #devops-alerts message with the workspace name and impact.

Putting it all together

Here's the full monitoring matrix for a DevPod deployment:

| Monitor | Type | What it catches | |---------|------|-----------------| | https://k8s.example.com:6443/healthz | HTTP | Kubernetes provider control plane health | | dev-vm.example.com:22 | TCP | SSH provider VM reachability | | Workspace provisioning heartbeat | Heartbeat | Provisioning latency SLA breaches | | Dev container build heartbeat | Heartbeat | Build failures and stalled containers | | http://workspace.example.com:3000/health | HTTP | Running workspace service health | | http://workspace-proxy.example.com:2222/status | HTTP | Workspace gateway / proxy health |

Set check intervals to 1 minute for TCP and HTTP monitors, and 15–20 minute grace windows for heartbeats.

What's next

  • Multi-provider coverage — if your team uses both Docker and Kubernetes providers, set up separate monitors for each so a provider-specific failure doesn't look like a global DevPod outage
  • SSL monitoring — if your workspace gateway uses TLS, Vigilmon monitors the certificate expiry and alerts you before it lapses, which would break all SSH tunnels
  • Status page for your platform team — publish a Vigilmon status page grouping all DevPod monitors so platform engineers can see overall workspace health at a glance

Get started free at vigilmon.online — no credit card, monitors start running in under a minute.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles