aimon-agent

Lightweight server monitoring agent for the AIMON ecosystem. Collects real-time system metrics and reports them securely to your AIMON dashboard.

Table of Contents

• Overview
• Prerequisites
• Installation
• Quick Start
• Configuration
• CLI Commands
• How It Works
• Metrics Collected
• API Reference
• Security
• Troubleshooting
• Uninstallation

Overview

aimon-agent is a globally installable Node.js CLI tool designed to run on Linux servers. It acts as the infrastructure-level data collector for the AIMON monitoring ecosystem — bridging your servers and the AIMON dashboard by securely transmitting real-time system performance metrics.

Ideal for:

• Production server monitoring
• Cloud VM monitoring (AWS, DigitalOcean, GCP, etc.)
• DevOps infrastructure tracking
• Lightweight alternative to heavy monitoring agents

Prerequisites

Before installing, make sure your server meets the following requirements:

| Requirement | Minimum Version | | ----------- | ------------------------- | | Node.js | v14 or higher | | npm | v6 or higher | | OS | Linux (any major distro) | | Network | Outbound HTTPS (port 443) |

To verify your Node.js and npm versions:

node --version
npm --version

Installation

Install the agent globally using npm:

npm install -g aimon-agent

Verify the installation was successful:

aimon-agent --version

You should see the current version number printed to the terminal.

Quick Start

Get up and running in two steps.

Step 1 — Set up your server token

Grab your unique server token from the AIMON Dashboard and run:

aimon-agent init

You will be prompted to enter your server token. This token is saved locally and used to authenticate all metric reports.

Step 2 — Start the agent

aimon-agent start

The agent will begin collecting and sending metrics to your AIMON dashboard immediately. That's it!

Configuration

Generating a Server Token

1. Log in to your AIMON Dashboard.
2. Navigate to Servers → Add New Server.
3. Copy the generated token.
4. Run aimon-agent init on your server and paste the token when prompted.

Each server must have its own unique token. Tokens can be revoked at any time from the dashboard.

Token Storage

The token is stored locally on your server. All API requests authenticate using:

Authorization: Bearer <SERVER_TOKEN>

CLI Commands

| Command | Description | | ----------------------- | -------------------------------------------- | | aimon-agent init | Configure your server token | | aimon-agent start | Start metrics collection and reporting | | aimon-agent stop | Stop the monitoring agent | | aimon-agent status | Check whether the agent is currently running | | aimon-agent --version | Display the installed version |

Examples

# First-time init
aimon-agent init

# Start monitoring
aimon-agent start

# Check if the agent is running
aimon-agent status

# Stop the agent
aimon-agent stop

How It Works

Your Linux Server
      │
      ▼
  aimon-agent
  (Collects Metrics)
      │
      ▼
  HTTPS POST Request
  (with Bearer Token)
      │
      ▼
  AIMON Backend API
      │
      ▼
  Dashboard Visualization

1. After running aimon-agent start, the agent runs as a background process.
2. Every few seconds (default: every 5 seconds), it collects system metrics.
3. Metrics are sent via a secure HTTPS POST request to the AIMON backend API.
4. Your dashboard updates in real time with the incoming data.

Metrics Collected

The agent collects and reports the following system metrics:

| Metric | Description | | ------------- | ------------------------------- | | hostname | Server hostname | | cpuUsage | Current CPU usage percentage | | memoryUsage | Current memory usage percentage | | uptime | System uptime in seconds | | OS info | Operating system details |

Example payload sent to the API:

{
  "hostname": "server-01",
  "cpuUsage": 32.5,
  "memoryUsage": 68.2,
  "uptime": 123456
}

API Reference

Metrics are reported to the following endpoint:

POST /api/metrics
Content-Type: application/json
Authorization: Bearer <SERVER_TOKEN>

Request Body:

{
  "hostname": "string",
  "cpuUsage": "number",
  "memoryUsage": "number",
  "uptime": "number"
}

All communication is over HTTPS to ensure data is encrypted in transit.

Security

• Unique tokens — Each server uses its own token; no two servers share credentials.
• HTTPS only — All communication is encrypted using TLS.
• Authorization header — Tokens are sent via Authorization: Bearer, never in the URL.
• Token revocation — Tokens can be revoked instantly from the AIMON dashboard if a server is compromised or decommissioned.

Best practice: Never share your server token or commit it to version control.

Troubleshooting

Agent won't start

Make sure your token is configured correctly:

aimon-agent init
aimon-agent start

Cannot connect to AIMON API

Check that your server allows outbound HTTPS traffic on port 443. If you're behind a firewall, whitelist the AIMON API domain.

Check agent status

aimon-agent status

Reinstall the agent

npm uninstall -g aimon-agent
npm install -g aimon-agent
aimon-agent init
aimon-agent start

Uninstallation

To remove the agent from your server:

# Stop the agent first
aimon-agent stop

# Uninstall the package
npm uninstall -g aimon-agent

License

MIT © AIMON

Need help? Open an issue on the GitHub repository or contact support via the AIMON dashboard.