Configuration

Kerrigan has two main configuration surfaces:

• Host services use environment variables. A packaged Ubuntu installation keeps them in /opt/kerrigan/.env; a source checkout can use shell environment variables or a .env file beside docker-compose.yml.
• Each device agent uses /etc/kerrigan/agent.toml. An environment variable or command-line option can override most agent settings.

This page documents runtime and operator-facing settings. Build metadata and test-fixture-only variables are intentionally omitted.

For the YAML that selects DevKits and defines setup, teardown, and test tasks, see the Workflow spec reference.

Before You Edit

On an Ubuntu host, edit the generated file and restart the affected services:

sudoedit /opt/kerrigan/.env
sudo kerrigan-ubuntu-stack up
sudo kerrigan-ubuntu-stack ps

Use one NAME=value assignment per line. Do not add shell expressions or quote values unless the quotes are meant to be part of the value. Comma-separated settings ignore surrounding whitespace and empty entries.

Boolean settings accept 1, true, yes, or on for enabled and 0, false, no, or off for disabled. Names ending in _SEC or _SECONDS are measured in seconds.

caution

The host configuration can contain GitHub, SSH, and bootstrap credentials. Do not commit it, include it in support bundles, or expose it in logs. Restrict read access to the host administrators and Kerrigan services.

Configuration Precedence

The effective value depends on which component owns the setting:

Component	Highest to lowest precedence
Ubuntu host services	Process environment, then /opt/kerrigan/.env, then the application default
Compose stack	Shell environment, then .env, then the default in docker-compose.yml
Device agent	Command-line option, environment variable, agent.toml, detected device value, then application default
GitHub dispatcher scope and credentials	Command-line option, environment variable, value saved in the Dashboard, then application default
Artifactory integration and GitHub polling state	Value saved in the Dashboard, environment variable, then application default

An empty Dashboard value falls back to the corresponding environment variable. The GitHub token is not returned by the API or Dashboard after it is saved.

Host Networking and Service URLs

Bind settings control where a service listens. URL settings control what other components or browsers connect to. For example, a Fleet Manager can bind to 0.0.0.0 while advertising http://192.168.2.1:8000 to DevKits.

Variable	Default	Description
KERRIGAN_HOST_IP	detected during setup	Host address on the DevKit-facing network. Setup uses it to generate Fleet Manager, discovery, and TFTP values.
KERRIGAN_MANAGEMENT_HOST_IP	detected during setup	Host address on the operator-facing network. The generated Dashboard URL and CORS list use this address.
KERRIGAN_FLEET_MANAGER_HOST	0.0.0.0 in Compose	Address on which the Fleet Manager API listens. This is a bind address, not a client URL.
KERRIGAN_FLEET_MANAGER_PORT	8000	Fleet Manager TCP port.
KERRIGAN_FLEET_MANAGER_URL	http://127.0.0.1:8000 in Compose	Full URL used by host-side services and the Dashboard backend. Use an address reachable from the calling component.
KERRIGAN_SERVER_URL	component-specific	Full Fleet Manager URL used by device agents, the GitHub dispatcher, and runner bridge. Agents fall back to http://127.0.0.1:8000; development dispatcher tools use port 8080. The Ubuntu setup writes the DevKit-facing URL for every component.
KERRIGAN_DASHBOARD_HOST	0.0.0.0 in Compose	Address on which the Dashboard listens.
KERRIGAN_DASHBOARD_PORT	8001	Dashboard TCP port.
KERRIGAN_DASHBOARD_PUBLIC_HOST	management host address	Hostname or address printed for operators. It does not change the Dashboard bind address.
KERRIGAN_DASHBOARD_API_URL	empty	Browser-visible Fleet Manager URL. When empty, the Dashboard uses its current scheme and hostname with port 8000. Set it explicitly when Fleet Manager uses another host or port.
KERRIGAN_CORS_ORIGINS	localhost origins in Compose	Comma-separated browser origins allowed to call Fleet Manager at startup. Each entry must include scheme and port, for example http://lab-host:8001.

Administrators can add browser-visible hostnames without restarting Fleet Manager. Open System → Kerrigan → Host Configuration, enter one hostname per line, and save. Use only the hostname from the Admin Console address—for example, kerrigan-appliance-001.example.ts.net—without http://, a port, or a path. Saved hostnames take effect immediately and persist in the Kerrigan database. Each entry is an exact hostname match; it does not authorize subdomains or wildcards. Configure the first additional hostname from an already allowed Admin Console origin or through the authenticated API.

The standard appliance uses separate DevKit and management interfaces. Keep KERRIGAN_SERVER_URL, KERRIGAN_DISCOVERY_ADVERTISE_URL, and KERRIGAN_TFTP_HOST reachable from the DevKit network. Use the management address for KERRIGAN_DASHBOARD_PUBLIC_HOST.

Storage and Images

Variable	Default	Description
KERRIGAN_DB_PATH	/data/kerrigan.db in Compose	SQLite database containing inventory, sessions, and persisted integration settings.
KERRIGAN_IMAGE_STORE_PATH	/data/system-images in Compose	Local directory for imported and downloaded system images.
KERRIGAN_SERVICES_IMAGE	kerrigan-services:local	Container image used for Fleet Manager, Dashboard, TFTP, and dispatcher services.
KERRIGAN_RUNNER_IMAGE	kerrigan-github-runner:local	Image used for ephemeral GitHub Actions runners.
KERRIGAN_DEVELOPER_PORTAL_TOKEN_PATH	/data/developer-portal-tokens.json in Compose	File in which Fleet Manager stores Developer Portal OAuth tokens.
KERRIGAN_DEVELOPER_PORTAL_STAGING	0	Use the staging Developer Portal identity endpoints instead of production.

Back up the database and image store together when moving an installation. Do not hand-edit the SQLite database.

Device Registration

Variable	Default	Description
KERRIGAN_OPEN_REGISTRATION	0	When disabled, only devices whose MAC addresses match the allowlist can register or heartbeat. Enable only in an isolated test lab.
KERRIGAN_ALLOWED_MAC_PREFIXES	68:e1:54	Comma-separated MAC prefixes accepted by registration, such as 68:e1:54,00:11:22. Matching is case-insensitive.

An empty allowlist with open registration disabled rejects all new devices. Existing identity is based on the device MAC address; local target_id and display_name values are legacy overrides and are normally left unset.

Discovery

Fleet Manager listens for LAN discovery requests, and agents use discovery when no explicit server URL is configured.

Variable	Default	Description
KERRIGAN_DISCOVERY_ENABLED	1	Enable Fleet Manager multicast responses and device-agent multicast discovery.
KERRIGAN_DISCOVERY_GROUP	239.255.77.77	IPv4 multicast group shared by Fleet Manager and agents. Change both sides together.
KERRIGAN_DISCOVERY_PORT	45777	UDP discovery port shared by Fleet Manager and agents. Change both sides together.
KERRIGAN_DISCOVERY_ADVERTISE_URL	KERRIGAN_FLEET_MANAGER_URL	Fleet Manager URL returned to agents. It must be reachable from the DevKit network and should not contain 0.0.0.0.
KERRIGAN_DISCOVERY_INTERFACES	empty	Comma-separated local IPv4 addresses on which Fleet Manager joins the multicast group. Set this on VPN or multi-interface hosts.
KERRIGAN_DISCOVERY_TIMEOUT_SECONDS	1.5	How long a device agent waits for a multicast reply.
KERRIGAN_DISCOVERY_BROADCAST_ENABLED	0	Make an agent send discovery requests to configured broadcast addresses as well as the multicast group.
KERRIGAN_DISCOVERY_BROADCASTS	empty	Comma-separated IPv4 broadcast addresses used when broadcast discovery is enabled.
KERRIGAN_DHCP_SERVER_URL	empty	Fleet Manager URL supplied to an agent by DHCP integration. It is considered after the agent file and before LAN discovery.

Agent server discovery uses this order:

1. --server-url
2. KERRIGAN_SERVER_URL
3. server_url in /etc/kerrigan/agent.toml
4. KERRIGAN_DHCP_SERVER_URL
5. UDP multicast or broadcast discovery
6. kerrigan.local and domain-derived DNS names
7. http://127.0.0.1:8000 where a command permits the local fallback

Device Agent

The packaged service reads /etc/kerrigan/agent.toml and optional overrides from /etc/kerrigan/device-agent.env.

The device-agent package installs its Python dependencies in an isolated virtual environment selected by /opt/kerrigan/device-agent/current. This supports the Python 3.11 environment on Platform 2.1.3 and Python 3.13 on Platform 3.0.0 without upgrading Debian-managed Python packages. The matching python3-venv package must be installed. The systemd service uses the virtual environment directly, and /usr/local/bin/kerrigan-device-agent links to its entry point.

Reinstalling the package migrates an existing system-wide agent to this environment, preserves agent.toml, and refreshes the agent code even when the wheel version is unchanged. Each install builds and checks a new environment under /opt/kerrigan/device-agent/releases before atomically switching the current symlink. A dependency-installation failure leaves the previous environment and service untouched. Previous environments (including the older venv directory) are retained so running processes can continue using them; they may be removed once no process uses them. It does not uninstall packages from system Python.

For system/pool software selection and controlled upgrades, see Device bundle policies.

A minimal configuration is:

# Omit server_url to use automatic discovery.
# server_url = "http://192.168.2.1:8000"
pool_id = "default"
heartbeat_interval_seconds = 15

The following TOML keys have equivalent environment variables:

TOML key	Environment variable	Default	Description
server_url	KERRIGAN_SERVER_URL	discovered	Full Fleet Manager URL. An explicit value disables later discovery methods.
pool_id	KERRIGAN_POOL_ID	default in the packaged file	Initial pool assignment requested during registration. Fleet Manager remains authoritative.
target_id	KERRIGAN_TARGET_ID	generated from device identity	Legacy stable device ID override. Normally omit it.
target_type	KERRIGAN_TARGET_TYPE	detected	Target type reported as a capability.
board	KERRIGAN_BOARD	detected	Board family reported as a capability, for example modalix.
display_name	KERRIGAN_DISPLAY_NAME	generated	Legacy display-name override. Operators can manage the name in Fleet Manager.
host_id	KERRIGAN_HOST_ID	empty	Optional physical host identifier for grouped or attached targets.
serial	KERRIGAN_SERIAL	detected/empty	Hardware serial override.
mac_addresses	KERRIGAN_MACS	detected	List in TOML or comma-separated MAC addresses in the environment. The first usable system MAC is used when omitted.
management_ip	KERRIGAN_MANAGEMENT_IP	controller route	Explicit device IP reachable from Fleet Manager for SSH management. Takes precedence over latest_ip.
latest_ip	KERRIGAN_LATEST_IP	controller route	Legacy alias for the management-address override.
os_type	KERRIGAN_OS_TYPE	detected	Operating-system identifier reported as a capability.
current_version	KERRIGAN_CURRENT_VERSION	detected	Installed software or firmware version reported by the agent.
heartbeat_interval_seconds	KERRIGAN_HEARTBEAT_INTERVAL_SECONDS	15	Interval between agent heartbeats.
n/a	KERRIGAN_DEVICE_WORKSPACE	/media/nvme/kerrigan/_work when NVMe is mounted; otherwise /tmp/kerrigan/_work	Directory recreated for each assigned task. KERRIGAN_WORKSPACE is a legacy alias. Do not point it at a directory containing persistent data.

Discovery-only TOML keys are discovery_enabled, discovery_group, discovery_port, discovery_timeout_seconds, discovery_broadcast_enabled, and discovery_broadcasts. They map to the discovery environment variables in the preceding section.

After editing the agent configuration, restart and inspect it with:

sudo systemctl restart kerrigan-device-agent
sudo systemctl status kerrigan-device-agent --no-pager
journalctl -u kerrigan-device-agent -n 100 --no-pager

Bootstrap

Bootstrap watches DHCP leases, waits for SSH on a newly attached DevKit, and installs the Kerrigan device agent. These settings apply to Fleet Manager unless identified as setup-only.

Variable	Default	Description
KERRIGAN_BOOTSTRAP_ENABLED	1	Start automatic DevKit bootstrap workers. Host-only setup writes 0.
KERRIGAN_BOOTSTRAP_DHCP_HOOK_TOKEN	generated by setup	Bearer token accepted from the local DHCP lease hook. Keep it secret and keep the hook and Fleet Manager values identical.
KERRIGAN_BOOTSTRAP_ALLOWED_MAC_PREFIXES	registration allowlist	Comma-separated MAC prefixes eligible for bootstrap. This can be narrower than the registration allowlist.
KERRIGAN_BOOTSTRAP_SSH_USER	sima	Username used for initial SSH bootstrap.
KERRIGAN_BOOTSTRAP_SSH_PASSWORD	edgeai	Password used for initial SSH bootstrap. Replace the lab default where the target image permits it.
KERRIGAN_BUNDLE_UPDATE_CONCURRENCY	4	Positive integer limiting concurrent managed bundle updates across all pools on this appliance; use 1 for serial updates. Restart Fleet Manager after changing it. Independent of bootstrap concurrency.
KERRIGAN_BOOTSTRAP_CONCURRENCY	4	Maximum bootstrap jobs executed at once.
KERRIGAN_BOOTSTRAP_MAX_ATTEMPTS	5	Maximum attempts for one bootstrap job.
KERRIGAN_BOOTSTRAP_RETRY_BASE_DELAY_SEC	30	Base delay used between bootstrap retries.
KERRIGAN_BOOTSTRAP_SSH_TIMEOUT_SEC	900	Maximum time to wait for a leased device to accept SSH.
KERRIGAN_BOOTSTRAP_COMMAND_TIMEOUT_SEC	300	Timeout for an individual remote bootstrap command.
KERRIGAN_BOOTSTRAP_EXISTING_AGENT_GRACE_SEC	90	Time to wait for an already provisioned device agent to resume after a reboot before starting a full reinstall.
KERRIGAN_BOOTSTRAP_DHCP_LEASE_SCAN_ENABLED	1	Periodically scan dnsmasq lease files to recover lease events missed by the hook.
KERRIGAN_BOOTSTRAP_DHCP_LEASE_SCAN_INTERVAL_SEC	15	Delay between lease-file scans.
KERRIGAN_BOOTSTRAP_DHCP_LEASE_FILES	detected by setup	Comma-separated file paths or glob patterns for dnsmasq lease files.
KERRIGAN_BOOTSTRAP_DEVKIT_INTERFACE	KERRIGAN_DEVKIT_INTERFACE	DevKit-facing network interface expected by the DHCP hook.
KERRIGAN_BOOTSTRAP_DEVKIT_HOST_IP	KERRIGAN_HOST_IP	Host address used to build the Fleet Manager URL written to the agent.
KERRIGAN_DEVKIT_INTERFACE	detected by setup	Host interface connected to DevKits. The firewall blocks host SSH and applies the DevKit forwarding boundary on this interface.
KERRIGAN_UPLINK_INTERFACE	detected by setup	Host interface carrying Internet and management traffic.
KERRIGAN_DEVKIT_SUBNET	detected by setup	IPv4 subnet assigned to DevKits. Packets with another source address arriving on the DevKit interface are dropped.
KERRIGAN_DEVKIT_ALLOWED_EGRESS	empty	Comma-separated exceptions for designated protected destinations. Each entry is IPv4-CIDR, IPv4-CIDR:tcp:PORT, or IPv4-CIDR:udp:PORT; for example, 10.20.30.40/32:tcp:2049 permits NFSv4 to one server. Exceptions are evaluated before protected-network rejects.
KERRIGAN_DEVKIT_ADDITIONAL_PROTECTED_CIDRS	empty	Comma-separated internal IPv4 CIDRs to block in addition to private, link-local, special-use, multicast, and the directly connected uplink network. Use this for corporate networks that use public address space or routed internal ranges.
KERRIGAN_BOOTSTRAP_SIMA_CLI_INSTALL_COMMAND	built-in install command	Shell command used to install sima-cli on a DevKit. Override only for a controlled mirror or pinned installer.
KERRIGAN_BOOTSTRAP_DEVICE_AGENT_INSTALL_COMMAND	built-in Neat install command	Shell command used to install the device-agent package. Override to select a controlled branch or package source.

The setup-only variables KERRIGAN_BOOTSTRAP_DHCP_HOOK_PATH and KERRIGAN_BOOTSTRAP_DNSMASQ_CONF change where kerrigan-ubuntu-setup writes its DHCP integration files; they do not change a running Fleet Manager.

TFTP and Firmware Updates

Variable	Default	Description
KERRIGAN_TFTP_HOST	0.0.0.0 in the service; DevKit host IP after setup	Local address on which the TFTP server listens. Prefer the DevKit-facing address on an appliance.
KERRIGAN_TFTP_PORT	69	TFTP UDP port. Physical DevKit netboot requires port 69.
KERRIGAN_TFTP_IP_MAC_MAP	empty	Optional static mapping used when ARP cannot resolve a requester. Use comma-separated IP=MAC pairs or a JSON object.
KERRIGAN_TFTP_STATUS_PATH	/data/tftp-status.json in Compose	Status file shared with Fleet Manager for TFTP health reporting.
KERRIGAN_FIRMWARE_UPDATE_MODE	real	real performs updates; simulated exercises the state machine without changing a device.
KERRIGAN_FIRMWARE_MAX_PARALLEL_MAINTENANCE	10	Fleet-wide limit for simultaneous firmware maintenance jobs. Pool limits can reduce actual concurrency further.
KERRIGAN_FIRMWARE_SSH_USER	sima	SSH username used during firmware workflows.
KERRIGAN_FIRMWARE_SSH_PASSWORD	edgeai	SSH password used during firmware workflows.
KERRIGAN_DEVICE_CLEANUP_COMMAND_TIMEOUT_SEC	900	Maximum time for a DevKit cleanup command.
KERRIGAN_DEVICE_CLEANUP_HEARTBEAT_TIMEOUT_SEC	120	Maximum wait for a fresh healthy heartbeat before cleanup releases its reservation.
KERRIGAN_FIRMWARE_PREFLIGHT_ENABLED	1	Check device reachability before starting the update.
KERRIGAN_FIRMWARE_PREFLIGHT_TIMEOUT_SEC	2	Timeout for the preflight reachability check.
KERRIGAN_FIRMWARE_WAIT_NETBOOT_STARTED_TIMEOUT_SEC	600	Maximum wait for the device to begin network boot.
KERRIGAN_FIRMWARE_WAIT_SSH_TIMEOUT_SEC	900	Maximum wait for SSH after flashing.
KERRIGAN_FIRMWARE_POST_REBOOT_TIMEOUT_SEC	900	Maximum wait for the final post-update reboot.
KERRIGAN_FIRMWARE_LOG_DIR	<database-directory>/firmware-update-logs	Directory for per-update logs.
KERRIGAN_FIRMWARE_LOG_MAX_FILE_BYTES	16777216	Maximum size of each OTA JSONL log segment.
KERRIGAN_FIRMWARE_LOG_BACKUP_COUNT	3	Rotated OTA log segments retained per job (four segments total including the active file).
KERRIGAN_FIRMWARE_LOG_MAX_TOTAL_BYTES	2147483648	Global cap for inactive OTA JSONL logs. Active job logs remain protected by their per-job rotation cap.
KERRIGAN_FIRMWARE_HISTORY_RETENTION_DAYS	30	Maximum age of terminal OTA jobs and their events. Active jobs are never pruned.
KERRIGAN_FIRMWARE_HISTORY_MAX_JOBS_PER_TARGET	50	Maximum terminal OTA jobs retained per target, independent of age.
KERRIGAN_FIRMWARE_HISTORY_MAX_JOBS	500	Fleet-wide maximum terminal OTA jobs retained in SQLite.
KERRIGAN_FIRMWARE_DEVICE_AGENT_PACKAGE_DIR	empty	Optional local device-agent package directory used during post-flash setup.

Detailed command output is kept in rotating JSONL files instead of SQLite. With the defaults, one job uses at most four 16 MiB segments. Fleet Manager removes those segments together with terminal database history after 30 days, once a target has more than 50 terminal jobs, or once the fleet has more than 500. Inactive JSONL logs also have a 2 GiB fleet-wide cap; active jobs are never pruned. Deleted SQLite pages are reused, and Fleet Manager checkpoints the WAL after pruning so normal OTA use does not cause unbounded database or WAL growth.

KERRIGAN_FIRMWARE_SIMA_CLI_INSTALL_COMMAND and KERRIGAN_FIRMWARE_DEVICE_AGENT_INSTALL_COMMAND replace the built-in remote installation commands. Treat them as advanced settings: they are executed by a shell on the target and should be pinned, reviewed, and tested before use.

The built-in device-agent commands for bootstrap and firmware recovery use the CLI's default production artifact environment and select the develop branch. The branch selects the software version independently of the artifact environment.

GitHub Dispatcher

Repository credentials and scope can be set in the Dashboard. For the running dispatcher, command-line options and non-empty environment variables override Dashboard-saved values. The saved pause state is applied immediately and overrides its environment fallback. Configure exactly one of a repository or an organization.

Variable	Default	Description
KERRIGAN_GITHUB_TOKEN	empty	GitHub token used to list Actions jobs and create ephemeral runner registration tokens.
KERRIGAN_GITHUB_REPO	empty	Single repository to poll, in owner/name form. Mutually exclusive with KERRIGAN_GITHUB_ORG.
KERRIGAN_GITHUB_ORG	empty	Organization to poll. Mutually exclusive with KERRIGAN_GITHUB_REPO.
KERRIGAN_GITHUB_BRANCH	empty	Optional branch filter applied when listing queued workflow runs. Empty accepts all branches.
KERRIGAN_GITHUB_ALLOWED_REPOS	empty	Comma-separated owner/name allowlist. For organization scope, empty means every repository visible to the token.
KERRIGAN_GITHUB_API_URL	https://api.github.com	GitHub REST API base URL. Set the API URL for GitHub Enterprise Server.
KERRIGAN_GITHUB_POLLING_PAUSED	0	Pause new queued-job polling without removing the configuration. The Dashboard can change this at runtime.
KERRIGAN_GITHUB_POLL_INTERVAL_SEC	5	Delay between GitHub API polling cycles.
KERRIGAN_GITHUB_MAX_RUNNERS	2	Maximum ephemeral runner containers active at once. This limits GitHub job pickup, not DevKit task parallelism.
KERRIGAN_RUNNER_IMAGE	kerrigan-github-runner:local	Container image launched for each queued Kerrigan job.
KERRIGAN_DOCKER_NETWORK	empty	Optional Docker network attached to ephemeral runners. Host-network installations normally leave it empty.

Only jobs whose runner labels include both self-hosted and kerrigan are eligible. KERRIGAN_GITHUB_MAX_RUNNERS is separate from manifest scheduling.max_parallel: the first limits GitHub runner containers and the second limits concurrent DevKit assignments within a Kerrigan session.

For workflow-side settings such as KERRIGAN_MANIFEST, see the Manifest Guide.

Runner bridge

The ephemeral runner bridge accepts command-line options for polling and timeouts. Only these two values have environment-variable equivalents:

Variable	Default	Description
KERRIGAN_MANIFEST	required	Path to the checked-in YAML manifest. --manifest takes precedence.
KERRIGAN_SERVER_URL	http://127.0.0.1:8080 outside the packaged stack	Fleet Manager URL to which the bridge submits and monitors the session. --server-url takes precedence.

Use --poll-interval-sec to tune status polling and --timeout-sec to set the whole-session deadline. On timeout or interruption, the bridge requests session cancellation before it exits.

Artifactory and Vulcan Reporting

Artifactory is normally configured in the Dashboard. Environment variables are useful for immutable deployments and act as fallbacks for empty saved values.

Variable	Default	Description
KERRIGAN_ARTIFACTORY_URL	https://artifacts.eng.sima.ai:443/artifactory	Artifactory base URL used to browse and download system images.
KERRIGAN_ARTIFACTORY_TOKEN	empty	Access token sent to Artifactory. Keep it secret.
KERRIGAN_ARTIFACTORY_VERIFY_SSL	1	Verify the Artifactory TLS certificate. Disable only for a controlled test endpoint.
KERRIGAN_VULCAN_PROFILE	empty	Path to an externally managed kerrigan-iot-profile.yaml. When set, activation-code pairing and local profile deletion are disabled.
KERRIGAN_VULCAN_PROFILE_DIR	beside the database under vulcan/	Directory used for the activation-code-paired cloud profile and its TLS files.
KERRIGAN_VULCAN_PAIRING_STAGING_URL	bundled Vulcan staging URL	Pairing API stage URL for the Vulcan Staging choice.
KERRIGAN_VULCAN_PAIRING_PRODUCTION_URL	bundled Vulcan production URL	Pairing API stage URL for the Vulcan Prod choice.
KERRIGAN_ARTHAS_PAIRING_STAGING_URL	bundled Arthas staging URL	Pairing API stage URL for the Arthas Staging choice.
KERRIGAN_ARTHAS_PAIRING_PRODUCTION_URL	bundled Arthas production URL	Pairing API stage URL for the Arthas Prod choice.
KERRIGAN_VULCAN_CONNECTOR_ENABLED	1	Start MQTT reporting when a usable Vulcan profile exists.
KERRIGAN_VULCAN_HEARTBEAT_INTERVAL_SEC	30	Interval between compact MQTT heartbeat reports.
KERRIGAN_VULCAN_REPORTING_INTERVAL_SEC	60	Interval between full state reports.
KERRIGAN_VULCAN_KEEPALIVE_SEC	60	MQTT keepalive interval.
KERRIGAN_VULCAN_RECONNECT_MIN_DELAY_SEC	1	Initial reconnect backoff after an MQTT failure.
KERRIGAN_VULCAN_RECONNECT_MAX_DELAY_SEC	60	Maximum reconnect backoff. Keep this greater than or equal to the minimum.

See Configure Artifactory and Vulcan reporting for the end-to-end setup.

Host Self-Update

Variable	Default	Description
KERRIGAN_SELF_UPDATE_BRANCHES_URL	https://artifacts.neat.sima.ai/kerrigan/branches.json	Vulcan artifact branch catalog exposed to Fleet Manager. The host updater downloads it to populate the software-channel branch list when no updater-specific URL is set.
KERRIGAN_UPDATE_CATALOG_URL	KERRIGAN_SELF_UPDATE_BRANCHES_URL	Host-updater override for the release catalog URL.
KERRIGAN_UPDATE_CHANNEL	build branch or develop	Release channel selected by the host updater.
KERRIGAN_UPDATER_SOCKET	/run/kerrigan-updater/control.sock	Fleet Manager's in-container path for the host-updater Unix socket. The Compose stack maps the persistent host control directory into this path.
KERRIGAN_UPDATER_STATE_DIR	/var/lib/kerrigan-updater	Host-updater download and state directory.
KERRIGAN_UPDATE_MIN_FREE_BYTES	4294967296	Minimum free bytes required before downloading an update (4 GiB).
KERRIGAN_UPDATE_HEALTH_TIMEOUT_SEC	180	Maximum wait for the updated Fleet Manager health check.

KERRIGAN_UPDATE_CATALOG_URL, KERRIGAN_UPDATER_STATE_DIR, KERRIGAN_UPDATE_MIN_FREE_BYTES, and KERRIGAN_UPDATE_HEALTH_TIMEOUT_SEC belong in /etc/kerrigan/updater.env. Fleet Manager and stack settings, including KERRIGAN_SELF_UPDATE_BRANCHES_URL, KERRIGAN_UPDATE_CHANNEL, and KERRIGAN_UPDATER_SOCKET, belong in /opt/kerrigan/.env. The packaged systemd unit creates the host socket at /var/lib/kerrigan-updater/control/control.sock. The Compose stack bind-mounts that dedicated persistent directory at /run/kerrigan-updater inside Fleet Manager. Keep these paths aligned if the Fleet Manager socket path is customized; do not bind-mount a systemd runtime directory.

Source-Checkout Development

These settings apply to ./start.sh and are not normally needed on a packaged appliance:

Variable	Default	Description
KERRIGAN_HOST	127.0.0.1	Common fallback bind address for Fleet Manager and Dashboard.
KERRIGAN_RELOAD	1	Enable Uvicorn automatic reload. Disable for a stable local smoke test.
KERRIGAN_HTTPS	0	Serve Fleet Manager and Dashboard with TLS. Requires both certificate settings.
KERRIGAN_TLS_CERTFILE	empty	PEM certificate chain used when local HTTPS is enabled.
KERRIGAN_TLS_KEYFILE	empty	PEM private key used when local HTTPS is enabled.
KERRIGAN_TFTP_REQUIRE_START	1	Fail startup when TFTP cannot bind.
KERRIGAN_TFTP_REPLACE_STALE	1	Stop a stale Kerrigan TFTP process that owns the configured port.

Example:

KERRIGAN_HTTPS=1 \
KERRIGAN_TLS_CERTFILE=/path/to/cert.pem \
KERRIGAN_TLS_KEYFILE=/path/to/key.pem \
./start.sh

Bundled cloud endpoints

Public pairing URLs are versioned in src/kerrigan/services/fleet_manager/cloud_endpoints.toml and included in the Python package and service image. Every environment uses its bundled endpoint by default. This does not pair the system automatically.

Each KERRIGAN_*_PAIRING_*_URL variable can override its endpoint. Unset variables or the value default use the bundled configuration; an explicit empty value disables that environment. Existing installations with empty values must change them to default to opt in. Recreate Fleet Manager after changing the environment.

Host updater self-restart

After a successful update, Kerrigan installs the new host updater code and service definition, records the completed update and history, then queues a restart of kerrigan-host-updater.service through systemd. This activates the new updater code without rebooting the appliance or restarting Kerrigan containers a second time. The control socket is recreated inside a persistent directory, so Fleet Manager's bind mount remains attached across the restart. Update-status polling may briefly retry while the socket itself is recreated, but the updater remains available afterward without container repair.

New update requests are blocked during the restart handoff. If the restart request fails or times out, the release remains completed and an updater_restart_warning is recorded in update status and history. Before starting another update, restart the updater manually:

sudo systemctl restart kerrigan-host-updater.service
sudo systemctl is-active kerrigan-host-updater.service

Failed or rolled-back updates do not request this automatic restart.

First upgrade: an older updater only replaces its files and does not restart itself. After the first successful installation of a release containing this feature, perform the manual restart above (or reboot the appliance) once to activate it. Subsequent successful updates restart the updater automatically.

Host update image retention

After a successful host update and service health check, the updater removes older updater-generated tags from kerrigan-services. It retains the active release, the immediately previous release, and the rollback tags needed for that previous version. The GitHub Dispatcher is currently disabled in appliance packages, so the updater also removes unused updater-owned kerrigan-github-runner images left by earlier releases. Multiple retained tags can refer to the same image without duplicating its data.

When an older appliance upgrades to a release with the dispatcher disabled, the new updater waits for the update transaction to complete, then explicitly stops and removes the legacy github-dispatcher Compose service before cleaning its unused runner images. Failed or rolled-back updates preserve the previous dispatcher and runner state. The cleanup result is recorded in updater status as disabled_service_cleanup.

Tag ownership is recorded in /var/lib/kerrigan-updater/owned-image-tags.json after the updater creates each release or rollback tag. For older installations, explicit image references in retained releases/*/release.env files also establish ownership. A timestamp suffix alone never makes a tag eligible for removal. Legacy rollback tags without recorded ownership remain untouched and may need one-time operator cleanup after their purpose is verified.

Images referenced by any running or stopped container remain protected, as do unrelated repositories and custom tags. Retained release references must be valid before cleanup begins. Cleanup uses targeted image removal without --force; it does not run a system-wide Docker prune. Errors are recorded in update status under image_cleanup and do not roll back healthy services. Cleanup does not run after failed updates, preserving recovery images.

This bounds normal updater-managed image history to two releases, except for images still used by containers or retained by custom tags.

Host update file retention

The updater passes an explicit per-update download directory to sima-cli at /var/lib/kerrigan-updater/staging/<release>. After the candidate services pass their health checks, it removes updater-managed package staging and retains only the active and immediately previous release directories and database snapshots. It also keeps the most recent 5,000 events in updates.jsonl. Cleanup warnings are recorded under file_cleanup and do not roll back healthy services.

Preflight checks free space on both the release and package-staging filesystems when they are separate. The first successful update also removes the legacy /kerrigan-services and /kerrigan-github-runner extraction trees left by older updaters, but only when each path is a valid OCI image layout with its referenced manifest present. Unexpected paths are preserved for inspection.

After a failed or rolled-back update, status events, the release directory, and the database snapshot remain available for diagnosis. The next preflight removes that update's transient package-staging directory before checking free space, so a partial download cannot permanently block recovery. Cleanup uses a durable ledger of release IDs created by the updater; a timestamp-shaped path name alone does not establish ownership. During migration, older releases present in the retained update history seed this ledger. Still older unrecorded paths are preserved for operator review because their ownership cannot be established safely. Firmware caches, downloaded system images, unrelated Docker tags, and other operator-managed storage are outside this policy. Remove downloaded system images through the Fleet Manager API or dashboard when they are no longer needed.