Agent Guide

The Orion Agent is a compiled Linux binary that runs as a systemd daemon. It sends system metrics (CPU, RAM, disk, network), manages application processes, and streams their stdout/stderr to Orion.

Installation

curl -fsSL https://install.orion.dev | bash

This installs the orion binary to /usr/local/bin/orion and the systemd service file.

Setup

Setup is a two-step process: server-wide (once per machine) then source (once per application).

Step 1 — Server setup

sudo orion setup --server

This interactive wizard:

• Authenticates via browser or API token
• Lets you select or create a project
• Registers the server with Orion (using hostname as the stable ID)
• Writes /etc/orion/config.json

After setup, enable and start the daemon:

sudo systemctl enable --now orion-agent

Step 2 — Source setup

Run this inside each application directory:

orion setup --source

This wizard:

• Selects or creates a source in your project
• Prompts for the application's start command (e.g. node dist/index.js)
• Configures auto-restart and output capture
• Writes .orion/config.json (the same format the SDK reads)
• Registers the script in /etc/orion/scripts.json

CLI commands

# Check daemon status + live metrics + script states
orion status

# Send a one-off log from the terminal
orion log info "Deploy complete"
orion log error "Disk space low"

# Script management
orion script start <name>
orion script stop <name>
orion script restart <name>
orion script list
orion script add <name> <command> [--cwd <path>] [--no-auto-restart] [--no-capture]

Script management

The agent manages application processes defined in /etc/orion/scripts.json. Each script entry:

{
  "name": "api-backend",
  "command": "node dist/index.js",
  "cwd": "/opt/myapp",
  "autoRestart": true,
  "maxRestarts": 5,
  "backoffBase": 1000,
  "captureOutput": true
}

Field	Description
name	Unique identifier (lowercase, hyphens)
command	Shell command to execute
cwd	Working directory
autoRestart	Restart on crash with exponential backoff
maxRestarts	Stop after N consecutive crashes
backoffBase	Initial backoff in ms (doubles each restart, max 60s)
captureOutput	Stream stdout/stderr to Orion as logs

When a script crashes, the agent always sends an alert to Orion — even if autoRestart is false.

Heartbeat

Every 30 seconds the daemon sends a heartbeat to POST /api/v1/agent/heartbeat with:

• CPU usage (%)
• RAM (used MB / total MB / %)
• Disk (used GB / total GB / %)
• Network (rx/tx bytes per second)
• Uptime (seconds)
• Script states (running / stopped / crashed)

Offline buffer

If the backend is unreachable, logs are buffered to /etc/orion/buffer.jsonl. The agent retries with exponential backoff (5s → 10s → 30s → 60s) and flushes in order when reconnected. Maximum buffer size: 10,000 entries (oldest dropped first).

File locations

Path	Purpose
/usr/local/bin/orion	The binary
/etc/orion/config.json	Server-wide config (token, apiUrl, heartbeatInterval)
/etc/orion/scripts.json	Managed scripts registry
/etc/orion/buffer.jsonl	Offline log buffer
/var/log/orion-agent.log	Internal agent logs
/run/orion/agent.sock	IPC Unix socket (CLI ↔ daemon)
.orion/config.json	Per-application source token

IPC protocol

CLI commands communicate with the daemon over a Unix socket at /run/orion/agent.sock. Each message is a JSON line terminated by \n:

{ "cmd": "script:start", "name": "api-backend" }
{ "cmd": "script:list" }
{ "cmd": "status" }
{ "cmd": "log", "level": "info", "message": "Deploy done" }

Daemon responses:

{ "ok": true, "data": { ... } }
{ "ok": false, "error": "Script not found" }