Agent Installation

The UptimeO monitoring agent is a lightweight Go binary that executes HTTP monitors and submits heartbeats to the backend. It is distributed as the vibhuvioio/uptimeo-agent Docker image. This guide covers creating an agent record, generating an API key, and running one or more agents.

1. Create an Agent in the UI

Start the UptimeO server and log in as admin, then go to Agents in the sidebar and click New Agent.

Fill in the agent details:

• Name — e.g. agent-us-east-1
• Datacenter — optional; pick from the searchable list to group agents by physical location
• Description — optional

Save the agent. Copy the numeric Agent ID for the next steps.

2. Generate an API Key

Navigate to Admin → API Keys and create a new key.

Copy the key value immediately — it is shown only once. The key prefix is uptimeo_.

3. Run with Docker

Run a single agent:

docker run -d \
  --name agent-us-east-1 \
  -e API_BASE_URL="http://host.docker.internal:8080" \
  -e API_KEY="uptimeo_YOUR_API_KEY" \
  -e AGENT_ID=1 \
  -e CONFIG_RELOAD_INTERVAL="1m" \
  --restart unless-stopped \
  vibhuvioio/uptimeo-agent:latest

host.docker.internal lets the container reach an app running on your Docker host. On Linux, use the host's bridge IP instead.

Environment Variables

Valid interval examples: 1m, 5m, 1h, 24h.

4. Run Multiple Agents

For several agents (e.g. one per region), use a small Compose file — one service per agent:

name: uptimeo-agents

services:
  agent-us-east:
    image: vibhuvioio/uptimeo-agent:latest
    environment:
      AGENT_ID: "1"
      API_BASE_URL: http://host.docker.internal:8080
      API_KEY: ${UPTIMEO_API_KEY_US_EAST}
      CONFIG_RELOAD_INTERVAL: 1m
    restart: unless-stopped

  agent-eu-west:
    image: vibhuvioio/uptimeo-agent:latest
    environment:
      AGENT_ID: "2"
      API_BASE_URL: http://host.docker.internal:8080
      API_KEY: ${UPTIMEO_API_KEY_EU_WEST}
      CONFIG_RELOAD_INTERVAL: 1m
    restart: unless-stopped

docker compose up -d
docker compose logs -f

5. Verify the Agent

Check the agent health endpoint (map the port if you need it on the host):

docker logs agent-us-east-1

In the logs, look for:

• Acquired leadership — the agent is active
• Successful heartbeat posts
• Successfully flushed X queued heartbeats if the queue had backlog

Query recent heartbeats in PostgreSQL:

SELECT id, monitor_id, agent_id, executed_at, success, response_time_ms
FROM api_heartbeats
ORDER BY executed_at DESC
LIMIT 10;

Resilience Features

The agent is designed for unreliable networks:

• Automatic retry — exponential backoff for API failures
• Persistent queue — heartbeats are saved to disk if the API is unavailable
• Graceful recovery — the queue auto-flushes when the API returns
• No data loss — the agent does not crash due to API downtime

Troubleshooting

Next Steps

• Create HTTP monitors
• Deployment guide
• Uptime analytics