tutorial

Monitoring Agent Zero with Vigilmon: Flask UI Availability, Docker Container Health & LLM Provider Connectivity

How to monitor a self-hosted Agent Zero installation with Vigilmon — Flask web UI availability on port 50080, Docker container health checks, LLM provider API connectivity, stuck agent task detection, and TLS certificate alerts.

Agent Zero is an open-source autonomous AI agent framework designed to act as a "personal assistant with a computer" — it can execute shell commands, write and run code, browse the web, manage files, and remember context between sessions. Each Agent Zero agent runs in an isolated Docker container, and the framework connects to any LLM backend (OpenAI, Anthropic, Ollama, and others) as its reasoning engine. A Flask web UI on port 50080 provides the chat interface for interacting with and directing agents. But autonomous agent frameworks introduce unique monitoring challenges: Docker containers can fail silently, LLM provider API keys can expire, and long-running agent tasks can stall indefinitely without any error output. Vigilmon monitors Agent Zero's web UI, Docker infrastructure, and LLM connectivity to detect failures before they strand your agents mid-task.

What You'll Build

  • An HTTP monitor on the Agent Zero Flask web UI (port 50080)
  • Docker daemon and container health heartbeats
  • LLM provider API connectivity checks (OpenAI, Anthropic, or Ollama)
  • Stuck agent task detection via heartbeat
  • File system and memory directory health monitoring
  • SSL certificate monitoring for reverse-proxied deployments
  • Alerting rules for UI failures, container crashes, and provider API issues

Prerequisites

  • Agent Zero installed and running (default web UI port 50080)
  • Docker Engine installed and running
  • An LLM provider configured (OpenAI API key, Anthropic API key, or local Ollama)
  • A free account at vigilmon.online

Step 1: Verify Agent Zero Is Running

Agent Zero's Flask web UI serves on port 50080 by default. Verify it is accessible:

# Check the web UI
curl -s -o /dev/null -w "%{http_code}" http://localhost:50080/
# 200

# Check if Docker is running (required for agent containers)
docker info > /dev/null 2>&1 && echo "Docker OK" || echo "Docker not running"

# List running Agent Zero containers
docker ps --filter "label=agent-zero" 2>/dev/null

Agent Zero creates one Docker container per agent session. If Docker is unavailable, Agent Zero cannot spawn agent sandboxes and any agent interaction will fail.

Step 2: Create the Flask Web UI Monitor

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: http://YOUR-SERVER-IP:50080/ (or your reverse-proxy HTTPS URL).
  3. Check interval: 60 seconds.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Keyword: Agent Zero or agent (present in the web UI page title/content).
  7. Click Save.

This monitor catches Flask process crashes, port binding failures, and unclean restarts. It is the primary availability signal for the web interface your team or you use to interact with agents.

Step 3: Monitor Docker Daemon Health

Docker is a hard dependency for Agent Zero — without Docker, no agent containers can be created. Monitor Docker daemon availability via a heartbeat:

#!/bin/bash
# /etc/cron.d/agent-zero-docker-heartbeat — runs every 5 minutes

# Check if Docker daemon is running and responsive
if docker info > /dev/null 2>&1; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-DOCKER-HEARTBEAT-ID
fi

Create a Heartbeat monitor in Vigilmon:

  1. Add Monitor → Heartbeat.
  2. Expected interval: 5 minutes.
  3. Grace period: 10 minutes.
  4. Alert: when heartbeat is missed.

Docker daemon crashes are rare but catastrophic for Agent Zero — every active agent loses its sandbox and any mid-task work is lost. Alert immediately on a single missed heartbeat.

Step 4: Monitor Agent Container Health

Each Agent Zero agent runs in its own Docker container. A container can become unhealthy (OOM killed, filesystem full inside the container, or hung process) while the Flask UI remains responsive. Monitor active agent containers:

#!/bin/bash
# /etc/cron.d/agent-zero-containers-heartbeat — runs every 5 minutes

# Check all Agent Zero containers for unhealthy status
UNHEALTHY=$(docker ps --filter "label=agent-zero" \
  --format "{{.Status}}" 2>/dev/null | grep -c "unhealthy" || true)

# Check for exited/crashed containers that should be running
EXITED=$(docker ps -a --filter "label=agent-zero" \
  --filter "status=exited" --format "{{.Names}}" 2>/dev/null | wc -l)

if [ "$UNHEALTHY" -eq "0" ] && [ "$EXITED" -eq "0" ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-CONTAINERS-HEARTBEAT-ID
fi

Container labels: Agent Zero container labels vary by version. Use docker ps and inspect your running containers to find the correct filter. You may need to filter by image name instead: --filter "ancestor=agent-zero-image-name".

Step 5: Monitor LLM Provider API Connectivity

Agent Zero is entirely dependent on its configured LLM backend for reasoning. If the LLM API becomes unreachable — expired API key, provider outage, or Ollama server crash — every agent interaction fails silently. Monitor each provider you use:

For OpenAI:

#!/bin/bash
# Check OpenAI API connectivity
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  --max-time 10 \
  "https://api.openai.com/v1/models")

if [ "$HTTP_STATUS" = "200" ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-OPENAI-HEARTBEAT-ID
fi

For Anthropic:

#!/bin/bash
# Check Anthropic API connectivity
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --max-time 10 \
  "https://api.anthropic.com/v1/models")

if [ "$HTTP_STATUS" = "200" ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-ANTHROPIC-HEARTBEAT-ID
fi

For local Ollama: Add a Vigilmon HTTP monitor pointing at your Ollama health endpoint (see the Ollama monitoring tutorial).

Add a Heartbeat monitor for each LLM provider:

  • Expected interval: 5 minutes.
  • Grace period: 5 minutes.
  • Alert: immediately on first miss (LLM unavailability halts all agent work).

Step 6: Detect Stuck Agent Tasks

Agent Zero agents can stall indefinitely on long-running shell commands, browser automation tasks, or LLM chains without producing any visible error. Use a heartbeat probe that checks Agent Zero's active task state:

#!/bin/bash
# /etc/cron.d/agent-zero-task-heartbeat — runs every 15 minutes
# Checks that the agent process responds to a simple API call

# Agent Zero exposes internal API endpoints — check the message endpoint
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  --max-time 10 \
  http://localhost:50080/api/status 2>/dev/null)

# Alternatively check that the web UI renders within a time budget
UI_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  --max-time 8 \
  http://localhost:50080/ 2>/dev/null)

if [ "$UI_STATUS" = "200" ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-TASK-HEARTBEAT-ID
fi

Create a Heartbeat monitor for task health:

  • Expected interval: 15 minutes.
  • Grace period: 20 minutes.
  • Alert: when missed for over 35 minutes (two intervals + grace).

Step 7: Monitor Memory and Persistence Directory Health

Agent Zero stores agent memory, session context, and learned information in a persistent file directory. If the memory directory becomes unwritable (disk full, permissions error, NFS mount failure), agents lose their ability to remember and learn:

#!/bin/bash
# /etc/cron.d/agent-zero-memory-heartbeat — runs every 10 minutes

MEMORY_DIR="${HOME}/agent-zero/memory"  # adjust to your Agent Zero install path

# Check disk usage
USED_PERCENT=$(df "$MEMORY_DIR" 2>/dev/null | awk 'NR==2 {print $5}' | tr -d '%')

# Check directory is writable
WRITE_OK=$(touch "$MEMORY_DIR/.write_test" 2>/dev/null && \
  rm "$MEMORY_DIR/.write_test" && echo "ok" || echo "fail")

if [ "${USED_PERCENT:-100}" -lt "90" ] && [ "$WRITE_OK" = "ok" ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-MEMORY-HEARTBEAT-ID
fi

Step 8: Monitor Browser Automation Health (Playwright/Selenium)

If your Agent Zero agents use web browsing capabilities, the browser automation stack (Playwright or Selenium) is an additional dependency. A failed browser install or missing display server (for headless Chrome) silently breaks all web-browsing tasks:

#!/bin/bash
# /etc/cron.d/agent-zero-browser-heartbeat — runs every 30 minutes

# Test Playwright browser launch (non-headless check)
BROWSER_OK=$(python3 -c "
from playwright.sync_api import sync_playwright
try:
  with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto('about:blank')
    browser.close()
    print('ok')
except Exception as e:
  print(f'fail: {e}')
" 2>/dev/null)

if [ "$BROWSER_OK" = "ok" ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-BROWSER-HEARTBEAT-ID
fi

Set the Expected interval to 30 minutes — browser health changes slowly but a failure blocks a key agent capability.

Step 9: Monitor SSL Certificate for Reverse-Proxied Deployments

If Agent Zero is accessible over HTTPS via a reverse proxy, monitor the SSL certificate:

  1. Add Monitor → SSL Certificate.
  2. Domain: agent-zero.yourdomain.com.
  3. Alert when expiry is within: 30 days.
  4. Alert escalation: 14 days, 7 days.

Step 10: Configure Alerting

Wire up alert channels in Vigilmon under Settings → Notifications:

| Monitor | Trigger | First action | |---|---|---| | Flask web UI | Non-200 | Restart Agent Zero; check Python/Flask logs | | Docker daemon heartbeat | Missed > 10 min | systemctl restart docker; check journalctl -u docker | | Container health | Heartbeat missed | docker ps -a to find crashed containers; docker logs <id> | | OpenAI/Anthropic heartbeat | Missed | Check API key validity and account billing status | | Ollama heartbeat | Missed | See Ollama monitoring tutorial; restart Ollama server | | Task health | Missed > 35 min | Check for stuck tasks in UI; consider restarting Agent Zero | | Memory directory | Heartbeat missed | Check disk space; verify directory permissions | | Browser heartbeat | Missed | Reinstall Playwright browsers: playwright install chromium | | SSL certificate | < 30 days | Renew via Caddy ACME or certbot renew |

Alert after 1 missed heartbeat for Docker daemon — it is a hard dependency. Alert after 2 consecutive failures for HTTP monitors.

Common Agent Zero Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Flask web UI crashes | HTTP monitor fails within 60 s | | Docker daemon stops | Docker heartbeat stops; all agent work halts | | Agent container OOM killed | Container health heartbeat stops | | OpenAI API key expires | LLM provider heartbeat stops; all agent reasoning fails | | Ollama server crashes (local LLM) | Ollama HTTP monitor fails | | Agent task stuck indefinitely | Task health heartbeat stops after 35 min | | Memory directory fills up | Memory heartbeat stops | | Playwright missing/broken | Browser heartbeat stops | | SSL certificate expires | SSL monitor alerts at 30 days | | Agent Zero not auto-started after reboot | Flask UI monitor fails immediately |

Agent Zero's power comes from combining a persistent LLM reasoning engine, Docker sandbox isolation, browser automation, and file system access — but that power stack is exactly what creates monitoring complexity. A failure in any layer silently degrades agent capabilities without obvious errors. Vigilmon's combination of HTTP monitoring, Docker heartbeats, and LLM provider checks gives you full visibility into every dependency: from the web UI your team interacts with down to the Docker containers where your agents actually work.

Start monitoring Agent Zero 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