@xoaurahiru/zyra-agent

Lightweight, security-focused monitoring agent for EC2 instances. Part of Project Lyra.

Features

• 📊 System Metrics: CPU, RAM, disk, network metrics every 30 seconds
• 🐳 Docker Log Collection: Automatically intercepts warnings and errors from containers
• 🔒 Security First: HMAC-signed requests, no remote access, events-only architecture
• 🚀 Easy Setup: CLI wizard, environment variables, or config file
• ⚡ Lightweight: Minimal resource footprint (~20MB RAM)

Installation

npm install -g @xoaurahiru/zyra-agent

Or with npx:

npx @xoaurahiru/zyra-agent start --deployment-id YOUR_ID --secret YOUR_SECRET

Quick Start

1. Get Your Credentials

1. Log in to Project Lyra Dashboard
2. Go to Settings → Zyra Deployments
3. Click New Deployment and copy your:
   • Deployment ID
   • Webhook Secret

2. Run the Agent

# Using CLI arguments
zyra-agent start --deployment-id YOUR_ID --secret YOUR_SECRET

# Using environment variables
export ZYRA_DEPLOYMENT_ID=your-deployment-id
export ZYRA_WEBHOOK_SECRET=your-64-char-secret
zyra-agent start

# Using config file
zyra-agent init  # Interactive setup
zyra-agent start --config ./zyra-agent.json

Configuration

Environment Variables

| Variable | Required | Description | Default | |----------|----------|-------------|---------| | ZYRA_DEPLOYMENT_ID | Yes | Your deployment ID | - | | ZYRA_WEBHOOK_SECRET | Yes | 64-char webhook secret | - | | ZYRA_API_URL | No | Lyra API endpoint | https://api.projectlyra.cloud | | ZYRA_METRICS_INTERVAL | No | Metrics interval (ms) | 30000 | | ZYRA_ENABLE_DOCKER_LOGS | No | Enable Docker logs | true | | ZYRA_CONTAINER_FILTER | No | Container name regex | .* | | ZYRA_DEBUG | No | Enable debug logging | false |

Config File

{
  "deploymentId": "your-deployment-id",
  "webhookSecret": "your-64-char-webhook-secret",
  "apiUrl": "https://api.projectlyra.cloud",
  "metricsInterval": 30000,
  "enableDockerLogs": true,
  "containerFilter": ".*",
  "debug": false
}

CLI Commands

# Start the agent
zyra-agent start [options]

# Generate config file interactively
zyra-agent init

# Test API connection
zyra-agent test

# Generate systemd service file
zyra-agent install-service

Options for start

| Option | Description | |--------|-------------| | -c, --config <path> | Path to config file | | -d, --deployment-id <id> | Deployment ID | | -s, --secret <secret> | Webhook secret | | -u, --api-url <url> | API URL | | -i, --interval <ms> | Metrics interval | | --no-docker | Disable Docker logs | | --debug | Enable debug logging | | --quiet | Suppress banner |

Programmatic Usage

import { createAgent, ZyraAgent } from '@xoaurahiru/zyra-agent';

const agent = createAgent({
  deploymentId: 'your-deployment-id',
  webhookSecret: 'your-webhook-secret',
  apiUrl: 'https://api.projectlyra.cloud',
  metricsInterval: 30000,
  enableDockerLogs: true,
});

// Event handlers
agent.on('started', () => console.log('Agent started'));
agent.on('metrics_sent', (metrics) => console.log('Metrics:', metrics));
agent.on('log_sent', (log) => console.log('Log:', log));
agent.on('error', (err) => console.error('Error:', err));

// Start monitoring
await agent.start();

// Stop when done
await agent.stop();

Running as a Service

systemd (Linux)

# Generate service file
zyra-agent install-service --config /etc/zyra-agent/config.json

# Install and enable
sudo cp zyra-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable zyra-agent
sudo systemctl start zyra-agent

# View logs
journalctl -u zyra-agent -f

Docker

FROM node:20-alpine
RUN npm install -g @xoaurahiru/zyra-agent
ENV ZYRA_DEPLOYMENT_ID=your-id
ENV ZYRA_WEBHOOK_SECRET=your-secret
CMD ["zyra-agent", "start"]

User Data (EC2)

#!/bin/bash
npm install -g @xoaurahiru/zyra-agent

cat > /etc/zyra-agent/config.json << 'EOF'
{
  "deploymentId": "your-deployment-id",
  "webhookSecret": "your-webhook-secret",
  "apiUrl": "https://api.projectlyra.cloud"
}
EOF

zyra-agent install-service
cp zyra-agent.service /etc/systemd/system/
systemctl enable --now zyra-agent

Security

This agent is designed with security as a top priority:

• Events Only: The agent can ONLY emit events. It cannot receive commands, execute code, or provide shell access.
• HMAC Signatures: All requests are signed with HMAC-SHA256 using your webhook secret.
• No Sensitive Data: The agent only collects system metrics and container logs - never credentials or secrets.
• TLS Only: All communication uses HTTPS.
• Minimal Permissions: Runs with least privilege. Only needs read access to Docker socket.

Metrics Collected

| Metric | Description | |--------|-------------| | cpu_usage_percent | Current CPU utilization | | cpu_cores | Number of CPU cores | | memory_usage_percent | RAM utilization | | memory_used_mb | RAM used in MB | | disk_usage_percent | Disk utilization | | disk_used_gb | Disk used in GB | | network_rx_bytes | Network received bytes | | network_tx_bytes | Network transmitted bytes | | load_average | System load (1, 5, 15 min) | | uptime_seconds | System uptime | | processes_count | Number of running processes |

EC2 Instance Metadata

When running on EC2, the agent automatically detects:

• Instance ID
• Instance Type
• Region
• Availability Zone
• Private/Public IP

Troubleshooting

Agent won't start

# Check configuration
zyra-agent test --config ./zyra-agent.json

# Enable debug logging
zyra-agent start --debug

Docker logs not collecting

# Check Docker socket permissions
ls -la /var/run/docker.sock

# Add user to docker group (then re-login)
sudo usermod -aG docker $USER

Connection issues

# Test API connectivity
curl -I https://api.projectlyra.cloud/health

# Check firewall rules
sudo iptables -L -n | grep 443

Support

• Documentation: projectlyra.cloud/docs
• Issues: GitHub Issues

License

MIT © xoaurahiru