tutorial

Monitoring Kasm Workspaces with Vigilmon

Kasm Workspaces streams isolated Linux desktops and apps to any browser — but when the container platform goes down, nobody gets in. Here's how to monitor the Kasm API, web UI, image registry, and SSL certificates with Vigilmon.

Kasm Workspaces turns Docker containers into browser-native Linux desktops and isolated applications — security teams use it for browser isolation, enterprises for virtual desktop infrastructure, and developers for on-demand cloud workstations. All of it streams over WebRTC to an ordinary browser tab. But if the Kasm nginx proxy, Go API backend, or container image registry goes down, every streaming session dies and nobody can launch a new one. Vigilmon catches those failures before users do, monitoring the Kasm web UI, API health endpoint, Manager service, SSL certificate, and session image pool.

What You'll Set Up

  • HTTP monitor for the Kasm web UI (port 443 HTTPS)
  • API health check monitor at /api/__healthcheck
  • Kasm Manager availability check via /api/public/get_client_settings
  • SSL certificate expiry alert for the Kasm domain
  • Heartbeat monitor for the container image pool and Docker daemon

Prerequisites

  • Kasm Workspaces 1.14+ deployed and accessible over HTTPS
  • A valid SSL certificate on your Kasm domain
  • A free Vigilmon account

Step 1: Monitor the Kasm Web UI

The Kasm frontend is a React SPA served through the Kasm nginx reverse proxy on port 443. A 200 response confirms the proxy and static web application layer are healthy.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Kasm URL: https://kasm.yourdomain.com
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Under Keyword match, enter kasm to confirm the Kasm login page content is being served (not a fallback error page).
  7. Click Save.

This confirms the Kasm nginx proxy is running and the React application files are being served. A failure here means no user can reach the login page.

Step 2: Monitor the Kasm API Health Endpoint

Kasm exposes a dedicated health check endpoint for its Go API backend at /api/__healthcheck. A healthy response returns {"status": "ok"} — this confirms the backend services and internal health checks are passing.

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: https://kasm.yourdomain.com/api/__healthcheck
  3. Set Check interval to 1 minute.
  4. Set Expected HTTP status to 200.
  5. Under Response body contains, enter "status": "ok".
  6. Click Save.

You can test this manually:

curl -sk https://kasm.yourdomain.com/api/__healthcheck
# {"status": "ok"}

If this endpoint returns anything other than {"status": "ok"} — or times out — the Kasm API backend has a problem and users will not be able to authenticate or manage sessions.

Step 3: Monitor the Kasm Manager Service

The Kasm Manager process handles workspace session lifecycle and communicates with the database. The /api/public/get_client_settings endpoint is publicly accessible and returns workspace session configuration, confirming the Manager is running and the database connection is healthy.

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: https://kasm.yourdomain.com/api/public/get_client_settings
  3. Set Check interval to 2 minutes.
  4. Set Expected HTTP status to 200.
  5. Under Response body contains, enter response (the JSON response wraps settings in a response key).
  6. Click Save.

Test it:

curl -sk https://kasm.yourdomain.com/api/public/get_client_settings | python3 -m json.tool | head -5

A timeout or 5xx error here indicates the Kasm Manager process has crashed or the database is unreachable — users can still reach the login page but cannot launch or manage workspace sessions.

Step 4: SSL Certificate Alert for the Kasm Domain

Kasm requires HTTPS for WebRTC streaming — browsers block WebRTC on non-HTTPS origins. An expired SSL certificate does not just show a warning; it actively breaks desktop streaming for every user.

  1. Open the Kasm web UI monitor you created in Step 1.
  2. Enable Monitor SSL certificate under the SSL section.
  3. Set Alert when certificate expires in less than 21 days.
  4. Click Save.

If you use Let's Encrypt with auto-renewal via certbot or Caddy, a 21-day alert window gives you three weeks to investigate a renewal failure before the certificate actually expires. For Kasm's built-in self-signed certificate on custom installs, this alert flags when you need to replace it.

Step 5: Heartbeat Monitor for the Workspace Image Pool

Kasm launches new workspace sessions by spinning up Docker containers from workspace images. If the Docker daemon is unhealthy or the image registry is unreachable, image pulls fail and no new sessions can start — even though the API and web UI appear healthy.

Set up a Vigilmon heartbeat that pings the workspace images endpoint on a schedule:

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set the expected ping interval to 5 minutes.
  3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
  4. On the Kasm host, create a cron script at /usr/local/bin/kasm-image-pool-check.sh:
#!/bin/bash
# Check that the Kasm workspace image pool is accessible
KASM_API="https://localhost/api/public/workspace_images"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"

response=$(curl -sk -o /dev/null -w "%{http_code}" "$KASM_API")
if [ "$response" = "200" ]; then
  curl -s "$HEARTBEAT_URL" > /dev/null
fi
  1. Make it executable and add a cron entry:
chmod +x /usr/local/bin/kasm-image-pool-check.sh

# Add to root crontab
echo "*/5 * * * * /usr/local/bin/kasm-image-pool-check.sh" | crontab -

The /api/public/workspace_images endpoint returns the list of available workspace images, confirming the image registry and Docker daemon are accessible. If the cron script stops pinging — because the endpoint returns an error — Vigilmon alerts after 5 minutes of silence.

Step 6: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
  2. Set Consecutive failures before alert to 2 on the web UI and API monitors — Kasm restarts individual services automatically and a transient failure can resolve within 30 seconds.
  3. For the Manager and image pool monitors, set consecutive failures to 1 — these indicate deeper infrastructure problems that need immediate attention.

For high-availability Kasm deployments with multiple agent servers, add a monitor for each agent's API endpoint:

https://kasm-agent-1.yourdomain.com/api/__healthcheck
https://kasm-agent-2.yourdomain.com/api/__healthcheck

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://kasm.yourdomain.com | nginx proxy down, SPA not served | | API health | /api/__healthcheck | Kasm Go backend crash | | Manager service | /api/public/get_client_settings | Manager crash, database disconnect | | SSL certificate | Kasm domain | Certificate expiry breaking WebRTC | | Cron heartbeat | /api/public/workspace_images | Docker daemon down, image pool inaccessible |

Kasm Workspaces provides powerful browser-native desktop streaming — but that streaming chain has multiple moving parts: the nginx proxy, Go API, Manager process, Docker daemon, and image registry. With Vigilmon watching each layer independently, you know exactly which component failed when a streaming outage occurs, and you know about it before your users do.

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