On-Premise Agent

Connector Guide

The connector agent is a lightweight Node.js daemon that runs inside your print facility. It bridges your physical devices with the QueueVIO cloud — no inbound firewall rules required.

How the agent works

All communication is outbound HTTPS initiated by the agent — you never need to open inbound ports or configure NAT rules. The agent self-registers with the cloud on first start, then loops between polling and heartbeat on configurable intervals.

Self-register

On first start the agent calls POST /api/connectors and stores the returned ID in connector-id.txt. Subsequent restarts reuse the persisted ID.

Poll for jobs

Every 5 s (configurable) the agent calls GET /api/jobs/dispatch?connectorId=X to fetch jobs queued for its devices.

Dispatch via adapter

Each job is translated into the target device's native format (IPP, JDF, hot folder, vendor REST) by the matching adapter and submitted.

Report back

Stage progress and completion are written back via PATCH /api/jobs/:id/status. Heartbeats and SNMP device metrics run in parallel.

Installation

Requires Node.js 20+. The agent ships as a single npm package with no native dependencies.

1Install the package

npm install -g @queuevio/connector-agent

# or run without installing:
npx @queuevio/connector-agent

2Run the setup wizard

On first start — or with the --setup flag — the agent opens a browser-based wizard at http://localhost:3101. Enter your API URL, token, and tenant ID, then optionally connect your devices.

terminal

queuevio-agent

# No config found — setup wizard auto-launches:
  ┌─────────────────────────────────────────────────────┐
  │  QueueVIO Connector Setup                           │
  │                                                     │
  │  Open your browser to: http://localhost:3101        │
  │                                                     │
  │  Complete the setup wizard, then this agent         │
  │  will start automatically.                          │
  └─────────────────────────────────────────────────────┘

# To reopen the wizard at any time:
queuevio-agent --setup

The wizard can fetch your registered devices directly from QueueVIO — no UUID copy-paste required. Devices can also be skipped and configured later from Admin › Devices.

3Agent starts automatically

# After saving in the wizard the agent starts immediately:
QueueVIO Connector Agent
  API:      https://api.queuevio.com
  Tenant:   ten_01j9x...
  Devices:  3

[init] registering new connector: Plant Floor A — Building 2
[init] registered — connector ID: con_01j9xp...

  Polling every 5s · Heartbeat every 30s

↓Prefer manual configuration?

Skip the wizard by creating a .env and devices.json before first run. See the environment variables table below.

# .env
QUEUEVIO_API_URL=https://api.queuevio.com
QUEUEVIO_API_TOKEN=eyJhbGci...
QUEUEVIO_TENANT_ID=ten_01j9x...
CONNECTOR_NAME="Plant Floor A — Building 2"
DEVICES_CONFIG=./devices.json

Environment variables

All configuration is via environment variables or a .env file in the working directory. Variables marked * are required.

Variable	Default	Description
QUEUEVIO_API_URL*	http://localhost:3000	Base URL of the QueueVIO cloud API.
QUEUEVIO_API_TOKEN*	—	JWT token from POST /api/auth/login. Scopes the agent to a single tenant.
QUEUEVIO_TENANT_ID*	tenant-demo	Tenant identifier. Must match the token's tenant scope.
CONNECTOR_NAME	Connector Agent	Human-readable label shown in the dashboard (e.g. "Plant Floor A — Building 2").
CONNECTOR_ID	auto	Set to auto (default) for self-registration, or provide an existing connector UUID to skip re-registration.
DEVICES_CONFIG	./devices.json	Path to the devices JSON file that maps QueueVIO device IDs to local adapters.
POLL_INTERVAL_MS	5000	How often the agent polls the cloud API for new jobs (milliseconds).
HEARTBEAT_INTERVAL_MS	30000	How often the agent sends a heartbeat with CPU, memory, and queue metrics (milliseconds).

Available adapters

Set the adapter field in devices.json to one of the keys below. No code changes required — the agent loads the correct driver automatically.

Transport Protocols

ipp / ipps

IPP / IPPS

Internet Printing Protocol — the universal standard for networked printers. Works with any IPP-compliant device out of the box.

lpr

LPR / LPD

Line Printer Remote protocol for legacy UNIX print queues and older network printers.

raw

Raw TCP

Sends raw PDL data over a TCP socket. Used for printers that accept PCL or PostScript on a direct port (typically 9100).

hot_folder

Hot Folder

Writes job files into a watched directory. The RIP or device software picks them up automatically. Monitored with chokidar.

jdf_jmf

JDF / JMF

Job Definition Format ticket submission with JMF messaging. Used for offset press integrations and MIS-connected workflows.

Vendor Adapters

efi_fiery

EFI Fiery DFE

Fiery Command WorkStation REST API. Submits jobs, monitors status, and reads queue depth directly from the Fiery server.

hp_indigo

HP Indigo

HP Production Pro / SmartStream Director integration for Indigo digital presses.

hp_smartstream

HP SmartStream

HP SmartStream Designer and Production Center for variable-data and transactional workflows.

ricoh_totalflow

Ricoh TotalFlow

TotalFlow Production Manager REST API for Ricoh inkjet and toner presses.

heidelberg_prinect

Heidelberg Prinect

Prinect Integration Manager JMF bridge for Heidelberg offset and digital presses.

konica_minolta

Konica Minolta

Konica Minolta IQ-501 Intelligent Quality Optimizer and bizhub PRESS series.

xerox_freeflow

Xerox FreeFlow

FreeFlow Print Server and Core integration for Xerox iGen, Versant, and Nuvera presses.

canon_prismasync

Canon PRISMAsync

PRISMAsync Print Server REST API for Canon varioPRINT and imagePRESS series.

onyx_rip

ONYX RIP

ONYX Thrive and ProductionHouse hot-folder and API integration for wide-format printers.

caldera_rip

Caldera RIP

CalderaRIP REST API for wide-format and textile printing workflows.

zebra_zpl

Zebra ZPL

ZPL II label generation and direct submission to Zebra label and barcode printers.

generic_rest

Generic REST

Configurable REST adapter for any device or system with a custom HTTP API.

Finishing Equipment

duplo_dcc

Duplo DCC

Duplo Digital Cutter / Creaser JDF integration for inline and nearline finishing.

horizon

Horizon

Horizon JDF-compatible folders, stitchers, and perfect binders.

muller_martini

Müller Martini

Müller Martini Connex workflow for high-speed saddle stitching and binding lines.

kolbus

Kolbus

Kolbus digital workflow integration for perfect binding and case making.

bobst_connect

Bobst Connect

Bobst Connect platform for folding carton and label converting lines.

MIS / Workflow

efi_pace

EFI Pace

EFI Pace MIS job import and status writeback for commercial printers.

xmpie

XMPie

XMPie PersonalEffect REST API for variable-data and multichannel campaign workflows.

SNMP Monitoring

Device health metrics

Add "snmp": { "enabled": true } to any device in devices.json to enable SNMP polling. The agent queries standard MIBs every 30 s and writes the results back as AI signals on the device record.

›Page counter and impression count
›Toner / ink levels per channel
›Paper tray status and media loaded
›Error and warning flags
›Temperature and fuser status
›Network interface utilisation

devices.json — SNMP config

{
  "queuevioDeviceId": "dev_01j9xq...",
  "name": "HP Indigo 100K — Bay 3",
  "adapter": "hp_indigo",
  "host": "192.168.1.42",
  "snmp": {
    "enabled": true,
    "community": "public",
    "port": 161
  }
}

SNMP polling runs independently of the job adapter — you can enable it alongside any adapter type. Collected metrics are written to device.aiSignals and used by the routing engine.

Running in production

Run the agent as a managed system service so it restarts automatically on reboot or crash.

systemd (Linux)

# /etc/systemd/system/queuevio-agent.service
[Unit]
Description=QueueVIO Connector Agent
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/queuevio-agent
EnvironmentFile=/opt/queuevio-agent/.env
ExecStart=/usr/bin/queuevio-agent
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Docker

# docker-compose.yml
services:
  connector:
    image: queuevio/connector-agent:latest
    restart: unless-stopped
    volumes:
      - ./devices.json:/app/devices.json:ro
      - ./connector-id.txt:/app/connector-id.txt
    environment:
      QUEUEVIO_API_URL: https://api.queuevio.com
      QUEUEVIO_API_TOKEN: ${QUEUEVIO_API_TOKEN}
      QUEUEVIO_TENANT_ID: ${QUEUEVIO_TENANT_ID}
      CONNECTOR_NAME: "Plant Floor A"

Mount connector-id.txt as a persistent volume or bind mount. If it is lost, the agent re-registers as a new connector and the old record becomes orphaned.

Ready to connect your floor?

API Reference →System Architecture →