Configuration Reference

Every environment variable that Infracast reads (132 variables). If a variable is not on this page, Infracast does not read it — setting it has no effect and raises no error.

How names are resolved

There are two kinds of variable, and the difference matters:

1. Prefixed variables (first table). Infracast reads the INFRACAST_-prefixed name, for example INFRACAST_JWT_SECRET. The prefixed name wins whenever it is set, even if set to the empty string. Legacy variable names from earlier releases are still accepted and log a one-time deprecation warning. A bare JWT_SECRET with no prefix is not read by the server. Use the INFRACAST_ spelling in all new configuration.
2. Exact-name variables (second table). The spelling shown is the only one honoured; there is no prefix swapping. Some carry an INFRACAST_ prefix in their exact name (for example INFRACAST_LICENSE_FILE); most carry none (for example ALLOWED_ORIGINS, SMTP_HOST).

Command-line flags take precedence over the environment for variables that have a flag (see infracast serve --help).

The Used by column shows which component reads the variable: the server, the agent, the relay, or the infracast audit configuration check only.

Prefixed variables (INFRACAST_)

Variable	Used by	Default	Description
INFRACAST_ADDR	server	—	Listen address, default :8080. Applied only while --addr is still its default.
INFRACAST_ADMIN_PASSWORD	server	—	Self-hosted only. Initial password for the admin account the server creates on first boot against an empty database. Never logged. If unset, a random password is generated and logged once. Either way the password must be changed at first login. See First Admin Account.
INFRACAST_ARTIFACTS_BACKEND	server	—	s3 or filesystem. This is the on/off switch for encrypted artifact storage: unset means the feature is off and the other ARTIFACTS_* settings are ignored. There is deliberately no default.
INFRACAST_ARTIFACTS_BACKFILL_LEGACY	server	—	Strict boolean (default off). When true, copies legacy database blobs into the artifact store and verifies each one at boot.
INFRACAST_ARTIFACTS_DIR	server	—	Data directory for the filesystem backend.
INFRACAST_ARTIFACTS_FINALIZE_LEGACY	server	—	Strict boolean. When true, verifies every legacy blob and then drops the legacy BYTEA columns. Destructive; take a backup first.
INFRACAST_ARTIFACTS_KEY_PROVIDER	server	—	kms (requires backend s3) or local (requires INFRACAST_ARTIFACTS_MASTER_KEY_FILE). Mandatory once a backend is set; there is no default.
INFRACAST_ARTIFACTS_MASTER_KEY_FILE	server	—	Path to the operator master key file for key provider local.
INFRACAST_ARTIFACTS_S3_BUCKET	server	—	Bucket for backend s3 (required for that backend).
INFRACAST_ARTIFACTS_S3_ENDPOINT	server	—	Optional custom S3 endpoint (for S3-compatible stores such as RustFS or Ceph).
INFRACAST_ARTIFACTS_S3_PATH_STYLE	server	—	true/false. A value that does not parse as a boolean is an error, not a silent false.
INFRACAST_ARTIFACTS_S3_REGION	server	—	Optional S3 region.
INFRACAST_ARTIFACTS_STS_ROLE_ARN	server	—	Optional IAM role assumed per tenant; must be a valid IAM role ARN and only applies to backend s3.
INFRACAST_AZURE_APP_CERT_FILE	server	—	Path to the Azure app certificate PEM, used when ..._APP_CERT_PEM is empty.
INFRACAST_AZURE_APP_CERT_PEM	server	—	Certificate and key (PEM) for the Azure app. Takes precedence over ..._APP_CERT_FILE.
INFRACAST_AZURE_APP_CERT_SEND_X5C	server	—	true (case-insensitive) sends the x5c chain on token requests; anything else is off.
INFRACAST_AZURE_APP_CLIENT_ID	server	—	Client id of the Infracast multi-tenant Entra app for Azure connections. Without it, Azure admin-consent and federated-app connections are reported as unavailable on this deployment.
INFRACAST_AZURE_CONSENT_REDIRECT_URI	server	—	Redirect URI registered on the Azure Entra app. If unset, derived from API_BASE_URL plus /api/v1/azure/consent/callback; if neither is set, consent is not available.
INFRACAST_CREDENTIAL_KEY	server	—	Master key for the encrypted credential vault. If unset, the vault silently falls back to the JWT secret. When INFRACAST_ENV=production and this is unset, the server refuses to start. Also available as the --credential-key flag.
INFRACAST_CREDENTIAL_KEY_NEW	server	—	infracast rekey only: the key to rotate to.
INFRACAST_CREDENTIAL_KEY_OLD	server	—	infracast rekey only: the key to rotate away from.
INFRACAST_CREDENTIAL_KMS_KEY_ID	server	—	AWS KMS key id. When set, the credential vault uses KMS envelope encryption instead of the master-key store, and the server exits if KMS initialisation fails.
INFRACAST_DB_TYPE	server	—	Storage backend. postgres is the only supported value; anything else makes the server exit.
INFRACAST_DB_URL	server	—	PostgreSQL connection string (postgres://...). Required: the server exits with no database configured if neither this nor --db-url is set. Also read by infracast user create, init and rekey.
INFRACAST_DEPLOYMENT_MODE	server	—	saas for the hosted service (skips the startup license check; licensing is per tenant). Unset means self-hosted: the server refuses to start without a valid license. Any other value is rejected at startup. See License Required.
INFRACAST_ENV	server	—	Only the exact value production has an effect: it makes the dedicated INFRACAST_CREDENTIAL_KEY mandatory. No other value is interpreted.
INFRACAST_EPSS_FILE	server	—	Path to a local EPSS scores snapshot, used in offline mode.
INFRACAST_GCP_WIF_ROLE_ARN	server	—	AWS role ARN used as the Workload Identity Federation broker for GCP connections. Empty or unset disables WIF; the setup page then offers only the service-account-key path.
INFRACAST_JWT_SECRET	server	—	HS256 signing secret for login tokens. The --jwt-secret flag wins if you pass it; the env var is only consulted while the flag still has its built-in default change-me. Also the bearer secret for the emergency /api/v1/admin/* endpoints, and the fallback credential-vault key when INFRACAST_CREDENTIAL_KEY is unset. Changing it invalidates every issued token. The server does not refuse to start on the default value; it only logs jwt_secret_is_default.
INFRACAST_KEV_FILE	server	—	Path to a local CISA KEV catalog snapshot, used in offline mode.
INFRACAST_LOG_LEVEL	server	—	debug, info, warn or error; default info. Applied only while --log-level is still info.
INFRACAST_M365_APP_CERT_FILE	server	—	Path to the M365 app certificate PEM, used when ..._APP_CERT_PEM is empty.
INFRACAST_M365_APP_CERT_PEM	server	—	Certificate and key (PEM) for the M365 app. Takes precedence over ..._APP_CERT_FILE.
INFRACAST_M365_APP_CERT_SEND_X5C	server	—	true sends the x5c chain on token requests.
INFRACAST_M365_APP_CLIENT_ID	server	—	Client id of the Infracast multi-tenant Entra app for Microsoft 365 connections (separate app from Azure).
INFRACAST_M365_CONSENT_REDIRECT_URI	server	—	Redirect URI registered on the M365 Entra app; if unset, derived from API_BASE_URL plus /api/v1/m365/consent/callback.
INFRACAST_NVD_DIR	server	—	Directory of local NVD data, used in offline mode.
INFRACAST_OFFLINE_MODE	server	—	Air-gap switch. Accepts true/1/yes/on, case-insensitive; anything else is off.
INFRACAST_PLUGIN_PROVIDERS	server	—	Comma-separated providers to route to their plugin instead of the built-in scanner. An unknown or non-routable name stops the server at boot. Providers whose built-in scanner has been deleted (m365, azure, aws, gcp) always use their plugin regardless of this list.
INFRACAST_PLUGIN_SHADOW_PROVIDERS	server	—	Comma-separated providers to run in shadow mode alongside the current route. Internal rollout control; leave unset unless instructed by Infracast support.
INFRACAST_PLUGINS_DIR	server	—	Directory scanned for plugin binaries; default plugins. Applied only while --plugins-dir is still its default.
INFRACAST_TOKEN	server	—	Bearer token used by infracast demo seeding. The agent reads the same name as its enrollment token.

Exact-name variables

Variable	Used by	Default	Description
ALLOWED_ORIGINS	server	—	Comma-separated CORS origins. Takes no INFRACAST_ prefix. Applied only while --allowed-origins is its default *; with nothing set, all origins are allowed.
API_BASE_URL	server	—	Public API origin; used only to derive the Azure/M365 consent redirect URIs when the explicit ..._CONSENT_REDIRECT_URI is unset.
APP_BASE_URL	server	—	Public UI origin used for email links, SSO redirects and consent redirects. Default https://app.infracast.io. Set it on every non-SaaS deployment or links point at the SaaS UI. Exact name.
APP_URL	server	https://app.infracast.io	Origin used only in the welcome email; default https://app.infracast.io. Distinct from APP_BASE_URL.
ASSETS_S3_BUCKET	server	—	Bucket for tenant logo uploads; if unset (or the upload fails) the logo is stored inline as base64.
AWS_DEFAULT_REGION	infracast audit only	—	infracast audit only reports it. The AWS SDK reads it independently.
AWS_MARKETPLACE_PRODUCT_CODE	server	—	Enables the AWS Marketplace integration (fulfilment endpoints and hourly metering) when non-empty.
AWS_REGION	infracast audit only	—	infracast audit only reports it. The AWS SDK reads it independently.
AWS_S3_BUCKET	infracast audit only	—	infracast audit only: counts as document storage configured. The server does not read it.
AWS_SES_REGION	infracast audit only	—	infracast audit only: counts as email configured. The server's SES sender reads SES_REGION, not this.
CAPACITY_CHECK_TOPOLOGY_NODES_DEV	server	—	Dev/test only: lowers the topology-nodes capacity alert threshold so the alert path can be exercised. Never set in production.
COLLECTOR_LIST_TIME_BUDGET	server	—	Duration (for example 15m) bounding any single paginated cloud list call; default 10m. Invalid or non-positive values fall back to the default.
CONTENT_CACHE_DIR	server	—	Local cache directory for downloaded content packs; default $TMPDIR/infracast-content for the CLI.
CONTENT_CDN_URL	server	—	Content-pack CDN base URL. The CLI default differs per command (https://content.infracast.io for content sync, a CloudFront URL elsewhere), so set it explicitly in air-gapped or self-hosted installs.
CONTENT_PUBLIC_KEY	server	—	Base64 Ed25519 public key used to verify signed content packs. An undecodable value is silently ignored.
DATABASE_URL	infracast audit only	—	Read only by the infracast audit configuration check. The server does not read it; use INFRACAST_DB_URL. audit therefore reports a database failure on a correctly configured server.
ENCRYPTION_KEY	infracast audit only	—	Read only by the infracast audit check. The server does not use it for credential encryption; see INFRACAST_CREDENTIAL_KEY.
FINDINGS_RETENTION_DAYS	server	—	Days to keep resolved findings before the daily purge deletes them; default 90. A non-integer or non-positive value is ignored.
HEAVY_REQUEST_CONCURRENCY	server	—	Maximum concurrent whole-tenant risk/report requests; default 1. Others queue.
INFRACAST_AWS_PRINCIPAL_ARN	server	—	ARN shown to customers as the principal to trust when they create the cross-account discovery role. If unset the setup page shows a visible placeholder, not a real ARN.
INFRACAST_CONFIG	agent	—	Agent only: path to the agent config file. The --config flag wins; otherwise the OS default location.
INFRACAST_LICENSE_FILE	server	—	Path to a signed license JSON file loaded at server start. Load errors are not reported: a bad path or invalid signature produces no log line and the server runs unlicensed. Confirm the loaded license through the licensing API after startup. Read by exact name.
INFRACAST_LICENSE_JSON	server	—	Base64-encoded signed license JSON (the value is base64-decoded before parsing). Errors are not reported, as for INFRACAST_LICENSE_FILE. Read by exact name.
INFRACAST_LICENSE_KEY	server	—	Base64 Ed25519 public key used to verify licenses; overrides the key embedded in the binary. Leave unset unless instructed. With neither set, license signatures are not verified.
INFRACAST_LICENSE_PRIVATE_KEY	server	—	Base64 Ed25519 private key used by the licence-issuing endpoints. Vendor-side only; a customer deployment does not need it.
INFRACAST_REPORT_SIGNING_KEY	server	—	Base64 Ed25519 private key used to sign reports and ConMon packages. For ConMon packages, an unset, undecodable or wrong-length (not 64 bytes) key means the package is left unsigned with no error. Confirm the signature on a generated package before relying on it.
INFRACAST_SELF_SCAN_TENANTS	server	—	Comma-separated tenant ids allowed to scan the operator's own AWS accounts. Unset means no tenant may.
INFRACAST_SERVER	agent	—	Agent only: server base URL, default https://api.infracast.io. The --server flag wins. Exact name; no legacy fallback.
JWT_SECRET	server	—	Read by name JWT_SECRET (no prefix) only by infracast audit and infracast content, not by the server. For serve, use INFRACAST_JWT_SECRET. A deployment that sets only INFRACAST_JWT_SECRET will see audit report "JWT_SECRET is not set".
LIFECYCLE_FROM_EMAIL	server	—	From address for lifecycle emails; falls back to SMTP_FROM / SMTP_FROM_NAME, then Infracast <noreply@infracast.io>.
LIFECYCLE_UNSUBSCRIBE_SECRET	server	—	HMAC key for unsubscribe links. If unset, a built-in default is used, which means unsubscribe links can be forged: set it on every deployment that sends lifecycle email.
METERING_SECRET	server	—	Shared secret for the internal metering endpoint (X-Metering-Secret header). If unset the endpoint always answers 401.
NVD_API_KEY	server	—	NVD API key for CVE correlation; raises NVD rate limits.
OPS_NOTIFY_EMAIL	server	—	Operator mailbox for capacity alerts and new-licence-request notifications. Capacity alerts also need SMTP_HOST and SMTP_PASSWORD.
OPS_PORTAL_URL	server	—	Operator-portal origin appended to the CORS allow-list when explicit origins are configured; default https://ops.infracast.io.
ProgramData	agent	—	Windows system variable read by the agent to locate its default config directory. Not an Infracast setting.
RELAY_ID	relay	—	Relay only: relay id. Required together with RELAY_TOKEN; the relay exits without both.
RELAY_NAME	relay	—	Relay only: display name; defaults to the host name.
RELAY_PLUGIN_DIR	relay	—	Relay only: directory of plugin binaries; default plugins/ next to the relay executable.
RELAY_PROXY_PORT	relay	—	Relay only: local proxy port, default 8443. An unparsable value is silently ignored.
RELAY_SERVER	relay	—	Relay only: WebSocket URL of the control plane, default wss://api.infracast.io/ws/relay. The --server flag wins.
RELAY_TOKEN	relay	—	Relay only: relay enrollment token. Required.
REMEDIATION_ENABLED	server	—	true or 1 enables direct remediation for all tenants. Off by default.
REMEDIATION_ENABLED_TENANTS	server	—	Comma-separated tenant ids with direct remediation enabled when REMEDIATION_ENABLED is not set.
RISK_RECORDER_TENANT_BUDGET	server	—	Duration: per-tenant time budget for the risk recorder; default 2m.
S3_BUCKET	infracast audit only	—	infracast audit only: counts as document storage configured. The server does not read it.
SAML_CERT	server	—	PEM certificate for the SAML service provider. Used only if both SAML_CERT and SAML_KEY are set; otherwise an ephemeral certificate is generated at runtime.
SAML_KEY	server	—	PEM private key paired with SAML_CERT.
SES_FROM	server	noreply@infracast.io	From address for the welcome email; default noreply@infracast.io.
SES_REGION	server	us-east-2	AWS SES region for the welcome email; default us-east-2.
SMTP_FROM	server	billing@infracast.io / noreply@infracast.io / licensing@infracast.io / reports@infracast.io	From address. The default differs by feature (reports@, noreply@, billing@, licensing@infracast.io), so set it explicitly.
SMTP_FROM_NAME	server	Infracast Billing / Infracast / Infracast Licensing / Infracast Reports	From display name. The default differs by feature, so set it explicitly.
SMTP_HOST	server	smtp.sendgrid.net	SMTP server. Report email falls back to smtp.sendgrid.net, but invite, billing, support, licensing and capacity mail only send when this is set, so treat it as required for any email.
SMTP_PASSWORD	server	—	SMTP password. No default.
SMTP_PORT	server	587	SMTP port; default 587.
SMTP_USERNAME	server	apikey	SMTP username; default apikey (the SendGrid convention).
STRIPE_SECRET_KEY	server	—	Stripe API key. Without it billing and subscription features are disabled.
STRIPE_WEBHOOK_SECRET	server	—	Stripe webhook signing secret.
SUPPORT_EMAIL	server	—	Destination for in-app support tickets; default support@infracast.io.

Stripe price identifiers (operator-run billing only)

These select Stripe price ids when an operator runs their own billing. A customer deployment does not set them. Each is read by exact name and has a built-in default, except the ones noted.

Variable	Description
STRIPE_ADDON_AGENTLESS_DISCOVERY	Stripe price id for the named add-on.
STRIPE_ADDON_AIR_GAP	Stripe price id for the named add-on.
STRIPE_ADDON_ATTACK_PATHS	Stripe price id for the named add-on.
STRIPE_ADDON_AUTO_DOCUMENTATION	Stripe price id for the named add-on.
STRIPE_ADDON_CIEM	Stripe price id for the named add-on.
STRIPE_ADDON_CONFIG_INTEL	Stripe price id for the named add-on.
STRIPE_ADDON_CONTAINER_DISCOVERY	Stripe price id for the named add-on.
STRIPE_ADDON_ENTERPRISE_STORAGE	Stripe price id for the named add-on.
STRIPE_ADDON_FEDERAL_COMPLIANCE	Stripe price id for the named add-on.
STRIPE_ADDON_FINANCIAL	Stripe price id for the named add-on.
STRIPE_ADDON_HEALTHCARE	Stripe price id for the named add-on.
STRIPE_ADDON_IAC_GOVERNANCE	Stripe price id for the named add-on.
STRIPE_ADDON_IDENTITY_DISCOVERY	Stripe price id for the named add-on.
STRIPE_ADDON_INTERNATIONAL	Stripe price id for the named add-on.
STRIPE_ADDON_MITRE_MAPPING	Stripe price id for the named add-on.
STRIPE_ADDON_NETWORK_DISCOVERY	Stripe price id for the named add-on.
STRIPE_ADDON_RISK_SCORING	Stripe price id for the named add-on.
STRIPE_ADDON_SBOM	Stripe price id for the named add-on.
STRIPE_ADDON_SECRETS_POLICY	Stripe price id for the named add-on.
STRIPE_ADDON_SIGNED_REPORTS	Stripe price id for the named add-on.
STRIPE_ADDON_THREAT_INTEL	Stripe price id for the named add-on.
STRIPE_ADDON_VIRTUALIZATION	Stripe price id for the named add-on.
STRIPE_ADDON_ZERO_TRUST	Stripe price id for the named add-on.
STRIPE_OVERAGE_BUSINESS	Stripe price id for per-tier node overage; defaults to empty.
STRIPE_OVERAGE_ENTERPRISE	Stripe price id for per-tier node overage; defaults to empty.
STRIPE_OVERAGE_ENTERPRISE_PLUS	Stripe price id for per-tier node overage; defaults to empty.
STRIPE_PRICE_BUSINESS	Stripe price id for a base tier.
STRIPE_PRICE_ENTERPRISE	Stripe price id for a base tier.
STRIPE_PRICE_ENTERPRISE_PLUS	Stripe price id for a base tier.
STRIPE_PRICE_GOV	Stripe price id for a base tier.
STRIPE_PRICE_PRO	Stripe price id for a base tier.

Obsolete and misleading names

Obsolete names — do not use

Infracast does not read these names (or, for the last group, only a diagnostic command does), so setting them does nothing.

• API_SECRET_KEY — Not used; remove it from your configuration.
• ADMIN_USERNAME — Not used. There is no environment-variable admin bootstrap; see First admin account.
• ADMIN_PASSWORD — Not used. See First admin account.
• INFRACAST_CREDENTIAL_MASTER_KEY — Not used; remove it from your configuration. The correct name is INFRACAST_CREDENTIAL_KEY.
• INFRACAST_INSECURE_SKIP_VERIFY — Not used; the relay has no such variable.
• INFRACAST_API_URL — Not used by any component.
• INFRACAST_AGENT_TOKEN — Not used. The agent reads INFRACAST_TOKEN.
• INFRACAST_TENANT_ID — Not used by the agent.
• INFRACAST_SCAN_INTERVAL — Not used by the agent.
• INFRACAST_MAX_CPU — Not used by the agent.

What this page does not cover

• Variables read by third-party libraries or the operating system: the AWS SDK credential chain (AWS_ACCESS_KEY_ID, AWS_PROFILE, …), proxy variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY), TZ, and similar.
• Variables used by deployment tooling such as Terraform, docker-compose or your CI system.
• Whether a variable is required, its valid range, or what happens when its value is malformed — read the description and test in a non-production environment if it matters.

The web UI build uses VITE_* variables at build time; those are not read by the server and are out of scope here.