Getting Started

Quick Start (Linux)

RelayQ ships as one static binary per architecture, packaged as a tarball with an install script, a systemd unit, and a reference config. Pick the package for your device:

Full is the edge gateway build. Lite drops TLS and WebSocket for constrained devices behind a trusted network or a TLS-terminating gateway. Both are built from the same source and have no runtime dependencies: no libc requirement, no package manager, nothing else to install. The commands below use amd64; substitute the package name for your architecture.

# Download for your platform (requires API key)
wget -O relayqdev-3.0.0-rc.2.1208-linux-amd64.tar.gz \
  "https://relayq.dev/downloads/relayqdev-3.0.0-rc.2.1208-linux-amd64.tar.gz?key=<your-key>"

# Verify integrity
wget -O relayqdev-3.0.0-rc.2.1208-linux-amd64.tar.gz.sha256 \
  "https://relayq.dev/downloads/relayqdev-3.0.0-rc.2.1208-linux-amd64.tar.gz.sha256?key=<your-key>"
sha256sum -c relayqdev-3.0.0-rc.2.1208-linux-amd64.tar.gz.sha256

# Extract and install
tar xzf relayqdev-3.0.0-rc.2.1208-linux-amd64.tar.gz
cd relayqdev-3.0.0-rc.2.1208-linux-amd64
sudo ./install.sh

# Start
sudo systemctl enable --now relayqdev

# Verify
curl http://localhost:8884/health
# Output: ok

What a healthy start looks like

Running the binary in the foreground shows exactly this (captured from the shipped current build; hardware-specific lines trimmed):

$ relayqdev serve --config /etc/relayqdev/relayqdev.conf
[INFO] Hardware fingerprint: v1:d2b2d3d3fe5fb247...
[INFO] binary integrity check passed

  ██████╗ ███████╗██╗      █████╗ ██╗   ██╗ ██████╗
  ██╔══██╗██╔════╝██║     ██╔══██╗╚██╗ ██╔╝██╔═══██╗
  ██████╔╝█████╗  ██║     ███████║ ╚████╔╝ ██║   ██║
  ██╔══██╗██╔══╝  ██║     ██╔══██║  ╚██╔╝  ██║▄▄ ██║
  ██║  ██║███████╗███████╗██║  ██║   ██║   ╚██████╔╝
  ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝  ╚═╝   ╚═╝    ╚══▀▀═╝

  RelayQ v3.0.0-rc.2.1208  *  Deterministic Industrial Edge Runtime
  Copyright (c) 2026 Precocity Research Limited. All rights reserved.
  Licensed under the Elastic License 2.0 (ELv2)

  ┌───────────────────────────────────────────────────────┐
  │  Listening      0.0.0.0:1883                          │
  │  Protocol       MQTT 3.1.1 + 5.0 (full conformance)   │
  │  Config         /etc/relayqdev/relayqdev.conf         │
  │  Log level      info                                  │
  │  TLS listener   not configured                        │
  │  Max conns      100000                                │
  │  Persistence    off                                   │
  ├───────────────────────────────────────────────────────┤
  │  Build variant  full                                  │
  │  Build mode     release                               │
  │  Features       tls ws tui opcua modbus dnp3 health   │
  │                 rules historian sparkplug ha bridge   │
  │                 bacnet mqtt5 licensing                │
  │  Target         x86_64-unknown-linux-musl             │
  └───────────────────────────────────────────────────────┘

[INFO] kernel primitives initialised
[INFO] 1 capability contract(s) registered with kernel
[INFO] listening on [::]:1883
[INFO] kernel: MQTT broker workload activated
[INFO] [startup] broker_init: 2ms
[INFO] [startup] total: 3ms
[INFO] kernel: protocol driver workloads registered
[INFO] health check listening on 0.0.0.0:8884

In Evaluation mode the log also notes the evaluation edition and the 24-hour runtime reminder before the banner. Startup to accepting connections is measured by the runtime itself and printed on every start (the [startup] lines above).

What install.sh does: creates a relayqdev system user, installs the binary to /usr/local/bin/relayqdev, the config to /etc/relayqdev/relayqdev.conf, state under /var/lib/relayqdev/, and the relayqdev.service unit. Re-running it on an existing install keeps your config; sudo ./install.sh --clean backs it up and resets to defaults (TLS certs are preserved). uninstall.sh reverses it.

Useful once it is running:

sudo systemctl status relayqdev          # running?
sudo journalctl -u relayqdev -f          # live log
sudo systemctl reload relayqdev          # after editing /etc/relayqdev/relayqdev.conf

The binary verifies its own Ed25519 signature every time it starts and refuses to run if it has been modified after signing, so a tampered download fails fast rather than running. The .sha256 check above catches a corrupt or substituted download before you get that far.

RelayQ starts in Evaluation mode – full features, no license required. Evaluation mode runs for 24 hours per start, shutting down gracefully. Two further limits apply: 72 hours of cumulative runtime, and 30 days from the first run. When either is reached the runtime will not start again without a licence file.

Quick Start (Windows)

RelayQ ships a native Windows x86_64 build of the Full variant as a zip: the binary, a minimal trial config, and optional service install scripts. No installer, no admin rights needed to evaluate. This build is for the Windows machine or VM a site already has in its OT zone beside SCADA, DCS, OPC Classic servers and historians, and for Windows data-centre hosts; it is not offered for resource-constrained hardware, where the Linux ARM builds are the target (see where RelayQ runs).

# Download (requires API key) -- same location as the Linux packages
$v = "3.0.0-rc.2.1208"
Invoke-WebRequest "https://relayq.dev/downloads/relayqdev-$v-windows-amd64.zip?key=<your-key>" `
  -OutFile "relayqdev-$v-windows-amd64.zip"
Invoke-WebRequest "https://relayq.dev/downloads/relayqdev-$v-windows-amd64.zip.sha256?key=<your-key>" `
  -OutFile "relayqdev-$v-windows-amd64.zip.sha256"

# Verify integrity: the two hashes must match exactly
(Get-FileHash "relayqdev-$v-windows-amd64.zip" -Algorithm SHA256).Hash.ToLower()
(Get-Content "relayqdev-$v-windows-amd64.zip.sha256").Split(" ")[0]

# Extract and start in the foreground
Expand-Archive "relayqdev-$v-windows-amd64.zip" -DestinationPath .
cd "relayqdev-$v-windows-amd64"
.\setup-trial.ps1
.\relayqdev.exe --config relayqdev-trial.conf

# Verify (second window)
.\relayqdev.exe --version
curl.exe http://127.0.0.1:8884/health
# Output: ok

The same evaluation limits apply as on Linux. To run RelayQ as a Windows service instead, open PowerShell as Administrator inside the extracted folder and run powershell -ExecutionPolicy Bypass -File .\install.ps1 -SourceExe .\relayqdev.exe -RegisterService; uninstall.ps1 removes it again.

What differs on Windows

The Windows package is the same Full build with these differences, and nothing else:

• Full variant only; there is no Lite build for Windows.
• No memory locking: the runtime cannot pin its pages (mlockall is Unix only).
• Binary integrity uses the detached relayqdev.exe.rqis manifest beside the executable rather than the Linux trailer; the manifest must stay next to the exe.
• The admin API is the named pipe \\.\pipe\relayqdev-admin, not a Unix socket.
• The service is installed by the signed install.ps1, not systemd.
• The hardware fingerprint is derived from Windows identifiers, so a licence is per machine as on Linux and is not portable between a Windows and a Linux host.

Protocol translation, TLS, persistence, the rules engine and the out-of-memory guard are the same build as on Linux.

Before you run the .exe: what Windows will say, and what to check

The Windows binary is Authenticode-signed by Precocity Research Limited. Every release is signed through Microsoft’s Trusted Signing service with a publicly trusted certificate and an RFC 3161 timestamp. Windows can therefore identify the publisher and detect any change to the file after it left the build. Check the signature before you run anything:

# Expect Status "Valid" and a signer of CN=Precocity Research Limited
Get-AuthenticodeSignature .\relayqdev.exe | Format-List Status, SignerCertificate, TimeStamperCertificate

Or right-click relayqdev.exe, Properties, Digital Signatures. The signer must read Precocity Research Limited. If the tab is missing, or the name is anything else, or the status is not Valid, the file is not the one we shipped. Delete it.

The three PowerShell scripts in the zip (setup-trial.ps1, install.ps1, uninstall.ps1) carry the same signature. Under the default RemoteSigned policy, the first time you run one PowerShell asks “Do you want to run software from this untrusted publisher?” and names Precocity Research Limited. Answer R to run it once or A to trust the publisher for future scripts. An unsigned script would be refused outright, so the prompt is the signature working. If your policy is Restricted, scripts do not run at all: use powershell -ExecutionPolicy Bypass -File .\setup-trial.ps1, or simply mkdir data, certs, which is all that script does.

The signature does two things. It tells Windows and your endpoint tools who published the file, and it makes any byte-level change detectable. It does not guarantee silence from every scanner:

• SmartScreen may still show “Windows protected your PC” on early releases. SmartScreen scores a publisher by download history as well as by signature, and a new certificate starts with none. The dialog names the publisher: if it says Precocity Research Limited, it is the reputation warning, not a verdict on the file. If it says “Unknown publisher”, the file is not signed by us. Stop.
• Some antivirus products may still flag a new executable. A signed binary lets them attribute it to a publisher, which is what lets a false positive be resolved. If yours quarantines the exe, restore it, confirm the signature above is still Valid, and then add an exclusion for the extracted folder using your product’s own UI. Send us the release version and hash so we can file the false positive with that vendor.

Check the file, then decide, in this order:

1. Verify the SHA-256 before anything else. The hash printed by Get-FileHash must equal the one in the .sha256 file you downloaded. If they differ, delete the zip and do not run it; the download is corrupt or has been tampered with.
2. Verify the signature with the command above after extracting. Valid, and signed by Precocity Research Limited.
3. Only then unblock. Right-click the zip, Properties, tick Unblock, or run Unblock-File .\relayqdev-3.0.0-rc.2.1208-windows-amd64.zip before extracting. On a SmartScreen reputation dialog that names our publisher, “More info” then “Run anyway”.
4. Let RelayQ check itself. relayqdev.exe also verifies a signed integrity manifest (relayqdev.exe.rqis, shipped next to the binary) every time it starts and refuses to run if the executable or the manifest has been altered. That check is independent of the Windows signature and uses RelayQ’s own release key, so a binary modified after packaging fails both, whatever a scanner says.
5. Never bypass a warning for a file whose hash or signature does not match. Verification first, unblocking second, and only for a file you obtained from relayq.dev/downloads with your own key.

If your organisation’s endpoint policy allow-lists publishers, the certificate subject is CN=Precocity Research Limited, O=Precocity Research Limited, L=North Shore City, S=Auckland, C=NZ.

First Pub/Sub Test

# Terminal 1: Subscribe
mosquitto_sub -h localhost -t "sensor/temp" -v

# Terminal 2: Publish
mosquitto_pub -h localhost -t "sensor/temp" -m "22.5"

# Terminal 1 output:
# sensor/temp 22.5

Verify Installation

# Check version
relayqdev --version
# Output: relayq 3.0.0-rc.2.1208 (a1b2c3d) [full] x86_64-unknown-linux-musl release

# Health check
curl http://localhost:8884/health
# Output: ok

WebSocket Connection

Connect from a browser or WebSocket client on port 1883 – the runtime detects the WebSocket upgrade on the same listener (Full variant only):

// Browser example using MQTT.js
const client = mqtt.connect('ws://localhost:1883')
client.on('connect', () => {
  client.subscribe('sensor/#')
  client.publish('sensor/temp', '22.5')
})
client.on('message', (topic, msg) => {
  console.log(`${topic}: ${msg.toString()}`)
})

Evaluation vs Production

Evaluation mode is fully functional – no feature restrictions. A production licence removes the clock limits but is not unlimited: it is bound to one device’s hardware fingerprint (a mismatch refuses to start), sets the maximum connections, subscriptions per client and publish rate, enables a defined set of capabilities, and carries a support expiry date. After that date the runtime keeps running but reports support_expired on $SYS/broker/license/status, and updates and support stop until it is renewed.

Next Steps

• Installation Guide – full deployment guide with systemd, upgrade, rollback (licensed docs, API key required)
• Configuration Reference – all config keys
• Security Hardening – TLS, auth, ACL, audit chain