Monitoring ttyd Web Terminal with Vigilmon

ttyd turns any command into a browser-accessible terminal in one line — no SSH client needed, no port forwarding, just a URL. But that simplicity cuts both ways: when the tiny ttyd process dies, there's no systemd notify, no health page, no alert. Vigilmon gives you that safety net: HTTP availability checks, TCP port probes, authentication enforcement verification, SSL certificate monitoring, and heartbeat confirmation that the backing shell actually spawned.

What You'll Set Up

• HTTP uptime monitor for the ttyd web terminal interface (port 7681)
• TCP probe confirming the libwebsockets server is accepting connections
• Authentication enforcement check (401 monitor) for credential-protected deployments
• SSL certificate expiry alert for HTTPS ttyd deployments
• Heartbeat monitor confirming the backing shell process starts successfully

Prerequisites

• ttyd installed and running (port 7681 by default)
• A domain or IP address accessible from the internet (or from Vigilmon's probe network)
• A free Vigilmon account

Step 1: Monitor the ttyd Web Interface (HTTP)

ttyd serves the xterm.js web terminal frontend over HTTP on port 7681. A successful GET / returns a 200 OK with the terminal HTML, confirming the C process is running and libwebsockets is serving requests.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: http://your-server:7681/ (or https://your-terminal.domain.com/ if behind a reverse proxy).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If ttyd is behind nginx or Caddy for SSL termination, use the proxied HTTPS URL instead of the raw port. The HTTP check confirms the entire serving stack — ttyd process, libwebsockets listener, and (if proxied) the reverse proxy — is healthy.

Step 2: TCP Port Probe for the WebSocket Listener

ttyd serves both HTTP and WebSocket traffic on the same port (7681 by default). A TCP connection check is a lightweight way to confirm the port is open and accepting connections, independent of the HTTP layer.

1. Click Add Monitor → TCP Port.
2. Enter your server's hostname or IP.
3. Set Port to 7681.
4. Set Check interval to 1 minute.
5. Click Save.

This probe catches cases where the port is bound but libwebsockets has stopped accepting new connections — a condition that sometimes appears under high load or after a partial crash before the process fully exits.

Step 3: Authentication Enforcement Check

If ttyd is started with the --credential username:password flag, unauthenticated requests to GET / should return 401 Unauthorized. Monitoring for this 401 confirms two things at once: ttyd is running, and HTTP basic authentication is still enforced.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-server:7681/.
3. Set Expected HTTP status to 401.
4. Set Check interval to 1 minute.
5. Click Save.

If ttyd is running without --credential (auth disabled), use a 200 monitor from Step 1 instead and skip this step. Do not add both a 200 and a 401 monitor for the same endpoint — pick the one that matches your deployment.

Losing a 401 response (e.g., getting 200 instead) could mean ttyd was restarted without the --credential flag, silently removing authentication from your terminal.

Step 4: SSL Certificate Alerts for HTTPS Deployments

ttyd supports native TLS via --ssl --ssl-cert /path/to/cert.pem --ssl-key /path/to/key.pem, or you can terminate SSL at nginx or Caddy. Either way, a certificate expiry would lock everyone out of the terminal the moment browsers reject the cert.

Enable SSL monitoring on the HTTP monitor created in Step 1 (or Step 3):

1. Open the monitor for your ttyd URL.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

For native ttyd TLS, the monitored URL must use https:// pointing at port 7681 (or whatever port ttyd is listening on with --port). For reverse-proxied TLS, use the HTTPS domain URL.

A 21-day window gives you three renewal cycles before expiry with a weekly-check cadence, and enough time to diagnose certificate manager failures and renew manually if needed.

Step 5: Heartbeat Monitoring for the Backing Shell Process

ttyd executes a backing command — typically bash, zsh, or tmux. The HTTP interface can return 200 even if the backing command fails to spawn for new connections (e.g., the shell binary is missing or the system is out of file descriptors). A Vigilmon heartbeat confirms end-to-end: ttyd started, the backing command spawned, and the process is healthy.

Create the heartbeat monitor

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match how often your wrapper runs (e.g., 5 minutes).
3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/YOUR_TOKEN.

Create a wrapper script

#!/bin/bash
# /usr/local/bin/ttyd-health-check.sh

# Verify ttyd is listening
if curl -sf --max-time 3 http://localhost:7681/ > /dev/null; then
    # Signal to Vigilmon that the terminal service is healthy
    curl -sf https://vigilmon.online/heartbeat/YOUR_TOKEN > /dev/null
fi

Schedule the wrapper

# Add to crontab: crontab -e
*/5 * * * * /usr/local/bin/ttyd-health-check.sh

If ttyd is running with --once (single-connection mode for demos or pair sessions), use the wrapper to verify each session starts and pings the heartbeat on success.

If the heartbeat stops arriving, Vigilmon alerts after the expected interval — catching crashes that the HTTP monitor alone might miss between check intervals.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook.
2. On the HTTP monitor, set Consecutive failures before alert to 2 — a single transient TCP hiccup shouldn't page you.
3. On the TCP probe and auth enforcement monitors, set Consecutive failures before alert to 1 — these are slower to recover and worth alerting faster.

If you restart ttyd frequently (e.g., for config changes), use Maintenance windows in Vigilmon to suppress alerts during planned restarts:

# Suppress alerts for 3 minutes while restarting ttyd
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "YOUR_MONITOR_ID", "duration_minutes": 3}'

systemctl restart ttyd

# Window expires automatically

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP uptime | http://your-server:7681/ | ttyd process crash, libwebsockets failure | | TCP port probe | Port 7681 | Port closed, listener not accepting | | Auth enforcement | 401 on GET / | Auth stripped on restart, ttyd config changed | | SSL certificate | ttyd HTTPS domain | Certificate expiry blocking browser access | | Cron heartbeat | Heartbeat URL | Backing shell spawn failure, resource exhaustion |

ttyd's single-binary simplicity is its greatest feature — and its monitoring blind spot. With Vigilmon watching the HTTP interface, TCP port, authentication enforcement, SSL certificate, and shell heartbeat, you get alerting coverage that matches how many different things can quietly break in a web terminal deployment.