How to Monitor SWE-agent with Vigilmon

SWE-agent (Princeton NLP) is an open-source autonomous software engineering agent that takes a GitHub issue URL, navigates the codebase, writes and runs code, executes the test suite, and submits a pull request — all without human intervention. When it's working, it's the closest thing to a tireless junior engineer that never sleeps. When it's not working, tasks pile up in the queue unnoticed.

In this tutorial you'll set up monitoring for a self-hosted SWE-agent deployment running in server mode using Vigilmon — covering the API server, LLM provider connectivity, task queue health, and Docker sandbox availability.

Why monitoring SWE-agent matters

SWE-agent running in server mode is a long-lived process that processes tasks asynchronously. Failures are often silent:

API server crash — new task submissions return connection refused; the queue empties as nothing new arrives; no one notices until deadlines pass
LLM API outage or rate limit — the agent stalls mid-task waiting for GPT-4/Claude responses; tasks time out after minutes; token costs spike if retries are aggressive
Docker daemon failure — SWE-agent can't start execution containers; every task fails at the sandbox step with a cryptic Docker error
GitHub API rate exhaustion — issue fetching and PR submission silently fail; the agent appears to run but produces no output
Stalled agent session — an agent enters an infinite loop searching the codebase; it holds the execution slot indefinitely; the queue backs up

External monitoring catches these failure modes before hours of compute time are wasted.

What you'll need

SWE-agent running in server mode (port 8000 by default)
Docker installed and running (SWE-agent executes code in containers)
A free Vigilmon account

Step 1: Verify the SWE-agent server health endpoint

Start SWE-agent in server mode and confirm the health endpoint is accessible:

# Start SWE-agent server
python run_api.py --port 8000

# Verify health endpoint
curl -s http://localhost:8000/health
# Expected: {"status":"ok","version":"..."}

# Check queue status
curl -s http://localhost:8000/api/v1/queue/status
# Expected: {"queue_depth":0,"active_tasks":0,"completed_today":N}

If SWE-agent doesn't expose a /health endpoint in your version, probe the task submission endpoint:

curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/v1/tasks
# 200 or 405 (method not allowed) both confirm the server is alive

Step 2: Monitor the SWE-agent API server (port 8000)

Log in to vigilmon.online and go to Monitors → New Monitor
Choose HTTP / HTTPS as the type
Set the URL to http://your-swe-agent-host:8000/health
Set the check interval to 1 minute
Expected status code: 200
Set timeout to 15 seconds (the server can be slow when an agent is under heavy CPU load)
Save the monitor

This is your primary alert. If the API server goes down, no new tasks can be submitted and the queue silently drains.

Step 3: Add a health endpoint for queue depth

SWE-agent processes one task at a time. A growing queue indicates the agent is stalled. Add a custom monitoring endpoint by wrapping the SWE-agent API in a thin health proxy:

# health_proxy.py — run alongside swe-agent
from fastapi import FastAPI
import httpx

app = FastAPI()

@app.get("/queue-health")
async def queue_health():
    r = httpx.get("http://localhost:8000/api/v1/queue/status", timeout=5)
    data = r.json()
    queue_depth = data.get("queue_depth", 0)
    # Alert if more than 5 tasks are waiting
    return {
        "status": "degraded" if queue_depth > 5 else "ok",
        "queue_depth": queue_depth,
        "active_tasks": data.get("active_tasks", 0),
    }

Run this on port 8001, then add an HTTP monitor in Vigilmon:

URL: http://your-host:8001/queue-health
Expected body contains: "status":"ok"
Alert when body contains "degraded" → trigger your on-call channel

Step 4: Monitor Docker sandbox availability

SWE-agent runs every task inside a Docker container. If Docker is unavailable, all tasks fail at the execution step.

Check Docker availability with a TCP monitor on the Docker daemon socket (if exposed over TCP) or add a health check script:

# healthcheck-docker.sh — expose via a simple HTTP server
#!/bin/bash
docker info > /dev/null 2>&1
if [ $? -eq 0 ]; then
    echo -e "HTTP/1.1 200 OK\r\nContent-Length: 15\r\n\r\n{\"docker\":\"ok\"}"
else
    echo -e "HTTP/1.1 503 Service Unavailable\r\nContent-Length: 20\r\n\r\n{\"docker\":\"failed\"}"
fi

Serve this via netcat or a lightweight HTTP server on port 8002, then add an HTTP monitor in Vigilmon targeting http://your-host:8002/.

For simpler setups, just add a TCP Port monitor for port 2375 if Docker is exposed over TCP (Docker Desktop or dockerd -H tcp://0.0.0.0:2375).

Step 5: Monitor GitHub API connectivity

SWE-agent fetches issue details and submits pull requests via the GitHub API. Rate limit exhaustion silently blocks both operations.

Add a cron-based health check that probes GitHub API rate limits:

# github_health.py
import requests, os
from fastapi import FastAPI

app = FastAPI()
GITHUB_TOKEN = os.environ["GITHUB_TOKEN"]

@app.get("/github-health")
def github_health():
    r = requests.get(
        "https://api.github.com/rate_limit",
        headers={"Authorization": f"token {GITHUB_TOKEN}"},
        timeout=10,
    )
    data = r.json()
    remaining = data["rate"]["remaining"]
    return {
        "status": "degraded" if remaining < 100 else "ok",
        "rate_limit_remaining": remaining,
        "reset_at": data["rate"]["reset"],
    }

Add an HTTP monitor for this endpoint in Vigilmon:

URL: http://your-host:8003/github-health
Expected body contains: "status":"ok"
Check interval: 5 minutes

Step 6: Monitor LLM provider connectivity

SWE-agent depends on OpenAI GPT-4 or Claude as its reasoning backbone. Add a lightweight probe that validates the API key and measures response latency:

# llm_health.py
import openai, time, os
from fastapi import FastAPI

app = FastAPI()
client = openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"])

@app.get("/llm-health")
def llm_health():
    start = time.time()
    try:
        client.models.list()
        latency_ms = int((time.time() - start) * 1000)
        return {"status": "ok", "latency_ms": latency_ms}
    except openai.AuthenticationError:
        return {"status": "error", "reason": "invalid_api_key"}
    except openai.RateLimitError:
        return {"status": "degraded", "reason": "rate_limited"}
    except Exception as e:
        return {"status": "error", "reason": str(e)}

Add an HTTP monitor in Vigilmon for http://your-host:8004/llm-health checking for "status":"ok".

Step 7: Configure alerting

Route alerts based on severity:

Go to Alert Channels → Add Channel
Add a Slack channel for your engineering team and a PagerDuty/email channel for critical failures

Recommended routing:

| Monitor | Alert | Why | |---------|-------|-----| | API server (port 8000) | PagerDuty + Slack | Queue intake stops | | Queue depth | Slack | Agent may be stalled | | Docker availability | PagerDuty + Slack | All tasks fail | | GitHub API rate limit | Slack | PR submission fails | | LLM provider health | Slack | Tasks stall mid-execution |

Summary: SWE-agent monitor checklist

| Monitor | Type | Endpoint | Interval | |---------|------|----------|----------| | API server | HTTP | :8000/health | 1 min | | Task queue depth | HTTP | :8001/queue-health | 2 min | | Docker daemon | TCP/HTTP | :2375 or script | 2 min | | GitHub API rate limits | HTTP | :8003/github-health | 5 min | | LLM provider | HTTP | :8004/llm-health | 5 min |

With these monitors in place, you'll catch API server crashes, stalled agents, Docker failures, and LLM provider outages before they silently consume your task queue.

What's next

Heartbeat monitors — wrap long-running SWE-agent tasks with a heartbeat so you're alerted if a task exceeds its expected duration
Status page — publish a status page for your SWE-agent deployment so your team can check current operational status

Get started free at vigilmon.online — no credit card, monitors start running in under a minute.