Quickstart Guide

This guide walks you through connecting your first sensor endpoint and getting a unit operation model running. Estimated time: 20 minutes for a single OPC-UA endpoint.

Prerequisites

A Twynvex pilot account — request access if you don't have one yet.
A Linux-based edge server (Ubuntu 20.04+ recommended) with network access to your DCS/historian.
Your OPC-UA endpoint address or MQTT broker address. IP, port, and authentication credentials.
One unit operation you want to model (e.g., distillation column, CSTR, evaporator).

Step 1: Install the connector agent

The Twynvex connector agent is a lightweight Linux service that reads from your sensor endpoints and pushes telemetry to the Twynvex simulation engine. Install it on your edge server:

edge-server:~

# Add Twynvex apt repository
$ curl -sSL https://packages.twynvex.com/install.sh | bash

# Install the connector agent
$ apt install twynvex-connector

# Verify installation
$ twynvex-connector --version
twynvex-connector 1.4.2 (build 20260415)

Step 2: Configure the YAML file

Create the connector configuration file at /etc/twynvex/connector.yaml. This file defines your source endpoints, data mappings, and pilot workspace credentials.

/etc/twynvex/connector.yaml

workspace_id: your-workspace-id
api_key: tvx_live_xxxxxxxxxxxx
flush_interval_s: 30

sources:
  - id: dcs-main
    protocol: opcua
    endpoint: opc.tcp://dcs-server-01.plant.local:4840
    security_mode: SignAndEncrypt
    certificate_path: /etc/twynvex/certs/client.der
    tags:
      - node_id: "ns=2;s=Distillation.T_FEED"
        alias: t_feed
        unit: degC
      - node_id: "ns=2;s=Distillation.F_FEED"
        alias: f_feed
        unit: kg/h
      - node_id: "ns=2;s=Distillation.T_TOP"
        alias: t_top
        unit: degC

Step 3: Verify connectivity

Run the connectivity check before starting the agent service to confirm your endpoint is reachable and your API key is valid:

edge-server:~

$ twynvex-connector check
✓  API key valid — workspace: your-workspace
✓  OPC-UA endpoint reachable: dcs-server-01.plant.local:4840
✓  Certificate handshake OK (SignAndEncrypt)
✓  Tag resolved: ns=2;s=Distillation.T_FEED → 147.3 degC
✓  Tag resolved: ns=2;s=Distillation.F_FEED → 12430 kg/h
✓  Tag resolved: ns=2;s=Distillation.T_TOP → 98.1 degC
All checks passed. Run: systemctl start twynvex-connector

Step 4: Define your unit operation model

Unit operations are configured in the Twynvex dashboard under Models → New unit operation. You can also define them via YAML in /etc/twynvex/models/:

/etc/twynvex/models/distillation-col-1.yaml

model_id: distillation-col-1
type: distillation_column
display_name: Column C-101 (Ethanol/Water)
horizon_hours: 4

inputs:
  feed_temperature: dcs-main.t_feed
  feed_flowrate: dcs-main.f_feed
  overhead_temperature: dcs-main.t_top

physics:
  stages: 24
  reflux_ratio_nominal: 3.2
  vle_model: wilson

Step 5: Run your first prediction

Once the connector is running and the model is defined, start the connector service and verify the prediction pipeline is running:

edge-server:~

$ systemctl enable --now twynvex-connector
Started twynvex-connector.service

$ twynvex-connector status
● connector active — 3 tags streaming, 1 model syncing
  last flush: 2026-03-04T14:22:18Z (28s ago)
  next prediction: distillation-col-1 in 12s

First prediction takes ~5 minutes. The engine needs 2–3 data flush cycles to initialize the Kalman filter state estimate before generating the first 4-hour prediction horizon. Check the dashboard under Models → distillation-col-1 → Predictions.

Next steps