lobsterboard-agent 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# 🦞 LobsterBoard Agent
+
+A lightweight stats agent for remote [LobsterBoard](https://github.com/Curbob/LobsterBoard) monitoring. Run it on your VPS or remote servers, then connect from your local LobsterBoard dashboard.
+
+## Features
+
+- **System stats** — CPU, memory, disk, network, uptime
+- **Docker stats** — Container list and status (optional)
+- **OpenClaw stats** — Cron jobs, sessions, gateway status (optional)
+- **API key auth** — Secure access to your server stats
+- **Lightweight** — Minimal footprint, runs anywhere Node runs
+- **Multi-server** — Monitor multiple servers from one LobsterBoard
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g lobsterboard-agent
+
+# Initialize (generates API key)
+lobsterboard-agent init
+
+# Start the agent
+lobsterboard-agent serve
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize config and generate API key |
+| `serve` | Start the stats server |
+| `rotate-key` | Generate a new API key (invalidates old one) |
+| `show-key` | Display current API key |
+| `status` | Show agent configuration |
+
+## Options
+
+```bash
+lobsterboard-agent serve --port=9090    # Custom port (default: 9090)
+lobsterboard-agent serve --host=0.0.0.0 # Bind address (default: 0.0.0.0)
+lobsterboard-agent serve --name=prod-1  # Server name for identification
+```
+
+## API Endpoints
+
+All endpoints require the `X-API-Key` header.
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /stats` | Full system stats (JSON) |
+| `GET /health` | Health check |
+
+### Example Request
+
+```bash
+curl -H "X-API-Key: sk_your_key_here" http://your-server:9090/stats
+```
+
+### Example Response
+
+```json
+{
+  "serverName": "prod-vps-1",
+  "timestamp": "2026-03-07T12:00:00.000Z",
+  "hostname": "vps-12345",
+  "platform": "linux",
+  "distro": "Ubuntu",
+  "uptime": 1234567,
+  "cpu": {
+    "model": "Intel Xeon",
+    "cores": 2,
+    "usage": 12.5
+  },
+  "memory": {
+    "total": 2147483648,
+    "used": 1073741824,
+    "percent": 50.0
+  },
+  "disk": {
+    "total": 42949672960,
+    "used": 21474836480,
+    "percent": 50.0
+  },
+  "network": {
+    "rxSec": 1024,
+    "txSec": 512
+  },
+  "docker": {
+    "available": true,
+    "running": 3,
+    "total": 5,
+    "containers": [...]
+  },
+  "openclaw": {
+    "installed": true,
+    "gateway": { "running": true },
+    "cron": { "total": 5, "enabled": 4 },
+    "sessions": { "total": 12, "recent24h": 3 }
+  }
+}
+```
+
+## Configuration
+
+Config is stored in `~/.lobsterboard-agent/config.json`:
+
+```json
+{
+  "apiKey": "sk_...",
+  "port": 9090,
+  "host": "0.0.0.0",
+  "serverName": "my-vps",
+  "enableDocker": true,
+  "enableOpenClaw": true
+}
+```
+
+## Run as Service
+
+### systemd (Linux)
+
+```bash
+sudo cat > /etc/systemd/system/lobsterboard-agent.service << 'EOF'
+[Unit]
+Description=LobsterBoard Agent
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+ExecStart=/usr/bin/lobsterboard-agent serve
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+sudo systemctl enable lobsterboard-agent
+sudo systemctl start lobsterboard-agent
+```
+
+### pm2
+
+```bash
+pm2 start lobsterboard-agent -- serve
+pm2 save
+pm2 startup
+```
+
+## Connecting from LobsterBoard
+
+In LobsterBoard, add a **Remote Server** widget and configure:
+
+- **URL**: `http://your-server:9090`
+- **API Key**: Your agent's API key
+
+You can add multiple widgets for multiple servers.
+
+## Security
+
+- Always use an API key (never disable it)
+- Consider running behind a reverse proxy with HTTPS
+- Use firewall rules to limit access by IP if possible
+- Rotate keys periodically with `lobsterboard-agent rotate-key`
+
+## License
+
+MIT
+
+---
+
+Made with 🦞 by [Curbob](https://github.com/Curbob)

package/bin/agent.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+/**
+ * LobsterBoard Agent CLI
+ * 
+ * Commands:
+ *   init        - Initialize config and generate API key
+ *   serve       - Start the stats server
+ *   rotate-key  - Generate a new API key
+ *   show-key    - Display current API key
+ *   status      - Show agent status
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+
+const CONFIG_DIR = path.join(os.homedir(), '.lobsterboard-agent');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+const DEFAULT_CONFIG = {
+  apiKey: null,
+  port: 9090,
+  host: '0.0.0.0',
+  enableDocker: true,
+  enableOpenClaw: true,
+  serverName: os.hostname(),
+};
+
+// Ensure config directory exists
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+// Load config
+function loadConfig() {
+  ensureConfigDir();
+  if (fs.existsSync(CONFIG_FILE)) {
+    try {
+      return { ...DEFAULT_CONFIG, ...JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')) };
+    } catch (e) {
+      console.error('Error reading config:', e.message);
+      return { ...DEFAULT_CONFIG };
+    }
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+// Save config
+function saveConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+// Generate API key
+function generateApiKey() {
+  return 'sk_' + crypto.randomBytes(24).toString('base64url');
+}
+
+// Commands
+const commands = {
+  init() {
+    const config = loadConfig();
+    if (config.apiKey) {
+      console.log('Config already exists.');
+      console.log('Use "lobsterboard-agent rotate-key" to generate a new key.');
+      console.log('\nCurrent config:', CONFIG_FILE);
+      return;
+    }
+    
+    config.apiKey = generateApiKey();
+    saveConfig(config);
+    
+    console.log('✅ LobsterBoard Agent initialized!\n');
+    console.log('Your API key (save this!):\n');
+    console.log(`   ${config.apiKey}\n`);
+    console.log('Config saved to:', CONFIG_FILE);
+    console.log('\nStart the agent with:');
+    console.log('   lobsterboard-agent serve');
+  },
+
+  serve() {
+    const config = loadConfig();
+    
+    if (!config.apiKey) {
+      console.error('No API key configured. Run "lobsterboard-agent init" first.');
+      process.exit(1);
+    }
+    
+    // Import and start server
+    const { startServer } = require('../lib/server.js');
+    startServer(config);
+  },
+
+  'rotate-key'() {
+    const config = loadConfig();
+    const oldKey = config.apiKey;
+    config.apiKey = generateApiKey();
+    saveConfig(config);
+    
+    console.log('✅ API key rotated!\n');
+    if (oldKey) {
+      console.log('Old key (now invalid):', oldKey.slice(0, 10) + '...');
+    }
+    console.log('New key:', config.apiKey);
+    console.log('\nRestart the agent to apply.');
+  },
+
+  'show-key'() {
+    const config = loadConfig();
+    if (!config.apiKey) {
+      console.log('No API key configured. Run "lobsterboard-agent init" first.');
+      return;
+    }
+    console.log('API Key:', config.apiKey);
+  },
+
+  status() {
+    const config = loadConfig();
+    console.log('LobsterBoard Agent Status\n');
+    console.log('Config file:', CONFIG_FILE);
+    console.log('API key:', config.apiKey ? config.apiKey.slice(0, 10) + '...' : '(not set)');
+    console.log('Port:', config.port);
+    console.log('Host:', config.host);
+    console.log('Server name:', config.serverName);
+    console.log('Docker stats:', config.enableDocker ? 'enabled' : 'disabled');
+    console.log('OpenClaw stats:', config.enableOpenClaw ? 'enabled' : 'disabled');
+  },
+
+  help() {
+    console.log(`
+LobsterBoard Agent - Remote stats for LobsterBoard dashboards
+
+Usage: lobsterboard-agent <command> [options]
+
+Commands:
+  init          Initialize config and generate API key
+  serve         Start the stats server
+  rotate-key    Generate a new API key (invalidates old one)
+  show-key      Display current API key
+  status        Show agent configuration
+  help          Show this help
+
+Options:
+  --port=PORT   Override port (default: 9090)
+  --host=HOST   Override host (default: 0.0.0.0)
+  --name=NAME   Set server name for identification
+
+Examples:
+  lobsterboard-agent init
+  lobsterboard-agent serve
+  lobsterboard-agent serve --port=8888
+`);
+  }
+};
+
+// Parse args
+const args = process.argv.slice(2);
+let command = args[0] || 'help';
+
+// Parse options
+const options = {};
+args.slice(1).forEach(arg => {
+  const match = arg.match(/^--(\w+)=(.+)$/);
+  if (match) {
+    options[match[1]] = match[2];
+  }
+});
+
+// Apply option overrides to config for serve command
+if (command === 'serve' && Object.keys(options).length > 0) {
+  const config = loadConfig();
+  if (options.port) config.port = parseInt(options.port, 10);
+  if (options.host) config.host = options.host;
+  if (options.name) config.serverName = options.name;
+  saveConfig(config);
+}
+
+// Run command
+if (commands[command]) {
+  commands[command]();
+} else {
+  console.error(`Unknown command: ${command}`);
+  commands.help();
+  process.exit(1);
+}

package/lib/docker.js

@@ -0,0 +1,51 @@
+/**
+ * Docker stats collection (optional)
+ */
+
+const { exec } = require('child_process');
+const { promisify } = require('util');
+
+const execAsync = promisify(exec);
+
+async function collectDockerStats() {
+  try {
+    // Check if Docker is available
+    await execAsync('docker info', { timeout: 5000 });
+  } catch (e) {
+    return { available: false };
+  }
+
+  try {
+    // Get container list
+    const { stdout } = await execAsync(
+      'docker ps --format "{{.ID}}|{{.Names}}|{{.Status}}|{{.Image}}"',
+      { timeout: 10000 }
+    );
+
+    const containers = stdout.trim().split('\n').filter(Boolean).map(line => {
+      const [id, name, status, image] = line.split('|');
+      return {
+        id: id?.slice(0, 12),
+        name,
+        status,
+        image,
+        running: status?.toLowerCase().includes('up'),
+      };
+    });
+
+    // Get counts
+    const { stdout: allCount } = await execAsync('docker ps -aq | wc -l', { timeout: 5000 });
+    const { stdout: runningCount } = await execAsync('docker ps -q | wc -l', { timeout: 5000 });
+
+    return {
+      available: true,
+      total: parseInt(allCount.trim(), 10) || 0,
+      running: parseInt(runningCount.trim(), 10) || 0,
+      containers: containers.slice(0, 20), // Limit to 20
+    };
+  } catch (e) {
+    return { available: true, error: e.message };
+  }
+}
+
+module.exports = { collectDockerStats };

package/lib/openclaw.js

@@ -0,0 +1,83 @@
+/**
+ * OpenClaw stats collection (optional)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const OPENCLAW_DIR = path.join(os.homedir(), '.openclaw');
+const CRON_FILE = path.join(OPENCLAW_DIR, 'cron', 'jobs.json');
+const SESSIONS_DIR = path.join(OPENCLAW_DIR, 'sessions');
+
+async function collectOpenClawStats() {
+  // Check if OpenClaw is installed
+  if (!fs.existsSync(OPENCLAW_DIR)) {
+    return { installed: false };
+  }
+
+  const stats = { installed: true };
+
+  // Cron jobs
+  try {
+    if (fs.existsSync(CRON_FILE)) {
+      const data = JSON.parse(fs.readFileSync(CRON_FILE, 'utf8'));
+      const jobs = data.jobs || [];
+      stats.cron = {
+        total: jobs.length,
+        enabled: jobs.filter(j => j.enabled !== false).length,
+        jobs: jobs.slice(0, 10).map(j => ({
+          name: j.name,
+          schedule: j.schedule?.expr || j.schedule?.kind,
+          enabled: j.enabled !== false,
+        })),
+      };
+    }
+  } catch (e) {
+    stats.cron = { error: e.message };
+  }
+
+  // Sessions (count recent activity)
+  try {
+    if (fs.existsSync(SESSIONS_DIR)) {
+      const sessionFiles = fs.readdirSync(SESSIONS_DIR)
+        .filter(f => f.endsWith('.json'));
+      
+      // Count sessions active in last 24h
+      const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;
+      let recentCount = 0;
+      
+      for (const file of sessionFiles.slice(0, 100)) {
+        try {
+          const filePath = path.join(SESSIONS_DIR, file);
+          const stat = fs.statSync(filePath);
+          if (stat.mtimeMs > oneDayAgo) {
+            recentCount++;
+          }
+        } catch (e) { /* skip */ }
+      }
+
+      stats.sessions = {
+        total: sessionFiles.length,
+        recent24h: recentCount,
+      };
+    }
+  } catch (e) {
+    stats.sessions = { error: e.message };
+  }
+
+  // Gateway status (check if process is running)
+  try {
+    const { execSync } = require('child_process');
+    const result = execSync('pgrep -f "openclaw.*gateway" || true', { encoding: 'utf8' });
+    stats.gateway = {
+      running: result.trim().length > 0,
+    };
+  } catch (e) {
+    stats.gateway = { running: false };
+  }
+
+  return stats;
+}
+
+module.exports = { collectOpenClawStats };

package/lib/server.js

@@ -0,0 +1,105 @@
+/**
+ * LobsterBoard Agent HTTP Server
+ */
+
+const http = require('http');
+const { collectStats } = require('./stats.js');
+const { collectDockerStats } = require('./docker.js');
+const { collectOpenClawStats } = require('./openclaw.js');
+
+function startServer(config) {
+  const { apiKey, port, host, serverName, enableDocker, enableOpenClaw } = config;
+
+  const server = http.createServer(async (req, res) => {
+    // CORS headers for browser requests
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Headers', 'X-API-Key, Content-Type');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+
+    // Handle preflight
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    // Check API key
+    const providedKey = req.headers['x-api-key'];
+    if (providedKey !== apiKey) {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Invalid or missing API key' }));
+      return;
+    }
+
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const pathname = url.pathname;
+
+    // Routes
+    if (req.method === 'GET' && pathname === '/stats') {
+      try {
+        const stats = await collectStats();
+        stats.serverName = serverName;
+        stats.timestamp = new Date().toISOString();
+
+        // Add Docker stats if enabled
+        if (enableDocker) {
+          stats.docker = await collectDockerStats();
+        }
+
+        // Add OpenClaw stats if enabled
+        if (enableOpenClaw) {
+          stats.openclaw = await collectOpenClawStats();
+        }
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(stats));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+      }
+      return;
+    }
+
+    if (req.method === 'GET' && pathname === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok', serverName }));
+      return;
+    }
+
+    if (req.method === 'GET' && pathname === '/') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        name: 'LobsterBoard Agent',
+        version: require('../package.json').version,
+        serverName,
+        endpoints: ['/stats', '/health']
+      }));
+      return;
+    }
+
+    // 404
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Not found' }));
+  });
+
+  server.listen(port, host, () => {
+    console.log(`
+🦞 LobsterBoard Agent running!
+
+   Server:  http://${host}:${port}
+   Name:    ${serverName}
+   
+   Endpoints:
+     GET /stats   - System stats (requires X-API-Key header)
+     GET /health  - Health check (requires X-API-Key header)
+
+   Press Ctrl+C to stop
+`);
+  });
+
+  // Graceful shutdown
+  process.on('SIGTERM', () => server.close(() => process.exit(0)));
+  process.on('SIGINT', () => server.close(() => process.exit(0)));
+}
+
+module.exports = { startServer };

package/lib/stats.js

@@ -0,0 +1,75 @@
+/**
+ * System stats collection using systeminformation
+ */
+
+const si = require('systeminformation');
+const os = require('os');
+
+async function collectStats() {
+  const [cpu, mem, fsSize, networkStats, osInfo, currentLoad] = await Promise.all([
+    si.cpu(),
+    si.mem(),
+    si.fsSize(),
+    si.networkStats(),
+    si.osInfo(),
+    si.currentLoad(),
+  ]);
+
+  // Calculate network totals
+  let netRx = 0, netTx = 0;
+  for (const iface of networkStats) {
+    netRx += iface.rx_sec || 0;
+    netTx += iface.tx_sec || 0;
+  }
+
+  // Get primary disk (largest or root)
+  const primaryDisk = fsSize.reduce((best, disk) => {
+    if (!best || disk.size > best.size) return disk;
+    return best;
+  }, null);
+
+  return {
+    hostname: os.hostname(),
+    platform: osInfo.platform,
+    distro: osInfo.distro,
+    release: osInfo.release,
+    uptime: os.uptime(),
+    
+    cpu: {
+      model: cpu.brand,
+      cores: cpu.cores,
+      speed: cpu.speed,
+      usage: Math.round(currentLoad.currentLoad * 10) / 10,
+    },
+    
+    memory: {
+      total: mem.total,
+      used: mem.used,
+      free: mem.free,
+      available: mem.available,
+      percent: Math.round((mem.used / mem.total) * 1000) / 10,
+    },
+    
+    disk: primaryDisk ? {
+      mount: primaryDisk.mount,
+      type: primaryDisk.type,
+      total: primaryDisk.size,
+      used: primaryDisk.used,
+      free: primaryDisk.available,
+      percent: Math.round(primaryDisk.use * 10) / 10,
+    } : null,
+    
+    network: {
+      rxSec: Math.round(netRx),
+      txSec: Math.round(netTx),
+    },
+    
+    load: {
+      avg1: os.loadavg()[0],
+      avg5: os.loadavg()[1],
+      avg15: os.loadavg()[2],
+    },
+  };
+}
+
+module.exports = { collectStats };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "lobsterboard-agent",
+  "version": "0.1.0",
+  "description": "Lightweight stats agent for remote LobsterBoard monitoring",
+  "main": "lib/server.js",
+  "bin": {
+    "lobsterboard-agent": "./bin/agent.js"
+  },
+  "scripts": {
+    "start": "node bin/agent.js serve",
+    "test": "node --test"
+  },
+  "keywords": [
+    "lobsterboard",
+    "monitoring",
+    "stats",
+    "agent",
+    "openclaw"
+  ],
+  "author": "Curbob",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Curbob/lobsterboard-agent.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "systeminformation": "^5.21.0"
+  }
+}