Monitoring Lima VMs on macOS with Vigilmon

Lima is the open-source VM manager that powers Docker Desktop alternatives like Colima — it runs Linux VMs on macOS using QEMU or Apple's Virtualization framework and exposes them via socket proxies and filesystem mounts. When a Lima VM hangs, its socket disappears and every tool that depends on it (Docker, Podman, containerd) fails silently. Vigilmon gives you lightweight external monitoring for Lima VM health, socket availability, and resource utilization so you catch VM stalls before they block your entire local development workflow.

What You'll Set Up

VM instance health checks via cron heartbeats
Socket availability monitoring for container runtimes
Resource utilization alerts (CPU, memory, disk)
File share sync status tracking
Automated recovery alerting when VM restarts

Prerequisites

Lima 0.18+ installed (brew install lima)
At least one VM instance running (limactl start)
A free Vigilmon account

Step 1: Monitor VM Instance Health with a Heartbeat

Lima VMs don't expose an HTTP endpoint by default, so the most reliable health signal is a heartbeat script that runs inside the VM and pings Vigilmon:

In Vigilmon, click Add Monitor → Cron Heartbeat.
Set Expected ping interval to 5 minutes.
Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/abc123).

Now set up the heartbeat script inside your Lima VM:

# Connect to the VM
limactl shell default

# Install the cron job inside the VM
(crontab -l 2>/dev/null; echo "*/5 * * * * curl -s https://vigilmon.online/heartbeat/abc123") | crontab -

If the VM hangs, the kernel panics, or QEMU terminates unexpectedly, the heartbeat stops firing and Vigilmon alerts after the expected interval passes.

For named instances (not default), use limactl shell <instance-name> to connect and repeat the setup. Create a separate Vigilmon heartbeat monitor for each critical VM instance.

Step 2: Monitor Socket Availability for Container Runtimes

Lima's most common use case is running container runtimes — Docker, Podman, or containerd — with their Unix sockets forwarded to the macOS host. When the VM hangs or the socket proxy drops, the socket file exists on the host but connections time out.

Add a health check script that tests the socket actively:

#!/bin/bash
# /usr/local/bin/lima-socket-check.sh

SOCKET="$HOME/.lima/default/sock/docker.sock"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/def456"

if [ ! -S "$SOCKET" ]; then
  echo "Socket missing: $SOCKET"
  exit 1
fi

# Test actual connectivity, not just file existence
if docker -H "unix://$SOCKET" info >/dev/null 2>&1; then
  curl -s "$HEARTBEAT_URL"
else
  echo "Socket exists but Docker is not responding"
  exit 1
fi

Add this to your macOS cron:

chmod +x /usr/local/bin/lima-socket-check.sh
(crontab -l 2>/dev/null; echo "*/5 * * * * /usr/local/bin/lima-socket-check.sh") | crontab -

Create a Vigilmon heartbeat monitor with a 5 minute expected interval for this check. A socket that exists but doesn't respond is a common failure mode — checking file existence alone will miss it.

Step 3: Track VM Resource Utilization

Lima VMs can exhaust their allocated memory or disk and stall without surfacing a clear error. Add a resource utilization heartbeat that only pings when usage is within healthy bounds:

#!/bin/bash
# /usr/local/bin/lima-resource-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/ghi789"
DISK_THRESHOLD=85   # percent
MEM_THRESHOLD=90    # percent

limactl shell default -- bash -s <<'INNER'
DISK_USED=$(df / | awk 'NR==2 {gsub(/%/, ""); print $5}')
MEM_TOTAL=$(free -m | awk '/^Mem:/ {print $2}')
MEM_USED=$(free -m | awk '/^Mem:/ {print $3}')
MEM_PCT=$(( MEM_USED * 100 / MEM_TOTAL ))

if [ "$DISK_USED" -lt 85 ] && [ "$MEM_PCT" -lt 90 ]; then
  echo "OK"
  exit 0
else
  echo "HIGH: disk=${DISK_USED}% mem=${MEM_PCT}%"
  exit 1
fi
INNER

if [ $? -eq 0 ]; then
  curl -s "$HEARTBEAT_URL"
fi

Set up a Vigilmon cron heartbeat with a 10 minute interval for this script. High disk utilization inside a Lima VM is a particularly common failure mode — Lima uses sparse disk images that can fill and stall writes silently.

To check disk usage directly without the script:

limactl shell default -- df -h /

Step 4: File Share Sync Status

Lima mounts macOS directories into the VM using reverse SSHFS (or virtiofs on Apple Silicon). When the sync stalls, writes from the VM appear to succeed but don't reach the macOS host — or vice versa. This is invisible without active testing.

Add a sync check:

#!/bin/bash
# /usr/local/bin/lima-sync-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/jkl012"
TEST_FILE="/tmp/lima-sync-test-$$"

# Write a file on the macOS side to the shared mount point
echo "$(date +%s)" > "$HOME/lima-test-sync.txt"

# Read it back from inside the VM
VM_CONTENT=$(limactl shell default -- cat /Users/$USER/lima-test-sync.txt 2>/dev/null)
HOST_CONTENT=$(cat "$HOME/lima-test-sync.txt")

# Clean up
rm -f "$HOME/lima-test-sync.txt"

if [ "$VM_CONTENT" = "$HOST_CONTENT" ]; then
  curl -s "$HEARTBEAT_URL"
else
  echo "File share sync failure: host='$HOST_CONTENT' vm='$VM_CONTENT'"
fi

Run this every 15 minutes and set the Vigilmon heartbeat interval to 20 minutes to allow a small window. Sync stalls are common after macOS wakeup from sleep when the SSHFS connection drops.

Step 5: Monitor VM Restart and Recovery

Lima can be configured to auto-start VMs on login, but it doesn't alert when a VM crashes and restarts. Add a startup hook that pings a Vigilmon heartbeat whenever the VM boots:

# Inside the VM: /etc/rc.local or a systemd service

#!/bin/bash
# /usr/local/bin/lima-boot-notify.sh
curl -s https://vigilmon.online/heartbeat/mno345

Create a systemd one-shot service inside the VM:

# /etc/systemd/system/vigilmon-boot.service
[Unit]
Description=Notify Vigilmon on boot
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/lima-boot-notify.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

# Enable the service inside the VM
limactl shell default -- sudo systemctl enable vigilmon-boot
limactl shell default -- sudo systemctl start vigilmon-boot

Set the Vigilmon heartbeat expected interval to 24 hours. If it fires more than once in a short period, that's a signal the VM is crash-looping. Unexpected boot pings within a normal session indicate instability worth investigating.

Step 6: Alert Channels and Notification Setup

For local development VMs, integrate alerts into the tools you're watching rather than your phone:

Go to Alert Channels in Vigilmon.
Add a Slack webhook pointing to your #dev-infra channel.
For critical socket monitors, also add email so you notice during off-hours.
Set Consecutive failures before alert to 2 — Lima sometimes misses a single heartbeat during macOS sleep/wake cycles without a real VM failure.

Add a maintenance window for planned VM restarts:

# Before running limactl stop
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "MONITOR_ID", "duration_minutes": 3}'

limactl stop default
limactl start default

Summary

| Monitor | Target | What It Catches | |---|---|---| | Cron heartbeat (VM) | In-VM cron ping | VM hang, QEMU crash, kernel panic | | Cron heartbeat (socket) | Socket connectivity test | Socket proxy drop, runtime stall | | Cron heartbeat (resources) | Disk and memory check | VM disk full, memory exhaustion | | Cron heartbeat (sync) | File share round-trip test | virtiofs/SSHFS sync stall | | Cron heartbeat (boot) | Startup notification | Unexpected VM restarts |

Lima makes Linux VMs on macOS fast and ergonomic, but VMs are still processes that crash, sockets are still proxies that drop, and file shares are still network mounts that stall. Vigilmon closes the observability gap so a hung Lima VM triggers an alert instead of a puzzling cascade of failures in every tool that depends on it.