Server monitoring agent

Install the agent on a Linux server, configure it, and check that it is reporting.

The UptimeDuck monitoring agent is a lightweight, statically linked Go binary. It collects CPU (usage, load, IOWait), RAM (used, cached, swap), uptime, partition usage and read/write speeds, per-interface network traffic, and disk health through smartctl, then reports to the UptimeDuck API.

Requirements

Linux (Ubuntu, Debian, CentOS, etc.) with systemd, run as root (the installer exits with “Please run as root” otherwise). Windows is listed as Coming Soon in the panel.
CPU architecture x86_64 (amd64), aarch64/arm64, or armv7l/armv7.
curl to download the installer and the binary.
A server token from the panel.

1. Get a server token

Log in to panel.uptimeduck.com and open Server Monitors.
Add a new server (Connect New Server), choose Linux, give it a name and, optionally, a project.
Click Get Install Command. The panel shows the install command with your token already filled in.

If you leave this screen before installing, the server's page shows the same Installation Command under Waiting for Connection until the agent connects.

The panel installs the agent on servers with this script only; there is no Docker method for servers. On Kubernetes, use the Helm chart.

2. Install with the script

Run the command from the panel on your server:

curl -sL https://uptimeduck.com/download/agent/linux/install.sh | sudo bash -s -- --token=YOUR_SERVER_TOKEN

The installer:

detects the architecture and downloads uptimeduck-agent-linux-amd64, -arm64 or -armv7 from https://uptimeduck.com/download/agent/linux/;
installs smartmontools if it is missing (apt-get, yum, dnf, pacman, zypper or apk);
installs the agent to /opt/uptimeduck-agent and writes /opt/uptimeduck-agent/agent.json;
creates the systemd service uptimeduck-agent, then enables and starts it;
turns on the Docker monitoring plugin automatically when the docker command is found.

Installer options

Pass options after bash -s --, in the form --option=value.

Option	Default	Description
`--token=`	required	Server token from the panel. On reinstall it is read from the existing agent.json if omitted.
`--api-url=` / `--server=`	`https://api.uptimeduck.com`	Base URL of the UptimeDuck API.
`--interval=`	`60`	Reporting interval in seconds. The agent enforces a minimum of 60.
`--auto-update=`	`true`	Automatic agent updates. Use `no` or `false` to disable.
`--docker-enabled=`	auto-detected	Docker monitoring plugin. Use `no`/`false` or `yes`/`true`.
`--auto-start=`	`yes`	Enable and start the service after installing. Any other value only creates the service.

Example with options:

curl -sL https://uptimeduck.com/download/agent/linux/install.sh | sudo bash -s -- --token=YOUR_SERVER_TOKEN --interval=120 --auto-update=no

Manual install (without the script)

Download the binary for your architecture (amd64, arm64 or armv7) and run it once with your token. The example uses amd64. The agent saves the settings to agent.json next to the binary, so later runs need no arguments.

sudo mkdir -p /opt/uptimeduck-agent
cd /opt/uptimeduck-agent
sudo curl -L -o uptimeduck-agent-linux-amd64 https://uptimeduck.com/download/agent/linux/uptimeduck-agent-linux-amd64
sudo chmod +x uptimeduck-agent-linux-amd64
sudo ./uptimeduck-agent-linux-amd64 -server="https://api.uptimeduck.com" -token="YOUR_SERVER_TOKEN"

To run it as a service, create /etc/systemd/system/uptimeduck-agent.service:

[Unit]
Description=UptimeDuck Monitoring Agent
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/uptimeduck-agent
ExecStart=/opt/uptimeduck-agent/uptimeduck-agent-linux-amd64
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Use the binary name for your architecture, then:

sudo systemctl daemon-reload
sudo systemctl enable uptimeduck-agent
sudo systemctl start uptimeduck-agent

3. Configuration

The agent reads agent.json from the directory of its binary (/opt/uptimeduck-agent/agent.json when installed with the script). Command-line flags override the file and are saved back to it.

{
  "serverUrl": "https://api.uptimeduck.com",
  "token": "YOUR_SERVER_TOKEN",
  "interval": 60,
  "autoUpdate": true,
  "dockerEnabled": false
}

Key	Flag	Default	Description
`serverUrl`	`-server`, `-api-url`	`https://api.uptimeduck.com`	Base URL of the UptimeDuck API.
`token`	`-token`	—	Server token. Can also come from the `UPTIMEDUCK_TOKEN` environment variable.
`interval`	`-interval`	`60`	Reporting interval in seconds (minimum 60).
`autoUpdate`	`-auto-update`, `-autoupdate`	`true`	Install new agent versions automatically (Linux).
`allowRemoteConfig`	`-allow-remote-config`	`true`	Let settings be changed from the panel.
`errorReporting`	—	`true`	Send agent error reports to UptimeDuck.
`dockerEnabled`	`-docker-enabled`	`false`	Docker monitoring plugin.
`kubernetesEnabled`	`-kubernetes-enabled`	`false`	Kubernetes monitoring plugin (used by the Helm chart).

Remote configuration

With allowRemoteConfig set to true, the panel can change auto-update, error reporting, Docker and Kubernetes monitoring, and ask the agent to restart or update. Set it to false in agent.json and restart the agent to ignore settings from the panel.

Updates

The agent checks for a new version once a day. With auto-update on, Linux agents update themselves by re-running the installer. To update manually, run the installer again; it keeps the token and settings from the existing agent.json:

curl -sL https://uptimeduck.com/download/agent/linux/install.sh | sudo bash

4. Verify

In the panel, the install step shows Waiting for connection... and switches to Server Connected! as soon as the first report arrives. The server's page also updates automatically once the agent connects.
The installer ends with Service started! and Installation Complete!
The agent logs Check-in successful after each report. If it logs Error checking in instead, check the token and the API URL in agent.json.