Environment Variables

An environment variable is a named value the operating system hands to a program when it starts. Bridge uses them to receive settings without writing them into the config file, which matters most for secrets and for values that differ between deployments.

Every setting has a variable, named after its path

You do not need a list. The variable name is the setting’s position in the config file, upper-cased, with each level joined by an underscore and prefixed with BRIDGE_:

Every setting documented in bridge.reference.yaml is reachable this way. The names come from Bridge’s own configuration structure rather than a maintained list, so a setting added in a later release is settable as soon as it exists.

Write values the way the config file writes them

Lists are comma-separated because an environment variable holds a single string. Spaces around a comma are ignored.

Listen addresses accept a bare port. BRIDGE_SSH_NATIVE_LISTEN=2222 binds every interface on port 2222, the same as writing listen: 2222 in the file. To bind one interface, give a host and a port: BRIDGE_SSH_NATIVE_LISTEN=127.0.0.1:2222.

An override completes the config file

Bridge reads the config file, applies environment variables over it, then validates the result once. A file that is missing a required value is completed by an override rather than rejected because of one.

An environment variable takes precedence over the same setting in the file. Nothing in the file overrides an environment variable.

A malformed value stops the process and names the variable. BRIDGE_SERVER_TLS_ENABLED=yes-please fails at startup and says which variable was wrong, rather than being ignored and leaving TLS in a state you did not choose.

Variables with no configuration setting

Bridge reads these from the environment only. The secrets are kept out of every config file deliberately. The identity values differ per process, so a file shared by several processes cannot carry them.

In v3.0.1, the container entrypoint exports defaults for BRIDGE_BROKER_API_URL, BRIDGE_BROKER_API_TOKEN_FILE, and BRIDGE_TLS_INSECURE to broker scripts. It preserves nonempty overrides. Bridge creates the credential file at startup. bsh reads that file. BSH_BRIDGE_BROKER_API_TOKEN can instead supply the token or a secret-manager reference. See bsh’s connection overrides.

Platform telemetry defaults to disabled in v3.0.1 and later. Set BRIDGE_SERVER_TELEMETRY_DISABLED=false only after your tenant supports telemetry ingestion, then restart the publisher. See Platform Telemetry.

BRIDGE_NAMESPACE is not a configuration override. The orchestrator passes it through to the workers it creates. The Kubernetes namespace itself is cluster.orchestrator.provisioner.k8s.namespace.

Older variable names still work

Bridge recognised a small number of variables before names were derived from setting paths. Each one remains valid and sets exactly what it always did. Where both forms are set, a nonempty path-derived value wins.

Create API tokens in the admin panel

In v3.0.2 and later, Admin > API Tokens contains read-only service tokens for monitoring and checkout tokens for external brokers. Bridge stores token hashes in the datastore. Token values are not Bridge configuration settings.

See Metrics and service tokens or Connect an external broker. External broker support defaults to disabled. Its maximum token lifetime defaults to 90 days.