Agent Installation

The StatusRadar Agent is a lightweight Python-based monitoring daemon that collects system metrics and plugin data from your servers. This guide will help you install and configure the agent on your Linux servers.

Quick Start

The fastest way to install the agent is using our one-line installer script:

TOKEN='your-agent-token-here' bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Note: Replace your-agent-token-here with your actual agent token from the dashboard.

Installation Methods

Method 1: Automatic Installation (Recommended)

The automatic installer handles everything for you:

• Downloads the latest agent version
• Installs Python dependencies
• Creates systemd service
• Configures the agent
• Starts monitoring

Basic Installation:

TOKEN='your-token' bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Installation with Plugins:

PLUGINS='redis,mysql,nginx' TOKEN='your-token' bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Method 2: Manual Installation

For more control over the installation process, follow these manual steps:

Step 1: Download the Agent

# Create directory
sudo mkdir -p /opt/statusradar
cd /opt/statusradar

# Download agent
sudo curl -sL https://statusradar.dev/agent/statusradar-agent.py -o statusradar-agent.py
sudo curl -sL https://statusradar.dev/agent/requirements.txt -o requirements.txt

# Download plugins
sudo mkdir -p plugins
cd plugins
sudo curl -sL https://statusradar.dev/agent/plugins/redis_plugin.py -o redis_plugin.py
# ... download other plugins as needed

Step 2: Install Dependencies

# Install Python 3 and pip (if not already installed)
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y python3 python3-pip python3-venv

# CentOS/RHEL/Rocky
sudo yum install -y python3 python3-pip

# Install agent dependencies
cd /opt/statusradar
sudo python3 -m pip install -r requirements.txt

Step 3: Create Configuration

The agent reads its settings from a shell environment file at /opt/statusradar/config.env (the systemd unit loads it via EnvironmentFile=). The automatic installer writes this for you; for a manual install, create it yourself:

# /opt/statusradar/config.env
API_TOKEN=your-agent-token-here
API_URL=https://api.statusradar.dev
INTERVAL=300

# Comma-separated list of enabled plugins (optional)
PLUGINS=redis,nginx

# Plugin settings — add only the ones your enabled plugins need
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
NGINX_STATUS_URL=http://127.0.0.1/nginx_status

Then lock it down so the token isn't world-readable:

sudo chmod 600 /opt/statusradar/config.env

Step 4: Create Systemd Service

Create /etc/systemd/system/statusradar-agent.service:

[Unit]
Description=StatusRadar Server Monitoring Agent
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/statusradar
EnvironmentFile=/opt/statusradar/config.env
ExecStart=/usr/bin/python3 /opt/statusradar/statusradar-agent.py --token ${API_TOKEN} --api-url ${API_URL} --interval ${INTERVAL}
Restart=always
RestartSec=30
StandardOutput=append:/var/log/statusradar/agent.log
StandardError=append:/var/log/statusradar/agent.log

[Install]
WantedBy=multi-user.target

Note: Settings come from EnvironmentFile=/opt/statusradar/config.env — don't hardcode the token in ExecStart. Create the log directory first (sudo mkdir -p /var/log/statusradar). On systemd older than v240 (CentOS/RHEL 7), replace the two Standard* lines with StandardOutput=journal and StandardError=journal.

Step 5: Start the Agent

# Reload systemd
sudo systemctl daemon-reload

# Enable agent to start on boot
sudo systemctl enable statusradar-agent

# Start the agent
sudo systemctl start statusradar-agent

# Check status
sudo systemctl status statusradar-agent

Plugin Installation

Plugins enable monitoring of specific services like databases, web servers, and caches.

Available Plugins

Installing Plugins

Redis Plugin Example

PLUGINS='redis' \
REDIS_HOST='localhost' \
REDIS_PORT='6379' \
TOKEN='your-token' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Multiple Plugins Example

PLUGINS='redis,mysql,nginx,memcached' \
REDIS_HOST='localhost' \
MYSQL_USER='monitor' \
MYSQL_PASSWORD='secret' \
NGINX_STATUS_URL='http://127.0.0.1/nginx_status' \
TOKEN='your-token' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

PostgreSQL Plugin Example

PLUGINS='postgresql' \
POSTGRESQL_HOST='localhost' \
POSTGRESQL_PORT='5432' \
POSTGRESQL_USER='postgres' \
POSTGRESQL_PASSWORD='secret' \
POSTGRESQL_DATABASE='postgres' \
TOKEN='your-token' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Plugin Configuration

Plugins are configured with environment variables in /opt/statusradar/config.env. List the plugins you want in PLUGINS= and add their variables, then restart the agent (sudo systemctl restart statusradar-agent):

# /opt/statusradar/config.env
PLUGINS=redis,mysql,nginx,docker

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# MySQL / MariaDB
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=monitor
MYSQL_PASSWORD=secret
MYSQL_DATABASE=

# Nginx (stub_status endpoint)
NGINX_STATUS_URL=http://127.0.0.1/nginx_status

# Docker
DOCKER_SOCKET=/var/run/docker.sock

The installer persists Redis, Docker, VictoriaMetrics and RabbitMQ variables automatically. For any other plugin (MySQL, PostgreSQL, Nginx, …) add its variables to config.env and restart. Each plugin's full variable list is on its plugin page.

Supported Operating Systems

The StatusRadar Agent supports all modern Linux distributions:

• Ubuntu: 18.04, 20.04, 22.04, 24.04
• Debian: 10 (Buster), 11 (Bullseye), 12 (Bookworm)
• CentOS: 7, 8, Stream 8, Stream 9
• RHEL: 7, 8, 9
• Rocky Linux: 8, 9
• Fedora: 36, 37, 38, 39
• Arch Linux: Latest
• Alpine Linux: 3.15+ (agent runs; install bash first and set up the service manually — automatic OpenRC setup is on the roadmap)

Note: The installer auto-detects your package manager (apt, dnf/yum, zypper, pacman, apk), so most modern distros work out of the box. Windows and macOS are not currently supported.

System Requirements

Minimum Requirements

• CPU: 1 core (shared)
• RAM: 50 MB
• Disk: 100 MB
• Python: 3.6 or later
• Network: HTTPS outbound access to api.statusradar.dev

Recommended Requirements

• CPU: 1 core (dedicated)
• RAM: 100 MB
• Disk: 500 MB (for logs)
• Python: 3.10 or later

Performance Impact

• CPU Usage: < 1% on average
• Memory Usage: ~20 MB base + 5-10 MB per plugin
• Network Usage: ~1 KB/min (basic metrics) + ~5 KB/min per plugin
• Disk I/O: Minimal (only during collection)

Verification

After installation, verify the agent is working:

Check Service Status

sudo systemctl status statusradar-agent

Expected output:

● statusradar-agent.service - StatusRadar Server Monitoring Agent
     Loaded: loaded (/etc/systemd/system/statusradar-agent.service; enabled)
     Active: active (running) since ...

Check Logs

sudo journalctl -u statusradar-agent -n 50 --no-pager

Look for successful metric collection messages:

INFO: Metrics collected successfully
INFO: Sent metrics to API

Check Dashboard

Visit the StatusRadar dashboard to see your server appear with live metrics.

Updating the Agent

To update the agent to the latest version, use the update mode:

curl -s https://statusradar.dev/install-agent.sh | sudo bash -s update

Or manually:

# Stop the agent
sudo systemctl stop statusradar-agent

# Download latest version
cd /opt/statusradar
sudo curl -sL https://statusradar.dev/agent/statusradar-agent.py -o statusradar-agent.py

# Restart the agent
sudo systemctl start statusradar-agent

Troubleshooting

Agent Not Starting

Check logs for errors:

sudo journalctl -u statusradar-agent -n 100 --no-pager

Common issues:

• Invalid token → Check /opt/statusradar/config.env
• Missing dependencies → Run pip3 install -r requirements.txt
• Permission denied → Service must run as root

Metrics Not Appearing

1. Verify agent is running: systemctl status statusradar-agent
2. Check network connectivity: curl -I https://api.statusradar.dev
3. Verify token is correct in dashboard
4. Check agent logs for API errors

Plugin Not Working

1. Verify plugin is enabled in config
2. Check plugin requirements (see plugin documentation)
3. Test plugin manually: python3 plugins/redis_plugin.py
4. Check service is running and accessible

Next Steps

• Configure the agent
• Add monitoring plugins
• Set up alerting
• Explore the API

Getting Help

• Troubleshooting Guide
• GitHub Issues
• Community Forum
• Email Support