Startup Options & Deployment

Configure the broker before it starts

Pass configuration at process start so containers, packages, and CI pipelines come up the same way every time. Typical jobs:

Point the data directory at a persistent volume
Import broker or user JSON on first boot
Load a LoT notebook project from git or disk
Stage a signed license or enrollment token before MQTT accepts connections

Think of startup options as a recipe card. You tell the broker where its data lives and which project to load; it applies that recipe and then stays up as a service or container.

For install commands (Docker, APT, DNF, Windows), start with Installation. For COREFLUX_* variables, secrets, and .env files, see Environment Variables & Secrets.

Command-line options

Configuration

Option	Long form	Description
`-c`	`--config`	Path to broker configuration JSON. Applied only when no broker config exists yet, unless you also pass `--config-force`.
`-cf`	`--config-force`	Overwrite existing broker configuration with `--config`.
`-u`	`--users`	Path to users JSON. Applied only when no users file exists yet, unless you also pass `--users-force`.
`-uf`	`--users-force`	Overwrite existing users with `--users`.
`-p`	`--path`	Data directory (same role as `COREFLUX_DATA_PATH`). Prefer the environment variable so the path is set before `--config` is applied.

Set COREFLUX_DATA_PATH or CONFIG_PATH in the process environment, then start the binary. -p / --path is applied late in startup, so --config can write into the default data directory instead of the path you intended.

Projects and licenses

Load LoT (Language of Things) from a project (git URL, local folder, or a project already stored on this broker). That is the supported way to ship Actions, Models, Connectors, and Rules at boot.

Option	Long form	Description
	`--project`	Load a project at startup (git URL, local path, or existing project name).
	`--branch`	Git branch or tag to check out with `--project`.
`-loadLicense`	`--load-license`	Stage a signed license file (compact JWS) as `config/license.jws` before MQTT starts.
`-showFingerprint`	`--show-fingerprint`	Print the broker host’s hardware fingerprint and exit. Send it to Coreflux to be issued an offline license. Does not start MQTT.
`-enroll`	`--enroll`	Stage a single-use enrollment token (`et_…`) for organization binding. Also accepted on `$SYS/Coreflux/Command` while the broker is running.

A project loaded with --project (or -loadProject at runtime) is remembered across restarts. On the next start, if you do not pass --project, the broker re-activates that project. -unloadProject clears it. --project always wins over the remembered project. To activate a license at start, set COREFLUX_ACTIVATION_CODE in the process environment or pass --load-license. Register at portal.coreflux.org for a 30-day Growth-type license. See Licensing and Enrollment.

Other options

Option	Long form	Description
`-I`	`--install`	Register a Windows service or a Linux systemd unit for a portable (zip/tarball) binary. Skip this when you installed from APT/DNF — the package already ships `coreflux-broker.service`.
`-h`	`--help`	Display help.

Basic usage

Starting with configuration files

Linux
Windows

# Start with broker configuration
./CorefluxMQTTBroker --config /path/to/broker-config.json

# Start with users configuration
./CorefluxMQTTBroker --users /path/to/users.json

# Start with both
./CorefluxMQTTBroker \
    --config /path/to/broker-config.json \
    --users /path/to/users.json

# Start with broker configuration
.\CorefluxMQTTBroker.exe --config C:\config\broker-config.json

# Start with users configuration
.\CorefluxMQTTBroker.exe --users C:\config\users.json

# Start with both
.\CorefluxMQTTBroker.exe `
    --config C:\config\broker-config.json `
    --users C:\config\users.json

Force overwrite existing configuration

By default, if configuration already exists in the data directory, startup JSON is ignored. Use force flags to overwrite:

# Force overwrite broker config
./CorefluxMQTTBroker --config /path/to/broker-config.json --config-force

# Force overwrite users config
./CorefluxMQTTBroker --users /path/to/users.json --users-force

# Force overwrite both (short form)
./CorefluxMQTTBroker -c /path/to/broker-config.json -cf -u /path/to/users.json -uf

Force flags overwrite existing configurations. Back up your current configuration before using them.

Loading a project at startup

# From git URL
./CorefluxMQTTBroker --project https://github.com/org/my-iot-project.git --branch production

# From local path
./CorefluxMQTTBroker --project /path/to/my-project

# By project name (already stored on this broker)
./CorefluxMQTTBroker --project my-iot-project

Package Actions, Models, Connectors, and Rules in a LoT notebook project and load it with --project. That is the supported bootstrap path for LoT at startup.

Configuration files

Broker configuration (JSON)

The broker configuration file defines MQTT service settings:

{
  "Name": "MyCorefluxBroker",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 443,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0",
  "AnonymousLogin": false,
  "FullDebugLog": false,
  "ServerCertificatePath": "/path/to/certificate.pfx",
  "ServerCertificatePassword": "your-certificate-password",
  "ResendRetainTopics": false
}

For every supported field (ports, TLS/mTLS, sessions, performance, data paths, ops, durability), see Broker Configuration.

Users configuration (JSON)

The users configuration file defines MQTT users and their permissions:

[
  {
    "UserName": "root",
    "Password": "your-secure-password",
    "AllowedBaseTopic": "#",
    "AllowedSystemConfiguration": true,
    "AllowedUserManagement": true,
    "AllowedLogManagement": true
  },
  {
    "UserName": "device-user",
    "Password": "device-password",
    "AllowedBaseTopic": "devices/",
    "AllowedSystemConfiguration": false,
    "AllowedUserManagement": false,
    "AllowedLogManagement": false
  }
]

Property	Type	Description
`UserName`	string	MQTT username
`Password`	string	MQTT password
`AllowedBaseTopic`	string	Topic access restriction (`#` for all topics)
`AllowedSystemConfiguration`	bool	Allow system configuration changes
`AllowedUserManagement`	bool	Allow user management operations
`AllowedLogManagement`	bool	Allow log management operations

Container deployment

Official images use CONFIG_PATH=/etc/project. Persist that directory so configuration, secrets, and projects survive image updates. The published image is coreflux/coreflux-mqtt-broker.

Docker
Docker Compose
Kubernetes

Same pattern as Installation: named volume at /etc/project, MQTT on 1883, WebSocket on 5000, ops on 9100.

docker run --pull=always -d --name coreflux_broker \
  -p 1883:1883 -p 5000:5000 -p 9100:9100 \
  -v project-volume:/etc/project \
  coreflux/coreflux-mqtt-broker:latest \
  --project https://github.com/org/my-iot-project.git --branch main

Import JSON on first boot by mounting files and passing --config / --users (add --config-force / --users-force only when you intend to replace existing state):

docker run --pull=always -d --name coreflux_broker \
  -p 1883:1883 -p 5000:5000 -p 9100:9100 \
  -v project-volume:/etc/project \
  -v /host/config:/config:ro \
  coreflux/coreflux-mqtt-broker:latest \
  --config /config/broker-config.json \
  --users /config/users.json

Probe liveness with curl http://localhost:9100/health. The image has no shell, so do not use exec healthchecks.

Use the Compose file from Installation. To load a project, add command on the broker service:

services:
  broker:
    image: coreflux/coreflux-mqtt-broker:latest
    ports:
      - "1883:1883"
      - "5000:5000"
      - "9100:9100"
    volumes:
      - broker-data:/etc/project
    command:
      - "--project"
      - "https://github.com/org/my-iot-project.git"
      - "--branch"
      - "main"
    restart: unless-stopped

volumes:
  broker-data:

The image already sets CONFIG_PATH=/etc/project. Override COREFLUX_DATA_PATH only if you change the mount path.

Mount a PVC at /etc/project. Use HTTP probes on port 9100 (the image has no shell). Paths and a Prometheus scrape are on Operational endpoints.

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-mqtt-broker:latest
          args:
            - "--project"
            - "https://github.com/org/my-iot-project.git"
            - "--branch"
            - "production"
          ports:
            - containerPort: 1883
              name: mqtt
            - containerPort: 5000
              name: websocket
            - containerPort: 9100
              name: ops
          env:
            - name: CONFIG_PATH
              value: "/etc/project"
          volumeMounts:
            - name: data
              mountPath: /etc/project
          livenessProbe:
            httpGet:
              path: /health
              port: 9100
            initialDelaySeconds: 5
            periodSeconds: 15
          readinessProbe:
            httpGet:
              path: /ready
              port: 9100
            initialDelaySeconds: 5
            periodSeconds: 10
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: coreflux-data

Service installation

Prefer the install method from Installation. Use --install only for portable binaries.

Linux packages
Windows
Portable Linux

APT and DNF packages already register coreflux-broker.service, install under /opt/coreflux-broker, and set COREFLUX_DATA_PATH=/var/lib/coreflux.

sudo systemctl status coreflux-broker
sudo systemctl restart coreflux-broker
sudo journalctl -u coreflux-broker -f

To add startup flags (for example --project), override the unit:

sudo systemctl edit coreflux-broker

[Service]
ExecStart=
ExecStart=/opt/coreflux-broker/CorefluxMQTTBroker --project https://github.com/org/my-iot-project.git --branch main

Then sudo systemctl daemon-reload && sudo systemctl restart coreflux-broker.

Ports below 1024

The service runs as the unprivileged user coreflux. The unit grants CAP_NET_BIND_SERVICE, so the broker can bind ports below 1024. A package upgrade replaces the unit file. Drop-in files under /etc/systemd/system/coreflux-broker.service.d/ are kept.An older package does not grant that capability. Add it in a drop-in:

sudo systemctl edit coreflux-broker

[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart coreflux-broker

A container, or a broker you start without the APT or DNF package, needs that capability on the process, or a port of 1024 or above.

Installation registers the service with sc create. For a portable zip, you can instead run as Administrator:

.\CorefluxMQTTBroker.exe --install
net start CorefluxMQTTBroker
Get-Service CorefluxMQTTBroker

To apply JSON once before the service owns the process, run the broker in the foreground with --config / --users, stop it, then install or start the service.

For a tarball (not APT/DNF), run as root:

sudo ./CorefluxMQTTBroker --install

That writes a systemd unit. For production, still prefer the Linux package from the Downloads page so upgrades and COREFLUX_DATA_PATH stay consistent.

Best practices

Set the data path in the environment

Use COREFLUX_DATA_PATH or CONFIG_PATH so --config and --users land in the same directory the broker uses at runtime. Docker images already set CONFIG_PATH=/etc/project.

Use force flags only when you mean to reset

-cf and -uf overwrite existing configuration. Back up first.

Ship LoT as a project

Load Actions, Models, Connectors, and Rules with --project, not with ad-hoc .lot file flags at process start.

Persist the data volume

Always mount a volume at /etc/project in Docker and Kubernetes. Without it, configuration, secrets, projects, the signed license (config/license.jws), and enrollment credentials disappear when the container is recreated. See Licensing and Enrollment.

Troubleshooting

Configuration not applied

Confirm COREFLUX_DATA_PATH / CONFIG_PATH matches the volume you mounted.
If files already exist in that directory, add --config-force / --users-force only if you intend to replace them.
Check logs for validation errors.

Port already in use

sudo lsof -i :1883

On Windows: netstat -ano | findstr :1883Stop the other listener or change the broker port in configuration.

Broker exits at start with code 78 (a LoT state file cannot be used)

Before it loads anything, the broker checks its LoT files in {data directory}/bin/ (actions.lot, models.lot, routes.lot, rules.lot, project-entity-ownership.json, Python.Scripts). It exits with code 78 when it can’t write to bin/, can’t open one of these files for reading and writing, or can’t copy a file with an earlier name to its new name. It prints each file with the reason. It does not start empty, because a broker without its rules or actions would allow and run different things than you configured.

Read the message in the console or the log. It names every file the broker cannot use.
Give the user the broker runs as read and write access to those files. The container image runs as user 10001, so on a mounted volume run chown -R 10001 <volume path>.
If the broker should start without a file, move that file aside and start again.

Permission denied on Linux

The package service user is coreflux, with state under /var/lib/coreflux. The service user needs read access to certificates and write access to the data directory.If the broker cannot bind a port below 1024, the process is missing CAP_NET_BIND_SERVICE. Current APT and DNF units grant it. On an older package, add the drop-in under Ports below 1024. A container or a manual run needs that capability, or a port of 1024 or above.

Next Steps

Broker Configuration

Ports, TLS, sessions, ops, and every JSON field.

Licensing and Enrollment

Activation codes, signed licenses, enrollment, and GET /license.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Coreflux Portal

Using AI with Coreflux

Product Updates

Configure the broker before it starts

Command-line options

Configuration

Projects and licenses

Other options

Basic usage

Starting with configuration files

Force overwrite existing configuration

Loading a project at startup

Configuration files

Broker configuration (JSON)

Users configuration (JSON)

Container deployment

Service installation

Ports below 1024

Best practices

Troubleshooting

Next Steps

Broker Configuration

Licensing and Enrollment

​Configure the broker before it starts

​Command-line options

​Configuration

​Projects and licenses

​Other options

​Basic usage

​Starting with configuration files

​Force overwrite existing configuration

​Loading a project at startup

​Configuration files

​Broker configuration (JSON)

​Users configuration (JSON)

​Container deployment

​Service installation

​Ports below 1024

​Best practices

​Troubleshooting

​Next Steps

Broker Configuration

Licensing and Enrollment

Configure the broker before it starts

Command-line options

Configuration

Projects and licenses

Other options

Basic usage

Starting with configuration files

Force overwrite existing configuration

Loading a project at startup

Configuration files

Broker configuration (JSON)

Users configuration (JSON)

Container deployment

Service installation

Ports below 1024

Best practices

Troubleshooting

Next Steps