Environment Variables & Secrets - Coreflux Documentation

Stop Hardcoding Credentials

Every IoT deployment needs connection strings, API keys, and passwords — but embedding them directly in your LoT code or route definitions creates security risks and makes your configuration impossible to reuse across environments. The Coreflux Broker solves this with built-in environment variable and secrets management.

Environment variables store non-sensitive configuration (hostnames, ports, URLs) in a plain-text .env file
Secrets store sensitive credentials (passwords, API keys, tokens) encrypted at rest with AES-256-GCM

Both are accessible from LoT Actions, Models, Routes, and broker CLI commands using a unified syntax — no external tools or services required.

Think of it like a vault and a notebook. Environment variables are the notebook — quick to read, easy to update, visible if someone opens the file. Secrets are the vault — locked with a key, encrypted on disk, only decrypted when the broker needs them at runtime.

Environment variables and secrets management is available from Coreflux Broker v1.9.3 and above.

When to Use Each

Scenario	Use	Why
Database host, port, name	Environment variable	Non-sensitive, changes per environment
API base URLs	Environment variable	Configuration that varies between dev/staging/prod
Feature flags	Environment variable	Simple on/off toggles
Database passwords	Secret	Must not be readable on disk
API keys and tokens	Secret	Sensitive credentials
TLS passphrases	Secret	Security-critical values

In This Page

Section	Description
Config Root	How the broker resolves its configuration directory
Environment Variables	Plain-text configuration management
Secrets	Encrypted credential storage
Using in LoT	GET ENV, GET SECRET, KEEP, DELETE syntax
Using in Routes	Referencing env vars and secrets in route definitions
CLI Commands	Managing env vars and secrets via broker commands
Deployment	Windows, Linux, Docker, and Kubernetes setup
Resolution Reference	Quick-reference tables for resolution order and syntax

Config Root

The broker builds its configuration root directory from two parts:

Config root = {CONFIG_PATH or AppDirectory} + /Coreflux

If the CONFIG_PATH environment variable is set, it is used as the base path
Otherwise, the application directory is used (e.g. /app in Docker, the executable’s folder on Windows/Linux)
/Coreflux is always appended automatically

For example, with CONFIG_PATH=/data, the config root becomes /data/Coreflux.

File Layout

The environment and secrets files live alongside the broker’s internal data under the config root:

{config_root}/
  .env                # Plain-text environment variables (key=value)
  secrets.json        # AES-256-GCM encrypted secrets
  secret.key          # Optional: encryption key (base64, 32 bytes)
  bin/                # Internal broker data (managed automatically)
  log/                # Log files
  stats/              # Statistics

Environment Variables

Storage

Environment variables are stored in plain text in {config_root}/.env using standard key=value format:

DB_HOST=postgres.example.com
DB_PORT=5432
API_BASE_URL=https://api.example.com
MQTT_BRIDGE_HOST=remote-broker.company.com

Resolution Order

When the broker resolves an environment variable (via GET ENV, route config, or CLI), it checks multiple sources in this order:

Priority	Source	Description
1	`.env` file (managed)	Set via `-setEnv` or `KEEP ENV`. Persisted to disk.
2	Process environment	Docker `environment:`, Kubernetes `env:`, or shell exports.
3	User environment	OS user-level environment variables (non-Docker).
4	Machine environment	OS machine-level environment variables (non-Docker).

If not found in any source, an empty string is returned.

This fallback chain means Docker environment: variables work even without a .env file — the broker picks them up from the process environment automatically.

Secrets

How Secrets Work

Secrets are encrypted at rest using AES-256-GCM and stored in {config_root}/secrets.json. Each secret entry contains the initialization vector, the encrypted value with authentication tag, and a creation timestamp:

{
  "DB_PASSWORD": {
    "IV": "base64...",
    "Value": "base64(ciphertext):base64(tag)",
    "Created": "2026-02-08T12:00:00Z"
  }
}

Secret values are only decrypted at runtime when accessed via GET SECRET or route configuration. They are never logged or displayed — even the -listSecrets command only shows secret names, never values.

Encryption Key

The broker resolves the encryption key in this order:

Priority	Source	Notes
1	`COREFLUX_SECRET_KEY` env var	Best for Docker/Kubernetes. Base64-encoded, 32 bytes.
2	`{config_root}/secret.key` file	Good for mounted volumes. Base64-encoded, 32 bytes.
3	Derived from machine GUID	Auto-generated fallback. Machine-specific — secrets become unreadable if moved to a different machine.

Generating a Key

Use OpenSSL to generate a cryptographically secure 32-byte key:

openssl rand -base64 32
# Example output: K7x2mN8pQ1rT5uW3yB6dF9hJ0kL4nP7sV2xZ8cG1eA=

If you use the derived key fallback (no explicit key), your secrets are tied to the specific machine. Moving the secrets.json file to another machine or container will make the secrets unreadable. Always use an explicit key for portable deployments.

Using in LoT

Environment variables and secrets can be read, written, and deleted from within LoT Actions, Models, and route configurations.

Reading Values

Use GET ENV to read an environment variable and GET SECRET to read an encrypted secret (decrypted at runtime):

-- Read configuration from environment
SET "myHost" WITH (GET ENV "DB_HOST")
SET "myPort" WITH (GET ENV "DB_PORT")

-- Read credentials from encrypted secrets
SET "dbPass" WITH (GET SECRET "DB_PASSWORD")
SET "apiKey" WITH (GET SECRET "API_KEY")

Persisting Values

Use KEEP ENV to save a new environment variable to the .env file, and KEEP SECRET to encrypt and store a new secret:

-- Save an environment variable (persisted to .env)
KEEP ENV "LAST_RUN" WITH TIMESTAMP "UTC"

-- Save an encrypted secret (persisted to secrets.json)
KEEP SECRET "API_KEY" WITH "sk-abc123"

Deleting Values

Use DELETE ENV and DELETE SECRET to remove values:

-- Remove an environment variable
DELETE ENV "OLD_CONFIG"

-- Remove a secret
DELETE SECRET "OLD_API_KEY"

Complete Example

This action reads database configuration from environment variables and credentials from secrets on broker startup, then reports the status:

DEFINE ACTION ConnectToDatabase
ON START DO
    -- Read connection settings from environment
    SET "host" WITH (GET ENV "DB_HOST")
    SET "port" WITH (GET ENV "DB_PORT")
    SET "dbName" WITH (GET ENV "DB_NAME")

    -- Read credentials from encrypted secrets
    SET "user" WITH (GET SECRET "DB_USER")
    SET "pass" WITH (GET SECRET "DB_PASSWORD")

    IF {host} == EMPTY THEN
        PUBLISH TOPIC "system/errors" WITH "DB_HOST not configured"
    ELSE
        PUBLISH TOPIC "system/status" WITH "Database configured: " + {host} + ":" + {port}

    -- Track when we last initialized
    KEEP ENV "LAST_DB_INIT" WITH TIMESTAMP "UTC"

Using in Routes

Environment variables and secrets can be referenced directly in route definitions, keeping connection details out of your LoT code.

Standard Syntax

Use GET ENV and GET SECRET in route configuration blocks to inject values at runtime:

DEFINE ROUTE MyDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER GET ENV "DB_HOST"
        WITH PORT 5432
        WITH DATABASE GET ENV "DB_NAME"
        WITH USERNAME GET ENV "DB_USER"
        WITH PASSWORD GET SECRET "DB_PASSWORD"

Legacy Prefix Syntax

The ENV: and SECRET: prefix syntax is also supported for backward compatibility in route ADD CONFIG sections:

WITH SERVER ENV:DB_HOST
WITH PASSWORD SECRET:DB_PASSWORD

Event Query Placeholders

In route event queries (e.g. WITH QUERY), use curly-brace placeholders that are resolved at execution time:

ADD EVENT StoreReading
    WITH SOURCE_TOPIC "sensors/#"
    WITH QUERY "INSERT INTO readings (host, value) VALUES ('{env.DB_HOST}', '{payload}')"

Placeholder	Resolves To
`{env.NAME}`	Environment variable value
`{secret.NAME}`	Decrypted secret value

CLI Commands

Manage environment variables and secrets at runtime by publishing commands to $SYS/Coreflux/Command using any MQTT client (such as MQTT Explorer).

Environment Variable Commands

Command	Description
`-setEnv NAME=value`	Set an environment variable (persisted to `.env` file)
`-removeEnv NAME`	Remove an environment variable
`-listEnv`	List all managed environment variables

Publish these messages to $SYS/Coreflux/Command to manage environment variables:

# Set an environment variable
-setEnv DB_HOST=postgres.example.com

# List all environment variables
-listEnv

# Remove an environment variable
-removeEnv OLD_CONFIG

Secret Commands

Command	Description
`-setSecret NAME=value`	Set a secret (encrypted and persisted to `secrets.json`)
`-removeSecret NAME`	Remove a secret
`-listSecrets`	List secret names (values are never shown)

Publish these messages to $SYS/Coreflux/Command to manage secrets:

# Set a secret
-setSecret DB_PASSWORD=my_secure_password

# List secret names
-listSecrets

# Remove a secret
-removeSecret OLD_API_KEY

Subscribe to $SYS/Coreflux/Command/Output to receive confirmation responses from commands.

Deployment

Set up environment variables and secrets across different deployment targets.

Windows
Linux
Docker Compose
Kubernetes

On Windows, the config root defaults to the broker’s executable directory + \Coreflux unless CONFIG_PATH is set.

Locate the Config Directory

If the broker is installed at C:\Coreflux\, the config root is C:\Coreflux\Coreflux\.To use a custom path, set the CONFIG_PATH system environment variable:

[Environment]::SetEnvironmentVariable("CONFIG_PATH", "C:\CorefluxData", "Machine")

The config root becomes C:\CorefluxData\Coreflux\.

Create the .env File

Create a .env file in the config root with your environment variables:

@"
DB_HOST=postgres.example.com
DB_PORT=5432
API_BASE_URL=https://api.example.com
"@ | Out-File -FilePath "C:\CorefluxData\Coreflux\.env" -Encoding UTF8

Generate an Encryption Key

Generate and save a secret.key file for encrypting secrets:

openssl rand -base64 32 > "C:\CorefluxData\Coreflux\secret.key"

Set Secrets After Start

Start the broker, then set secrets using any MQTT client (such as MQTT Explorer). Publish to $SYS/Coreflux/Command:

-setSecret DB_PASSWORD=my_secure_password

Subscribe to $SYS/Coreflux/Command/Output to confirm the secret was stored.

On Linux, set CONFIG_PATH in the systemd service file or shell environment.

Create the Config Directory

Create the directory and set ownership to the broker’s service user:

sudo mkdir -p /data/Coreflux
sudo chown coreflux:coreflux /data/Coreflux

Create the .env File

Write your environment variables and restrict permissions:

cat > /data/Coreflux/.env << 'EOF'
DB_HOST=postgres.example.com
DB_PORT=5432
API_BASE_URL=https://api.example.com
EOF
chmod 600 /data/Coreflux/.env

Generate an Encryption Key

Generate the key and restrict permissions:

openssl rand -base64 32 > /data/Coreflux/secret.key
chmod 600 /data/Coreflux/secret.key

Configure the systemd Service

Add CONFIG_PATH to your service file at /etc/systemd/system/coreflux.service:

[Service]
Environment=CONFIG_PATH=/data
ExecStart=/opt/coreflux/CorefluxMQTTBroker

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart coreflux

Set Secrets After Start

Using any MQTT client, publish to $SYS/Coreflux/Command:

-setSecret DB_PASSWORD=my_secure_password

Verify with -listSecrets — the secret name should appear in the output.

Option 1: Mount a Config Volume (Recommended)

Pre-create the config files on the host and mount them into the container.1. Prepare the host directory:Create the config directory, generate an encryption key, and write your environment variables:

mkdir -p ./coreflux-data

# Generate encryption key
openssl rand -base64 32 > ./coreflux-data/secret.key

# Create .env file
cat > ./coreflux-data/.env << 'EOF'
DB_HOST=postgres.example.com
DB_PORT=5432
API_BASE_URL=https://api.example.com
EOF

2. Docker Compose file:Mount the config directory and set CONFIG_PATH so the broker finds its files:

services:
  coreflux-broker:
    image: coreflux/coreflux-broker:latest
    container_name: coreflux-broker
    ports:
      - "1883:1883"
      - "8883:8883"
      - "5000:5000"
    environment:
      - CONFIG_PATH=/data
    volumes:
      - ./coreflux-data:/data/Coreflux
    restart: unless-stopped

The broker resolves:

CONFIG_PATH=/data means config root is /data/Coreflux
.env loaded from /data/Coreflux/.env (your mounted ./coreflux-data/.env)
secret.key loaded from /data/Coreflux/secret.key (your mounted key)
All config files (bin/, log/, etc.) persist in the mounted volume

3. Set secrets after the broker starts:Using any MQTT client, publish to $SYS/Coreflux/Command:

-setSecret DB_PASSWORD=my_secure_password

Option 2: Pass Env Vars via Docker (No .env File)

If you prefer not to manage a .env file, pass variables directly through Docker’s environment:. The resolution fallback to process environment picks them up:

services:
  coreflux-broker:
    image: coreflux/coreflux-broker:latest
    ports:
      - "1883:1883"
    environment:
      - CONFIG_PATH=/data
      - DB_HOST=postgres.example.com
      - DB_PORT=5432
      - API_BASE_URL=https://api.example.com
      - COREFLUX_SECRET_KEY=K7x2mN8pQ1rT5uW3yB6dF9hJ0kL4nP7sV2xZ8cG1eA=
    volumes:
      - coreflux-data:/data/Coreflux

volumes:
  coreflux-data:

Variables set this way:

Are available to LoT via GET ENV "DB_HOST"
Are available to routes via GET ENV "DB_HOST" and legacy ENV:DB_HOST
Are not persisted to .env (they exist only in the process environment)
Will be lost if the container restarts without the same environment: block

Secrets still need a volume for secrets.json persistence, even when passing the encryption key via COREFLUX_SECRET_KEY.

Use Kubernetes ConfigMaps for environment variables and Kubernetes Secrets for the encryption key.1. ConfigMap for environment variables:Store non-sensitive configuration in a ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: coreflux-env
data:
  DB_HOST: "postgres.cluster.local"
  DB_PORT: "5432"
  API_BASE_URL: "https://api.example.com"

2. Kubernetes Secret for the encryption key:Store the encryption key in a Kubernetes Secret (base64-encoded):

apiVersion: v1
kind: Secret
metadata:
  name: coreflux-secrets
type: Opaque
data:
  COREFLUX_SECRET_KEY: SzdsMm1OOHBRMXJUNXVXM3lCNmRGOWhKMGtMNG5QN3NWMnhaOGNHMWVBPQ==

3. Deployment:Inject the ConfigMap as environment variables via envFrom, and the encryption key from the Kubernetes Secret:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: coreflux-broker
spec:
  replicas: 1
  selector:
    matchLabels:
      app: coreflux-broker
  template:
    metadata:
      labels:
        app: coreflux-broker
    spec:
      containers:
        - name: broker
          image: coreflux/coreflux-broker:latest
          ports:
            - containerPort: 1883
            - containerPort: 5000
          env:
            - name: CONFIG_PATH
              value: "/data"
            - name: COREFLUX_SECRET_KEY
              valueFrom:
                secretKeyRef:
                  name: coreflux-secrets
                  key: COREFLUX_SECRET_KEY
          envFrom:
            - configMapRef:
                name: coreflux-env
          volumeMounts:
            - name: data
              mountPath: /data/Coreflux
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: coreflux-pvc

4. PersistentVolumeClaim:Provide persistent storage for broker data, secrets, and configuration:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: coreflux-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

Apply all resources:

kubectl apply -f coreflux-configmap.yaml
kubectl apply -f coreflux-secret.yaml
kubectl apply -f coreflux-pvc.yaml
kubectl apply -f coreflux-deployment.yaml

ConfigMap values are injected as process environment variables via envFrom, so GET ENV picks them up through the fallback chain. The COREFLUX_SECRET_KEY from the Kubernetes Secret enables portable secret encryption.

Best Practices

Use explicit encryption keys in production

Never rely on the derived key fallback for production deployments. Always provide a COREFLUX_SECRET_KEY environment variable or a secret.key file. The derived key is machine-specific — if you migrate, scale, or recreate a container, your secrets become unreadable.

Restrict file permissions

On Linux, restrict access to sensitive files to the broker’s service user only:

chmod 600 /data/Coreflux/.env
chmod 600 /data/Coreflux/secret.key
chmod 600 /data/Coreflux/secrets.json

Prefer GET ENV over hardcoded values

Even for values that seem static (like a database port), use GET ENV so you can change configuration without redeploying LoT code. This makes your Actions and Routes portable across dev, staging, and production.

Use mounted volumes for Docker

Always mount a persistent volume at {CONFIG_PATH}/Coreflux in Docker and Kubernetes. Without a volume, your .env, secrets.json, and all broker state are lost when the container stops.

Never commit secrets to version control

Keep secret.key, secrets.json, and .env files out of Git. Add them to .gitignore and use your deployment pipeline to inject them at runtime.

Resolution Reference

Where Each Syntax Reads From

Syntax	Where It Works	Resolved By
`GET ENV "NAME"`	Actions, Models, Route configs	`.env` file, then process env fallback
`GET SECRET "NAME"`	Actions, Models, Route configs	Decrypts from `secrets.json`
`ENV:NAME`	Route `ADD CONFIG` sections only	Same as `GET ENV`
`SECRET:NAME`	Route `ADD CONFIG` sections only	Same as `GET SECRET`
`{env.NAME}`	Event queries (`WITH QUERY`)	Replaced at event execution time
`{secret.NAME}`	Event queries (`WITH QUERY`)	Replaced at event execution time

Encryption Key Resolution Order

Priority	Source	Notes
1	`COREFLUX_SECRET_KEY` env var	Best for Docker/Kubernetes. Base64-encoded, 32 bytes.
2	`{config_root}/secret.key` file	Good for mounted volumes. Base64-encoded, 32 bytes.
3	Derived from machine GUID	Auto-generated fallback. Machine-specific — secrets won’t decrypt on a different machine.

GetEnv Resolution Order

Priority	Source	Notes
1	`.env` file (managed)	Set via `-setEnv` or `KEEP ENV`. Persisted to disk.
2	Process environment	Docker `environment:`, Kubernetes `env:`, or shell exports.
3	User environment	OS user-level env vars (non-Docker).
4	Machine environment	OS machine-level env vars (non-Docker).

Quick Start

MQTT Broker

AI

LoT Language

LoT Notebooks

Actions

Routes

Models

Rules

​Stop Hardcoding Credentials

​When to Use Each

​In This Page

​Config Root

​File Layout

​Environment Variables

​Storage

​Resolution Order

​Secrets

​How Secrets Work

​Encryption Key

​Generating a Key

​Using in LoT

​Reading Values

​Persisting Values

​Deleting Values

​Complete Example

​Using in Routes

​Standard Syntax

​Legacy Prefix Syntax

​Event Query Placeholders

​CLI Commands

​Environment Variable Commands

​Secret Commands

​Deployment

​Option 1: Mount a Config Volume (Recommended)

​Option 2: Pass Env Vars via Docker (No .env File)

​Best Practices

​Resolution Reference

​Where Each Syntax Reads From

​Encryption Key Resolution Order

​GetEnv Resolution Order

​Next Steps

Broker Commands

Operations Reference

Stop Hardcoding Credentials

When to Use Each

In This Page

Config Root

File Layout

Environment Variables

Storage

Resolution Order

Secrets

How Secrets Work

Encryption Key

Generating a Key

Using in LoT

Reading Values

Persisting Values

Deleting Values

Complete Example

Using in Routes

Standard Syntax

Legacy Prefix Syntax

Event Query Placeholders

CLI Commands

Environment Variable Commands

Secret Commands

Deployment

Option 1: Mount a Config Volume (Recommended)

Option 2: Pass Env Vars via Docker (No .env File)

Best Practices

Resolution Reference

Where Each Syntax Reads From

Encryption Key Resolution Order

GetEnv Resolution Order

Next Steps