@orion-monitoring/agent

Linux system monitoring agent for the Orion platform. Runs as a systemd daemon and exposes a CLI — both compiled into a single standalone binary.

Installation

# Via npm (global)
npm install -g orion-agent

# Or download the pre-built binary
# binaries/orion  (x64 / arm64)

Quick Start

# 1. Register this server with Orion (requires sudo)
sudo orion setup --server

# 2. Start the daemon
orion daemon start

# 3. Check everything is running
orion status

Commands

Setup

orion setup --server

Server-wide registration wizard. Requires sudo.

• Authenticates with Orion (browser OAuth on desktop, token paste on headless)
• Selects or creates a project
• Enters a server display name
• Registers the server and writes /etc/orion/config.json

orion setup --source

Per-application setup wizard. No sudo required. Run from the app's root directory.

• Verifies server-wide setup exists
• Selects or creates a source (name + start command + restart/capture options)
• Writes .orion/config.json with a scoped SDK token
• Registers the script in /etc/orion/scripts.json

Daemon

orion daemon          # Start in foreground (used by systemd)
orion daemon start    # Start in background (detached)
orion daemon stop     # Graceful shutdown (SIGTERM, 5s grace)

Logging

orion log <level> <message>

Levels: debug · info · warn · error · fatal

Context resolution: the CLI walks up the directory tree looking for .orion/config.json. If found, the log is attributed to that source; otherwise it is attributed to the server.

# From an app directory (attributed to source)
cd /app/api
orion log info "Deployment started"

# From anywhere else (attributed to server)
orion log warn "Disk space low"

If the daemon is offline, logs are written to the offline buffer and flushed when the daemon reconnects.

Status

orion status

Displays:

• Daemon running / stopped
• Backend connected / offline
• CPU, RAM, disk usage with colored progress bars
• List of registered scripts with status, PID, uptime, and restart count

Scripts

# List registered scripts
orion script list

# Lifecycle control
orion script start <name>
orion script stop <name>
orion script restart <name>

# Register a new script
orion script add <name> <command> [options]

orion script add options:

| Flag | Description | Default | | --------------------- | ----------------------------- | -------------------- | | --cwd <path> | Working directory | current directory | | --no-auto-restart | Disable auto-restart on crash | auto-restart enabled | | --no-capture | Disable stdout/stderr capture | capture enabled |

Daemon Internals

Heartbeat

Sends system metrics to /api/v1/agent/heartbeat every 10 seconds (configurable):

• CPU %, RAM (used/total MB + %), disk (used/total GB + %)
• Network RX/TX bytes per second
• Script statuses (name, pid, uptime, restarts)

On backend failure, uses exponential backoff (5s → 10s → 30s → 60s).

Offline Buffer

When the backend is unreachable, logs are appended to /etc/orion/buffer.jsonl (JSONL format, max 10,000 entries FIFO). On reconnect the buffer is flushed in order.

Script Manager

Supervises processes registered in the scripts registry:

• Crash detection: fires an Orion alert on every crash, even without auto-restart
• Auto-restart: exponential backoff (base * 2^n, capped at 60s)
• stdout/stderr capture: each line is sent as a log with stream: "stdout" or "stderr"
• Graceful shutdown: SIGTERM → 5s grace → SIGKILL

Remote Commands

The daemon polls /api/v1/agent/commands and executes start / stop / restart commands issued from the Orion dashboard, acknowledging each result back to the backend.

IPC

The daemon and CLI communicate over a Unix socket at /run/orion/agent.sock using a JSON-RPC protocol (one-line JSON messages terminated with \n).

Configuration Files

| Path | Description | | ---------------------------- | ---------------------------------------- | | /etc/orion/config.json | Server config: token + heartbeatInterval | | .orion/config.json | Per-app source token | | /etc/orion/scripts.json | Registered scripts registry | | /etc/orion/buffer.jsonl | Offline log buffer | | /run/orion/agent.pid | Daemon PID file | | /var/log/orion-agent.log | Daemon log file |

/etc/orion/config.json

{
  "token": "orion_agent_xxx",
  "heartbeatInterval": 10000
}

.orion/config.json

{
  "token": "orion_xxx"
}

/etc/orion/scripts.json

[
  {
    "name": "api",
    "command": "node dist/index.js",
    "cwd": "/app/api",
    "sourceToken": "orion_xxx",
    "autoRestart": true,
    "maxRestarts": 5,
    "captureOutput": true
  }
]

Build

npm run build       # tsc → CommonJS marker → pkg (x64 + arm64 binaries)
npm run pkg:x64     # linux-x64 only
npm run pkg:arm64   # linux-arm64 only
npm run typecheck   # type-check without emitting

Output binary: binaries/orion