Dashio Agent

A lightweight Node.js agent that runs on OpenClaw nodes and connects to the Dashio Dashboard via WebSocket.

Features

• 🔌 Self-registration - One-command installation with invite token
• 🔄 Auto-reconnect - Exponential backoff on connection loss
• 📊 Data collection - Reads OpenClaw SQLite DB, system metrics, gateway status
• 📜 Log streaming - Real-time log forwarding from files and journalctl
• 🎮 Remote control - Execute commands from dashboard (start/stop agents, install skills)
• 🏥 Health checks - Local HTTP endpoint for monitoring
• 🔒 Secure - Token-based auth, command whitelist, no arbitrary execution

Installation

Prerequisites

• Node.js 22+ (LTS)
• Linux system with systemd (Ubuntu 20.04+, Debian 11+, Raspberry Pi OS)
• OpenClaw installed (optional - agent works without it)

Via NPM (GitLab Package Registry)

# Configure GitLab registry auth
npm config set @msisside01:registry https://gitlab.com/api/v4/projects/msisside01%2Fdashio/packages/npm/
npm config set //gitlab.com/api/v4/projects/msisside01%2Fdashio/packages/npm/:_authToken=YOUR_GITLAB_TOKEN

# Install globally
npm install -g @msisside01/dashio-agent

# Run agent
dashio-agent --register \
  --dashboard-url https://dashio.example.com \
  --token inv_xxxxxxxxxxxxxxxx \
  --name "My Node"

One-Command Install

curl -fsSL https://your-dashio-url/install-agent.sh | bash -s -- \
  --dashboard-url https://dashio.example.com \
  --token inv_xxxxxxxxxxxxxxxx \
  --name "My Node"

Manual Install

# Clone and build
git clone https://github.com/your-org/dashio-agent.git
cd dashio-agent
npm install
npm run build

# Register with dashboard
node dist/index.js --register \
  --dashboard-url https://dashio.example.com \
  --token inv_xxxxxxxxxxxxxxxx \
  --name "My Node"

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

Usage

CLI Options

dashio-agent [options]

Options:
  --register              Register this node with the Dashio Dashboard
  --dashboard-url <url>   Dashboard URL (required for --register)
  --token <token>         Invite token (required for --register)
  --name <name>           Node name (optional, defaults to hostname)
  --force                 Force re-registration
  --help, -h              Show help message

Environment Variables

• DASHIO_LOG_LEVEL - Log level (debug, info, warn, error) - default: info
• DASHIO_HEALTH_PORT - Health check port - default: 19999
• DASHIO_OPENCLAW_BIN - Override OpenClaw binary path
• DASHIO_OPENCLAW_DB - Override OpenClaw database path
• DASHIO_OPENCLAW_LOGS - Override OpenClaw logs path

Health Check

# Check agent status
curl http://localhost:19999/health

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

# Check service status
sudo systemctl status dashio-agent

Architecture

Node Machine                    Dashio Dashboard
┌─────────────────┐             ┌──────────────────┐
│ OpenClaw        │             │                  │
│ Gateway :18789  │◄────────────│ Dashio Agent     │
│ SQLite DB       │  WebSocket  │ (Node.js)        │
└─────────────────┘  (outbound) │                  │
                                └──────────────────┘

The agent:

1. Registers with dashboard via HTTP POST
2. Opens persistent WebSocket connection
3. Streams data (agents, sessions, metrics, logs)
4. Executes commands from dashboard
5. Auto-reconnects on disconnect

WebSocket Protocol

Agent → Dashboard

• heartbeat - Every 10 seconds
• snapshot - Full state every 60 seconds
• update - Incremental changes
• log - Real-time log lines
• metrics - System metrics every 30 seconds
• command_result - Command responses

Dashboard → Agent

• ping - Connection test
• gateway_start/stop/restart - Control OpenClaw gateway
• agent_start/stop/restart - Control agents
• skill_install/remove - Manage skills
• message_send - Send messages
• config_read - Read configuration

Development

# Install dependencies
npm install

# Run type check
npm run typecheck

# Build
npm run build

# Run locally
npm run dev

License

MIT