tutorial

Monitoring OpenHands with Vigilmon: AI Agent Runtime, LLM Backend & Web UI Availability

How to monitor OpenHands with Vigilmon — AI agent runtime health, LLM API endpoint availability, web UI uptime, and alerting for open-source AI software engineering agent outages.

OpenHands (formerly OpenDevin) is an open-source AI software engineering agent that can browse the web, write and run code, use terminal commands, and interact with APIs to complete complex software engineering tasks autonomously. Teams deploy OpenHands as a shared service for developers to delegate multi-step coding tasks — refactoring, bug investigation, test writing, and repository exploration — without manual step-by-step prompting. Because OpenHands agents run long-horizon tasks that may span minutes or hours, the availability of both the OpenHands runtime and the underlying LLM APIs is critical: a mid-task outage forces the agent to restart from scratch, wasting tokens and time. Vigilmon gives you external visibility into the OpenHands web interface, the LLM backends it routes requests to, and any custom agent sandboxes, so outages are caught and alerted before developers lose in-progress work.

What You'll Build

  • An HTTP monitor for the OpenHands web UI
  • Monitors for the LLM API endpoints OpenHands routes agent requests to
  • SSL certificate monitoring for the OpenHands host and LLM API domains
  • An alerting setup that distinguishes runtime failures from LLM backend failures

Prerequisites

  • OpenHands running via Docker (docker run -p 3000:3000 ...) or a local install
  • Knowledge of which LLM provider OpenHands is configured to use (Anthropic, OpenAI, or a local model)
  • A free account at vigilmon.online

Step 1: Identify Your OpenHands Deployment

OpenHands is typically deployed in one of three ways:

  1. Docker on a single machine — docker run -it -p 3000:3000 -v /path/to/workspace:... running on a server or workstation
  2. Shared team server — an instance running persistently on an internal or cloud server, accessed by multiple developers
  3. Local developer machine — each developer runs their own instance on localhost

For cases 1 and 2, external monitoring via Vigilmon is directly applicable. For local instances, you can still monitor the LLM backends that power the agent:

# Check OpenHands web UI is running
curl http://your-openhands-host:3000

# Check the default OpenHands API endpoint
curl http://your-openhands-host:3000/api/health

Step 2: Monitor the OpenHands Web UI

The OpenHands web interface is the primary access point for developers submitting tasks to the agent. Monitoring it ensures the runtime service is alive and serving the browser-based chat interface:

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: http://your-openhands-host:3000.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: OpenHands.
  7. Label: OpenHands web UI.
  8. Click Save.

If you've placed OpenHands behind a reverse proxy (Nginx, Caddy, Traefik) on port 443, update the URL to https://openhands.your-domain.com and remove the port. The keyword check ensures the response is the actual OpenHands interface and not a proxy error page.

Step 3: Monitor the OpenHands API Health Endpoint

OpenHands exposes an API backend that the web UI communicates with to start agents, track sessions, and retrieve results. The API health endpoint confirms the backend service is operational:

# Check the OpenHands API health
curl http://your-openhands-host:3000/api/health
  1. Add Monitor → HTTP.
  2. URL: http://your-openhands-host:3000/api/health.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Label: OpenHands API health.
  7. Click Save.

This monitor catches cases where the web UI static files are served but the Python backend has crashed, leaving the interface appearing healthy while all agent operations fail silently.

Step 4: Monitor the Anthropic API (for Claude models)

OpenHands works best with capable frontier models. Anthropic's Claude is a common choice for complex software engineering tasks due to its strong code understanding and long context window. Monitor the Anthropic API:

curl -I https://api.anthropic.com
  1. Add Monitor → HTTP.
  2. URL: https://api.anthropic.com.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Label: Anthropic API (OpenHands backend).
  7. Click Save.

This monitor fires when the Anthropic API is down, causing OpenHands agents to fail immediately at their first LLM call — before the agent has taken any action in the workspace.

Step 5: Monitor the OpenAI API (for GPT-4o models)

OpenHands supports OpenAI models and any OpenAI-compatible endpoint. If your team has configured OpenHands to use GPT-4o or a custom OpenAI-compatible gateway:

  1. Add Monitor → HTTP.
  2. URL: https://api.openai.com/v1/models.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Label: OpenAI API (OpenHands backend).
  7. Click Save.

If OpenHands is configured to route through an LLM proxy (LiteLLM, OpenRouter, or a corporate gateway), monitor the proxy's health endpoint instead:

curl https://your-llm-proxy.example.com/health

The proxy is the single point of failure for all model backends in this topology.

Step 6: Monitor a Local LLM Backend

OpenHands supports local models via Ollama or any OpenAI-compatible server. Teams running OpenHands with a local model for privacy or cost reasons need to monitor the model server independently:

# Ollama health check
curl http://your-model-server:11434/api/tags

# vLLM or llama.cpp OpenAI-compatible server
curl http://your-model-server:8000/v1/models

For an Ollama backend:

  1. Add Monitor → HTTP.
  2. URL: http://your-model-server:11434/api/tags.
  3. Check interval: 60 seconds.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Keyword: models.
  7. Label: Ollama server (OpenHands local backend).
  8. Click Save.

For a vLLM or llama.cpp server:

  1. Add Monitor → HTTP.
  2. URL: http://your-model-server:8000/v1/models.
  3. Check interval: 60 seconds.
  4. Expected status: 200.
  5. Label: Local LLM server (OpenHands backend).
  6. Click Save.

Step 7: Monitor SSL Certificates

If OpenHands is deployed with HTTPS (recommended for shared team deployments), monitor the SSL certificate so an expiry doesn't block developers from accessing the agent interface:

# Check TLS certificate expiry
openssl s_client -connect openhands.your-domain.com:443 < /dev/null 2>/dev/null | openssl x509 -noout -dates
  1. Add Monitor → SSL Certificate.
  2. Domain: openhands.your-domain.com.
  3. Alert when expiry is within: 30 days.
  4. Alert again: 14 days, 7 days, 3 days, 1 day.
  5. Click Save.

Monitor the LLM API certificates as well, since OpenHands calls them directly and TLS failures on those domains also break agent operations:

  1. Add Monitor → SSL Certificate.
  2. Domain: api.anthropic.com.
  3. Alert when expiry is within: 30 days.
  4. Click Save.

Step 8: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | OpenHands web UI | Non-200 or keyword missing | Web interface down; check Docker container or process status | | OpenHands API health | Non-200 or timeout | Backend service crashed; restart the OpenHands server process | | Anthropic API | Non-200 or timeout | All Claude-powered agents fail; check status.anthropic.com | | OpenAI API | Non-200 or timeout | GPT-4 agents fail; check OpenAI status page | | Local LLM server | Non-200 or keyword missing | Restart Ollama/vLLM; check GPU memory and model loading | | LLM proxy | Non-200 or keyword missing | All agent LLM calls blocked; check proxy logs | | SSL certificate | < 30 days to expiry | HTTPS access will fail on expiry; renew certificate |

Alert routing: Route OpenHands runtime alerts to the platform team responsible for the deployment. LLM API failures affect all agents simultaneously and warrant team-wide notification. Include runbook links that describe whether to wait for the cloud provider to recover or to switch to a backup model.

Common OpenHands Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | OpenHands Docker container OOM-killed | Web UI and API monitors fire; agents cannot start | | LLM API rate limit hit (429 errors) | API monitor catches non-200 when the 429 causes a persistent error | | Python backend crash (web UI still serves) | API health monitor fires; web UI monitor passes (misleading) | | Anthropic API partial outage | Anthropic API monitor fires; agents fail mid-task | | Ollama GPU memory exhausted after multiple sessions | Local model server monitor fires; new agent tasks hang | | LLM proxy misconfigured after upgrade | Proxy health monitor fires; all model backends unreachable | | SSL certificate expired on OpenHands host | SSL monitor alerts 30 days before browser HTTPS errors | | DNS failure for OpenHands domain | External URL monitor fires; developers cannot reach the service |

OpenHands agents handle long-horizon software engineering tasks that span multiple tool calls, code executions, and LLM requests over minutes or hours. A mid-task infrastructure failure wastes the entire task's context and progress. Vigilmon's external monitoring catches the runtime and LLM backend failures that interrupt agent runs, so you can restore service quickly and minimize the amount of work that needs to be redone from scratch.

Start monitoring OpenHands 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