Installation

Install Coreflux

Most people should use Docker or Docker Compose for the broker and the Coreflux HUB. Just evaluating with nothing to install? Use the Cloud Trial tab. The HUB desktop tab is the standalone app. Native broker binaries and cloud droplets are in the remaining tabs.

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

Setting	Value
Username	`root`
Password	`coreflux`

~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.

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 Enter 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	`/health`, `/ready`, `/info`, `/metrics`
`3000`	HUB	Coreflux HUB

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, routes, 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 5443):

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

Port	Protocol	Description
`8883`	TCP/TLS	MQTT over TLS
`5443`	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.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
          - "5443:5443"   # WebSocket / HTTP API over TLS
          - "9100:9100"   # Operational endpoints: /health /ready /info /metrics
        volumes:
          # Persists everything under /etc/project/Coreflux (encrypted config,
          # routes, 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:
        #   - GROQ_API_KEY=...   # optional, only for the Hub AI assistant feature
        #
        # NOTE: the Hub has no broker-connection env var. You choose the broker
        # from the Hub UI. Because the Hub proxies the MQTT connection
        # server-side, enter the broker's 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
`5443`	Broker	WebSocket / HTTP API over TLS
`9100`	Broker	`/health`, `/ready`, `/info`, `/metrics`
`3000`	HUB	Coreflux HUB

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 it from the host:

curl http://localhost:9100/health

Named volumes

broker-data persists broker configuration, routes, 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).

~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 executable for your platform from coreflux.org > Start Free.

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.

~5 min, nothing to install — hosted broker and HUB in your browser.

Get a hosted Coreflux instance without installing anything. Request a trial on the Coreflux website, and you will receive an email with a URL (used for both the Coreflux HUB and the MQTT broker) and login credentials.

Request a trial

Go to coreflux.org and submit a trial request using the form on the site.

Check your email

When your environment is ready, Coreflux sends an email with:

Item	What you use it for
URL	Open the HUB in your browser and connect MQTT clients to the same host (broker and HUB share one address)
Credentials	Username and password for the HUB login screen and for MQTT clients

The broker may take up to 60 seconds to be fully available after you receive the email. If the HUB or MQTT connection fails immediately, wait briefly and try again.

Open the HUB

Paste the URL from the email into your browser. Click New Connection (or Enter on a saved connection), enter your username and password, and click Connect. Use the broker host from the email if it is pre-filled differently than your trial URL.

Coreflux HUB New Connection form with Local Hub, ws:// localhost port 5000 path mqtt, username root, and Connect — Coreflux HUB — New Connection with broker host, protocol, port, and credentials

From the HUB you can deploy LoT Actions, browse MQTT topics in the Data Viewer, and manage Routes—same experience as a local Docker install.

Connect MQTT clients

Use the same host as the URL in your email (not localhost). For MQTT Explorer and other desktop clients:

Setting	Value
Protocol	MQTTS (MQTT over TLS)
Port	8883
Username / Password	From your trial email

In MQTT Explorer specifically: enable Encryption, and disable Validate certificate (the trial broker uses a certificate that desktop tools may not trust by default).

That’s it—your trial is live and ready to use, with the broker and HUB already running on the URL from your email.

HUB remote access: If your browser blocks the HUB page, allow unsecure access (or proceed past the certificate warning) for the trial URL. Managed trial environments often use certificates that browsers flag on first visit.

After the HUB loads, continue with Getting Started using the Coreflux HUB tabs—your trial already includes the HUB and broker.

~10 min (plus a DigitalOcean account) — production-ready broker running in the cloud.

Deploy Coreflux in seconds with our 1-Click Droplet on DigitalOcean Marketplace. This is the fastest way to get a production-ready broker running in the cloud.

Click Deploy

Click the button above or visit the Coreflux Marketplace page.

Choose Your Droplet Size

Select a plan based on your needs:

Plan	RAM	vCPUs	Best For
Basic	1 GB	1	Development, testing
Basic	2 GB	1	Small deployments
Basic	4 GB	2	Recommended ✓

We recommend the 4 GB / 2 vCPU droplet for most use cases. It provides headroom for LoT Actions, multiple routes, and moderate message throughput.

Select Region

Choose a datacenter close to your devices for lower latency.

Create Droplet

Click Create Droplet and wait ~60 seconds for deployment.

Connect to Your Broker

Once the droplet is ready, use the public IP address to connect:

Setting	Value
Host	`<your-droplet-ip>`
Port	`1883`
Username	`root`
Password	`coreflux`

That’s it—your droplet is now running Coreflux and ready to use.

Change the default password immediately after first login. SSH into your droplet and update the broker configuration.

Exposed Ports

The Coreflux droplet exposes the following ports by default:

Port	Protocol	Description
`1883`	TCP	MQTT (unencrypted)
`8883`	TCP/TLS	MQTT over TLS
`5000`	WebSocket	WebSocket connections
`443`	WSS	WebSocket over TLS

Configure your DigitalOcean firewall to restrict access as needed.

SSH Access

To manage your Coreflux installation via SSH:

ssh root@<your-droplet-ip>

The Coreflux broker runs as a systemd service. Common commands:

# Check status
sudo systemctl status coreflux

# Restart broker
sudo systemctl restart coreflux

# View logs
sudo journalctl -u coreflux -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 zip from coreflux.org > Start Free
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

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

Install the MQTT broker with your distribution’s package manager. Packages are published at packages.coreflux.org 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

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 (or your trial email).

Coreflux HUB
MQTT Client

Open the HUB

Open your environment URL in the browser—for a Cloud Trial, use the address from your email; for Docker or Docker Compose, use http://localhost:3000. For the HUB desktop app, the window opens on its own.

Coreflux HUB login screen with stored connections, Enter buttons, and New Connection — Coreflux HUB — choose a stored connection or click New Connection

Choose or create a connection

The login screen lists stored connections. Click Enter on a saved one, or click New Connection to add a broker.Fill in the broker fields, then enter the default credentials (or your trial email) and click Connect. 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 route 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 your trial URL host for Cloud Trial)
Port	`1883` (local Docker or Compose) or 8883 with MQTTS (Cloud Trial)
Username / Password	The default credentials above

For Cloud Trial, use MQTTS on port 8883, enable Encryption, and disable Validate certificate in MQTT Explorer.

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), sudo systemctl status coreflux (DigitalOcean droplet), or sc query CorefluxBroker (Windows).

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 receive your trial email.Fix: wait up to 60 seconds for the broker to become available, then retry. In the browser, allow unsecure access (or proceed past the certificate warning) for the trial URL. In MQTT Explorer, use MQTTS on port 8883, enable Encryption, and disable Validate certificate.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

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