agent

README

Monify Agent

Lightweight system monitoring agent for Monify platform

Features • Installation • Usage • Configuration • Development

---

🚀 Features

• 🔒 Secure Authentication: Token-based authentication with the Monify platform
• 📊 Comprehensive Monitoring: CPU, Memory, Disk, Network, and System metrics
• 🔍 Port Scanning: Built-in port scanner for security auditing
• ⚡ Real-time Updates: Configurable collection intervals (default: 30s)
• 🎛️ Remote Control: Receive and execute commands from the Monify server
• 🔄 Auto-reload: Dynamic configuration updates without restart
• 📝 Flexible Logging: JSON or text format, file or stdout
• 🛡️ Single Instance: Prevents multiple agents from running simultaneously
• 💾 Optimized Bandwidth: Gzip compression and smart static/dynamic metric separation
• ⏸️ Pause/Resume: Agent pauses when disabled, auto-resumes when enabled
• 🗑️ Auto-Uninstall: Automatically removes itself when server is deleted

📦 Installation

Quick Install

# Automated installation (recommended)
curl -fsSL https://get.monify.cloud/install.sh | sudo bash

# Or manual installation
wget https://github.com/monify-labs/agent/releases/latest/download/monify-agent-linux-amd64
sudo mv monify-agent-linux-amd64 /usr/local/bin/monify-agent
sudo chmod +x /usr/local/bin/monify-agent

Platform-Specific Binaries

# Linux AMD64
wget https://github.com/monify-labs/agent/releases/latest/download/monify-agent-linux-amd64

# Linux ARM64
wget https://github.com/monify-labs/agent/releases/latest/download/monify-agent-linux-arm64

# macOS AMD64
wget https://github.com/monify-labs/agent/releases/latest/download/monify-agent-darwin-amd64

# macOS ARM64 (Apple Silicon)
wget https://github.com/monify-labs/agent/releases/latest/download/monify-agent-darwin-arm64

# Windows AMD64
wget https://github.com/monify-labs/agent/releases/latest/download/monify-agent-windows-amd64.exe

Systemd Service Setup

# Create systemd service
sudo tee /etc/systemd/system/monify-agent.service > /dev/null <<EOF
[Unit]
Description=Monify Monitoring Agent
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/monify-agent
Restart=always
RestartSec=10
Environment="TOKEN_DEVICE=your-token-here"

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable monify-agent
sudo systemctl start monify-agent

# Check status
sudo systemctl status monify-agent

Option 3: Build from Source

git clone https://github.com/monify-labs/agent.git
cd agent
make build
sudo make install

🎯 Quick Start

1. Authenticate

# Get your token from https://app.monify.cloud/settings/tokens
sudo monify-agent login YOUR_TOKEN_HERE

2. Start the Agent

# Using systemd (recommended)
sudo systemctl start monify-agent
sudo systemctl enable monify-agent  # Auto-start on boot

# Or run directly
sudo monify-agent

3. Check Status

monify-agent status

📖 Usage

Commands

# Authenticate with token
sudo monify-agent login <token>

# Remove authentication
sudo monify-agent logout

# Show agent status
monify-agent status

# Show version
monify-agent version

# Show help
monify-agent help

# Run as daemon (usually via systemd)
sudo monify-agent [flags]

Daemon Flags

-config string      Path to configuration file (default "/etc/monify-agent/config.yaml")
-lock-dir string    Directory for lock file (default "/var/run")
-version           Show version information

Systemd Management

# Start agent
sudo systemctl start monify-agent

# Stop agent
sudo systemctl stop monify-agent

# Restart agent
sudo systemctl restart monify-agent

# Enable auto-start
sudo systemctl enable monify-agent

# View logs
sudo journalctl -u monify-agent -f

# Reload configuration (SIGHUP)
sudo systemctl reload monify-agent

⚙️ Configuration

Configuration File

Default location: /etc/monify-agent/config.yaml

# Server configuration
server:
  url: "https://api.monify.cloud/v1/metrics"
  token: ""  # Set via 'monify-agent login' or TOKEN_DEVICE env var
  timeout: 10s
  tls:
    enabled: true
    insecure_skip_verify: false

# Agent identification
agent:
  hostname: ""  # Auto-detected if not set
  version: "1.0.0"

# Collection settings
collection:
  interval: 30s  # Can be updated remotely by server

# Metrics to collect
metrics:
  cpu: true
  memory: true
  disk: true
  network: true
  system: true

# Port scanner settings
port_scanner:
  enabled: true
  timeout: 5s
  max_workers: 100

# Logging configuration
logging:
  level: "info"  # debug, info, warn, error
  format: "text"  # text, json
  file: ""  # Empty for stdout, or path to log file

Environment Variables

Environment variables override config file settings:

TOKEN_DEVICE                  # Authentication token
MONIFY_SERVER_URL             # Server URL
MONIFY_HOSTNAME               # Hostname override
MONIFY_LOG_LEVEL              # Log level
MONIFY_COLLECTION_INTERVAL    # Collection interval (e.g., "30s", "1m")

Docker Environment Variables

docker run -d \
  -e TOKEN_DEVICE=your_token \
  -e MONIFY_SERVER_URL=https://api.monify.cloud/v1/metrics \
  -e MONIFY_LOG_LEVEL=debug \
  -e MONIFY_COLLECTION_INTERVAL=60s \
  monify/agent:latest

🔧 Server Commands

The agent can receive and execute commands from the Monify server:

update_config

Update collection interval dynamically:

{
  "command": "update_config",
  "params": {
    "collection_interval": "60s"
  }
}

refresh

Trigger immediate metric collection:

{
  "command": "refresh"
}

scan_ports

Perform port scan:

{
  "command": "scan_ports",
  "params": {
    "target": "192.168.1.1",
    "ports": [22, 80, 443, 3306]
  }
}

📊 Metrics Collected

Static Metrics (sent once or when changed)

• Platform information (OS, distribution, version)
• Hardware specs (CPU model, cores, total RAM)
• Network configuration (IPs, hostname, FQDN)
• Virtualization type
• Timezone and region

Dynamic Metrics (sent every interval)

• CPU: Usage percentage, per-core usage, load averages
• Memory: Total, used, free, available, cached, buffers, swap
• Disk: Usage per mount point, I/O statistics, inode usage
• Network: Bytes/packets sent/received, errors, drops per interface
• System: Uptime, boot time, process count

🐳 Docker Deployment

Using Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  monify-agent:
    image: monify/agent:latest
    container_name: monify-agent
    restart: unless-stopped
    environment:
      - TOKEN_DEVICE=${TOKEN_DEVICE}
      - MONIFY_SERVER_URL=${MONIFY_SERVER_URL:-https://api.monify.cloud/v1/metrics}
      - MONIFY_LOG_LEVEL=${MONIFY_LOG_LEVEL:-info}
      - MONIFY_COLLECTION_INTERVAL=${MONIFY_COLLECTION_INTERVAL:-30s}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro  # Optional: for container monitoring
    network_mode: host  # Required for accurate network metrics

Run:

export TOKEN_DEVICE=your_token_here
docker-compose up -d

Building Custom Image

# Build
docker build -t monify-agent:custom .

# Run
docker run -d \
  --name monify-agent \
  --restart unless-stopped \
  -e TOKEN_DEVICE=your_token \
  monify-agent:custom

🛠️ Development

Prerequisites

• Go 1.21 or higher
• Make (optional, for convenience)

Setup

# Clone repository
git clone https://github.com/monify-labs/agent.git
cd agent

# Install dependencies
go mod download

# Build
make build

# Run tests
make test

# Run locally
go run cmd/agent/main.go -config ./config.yaml

Project Structure

.
├── cmd/
│   └── agent/          # Main application entry point
├── internal/
│   ├── agent/          # Core agent logic
│   ├── collector/      # Metric collectors
│   ├── scanner/        # Port scanner
│   └── sender/         # HTTP sender
├── pkg/
│   ├── config/         # Configuration management
│   ├── lock/           # Single instance lock
│   └── models/         # Data models
├── scripts/            # Installation scripts
├── config.yaml.example # Example configuration
├── Dockerfile          # Docker image
├── docker-compose.yml  # Docker Compose config
└── Makefile           # Build automation

Building

# Build for current platform
make build

# Build for all platforms
make build-all

# Build Docker image
make docker-build

# Run tests
make test

# Run linter
make lint

# Clean build artifacts
make clean

🔒 Security

• Token Storage: Tokens are stored in /etc/monify-agent/config.yaml with 0644 permissions
• TLS: All communication with the server uses HTTPS by default
• Single Instance: Lock file prevents multiple instances
• Minimal Privileges: Agent should run as root for full system access, but can run as limited user with reduced metrics

🐛 Troubleshooting

Agent won't start

# Check if another instance is running
ps aux | grep monify-agent

# Check lock file
ls -la /var/run/monify-agent.lock

# Check logs
sudo journalctl -u monify-agent -n 50

Authentication issues

# Verify token is set
monify-agent status

# Re-authenticate
sudo monify-agent logout
sudo monify-agent login YOUR_NEW_TOKEN

Permission denied errors

# Ensure running as root for full metrics
sudo monify-agent

# Or use systemd
sudo systemctl start monify-agent

High CPU/Memory usage

# Increase collection interval
# Edit /etc/monify-agent/config.yaml
collection:
  interval: 60s  # Increase from 30s

# Restart agent
sudo systemctl restart monify-agent

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📧 Support

• 📖 Documentation: https://docs.monify.cloud
• 💬 Discord: https://discord.gg/monify
• 🐛 Issues: https://github.com/monify-labs/agent/issues
• 📧 Email: support@monify.cloud

---

Made with ❤️ by the Monify Team