What is Onicis

Onicis is an autonomous IT operations platform designed for small and mid-size businesses. It deploys a lightweight agent on each machine in your fleet, continuously monitoring system health -- CPU, memory, disk, running processes, network connectivity -- and reporting events to a central server where an AI classification engine identifies incidents in real time.

When a problem is detected, Onicis does not just create a ticket and wait. It executes an ORBEL runbook -- a human-readable remediation script written in the Open Runbook Expression Language -- directly on the affected machine. The runbook follows a strict diagnose-remediate-verify cycle: it confirms the problem, applies a fix, and validates that the fix worked. If the automated remediation fails, Onicis escalates to your existing ticketing system (Zendesk, Freshdesk, or ServiceNow) with full diagnostic context attached.

The result is fewer tickets, faster resolution, and less 3 AM paging. Your IT team focuses on strategic work while Onicis handles the repetitive operational tasks that consume most of a helpdesk's time: restarting crashed services, clearing full disks, killing runaway processes, flushing DNS caches, and more.

How it Works

Onicis operates in four steps, running continuously on every managed machine:

Prerequisites

Before installing the Onicis agent, make sure your machine meets the following requirements:

• Operating System: Windows 10+, Windows Server 2016+, or Linux (Ubuntu 18+, Debian 10+, CentOS 7+, RHEL 7+, or any distro with /proc/stat and /proc/meminfo)
• Port: TCP port 8888 must be available on the local machine
• Permissions: Administrator (Windows) or root (Linux) -- required for restarting services, killing processes, and reading performance counters
• Network: Outbound HTTPS (port 443) to api.onicis.com for event reporting (optional for standalone mode)
• Build from source (optional): Go 1.21+ if compiling the agent yourself. Pre-built binaries have no external dependencies
• Account: An Onicis account with an org token (sign up at app.onicis.com)

Installation -- Windows

Step 1: Get the binary

Option A -- Build from source (requires Go 1.21+):

cd agent
go build -o onicis-agent.exe .

Option B -- Download the pre-built binary from the releases page and place it in a directory such as C:\\onicis\\.

Step 2: Configure environment variables

# Required -- authentication token for the agent API
[System.Environment]::SetEnvironmentVariable("ONICIS_TOKEN", "your-secret-token", "Machine")

# Optional -- URL of the central Onicis server (enables automatic monitoring)
[System.Environment]::SetEnvironmentVariable("ONICIS_SERVER_URL", "https://your-org.onicis.com", "Machine")

# Optional -- auth token for the central server
[System.Environment]::SetEnvironmentVariable("ONICIS_SERVER_TOKEN", "server-token", "Machine")

Step 3: Run the agent

For testing, run directly:

.\onicis-agent.exe

# Expected output:
# Onicis Agent listening on 0.0.0.0:8888 (machine: YOUR-MACHINE-NAME)

For production, install as a Windows Service:

sc.exe create OnicisAgent binPath= "C:\onicis\onicis-agent.exe" start= auto
sc.exe description OnicisAgent "Onicis Agent - Monitoring and remediation"
sc.exe start OnicisAgent

Step 4: Verify

curl http://localhost:8888/health

# Expected: {"status":"ok","machine":"YOUR-MACHINE-NAME"}

Installation -- Linux

Step 1: Get the binary

Option A -- Build from source (requires Go 1.21+):

cd agent
go build -o onicis-agent .
chmod +x onicis-agent

Option B -- Download the pre-built binary:

curl -L -o /usr/local/bin/onicis-agent https://releases.onicis.com/agent/latest/linux-amd64
chmod +x /usr/local/bin/onicis-agent

Step 2: Create a systemd service

Create the file /etc/systemd/system/onicis-agent.service:

[Unit]
Description=Onicis Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/onicis-agent
Restart=always
RestartSec=5
Environment=ONICIS_TOKEN=your-secret-token
Environment=ONICIS_SERVER_URL=https://your-org.onicis.com
Environment=ONICIS_SERVER_TOKEN=server-token
User=root

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable onicis-agent
sudo systemctl start onicis-agent

Step 3: Verify

curl http://localhost:8888/health

# Expected: {"status":"ok","machine":"your-hostname"}

First Runbook

Create a file called hello.orb to test the ORBEL pipeline:

runbook "hello_world"
  description: "A minimal runbook to verify the setup"

  cycle:
    diagnose system_health
    remediate clear_temp_files
    verify system_health

Validate and dry-run it with the ORBEL CLI:

# Validate syntax
orbel validate hello.orb

# Dry-run (shows execution plan without running anything)
orbel run hello.orb

# Push to the platform
onicis runbook push hello.orb
# Runbook "hello_world" uploaded successfully.

Verify Setup

Once the agent is running, confirm everything is working:

# 1. Health check (no auth required)
curl http://localhost:8888/health
# {"status":"ok","machine":"your-hostname"}

# 2. Run a diagnostic (requires Bearer token)
curl -X POST http://localhost:8888/diagnostic \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"name": "check_cpu_usage", "args": {}}'
# {"success":true,"message":"CPU usage is 23.45% (threshold 90%).","metadata":{...}}

# 3. Check agent logs (Linux)
sudo journalctl -u onicis-agent -f

Agent Endpoints

The agent exposes an HTTP API on port 8888 (bound to 0.0.0.0). All endpoints except /health require a Bearer token via theAuthorization header.

Request body for /diagnostic and /remediation:

{
  "name": "check_cpu_usage",
  "args": {
    "threshold": 80
  }
}

Request body for /analyze:

{
  "machine": "WORKSTATION-01"
}

Available Diagnostics

Diagnostics are read-only checks that inspect the current state of the machine. They never modify the system.

Available Remediations

Remediations take corrective action on the machine. They require administrator or root permissions.

Background Monitor

When ONICIS_SERVER_URL is configured, the agent starts a background monitor that continuously checks system metrics and sends events when thresholds are exceeded.

The monitor also sends a heartbeat event (agent_heartbeat) every 5 minutes, including the agent version and uptime. Events are sent via POST to{ONICIS_SERVER_URL}/events/machine with automatic retry (up to 3 attempts with exponential backoff).

If ONICIS_SERVER_URL is not set, monitoring is disabled and the agent runs in standalone mode. The agent logs will show: Monitor: disabled (no ONICIS_SERVER_URL).

Configuration

The agent is configured exclusively through environment variables. There are no configuration files.

Request Examples

Health check

curl http://localhost:8888/health

# Response:
# {"status":"ok","machine":"WORKSTATION-01"}

Check CPU usage

curl -X POST http://localhost:8888/diagnostic \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"name": "check_cpu_usage", "args": {"threshold": 80}}'

# Response:
# {
#   "success": true,
#   "message": "CPU usage is 23.45% (threshold 80%).",
#   "metadata": {
#     "cpu_usage_percent": 23.45,
#     "threshold_percent": 80,
#     "os": "linux"
#   }
# }

Check disk usage for a specific path

curl -X POST http://localhost:8888/diagnostic \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"name": "check_disk_usage", "args": {"path": "/var", "threshold": 70}}'

Check if a process is running

curl -X POST http://localhost:8888/diagnostic \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"name": "check_running_process", "args": {"name": "nginx"}}'

Kill a process

curl -X POST http://localhost:8888/remediation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"name": "kill_process", "args": {"name": "runaway-app"}}'

Flush DNS cache

curl -X POST http://localhost:8888/remediation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"name": "flush_dns", "args": {}}'

Full machine analysis

curl -X POST http://localhost:8888/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"machine": "WORKSTATION-01"}'

ORBEL Overview

ORBEL (Open Runbook Expression Language) is a declarative domain-specific language for describing IT operations runbooks. An ORBEL runbook captures the full diagnostic-remediation-verification cycle that a helpdesk operator or automation engine follows when responding to an incident.

Rather than encoding procedures as opaque scripts, ORBEL makes each runbook human-readable, version-controllable, and auditable. Every step is explicit and every outcome is recorded -- no hidden side effects.

ORBEL source files use the .orb extension and must be encoded in UTF-8.

Syntax

Every ORBEL file defines a runbook with a name, optional description, optional parameters, and one or more cycle blocks. Each cycle contains ordered steps: diagnose, remediate, and verify.

runbook "<name>"
  description: "<what this runbook does>"

  params:
    hostname: string
    threshold: int

  cycle:
    diagnose <target> [qualifiers]
    remediate <action>
    verify <target> [qualifiers]

Comments start with # and extend to the end of the line. Variables reference parameters using the $name syntax.

# This is a comment
diagnose dns_resolution with host "$hostname"  # inline comment

ORBEL supports five parameter types:

Features (v0.2)

ORBEL v0.2 introduces several features for production runbook authoring:

ORBEL Examples

1. cpu_runaway.orb -- Detect and kill runaway processes consuming excessive CPU.

runbook "cpu_runaway"
  description: "Kill runaway processes consuming excessive CPU"

  cycle:
    timeout "30s"
    retry 2 times interval "10s"
    notify to "slack"

    diagnose cpu_usage
      if failed:
        remediate kill_top_cpu_process
        verify cpu_usage

2. disk_full.orb -- Free disk space by purging old logs when usage exceeds 90%.

runbook "disk_full"
  description: "Free disk space by purging old logs"

  cycle:
    timeout "60s"
    notify to "email"
    escalate to "zendesk"

    diagnose disk_usage with path "/" threshold 90
      if failed:
        remediate clear_old_logs
        remediate vacuum_journal
        verify disk_usage with path "/" threshold 80

3. printer_spooler.orb -- Restart the print spooler when it stops responding.

runbook "printer_spooler"
  description: "Restart the print spooler service"

  cycle:
    timeout "30s"
    notify to "telegram"

    diagnose spooler_status
      if failed:
        remediate restart_spooler
        verify spooler_status

4. password_reset.orb -- Parameterized runbook for user password resets.

runbook "password_reset"
  description: "Reset a user password and verify account status"

  params:
    username: string
    department: enum[hr|finance|it|engineering]

  cycle:
    timeout "30s"
    escalate to "freshdesk"

    diagnose account_status with user "$username"
      if failed:
        stop
    remediate reset_password with user "$username"
    verify account_status with user "$username"
    notify to "email"

5. service_restart.orb -- Restart a service with retry logic.

runbook "service_restart"
  description: "Restart a failed service with retry"

  params:
    service_name: string

  cycle:
    timeout "120s"
    retry 3 times interval "15s"
    notify to "telegram"
    escalate to "zendesk"

    diagnose service_status with name "$service_name"
      if failed:
        remediate restart_service with name "$service_name"
        verify service_status with name "$service_name"
          if failed:
            escalate to "zendesk"

Validation and Tooling

Use the ORBEL CLI to validate, format, and lint your runbooks before deploying them:

# Validate syntax and semantics
orbel validate my-runbook.orb

# Lint for errors and warnings
orbel lint my-runbook.orb

# Auto-format to canonical style
orbel fmt my-runbook.orb

# Check formatting without modifying
orbel fmt my-runbook.orb --check

A VS Code extension is available for syntax highlighting, inline validation, and auto-completion of ORBEL keywords and targets. Search for "ORBEL" in the VS Code marketplace.

CLI Overview

The ORBEL CLI (orbel) is the command-line tool for working with ORBEL runbook files. It provides parsing, validation, formatting, linting, dry-run execution, and access to the community runbook registry.

# Install via pip
pip install orbel

# Verify installation
orbel version

orbel parse

Parse and display the structure of an ORBEL file.

orbel parse <file> [--json] [--verbose]

orbel parse cpu_runaway.orb --json

# Output: full JSON representation of the runbook AST

orbel validate

Validate an ORBEL file for syntax and semantic errors. Exits with code 1 if validation fails.

orbel validate <file>

orbel validate my-runbook.orb
# Output: ✓ Validation successful

orbel fmt

Auto-format ORBEL files to the canonical style. Without arguments, formats all .orbel files in the current directory.

orbel fmt [files...] [--check] [--verbose]

# Format all files in the current directory
orbel fmt

# Check formatting in CI
orbel fmt --check
# Exit code 0 = all formatted, 1 = needs formatting

orbel lint

Lint ORBEL files for errors and warnings. Checks for parse errors, validation errors, and best-practice warnings (missing if failed handlers, excessive retry counts, long timeouts).

orbel lint [path] [--format text|json]

Warning codes:

orbel lint ./runbooks/ --format json

# Output: JSON array of files with issues, severity, codes, and messages

orbel run

Dry-run an ORBEL file. Displays the execution plan without running any commands or making changes to the system.

orbel run <file>

orbel run disk_full.orb

# Output:
# Execution Plan for: disk_full
# Description: Free disk space by purging old logs
#
# --- Cycle 1 ---
# Diagnostics:
#   → Check disk_usage
# Remediations:
#   → Execute clear_old_logs
#   → Execute vacuum_journal
# Verifications:
#   → Verify disk_usage

orbel list

List available diagnostic targets, remediation actions, runbook files, or domains.

orbel list targets|actions|runbooks|domains [--domain <domain>]

orbel list domains

# Output:
# Available domains:
#   networking       12 targets, 8 actions
#   storage           6 targets, 4 actions
#   ...

orbel new

Create a new runbook from a starter template. Generates a .orbel file with the correct structure.

orbel new <name>

orbel new memory-cleanup
# Output: ✓ Created memory-cleanup.orbel

orbel registry

Browse and install runbooks from the ORBEL community registry.

orbel registry list              # List all categories and counts
orbel registry search <term>     # Search by name, description, or tags
orbel registry show <name>       # Display full runbook source
orbel registry install <name>    # Download runbook to current directory

# Search for disk-related runbooks
orbel registry search disk
# Found 3 runbook(s) matching 'disk':
#   disk_full                        Free disk space by purging old logs
#                                    tags: storage, cleanup, linux
#   ...

# Install a runbook
orbel registry install disk_full
# Installed disk_full -> ./disk_full.orbel

orbel version

Display the ORBEL CLI version.

orbel version
# Output: ORBEL CLI v0.2.0
# The open expression language for IT runbook automation

Zendesk

Connect Onicis to Zendesk to automatically create and sync tickets when escalation is triggered. When a runbook fails to remediate an issue, Onicis can create a Zendesk ticket with full diagnostic context -- system metrics, runbook output, and remediation history.

Environment variables:

Setup steps:

1. In your Zendesk admin panel, go to Admin > Channels > API and generate an API token.
2. Set the three environment variables on your Onicis server.
3. Go to Settings > Integrations in the Onicis dashboard and click Connect Zendesk.
4. Map your escalation policies to Zendesk ticket groups.
5. Test the connection: onicis config test zendesk

Capabilities:

• Sync tickets bi-directionally between Onicis and Zendesk
• Auto-triage incoming tickets using AI classification
• Create tickets with diagnostic context on escalation
• Update ticket status when runbooks resolve issues

Freshdesk

Connect Onicis to Freshdesk for ticket synchronization and automated triage.

Environment variables:

Setup steps:

1. In Freshdesk, go to your profile settings and copy your API key.
2. Set FRESHDESK_DOMAIN and FRESHDESK_API_KEY on your Onicis server.
3. Go to Settings > Integrations in the Onicis dashboard and click Connect Freshdesk.
4. Map escalation policies to Freshdesk groups.
5. Test with onicis config test freshdesk.

Telegram

Receive real-time incident notifications on Telegram. Onicis sends formatted HTML messages for workflow completions, incident alerts, and escalation events.

Environment variables:

How to create a Telegram bot:

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to name your bot.
3. Copy the bot token provided by BotFather.
4. Add the bot to your team's group chat (or use a direct chat).
5. Get your chat ID by sending a message to the bot and visiting https://api.telegram.org/bot<TOKEN>/getUpdates.
6. Set ONICIS_TELEGRAM_TOKEN and ONICIS_TELEGRAM_CHAT_ID on your Onicis server.

Notification types:

• Workflow Complete: Sent when a runbook cycle finishes. Includes runbook name, status (SUCCESS/FAILED), result message, and any errors.
• Incident Alert: Sent when a new incident is detected. Includes workflow name, ticket count, and alert message.

ServiceNow

Connect Onicis to ServiceNow for incident management via the ServiceNow Table API.

Environment variables:

Coming Soon

The following integrations are planned for upcoming releases:

• Jira -- Create and track issues from escalation events. Supports Jira Cloud and Jira Server.
• Slack -- Real-time incident notifications and interactive runbook approvals via Slack channels.
• Microsoft Teams -- Incident notifications and status updates via Teams webhooks.

Troubleshooting

FAQ

Changelog