Guide

Agent Deployment Guide

Install and configure the UptimeGrid agent so it can run health checks from any network you control.

Overview

The UptimeGrid agent is a lightweight Node.js process that runs on your source servers. On each polling cycle it:

Fetches its assigned monitors from the hub.
Runs health checks — HTTP, TCP, ping, and DNS.
Pushes heartbeat results back to the hub.
When a monitor is down, automatically runs diagnostics (DNS, ping, port check) and pushes results.

The agent has zero npm dependencies — it uses only Node.js built-in modules.

Requirements

Node.js 22+ for a direct install.
Or Docker / Kubernetes (Node.js is bundled in the container image).

Prerequisites

Go to the Agents page in the dashboard and click "Add Agent".

Give the agent a name and select a source location.

Copy the API key — it is shown only once.

Deploy

One command to install, configure, and start the agent as a service:

curl -sSL https://uptimegrid.net/install.sh | sudo UPTIMEGRID_API_KEY=your-api-key bash

This downloads the agent to /opt/uptimegrid-agent, creates a systemd service, and starts it automatically.

Or install manually:

curl -O https://uptimegrid.net/downloads/uptimegrid-agent.tar.gz
tar xzf uptimegrid-agent.tar.gz
cd agent

Create agent.config.json in the same directory:

{
  "apiKey": "your-api-key"
}

Start the agent:

node index.js

Optional: systemd service

[Unit]
Description=UptimeGrid Agent
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/uptimegrid-agent
ExecStart=/usr/bin/node index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable --now uptimegrid-agent

Configuration Reference

Field	Type	Required	Description
apiKey UPTIMEGRID_API_KEY	string	Yes	API key from the dashboard Agents page.

Note: Environment variables take precedence. If both an env var and a config-file value are set, the env var wins. agent.config.json is loaded from the same directory as index.js.

Verify

After starting the agent you should see output similar to:

[UptimeGrid Agent] 2026-04-19T10:00:00.000Z Starting...
[UptimeGrid Agent] 2026-04-19T10:00:00.000Z Hub: https://api.uptimegrid.net
[UptimeGrid Agent] 2026-04-19T10:00:00.500Z Fetched 3 monitor(s) from hub
[UptimeGrid Agent] 2026-04-19T10:00:00.500Z Scheduled monitor 1 (http) every 60s
[UptimeGrid Agent] 2026-04-19T10:00:00.500Z Running. Press Ctrl+C to stop.

In the dashboard, navigate to the Agentspage. The agent's status should show "Online" with the last_seen timestamp updating on every heartbeat.

Manage Agent

Linux / macOS (systemd)

Check status

sudo systemctl status uptimegrid-agent

View logs

journalctl -u uptimegrid-agent -f

Stop the agent

sudo systemctl stop uptimegrid-agent

Start the agent

sudo systemctl start uptimegrid-agent

Restart the agent

sudo systemctl restart uptimegrid-agent

Update the API key

sudo nano /opt/uptimegrid-agent/agent.config.json
# Change the "apiKey" value, then:
sudo systemctl restart uptimegrid-agent

Uninstall the agent

sudo systemctl stop uptimegrid-agent
sudo systemctl disable uptimegrid-agent
sudo rm /etc/systemd/system/uptimegrid-agent.service
sudo systemctl daemon-reload
sudo rm -rf /opt/uptimegrid-agent

Windows Server (NSSM)

Check status

nssm status UptimeGridAgent

Stop the agent

nssm stop UptimeGridAgent

Start the agent

nssm start UptimeGridAgent

Restart the agent

nssm restart UptimeGridAgent

Update the API key

notepad C:\uptimegrid-agent\agent.config.json
# Change the "apiKey" value, save, then:
nssm restart UptimeGridAgent

Uninstall the agent

nssm stop UptimeGridAgent
nssm remove UptimeGridAgent confirm
Remove-Item -Recurse -Force C:\uptimegrid-agent

Note: After uninstalling the agent from the server, go to the Agents page in the dashboard and delete the agent entry to clean up.

Troubleshooting

Missing apiKey

Copy the API key from the dashboard Agents page. If you lost it, regenerate a new key.

Failed to fetch config from hub

Verify the agent can reach api.uptimegrid.net. Check firewall rules and DNS resolution.

Fetched 0 monitors

Assign at least one monitor to this agent's source location in the dashboard.

Agent shows "offline" in dashboard

Confirm the agent process is running and the API key is correct.