Skip to content
Chronix

Reference Manual

Chronix Comprehensive Reference Manual

Section titled “Chronix Comprehensive Reference Manual”

This document provides a detailed technical reference for all aspects of Chronix, including CLI commands, system configuration, task execution details, and administrative operations.

1. CLI Commands Reference

Section titled “1. CLI Commands Reference”

The Chronix binary supports several subcommands for service management and administration.

CommandDescription
runStarts the Chronix server in the foreground.
adminCodeGenerates a new one-time admin login code via RPC. Useful if you lose access to the UI.
agentsManage connected agents (list, update).
updateManage Chronix server updates (check, apply).
versionShows the current version and release notes.
systemdataShows live system resource usage (Memory, CPU, etc.) via RPC.
suspendServerPauses all job scheduling and execution.
unsuspendServerResumes job scheduling and execution.
restartRestarts the Chronix server daemon via RPC.

Global Flags and Environment Variables

Section titled “Global Flags and Environment Variables”
  • -D, --datadir: Path to the data directory (overrides default).
  • CHRONIX_DATA_DIR: Environment variable to set the data directory.
  • -c, --conf: Path to a configuration file (reserved for future use).

2. System Configuration

Section titled “2. System Configuration”

Chronix settings are stored in the database and can be managed via the Settings page in the Web UI.

Network Settings

Section titled “Network Settings”
  • HTTP Enabled/Port: Toggle the insecure HTTP server (default: 5170).
  • HTTPS Enabled/Port: Toggle the secure HTTPS server (default: 5171).
  • HTTPS Mode: Supports selfsigned or manual PEM injection.
  • Agent Port: Port for incoming Agent WebSocket connections (default: 5172).

Security

Section titled “Security”
  • Admin Login Codes: One-time codes are valid for 10 minutes.
  • TOFU (Trust On First Use): Agents pin the server’s TLS certificate on the first connection. If the certificate changes, the agent will refuse to connect until reset.
  • Encryption: Sensitive fields like passwords and private keys are encrypted at rest using a master key (master.key) located in the data directory.

3. Task Type Specifications

Section titled “3. Task Type Specifications”

SQL Tasks

Section titled “SQL Tasks”
  • Supported Engines: SQLite, PostgreSQL, MySQL.
  • Dialect Handling: Dialect-specific syntax is supported per action.
  • Expectation Types:
    • rowsAffected: Compare against the count of modified rows.
    • rowExists: Verify if a query returns at least one row.
    • fieldEquals: Verify if a specific field in the first row matches a value.
    • noError: Simply verify the query executed without an error.

Shell Tasks

Section titled “Shell Tasks”
  • Modes:
    • localhost: Runs as the user owning the Chronix process.
    • ssh: Runs via SSH.
  • Run Modes: Supports command (single line) or script (multi-line block).
  • Output Capture: Configurable truncation (Head/Tail) and max byte limits (default: 64KB).

Web Tasks (HTTP)

Section titled “Web Tasks (HTTP)”
  • Methods: GET, POST, PUT, DELETE, PATCH.
  • Variable Capture:
    • JSONPath: Extract values from JSON responses (e.g., $.status).
    • Regex: Extract values from any response body via capture groups.

4. Scheduling Engine

Section titled “4. Scheduling Engine”

Chronix uses a high-precision scheduler that supports multiple definition formats.

JSON Structure

Section titled “JSON Structure”

Schedules are stored as JSON in the database:

  • kind: single or recurring.
  • cron: Standard 5-field cron string (e.g., 0 0 * * *).
  • structured: A nested object for human-friendly recurrence rules.
  • startAt / endAt: Lifecycle boundaries for the job.

Cron Syntax

Section titled “Cron Syntax”

Supports the standard minute hour dom month dow format. Example: */15 * * * * (Every 15 minutes).

5. User and Admin Management

Section titled “5. User and Admin Management”

Roles

Section titled “Roles”
  • Admin: Full access to all settings, connections, actions, and user management.
  • User: Access to view activity and manage their own profile. (Permissions for specific resources are expanded in Phase 2/3).

Password Policy

Section titled “Password Policy”
  • Passwords are hashed using bcrypt.
  • Admins can force-reset user passwords or disable accounts.

Password Recovery (CLI-Based)

Section titled “Password Recovery (CLI-Based)”

Since Chronix does not support SMTP-based password recovery by design, the CLI must be used for administrative recovery:

  1. Run chronix adminCode to generate a 10-minute temporary login token.
  2. Navigate to /settings in the web UI.
  3. Authenticate with the code to access the “Setup Admin” profile (ID 0).
  4. Use this access to modify existing users and reset their passwords.

6. Notification and Reporting

Section titled “6. Notification and Reporting”

Chronix supports sophisticated alerting and reporting mechanisms.

Alerting Policies

Section titled “Alerting Policies”
  • Success/Failure: Per-job toggle for notifications on successful or failed runs.
  • Reporting (Include Output): When enabled, the notification payload includes snapshots of the task output:
    • SQL: Includes rows affected or rows count.
    • Shell: Includes truncated stdout and stderr.
    • Web: Includes the HTTP response body.

Delivery Channels

Section titled “Delivery Channels”
  • Email (SMTP): Formats reporting data into Markdown-style tables and code blocks.
  • SMS (Twilio): Provides a high-level summary of the final step’s outcome.
  • Webhooks (Outgoing): Sends a JSON POST request to a configured URL. Includes an X-Chronix-Signature header (HMAC-SHA256) if a secret is provided.

7. Activity & Reporting Engine

Section titled “7. Activity & Reporting Engine”

Chronix maintains a unified activity log combining job executions and user actions.

Unified Query Logic

Section titled “Unified Query Logic”

The activity system uses a SQL UNION ALL approach to combine job_runs and user_activity tables, allowing for efficient server-side pagination and filtering across disparate data types.

Export Formats

Section titled “Export Formats”
  • CSV: A flat file containing all selected activity fields.
  • HTML: A standalone, styled document suitable for browser viewing or printing.
  • PDF: A professional, paginated report generated using the fpdf library.

8. Licensing and Whitelabeling

Section titled “8. Licensing and Whitelabeling”

Chronix implements a robust licensing system to gate premium features and enforce usage limits.

Enforcement Logic

Section titled “Enforcement Logic”

If a license expires or limits are exceeded, the system automatically identifies the most recent entities (agents, jobs, connections) and marks them as Suspended. Suspended items remain in the database but are ignored by the scheduler and runner.

Branding Configuration

Section titled “Branding Configuration”

For the Enterprise tier, custom branding settings are stored in the cx_settings table:

  • brand_logo_url: Remote or local URL for the primary UI logo.
  • brand_name: Text identity for the application.

9. The Chronix Agent System

Section titled “9. The Chronix Agent System”

Agents are lightweight workers that connect back to the server via an encrypted WebSocket tunnel.

  • WebSocket Tunnel: Uses wss:// on port 5172 (default) for secure, encrypted command and control.
  • Phone Home: Agents initiate the connection, bypassing the need for inbound firewall rules on the agent’s network.
  • JWT Authentication: Agents authenticate using a unique JWT signed with an Ed25519 key pair generated locally during registration.
  • Relay Updates: Agents can be updated or reverted to specific versions via the server. The server acts as a relay, caching binaries from the distribution server and serving them to agents over an authenticated HTTPS endpoint (/agent/update/:version/:platform).

10. Maintenance and Updates

Section titled “10. Maintenance and Updates”

Chronix features a robust update system for both the server and its connected agents.

Update Manifests

Section titled “Update Manifests”

Chronix checks for updates by fetching JSON manifests from dist.chronixhq.com:

  • latest.json: Contains information about the most recent stable release for server and agent.
  • versions.json: A full history of available versions, used for reverting or installing specific older versions.

CLI Update Commands

Section titled “CLI Update Commands”
  • update check: Queries the distribution server (or the running daemon via RPC) to see if a newer version is available.
  • update apply: Downloads the latest binary, verifies its SHA256 hash and Ed25519 signature, and replaces the current executable. If the daemon is running, it is automatically restarted.

Agent Versioning

Section titled “Agent Versioning”
  • agents list: Displays the current version of all connected agents. It also checks for the latest available version and flags agents that are out of date.
  • agents update <uuid> [version]: Sends a command to the specified agent(s) to download and apply an update. If version is omitted, the latest version is used.

Advanced Version Management

Section titled “Advanced Version Management”
  • version list: Lists all available versions for both the server and agents.
  • version revert <version>: Force-installs a specific version of the Chronix server, whether it is an upgrade or a downgrade.

11. Data Management

Section titled “11. Data Management”

Data Directory

Section titled “Data Directory”

By default, Chronix stores all files in:

  • Linux: /var/lib/chronix
  • macOS: ~/Library/Application Support/Chronix
  • Windows: C:\ProgramData\Chronix

Critical Files

Section titled “Critical Files”
  • chronix.db: The SQLite database containing all state.
  • master.key: The key used for encrypting credentials. Do not lose this file.
  • cert.pem / key.pem: TLS certificates for HTTPS and Agent connections.