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

Create /opt/statusradar/config/agent.yaml:

# StatusRadar Agent Configuration

api:
  url: https://api.statusradar.dev
  token: your-agent-token-here

agent:
  hostname: my-server-01
  interval: 300        # Collection interval in seconds
  timeout: 30          # API request timeout

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6379

Step 4: Create Systemd Service

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

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

[Service]
Type=simple
User=root
WorkingDirectory=/opt/statusradar
ExecStart=/usr/bin/python3 /opt/statusradar/statusradar-agent.py --token YOUR_TOKEN --api-url https://api.statusradar.dev --interval 300
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

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

Each plugin can be configured in /opt/statusradar/config/agent.yaml:

plugins:
  redis:
    enabled: true
    host: localhost
    port: 6379
    password: ''              # Optional
    ssl: false                # Optional

  mysql:
    enabled: true
    host: localhost
    port: 3306
    user: monitor
    password: secret
    database: ''              # Optional, for connection test

  nginx:
    enabled: true
    status_url: http://127.0.0.1/nginx_status

  docker:
    enabled: true
    socket: /var/run/docker.sock

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+

Note: Windows and macOS are not currently supported.

System Requirements

Minimum Requirements

• CPU: 1 core (shared)
• RAM: 50 MB
• Disk: 100 MB
• Python: 3.9 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:

TOKEN='your-token' bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)" 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/agent.yaml
• 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