Installation

Install Coreflux

Most people should use Docker or Docker Compose for the broker and the Coreflux HUB. Native broker installs are in the Linux and Windows tabs. Just evaluating with nothing to install? Use the Cloud tab. The HUB desktop tab is the standalone app. Packages and desktop builds are on the Downloads page.

Coreflux runs as a single install. No separate databases or message queues—pick a method below and run it.

Every local install method uses the same defaults:

Setting	Value
Username	`root`
Password	`coreflux`

For a Cloud Trial, open the broker in Coreflux Fleet at portal.coreflux.org. The address and login are on that page.

~2 min if Docker is already installed — broker, HUB, or both.

The broker and Coreflux HUB are separate images. Pick the command that matches what you want to run. The HUB desktop app is in the HUB desktop tab.

When you open the web HUB, the browser can install it as an app that opens in its own window. Use the browser’s install control — often Install or Add to Home Screen. Browsers offer this on localhost and on HTTPS. The HUB desktop app is already installed and does not use this.

New to Docker? Install it from the official Docker install page, then confirm with docker --version before you continue. Images are on Docker Hub.

Broker only
HUB only
Broker + HUB

Start the broker. Docker fetches the latest image automatically:

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

MQTT is on localhost:1883. There is no HUB in this command — use HUB only or Broker + HUB, or the standalone HUB app.

Start the HUB and connect it to a broker that is already running:

docker run --pull=always -d --name coreflux_hub -p 3000:3000 -v hub-data:/opt/coreflux-hub/data coreflux/coreflux-hub:latest

Open http://localhost:3000. Click New Connection (or Connect on a saved one). If the broker is on the same machine, set Protocol mqtt://, Host host.docker.internal (Docker Desktop) or the host’s LAN IP, and Port 1883 — not localhost, because the HUB proxies MQTT from inside its container.

Create a shared network and start both containers in one command:

docker network create coreflux && docker run --pull=always -d --name coreflux_broker --network coreflux --network-alias broker -p 1883:1883 -p 5000:5000 -p 9100:9100 -v project-volume:/etc/project coreflux/coreflux-mqtt-broker:latest && docker run --pull=always -d --name coreflux_hub --network coreflux -p 3000:3000 -v hub-data:/opt/coreflux-hub/data coreflux/coreflux-hub:latest

Open the HUB at http://localhost:3000, click New Connection, and connect with Protocol mqtt://, Host broker, Port 1883 (or Protocol ws://, Host broker, Port 5000, Path mqtt). Skip docker network create coreflux && if the coreflux network already exists.

Port	Service	Description
`1883`	Broker	MQTT (unencrypted)
`5000`	Broker	WebSocket / HTTP API
`9100`	Broker	Operational endpoints: `/health`, `/ready`, `/info`, `/license`, `/metrics`
`3000`	HUB	Coreflux HUB

The broker’s MCP server has its own port, 6278. It’s off by default and isn’t published here. To reach it from outside the container, see Docker and Kubernetes.

Port 3000 serves the HUB over plain HTTP. Open it on localhost, or put it behind a reverse proxy that terminates TLS and open it over HTTPS. Browsers only allow clipboard access on HTTPS or localhost, so on current HUB versions the copy buttons fail when you open the HUB as http://<LAN IP>:3000. See Copy buttons don’t work under troubleshooting.

Command	Broker fields on New Connection
Broker + HUB	Protocol `mqtt://`, Host `broker`, Port `1883` (or `ws://`, Host `broker`, Port `5000`, Path `mqtt`)
HUB only	Protocol `mqtt://`, Host `host.docker.internal` if the broker is on the same machine, or the broker’s host address

The HUB proxies MQTT from inside Docker, so Host localhost does not reach a broker container.That’s it—Coreflux is now running locally. Confirm it works under Verify Installation below.

What does the broker command do?

Breaking the broker docker run down piece by piece:

--pull=always — always fetch the latest image before starting, so you never run a stale version.
-d — runs the container detached (in the background), so your terminal stays free.
--name coreflux_broker — names the container so you can reference it later (for example docker logs coreflux_broker).
-p 1883:1883 -p 5000:5000 -p 9100:9100 — each -p host:container maps a port on your machine to the same port inside the container. See the port table above for what each one is for.
-v project-volume:/etc/project — mounts a named volume so your project (LoT, connectors, configuration) persists across restarts and image updates.
coreflux/coreflux-mqtt-broker:latest — the broker image, pulled from Docker Hub. The HUB image is coreflux/coreflux-hub:latest.

TLS/SSL Ports (when using certificates)

If you configure TLS certificates, expose these additional broker ports (8883 and 443):

docker run --pull=always -d --name coreflux_broker -p 1883:1883 -p 5000:5000 -p 9100:9100 -p 8883:8883 -p 443:443 -v project-volume:/etc/project coreflux/coreflux-mqtt-broker:latest

Port	Protocol	Description
`8883`	TCP/TLS	MQTT over TLS
`443`	WSS	WebSocket / HTTP API over TLS

See Broker Configuration for TLS setup.

~3 min if Docker is already installed — broker and HUB on one network.

Docker Compose starts the broker and the Coreflux HUB as two services on a shared network. Use the full profile to run both, or start either service alone. The HUB desktop app is in the HUB desktop tab. The web HUB can be installed from the browser as its own window — same install control as in the Docker tab (localhost or HTTPS).Create a directory, then add docker-compose.yml:

    # Coreflux — Broker + Hub deployment
    #
    # Profiles:
    #   full   -> broker + hub, on the same network
    #   broker -> broker only
    #   hub    -> hub only
    #
    # Usage:
    #   docker compose --profile full up    # broker + hub
    #   docker compose --profile broker up  # broker only
    #   docker compose --profile hub up     # hub only

    services:
      broker:
        image: coreflux/coreflux-mqtt-broker:latest
        profiles: [full, broker]
        container_name: coreflux-broker
        restart: unless-stopped
        ports:
          - "1883:1883"   # MQTT (plain TCP)
          - "8883:8883"   # MQTT over TLS
          - "5000:5000"   # WebSocket transport / HTTP API
          - "443:443"   # WebSocket / HTTP API over TLS
          - "9100:9100"   # Operational endpoints: /health /ready /info /license /metrics
        volumes:
          # Persists everything under /etc/project (signed license, enrollment,
          # encrypted config, connectors, actions, models, rules, logs, stats, projects).
          - broker-data:/etc/project
        # The published image has no shell, so a shell-based
        # healthcheck cannot run inside the container. Check health externally
        # via HTTP GET http://localhost:9100/health.
        healthcheck:
          disable: true

      hub:
        image: coreflux/coreflux-hub:latest
        profiles: [full, hub]
        container_name: coreflux-hub
        restart: unless-stopped
        ports:
          - "3000:3000"   # Web UI + API + MQTT WebSocket proxy (plain HTTP)
        volumes:
          # Persists writable Hub state (e.g. theme-media uploads).
          - hub-data:/opt/coreflux-hub/data
        # environment:
        #   - HUB_DEFAULT_CONNECTION_HOST=broker
        #   - HUB_DEFAULT_CONNECTION_PROTOCOL=mqtt
        #   - HUB_DEFAULT_CONNECTION_PORT=1883
        #
        # Those variables pre-fill New Connection in the web HUB. They do not
        # save a connection. Because the HUB proxies the MQTT connection
        # server-side, use the broker service name (not "localhost"):
        #   mqtt://broker:1883      (plain MQTT)
        #   ws://broker:5000/mqtt   (MQTT over WebSocket)

    volumes:
      broker-data:
      hub-data:

    # Both services attach to this network and resolve each other by service
    # name ("broker", "hub").
    networks:
      default:
        name: coreflux

Then start the stack:

Broker + HUB
Broker only
HUB only

From the directory that contains docker-compose.yml:

docker compose --profile full up -d

Open the HUB at http://localhost:3000. Click New Connection and set Protocol mqtt://, Host broker, Port 1883 — the HUB proxies MQTT from inside Docker, so Host localhost does not reach the broker container.

Start just the broker:

docker compose --profile broker up -d

MQTT is on localhost:1883. There is no HUB in this profile.

Start just the HUB (the broker must already be reachable on the coreflux network, or you will connect to a remote broker from the UI):

docker compose --profile hub up -d

Open the HUB at http://localhost:3000, click New Connection, and enter the broker Host, Protocol, and Port on the login screen.

Command	Starts
`docker compose --profile full up`	broker + HUB
`docker compose --profile broker up`	broker only
`docker compose --profile hub up`	HUB only

Port	Service	Description
`1883`	Broker	MQTT (unencrypted)
`8883`	Broker	MQTT over TLS
`5000`	Broker	WebSocket / HTTP API
`443`	Broker	WebSocket / HTTP API over TLS
`9100`	Broker	Operational endpoints: `/health`, `/ready`, `/info`, `/license`, `/metrics`
`3000`	HUB	Coreflux HUB

The broker’s MCP server has its own port, 6278. It’s off by default and isn’t published here. To reach it from outside the container, see Docker and Kubernetes.

The HUB talks to the broker from inside Docker. On New Connection, set Host to the Compose service name (broker) — Protocol mqtt:// and Port 1883, or Protocol ws://, Port 5000, and Path mqtt. Do not use Host localhost.

That’s it—Coreflux is running locally. Confirm it works under Verify Installation below.

Check broker health

The broker image has no shell, so Compose cannot run a healthcheck inside the container. Probe the operational endpoints from the broker host:

curl http://localhost:9100/health
curl http://localhost:9100/ready
curl http://localhost:9100/info

/health answers while the process is up. /ready stays unavailable until the broker is accepting MQTT connections. /info returns version, uptime, and the listener ports.

Named volumes

broker-data persists broker configuration, connectors, actions, models, rules, logs, and projects under /etc/project. hub-data persists HUB state such as theme-media uploads. Stopping or recreating containers does not delete these volumes.

Stop or remove the stack

docker compose down

Add -v only if you also want to delete the named volumes (this wipes broker and HUB data).

~10 min — broker installed from native packages and running as a systemd service.

Install the MQTT broker with your distribution’s package manager. Get the packages from the Downloads page. The steps below add the repository for Debian-based systems (APT) and RHEL-compatible systems (DNF).

Debian & Ubuntu (APT)
RPM (dnf)

APT is the package manager on Debian, Ubuntu, and Debian-based distributions—including Raspberry Pi OS. The package manager picks the right architecture (x64 or ARM64) for your machine.

OS	Codename
Ubuntu 22.04	`jammy`
Ubuntu 24.04	`noble`
Debian 12	`bookworm`
Debian 13	`trixie`

On Raspberry Pi OS, use the codename that matches your release (for example bookworm on Pi OS based on Debian 12, noble on releases based on Ubuntu 24.04).

Check your distribution codename

Run lsb_release -a and note the Codename line—you will use it in the next step.

lsb_release -a

Example output on Ubuntu 24.04:

Codename:       noble

Install the signing key

Download Coreflux’s archive signing key into /usr/share/keyrings:

sudo mkdir -p /usr/share/keyrings

curl -fsSL https://packages.coreflux.org/keys/coreflux-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/coreflux-archive-keyring.gpg >/dev/null

sudo chmod 0644 /usr/share/keyrings/coreflux-archive-keyring.gpg

Add the APT source

Run only the command that matches your codename. Each command writes /etc/apt/sources.list.d/coreflux.list.

Ubuntu 22.04 (jammy)
Ubuntu 24.04 (noble)
Debian 12 (bookworm)
Debian 13 (trixie)

echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/ubuntu jammy main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list

echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/ubuntu noble main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list

echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/debian bookworm main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list

echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/debian trixie main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list

Install coreflux-broker

Refresh package lists and install the broker package:

sudo apt update
sudo apt install coreflux-broker

Optional — list available versions before installing:

apt-cache policy coreflux-broker

Confirm the service is running

The package registers and starts coreflux-broker as a systemd service:

systemctl status coreflux-broker.service

active (running) means Coreflux is up. MQTT listens on port 1883 by default.

That’s it—the broker is installed under /opt/coreflux-broker and managed by systemd. Confirm it works under Verify Installation below. For the HUB, use the HUB desktop tab or run the HUB container from the Docker tab.

Verify the signing key (optional)

The key UID should show Coreflux Portugal S.A. Package Signing with email packages@coreflux.org:

gpg --no-default-keyring \
  --keyring /usr/share/keyrings/coreflux-archive-keyring.gpg \
  --list-keys --with-fingerprint

Manage the service

sudo systemctl stop coreflux-broker
sudo systemctl start coreflux-broker
sudo systemctl restart coreflux-broker
sudo journalctl -u coreflux-broker -f

Use dnf on RHEL-compatible distributions—RHEL, Rocky Linux, AlmaLinux, and CentOS Stream. The repository uses $releasever and $basearch, so one repo file covers your EL version and CPU architecture (x86_64 or aarch64).

OS family	`$releasever`
EL 8 (RHEL / Rocky / Alma / CentOS Stream 8)	`8`
EL 9 (RHEL / Rocky / Alma / CentOS Stream 9)	`9`
EL 10 (RHEL / Rocky / Alma / CentOS Stream 10)	`10`

Import the signing key

sudo rpm --import https://packages.coreflux.org/keys/coreflux.asc

Add the repository

Create /etc/yum.repos.d/coreflux.repo:

printf '%s\n' \
  '[coreflux]' \
  'name=Coreflux stable (GA)' \
  'baseurl=https://packages.coreflux.org/rpm/el/$releasever/$basearch' \
  'enabled=1' \
  'gpgcheck=1' \
  'repo_gpgcheck=1' \
  'gpgkey=https://packages.coreflux.org/keys/coreflux.asc' \
  | sudo tee /etc/yum.repos.d/coreflux.repo

Install coreflux-broker

Refresh the package cache and install the broker:

sudo dnf makecache --refresh
sudo dnf install coreflux-broker

Optional — list available versions before installing:

dnf list --showduplicates coreflux-broker

Confirm the service is running

The package registers and starts coreflux-broker as a systemd service:

systemctl status coreflux-broker.service

active (running) means Coreflux is up. MQTT listens on port 1883 by default.

Manage the service

sudo systemctl stop coreflux-broker
sudo systemctl start coreflux-broker
sudo systemctl restart coreflux-broker
sudo journalctl -u coreflux-broker -f

~10 min — broker running as a Windows service.

Download and install Coreflux, then register it as a Windows service using the native sc tool.

Download the Windows package from the Downloads page
Extract the zip file to your preferred location (e.g., C:\Coreflux)
Open Command Prompt as Administrator and run:

sc create CorefluxBroker binPath= "C:\Coreflux\CorefluxMQTTBroker.exe" start= auto DisplayName= "Coreflux MQTT Broker"
sc description CorefluxBroker "Coreflux MQTT Broker Service"
sc start CorefluxBroker

That’s it—the service is now registered, set to start automatically on boot, and running, so Coreflux is ready to use. For the HUB, use the HUB desktop tab or run the HUB container from the Docker tab.

Manage the service

Use these native Windows commands to control the service:

sc stop CorefluxBroker
sc start CorefluxBroker
sc query CorefluxBroker

You can also manage it from Services (services.msc) in Windows.

Uninstall the service

Stop and remove the service with:

sc stop CorefluxBroker
sc delete CorefluxBroker

~2 min — no Docker required for the HUB.

The standalone HUB is a desktop application for Windows x64, Linux x64, and Linux ARM64. It does not require a broker on the same machine.

Download

Download the HUB for your platform from the Downloads page.

Run

Run the executable — the HUB window opens immediately.

Connect

Click New Connection. If the broker is on this machine, set Protocol mqtt://, Host localhost, Port 1883, then enter the default credentials and click Connect.

After this first install, the desktop app updates itself. See Update the HUB desktop app.

Verify Installation

The quickest visual check is the Coreflux HUB in your browser. You can also confirm directly by connecting an MQTT client and seeing Coreflux’s system topics—that’s how the broker is actually used. Use the default credentials from the top of the page. For a Cloud Trial, use the address and login in Coreflux Fleet.

Coreflux HUB
MQTT Client

Open the HUB

Open the HUB for your install. For a Cloud Trial, open it from Coreflux Fleet in the portal. For Docker or Docker Compose, use http://localhost:3000. For the HUB desktop app, the window opens on its own.

Coreflux HUB login card listing local connections with Coreflux or MQTT broker badges, online status, identity, and Connect buttons, plus All and Starred filters and a New Connection button — Coreflux HUB — choose a stored connection or click New Connection

Choose or create a connection

The login screen lists stored connections. Click Connect on a saved one, or click New Connection to add a broker.Fill in the broker fields, then enter the default credentials and click Connect. For a Cloud Trial, use the login shown in Coreflux Fleet. Optionally click Save connection so the HUB remembers this broker next time.

Install	Protocol	Host	Port	Path
Docker / Compose (broker + HUB)	`mqtt://`	`broker`	`1883`	—
Docker / Compose (WebSocket)	`ws://`	`broker`	`5000`	`mqtt`
HUB desktop, broker on this machine	`mqtt://`	`localhost`	`1883`	—
HUB-only container, broker on the host	`mqtt://`	`host.docker.internal`	`1883`	—

Coreflux HUB New Connection form with Local Hub, ws:// localhost port 5000 path mqtt, username root, Save connection, and Connect — New Connection — name the broker, set protocol, host, and port, then Connect

Confirm the dashboard loaded

After a successful login, you should see the HUB home screen with the bottom navigation bar.

Coreflux HUB dashboard with Start here pointing to the first navigation icon — Coreflux HUB after login — start from the first icon in the navigation bar

The status bar shows connector count and license info—the broker is reachable from the HUB.

Browse MQTT data

Select MQTT → Data Viewer. Expand $SYS/Coreflux in the Topic Tree—you should see broker topics such as Config, Version, and Resources updating live.

Coreflux HUB Data Viewer with Publish panel, Topic Tree, and tracked topic details — Data Viewer — Topic Tree, Publish panel, and live topic values

Open MQTT Explorer

Download MQTT Explorer or use any MQTT client of your choice.

Connect to the Broker

Create a new connection with these settings:

Setting	Value
Host	`localhost`, or the endpoint shown in Coreflux Fleet for a Cloud Trial
Port	`1883` (local Docker or Compose) or 8883 with MQTTS (Cloud Trial)
Username / Password	The default credentials above, or the login shown in Coreflux Fleet

Check System Topics

Subscribe to $SYS/# to see broker status messages. If you see topics such as $SYS/Coreflux/Version, the broker is running correctly.

You should see Coreflux system topics under $SYS/Coreflux/.

If verification fails

Pick the symptom that matches your setup:

All Versions — Broker isn't running or won't accept connections

If you can’t connect, confirm the broker is actually up using the tooling for your install method.For a Docker install, inspect the container:

# Is the container running?
docker ps

# View broker logs (live)
docker logs -f coreflux_broker

# View HUB logs (if you started the HUB container)
docker logs -f coreflux_hub

# Restart the container
docker restart coreflux_broker

For Docker Compose, use docker compose ps and docker compose logs -f from the directory that contains docker-compose.yml. The broker container is named coreflux-broker.For a service install, check the service status: sudo systemctl status coreflux-broker (Linux package install) or sc query CorefluxBroker (Windows).

Copy buttons don't work in the HUB

Symptom: copy buttons in a Docker or Docker Compose HUB do nothing, and nothing lands on the clipboard. This happens when you open the HUB over plain HTTP on a LAN IP or host name, for example http://192.168.1.20:3000.Cause: browsers only give pages clipboard access in a secure context, which means HTTPS or localhost. Current HUB versions have no fallback for plain HTTP.Fix: serve the HUB over HTTPS through a reverse proxy that terminates TLS (for example nginx, Caddy, or Traefik) and open the https:// address. On the HUB’s own machine, open http://localhost:3000 instead. Until then, select the text and copy it with the keyboard. The desktop app is not affected.

All Versions — localhost doesn't load the HUB

Symptom: the HUB loads in some environments but not in a Docker-in-VM or remote setup.Fix: use the host’s actual address instead of localhost.

Docker Only — Docker daemon not running

Symptom: the command errors with “cannot connect to the Docker daemon”.Fix: start Docker Desktop (or the Docker service) and run the command again.

Docker Only — Port already in use

Symptom: an error binding a port, e.g. 3000 or 1883 is already allocated.Fix: stop the process using that port, or remap the host side of the port (for example -p 1884:1883 on Docker, or change the left-hand port in docker-compose.yml).

Docker Only — Container exits immediately

Symptom: docker ps shows nothing after you start the broker.Fix: run docker logs coreflux_broker to see why it exited. For Compose, run docker compose logs broker from the directory that contains docker-compose.yml.

Docker Compose — HUB cannot reach the broker

Symptom: the HUB at http://localhost:3000 fails to connect when Host is localhost, or shows Broker isn’t reachable.Fix: the HUB proxies MQTT from inside Docker. On New Connection, set Host to broker, Protocol mqtt://, Port 1883 (or Protocol ws://, Port 5000, Path mqtt).

Cloud Only — Can't connect to your trial

Symptom: the HUB or an MQTT client fails to connect right after you start the trial.Fix: wait until Coreflux Fleet shows the broker as ready, then open the HUB from that page. Use the endpoint and login shown there for MQTT clients.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Coreflux Portal

Using AI with Coreflux

Product Updates

Install Coreflux

Verify Installation

If verification fails

Next Steps

Getting Started

VS Code Extension

​Install Coreflux

​Verify Installation

​If verification fails

​Next Steps

Getting Started

VS Code Extension

Install Coreflux

Verify Installation

If verification fails

Next Steps