Environment variables

Deploy-time environment variables for Lerian SPI: BACEN SPI/DICT connectivity, ISO 20022 signing certificates, PII encryption, persistence, and streaming.

Lerian SPI is Lerian’s native messaging integration for Pix. It reaches BACEN’s instant-payment system (SPI) and the DICT key directory over the RSFN. It ships four runtime binaries — spi, dict, brcode, and core — so its variable set is broad.

The service reads every variable at startup. When systemplane is on — the default — it can override a subset at runtime without a restart. The rest of the variables need a restart to change. For the knobs that behave the same across every Lerian Go service — deployment posture, datastores, multi-tenancy, telemetry, streaming — see BYOC configuration essentials.

In the tables below, Required marks a variable you must set — globally, or under the condition named. — means no default.

Most BACEN-facing variables carry a surface prefix: BACEN_SPI_* for the SPI settlement transport, BACEN_DICT_* for the DICT client, BACEN_BRCODE_JOSE_* for BR Code JOSE signing, and BACEN_ICOM_* for the inbound long-poll channel.

Runtime and server

Variable	Description	Default	Required
ENV_NAME	Runtime environment label. When unset, it resolves to development; an explicit none is invalid. Production arms stricter security gates.	development	No
LOG_LEVEL	Log verbosity (debug, info, warn, error).	info	No
SERVER_ADDRESS	Main HTTP listen address (host:port or :port). Liveness, readiness, and systemplane bind this port.	:8080	No
HTTP_BODY_LIMIT_BYTES	Maximum request body size in bytes.	1048576	No
PUBLIC_BASE_URL	Externally reachable base URL of the service, used to build absolute callback URLs and BR Code payload links.	—	In production or if BR Code JOSE is enabled
ACCESS_CONTROL_ALLOW_ORIGIN	Allowed CORS origins.	http://localhost:3000	No
ACCESS_CONTROL_ALLOW_METHODS	Allowed CORS methods.	GET,POST,PUT,PATCH,DELETE,OPTIONS	No
ACCESS_CONTROL_ALLOW_HEADERS	Allowed CORS request headers.	(standard set)	No
TRUSTED_PROXIES	Comma-separated proxy IPs/CIDRs trusted to set the real client IP.	—	No
SERVER_TLS_CERT_FILE	Path to the server TLS certificate. Set together with the key file.	—	No
SERVER_TLS_KEY_FILE	Path to the server TLS private key. Sensitive.	—	No
SERVER_TLS_CLIENT_CA_FILE	CA file for verifying client certificates (mutual TLS).	—	No
TLS_TERMINATED_UPSTREAM	Set true when TLS is terminated by a load balancer or reverse proxy.	false	No

Authentication

Lerian SPI authorizes protected routes — including the systemplane admin API — through Access Manager.

Variable	Description	Default	Required
AUTH_ENABLED	Require Access Manager authentication on protected routes.	false	In production
PLUGIN_AUTH_ADDRESS	Access Manager service address.	—	If enabled
AUTH_TRUST_UPSTREAM_METADATA	Trust identity metadata forwarded by an upstream proxy. Leave false unless the proxy is trusted.	false	No

BACEN callback (inbound from SPI)

Variable	Description	Default	Required
BACEN_CALLBACK_TRUSTED_PROXY_CIDRS	CIDRs trusted as the source of BACEN callbacks.	—	No
BACEN_CALLBACK_MTLS_HEADER_SECRET	Shared secret proving the upstream terminated the callback mutual-TLS. Sensitive.	—	If the primary ICOM consumer is enabled

SPI settlement transport (BACEN_SPI_*)

Connection to BACEN’s SPI settlement endpoint over the RSFN, with an optional secondary endpoint and the archive (ARQ) endpoint.

Variable	Description	Default	Required
BACEN_SPI_ENDPOINT	Primary SPI endpoint URL.	http://localhost:9900	Yes (live SPI)
BACEN_SPI_SECONDARY_ENDPOINT	Secondary SPI endpoint URL for failover.	—	If the secondary ICOM consumer is enabled
BACEN_ARQ_ENDPOINT	ARQ (archive/batch) endpoint URL.	—	No
BACEN_SPI_PARTICIPANT_ISPB	The participant’s ISPB for the SPI surface.	—	Yes (live SPI)
BACEN_SPI_ALLOWED_ENDPOINT_HOSTS	Allow-list of hosts the SPI client may reach (SSRF guard).	—	No
BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS	Allow-list for the secondary endpoint.	—	No
BACEN_ARQ_ALLOWED_ENDPOINT_HOSTS	Allow-list for the ARQ endpoint.	—	No
BACEN_SPI_TIMEOUT_SEC	Request timeout (seconds).	30	No
BACEN_SPI_INITIATION_TIMEOUT_MS	Payment-initiation timeout (milliseconds).	150	No
BACEN_SPI_INBOUND_CALLBACK_TIMEOUT_MS	Inbound-callback processing timeout (milliseconds).	250	No
BACEN_SPI_RETRY_ATTEMPTS	Retry attempts on transport failure.	3	No
BACEN_SPI_RETRY_INITIAL_BACKOFF_MS	Initial retry backoff (milliseconds).	500	No
BACEN_SPI_RETRY_MAX_BACKOFF_MS	Maximum retry backoff (milliseconds).	5000	No
BACEN_SPI_OUTBOUND_QUOTA_ENABLED	Enable client-side outbound rate quota.	false	No
BACEN_SPI_OUTBOUND_QUOTA_LIMIT	Sustained outbound quota (requests).	—	If quota enabled
BACEN_SPI_OUTBOUND_QUOTA_BURST	Burst allowance above the quota.	—	If quota enabled
BACEN_SPI_CATALOGUE_VERSION	BACEN SPI message-catalogue version.	5.12.1	No
BACEN_SPI_XSD_DIR	Directory of the bundled BACEN XSD schemas for the catalogue.	Bundled path	No
BACEN_SPI_CATALOGUE_ROOT	Override root for the message catalogue.	—	No
BACEN_SPI_INTERNAL_CALLBACK_SECRET	Shared secret for the internal callback path. At least 32 characters when set. Sensitive.	—	In production or if the primary ICOM consumer is enabled

mutual TLS to BACEN

The BACEN_TLS_* files back the mutual-TLS channel to BACEN. The SPI and DICT clients share them.

Variable	Description	Default	Required
BACEN_TLS_CERT_FILE	Client certificate presented to BACEN.	—	Yes (live)
BACEN_TLS_KEY_FILE	Client private key. Sensitive.	—	Yes (live)
BACEN_TLS_CA_FILE	CA bundle used to verify BACEN’s server certificate.	—	Yes (live)

Message signing and certificates

Lerian SPI digitally signs its outbound messages. Pick a custody backend with BACEN_SPI_SIGNER_KIND.

Variable	Description	Default	Required
BACEN_SPI_SIGNER_KIND	Signing custody backend: file, pkcs11, or kmip. Use a hardware backend in production.	file	No
BACEN_SPI_SIGNER_COMMON_NAME	Expected common name of the signing certificate.	—	No
BACEN_SPI_SIGNING_CERT_FILE	Path to the certificate bound to the signing key. Required for pkcs11 or kmip; for file, it falls back to BACEN_TLS_CERT_FILE when unset.	BACEN_TLS_CERT_FILE (file)	If pkcs11 or kmip
BACEN_SPI_INBOUND_SIGNER_COMMON_NAME	Expected common name of the signer on inbound messages.	—	No
CERT_READINESS_MIN_DAYS	Minimum days-to-expiry before the certificate readiness check reports degraded.	14	No
BACEN_SPI_PKCS11_MODULE_PATH	PKCS#11 module library path.	—	If pkcs11
BACEN_SPI_PKCS11_TOKEN_LABEL	PKCS#11 token label.	—	If pkcs11
BACEN_SPI_PKCS11_PIN_FILE	Path to a file holding the token PIN. Sensitive.	—	If pkcs11
BACEN_SPI_PKCS11_KEY_LABEL	Signing-key label on the token.	—	If pkcs11
BACEN_SPI_KMIP_BASE_URL	KMIP service base URL.	—	If kmip
BACEN_SPI_KMIP_VHSM	Virtual HSM identifier.	—	If kmip
BACEN_SPI_KMIP_CRYPTO_USER	KMIP crypto user.	—	If kmip
BACEN_SPI_KMIP_CRYPTO_USER_TOKEN	KMIP crypto-user token. Sensitive.	—	If kmip
BACEN_SPI_KMIP_SIGN_PRIVATE_KEY_UID	UID of the signing private key.	—	If kmip
BACEN_SPI_KMIP_SIGN_PUBLIC_KEY_UID	UID of the signing public key.	—	If kmip
BACEN_SPI_KMIP_DIGEST_INFO_PREFIX	Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.	false	No

Certificate validation (OCSP/CRL)

Variable	Description	Default	Required
BACEN_SPI_OCSP_MODE	Certificate revocation-check mode (e.g. soft_fail).	soft_fail	No
BACEN_SPI_OCSP_TIMEOUT_MS	OCSP request timeout (milliseconds).	3000	No
BACEN_SPI_OCSP_CACHE_TTL_CAP_SEC	Cap on cached OCSP response TTL (seconds).	3600	No
BACEN_SPI_OCSP_CRL_CACHE_TTL_SEC	CRL cache TTL (seconds).	3600	No

Payload resolver

These variables control how the service stores and references large SPI payloads.

Variable	Description	Default	Required
BACEN_SPI_PAYLOAD_RESOLVER_KIND	Payload storage backend: in_memory or postgres. Production-like environments refuse in_memory — use a durable backend.	in_memory	No
BACEN_SPI_PAYLOAD_RESOLVER_IN_MEMORY_MAX_BYTES	Max bytes held by the in-memory resolver.	134217728	No
BACEN_SPI_PAYLOAD_RESOLVER_TTL_SEC	Retention TTL for resolved payloads (seconds).	86400	No
BACEN_SPI_PAYLOAD_RESOLVER_ENCRYPTION_KEY	AES-256 key for encrypting stored payloads. Sensitive.	—	If kind is postgres

Inbound channel (BACEN_ICOM_*)

Long-poll channel for messages BACEN pushes back to the participant.

Variable	Description	Default	Required
BACEN_ICOM_BASE_URL	Inbound channel base URL.	—	If the primary ICOM consumer is enabled
BACEN_ICOM_ISPB	Participant ISPB for the inbound channel.	—	If the primary ICOM consumer is enabled
BACEN_ICOM_CONSUMER_ENABLED	Enable the primary inbound consumer.	false	No
BACEN_ICOM_SECONDARY_CONSUMER_ENABLED	Enable the secondary inbound consumer.	false	No
BACEN_ICOM_LONGPOLL_TIMEOUT_MS	Long-poll wait timeout (milliseconds).	90000	No

With BACEN_ICOM_CONSUMER_ENABLED=true, startup also requires a configured persistence backend, BACEN_SPI_INTERNAL_CALLBACK_SECRET, and BACEN_CALLBACK_MTLS_HEADER_SECRET. With BACEN_ICOM_SECONDARY_CONSUMER_ENABLED=true, it additionally requires BACEN_SPI_SECONDARY_ENDPOINT.

DICT client (BACEN_DICT_*)

Client for BACEN’s Pix key directory (DICT), including the anti-fraud (NP) endpoint.

Variable	Description	Default	Required
BACEN_DICT_ENDPOINT	DICT endpoint URL.	http://localhost:9900	Yes (live DICT)
BACEN_DICT_PARTICIPANT_ISPB	Participant ISPB for the DICT surface.	—	Yes (live DICT)
BACEN_DICT_ALLOWED_ENDPOINT_HOSTS	Allow-list of hosts the DICT client may reach.	—	No
BACEN_DICT_TIMEOUT_SEC	DICT request timeout (seconds).	10	No
BACEN_DICT_NP_ENDPOINT	Anti-fraud (NP) endpoint URL.	—	No
BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS	Allow-list for the NP endpoint.	—	No
BACEN_DICT_SIGNER_KIND	DICT signing custody backend: file, pkcs11, or kmip.	file	No
BACEN_DICT_SIGNING_CERT_FILE	Path to the DICT signing certificate.	—	For the selected DICT custody path
BACEN_DICT_SIGNING_KEY_FILE	Path to the DICT signing private key (file backend). Sensitive.	—	If file
BACEN_DICT_VERIFY_CERT_FILE	Certificate used to verify DICT responses.	—	No
BACEN_DICT_PKCS11_MODULE_PATH	PKCS#11 module path.	—	If pkcs11
BACEN_DICT_PKCS11_TOKEN_LABEL	PKCS#11 token label.	—	If pkcs11
BACEN_DICT_PKCS11_PIN_FILE	Path to the token PIN file. Sensitive.	—	If pkcs11
BACEN_DICT_PKCS11_KEY_LABEL	Signing-key label on the token.	—	If pkcs11
BACEN_DICT_KMIP_BASE_URL	KMIP service base URL.	—	If kmip
BACEN_DICT_KMIP_VHSM	Virtual HSM identifier.	—	If kmip
BACEN_DICT_KMIP_CRYPTO_USER	KMIP crypto user.	—	If kmip
BACEN_DICT_KMIP_CRYPTO_USER_TOKEN	KMIP crypto-user token. Sensitive.	—	If kmip
BACEN_DICT_KMIP_SIGN_PRIVATE_KEY_UID	UID of the signing private key.	—	If kmip
BACEN_DICT_KMIP_SIGN_PUBLIC_KEY_UID	UID of the signing public key.	—	If kmip
BACEN_DICT_KMIP_DIGEST_INFO_PREFIX	Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.	false	No
BACEN_DICT_INTENT_ENCRYPTION_KEY	AES-256 key for encrypting stored DICT claim intents. Sensitive.	—	In production

BR Code JOSE signing (BACEN_BRCODE_JOSE_*)

Signs dynamic BR Code payloads (JWS).

Variable	Description	Default	Required
BACEN_BRCODE_JOSE_SIGNER_KIND	JOSE signing custody backend: file, pkcs11, or kmip.	—	No
BACEN_BRCODE_JOSE_SIGNING_CERT_FILE	Path to the JOSE signing certificate.	—	If BR Code JOSE is enabled
BACEN_BRCODE_JOSE_SIGNING_KEY_FILE	Path to the JOSE signing private key (file backend). Sensitive.	—	If BR Code JOSE is enabled with file
BACEN_BRCODE_JOSE_KID	JWS key identifier (kid) header value.	—	If BR Code JOSE is enabled
BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH	PKCS#11 module path.	—	If BR Code JOSE is enabled with pkcs11
BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL	PKCS#11 token label.	—	If BR Code JOSE is enabled with pkcs11
BACEN_BRCODE_JOSE_PKCS11_PIN_FILE	Path to the token PIN file. Sensitive.	—	If BR Code JOSE is enabled with pkcs11
BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL	Signing-key label on the token.	—	If BR Code JOSE is enabled with pkcs11
BACEN_BRCODE_JOSE_KMIP_BASE_URL	KMIP service base URL.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_VHSM	Virtual HSM identifier.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER	KMIP crypto user.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN	KMIP crypto-user token. Sensitive.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID	UID of the signing private key.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID	UID of the signing public key.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX	Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.	false	No

PII encryption and hashing

Every variable below holds sensitive key or pepper material. It protects personal data at rest through encryption and blind indexing. Never commit or log a value. Inject it at deploy time through your secret manager. A pepper or key rotation requires a planned re-index or re-encryption.

Variable	Description	Default	Required
DICT_KEY_PII_ENCRYPTION_KEY	AES key for DICT key-holder PII. Sensitive.	—	Protected DICT runtime
DICT_KEY_BLIND_INDEX_PEPPER	Pepper for blind-indexing DICT key PII. Sensitive.	—	Protected DICT runtime
DICT_AUDIT_HASH_PEPPER	Pepper for DICT audit-record hashing. Sensitive.	—	Protected runtime
AUDIT_HASH_PEPPER	Legacy audit-hash pepper. Sensitive.	—	Protected runtime
SPI_RESPONSIBLES_ENCRYPTION_KEY	AES key for responsible-party PII. Sensitive.	—	Protected SPI runtime
SPI_OPERATIONS_PII_ENCRYPTION_KEY	AES-256 key for operation PII. Sensitive. The SPI service refuses to start if it is missing or malformed.	—	Yes — SPI service in every environment
SPI_OPERATIONS_BLIND_INDEX_PEPPER	Pepper for blind-indexing operation PII. Sensitive. Must contain at least 32 characters; the SPI service refuses to start if it is missing or shorter.	—	Yes — SPI service in every environment
BRCODE_PII_ENCRYPTION_KEY	AES key for BR Code PII. Sensitive.	—	Protected BR Code runtime
BRCODE_PII_BLIND_INDEX_PEPPER	Pepper for blind-indexing BR Code PII. Sensitive.	—	Protected BR Code runtime

PostgreSQL

Variable	Description	Default	Required
POSTGRES_HOST	Primary PostgreSQL host.	localhost	Yes
POSTGRES_PORT	Primary PostgreSQL port.	5432	No
POSTGRES_USER	Database user.	brspi	No
POSTGRES_PASSWORD	Database password. Sensitive. Use an explicit secret in production.	In-code development password	No
POSTGRES_DB	Database name.	brspi	No
POSTGRES_SSLMODE	libpq TLS mode. For remote production connections, use verify-full with a trusted CA; require encrypts the channel but does not verify the server identity.	disable	No
POSTGRES_MAX_OPEN_CONNS	Maximum open connections.	25	No
POSTGRES_MAX_IDLE_CONNS	Maximum idle connections.	5	No
POSTGRES_CONN_MAX_LIFETIME_MINS	Connection max lifetime (minutes).	30	No
POSTGRES_CONN_MAX_IDLE_TIME_MINS	Connection max idle time (minutes).	5	No
POSTGRES_CONNECT_TIMEOUT_SEC	Connection timeout (seconds).	10	No
POSTGRES_REPLICA_HOST	Optional read-replica host. Other replica fields fall back to the primary.	—	No
POSTGRES_REPLICA_PORT	Replica port.	—	No
POSTGRES_REPLICA_USER	Replica user.	—	No
POSTGRES_REPLICA_PASSWORD	Replica password. Sensitive.	—	No
POSTGRES_REPLICA_DB	Replica database name.	—	No
POSTGRES_REPLICA_SSLMODE	Replica TLS mode.	—	No

Redis

Variable	Description	Default	Required
REDIS_HOST	Redis host and port.	localhost:6379	No
REDIS_MASTER_NAME	Sentinel master name (if using Sentinel).	—	No
REDIS_PASSWORD	Redis password. Sensitive.	—	No
REDIS_DB	Redis database number.	0	No
REDIS_PROTOCOL	Redis protocol version (2 or 3).	3	No
REDIS_TLS	Enable TLS to Redis.	false	No
REDIS_CA_CERT	CA certificate for Redis TLS.	—	No
REDIS_POOL_SIZE	Connection pool size.	10	No
REDIS_MIN_IDLE_CONNS	Minimum idle connections.	2	No
REDIS_READ_TIMEOUT_MS	Read timeout (milliseconds).	3000	No
REDIS_WRITE_TIMEOUT_MS	Write timeout (milliseconds).	3000	No
REDIS_DIAL_TIMEOUT_MS	Dial timeout (milliseconds).	5000	No

Outbox and streaming

Lerian SPI publishes events through a transactional outbox and a lib-streaming producer, and consumes settlement events for BR Code. Streaming has no enable switch: STREAMING_BROKERS is required at startup, including when OUTBOX_ENABLED=false. Configure the shared STREAMING_CLOUDEVENTS_SOURCE, STREAMING_COMPRESSION, STREAMING_REQUIRED_ACKS, and STREAMING_EVENT_POLICIES settings as described in Streaming and outbox.

Variable	Description	Default	Required
OUTBOX_ENABLED	Enable the transactional outbox dispatcher.	true	No
OUTBOX_DISPATCH_INTERVAL_MS	Interval between dispatch cycles (milliseconds).	2000	No
OUTBOX_BATCH_SIZE	Rows drained per dispatch cycle.	50	No
OUTBOX_MAX_DISPATCH_ATTEMPTS	Dispatch attempts before an event is parked.	10	No
OUTBOX_PROCESSING_TIMEOUT_MS	Per-batch processing timeout (milliseconds).	600000	No
OUTBOX_RETRY_WINDOW_MS	Retry window before a stuck row is reclaimed (milliseconds).	300000	No
BRCODE_SETTLEMENT_CONSUMER_ENABLED	Enable the BR Code settlement consumer. Requires STREAMING_BROKERS.	false	No
BRCODE_SETTLEMENT_CONSUMER_TOPIC	Topic the BR Code settlement consumer reads.	br-spi.spi.payment	No
BRCODE_SETTLEMENT_CONSUMER_GROUP	Consumer group for BR Code settlement.	br-spi-brcode-settlement-consumer	No
BRCODE_SETTLEMENT_CONSUMER_CLIENT_ID	Client ID presented to the broker by the settlement consumer.	—	No
SPI_PARTICIPANT_CONSUMER_ENABLED	Enable the Core-to-SPI participant-request consumer. It requires STREAMING_BROKERS, BACEN transport, and persistence when enabled.	false	No
SPI_PARTICIPANT_CONSUMER_TOPIC	Topic carrying Core participant requests.	br-spi.core.participant	No
SPI_PARTICIPANT_CONSUMER_GROUP	Durable consumer group for participant requests.	br-spi-participant-request-consumer	No
SPI_PARTICIPANT_CONSUMER_CLIENT_ID	Client ID presented to the broker by the participant-request consumer. Falls back to the shared streaming client ID.	Shared client ID	No

Schedulers

Background jobs, each independently gated. All default off.

Variable	Description	Default	Required
SCHEDULER_ENABLED	Master switch for the scheduler subsystem.	false	No
SCHEDULER_MED_DEADLINE_ENABLED	Run the MED (special return) deadline job.	false	No
SCHEDULER_QUOTA_RESET_ENABLED	Run the outbound-quota reset job.	false	No
SCHEDULER_CLAIM_DEADLINE_ENABLED	Run the DICT claim-deadline job.	false	No
SCHEDULER_DICT_RECONCILIATION_INCREMENTAL_ENABLED	Run incremental DICT reconciliation.	false	No
SCHEDULER_DICT_RECONCILIATION_FULL_ENABLED	Run full DICT reconciliation.	false	No
SCHEDULER_DICT_AUDIT_RETENTION_ENABLED	Run the DICT audit-retention job.	false	No
SCHEDULER_INBOUND_DISCOVERY_ENABLED	Run the inbound-message discovery job.	false	No
SCHEDULER_APPROVAL_EXPIRY_ENABLED	Run the approval-expiry sweep.	false	No
SCHEDULER_PORTABILITY_DEADLINE_ENABLED	Run the portability-deadline job.	false	No

Rate limiting, idempotency, and connectivity

Variable	Description	Default	Required
RATE_LIMIT_ENABLED	Enable request rate limiting.	true	No
RATE_LIMIT_MAX	Maximum requests per window.	100	No
RATE_LIMIT_EXPIRY_SEC	Rate-limit window (seconds).	60	No
IDEMPOTENCY_RETRY_WINDOW_SEC	How long (seconds) an idempotency key is retained.	86400	No
IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY	AES-256 key for encrypting stored idempotency responses. Sensitive.	—	Protected SPI, DICT, or Core runtime
INFRA_CONNECT_TIMEOUT_SEC	Connect timeout for infrastructure dependencies at startup (seconds).	30	No

Systemplane and runtime configuration

Variable	Description	Default	Required
SYSTEMPLANE_ENABLED	Enable the systemplane runtime-configuration admin API, mounted at /v1/system on the main port. When false, the service runs in env-only mode with no admin plane. SPI defaults this on — unlike most Lerian services, where systemplane is off by default.	true	No

See Systemplane for the API, namespaces, and required permissions.

Observability

Variable	Description	Default	Required
ENABLE_TELEMETRY	Enable OpenTelemetry tracing and metrics.	false	No
TELEMETRY_REQUIRED	Fail startup if telemetry cannot initialize.	false	No
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP collector endpoint.	localhost:4317	If telemetry enabled
OTEL_RESOURCE_SERVICE_NAME	Service name attached to exported telemetry.	Service default	No
OTEL_RESOURCE_SERVICE_VERSION	Service version label.	1.0.0	No
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT	Deployment environment label.	development	No
OTEL_LIBRARY_NAME	Instrumentation library name.	Service default	No
METRICS_PROMETHEUS_ENABLED	Expose a dedicated Prometheus scrape endpoint.	false	No
METRICS_PROMETHEUS_ADDRESS	Listen address for the Prometheus endpoint. Binds loopback by default.	127.0.0.1:9090	No

Documentation

Variable	Description	Default	Required
SWAGGER_ENABLED	Serve the OpenAPI spec and API docs UI. Forced off in production.	false	No

Health and readiness

Lerian SPI exposes GET /health (liveness), GET /readyz (readiness), and GET /version on the main HTTP port. /metrics runs on its own listener when enabled. See Health and readiness for the probe contract.