Configuration

July 18, 2026 · View on GitHub

Overview

xyOps is configured primarily by a single JSON file located here: /opt/xyops/conf/config.json (the location may vary for custom installs).

However, if the configuration is modified using the UI, overrides are saved in a separate file: /opt/xyops/conf/overrides.json

This document describes all the editable properties in the config.json file.

This string is the base URL of your xyOps instance (default: http://localhost:5522), and is used to build fully-qualified links in emails, alerts, tickets, and web hooks (e.g., job/ticket URLs and the logo URL in emails).

secret_key

This string is a shared secret used to sign tokens (e.g., download links), authenticate multi-conductor messages, and encrypt/decrypt stored secrets -- set this to a long random value in production.

temp_dir

This string is the scratch directory for temporary files such as plugin bundles and staging uploads (default: temp).

If this is a relative path, it is computed from the xyOps base directory, which is typically /opt/xyops.

pid_file

This string sets the path to the main process PID file for start/stop tooling (default: logs/xyops.pid).

If this is a relative path, it is computed from the xyOps base directory, which is typically /opt/xyops.

debug_level

This number sets the verbosity level for the logger (default: 5; 1 = quiet, 10 = very verbose).

tick_precision_ms

This number sets the internal timer precision in milliseconds used by the server framework for scheduling ticks (default: 50).

This controls how precise xyOps is when executing actions targeted on a specific second. Lower values mean xyOps is more precise, but will result in heavier idle CPU usage.

maintenance

This string (in HH:MM format, server local time) schedules daily maintenance tasks such as DB trimming and log archival (default: 04:00).

ttl

This number (seconds) is the default HTTP cache TTL applied to selected API responses and static resources where applicable (default: 300).

file_expiration

This duration string sets the default expiration for uploaded files (e.g., ticket attachments), used to compute per-file expiration timestamps (default: 5 years).

timeline_expiration

This duration string sets the retention for monitor timelines; older points are pruned during maintenance (default: 10 years).

ping_freq_sec

This number (seconds) controls the interval for sending WebSocket pings to clients/workers (default: 5).

ping_timeout_sec

This number (seconds) is the max allowed time without a pong before a socket is considered timed out (default: 30).

max_jobs_per_min

This number sets a global rate limit on job starts per minute (default: 100); additional jobs are prevented from launching.

This is designed as a runaway e-brake mechanism, to prevent an erroneous workflow configuration from bringing down the entire system.

max_jobs_per_workflow

This number sets a global limit on the number of sub-jobs allowed per workflow run (default: 1000). Additional jobs are prevented from launching, and the workflow is aborted.

scheduler_stagger_ms

This number sets the delay between parallel scheduled job launches, in milliseconds (default: 50). It insures a large amount of job launches at the same instant won't stall the system.

dead_job_timeout

This number (in seconds) determines when a running job with no updates is considered dead and aborted (default: 120).

stale_alert_timeout

This number (in seconds) determines when stale alerts are cleared. Stale alerts occur when a server disconnects with active alerts attached.

default_plugin_credentials

This object allows you to set default UID and/or GID values for each type of Plugin. The UID/GID may be either numerical IDs or username strings (root, admin, etc.). Linux/macOS only.

job_env

This object contains environment variables merged into every job process.

Values can be overridden per job.

job_universal_limits

This object defines global limit rules automatically applied to all jobs/workflows, such as concurrency, queue, or retry caps.

job_universal_actions

This object defines global actions executed when conditions are met (default includes a system snapshot on error). Actions can be assigned by job type (workflow or event).

Example:

"job_universal_actions": {
	"default": [
		{
			"enabled": true,
			"hidden": false,
			"condition": "error",
			"type": "snapshot"
		}
	],
	"workflow": []
}

alert_universal_actions

This array lists actions automatically applied to all alerts for standardized behavior (default includes a hidden snapshot on new alert).

Example:

"alert_universal_actions": [
	{
		"enabled": true,
		"hidden": true,
		"condition": "alert_new",
		"type": "snapshot"
	}
]

hostname_display_strip

This regex string is removed from the end of hostnames for display and notifications (default: \\.[\\w\\-]+\\.\\w+$), e.g., to strip the domain suffix.

ip_display_strip

This regex string is removed from IP addresses for display (default: ^::ffff:), e.g., to strip the IPv6 IPv4-mapped prefix.

search_file_threads

This number sets how many worker threads are used when searching files on disk (default: 1).

search_file_regex

This regex string limits which filenames are scanned by the file search APIs (default: \\.(txt|log|csv|tsv|xml|json)(\\.gz)?$).

quick_monitors

This array defines built-in metrics to collect (defaults include CPU, memory, disk, and network presets). These are displayed on server detail pages for real-time monitoring.

email_from

This string is the sender email address for all outbound messages (default: admin@localhost); many SMTP servers require this to be a valid address.

mail_settings

This object configures the email transport and is passed verbatim to Nodemailer.

The default configuration is:

{
	"host": "localhost",
	"port": 25,
	"auth": { "user": "", "pass": "" }
}

See Nodemailer - SMTP and Nodemailer - Sendmail for full options.

Example (basic SMTP on localhost):

"mail_settings": {
	"host": "localhost",
	"port": 25
}

Example (local sendmail):

"mail_settings": {
	"sendmail": true,
	"newline": "unix",
	"path": "/usr/sbin/sendmail"
}

Example (Fastmail):

"mail_settings": {
	"host": "smtp.fastmail.com",
	"port": 465,
	"auth": { "user": "youremail@fastmail.com", "pass": "YOUR_PASSWORD" },
	"secure": true
}

email_format

This string controls the email body format (default: html). Use html for styled emails or text for plain text.

email_logo

This controls the email logo image (default: inline). Use inline to include the logo as an inline attachment, link to link to the logo image URL directly, or none to hide the logo image entirely.

When this is set to inline, client.logo_url must be a local web root path under the xyOps htdocs directory, because xyOps loads the image from disk before attaching it to outgoing emails. When this is set to link, client.logo_url may be a normal linked image URL instead.

max_emails_per_day

This number caps total emails sent per day across the app (default: 0, meaning no limit); excess sends are rejected with an error.

log_dir

This string sets the base directory for server logs and job logs (default: logs), e.g., logs/Error.log and logs/jobs/ID.log.

If this is a relative path, it is computed from the xyOps base directory, which is typically /opt/xyops.

log_filename

This string is the filename pattern used by the core logger (default: [component].log); supports log column placeholders like [component].

log_columns

This array of strings controls which log columns are written and their order.

Default:

["hires_epoch", "date", "hostname", "pid", "component", "category", "code", "msg", "data"]

See pixl-logger for more details.

log_archive_path

This string sets the nightly log archive path pattern (default: logs/archives/[yyyy]/[mm]/[dd]/[filename]-[yyyy]-[mm]-[dd].log.gz); maintenance gzips and writes logs here.

Accepts date/time placeholders to dynamically generate the log archive filenames.

log_archive_keep

This string specifies how long to keep log archives for, e.g. 30 days.

Older log archives found in log_archive_path are automatically deleted after the nightly logs are rotated.

Set this to an empty string to disable the feature and keep log archives indefinitely.

log_archive_storage

Optionally archive logs to storage instead of local disk. This is primarily designed for 3rd party storage engines like S3. To use this feature, first disable log_archive_path (set to empty string), and then set this property accordingly.

Example:

"log_archive_storage": {
	"enabled": true,
	"key_template": "logs/archives/[yyyy]/[mm]/[dd]/[filename]-[yyyy]-[mm]-[dd].log.gz",
	"expiration": "1 year"
}

log_crashes

This boolean enables capturing uncaught exceptions and crashes in the logger subsystem (default: true).

The crash log location will be: /opt/xyops/logs/crash.log

tickets

This section configures the ticketing subsystem.

tickets.email_enabled

This boolean enables ticket-related outgoing emails such as new/overdue notifications (default: true).

tickets.email_debounce_sec

This number (seconds) sets the minimum spacing between repeated ticket update emails to reduce noise (default: 30).

For example, if a user makes a series of sequential changes to a ticket, only one email will be sent in a 30-second window, containing a summary of all the accumulated changes.

tickets.overdue_schedule

This string (HH:MM) sets the daily time when the system scans for overdue tickets and sends notices (default: 04:30).

tickets.overdue_query

This string is the Unbase-style search query used to select overdue tickets during the scheduled scan (default: status:open due:<today).

tickets.due_date_format

This date format string controls how ticket due dates are displayed (default: [dddd], [mmmm] [mday], [yyyy]).

tickets.date_time_format

This date/time format string controls how ticket timestamps are displayed (default: [dddd], [mmmm] [mday], [yyyy] [hour12]:[mi] [ampm]).

hooks

This object defines system-wide hook triggers that can fire on any logged activity.

Example:

{ "job_complete": { "web_hook": "wmhv3s16ymk" } }

See System Hooks for more details.

hook_text_templates

This object provides message templates for jobs and alerts; Mustache-style placeholders populate human-readable text for emails and web hooks (default includes templates like {{links.job_details}}).

Example set:

{
  "job_start": "Job started on {{nice_server}}: {{event.title}}: {{links.job_details}}",
  "job_success": "Job completed successfully on {{nice_server}}: {{event.title}}: {{links.job_details}}",
  "job_error": "Job failed on {{nice_server}}: {{event.title}}: Error ({{job.code}}): {{job.description}}: {{links.job_details}}",
  "job_progress": "Job is in progress on {{nice_server}} ({{event.title}}): {{links.job_details}}",
  "job_suspended": "Job is suspended and requires human intervention: {{event.title}}: {{links.job_details}}&resume=1",
  "job_limited": "{{action.msg}}: {{links.job_details}}",
  "alert_new": "Alert: {{nice_server}}: {{def.title}}: {{alert.message}}: {{links.alert_url}}",
  "alert_cleared": "Alert Cleared: {{nice_server}}: {{def.title}}"
}

See JobHookData and AlertHookData for a list of the placeholder macros you can use here.

multi

This section configures the multi-server subsystem.

multi.enable_version_checks

When set to true, xyOps will check for version updates of the core app, which will make external web requests to the Release Metadata URL.

multi.list_url

This URL string points to the release metadata used by multi-conductor upgrade flows (default: https://api.github.com/repos/pixlcore/xyops/releases).

multi.protocol

This string selects the WebSocket protocol for peer communications (default: ws:); set to wss: to require TLS.

multi.connect_timeout_sec

This number (seconds) sets the connection timeout for initial peer socket connections (default: 3).

multi.master_timeout_sec

This number (seconds) is used for the election timer and general control timeouts for conductor operations (default: 10).

multi.socket_opts

This object holds options merged into the WebSocket client, e.g., TLS options for self-signed certs.

Default:

{ "rejectUnauthorized": false }

multi.preferred_conductors

This optional array lists your preferred conductor servers (by their exact hostnames), in order from highest to lowest priority. If a preferred conductor is online and outranks the current primary (or the current primary is not preferred), and it satisfies the minimum age requirement, the current primary will relinquish command.

multi.relinquish_min_age

The minimum "age" of a peer conductor (time since last connect in seconds) that must be met before the current primary conductor will consider relinquishing command to it. This field is only applicable if you specify a list of preferred conductors.

multi.relinquish_wait_jobs

When checked, the peer relinquish operation will wait for all active jobs to complete, before the current primary conductor relinquishes command to a higher-ranked preferred one. This field is only applicable if you specify a list of preferred conductors.

satellite

This section configures xySat, our remote satellite agent.

satellite.enable_version_checks

When set to true, xyOps will check for version updates of the xySat app, which will make external web requests to the Release Metadata URL.

satellite.list_url

This URL string points to the release metadata for the satellite agent (default: https://api.github.com/repos/pixlcore/xysat/releases).

satellite.base_url

This URL string is the base for satellite downloads/upgrades (default: https://github.com/pixlcore/xysat/releases).

satellite.image

This is the Docker image to use when adding Docker-based satellite servers via the UI (default: ghcr.io/pixlcore/xysat).

satellite.version

This string sets the desired satellite version to fetch; may be a semver or tag (default: latest).

satellite.cache_ttl

This number (seconds) sets the cache TTL for satellite release metadata and tarballs to reduce network calls (default: 3600).

satellite.config

This object contains web server and runtime settings for xySat; these options are passed along when managing or provisioning satellite nodes (defaults provided in the sample config).

marketplace

This section configures the xyOps Marketplace.

marketplace.enabled

This boolean enables or disables the marketplace. If disabled, users cannot search for or install plugins. The default is true (enabled).

marketplace.metadata_url

This string points to the central marketplace metadata location, which contains the full product catalog.

Example:

https://raw.githubusercontent.com/pixlcore/xyops-marketplace/refs/heads/main/marketplace.json

marketplace.repo_url_template

This string is a template used to generate plugin repository URLs to specific files. It has placeholder macros for id (org and repo), version (git tag), and filename.

Example:

https://raw.githubusercontent.com/[id]/refs/tags/[version]/[filename]

marketplace.ttl

This is the number of seconds to cache the marketplace metadata locally before re-fetching from origin. The default is 3600 (one hour).

default_user_privileges

This object sets default privileges for new users (defaults include create/edit events, run/tag/comment jobs, and ticket permissions) unless overridden by roles or SSO.

See Privileges for more details on privileges.

default_user_prefs

This object sets default UI preferences for new users (locale, theme, motion/contrast, volume, saved searches, etc.), merged into profiles at creation/login.

See User for details on what properties can be specified here.

db_maint

These settings are used during nightly database maintenance.

db_maint.jobs.max_rows

This number sets the maximum rows retained for the jobs database table (default: 1000000); oldest are pruned during maintenance.

db_maint.alerts.max_rows

This number sets the maximum rows retained for the alerts database table (default: 100000); oldest are pruned during maintenance.

db_maint.snapshots.max_rows

This number sets the maximum rows retained for the snapshots database table (default: 100000); oldest are pruned during maintenance.

db_maint.activity.max_rows

This number sets the maximum rows retained for the activity database table (default: 100000); oldest are pruned during maintenance.

db_maint.servers.max_rows

This number sets the maximum rows retained for the servers database table (default: 10000); oldest are pruned during maintenance.

airgap

This section is for airgap mode, which can prevent xyOps from making unauthorized outbound connections beyond a specified IP range.

See Air-Gapped Mode for more details.

airgap.enabled

This boolean enables outbound network egress controls for server-initiated HTTP(S) requests (default: false).

airgap.whitelist

This array of CIDRs/hosts defines destinations explicitly allowed for outbound requests (default includes local/private networks); when enabled, only these are permitted.

airgap.blacklist

This array of CIDRs/hosts defines destinations that are always blocked for outbound requests.

client

This section is for the client-side configuration, used in the xyOps web application.

client.name

This string is the product name displayed in the UI and included in email/version text (default: xyOps).

client.company

This string is displayed as part of the copyright message at the bottom-left corner of the UI (default: PixlCore LLC).

client.logo_url

This points to the logo used in the UI header/sidebar and in emails (default: /images/logotype.png).

For the default email_logo mode of inline, this must be a local web root path under the xyOps htdocs directory, because xyOps loads the image from disk before attaching it to outgoing emails. If email_logo is set to link, this may be a normal image URL instead.

client.hide_sidebar_sections

This array allows you to globally hide specific sidebar sections for all users, regardless of their preferences.

client.tables

This object allows you to set default sort preferences for all the sortable tables in the UI.

client.items_per_page

This number sets the default page size for list views and searches (default: 50).

client.alt_items_per_page

This number sets the secondary page size for inline widgets and dropdown lists (default: 25).

client.max_table_rows

This number caps the number of rendered table rows client-side to keep the UI responsive (default: 500).

client.max_menu_items

Upper bound for items shown in menus and dropdowns (default: 1000).

client.api_timeout_ms

This number sets the API timeout for client requests in milliseconds (default: 10000).

client.max_job_output

Maximum size of job output to display inline on the details page (default: 5 MB).

client.alt_to_toggle

Requires the user to hold the Opt/Alt key to toggle the enabled property of certain entities in the UI (prevents accidental clicks).

client.outdated_badges

When set to true, will show a colored badge on sidebar sections for outdated software versions on the Conductors, Servers and Marketplace tabs. Admin only.

client.new_event_template

Provides sensible defaults for new events (triggers, limits, actions). Used to prefill the New Event form.

client.new_ticket_template

Provides defaults for creating new tickets. Used to prefill the New Ticket form.

client.chart_defaults

Default chart rendering options (line width, smoothing, ticks). Applied to pixl-chart monitor charts in the UI.

The defaults are:

"chart_defaults": {
	"lineWidth": 2,
	"lineJoin": "round",
	"lineCap": "butt",
	"stroke": true,
	"fill": 0.5,
	"horizTicks": 6,
	"vertTicks": 6,
	"smoothingMaxSamples": 100,
	"smoothingMaxTotalSamples": 1000,
	"hoverSort": -1
}

See pixl-chart for more details.

client.editor_defaults

Default code editor preferences (tabs, indent, line wrapping) for CodeMirror fields in the UI.

The defaults are:

"editor_defaults": {
	"lineNumbers": false,
	"matchBrackets": false,
	"indentWithTabs": true,
	"tabSize": 4,
	"indentUnit": 4,
	"lineWrapping": true,
	"dragDrop": false
}

See CodeMirror for more details.

client.bucket_upload_settings

Client-side limits for bucket uploads (max files/size/types). Enforced in the UI before upload, and enforced server-side.

The defaults are:

"bucket_upload_settings": {
	"max_files_per_bucket": 100,
	"max_file_size": 1073741824,
	"accepted_file_types": ""
}

client.ticket_upload_settings

Client-side limits for ticket attachments (max files/size/types). Enforced in the UI before upload, and enforced server-side.

The defaults are:

"ticket_upload_settings": {
	"max_files_per_ticket": 100,
	"max_file_size": 1073741824,
	"accepted_file_types": ""
}

client.job_upload_settings

Client-side limits for job file uploads (max files/size/types) and default expiration for user/plugin files.

The defaults are:

"job_upload_settings": {
	"max_files_per_job": 100,
	"max_file_size": 1073741824,
	"accepted_file_types": "",
	"user_file_expiration": "30 days",
	"plugin_file_expiration": "30 days"
}

client.run_event_dialog

Client-side configuration for the "Run Event" dialog, offering the ability to globally hide specific sections.

The defaults are:

"run_event_dialog": {
	"hide_files": false,
	"hide_tags": false,
	"hide_priority": false,
	"hide_params": false
}

Storage

This section configures the backend storage subsystem used by xyOps.

For full storage system documentation, see pixl-server-storage.

Storage.engine

Selects the storage engine (e.g., Hybrid, Filesystem, SQLite, S3). The default is Hybrid, which uses a combination of SQLite for JSON data records and the filesystem for binary file storage.

See Engines for more details.

Storage.list_page_size

Default page size for storage lists (default: 100).

Storage.hash_page_size

Default page size for storage hashes (default: 100).

Storage.concurrency

Maximum concurrent I/O operations (default: 32).

Storage.transactions

Enables transactional writes (default: true). Please leave this enabled!

Storage.trans_auto_recover

Automatically recover incomplete transactions on startup (default: true).

Storage.trans_dir

Local directory for transaction rollback logs and recovery bookkeeping (default: data/_transactions). Engines with native transaction support, such as SQLite, Postgres, and Redis, do not write rollback logs for successful commits, but the directory is still used for transaction housekeeping.