Install HotLoop Gateway 4.23.2 with Helm
HotLoop Gateway 4.23.2 ships as a container image for amd64 and arm64, about 37 MB on amd64 and 35 MB on arm64, and a Helm chart. Both pull with no login. It keeps the names it shipped under through 4.17.0, image ghcr.io/hotloop-io/hotloop and chart hotloop, so nobody running it has to change a thing. Already running an older release? Don’t install over it. Upgrading has the path from 4.17.0, which is a plain helm upgrade, and the paths from 4.16.0 and 4.3.1, which go in hops.
Two ways to run it for real: the Helm chart on any Kubernetes, k3s included, and Podman Quadlet on a box that isn’t in a cluster, below. There’s no Docker or Compose path, on purpose, and a bare podman run from a shell that dies with the session isn’t an install.
helm repo add hotloop https://hotloop.io/hotloophelm repo updatehelm install hotloop hotloop/hotloop --version 4.23.2 \ --namespace hotloop --create-namespaceThat deploys the Gateway, plus TimescaleDB 2.30.1 beside it on a 20 Gi volume, keeping 90 days of history. The database is a setting, database.type: timescaledb is the default, postgresql runs plain PostgreSQL 17, and sqlite runs the Gateway on a file with no database pod at all, on one replica and local storage, never NFS. Moving between them later is a backup and a restore, because the new database starts empty. A box that already holds PostgreSQL 16 data moves to 17 on its next upgrade without you running anything, so read how that goes before you touch a running plant. The chart generates the database password, the MCP token, and an admin password into the release Secret, and reuses them on every upgrade, so a helm upgrade never rotates a password out from under you or logs you out of your own plant.
Back up the key before you need it
Section titled “Back up the key before you need it”The chart also generates a second Secret, <release>-secret-key (hotloop-secret-key with the command above). It holds the key that encrypts every password HotLoop keeps for a device: an OPC UA, MQTT, HTTP, MTConnect, or UniFi password, HTTP, and MTConnect header values such as API keys, the password of each other MQTT broker discovery listens to, and the password of each historian target. The key is never in the database and never in a backup, so a dump that walks out the door on a laptop holds ciphertext, not the keys to the plant.
The chart keeps that Secret across upgrades, and keeps it through a helm uninstall too, because a database left on its volume is useless for its credentials without it. That also means the key is part of your data. Start the Gateway without it and every device with a sealed password stays down, retrying, with an error that names the key it needs. A backup restores only where that key is mounted, and --restore-from refuses it by name anywhere else.
So back the Secret up the way you back up the rest of the cluster’s secrets, and keep it somewhere other than next to your backups. A key sitting beside the backups it protects protects nothing.
Rendering the chart instead of installing it? Bring your own key. The key is generated by a lookup that only a real helm install or helm upgrade can do. Anything that runs helm template and applies the result gets a new key on every render, and the next sync locks every sealed password out. Make a key with hotloop gen-secret-key, put it in a Secret you manage under the key secret.key, and name that Secret in secretKey.existingSecret. Helm, Fleet, and the EmberNet App Store all install for real and don’t need this.
A credential written into a URL (mqtt://user:pass@host) or into free text stays in the clear. Put it in password. Device credentials has the full list of what gets encrypted.
Sign in
Section titled “Sign in”The user is admin. The install notes print the command that reads the password back:
kubectl -n hotloop get secret hotloop \ -o jsonpath='{.data.admin-password}' | base64 -dkubectl -n hotloop port-forward svc/hotloop 8080:8080Open http://localhost:8080. That admin account is a bootstrap, not a reset switch. Once it exists, changing auth.admin.password and upgrading does nothing, so a password somebody set in the UI never gets clobbered by the next deploy.
Now add a device, discover its tags, and try to write to one. You can’t. That’s on purpose. Every tag starts read-only and gets armed one at a time, and safety.allowWrites stays off until you decide this pod gets to move machinery. Nobody’s first day with HotLoop should end with a press doing something they didn’t ask for.
Box health and the host mount
Section titled “Box health and the host mount”The chart’s OPC UA server also serves this box’s own health (CPU, memory, disk, and real-time jitter when an agent writes the file) for the EmberNet dashboard, and it makes a login for the dashboard that can read tags and values and nothing else, its password kept in the Secret <release>-opcua-dashboard across upgrades. The mounts are on by default: the chart mounts the host’s root at /host and its /proc at /host/proc, both read-only, and adds no privilege. A cluster that enforces the restricted Pod Security profile refuses a hostPath, so there you set opcuaServer.dashboard.boxHealth.enabled: false for no device and no mounts, or opcuaServer.dashboard.boxHealth.hostMount: false to keep the device with the disk and CPU reading bad and saying what to mount. The Quadlet drop-in is deploy/quadlet/opcua-dashboard.conf.
What to set before a real plant sees it
Section titled “What to set before a real plant sees it”Put these in a values file and install with -f. Don’t lean on --set for anything you’ll need again at the next upgrade, because you won’t remember it and the upgrade won’t either.
| Value | Default | Why you’d touch it |
|---|---|---|
plant.name, plant.siteId |
HotLoop, empty |
What the plant is called on screens, in pages, and to other sites. |
global.timezone |
America/New_York |
Schedules, reports and shift changes run on it. It has to be a real zone name (America/Chicago, not CST), because a timezone that won’t load stops startup instead of quietly running on UTC. |
publicUrl |
empty | The address a phone on the plant Wi-Fi reaches HotLoop at. Without it, notifications have no link back and ntfy gets no Acknowledge button. |
safety.allowWrites |
false |
The master switch. Off, nothing writes to a machine, from anywhere. Turn it on once the deployment has been reviewed. |
safety.allowMcpWrites |
true |
Lets agents write through the same gate, on since 4.19.4. It follows the master switch: with safety.allowWrites off, nothing writes, agents included. Set it false and agents can still read the whole plant and never write. The charts always set an MCP token, so /mcp is never open. |
database.postgresql.persistence.size |
20Gi |
Your history lives here. Size it for your tag count and historian.retentionDays (90). |
logbook.retentionDays |
90 |
Days of entity state changes the logbook keeps. 0 keeps everything until the volume fills, and the Gateway warns you about it at start. |
secretKey.existingSecret |
empty | A Secret you manage holding the device password key. Leave it empty and the chart makes one. Set it if you render the chart with helm template. |
database.type |
timescaledb |
Which database the app runs on: timescaledb, postgresql or sqlite. A setting, not a different image. |
plant.latitude, plant.longitude |
empty | Where the plant is, in decimal degrees, so the sun is worked out on the box. Both or neither. |
edgePublish.queueMaxBytes |
67108864 |
The outage queue’s limit when you publish upstream over Sparkplug, 64 MiB. Past it the oldest readings are dropped and counted. 0 is unbounded, and a long enough outage then fills the volume. |
database.postgresql.enabled |
true |
Set false and fill in database.external to use your own PostgreSQL. With the TimescaleDB extension you get a hypertable, without it native partitioning. |
opcuaClient.persistence.enabled |
false |
Turn it on before you add a secured OPC UA device. Without it the client’s certificates have nowhere to survive a restart, and the device refuses to connect rather than make you re-approve trust on both ends after every redeploy. |
ingress |
off | Only if you want it reachable from outside the cluster by a name. |
Writes ship off, and that’s the point. Even with safety.allowWrites on, a tag is read-only until you arm it on its own, and every value is checked against the tag’s range, refused and never clamped. The write gate has every check, in order.
Podman Quadlet
Section titled “Podman Quadlet”For a box that isn’t in a cluster. Quadlet turns the containers into real systemd services: they start on boot with nobody logged in, restart when they die, and log to the journal. It needs Podman 5.0 or newer. Raspberry Pi OS Bookworm ships 4.3, which has no Quadlet at all, so a Pi wants Trixie or newer. Put the database volume on a USB SSD and not the SD card.
The units are in the gateway/ directory of the HotLoop repository, under deploy/quadlet/. Podman Quadlet explains each file.
sudo cp hotloop.network hotloop.container hotloop-db.container \ hotloop-db.volume hotloop-data.volume /etc/containers/systemd/
openssl rand -hex 24 | sudo podman secret create hotloop-db-password -sudo podman run --rm ghcr.io/hotloop-io/hotloop:stable gen-secret-key \ | sudo podman secret create hotloop-secret-key -printf '%s' 'a long admin password' \ | sudo podman run --rm -i ghcr.io/hotloop-io/hotloop:stable hash-password \ | sudo podman secret create hotloop-admin-password-hash -
sudo systemctl daemon-reloadsudo systemctl start hotloop.servicesudo systemctl status hotloop.service hotloop-db.servicecurl -s localhost:8080/api/statusThen open http://<this box>:8080 and log in as admin. The three secrets are the database password, the device password key (back it up somewhere that isn’t this box, for the same reason as above), and the bcrypt hash of the admin’s password, never the password itself. The unit keeps 90 days of history and follows :stable.
Plain PostgreSQL instead of TimescaleDB is the same unit with Environment=HOTLOOP_HISTORIAN_TIMESCALE=false added to hotloop.container. A SQLite file is the files in gateway/sqlite/ and nothing from the directory above, because they share unit names: hotloop.container and hotloop-data.volume, and two secrets, hotloop-secret-key and hotloop-admin-password-hash.
Turn Podman’s timer on once per box and the Gateway updates itself:
sudo systemctl enable --now podman-auto-update.timerThe database container does not follow :stable, on purpose, and an update that can’t start is rolled back. The :stable auto-update says what an update does, what a rollback cannot undo, and how to hold updates until you say. These are the units that were run for real: rootless under systemd, including an update that migrates and then can’t start and gets rolled back. It has since been run on bare metal (2026-11-17).
Add a device, discover its tags, and watch them come in. Protocols says how far each driver has been proven, including the two that were run on bare metal on 2026-11-17, S7comm and EtherNet/IP. If you run it under EmberCORE, EmberCORE finds it by itself and proxies it at the in-cluster address, no ingress needed.
Licensing
Section titled “Licensing”HotLoop Gateway is under the HotLoop Source License Agreement 1.0. It is free to use and source-available, not OSI open source. Home and lab use is free, and so is use by schools, nonprofits and government bodies for their own operations. See the License page and Using HotLoop in a business.