> ## 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 for Lerian STA: the BACEN environment target, S3-compatible object storage, and envelope-encryption master keys.

Lerian STA is the Lerian-owned rail that transmits and receives files with the BACEN STA hub. You set these variables at deploy time. A service restart makes them take effect. 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 STA.

In the tables below, the **Default / Required** column shows the default value. A bold qualifier marks a variable you must set, such as **Required** or **Required in production**. `—` means no default. A variable flagged **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`      | `:4028`                                | Main HTTP listen address. The liveness, readiness, metrics, and version probes bind this same port.                                                                                                                                             |
| `SYSTEMPLANE_ENABLED` | `false`                                | Enable the [Systemplane](/en/reference/platform/systemplane/overview) runtime-configuration admin API under the `/system` prefix on the main port. Off by default (environment-variable-only mode).                                             |
| `DEFAULT_TENANT_ID`   | `11111111-1111-1111-1111-111111111111` | UUID fallback used only for the streaming/outbox `ce-tenantid` when an event has no tenant ID; it is not injected into ordinary single-tenant request or transfer context.                                                                      |
| `BACEN_ENVIRONMENT`   | `homologation`                         | Selects the upstream BACEN STA target for the connectivity probe: `homologation` (staging) or `production` (live). An unrecognized value falls back to `homologation` so a non-production stack cannot route traffic to the live BACEN service. |

<Note>
  Lerian STA 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.
</Note>

## Object storage

Lerian STA persists transfer bytes and inbound downloads to an S3-compatible object store. Each subsystem configures its own connection through the AWS SDK, so the same wiring drives AWS S3, MinIO, or a local store.

| Variable                                       | Default / Required         | Description                                                                                                                                                         |
| ---------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRANSFER_OBJECT_STORAGE_BUCKET`               | **Required in production** | Bucket holding both transfer directions, keyed by direction prefix. Production boot is refused if it is empty, regardless of whether inbound transfers are enabled. |
| `TRANSFER_INBOUND_ENABLED`                     | `false`                    | Enable the inbound (BACEN-pulled) transfer pipeline. It does not change the production bucket requirement because outbound transfers also use the bucket.           |
| `TRANSFER_INBOUND_MAX_FILE_SIZE_BYTES`         | `5368709120`               | Maximum BACEN-advertised inbound file size, in bytes (5 GiB). A value of `0` or less disables this admission bound.                                                 |
| `TRANSFER_INBOUND_EXTRACT_MAX_EXPANSION_RATIO` | `100`                      | Maximum ratio between the extracted entry size and its delivered ZIP envelope. A value of `0` or less disables the ratio check.                                     |
| `TRANSFER_INBOUND_EXTRACT_MAX_EXTRACTED_BYTES` | `5368709120`               | Absolute maximum size of the single extracted ZIP entry, in bytes (5 GiB). A value of `0` or less disables this bound.                                              |
| `AWS_REGION`                                   | —                          | Region for M2M AWS Secrets Manager and, when `MASTER_KEY_KMS_REGION` is empty, the AWS KMS fallback. It does not configure object storage.                          |
| `AWS_ACCESS_KEY_ID`                            | —                          | Access key for the object store. Sensitive. Leave unset when an attached IAM role supplies credentials.                                                             |
| `AWS_SECRET_ACCESS_KEY`                        | —                          | Secret key for the object store. Sensitive. Leave unset when an attached IAM role supplies credentials.                                                             |

## Envelope encryption

Lerian STA protects operator credentials with AES-GCM envelope encryption. The manager process always needs the master-key material. A missing or malformed value aborts boot.

| Variable                       | Default / Required        | Description                                                                                                                                                                                                                                                                                                                |
| ------------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MASTER_KEY_PROVIDER`          | `envvar`                  | Source of the envelope-encryption key: `envvar` (key read from `MASTER_KEYS`) or `aws-kms` (key wrapped by a cloud KMS).                                                                                                                                                                                                   |
| `MASTER_KEY_VERSION`           | **Required**              | Selects the currently active master-key version. Must match a version present in `MASTER_KEYS`.                                                                                                                                                                                                                            |
| `MASTER_KEYS`                  | **Required**              | Comma-separated `version:key` pairs. Sensitive. With `envvar`, each value is a 64-hex-character AES-256 key: `version:<64-hex-key>`. With `aws-kms`, each value is base64 KMS ciphertext: `version:<base64-ciphertext>`, decrypted in process. Source from your secret manager — a missing or malformed value aborts boot. |
| `MASTER_KEY_KMS_KEY_ID`        | **Required if `aws-kms`** | Identifier of the AWS KMS key used to decrypt the `MASTER_KEYS` ciphertext. With `aws-kms`, the ciphertext is decrypted in the STA process.                                                                                                                                                                                |
| `CREDENTIALS_RECOVERY_ON_BOOT` | `false`                   | Set explicitly to `true` to run the worker-side credential-recovery sweep once at boot for credentials left mid-rotation by a previous process.                                                                                                                                                                            |

<Note>
  Lerian STA runs its audit pipeline in a dedicated worker. The publisher, consumer, and export generator support both single-tenant and multi-tenant modes. The export generator also needs its S3 bucket. The partition manager, cleanup, and verifier require multi-tenancy.

  Configure the enabled flags and required knobs through the `AUDIT_PUBLISHER_*`, `AUDIT_CONSUMER_*`, `AUDIT_PARTITION_*`, `AUDIT_CLEANUP_*`, `AUDIT_VERIFIER_*`, `AUDIT_EXPORT_GENERATOR_*`, and `AUDIT_EXPORT_RATE_LIMIT_*` families. The runtime applies their declared defaults. Explicitly enable a worker before expecting it to run.
</Note>