tutorial

Monitoring Colima with Vigilmon: VM Health, Docker Socket Availability, Port-Forwarded Services & Resource Alerts

How to monitor Colima with Vigilmon — VM liveness checks, Docker and containerd socket availability, port-forwarded service health, and resource utilization alerts for macOS container runtimes.

Colima is the lightweight macOS container runtime that runs Docker and containerd inside a Lima-managed virtual machine — giving developers Docker Desktop-equivalent functionality without the licensing overhead. While Colima is primarily a local development tool, many teams run it persistently as a shared CI/CD builder, a local staging environment, or a development server accessed by remote teammates over SSH or Tailscale. When Colima's Lima VM crashes, the Docker socket becomes unavailable and every container build, push, and run fails silently. When port-forwarded services go down inside Colima, the teams depending on those endpoints lose access without warning. Vigilmon gives you external visibility into Colima's port-forwarded services, local HTTP endpoints, and the health of anything running inside your Colima environment.

What You'll Build

  • HTTP monitors on port-forwarded services running inside Colima
  • A TCP monitor to confirm that Colima's port forwarding is active
  • Monitors for any web services, APIs, or databases exposed through Colima
  • SSL certificate monitoring if you're running HTTPS inside Colima
  • Alerting tuned for the macOS development environment context

Prerequisites

  • Colima installed and running on macOS (colima start)
  • One or more services running inside Colima with port forwarding configured (e.g., colima start --port 8080:8080)
  • Vigilmon accessible from the machine running Colima (or a shared dev server)
  • A free account at vigilmon.online

Step 1: Understand How Colima Exposes Services

Colima runs a Lima VM (Linux virtual machine) that hosts the container runtime. Services running inside containers are exposed to the macOS host via port forwarding. A container bound to port 8080 inside Colima appears as localhost:8080 or 127.0.0.1:8080 on the macOS host.

When you run services with docker run -p 8080:8080, the port is forwarded through:

  1. The container's network namespace → the Lima VM network
  2. The Lima VM's VirtioFS or SLIRP network → the macOS host interface

You can confirm what's exposed:

# List running containers and their port mappings
colima exec -- docker ps --format "table {{.Names}}\t{{.Ports}}"

# Verify a port is listening on the macOS host
curl http://localhost:8080/health

For Vigilmon to monitor these services externally, the macOS machine must be reachable over a network. In a shared development server scenario (a macOS Mac mini or Mac Pro used by a team), this means the machine's local IP or a Tailscale address. In a solo development setup, you can run Vigilmon checks from within the same machine by configuring an agent if needed, but the most common use case is a shared Colima instance.

Step 2: Monitor a Port-Forwarded HTTP Service

The most important thing to monitor in a Colima environment is whether the services you depend on inside containers are still running and reachable. A web API, a development server, or a backend service should all have an HTTP health check.

For a web application container forwarded to port 8080:

curl http://dev-server.local:8080/health
# or
curl http://192.168.1.50:8080/health
  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: http://192.168.1.50:8080/health (use the shared macOS server's IP, not localhost).
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: a string from your app's health response (e.g., ok, healthy, or a JSON key).
  7. Label: Colima web app :8080.
  8. Click Save.

This monitor catches:

  • The container exiting due to an application crash or OOM kill
  • Colima's Lima VM failing or being stopped by a macOS power event
  • Port forwarding breaking after a Colima restart or macOS network interface change
  • Docker daemon failure inside the Colima VM
  • Application-level errors causing the health endpoint to return non-200

Alert sensitivity: 1 consecutive failure for production-critical services, 2 for development environments.

Step 3: Monitor the Docker API Socket via HTTP

The Docker daemon inside Colima exposes a REST API that can be reached from the macOS host through the forwarded Docker socket. If you expose the Docker API over TCP (for CI/CD tools that need remote Docker access), you can monitor it directly:

# If Docker TCP API is exposed (e.g., colima start with DOCKER_HOST=tcp://...)
curl http://192.168.1.50:2375/version
# Returns JSON with Docker daemon version info

Security warning: Exposing the Docker TCP API without TLS on a network interface is a significant security risk. Only do this in isolated development networks or with mutual TLS configured.

For a safer alternative, monitor the Docker API's /ping endpoint if you've set up a TCP proxy:

  1. Add Monitor → HTTP.
  2. URL: http://192.168.1.50:2375/ping (replace with your actual Docker TCP port and server IP).
  3. Check interval: 2 minutes.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Keyword: OK (the Docker ping response body).
  7. Label: Colima Docker API.
  8. Click Save.

If you prefer not to expose the Docker TCP API, skip this step — the port-forwarded service monitors from Step 2 are sufficient to detect container and VM failures.

Step 4: Monitor TCP Port Availability

For services that don't expose HTTP — databases, message brokers, or raw TCP services — use Vigilmon's TCP monitor to confirm the port is accepting connections:

# Test that PostgreSQL inside Colima is reachable
nc -zv 192.168.1.50 5432

# Test that Redis inside Colima is reachable
nc -zv 192.168.1.50 6379
  1. Add Monitor → TCP.
  2. Host: 192.168.1.50 (your Colima server's IP).
  3. Port: 5432 (PostgreSQL), 6379 (Redis), or whichever port your service forwards.
  4. Check interval: 2 minutes.
  5. Response timeout: 10 seconds.
  6. Label: Colima PostgreSQL :5432.
  7. Click Save.

Repeat for each TCP service you need to monitor. Common Colima TCP ports:

| Service | Default port | |---|---| | PostgreSQL | 5432 | | MySQL / MariaDB | 3306 | | Redis | 6379 | | MongoDB | 27017 | | Kafka | 9092 | | Elasticsearch | 9200 | | NATS | 4222 |

Step 5: Monitor Multiple Services in a Docker Compose Stack

Colima is frequently used to run Docker Compose stacks with multiple services. Each service that exposes a port can be individually monitored. For a typical web stack:

# docker-compose.yml example
services:
  api:
    image: myapp-api
    ports:
      - "8080:8080"
  postgres:
    image: postgres:16
    ports:
      - "5432:5432"
  redis:
    image: redis:7
    ports:
      - "6379:6379"
  nginx:
    image: nginx
    ports:
      - "80:80"
      - "443:443"

Set up monitors for each exposed service:

| Service | Monitor type | URL/endpoint | Check interval | |---|---|---|---| | API service | HTTP | http://server:8080/health | 60 s | | Nginx | HTTP | http://server:80 | 60 s | | PostgreSQL | TCP | server:5432 | 2 min | | Redis | TCP | server:6379 | 2 min |

Compose dependency tracking: If the API container depends on PostgreSQL, a PostgreSQL TCP failure followed by an API HTTP failure within 1-2 minutes is likely a cascade. Set up both monitors and note the sequence in your alerting runbook — it helps your team distinguish a database failure from an API bug.

Step 6: Monitor Colima VM Liveness via the Host API

If your macOS server exposes a simple liveness endpoint (a tiny health-check server, or a Prometheus metrics exporter on the host), you can use it to detect whether the macOS machine itself is reachable, independent of any Colima containers:

# Example: a simple Python health server on the macOS host
python3 -m http.server 9999
curl http://192.168.1.50:9999

For a more robust approach, deploy a lightweight sidecar health-check container in your Colima Docker Compose stack:

healthcheck:
  image: alpine
  ports:
    - "9999:9999"
  command: sh -c "while true; do echo -e 'HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nok' | nc -l -p 9999; done"
  1. Add Monitor → HTTP.
  2. URL: http://192.168.1.50:9999
  3. Check interval: 30 seconds.
  4. Response timeout: 5 seconds.
  5. Expected status: 200.
  6. Label: Colima VM host liveness.
  7. Click Save.

When this monitor fails, it indicates the macOS host is unreachable (network failure, machine off, sleep/hibernate) rather than a container failure. When the host liveness monitor is green but a service monitor is red, you know Colima's VM is up but a specific container has crashed.

Step 7: SSL Certificate Monitoring for HTTPS Services

If you're running HTTPS services inside Colima (e.g., with self-signed certificates for local HTTPS development, or with mkcert-issued certificates), Vigilmon can monitor those certificates:

openssl s_client -connect 192.168.1.50:443 2>/dev/null | openssl x509 -noout -dates
  1. Add Monitor → SSL Certificate.
  2. Domain: your Colima server's IP or hostname.
  3. Port: 443 (or your HTTPS port).
  4. Alert when expiry is within: 14 days (mkcert certs can be short-lived).
  5. Click Save.

Self-signed and mkcert certificates: Vigilmon's SSL monitor checks the certificate's expiry date and chain validity. mkcert certificates are signed by a local CA that isn't trusted by Vigilmon's monitoring infrastructure — the SSL check will report a certificate error (invalid CA). Use this monitor for domains with publicly trusted certificates, or for detecting basic connectivity rather than full chain validation.

Step 8: Configure Alerting for Development Environments

Development environment alerting has different sensitivity requirements than production. In Vigilmon under Settings → Notifications, configure:

| Monitor | Trigger | Action | |---|---|---| | HTTP service | Non-200 or keyword missing | Check container: colima exec -- docker ps; restart if needed | | TCP port | Connection refused | Port forwarding may have reset; run colima restart or restart specific container | | Docker API | Non-200 | Docker daemon crashed inside Lima VM; run colima stop && colima start | | Host liveness | Timeout | macOS host unreachable; check network, wake-on-LAN, or SSH access | | SSL certificate | < 14 days to expiry | Regenerate certificate with mkcert or ACME client |

Alert after: 2 consecutive failures for development-only services. 1 consecutive failure for shared infrastructure that multiple team members depend on.

Common Colima Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | macOS puts the machine to sleep | Host liveness and all service monitors fail simultaneously | | Colima Lima VM crashes | All port-forwarded service monitors fail | | Docker daemon OOM killed inside VM | Docker API monitor fails; container monitors fail | | Specific container exits (OOM, crash) | That service's HTTP/TCP monitor fires; others stay green | | Port forwarding breaks after macOS network change | Service monitors fail; host liveness may still be green | | Docker Compose restart leaves port unbound briefly | Service monitors fire briefly; recover within check interval | | Disk full inside Lima VM | Containers fail to start or write; service monitors fire | | Colima version upgrade breaks socket path | Docker API and all service monitors fail | | macOS firewall blocking forwarded port | Service monitors fail; host liveness on different port stays green | | VirtioFS mount failure | Container mounts fail; service monitors catch application errors |

Colima turns macOS into a capable container runtime for development, CI/CD, and shared staging environments — but it runs behind Lima's VM layer where crashes and restarts are invisible to your team. Vigilmon gives you external visibility into every port-forwarded service, TCP endpoint, and HTTP API running inside your Colima environment, so you know the moment a container crashes, the VM restarts, or port forwarding breaks, and can restore service before the team loses access to shared development infrastructure.

Start monitoring your Colima services in under 5 minutes — register free at vigilmon.online.

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