Monitoring chatwire

Health endpoints

GET /healthz

Basic alive check. Returns HTTP 200 when the web server is running.

{"ok": true, "version": "1778952714", "release": "1.14.0"}

Use this for Uptime Kuma, Healthchecks.io, or any HTTP monitor.

GET /api/heartbeat

Detailed health check including bridge liveness and last message timestamp.

{
  "ok": true,
  "ts": 1715900000.0,
  "bridge_alive": true,
  "last_heartbeat": 1715899998.0,
  "last_message_ts": "2026-05-16T14:30:00Z"
}

Field	Type	Description
ok	bool	Always true when the web server responds
ts	float	Current server unix timestamp
bridge_alive	bool	True if the bridge poll loop ran within the last 10 seconds
last_heartbeat	float or null	Unix timestamp of the last bridge poll iteration
last_message_ts	string or null	Timestamp of the most recent message in the mirror log

bridge_alive = false means the bridge process has stopped polling chat.db. Messages will not be relayed until it recovers. The web UI still works for viewing history.

Uptime Kuma setup

1. Add a new monitor: HTTP(s) - Keyword
2. URL: http://<your-mac-ip>:8723/healthz
3. Keyword: "ok"
4. Interval: 60 seconds
5. Retry: 3 times

For bridge-level monitoring (optional):

1. Add a second monitor: HTTP(s) - JSON Query
2. URL: http://<your-mac-ip>:8723/api/heartbeat
3. JSON Path: $.bridge_alive
4. Expected Value: true
5. Interval: 60 seconds

In-app health indicators

Web UI

• ConnectionBanner: Amber banner appears when the server is unreachable for longer than the configured threshold (Settings → Notifications → "Server offline alert"). Auto-dismisses on reconnect with a "Reconnected" toast.
• Offline banner: Red "Offline" indicator in sidebar when the browser loses network connectivity (independent of server status).

macOS menu bar (chatwire-toolbar)

• Icon: Solid "ᴄ" when healthy, outline "ⓒ" when unhealthy
• Dropdown menu: Shows port, listening interface, uptime, last message time, per-service status, restart buttons

Settings

• Server offline alert (Settings → Notifications): Configure how long the server must be unreachable before showing the ConnectionBanner. Options: 30s, 1 minute, 2 minutes, 5 minutes, or disabled.

Configuration

{
  "web": {
    "heartbeat_alert_seconds": 60
  }
}

Set to 0 to disable the server offline alert entirely.

Bridge heartbeat file

The bridge writes its heartbeat to ~/.chatwire/bridge_heartbeat on each poll iteration (~every 2 seconds). This is a plain text file containing a unix timestamp. The /api/heartbeat endpoint reads this file to determine bridge liveness.

If you need to check bridge health from a script:

# Check if bridge heartbeat is fresh (< 10 seconds old)
ts=$(cat ~/.chatwire/bridge_heartbeat 2>/dev/null)
now=$(date +%s)
if [ -n "$ts" ] && [ $((now - ${ts%.*})) -lt 10 ]; then
  echo "bridge alive"
else
  echo "bridge down"
fi