How to Monitor OrbStack with Vigilmon

OrbStack replaces Docker Desktop on macOS with a leaner, faster alternative — millisecond startup, native Apple Silicon support, and Linux VM integration that feels seamless. But OrbStack's speed advantage doesn't mean your containers are immune to crashes, misconfigured health checks, or services that stop responding. Vigilmon extends OrbStack's local-first approach with external uptime monitoring: HTTP checks on exposed container ports, heartbeat signals from scheduled tasks, and instant alerts when a container goes silent.

What You'll Set Up

• HTTP uptime monitors for services exposed by OrbStack containers
• Heartbeat monitors for scheduled tasks running inside OrbStack VMs
• SSL certificate monitoring for local HTTPS services via OrbStack's built-in domains

Prerequisites

• OrbStack installed on macOS with at least one running container or Linux VM
• A service accessible over HTTP (on localhost or OrbStack's .local domain)
• A free Vigilmon account

Step 1: Expose Your Container and Find Its URL

OrbStack automatically assigns each container a domain on the orb.local network. Find your container's URL:

# List running containers with their OrbStack domains
orb list

OrbStack containers are accessible at http://<container-name>.orb.local from the host machine. For a container named api, that's http://api.orb.local.

If your container maps a port to localhost, find the mapping:

docker ps --format "table {{.Names}}\t{{.Ports}}"

A container binding 0.0.0.0:8080->8080/tcp is accessible at http://localhost:8080.

Step 2: Add a Health Endpoint to Your Container

Before adding Vigilmon monitors, give your service a dedicated health route:

Node.js / Express

app.get('/health', (req, res) => {
  res.json({ status: 'ok', uptime: process.uptime() });
});

Python / FastAPI

@app.get('/health')
def health():
    return {'status': 'ok'}

Go

http.HandleFunc('/health', func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.Write([]byte(`{"status":"ok"}`))
})

Rebuild and restart your container after adding the endpoint:

docker compose up --build -d

Verify the endpoint is live:

curl http://localhost:8080/health
# or
curl http://api.orb.local/health

Step 3: Add an HTTP Monitor in Vigilmon

Once your health endpoint is reachable, point Vigilmon at it:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: http://localhost:8080/health (or your OrbStack domain).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

Vigilmon will now check your container's health every minute. If the container crashes, the service stops responding, or a bad deployment breaks the health route, you'll receive an alert within the check interval.

Note: Vigilmon's external probes can't reach localhost or .orb.local domains directly — they're only accessible from your Mac. To monitor OrbStack containers externally, either expose the port via a tunnel (see Step 5) or install the Vigilmon agent inside the OrbStack VM (see Step 4).

Step 4: Monitor from Inside the OrbStack Linux VM

OrbStack includes a full Linux VM (orb). You can run the Vigilmon agent inside the VM to monitor containers without exposing ports externally:

# Open a shell inside the OrbStack VM
orb shell

# Install curl if not present
sudo apt-get install -y curl

# Run a simple health probe loop as a systemd service or cron job
*/1 * * * * curl -fsS http://api.orb.local/health | grep -q '"status":"ok"' && \
  curl -fsS "https://vigilmon.online/api/heartbeat/YOUR_HEARTBEAT_TOKEN" > /dev/null

Add this cron line inside the OrbStack VM to send a Vigilmon heartbeat every minute only if the health check passes. If the health check fails or the cron stops running, Vigilmon detects the missing ping.

Step 5: Expose Containers Externally with a Tunnel

For monitoring from Vigilmon's external probes — or sharing a local service with teammates — expose your OrbStack container via a tunnel:

# Using ngrok
ngrok http 8080

# Using cloudflared
cloudflared tunnel --url http://localhost:8080

Copy the public HTTPS URL from the tunnel output (e.g., https://abc123.ngrok-free.app) and add it as an HTTP monitor in Vigilmon. This gives you genuine external uptime monitoring that catches network-level issues, not just local container health.

Step 6: Monitor OrbStack's Built-in HTTPS Domains

OrbStack can provision HTTPS for containers using its built-in certificate authority. If you're using OrbStack HTTPS domains (https://api.orb.local), add an SSL monitor:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the HTTPS URL.
3. Enable SSL Certificate monitoring.
4. Set Alert when certificate expires within: 14 days.

This catches OrbStack CA certificate issues or expired certs before they break local development workflows.

Step 7: Heartbeat Monitor for Docker Compose Jobs

If you use Docker Compose to run scheduled jobs or one-off tasks in OrbStack, add a heartbeat ping at the end of each job:

# docker-compose.yml
services:
  backup:
    image: postgres:16
    command: >
      sh -c "
        pg_dump -h db myapp > /backups/myapp.sql &&
        curl -fsS --retry 3 'https://vigilmon.online/api/heartbeat/YOUR_HEARTBEAT_TOKEN' > /dev/null
      "
    volumes:
      - ./backups:/backups

Run this service on a schedule using a host-level cron:

# macOS crontab -e
0 2 * * * docker compose -f /path/to/docker-compose.yml run --rm backup

If the backup job fails or the cron stops firing, Vigilmon alerts you before the next day's backup window.

Step 8: Configure Alerting

Set alert channels so the right people know when a container goes down:

1. Go to Monitors → [your monitor] → Alerts.
2. Add channels: email, Slack, or webhook.
3. Development monitors: alert after 2 failed checks (transient restarts are common locally).
4. Production-mirroring environments: alert after 1 failed check.

For heartbeat monitors, set the grace period to interval + 10 minutes to absorb occasional slow starts.

Conclusion

OrbStack makes running containers on macOS fast and frictionless. Vigilmon makes sure those containers stay healthy — catching crashes, failed jobs, and degraded services before they waste your development time. Whether you're running a local API, a background worker, or a full microservices stack in OrbStack, adding Vigilmon monitors takes two minutes and saves you from the "why did everything break?" investigation that follows an unnoticed container failure.

Start monitoring your OrbStack containers at vigilmon.online.