Version: Next

Installation

QUBIQ ships as a signed installer for each operating system. The installer places the application, registers it with the operating system's service manager so it starts on boot, opens the firewall for the ports you choose, and takes you to the first-run setup screen.

There is nothing to install alongside it. No database server, no message broker, no web server — and no Python. The Python runtime that powers scripting is bundled inside QUBIQ's own folder.

Before you start

Check system requirements.
Have administrator rights. QUBIQ installs as a machine-wide service on every platform, which is the only mode that makes sense for a plant: a login-start install would stop the moment the operator logged out, taking the historian and every device connection with it.
QUBIQ is 64-bit only. The Windows installer refuses a 32-bit host rather than installing cleanly and failing to start, which is far harder to diagnose.

Code signing

Installers are not yet code-signed. Windows SmartScreen and macOS Gatekeeper will show a one-time "unrecognised publisher" prompt — choose More info → Run anyway (Windows) or right-click → Open (macOS). Nothing else is affected.

Windows

Run QUBIQ-<version>-setup.exe.
Accept or change the install folder — C:\Program Files\QUBIQ.
Finish. The installer starts the service and opens http://localhost:8182.

It registers the Windows service with the Service Control Manager, sets it to Automatic start with a restart-on-failure policy, opens the firewall for ports 8182 and 8090, and grants the data directory only to SYSTEM and the local Administrators group.

Upgrading over a running installation is supported: the installer stops the service through the SCM and waits for it, rather than assuming. It also refuses to install over a newer version — the database schema guard would refuse to open app.db anyway, and failing before anything is replaced is easier to understand than failing on first boot with the old binary already gone.

qubiq.exe is hidden, and refuses to run on its own

Running the engine by hand boots the whole platform outside the service — a plant that dies with your session and never returns after a reboot, with nothing about the double-click to suggest it. So the installer hides the executable, and the binary itself refuses to start unless it was installed. Use the service, or qubiqctl.

Linux

Install the package for your distribution:

sudo apt install ./qubiq_<version>_amd64.deb      # Debian, Ubuntu
sudo dnf install ./qubiq-<version>.x86_64.rpm     # RHEL, Rocky, Fedora

The package unpacks the bundled Python runtime, creates a dedicated qubiq system account that owns the data directory, installs a systemd unit, and enables it:

systemctl status qubiq

Then open http://<host>:8182.

macOS

Run QUBIQ-<version>.pkg.
Follow the installer.
It registers a LaunchDaemon running as a dedicated _qubiq user, and starts it.

Then open http://localhost:8182.

Where things are installed

	Windows (all users)	Linux	macOS
Application	`C:\Program Files\QUBIQ`	`/opt/qubiq`	`/opt/qubiq`
Data directory	`C:\ProgramData\QUBIQ`	`/var/lib/qubiq`	`/Library/Application Support/QUBIQ`
Bundled Python	`…\QUBIQ\python`	`/opt/qubiq/python`	`/opt/qubiq/python`
Its bundled packages	`…\QUBIQ\python-packages-bundled`	`/opt/qubiq/python-packages-bundled`	`/opt/qubiq/python-packages-bundled`
Service unit	Windows service `QUBIQ`	`/lib/systemd/system/qubiq.service`	`/Library/LaunchDaemons/com.qubiq.plist`
Open-source notices	`…\QUBIQ\THIRD-PARTY-NOTICES.md`	`/usr/share/doc/qubiq/`	inside the app bundle

The installer pins the data directory with the QUBIQ_DATA_DIR environment variable, so a service account with no user profile still finds it.

Inside the data directory:

.env                JWT_SECRET and ENCRYPTION_KEY — generated on first boot
projects/           per-project view, script and asset trees
user-databases/     sandbox for user-created SQLite connections
python-packages/    admin-installed Python modules for the script sandbox
mibs/               uploaded SNMP vendor MIBs
log/                rotated diagnostic reports

The directory also holds the configuration database, encrypted at rest.

The directory is created with restrictive permissions — a locked ACL on Windows, owner-only on Unix — because it holds the configuration database, .env and every connection credential.

Back up .env separately

It holds ENCRYPTION_KEY. Lose it and the configuration database and every stored credential are unrecoverable — a backup of the data directory alone will not save you. → Backup & restore

Python is bundled — do not install your own

QUBIQ ships a private, version-pinned Python runtime inside its install folder, with the two things the platform needs already in it:

Bundled	For
Python runtime	Pipeline Python nodes and Gateway scripts
Transport library	How the worker reaches the platform
`ruff`	The in-editor Python linter

The installer points PYTHON_PATH at it. That runtime is not added to your system PATH, does not register as "the system Python", cannot collide with a Python you already have, and is removed when you uninstall.

So: scripting works out of the box. You do not need to install Python, create a virtual environment, or run pip install to get started.

To add extra modules for your scripts — pandas, a vendor SDK — use Settings → Script Sandbox → Add & install in the interface. Packages land in python-packages/ inside the data directory, which keeps them separate from the bundled runtime and means they survive a QUBIQ upgrade. → The script sandbox

If scripting is unavailable

QUBIQ boots degraded rather than failing: the interface works, connections poll, screens render — only Python script nodes and Gateway scripts fail. If that happens after an install, the bundled runtime did not land; reinstall rather than pointing PYTHON_PATH at a system Python.

Ports and the firewall

On Windows the installer adds firewall rules for two ports.

Port	Service	Opened by the installer	Notes
8182	Web interface and API	Yes	The port engineers and operators connect to.
8090	REST gateway — API-key data ingress/egress	Yes	The intended door for third-party systems. Remove the rule if nothing outside the host uses it.
8183	Telemetry WebSocket	No	The browser reaches it from the same origin as 8182, so it needs no rule of its own.

The internal message bus is not in this table and never will be: it binds to loopback on a random port, so there is nothing to open, firewall or authenticate. → The gateway | 8091 | Script gateway | Loopback | Never exposed. |

The internal message bus binds to loopback on a random port and is never opened.

TLS on 8090

Port 8090 carries API keys over the network. Enable TLS during setup, or put the gateway behind a TLS-terminating reverse proxy, before you issue keys to anything. → API keys

After installing

Open http://localhost:8182 and complete the first-run setup — QUBIQ ships with no default account, and the wizard is reachable only until you create the first one.
Point the historian at a QuestDB store → Historian configuration.
Point the audit journal at an external database → Audit journal.
Take a baseline backup → Backup & restore.

Managing the service

Day to day, use your platform's service manager, or the bundled qubiqctl control utility, which detects the installed service manager and delegates to it so shutdown is always graceful.

Linux / macOS
qubiqctl start | stop | restart | status

Windows (elevated)
qubiqctl.bat start | stop | restart | status

→ Services & system settings

Serving over HTTPS

Terminate TLS at QUBIQ or at a reverse proxy.

At QUBIQ — set in .env inside the data directory:

TLS_ENABLED=true
TLS_CERT_FILE=/etc/qubiq/tls/fullchain.pem
TLS_KEY_FILE=/etc/qubiq/tls/privkey.pem

Behind a proxy — proxy 8182 (HTTP + WebSocket upgrade) and 8183, and declare the proxy so client addresses are attributed correctly in the audit journal:

TRUSTED_PROXIES=10.0.0.0/8,192.168.0.0/16
ALLOWED_ORIGINS=https://qubiq.example.com
QUBIQ_COOKIE_SECURE=true

→ Environment variables

Upgrading

Run the new installer over the existing installation. It stops the service, replaces the application and the bundled runtime, and starts it again. It never touches the data directory or .env.

The database schema is migrated once at boot, before any service starts, so there is no separate migration step.

Take a backup first — schema migrations are not reversible.

Uninstalling

Use the platform's normal uninstall route: Add/Remove Programs, apt remove qubiq / dnf remove qubiq, or the macOS uninstall script.

The uninstaller stops and deregisters the service, removes the firewall rules and the bundled runtime, and asks whether to keep your data. The default is keep — the data directory holds the configuration database and the encryption key.

To remove everything, delete the data directory afterwards. Export a backup first if there is any chance you will want the configuration back.

→ First-run setup

Before you start​

Windows​

Linux​

macOS​

Where things are installed​

Python is bundled — do not install your own​

Ports and the firewall​

After installing​

Managing the service​

Serving over HTTPS​

Upgrading​

Uninstalling​

Next​