> ## 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. You set these variables at deploy time. A service restart applies them. Every Lerian Go service shares a universal backbone — server, datastores, multi-tenancy, telemetry, plugin authentication, and licensing. [BYOC configuration essentials](/en/reference/byoc-configuration) documents that backbone once. 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 a variable you must set. `—` means no default. A variable marked **Sensitive** carries credential or key material. Inject it from your secret manager at deploy time. 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`. When you enable multi-tenancy, it also exposes `GET /readyz/tenant/{id}`. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.
## Núclea REST transport
This channel submits to Núclea online 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
This channel receives inbound RSFN messages. It also observes XSD conformance.
| 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). |
| `MQ_BRIDGE_URL` | **Required if transport `mq`** | Base URL of the MQ bridge. You must declare it explicitly when `RSFN_CONSUMER_TRANSPORT=mq`; it cannot inherit `http://localhost:9121`, because the correct address depends on your deployment topology. |
| `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` | `http://localhost:9091` | 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
The SFN bus relays SILOC messages. This path ingests them. The whole family stays inert unless you set `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` | service-scoped default | Kafka consumer group id; override per deployment when needed. |
| `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. The private key never enters the service process. You select the custody backend per deployment.
| Variable | Default / Required | Description |
| ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SIGNER_URL` | `http://localhost:9101` | 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 cloud-KMS adapter needs `SIGNER_AWSKMS_REGION`, the KMS key's AWS region, which the standard deployment derives 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` | **Required in every environment** | Credit-acceptance window open, as `HH:MM` São Paulo local time (half-open interval, opening boundary inclusive). Declare it explicitly for the grade in force. |
| `SCHEDULE_CREDIT_WINDOW_CLOSE` | **Required in every environment** | Credit-acceptance window close, as `HH:MM` São Paulo local time (exclusive). Declare it explicitly for the grade in force. |
| `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_DISPATCH_MAX_TRANSMIT_ATTEMPTS` | `20` | Transmit attempts a dispatch may burn before the operation is parked for operator review instead of retrying forever. At the default 30-second tick, 20 attempts is about ten minutes before the first alert. |
| `SCHEDULE_HOLIDAYS` | — | Comma-separated `YYYY-MM-DD` banking holidays in São Paulo local time; the grid never opens a window on a holiday. |
You must declare both credit-window variables, even when you use the standing schedule. The service refuses to start if either value is omitted or blank; it never assumes a credit grade from a default.
Lerian SLC ships a family of per-driver runtime toggles. Each toggle opts one flow into the schedule worker: credit and debit dispatch and forward, anticipation, cancellation, status relay, D+1 confirmation, and stuck-operation alerts. Each is a `SCHEDULE_*_ENABLED` switch that defaults to `false`. You opt each one in during homologation, once the per-tenant Núclea material is ready. The 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_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. |