Environment variables

Environment variables for deploying and operating Pix Lerian: identity, persistence, integrations, connectivity, and events.

Pix Lerian components include the SPI, DICT Hub, COB Hub, Pix Automático API, their workers, and the connectivity adapter. This page lists the deployment inputs Pix Lerian reads. Use the tables to see which values components share and which belong to one component.

To install or upgrade Pix Lerian, see the Pix Lerian chart README.

Values shown here are placeholders. Inject credentials and license material from your secret store. Never commit real secrets.

Configuration model

Each component loads bootstrap values from its environment. The SPI, DICT Hub, COB Hub, Pix Automático API, and DICT VSync worker also consume runtime configuration from their Systemplane store after initialization. The mock provider adapter reads its configuration from the environment only and keeps its state in memory.

Configure each component separately. Their ports, stores, and required dependencies differ.

Shared identity and deployment

Variable	Components	Contract
APPLICATION_NAME	All	Component identity used in logs, telemetry, and licensing. Keep the value supplied by the release configuration.
SERVER_ADDRESS	All HTTP components	Listen address in host:port format. The port must match the component service and probe configuration.
DEPLOYMENT_MODE	API components and workers	local, saas, or byoc. The default is local when the value is absent.
REQUEST_TIMEOUT_SEC	HTTP components	Per-request timeout in seconds. The default is 30.
LICENSE_KEY	Licensed components	Optional in local; required in non-local deployment modes. Inject it as a secret.
ORGANIZATION_IDS	Licensed components	License scope, such as global or a comma-separated organization list.
SWAGGER_ENABLED	API components	Strict boolean. When unset, the runtime OpenAPI and Scalar surface is enabled outside production and disabled in production.

PLUGIN_AUTH_ENABLED controls inbound route authentication. PLUGIN_AUTH_HOST is the Access Manager base address used by the shared auth integration and OAuth client-credentials flows. It must be a base address only, without an OAuth path, query, fragment, or embedded credentials. Use https:// outside local development.

The mock provider adapter requires SPI_BASE_URL, PROVIDER_CLIENT_ID, and PROVIDER_CLIENT_SECRET at boot. MOCK_TEST_ENDPOINTS_ENABLED=true turns on test routes that can forge provider callbacks. The mock adapter has no route authorization: keep it unreachable from untrusted callers, whatever this switch says. Do not configure the mock adapter as a production rail.

Persistence and Valkey

Variable	Components	Contract
DATABASE_URL	SPI, DICT Hub, COB Hub, Pix Automático API, and VSync	PostgreSQL DSN for the component’s business store. It is required where that component persists business data.
DATABASE_READ_REPLICA	SPI, DICT Hub, COB Hub, and Pix Automático API	Optional PostgreSQL DSN for a read replica. Only list routes read from it, so a recent write can be missing from a list for a moment. The component does not start when the replica is unreachable. Multi-tenant mode ignores it.
SYSTEMPLANE_POSTGRES_DSN	Systemplane consumers	PostgreSQL DSN for the runtime configuration store. It falls back to DATABASE_URL in the SPI, DICT Hub, COB Hub, and Pix Automático API when unset.
REDIS_HOST, REDIS_PORT, REDIS_USER, REDIS_PASSWORD, REDIS_DB	API components and VSync	Structured Valkey connection settings. Do not replace them with the retired VALKEY_URL variable.
REDIS_TLS, REDIS_PROTOCOL, REDIS_CA_CERT	API components and VSync	Valkey transport security. A private or self-signed certificate requires REDIS_CA_CERT; there is no skip-verification switch.
KEY_CACHE_TTL_SEC	DICT Hub	Pix-key cache TTL in seconds. The default is 60.

Valkey behavior differs by component. SPI, DICT Hub, and COB Hub can degrade selected idempotency or cache paths when you do not configure Valkey. Some SPI, DICT, and COB mutations fail closed with PIX-0032 when no durable replay backstop exists. DICT VSync treats Valkey as a hard dependency because it coordinates the cross-pod mutation gate. A configured but malformed REDIS_* value fails boot rather than silently selecting a different endpoint.

The Systemplane implementation does not use SYSTEMPLANE_SECRET_MASTER_KEY. Protect Systemplane database access, backups, and disk storage through the deployment environment.

Institution and service integrations

Variable	Components	Contract
ORGANIZATION_ID	SPI, DICT Hub, COB Hub	Midaz organization the components use.
ISPB	SPI, DICT Hub, COB Hub	Participant identifier. The API validates the participant header or resolves the value from tenant configuration.
ADAPTER_BASE_URL	SPI, DICT Hub, COB Hub, VSync	Connectivity adapter base URL, route prefix included. Point it at the Lerian connectivity adapter, or at the mock provider adapter for integration tests.
ADAPTER_CLIENT_ID, ADAPTER_CLIENT_SECRET	SPI, DICT Hub, COB Hub, VSync	Optional client credentials for calls to the connectivity adapter. When both are empty, these calls carry no Authorization header.
MIDAZ_BASE_URL	SPI	Midaz base URL for onboarding and transaction operations.
MIDAZ_LEDGER_ID	SPI	Ledger identifier used for accounting operations.
MIDAZ_CLIENT_ID, MIDAZ_CLIENT_SECRET	SPI	OAuth client credentials for Midaz calls.
CRM_BASE_URL, CRM_CLIENT_ID, CRM_CLIENT_SECRET	SPI, DICT Hub, VSync	CRM integration used by flows that validate accounts, holders, or orphaned entries.
DICT_BASE_URL, DICT_CLIENT_ID, DICT_CLIENT_SECRET	SPI and COB Hub	DICT Hub or proxy address and credentials. DICT_ROUTING_MODE selects hub or proxy; keep the URL consistent with that choice.
COB_BASE_URL, COB_CLIENT_ID, COB_CLIENT_SECRET	SPI	COB Hub or proxy address and credentials. COB_ROUTING_MODE selects hub or proxy; keep the URL consistent with that choice.
SPI_BASE_URL, SPI_CLIENT_ID, SPI_CLIENT_SECRET	DICT Hub	SPI address and credentials used for transfer lookups and MED 2.0 balance-lock operations.
ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK	SPI	true lets the fraud check call an http address or an address on a private network. Use it only in a test environment. The default is false.

Lerian connectivity adapter

The Lerian connectivity adapter connects Pix Lerian to Lerian SPI. It runs as two components: the adapter API and its configuration writer. The adapter API serves its routes under the /lerian prefix.

The configuration writer copies its variables into the adapter’s runtime configuration store at startup. It does not overwrite a stored value that differs from the default. The adapter API reads its routing and credentials from that store.

In multi-tenant mode, the writer copies nothing. Write the values of each tenant through the writer’s admin API. These are the four callback addresses and their client credential pairs, DICT_CID_FILE_BASE_URL, and the three BRSFN_*_BASE_URL addresses. PLUGIN_AUTH_HOST, the BRSFN_SPI_CLIENT_*, BRSFN_DICT_CLIENT_*, and BRSFN_COB_CLIENT_* pairs, and the signing secrets of the event routes are not tenant values. The adapter API reads them for all tenants from the store at SYSTEMPLANE_POSTGRES_DSN.

Variable	Component	Contract
SYSTEMPLANE_POSTGRES_DSN	Adapter API	PostgreSQL DSN of the runtime configuration store. The adapter API does not start without it.
DATABASE_URL	Configuration writer	PostgreSQL DSN that the writer stores the values in. SYSTEMPLANE_POSTGRES_DSN replaces it when set. The writer does not start without one of them.
BRSFN_SPI_BASE_URL, BRSFN_DICT_BASE_URL, BRSFN_BRCODE_BASE_URL	Configuration writer	Addresses of the Lerian SPI spi, dict, and brcode surfaces: scheme, host, and port only. A surface with no address refuses its calls. No surface uses the address of another.
BRSFN_SPI_CLIENT_ID, BRSFN_SPI_CLIENT_SECRET	Configuration writer	OAuth client credentials for the spi surface.
BRSFN_DICT_CLIENT_ID, BRSFN_DICT_CLIENT_SECRET	Configuration writer	OAuth client credentials for the dict surface.
BRSFN_COB_CLIENT_ID, BRSFN_COB_CLIENT_SECRET	Configuration writer	OAuth client credentials for the brcode surface.
PLUGIN_AUTH_HOST	Configuration writer	Access Manager address. The adapter gets the token for each client credential pair from it.
SPI_BASE_URL	Configuration writer	Full SPI address, /spi path included, for payment callbacks. Without it, the adapter routes no request.
DICT_BASE_URL, COB_BASE_URL, PIXAUTO_BASE_URL	Configuration writer	Full DICT Hub, COB Hub, and Pix Automático API addresses for their callbacks. Include the /pixauto path in PIXAUTO_BASE_URL. When one is unset, only its callbacks fail.
SPI_CLIENT_ID, SPI_CLIENT_SECRET, DICT_CLIENT_ID, DICT_CLIENT_SECRET, COB_CLIENT_ID, COB_CLIENT_SECRET, PIXAUTO_CLIENT_ID, PIXAUTO_CLIENT_SECRET	Configuration writer	Client credentials, one pair for the callbacks to each component. When the SPI, COB, or Pix Automático pair is incomplete, the adapter sends the callbacks to that component without a token. Without the complete DICT pair, the adapter refuses each event it must forward to the DICT Hub.
DICT_CID_FILE_BASE_URL	Configuration writer	Address of the adapter API, /lerian prefix included, as the DICT Hub reaches it. Without it, the adapter refuses each DICT VSync file event.
WEBHOOK_INGRESS_ENABLED	Adapter API	Turns on the routes that receive Lerian SPI events, such as cash-in and settlement results. The default is false. When it is true, the adapter API does not start without REDIS_HOST.
MULTI_TENANT_URL, MULTI_TENANT_SERVICE_API_KEY	Both	Required when MULTI_TENANT_ENABLED=true.
AWS_REGION	Adapter API	Required when multi-tenant mode and the event routes are both on. The adapter finds the tenant of each event from its participant ISPB in AWS Secrets Manager, under ISPB_SECRET_PREFIX (default pix/ispb/).

When a Lerian SPI surface has no complete credential pair or no PLUGIN_AUTH_HOST, the adapter does not call that surface. Each event route checks each delivery against the signing secret of its event subscription. The adapter reads these secrets from its runtime configuration, not from the environment. In single-tenant mode, when a subscription has a new signing secret, write that secret to the runtime configuration through the configuration writer’s admin API. A route with no secret refuses every delivery.

DICT VSync

The DICT VSync worker reconciles DICT state and requires its own worker configuration:

Variable	Default	Contract
VSYNC_ENABLED	true	Enables the worker scheduler.
VSYNC_FILE_RECON_ENABLED	true	Enables file-based reconciliation.
VSYNC_CHUNK_PROCESSING_DEADLINE_MIN	30	Chunk processing deadline in minutes.
VSYNC_MAX_JOB_ATTEMPTS	3	Maximum attempts for a reconciliation job.
VSYNC_EVENTSYNC_MAX_PAGES	100	Maximum pages in event synchronization.
VSYNC_GATE_TTL_SEC	3600	Mutation-gate lease TTL in seconds.
VSYNC_STUCK_JOB_SWEEP_TICK_SEC	120	Interval between stuck-job scans in seconds.
RABBITMQ_URI	—	RabbitMQ URI for the file-reconciliation queue. Use amqps:// outside local development.
RABBITMQ_ENABLED	component-dependent	Enables the DICT Hub jobs publisher. The VSync worker itself requires its queue configuration.

VSYNC_ENABLED and VSYNC_FILE_RECON_ENABLED can be hot-reloaded through the worker’s runtime configuration. The remaining tuning values are read at boot and require a restart.

Pix Automático API

The Pix Automático API sends settlement commands to the SPI and reads these variables:

Variable	Contract
ORGANIZATION_ID	Organization that the component acts for in single-tenant mode. The component reads its runtime configuration first and uses this value only when that configuration has none. When MULTI_TENANT_ENABLED=true, the component refuses to start if this value is set.
SPI_BASE_URL	SPI address for Pix Automático settlement. Include the SPI /spi path segment. A malformed value stops the component at startup.
SPI_CLIENT_ID, SPI_CLIENT_SECRET	Client credentials for the settlement call. In multi-tenant mode, the component resolves the credentials per tenant and does not use these values.
REGULATORY_DISPATCH_ENABLED	Turns on the dispatcher that sends regulatory intents to the provider adapter. The default is false.
ADAPTER_BASE_URL	Provider adapter address that the dispatcher posts to. The component reads REGULATORY_DISPATCH_BASE_URL only when this value is empty. When dispatch is on and no address is set, the component refuses to start.
ADAPTER_CLIENT_ID, ADAPTER_CLIENT_SECRET	Client credentials for the dispatcher. When dispatch is on, the component refuses to start if only one of them is set. It also refuses to start if both are empty and ENV_NAME is not local or development.
CRM_BASE_URL, CRM_CLIENT_ID, CRM_CLIENT_SECRET	CRM address and credentials used to resolve the payer account on the QR code journeys and on journey 1 requests that do not name the account. When CRM_BASE_URL is unset, every resolution answers 503 (PIX-0814).

Streaming and observability

The notification-outbox relay is disabled by default. To enable it, set STREAMING_ENABLED=true and provide STREAMING_BROKERS. The shared CloudEvents source, when configured, must identify the Pix Lerian service. The component also validates the streaming broker’s TLS/SASL settings and the optional STREAMING_DATASCHEMA_BASE_URL.

Set ENABLE_TELEMETRY=true to turn on OpenTelemetry. The OTEL_* variables configure it. See BYOC configuration for shared telemetry and broker transport parameters.

Health and readiness

Probe paths and route prefixes belong to the component deployment configuration. Do not assume that every component exposes unprefixed /health or /readyz. Use the paths in the release chart and component bootstrap configuration.