What's New

This manual documents QUBIQ 1.0.4. Capabilities that arrived during the 1.0 series carry a badge like this one New in 1.0.4 on the page that describes them, so you can tell at a glance whether something is available on the version you are running.

1.0.4

Errors are something a pipeline can act on. New in 1.0.4 Until now a failed node was logged and its branch stopped. Two features change that, and they compose:

• The Catch node receives every failure in its pipeline — or a chosen few — and hands it to whatever should report it: a Telegram message, a dead-letter table, a Link into one central error-handling pipeline. The message it emits carries not only the error but the payload that caused it, so a failure can be replayed rather than only announced.
• A per-node error output puts a second, red socket on any node. Wire it and that node's failure carries on down a branch of its own, so a cached value can be substituted and the rest of the flow still runs. Off by default; every saved pipeline renders exactly as before.

A lost administrator password is recoverable, and a console reset cannot be quiet. New in 1.0.4 qubiq admin reset-password at the server console prints a temporary password once, forces a change at next sign-in, and ends every session that account held. It is recorded three ways, one of which no one can dismiss. First-run setup is now genuinely one-shot: deleting the user table no longer reopens the public setup endpoint, which is the hole this replaces. → Console recovery

The database encryption key has an escape hatch. New in 1.0.4 qubiq db-key create prints a recovery key you write on paper. Without one, a changed service account or a rebuilt profile could leave app.db permanently unreadable — which needs no attacker, just an ordinary Tuesday. The key is also re-sealed on every boot so a service-account change stops being a data-loss event. → Console recovery

A backup will not be read by a build that would read it wrongly. New in 1.0.4 Archives carry a compatibility floor measured from what they actually contain, so an estate that never touched a newer feature keeps producing archives older builds accept. Two silent-corruption bugs went with it: a restore no longer turns disabled connections, disabled tags and suspended users back on. → Backup & restore

A script may not do what its caller could not. New in 1.0.4 Tag write levels now apply to system.tag.write, not just to a write from a screen; and a Gateway script started from a browser button runs with the caller's own capabilities rather than unclamped. The Script Sandbox page also says plainly, at the Install button, that a data library widens what scripts can reach — the sandbox stops mistakes, not a determined author. → The script sandbox

Handled faults have their own log level. New in 1.0.4 WARN sits between routine chatter and an outage, and is filterable. It also fixes a live bug: the log panel had been labelling every warn row RETRYING, telling its reader to expect an attempt that was never coming.

Two new API reference pages — every system.* and context.* member, with worked examples in both languages. → System API · Context API

An electrical symbol library. New in 1.0.4 529 electrical symbols across 24 categories — contacts, breakers, relays, logic gates, op-amps, MOSFETs, PLC ladder elements — join the 485 process symbols on the same canvas. 77 of them carry an operating state you can bind to a tag: a contact opens, a coil lights, a selector turns. Both states share a viewBox and terminal positions, so a bound line stays connected when the tag flips. → Drawing & symbols

The Breakpoint layout. New in 1.0.4 A fourth layout mode, for a screen whose phone version is a different screen rather than a narrower one. Each width tier gets its own authored panel and the view renders exactly one; a tier can mirror another, so a new view costs two screens rather than three. Switches at the project's own breakpoints, measures the container rather than the window (so they nest), and carries a dead-band for the flicker that happens when two tiers disagree about a scrollbar. → Breakpoint layout

The Timer node. New in 1.0.4 The pipeline runtime can now put time between messages — pulse a tag and put it back, hold a burst until it settles, delay every message, count down to a deadline, repeat on a cadence, or raise an alarm when a message that should have arrived did not. One independent timer per topic, controllable from the flow itself. → Timer node

Search that answers three questions. New in 1.0.4 A ⌘K / Ctrl+K palette across every project; faceted tag filters in the namespace (is:disabled, no:binding, is:unused, has:history, is:published, source:expression, …); where is this used for a tag or a connection; and an impact warning before a rename or delete that names what will break. → Search & impact

Telegram sends a position. New in 1.0.4 A pin, a named venue, a live location this platform then moves as a vehicle moves, or a button asking a recipient to share theirs. → Telegram node

Numeric readouts keep their decimals. New in 1.0.4 The Gauge, Tank, Moving Analog Indicator and HMI Trend take a decimals property instead of rounding a value away. A tag reading 23.998 is no longer displayed as 24 with no way to get the fraction back. → Gauge

Zoom and fit controls on the pipeline canvas. New in 1.0.4 Undo, redo, zoom in and out, reset to 100% and zoom-to-fit, with their keyboard equivalents shown on each.

The Connected column carries a date. New in 1.0.4 A LiveView screen on a wall stays up for days, and a bare 14:03 on such a row reads as a few minutes ago when it was Tuesday. The full instant is in the cell's tooltip.

Also in 1.0.4: the trial is recorded outside the data directory, so deleting that folder no longer buys a second one; and the pipeline-level POST /api/pipelines/{id}/execute route was removed — it answered 500 on every call it ever received, and nothing used it.

Fixes worth knowing about: node status badges never rendered in a production build; the runtime's STALE indicator was measuring clock skew rather than staleness; Python results were being refused by the bus, and child processes looked for the interpreter in the wrong directory.

1.0.3

A configuration fix that matters on every production install: every service opened a different app.db. Also: the import browser no longer collapses, and the storage folder picker no longer flickers or turns unreadable on hover.

1.0.2

AI Specialists can compute. New in 1.0.2 A specialist may carry a Python compute body, run end to end behind every fence, and declare its inputs once — so a figure is calculated exactly rather than worked out in a model's head. A specialist can also be saved as a draft: testable by its author, withheld from the assistant. → Answering with code

The trial is 21 days, not 7. New in 1.0.2 A week can vanish waiting for PLC access or a downtime window. → Licensing

On Windows, double-clicking the executable no longer flashes a console, and an uninstalled copy refuses to run.

1.0.1

P&ID line types. New in 1.0.1 ISA-5.1 tells signal lines apart by a repeated glyph rather than by colour — pneumatic hashes, data-link circles, a capillary X, a sonic wave. A line now carries its meaning as a property. → Drawing & symbols

Fittings that ride the pipe. New in 1.0.1 A flange, orifice plate, strainer or spectacle blind sits on a run at a normalised position along it, and stays there through a drag, a bend or a change of routing mode. → Drawing & symbols

A multi-value Progress bar. New in 1.0.1 One track, several coloured segments, each separately bindable, in absolute or proportional mode. → Progress

Storage folders are browsed, not typed. New in 1.0.1 A server-side folder picker with OS-aware suggestions, so a path is chosen rather than guessed at.

The status panel shows every volume QUBIQ writes to, not just one. New in 1.0.1

Open-source notices. New in 1.0.1 A third-party licence inventory, and the page that shows it, at /notices.

Also in 1.0.1: multi-touch pinch and pan on the Designer and pipeline canvases; a rebuilt Windows installer, and the same application identity on macOS and Linux; and licence status in the app status bar.

The Breakpoint Container widget was withdrawn from the component library in this release. The idea returned in 1.0.4 as a layout mode rather than a widget you drag from the palette — its containers are structural, so they are not in the component reference.

1.0.0

The first release. The parts of it this manual gained pages for:

MQTT publishing. New in 1.0.0 Mirror namespace tags out to an external broker — classic MQTT or Sparkplug B, with scope and exclusion fences, four layers of loop protection, and a choice between live and durably-buffered delivery. → MQTT publishing

Per-module licensing. New in 1.0.0 Offline, hardware-bound activation; a modules page that never hides what you do not own; and a lapse that degrades visibly rather than stopping a plant. → Licensing & modules

The Switch node. New in 1.0.0 The first router in the pipeline runtime, and the only node with more than one output. → Switch node

A Color Picker widget, and menu components that can run an action instead of navigating. → Color Picker · Horizontal Menu

AI playbooks, specialists and named endpoints. New in 1.0.0 An answer procedure written down once so every phrasing of a question gets the same complete answer; saved sub-assistants the assistant hands one sub-question to; and an admin-authored menu of lookups into an ERP or a CMMS that the model can select from but never compose. → Playbooks · Specialists · External systems · Skills & fences

---

The platform at a glance

What QUBIQ does, and where each part is documented.

Platform

Ships as one file. A single executable contains every service. Starting it with no arguments boots the supervisor, which runs one process per service under its own QBQ-* name. → Architecture

Zero-port internal bus. The message bus binds to loopback on a random port. No broker port is exposed, authenticated or firewalled, and no service other than the gateways opens a port. → The gateway

Encryption at rest. The configuration database is encrypted with a key bound to the machine it runs on. JWT_SECRET and ENCRYPTION_KEY are required, with no insecure defaults. → Security

In-app setup wizard. There is no default account and no create-superadmin step; the first super admin is created through the interface, once. → First-run setup

Connectivity

Protocol coverage — OPC-UA, MQTT with Sparkplug B, Modbus, SNMP (v1/v2c/v3 with vendor MIBs and traps), raw TCP/UDP, SQL, MongoDB, QuestDB and media servers — plus SMTP, Telegram and WhatsApp for notification and a Qdrant vector store for the assistant. → Connections

Publishing out, not just reading in: tags mirrored to an external broker in classic MQTT or Sparkplug B. → MQTT publishing

Passive liveness. Connection health comes from the protocol libraries' own callbacks rather than from polling. LIVENESS_MODE selects passive (default), hybrid or active. → Connections

OPC-UA node quarantine. A repeatedly-failing node is quarantined so one bad address cannot degrade a whole subscription, with a release path when the PLC program is fixed. → OPC-UA

Isolated MIB compilation. Vendor SNMP MIBs are compiled in a separate child process, so a malformed MIB cannot crash the gateway. → SNMP

Data model

User-defined types with parameters, nesting, reconciliation planning, per-instance overrides and member-context capture/revert. → User-defined types

Portable namespace import/export. Documents carry no database identifiers and reference connections by name, so a model moves between environments cleanly. → Bulk import & export

Tag write-security levels. A 0–3 hierarchy enforced server-side, independent of the writable flag. → Tags

Reference tracking. Where a tag is used, what a rename would break, and what nothing references at all. → Search & impact

Historian

History epochs. Changing the historian is non-destructive: reads resolve across epochs and stitch the timeline. Range statistics are recombined exactly rather than averaged. → Historian

Physical store ownership. Ownership is recorded inside the QuestDB store, so a cloned VM or a restored backup cannot silently corrupt a live historian. → QuestDB

Self-healing. Schema-drift detection with rebuild, write-ahead-log supervision that distinguishes recoverable stalls from poison segments, and on-demand rollup rebuild. → Historian configuration

Live-tail merge. Recent in-memory samples are merged into live chart queries, so charts look live despite batched storage.

Reliability

Store and forward for all outgoing data writes: a durable per-connection buffer, ordered ack-after-flush drain, an ordering latch, transient-versus-permanent failure classification, buffer pressure alarms and an operator quarantine. → Store and forward

Pipeline error handling — a Catch node that reports any node's failure with the payload that caused it, and a per-node error output that lets the flow recover in place. → Errors

Alarms

ISA-18.2 lifecycle — NORM / UNACK / ACK / RTNUN, with latching, require-ack, on/off delays, absolute and percentage deadbands, and bad-quality alarming. → Configuring alarms

Three distinct suppression kinds — timed shelving with automatic release, indefinite suppress-by-design, and out-of-service — so the reason an alarm is silent is always recorded. → Operating alarms

Performance metrics — rate, floods, bad actors, priority distribution and standing alarms.

Visualization

53 widgets, 9 drawing tools, 1048 symbols — 485 process (P&ID) and 529 electrical, plus 3D model viewing, PDF, video, maps, scheduling and a full form engine. → Components

Vector drawing with orthogonal, isometric and curved routing, endpoint binding to equipment, ISA-5.1 line types, in-line fittings and stroke animation for process mimics. → Drawing & symbols

Four layout modes — coordinate, grid, flex and breakpoint — chosen per view. Breakpoint gives each width tier its own authored screen rather than reflowing one. → Views and layout · Breakpoint layout

Optimistic locking on views, scripts and pipelines: a conflicting concurrent save is rejected rather than silently overwriting.

Streamed query results in LiveView, so a large result set renders as it arrives rather than after it has all landed.

Pipelines

23 node types across eight categories — sources, routing, protocol I/O, databases, transforms, AI, notification, REST and error handling. → Node reference

Scripting

One API surface in two languages. system.* is identical, camelCase, in Python and JavaScript. → System API reference

Gateway scripts with default-deny @gateway exports, static AST-based discovery, per-entry-point timeouts and idempotency keys. → Gateway scripts

Managed transactions with isolation levels and a server-side TTL, so a browser disconnect cannot strand an open transaction.

Capability scopes gating every system call, fail-safe by default — a newly-added API is gated rather than accidentally open. → The script sandbox

Administrator-installed Python packages, isolated in a managed directory with a connectivity check for air-gapped networks.

Security

Two independent sign-in systems. Engineers and plant operators sign in separately, against different user stores. Neither system accepts the other's sign-in. → LiveView authentication

Tamper-evident audit journal in an external SQL database, hash-chained, durable-buffered, with a verification endpoint — aligned to IEC 62443-3-3. → Audit journal

Scoped API keys, hashed at rest, with fail-closed REST routes, IP allow-lists, rate limits and payload caps. → API keys

Sandboxed user SQLite connections, confined to a resolved directory with traversal and internal-database denial.

Console recovery without a back door. A lost administrator password and a lost database key are both recoverable by somebody with the server's data directory, and by nobody else. Every reset is audited and surfaced where an administrator will see it. → Console recovery

AI assistant

Propose-and-approve. The assistant drafts views, pipelines, alarms and queries as proposals a human approves. Actions are audited under both the assistant and the approving user. → AI assistant

Skills, realms and fences. What an assistant may do is the intersection of its skills, where it runs, what the administrator switched on, and what the person asking already holds — and each instance carries its own fences over tags, databases, external systems and specialists. → Skills & fences

Playbooks and specialists — a procedure written down once, and saved sub-assistants with their own fences and budgets. → Playbooks · Specialists

Per-connection access and read-only credentials, so the assistant can explore a production database without being able to change it.

Administration

Per-module, offline licensing with a modules page that locks rather than hides. → Licensing & modules

Backup and restore with whole-archive passphrase encryption and secret re-keying between machines. → Backup & restore

Project lifecycle — enable, disable, trash with a 30-day retention window, restore and purge. → Projects

Service control from the interface, with the supervisor honouring a deliberate stop. → Services

---

Upgrading

1. Take a backup — schema migrations are not reversible.
2. Stop the service.
3. Replace the binary.
4. Start it. The supervisor migrates the schema before spawning children.
5. Check the startup report, then verify connections and pipelines.

Keep .env. Losing ENCRYPTION_KEY makes every stored credential unrecoverable, and losing this machine's database key store makes app.db unreadable — so run qubiq db-key create and file the code somewhere off the machine. → Console recovery

Check your licence covers the version

A licence names the versions it covers. Upgrading past that ceiling reports version not covered — not unlicensed — and the remedy is to install the version you own or extend the licence. → Licensing