Lightweight agent

Use the docker-compose based agent to monitor Linux hosts with minimal footprint. Follow the quick start, review the configuration reference, and troubleshoot the most common issues.

Back to documentation

Linux server

Docker Engine 20.10+

Docker Compose 1.29+

Quick start

# 1. Create the installation folder
mkdir -p /opt/checklogs && cd /opt/checklogs

# 2. Download docker-compose.yml
curl -o docker-compose.yml https://raw.githubusercontent.com/checklogsdev/Agent/main/docker-compose.yml

# 3. Create your configuration
cat > .env <<'EOF'
CHECKLOGS_API_KEY=your_api_key_from_dashboard
CHECKLOGS_API_PORT=your_udp_port_from_dashboard
SERVER_NAME=My Production Server
EOF

# 4. Start the agent
docker-compose up -d

# 5. Follow the logs
docker-compose logs -f

The server appears in the dashboard within 30 seconds when the credentials are valid.

Features

Real-time monitoring of CPU, RAM, disk, load, and processes every 10 seconds.
Alerting on thresholds defined in the dashboard.
Historical data for trend analysis.
Team collaboration with role-based access.
Low resource footprint (≈5% CPU, 50 MB RAM).
Secure communication with per-server API keys and dedicated UDP ports.

Configuration variables

Variable	Description	Example
`CHECKLOGS_API_KEY`	Your unique API key from the dashboard	`a1b2c3d4e5f6...`
`CHECKLOGS_API_PORT`	Dedicated UDP port assigned to the server	`9876`
`SERVER_NAME`	Display name in the UI	`Web Server 01`
`COLLECT_INTERVAL`	Metric collection interval in seconds (default 10)	`10`
`COLLECT_CPU` … `COLLECT_PROCESSES`	Enable or disable individual collectors (`true`/`false`)	`true`
`TOP_PROCESSES_COUNT`	Number of processes tracked for CPU/RAM	`10`
`LOG_LEVEL`	Log verbosity (`debug`, `info`, `warning`, `error`)	`info`

Useful commands

# Manage the agent
docker-compose up -d
docker-compose down
docker-compose restart

# Watch the logs
docker-compose logs -f
docker-compose logs --tail=100
docker-compose logs -f -t

# Update or remove
docker-compose pull
docker-compose up -d
docker-compose down -v

Troubleshooting

Agent offline?

docker-compose ps
docker-compose logs -f
cat .env | grep CHECKLOGS

Connectivity issues?

nc -u -v api.checklogs.dev 9876

Ensure outbound UDP traffic is allowed for the assigned port.

High resource usage?

Increase the collection interval (30 or 60 seconds).
Disable collectors that you do not need.
Lower the top process count and restart the agent.

Security & architecture

Each server uses a unique API key and UDP port.
Metrics are validated against your key before storage.
The server IP is detected automatically from UDP traffic.
Only members of your organisation can access collected data.
No sensitive payloads are transmitted—system metrics only.

┌─────────────────┐         UDP          ┌──────────────────┐
│  Your server    │    (Port 9876+)      │  CheckLogs API   │
│  Agent docker   │─────────────────────▶│  api.checklogs   │
│                 │   Metrics + key      │      .dev        │
└─────────────────┘                      └──────────────────┘
          │                                       │
          │ Collects every 10s                    ▼
          ▼                               ┌──────────────────┐
┌─────────────────┐                      │  Web dashboard    │
│  Host system    │                      │  checklogs.dev    │
│  CPU / RAM      │                      │  - Alerts         │
│  /proc, /sys    │                      │  - History        │
└─────────────────┘                      └──────────────────┘