Getting Started

Chronix Help Guide: Getting Started Step-by-Step

Welcome to Chronix! This guide will walk you through the process of setting up Chronix from scratch, configuring your first connections, actions, and jobs, and ensuring you are notified of their status.

---

1. Installation

Chronix is distributed as a single, self-contained binary with no external dependencies. Choose the method that fits your environment:

Manual Download

1. Head to the Downloads page.
2. Download the binary for your architecture (Linux, macOS, or Windows).
3. Move the binary to a directory in your PATH (e.g., /usr/local/bin).
4. Ensure it is executable by running: chmod +x chronix.

One-Line Install (Linux & macOS)

Run the following command in your terminal to automatically download and install the latest version:

curl -fsSL https://dist.chronixhq.com/install.sh | sh

Package Managers (Coming Soon)

We are currently working on native repositories for DNF (Fedora/RHEL), APT (Debian/Ubuntu), and Homebrew.

---

2. Initial Startup and Administration

Starting Chronix

To start the Chronix server, navigate to the directory containing the chronix binary and run:

./chronix

Chronix will initialize its data directory and start the embedded web server.

Bootstrapping the Admin Account

On the first run, Chronix is in an “Uninitialized” state.

1. Check the Console: Look for a message like:

   System uninitialized
   Go to http://localhost:5170
   Admin login code: xxxx xxxx xxxx

2. Access the Web UI: Open your browser and navigate to the provided URL (default is http://localhost:5170).
3. Enter the Admin Code: Input the 12-character code displayed in your console.
4. Create Admin Profile: Once authenticated with the code, you will be prompted to set up your primary admin account. Provide your name, email address, and a strong password. This will be your primary way to access the system going forward.

Admin Password Recovery

Chronix is designed to be completely sovereign, which means it does not rely on external services for password resets. If you lose your admin password:

1. Access the CLI: On the server where Chronix is running, execute:

   ./chronix adminCode

2. Get the Code: The CLI will output a 12-character “Admin login code” that is valid for 10 minutes.
3. Login with Code: Open the web UI and append /settings to the URL (e.g., http://localhost:5170/settings).
4. Enter the Code: Input the code from the CLI to gain temporary admin access.
5. Reset Password: Navigate to Settings > Users, select the account you need to recover, and update the password.

---

3. Notification Setup

Stay informed about your jobs by setting up Email or SMS notifications. Go to Settings in the sidebar.

Email (SMTP) Configuration

Chronix can send alerts via any standard SMTP server.

• SMTP Host & Port: The address of your mail server (e.g., smtp.gmail.com) and port (usually 587 or 465).
• SMTP Login & Password: Your authentication credentials.
• SMTP Secure: Choose between SSL, TLS, or None.
• From Name & Email: How the emails will appear in the recipient’s inbox.
• System Alert Emails: A comma-separated list of emails that should receive all system-wide alerts.

SMS (Twilio) Configuration

Chronix supports Twilio for SMS alerts.

• Twilio Account SID & Token: Found in your Twilio Console.
• From Number: Your Twilio SMS-enabled phone number.
• System Alert Phones: A comma-separated list of phone numbers (in E.164 format, e.g., +1234567890) to receive critical alerts.

Webhook Configuration

For integration with external services (Slack, Discord, custom APIs), you can configure outgoing Webhooks.

• Target URL: The endpoint where the JSON payload will be sent.
• HMAC Secret: (Optional) For signing the payload, allowing the receiver to verify the source.
• Events: Subscribe to specific event categories like job, connection, or system.

---

4. Creating Connections

Connections define where your tasks will run. Navigate to Connections and click New Connection.

Database Connections

Used for SQL Tasks (SQLite, PostgreSQL, MySQL).

• Name: A descriptive name (e.g., “Production Postgres”).
• Driver: Select the database type.
• DSN (Connection String): The standard connection string for your database.
• Agent: (Optional) Select a Chronix Agent if the database is in a private network. See Chronix Agents for setup instructions.

Shell Connections

Used for Shell and Scripting Tasks.

• Mode:
  • Localhost: Run directly on the Chronix server.
  • SSH: Run on a remote host via SSH.
• Host & Port: (For SSH) The remote address and port.
• Authentication: (For SSH) Support for Password or Private Key.
• Sudo: Enable this if your commands require root privileges. You can provide a sudo password for secure injection.
• Common Shells: When defining steps in a Shell Action, you can select from a list of common shells (e.g., /bin/bash for Linux/macOS or absolute paths for Windows like C:\Windows\System32\cmd.exe). Using absolute paths on Windows ensures reliable execution even if the PATH environment variable is limited.

Web Task Connections

Used for HTTP/API Tasks.

• Base URL: The root URL of the API (e.g., https://api.example.com).
• Authentication: Supports None, Basic Auth, Bearer Token, or Custom Header.

---

5. Creating Actions

Actions define what will be executed. An Action consists of one or more Steps. Navigate to Actions and click New Action.

Defining Steps

• Name: A name for the specific step.
• SQL/Command/URL: The actual logic to execute (SQL query, shell command, or API endpoint).
• Timeout: How long Chronix should wait for this step to complete before failing.

Success Criteria (Expectations)

For each step, you can define what constitutes a “success”:

• SQL: Check rows affected, or verify if a specific value exists in the result set.
• Shell: Check the exit code (usually 0 for success) or look for specific text in the output (stdout/stderr).
• Web: Check the HTTP status code (e.g., 200) or validate the JSON response using JSONPath.

Failure Policy

• Exit on Failure: Stop the entire Action if this step fails (default).
• Continue on Failure: Proceed to the next step even if this one fails.

---

6. Creating Jobs

Jobs are the final piece that ties everything together. They define when an Action runs on a specific Connection. Navigate to Jobs and click New Job.

Configuration

1. General Info: Name and optional description.
2. Target Connection: Choose the Connection you created earlier.
3. Action: Choose the Action to be executed.
4. Schedule:
   • Single Shot: Run once at a specific date and time.
   • Recurring: Use the human-friendly builder (e.g., “Every hour”, “Daily at 3:00 PM”) or a standard Cron expression.
5. Variables: If your Action uses placeholders like {{customer_id}}, you can define their values here. This allows you to reuse the same Action for different Jobs.
6. Notifications & Reporting:
   • Toggle whether you want to receive alerts for this specific job’s Success or Failure.
   • Include Output: Enable this to have the actual task results (SQL counts, script logs, etc.) sent directly in the notification. This is perfect for daily reports or actionable debugging.

Once saved, your Job will appear in the Dashboard and execute automatically according to its schedule!

---

7. Chronix Agents

Chronix Agents are lightweight binaries that allow you to execute tasks on remote servers or within private networks. They connect back to the main Chronix server via an encrypted WebSocket, bypassing the need for complex firewall rules or VPNs.

Setup and Registration

To set up a new agent:

1. Download the Agent Binary: Download the chronix-agent binary for your target machine’s architecture from the Downloads page.
2. Register the Agent: Run the following command on the target machine:

   ./chronix-agent register <chronix-server-ip> <agent-name>

   Replace <chronix-server-ip> with the IP or hostname of your Chronix server, and <agent-name> with a unique name for this agent.
3. Approve in the Web UI: Log in to the Chronix web UI. You will see a notification for a pending agent registration. Approve it to complete the setup.
4. Start the Agent: Once approved, start the agent by running:

   ./chronix-agent

   Tip: Set this up as a systemd service or background process for production use.

Agent Troubleshooting and Maintenance

• Reset Server Pin: If the server’s certificate changes, the agent might refuse to connect. Use reset to clear the pinned fingerprint and trust the new certificate (TOFU):

  ./chronix-agent reset

• Unregister Agent: To completely remove an agent’s identity and association with a server:

  ./chronix-agent unregister

Managing Agents via CLI

You can manage your connected agents directly from the Chronix server CLI:

• List Agents: See all registered agents and their status.

  ./chronix agents list

• Update Agents: Trigger an update for agents to the latest version or a specific one.

  ./chronix agents update all           # Update all agents to latest
  ./chronix agents update <uuid>        # Update specific agent to latest
  ./chronix agents update <uuid> 0.0.5  # Revert/Update specific agent to 0.0.5

---

8. Maintenance and Updates

Chronix includes a built-in update mechanism to keep your server and agents running the latest versions with the latest features and security fixes.

Server Updates

You can check for and apply updates to the Chronix server using the CLI:

• Check for Updates:

  ./chronix update check

• Apply Update:

  ./chronix update apply

  This command downloads the latest binary, replaces the current one, and restarts the Chronix daemon if it is running.

Automatic Updates

Updates can be fully automated via the Web UI under Settings > Updates:

• Enabled: Toggle automatic checks and updates.
• Update Window: Define a preferred time window (e.g., 02:00) when updates should be applied to minimize disruption.
• Agent Updates: Choose whether agents should also be updated automatically when a new version is released.

---

9. Activity, Reporting, and Branding

Chronix provides comprehensive observability into your automated environment.

Activity Timeline

The Activity tab shows a unified history of job runs and administrative actions.

• Server-Side Filtering: Search by action, user, or date range across the entire history.
• Pagination: Navigate large datasets efficiently.

Exporting Reports

You can export the activity log for compliance or internal reporting.

• Click the Export button on the Activity page.
• Choose between CSV, HTML, or PDF formats.
• Note: HTML and PDF formats require a Pro or Enterprise license.

Custom Branding

Enterprise and Pro users can whitelabel the Chronix interface.

• Navigate to Settings > Branding.
• Provide a Custom Logo URL and Brand Name.
• These will replace the Chronix identity in the top navigation bar.

---

10. Licensing & Support

Chronix uses a tiered licensing model to support organizations of all sizes.

Applying a License

1. Navigate to Settings > Licensing.
2. Paste your signed license key into the Update License Key field and click Update.
3. Your limits (Agents, Jobs, Connections) and capabilities (Reports, Webhooks, Branding) will update immediately.

License Enforcement

If your license expires or you exceed your limits, Chronix will automatically suspend the most recently added items (e.g., extra agents or jobs) until the environment is back in compliance. The system will revert to the Free Edition if no valid license is found.