Environment variables

Set these variables at deployment time. Unless stated otherwise, changing one requires a restart. The BYOC configuration reference covers the shared Lerian runtime: server, datastores, multi-tenancy, telemetry, authentication, streaming, outbox, and licensing. This page lists Consignado-specific settings and the few shared settings that materially change its rail behavior. — means no default. Variables carrying certificates, private keys, OAuth secrets, or HMAC keys are sensitive and must come from a secret manager. A deployment is managed when DEPLOYMENT_MODE is byoc or saas, when ENV_NAME is production, or when MULTI_TENANT_ENABLED is true.

Service and tenant mode

Variable	Default	Purpose
`SERVER_ADDRESS`	`:8080`	Main HTTP listener for the API and probes.
`DEPLOYMENT_MODE`	`local`	`local`, `byoc`, or `saas`. Startup refuses any other value. `byoc` and `saas` make the deployment managed.
`ENV_NAME`	`development`	Environment label. `production` makes the deployment managed.
`ENVIRONMENT_NAME`	—	Multi-tenant event-listener environment; falls back to `ENV_NAME`.
`SYSTEMPLANE_ENABLED`	`false`	Enables runtime configuration under `/system`.
`MULTI_TENANT_ENABLED`	`false`	Enables multi-tenant mode. `true` makes the deployment managed.
`DEFAULT_TENANT_ID`	`default`	Tenant used in single-tenant mode.
`OUTBOX_ENABLED`	`true`	Must be `true`; startup refuses a deployment that cannot durably record rail facts.
`STREAMING_ENABLED`	`true`	Must be `true`; the streaming relay is the only publisher for outbox facts.
`STREAMING_BROKERS`	—	Required broker list. Startup refuses a relay with no destination.
`STREAMING_CLOUDEVENTS_SOURCE`	—	Must be exactly `consignado-gw`. Startup refuses any other value; a wrong source means no fact ever reaches a consumer.
`STREAMING_KAFKA_TLS_ENABLED`	`false`	Connects to the brokers over TLS. Startup requires `true` unless `STREAMING_KAFKA_ALLOW_PLAINTEXT` is `true`.
`STREAMING_KAFKA_ALLOW_PLAINTEXT`	`false`	Permits a plaintext broker connection when `ENV_NAME` is `development`, `local`, or `test`. A managed deployment refuses it.
`STREAMING_KAFKA_SASL_MECHANISM`	—	`plain`, `scram-sha-256`, or `scram-sha-512`. A managed deployment requires one of the two SCRAM values.
`STREAMING_KAFKA_SASL_USERNAME_FILE`	—	Path to the file that holds the broker user name. Required with a SASL mechanism and in a managed deployment.
`STREAMING_KAFKA_SASL_PASSWORD_FILE`	—	Path to the file that holds the broker password. Required with a SASL mechanism and in a managed deployment. Sensitive.
`SUBSCRIPTIONS_HUB_ENABLED`	`false`	A managed deployment requires `true` and refuses to start without it.
`SUBSCRIPTIONS_HUB_BASE_URL`	—	Streaming Hub base URL. A managed deployment refuses to start without it.

Dataprev client and authentication

Variable	Default	Purpose
`DATAPREV_ENABLED`	`false`	Master switch for the Dataprev rail runtime.
`DATAPREV_BASE_URL`	—	Base URL for the main Dataprev API. HTTPS is required in managed deployments; a non-managed deployment permits HTTP only for loopback hosts.
`DATAPREV_TOMBAMENTO_BASE_URL`	—	Separate endpoint for tombamento operations. Empty keeps those operations unavailable. It follows the same HTTPS/loopback policy.
`DATAPREV_OAUTH_TOKEN_URL`	—	OAuth2 token endpoint. HTTPS is required in managed deployments; a non-managed deployment permits HTTP only for loopback hosts.
`DATAPREV_OAUTH_CLIENT_ID`	—	Single-tenant OAuth client ID fallback. Sensitive.
`DATAPREV_OAUTH_CLIENT_SECRET`	—	Single-tenant OAuth client secret fallback. Sensitive.
`DATAPREV_OAUTH_SCOPES`	—	Comma-separated OAuth scopes requested from Dataprev.
`DATAPREV_CERT_FILE`	—	Local ICP-Brasil certificate path for non-managed single-tenant development. Sensitive.
`DATAPREV_KEY_FILE`	—	Local private-key path paired with `DATAPREV_CERT_FILE`. Sensitive.
`DATAPREV_CODIGO_SOLICITANTE`	—	Three-digit requester-code fallback for single-tenant mode.
`DATAPREV_REQUEST_TIMEOUT_SEC`	`30`	Timeout for one Dataprev request.
`DATAPREV_REQUESTS_PER_SECOND`	`25`	Rail rate, from 0 to 25, for requests that carry no tenant identity. With the Systemplane enabled, the stored value applies instead.
`DATAPREV_CONSENT_CACHE_HMAC_KEY`	—	HMAC key for worker-consent records and cache entries. Worker margin and FGTS reads refuse without it, and startup refuses a Redis deployment without it. Sensitive.

Managed deployments must use tenant credential custody. They fail closed instead of falling back to an unauthenticated or non-mTLS client.

Contract and portability windows

Variable	Default	Purpose
`DATAPREV_AVERBACAO_ENABLED`	`false`	Enables averbação, CCB and rail artifact storage, and contract corrections.
`DATAPREV_PORTABILIDADE_SOLICITACAO_WINDOW_HOURS`	`72`	Lookback window for portability proposals.
`DATAPREV_PORTABILIDADE_INCLUSAO_GARANTIAS_PATH`	—	Override for the Dataprev portability-guarantee submission path.
`DATAPREV_PORTABILIDADE_AVERBACAO_WINDOW_DAYS`	`20`	Calendar days from the origin exclusion date a request names to register an inbound portability.
`DATAPREV_REFINANCIAMENTO_REVERSAO_WINDOW_BUSINESS_DAYS`	`7`	Business-day window for refinancing reversal.
`DATAPREV_SALDO_DEVEDOR_CLOCK_INTERVAL_SEC`	`86400`	Cadence for outstanding-balance obligations and month-end fallback.
`DATAPREV_SALDO_DEVEDOR_REENVIO_INTERVAL_SEC`	`60`	Cadence of the resend of outstanding-balance reports that a competência turnover held back.

Reconciliation and employment feeds

Variable	Default	Purpose
`DATAPREV_RECONCILIATION_ENABLED`	`false`	Enables payroll bookkeeping and repasse reconciliation.
`DATAPREV_RECONCILIATION_INTERVAL_SEC`	`3600`	Reconciliation cadence.
`DATAPREV_RECONCILIATION_LOOKBACK_MONTHS`	`1`	Previous payroll competences included in each pass.
`DATAPREV_RECONCILIATION_CNPJS`	—	Comma-separated employer scopes; empty reads the rail-wide feed.
`DATAPREV_RECONCILIATION_TENANT_ID`	—	Tenant the reconciliation poller runs for. In single-tenant mode, the employment feed and exclusion recovery also require it.
`DATAPREV_EMPLOYMENT_REPORT_ENABLED`	`false`	Enables the employment-termination feed.
`DATAPREV_EMPLOYMENT_REPORT_ADAPTER`	`disabled`	`dataprev` for the real adapter; `fake` is local-only.
`DATAPREV_EMPLOYMENT_REPORT_INTERVAL_SEC`	`3600`	Employment-report cadence.
`DATAPREV_EMPLOYMENT_REPORT_PAGE_SIZE`	`100`	Records requested per page.
`DATAPREV_EMPLOYMENT_REPORT_CONCURRENCY`	`4`	Concurrent tenant workers.
`DATAPREV_EMPLOYMENT_REPORT_TENANT_TIMEOUT_SEC`	`300`	Maximum processing time for one tenant in a pass.

Exclusion and redirection

Variable	Default	Purpose
`DATAPREV_EXCLUSION_ENABLED`	`false`	Enables exclusion admission and recovery.
`DATAPREV_EXCLUSION_PROVIDER_TIMEOUT_SEC`	`30`	Timeout for one exclusion provider call.
`DATAPREV_EXCLUSION_CLAIM_DWELL_SEC`	`60`	Minimum dwell before claimed work can be retried.
`DATAPREV_EXCLUSION_STATUS_CHECK_LEASE_SEC`	`60`	Lease for exclusion status checks.
`DATAPREV_EXCLUSION_RECOVERY_INTERVAL_SEC`	`30`	Recovery-loop cadence.
`DATAPREV_EXCLUSION_RECOVERY_BATCH`	`50`	Operations claimed per pass.
`DATAPREV_EXCLUSION_RECOVERY_CONCURRENCY`	`4`	Concurrent recovery workers.
`DATAPREV_EXCLUSION_RECOVERY_TENANT_TIMEOUT_SEC`	`60`	Maximum processing time for one tenant in a pass.

Leave DATAPREV_EXCLUSION_ADAPTER and DATAPREV_EXCLUSION_FAKE_BASE_URL unset.

Outcome recovery

A rail command can end with its outcome unestablished: the process died mid-call, or Dataprev never answered. Two recovery loops converge that state against the rail’s own registry. A third loop resends a bid whose rail answer was lost. The three loops are off by default. Enable them in any deployment that submits averbações, rail commands, or bids. Otherwise nothing converges an unestablished outcome automatically.

Variable	Default	Purpose
`DATAPREV_AVERBACAO_RECOVERY_ENABLED`	`false`	Enables averbação outcome convergence.
`DATAPREV_AVERBACAO_RECOVERY_INTERVAL_SEC`	`60`	Convergence cadence.
`DATAPREV_AVERBACAO_RECOVERY_BATCH`	`50`	Records claimed per pass.
`DATAPREV_AVERBACAO_RECOVERY_CONCURRENCY`	`4`	Concurrent tenant workers.
`DATAPREV_AVERBACAO_RECOVERY_TENANT_TIMEOUT_SEC`	`60`	Maximum processing time for one tenant in a pass.
`DATAPREV_AVERBACAO_RECOVERY_MINIMUM_DWELL_SEC`	`300`	Minimum age before an unestablished outcome is reconciled.
`DATAPREV_AVERBACAO_RECOVERY_PROVIDER_TIMEOUT_SEC`	`30`	Timeout for one registry read.
`DATAPREV_RAIL_COMMAND_RECOVERY_ENABLED`	`false`	Enables convergence for refinancing, reversal, renegotiation, and origin-side portability exclusion.
`DATAPREV_RAIL_COMMAND_RECOVERY_INTERVAL_SEC`	`60`	Convergence cadence.
`DATAPREV_RAIL_COMMAND_RECOVERY_BATCH`	`50`	Records claimed per pass.
`DATAPREV_RAIL_COMMAND_RECOVERY_CONCURRENCY`	`4`	Concurrent tenant workers.
`DATAPREV_RAIL_COMMAND_RECOVERY_TENANT_TIMEOUT_SEC`	`60`	Maximum processing time for one tenant in a pass.
`DATAPREV_RAIL_COMMAND_RECOVERY_MINIMUM_DWELL_SEC`	`300`	Minimum age before an unestablished outcome is reconciled.
`DATAPREV_RAIL_COMMAND_RECOVERY_PROVIDER_TIMEOUT_SEC`	`30`	Timeout for one registry read.
`CONSIGNADO_BID_RECONDUCTION_ENABLED`	`false`	Enables the resend of bids whose rail answer was lost, under the original proposal number.
`CONSIGNADO_BID_RECONDUCTION_INTERVAL_SEC`	`15`	Resend cadence.
`CONSIGNADO_BID_RECONDUCTION_BATCH_SIZE`	`20`	Bids resent per tenant in one pass.

Auctions and client bids

Variable	Default	Purpose
`LEILAO_ENABLED`	`false`	Enables scheduled discovery of open loan requests.
`LEILAO_CLIENT_BID_ENABLED`	`false`	Enables the authenticated client bid command surface.
`LEILAO_INTERVAL_SEC`	`3600`	Auction-discovery cadence.
`LEILAO_TENANT_ID`	—	Tenant that auction discovery and portability discovery run for. Both require it.
`LEILAO_PORTAL_BASE_URL`	—	Optional single-tenant worker portal base URL fallback. Leaving it unset is a valid deployment: bids then travel with the client’s own contacts. A value that is set is validated at boot and an unsafe one fails the boot closed.
`LEILAO_DISCOVERY_LOOKBACK_HOURS`	`48`	Width of each discovery window. It must be wider than `LEILAO_INTERVAL_SEC` plus `LEILAO_DISCOVERY_CLOCK_SKEW_SEC`, or startup fails.
`LEILAO_DISCOVERY_CLOCK_SKEW_SEC`	`300`	Clock-skew overlap applied to discovery windows.
`LEILAO_FAST_LANE_ENABLED`	`false`	Enables a second discovery pass over the last 60 seconds of open requests, once per second by default. It starts only with `LEILAO_ENABLED=true`.
`LEILAO_PORTABILITY_ENABLED`	`false`	Enables portability discovery. This is independent from `LEILAO_ENABLED`.
`LEILAO_PORTABILITY_INTERVAL_SEC`	`3600`	Cadence of the portability-discovery pass.

Portability discovery requires LEILAO_PORTABILITY_ENABLED=true, LEILAO_TENANT_ID, DATAPREV_ENABLED=true, STREAMING_ENABLED=true, a primary database, and the canonical outbox. It does not require LEILAO_ENABLED=true. The portability listing window is 72 hours by default (DATAPREV_PORTABILIDADE_SOLICITACAO_WINDOW_HOURS). The service refuses to boot unless that window is wider than LEILAO_PORTABILITY_INTERVAL_SEC plus the 300-second LEILAO_DISCOVERY_CLOCK_SKEW_SEC margin.

Credential custody and artifacts

Variable	Default	Purpose
`CREDENTIALS_STORE_ENABLED`	`false`	Enables per-tenant Dataprev credential custody. A managed deployment requires it.
`CREDENTIALS_CLEANUP_INTERVAL_SEC`	`30`	Credential-cleanup cadence.
`CREDENTIALS_CLEANUP_BATCH_SIZE`	`50`	Credentials claimed per cleanup pass.
`CREDENTIALS_CLEANUP_CONCURRENCY`	`4`	Concurrent cleanup workers.
`CREDENTIALS_CLEANUP_LEASE_SEC`	`60`	Cleanup lease.
`CREDENTIALS_CLEANUP_PERSISTENCE_TIMEOUT_SEC`	`5`	Persistence timeout for one cleanup operation.
`AVERBACAO_ARTIFACTS_BUCKET`	—	Private object-store bucket for CCB and rail artifacts. Required when `DATAPREV_AVERBACAO_ENABLED=true`.
`AVERBACAO_ARTIFACTS_ENDPOINT_URL`	—	S3-compatible endpoint override for local or private object stores.
`AVERBACAO_ARTIFACTS_USE_PATH_STYLE`	`false`	Uses path-style S3 addressing when enabled.
`AWS_REGION`	—	Region used by credential custody and artifact storage. Deliberately has no default: an unset value lets the AWS SDK resolve the institution’s own region, and a hardcoded one would override it. Set it explicitly for the region your data must stay in.
`AWS_ENDPOINT_URL`	—	AWS-compatible endpoint override for local development. Do not set it in managed AWS production.

Consignado has no non-event-driven startup mode: outbox, streaming, and brokers are mandatory even though the platform shares those settings. Keep the CloudEvent source pinned to consignado-gw.

​Service and tenant mode

​Dataprev client and authentication

​Contract and portability windows

​Reconciliation and employment feeds

​Exclusion and redirection

​Outcome recovery

​Auctions and client bids

​Credential custody and artifacts

Service and tenant mode

Dataprev client and authentication

Contract and portability windows

Reconciliation and employment feeds

Exclusion and redirection

Outcome recovery

Auctions and client bids

Credential custody and artifacts