> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment variables
> Deploy-time environment variables distinctive to Lerian SLC — Núclea/RSFN transport, the SFN inbound bus, the signing sidecar, and the settlement schedule.
Lerian SLC is the Lerian-owned settlement rail that clears and settles over Núclea's SLC across the RSFN. These variables are set at deploy time and require a service restart to take effect. The universal backbone that every Lerian Go service shares — server, datastores, multi-tenancy, telemetry, plugin authentication, and licensing — is documented once in [BYOC configuration essentials](/en/reference/byoc-configuration); this page covers only the variables distinctive to Lerian SLC.
In the tables below, the **Default / Required** column shows the default value; a bold qualifier (e.g. **Required**, **Required in production**) marks variables that must be set. `—` means no default. Any variable flagged **Sensitive** carries credential or key material — inject it from your secret manager at deploy time and never commit a value.
## Service and runtime
| Variable | Default / Required | Description |
| ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SERVER_ADDRESS` | `:4111` | Main HTTP listen address. The liveness, readiness, metrics, and version probes bind this same port. |
| `SYSTEMPLANE_ENABLED` | `false` | Enable the [Systemplane](/en/reference/systemplane/overview) runtime-configuration admin API under the `/system` prefix on the main port. Off by default (environment-variable-only mode). |
| `TENANT_RUNTIME_CONFIG_ENABLED` | `false` | Enable the per-tenant runtime-config store and admin surface, resolving each tenant's connectivity transport from a per-tenant record rather than the shared configuration. Selection and policy only. |
Lerian SLC exposes `/health` (liveness) and `/readyz` (readiness) on the main port, plus `/version` and `/metrics`, and — when multi-tenancy is enabled — `GET /readyz/tenant/{id}`. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.
## Núclea REST transport
The online submission channel to Núclea over mutual TLS. Leave `NUCLEA_REST_BASE_URL` empty to keep the transport unwired.
| Variable | Default / Required | Description |
| ------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NUCLEA_REST_BASE_URL` | — | Base URL of the Núclea node. Empty disables the online submitter. In production this points at the Núclea endpoint; locally it points at a simulator. |
| `NUCLEA_REST_TIMEOUT_SEC` | `30` | Per-request timeout in seconds. |
| `NUCLEA_REST_CB_CONSECUTIVE_FAILURES` | `5` | Consecutive failures that trip the circuit breaker open. |
| `NUCLEA_REST_CB_OPEN_TIMEOUT_SEC` | `30` | How long the breaker stays open before half-open. |
| `NUCLEA_REST_ALLOW_INSECURE_TLS` | `false` | Relax Núclea TLS verification for local development only. Boot is rejected when this is `true` under `ENV_NAME=production` or `DEPLOYMENT_MODE=saas`. |
| `NUCLEA_REST_CLIENT_CERT_PATH` | **Required in production/SaaS** | Path to the PEM client certificate presented to Núclea for mutual TLS. |
| `NUCLEA_REST_CLIENT_KEY_PATH` | **Required in production/SaaS** | Path to the PEM client private key for mutual TLS. Sensitive — the file holds private key material. |
## RSFN inbound consumer
The inbound channel for RSFN messages, plus optional XSD conformance observation.
| Variable | Default / Required | Description |
| --------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RSFN_CONSUMER_TRANSPORT` | `stub` | Inbound transport behind the RSFN consumer port: `stub` (a development REST channel) or `mq` (the RSFN network transport, wired at homologation). |
| `RSFN_CONSUMER_BASE_URL` | — | Base URL for the `stub` transport. Empty leaves the consumer unwired. |
| `RSFN_CONSUMER_TIMEOUT_SEC` | `30` | Per-request timeout in seconds. |
| `RSFN_CONSUMER_CB_CONSECUTIVE_FAILURES` | `5` | Consecutive failures that trip the circuit breaker open. |
| `RSFN_CONSUMER_CB_OPEN_TIMEOUT_SEC` | `30` | How long the breaker stays open before half-open. |
| `RSFN_CONSUMER_ALLOW_INSECURE_TLS` | `false` | Relax the stub-channel TLS verification for local development only. Forced `false` under `ENV_NAME=production` or `DEPLOYMENT_MODE=saas`. |
| `RSFN_INBOUND_XSD_VALIDATION_ENABLED` | `true` | Observe-only XSD validation of inbound RSFN/SILOC messages against the official schemas. Logs and meters non-conformance without altering dispatch. |
| `ASLC_INBOUND_XSD_VALIDATION_ENABLED` | `true` | Observe-only XSD validation of inbound ASLC return messages. Logs and meters non-conformance without altering the return pipeline. |
| `XSD_VALIDATOR_URL` | — | Base URL of the XSD-validation sidecar the observers call. |
| `XSD_VALIDATOR_TIMEOUT_SEC` | `10` | Per-request timeout in seconds for XSD-validation calls. |
## SFN inbound bus
Ingest of SILOC messages relayed by the SFN bus. The whole family is inert unless `SFN_INGEST_ENABLED=true`.
| Variable | Default / Required | Description |
| ---------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
| `SFN_INGEST_ENABLED` | `false` | Master switch for the SFN ingest path (bus consumer and driver). |
| `SFN_BUS_PROVIDER` | `kafka` | Consumer adapter: `kafka` or `stub` (development/CI). |
| `SFN_KAFKA_BROKERS` | **Required if ingest on and provider `kafka`** | Comma-separated Kafka/RedPanda bootstrap broker list. |
| `SFN_KAFKA_TOPIC` | `siloc.inbound` | Topic the SILOC relay publishes to. |
| `SFN_KAFKA_GROUP_ID` | `—` | Kafka consumer group id; set per deployment. |
| `SFN_KAFKA_BATCH_SIZE` | `100` | Records read per batch. |
| `SFN_STUB_TIMEOUT_SEC` | `30` | Per-request timeout in seconds for the `stub` adapter. |
## Signing sidecar
Lerian SLC signs the SPB security envelope through a stateless signing sidecar so the private key never enters the service process. Custody is selectable per deployment.
| Variable | Default / Required | Description |
| ------------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SIGNER_URL` | **Required** | Base URL of the signing sidecar. |
| `SIGNER_TIMEOUT_SEC` | `10` | Per-request timeout in seconds for signing calls. |
| `SIGNER_SOFTKEY_PFX_PASSPHRASE` | — | Passphrase for the software-key custody adapter. Sensitive. The software-key posture is refused under `ENV_NAME=production` unless explicitly allowed. |
| `SIGNER_SOFTKEY_ALLOW_IN_PRODUCTION` | `false` | Permit the in-process software-key posture in production. Leave `false` — a hardware or cloud-KMS custody path is the production posture. |
| `SIGNER_AWSKMS_DEFAULT_KEY_REF` | — | Optional fallback key reference for the cloud-KMS custody adapter, used only when a request supplies none. Key material never enters the process; only the reference is passed. The custody region comes from the shared `AWS_REGION`. |
## Settlement schedule
Lerian SLC gates dispatch to Núclea's settlement windows and runs a per-tenant schedule worker.
| Variable | Default / Required | Description |
| -------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `SCHEDULE_CREDIT_WINDOW_OPEN` | `00:30` | Credit-acceptance window open, as `HH:MM` São Paulo local time (half-open interval, inclusive). |
| `SCHEDULE_CREDIT_WINDOW_CLOSE` | `17:30` | Credit-acceptance window close, as `HH:MM` São Paulo local time (exclusive). |
| `SCHEDULE_WORKER_ENABLED` | `true` | Enable the recurring per-tenant schedule worker (cutoff alerting and, when enabled, the dispatch and return drivers). |
| `SCHEDULE_WORKER_INTERVAL_SEC` | `30` | Schedule worker tick period in seconds. |
| `SCHEDULE_GRID_GATE_ENABLED` | `false` | Gate dispatch to the calendar-backed STR grid instead of the single credit window. |
| `SCHEDULE_CUTOFF_ALERT_LEAD_MIN` | `30` | Minutes before an STR cutoff at which the window enters pre-cutoff and one alert is emitted. |
| `SCHEDULE_HOLIDAYS` | — | Comma-separated `YYYY-MM-DD` banking holidays in São Paulo local time; the grid never opens a window on a holiday. |
Lerian SLC ships a family of per-driver runtime toggles that opt each settlement flow into the schedule worker — credit and debit dispatch and forward, anticipation, cancellation, status relay, D+1 confirmation, and stuck-operation alerting. Each is a `SCHEDULE_*_ENABLED` switch that defaults to `false` and is opted in during homologation once the per-tenant Núclea material is provisioned. Their cadence and batch knobs follow the `*_INTERVAL_SEC` / `*_BATCH_SIZE` / `*_PAGE_SIZE` pattern.
## Webhooks
Lerian SLC can deliver settlement events to a subscriber endpoint. In BYOC the client supplies the credential material through their own Kubernetes secret.
| Variable | Default / Required | Description |
| -------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `WEBHOOK_WORKER_ENABLED` | `false` | Enable the per-tenant webhook delivery worker. |
| `WEBHOOK_DELIVERY_PROVIDER` | `direct` | Delivery adapter: `direct` (BYOC HMAC HTTP) or `notifications` (SaaS). |
| `WEBHOOK_API_KEY` | **Required if delivering** | Client-defined API key sent in the webhook API-key header. Sensitive. |
| `WEBHOOK_API_KEY_FILE` | — | Path to a file holding the API key (a mounted secret volume). When set, the inline value is ignored. |
| `WEBHOOK_HMAC_SECRET` | **Required if delivering** | Client-defined shared secret used to sign each webhook. Sensitive. Never comes from the runtime-config plane or the database. |
| `WEBHOOK_HMAC_SECRET_FILE` | — | Path to a file holding the HMAC secret (a mounted secret volume). When set, the inline value is ignored. |
| `WEBHOOK_DELIVERY_TIMEOUT_SEC` | `10` | Bound on a single webhook POST attempt, in seconds. |
| `WEBHOOK_MAX_ATTEMPTS` | `6` | Per-subscription retry budget before a delivery is parked on the dead-letter queue. |
| `WEBHOOK_ALLOW_PRIVATE_NETWORK` | `false` | Development-only relaxation of the delivery SSRF block. Must stay `false` in production/SaaS — boot fails closed otherwise. |
| `WEBHOOK_NOTIFICATIONS_BASE_URL` | **Required if provider `notifications`** | Base URL of the notifications service used by the SaaS provider. |