Skip to main content
Version: 0.4 · current

Environment variables

ReferenceReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Installer (Linux administrator)
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

Excubius reads its installation settings from the .env file in the install directory, /opt/excubius/.env by default, mode 0600, owned by the service account. The installer writes it from your answers and generates the secrets once. This reference lists the keys you can set, grouped as in the file.

Most settings live in the console, not here: branding and feature switches in Settings › Instance, names and certificates in Settings › Server, sources in Settings › Sources, monitoring credentials in Settings › Credentials. After you change the file, restart the platform as the service account with systemctl --user restart excubius.

warning

Back up the .env file, and with it EXCUBIUS_DATA_KEY. Without that key, the secrets stored in the database cannot be decrypted.

Installation​

KeyDefaultMeaning
EXCUBIUS_HOME/opt/excubiusInstall directory. Written by the installer
SERVER_NAME—The primary name: the host of the public URL
REGISTRYghcr.io/custorius-labs/excubiusRegistry and repository prefix of the images
PROXY_MODEhttphttp or https. Applies only until the certificate service has taken over; afterwards Settings › Server decides
COOKIE_SECUREemptyEmpty: session cookies are Secure whenever the request arrived over HTTPS. true or false force it. Leave it empty

Names and TLS​

These keys seed the TLS settings on the first start only, when the platform has none yet. From then on, names and certificates are managed in Settings › Server, without a restart. The installer removes the DNS credentials and the private key from the file once the platform has stored them.

KeyDefaultMeaning
TLS_MODEemptyletsencrypt_http, letsencrypt_dns, selfsigned, custom, gateway or http. The installer's names letsencrypt, letsencrypt-dns and later are accepted too
TLS_ALIASESemptyOther names users may open, separated by spaces
TLS_CERT_NAMESemptyNames to put in the certificate, separated by spaces. Empty: every name
TLS_EMAILemptyE-mail of the Let's Encrypt account
TLS_ACME_SERVERproductionstaging to rehearse with test certificates that browsers do not trust
TLS_DNS_PROVIDERemptyThe acme.sh dnsapi ID of the DNS provider, such as dns_cf or dns_azure
TLS_DNS_CREDENTIALSemptyKEY=VALUE pairs separated by new lines or ;, or base64:<…>
TLS_CERT_FILE, TLS_KEY_FILEemptybase64:<PEM contents> of your own certificate chain and private key
TLS_ACME_DNSSLEEP0Seconds to wait for DNS propagation instead of checking it through public DNS-over-HTTPS resolvers. Use it on networks that cannot reach them

Product​

KeyDefaultMeaning
PRODUCT_NAMEExcubiusFallback only. The product name comes from the branding in Settings › Instance
DEFAULT_LOCALEenDefault language
BASE_URL—The public URL, such as https://monitoring.example.com. Links in messages use it
EXCUBIUS_DEFAULT_PRESETenterpriseThe preset the instance starts from: enterprise, databases or core
EXCUBIUS_FEATURES_ENFORCE_APIfalsetrue: switched-off features are also refused by the API. Default: they are hidden in the interface only

Database and secrets​

KeyDefaultMeaning
POSTGRES_USERexcubiusDatabase user
POSTGRES_PASSWORDgeneratedLetters and digits only, because it is embedded in a connection URL
POSTGRES_DBexcubiusDatabase name
DATABASE_URLbuilt from the three aboveConnection URL. The containers receive it built from the three keys above
EXCUBIUS_DATA_KEYgeneratedKey that encrypts the secrets stored in the database: credentials, source secrets, DNS API keys. 32 random bytes, URL-safe base64. Never change it on a running installation
EXCUBIUS_COLLECTOR_TOKENgeneratedShared secret between the collector and the API. Empty: the collector idles and the collector endpoints are disabled

Sign-in​

KeyDefaultMeaning
JWT_SECRETgeneratedSigns the session tokens. 64 random characters
ACCESS_TOKEN_MINUTES15Lifetime of an access token
REFRESH_TOKEN_DAYS14Lifetime of a session
ENTRA_TENANT_ID, ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRETemptyMicrosoft Entra ID sign-in, single tenant: the directory ID, not common or organizations. Offered once all three are set. Redirect URI: <BASE_URL>/api/v1/auth/entra/callback
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRETemptyGoogle sign-in. Redirect URI: <BASE_URL>/api/v1/auth/google/callback
ALLOWED_SIGNUP_DOMAINSemptyE-mail domains, separated by commas, whose people get an account as viewer on the root at their first sign-in. Applies only until a registration mode is saved on the root entity. Empty: invitation only

The client secrets are never stored in the database or logged.

Monitoring core​

KeyDefaultMeaning
EXCUBIUS_UNREACHABLE_AFTER3Consecutive connection, sign-in or timeout failures before a resource gets its Cannot reach alert
EXCUBIUS_NOTIFY_QUIET_MINUTES10Minimum minutes between two messages for the same condition. A rising severity always goes out
EXCUBIUS_COLLECTOR_VIA_PROXYfalsetrue only for a collector outside the server that reaches the API through the public address

Collector​

The collector container receives only these keys, never the whole file.

KeyDefaultMeaning
EXCUBIUS_COLLECTOR_TOKENgeneratedSee Database and secrets
EXCUBIUS_COLLECTOR_TRANSPORTSevery transport presentComma-separated subset to offer, such as tsql,http,dns. Values: tsql, http, dns, winrm, ssh, azure_graph, defender, entra, wazuh
EXCUBIUS_COLLECTOR_CONCURRENCY32Checks running at once
EXCUBIUS_TSQL_THREADS16Threads for SQL Server connections
EXCUBIUS_SQL_APP_NAMEmonitoring-collectorApplication name of the collector's SQL Server sessions
EXCUBIUS_ODBC_DRIVERODBC Driver 18 for SQL ServerODBC driver name
AZURE_SUBSCRIPTION_IDSemptyComma-separated subscriptions for the native Resource Graph checks (cloud security, Azure Update Manager) when the credential sets none. Empty: every subscription the identity can read. The Azure Monitor source has its own list
AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRETemptyEmpty: the server's managed identity. AZURE_CLIENT_ID alone names a user-assigned managed identity. All three: that service principal is used instead

The collector also has settings for its polling intervals, batch and buffer sizes and host name, but the installed platform does not pass them to its container, so their defaults apply: assignments every 30 seconds, jobs every 10 seconds, a heartbeat every 60 seconds, 200 results per batch, 10,000 results kept while the API is unreachable.

Notifications and tickets​

KeyDefaultMeaning
SLACK_BOT_TOKENemptyBot token of the Slack app, with the scope chat:write. Empty: nothing is sent to Slack
SLACK_DEFAULT_CHANNEL#alertsReceives warnings and criticals when no entity on the path has a channel
JIRA_BASE_URLemptyhttps://<site>.atlassian.net
JIRA_AUTHtokentoken (e-mail and API token), oauth (client credentials of an Atlassian service account) or bearer
JIRA_EMAIL, JIRA_API_TOKENemptyCredentials for token
JIRA_OAUTH_CLIENT_ID, JIRA_OAUTH_CLIENT_SECRETemptyCredentials for oauth
JIRA_CLOUD_IDemptyoauth only: the site's cloud ID
JIRA_OAUTH_TOKEN_URLhttps://auth.atlassian.com/oauth/tokenToken URL for oauth
JIRA_DEFAULT_PROJECTemptyProject key for new issues
JIRA_ISSUE_TYPETaskIssue type name in that project
JIRA_SYNC_MINUTES10How often the status of open issues is read
WEB_PUSH_VAPID_PUBLIC, WEB_PUSH_VAPID_PRIVATEemptyReserved for web push notifications, not available in this release. Leave them empty

The Jira keys are defaults: each entity may override them in its own Jira settings. See Create Jira issues from alerts.

Updates and security worker​

KeyDefaultMeaning
EXCUBIUS_SECURITY_WORKERtrueThe API's background worker: vendor feeds, risk acceptance expiry, checks run by the API, security score snapshots, Jira status. Set false only on extra API replicas
EXCUBIUS_FEEDS_ENABLEDtruefalse: never fetch the vendor feeds, for air-gapped installations. The copies shipped with the release are used
EXCUBIUS_FEED_TIMEOUT_SECONDS60Timeout per feed request
EXCUBIUS_FEED_SQLSERVER_BUILDS_URLSthe dbatools site, then GitHubSpace-separated URLs of the SQL Server build list, tried in order. Put an internal mirror first
EXCUBIUS_FEED_ENDOFLIFE_URLhttps://endoflife.date/apiBase URL of the end-of-support feed
EXCUBIUS_FEED_MSRC_URLhttps://api.msrc.microsoft.com/cvrf/v3.0Base URL of the Microsoft security advisories
EXCUBIUS_FEED_MSRC_MONTHS3Monthly releases kept up to date, from 1 to 24
HTTPS_PROXYemptyProxy for the feed requests

Keys this release does not read​

The shipped .env.example still lists NEWRELIC_API_KEY, NEWRELIC_ACCOUNT_ID, NEWRELIC_WEBHOOK_SECRET, NINJAONE_CLIENT_ID, NINJAONE_CLIENT_SECRET, NINJAONE_REGION, WAZUH_API_URL, WAZUH_API_USER and WAZUH_API_PASSWORD. This release ignores them. Configure New Relic and NinjaOne in Settings › Sources, and Wazuh with a credential and the check's parameters; see Sources and Cloud security.