Quick Start

Voltrus runs as a single binary with zero dependencies. From download to live dashboard in under three minutes.

1. Download

Get the binary for your platform from the downloads page or extract from your purchase email.

2. Configure

Copy the example configuration and edit it for your Modbus devices:

cp config.yaml.example config.yaml
nano config.yaml

3. Run

Linux:

./voltrus

Windows:

voltrus.exe

Open http://localhost:3000 in your browser. On first startup, a random 16-character admin password is generated and printed to the terminal once:

GENERATED ADMIN PASSWORD: xK9mP2vLqR5nW8jD
You will be required to change this on first login.

Username: admin. Password: the one shown in your terminal output.
You will be forced to change the password on your first login. Save it immediately: it will not be shown again.

Configuration Reference

Everything is configured through a single config.yaml file. Here are the available sections.

Minimal Config Example

Devices are configured through the UI: no need to edit the config file for device setup.

server_port: 3000
db_path: "data.db"
persist_interval_secs: 5
# auth_secret: "change-me-to-a-strong-random-string"

# Data retention: automatic downsampling and archiving
# retention:
#   enabled: true
#   run_interval_secs: 21600
#   archive_dir: "./archive"
#   tiers:
#     - name: raw
#       keep: 604800
#       downsample_to: hourly
#       archive: true
#     - name: hourly
#       keep: 7776000
#       downsample_to: daily
#     - name: daily
#       keep: null

Modbus Register Mapping

Each device in your config.yaml can have multiple registers. Here is the full set of options per register.

Multi-Device Example

devices:
  - name: "Main Power Meter"
    address: "192.168.1.100:502"
    unit_id: 1
    interval_ms: 1000
    registers:
      - name: "Voltage_L1"
        address: 0
        type: Float32
        endian: Big
        unit: "V"
      - name: "Current_L1"
        address: 2
        type: Float32
        endian: Big
        unit: "A"

  - name: "Solar Inverter"
    address: "192.168.1.101:502"
    unit_id: 1
    interval_ms: 2000
    registers:
      - name: "DC_Power"
        address: 10
        type: Float32
        endian: Big
        unit: "kW"

Protocol Support

Voltrus Core supports seven industrial protocols, all included with no licence. All protocols are configured through the web UI or config.yaml and share the same device/metric pipeline.

OPC-UA Configuration

Add OPC-UA endpoints through the web UI under Devices, or in config.yaml:

# OPC-UA devices are configured through the web UI.
# Navigate to Devices → Add Device → OPC-UA
# Enter the endpoint URL, security policy, and authentication.

Siemens S7 Configuration

Included in Core. Add S7 devices through the web UI. Supported blocks: DB, I/O, Markers, Timers, Counters.

# S7 devices are configured through the web UI.
# Navigate to Devices → Add Device → Siemens S7
# Enter IP, rack, slot, and select block types.

Allen-Bradley EtherNet/IP Configuration

Included in Core. Supports tag browsing: discover available tags from the controller.

# AB devices are configured through the web UI.
# Navigate to Devices → Add Device → Allen-Bradley
# Enter IP, and browse controller tags.

Modbus TCP Auto-Discovery

Scan a subnet (up to a /24) for Modbus TCP devices. In the dashboard, open the Modbus device manager and choose Scan Network: pick the devices it finds and add them in one step. From the command line:

./voltrus discover --range 192.168.1.0/24 --port 502

The CLI scans all hosts in the subnet, probes standard register maps, and outputs discovered devices. Export to config YAML for review before importing.

Alarm Notifications

Five notification channels are available. Email, webhook and push work fully on-premise. Telegram and WhatsApp need outbound internet access from the server.

Email (SMTP)

Configure your client's mail server in config.yaml. Uses SMTP relay: works with any on-premise mail server.

smtp:
  host: "smtp.client-network.local"
  port: 587
  from: "[email protected]"
  username: "voltrus"
  password: "smtp-password"
  use_tls: true

Webhook

HTTP POST on alarm trigger. Configure through the Data Flow Engine using the http_out node. Send to Slack, Teams, PagerDuty, or any HTTP endpoint.

Push Notifications

Web Push API with VAPID. Works on Chrome, Safari, and Firefox, including mobile browsers. Configure in config.yaml:

web_push:
  vapid_subject: "mailto:[email protected]"
  vapid_public_key: "BP..."
  vapid_private_key: "priv..."

Users subscribe through the notification settings panel in the dashboard.

Telegram

Integrator licence. Create a bot with BotFather, add it to the group or chat that should receive alarms, then add a Telegram rule in the notification settings with the bot token and one or more chat IDs. Send test checks the setup before an alarm does.

WhatsApp

Integrator licence. Uses the WhatsApp Business Cloud API from Meta. Business-initiated messages must use an approved message template, so a WhatsApp rule takes the phone number ID, an access token, recipient numbers in international format, and the template name and language. Map the template parameters ({{1}}, {{2}} and so on) to alarm fields: severity, source, value, message and time.

Bot tokens and access tokens are masked in the API and left out of project exports.

REST API

Voltrus includes a REST API for programmatic access to device data, alarms, and configuration. Included in Core.

Authentication

API requests require an API key. Generate keys through the web UI under Settings → API Keys.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/v1/devices

Key Endpoints

Query Parameters

# Historical data with time range
GET /api/v1/data?device_id=1&metric=voltage&start=2026-05-01T00:00:00Z&end=2026-05-03T00:00:00Z

# Aggregated data
GET /api/v1/data?device_id=1&metric=voltage&aggregation=avg&interval=1h

CORS

CORS headers are enabled for external access. Configure allowed origins in config.yaml:

cors:
  allowed_origins:
    - "https://your-frontend.example.com"

Analytics

Statistical process control and analytics endpoints for advanced data analysis. Included in Core.

Endpoints

API Reference & SDKs

Interactive API Explorer

Navigate to /api/docs on your Voltrus instance for the interactive Swagger UI. All endpoints are documented with request/response schemas and "Try it out" functionality.

OpenAPI Spec

The raw OpenAPI 3.1 spec is available at /api/openapi.json. Use it with any OpenAPI-compatible tool (Postman, Insomnia, code generators).

voltrus --dump-openapi > openapi.json

Python SDK

pip install voltrus

from voltrus import ApiClient, Configuration
from voltrus.api.data_api import DataApi

config = Configuration(host="http://192.168.1.100:3000")
config.api_key["api_key"] = "vt_sk_abc123"

with ApiClient(config) as client:
    data = DataApi(client).get_data(screen="overview")
    for ds in data:
        print(f"{ds.key}: {ds.value}")

TypeScript SDK

npm install voltrus

import { Configuration, DataApi } from "voltrus";

const config = new Configuration({
  basePath: "http://192.168.1.100:3000",
  apiKey: "vt_sk_abc123",
});

const data = await new DataApi(config).getData({ screen: "overview" });
data.forEach(ds => console.log(`${ds.key}: ${ds.value}`));

Backup & Restore

Create consistent backups of the SQLite database and configuration. Included in Core.

Create Backup

./voltrus backup

Creates a timestamped archive containing the SQLite database snapshot and config.yaml:

voltrus-backup-20260503-143022.tar.gz

Restore from Backup

./voltrus restore voltrus-backup-20260503-143022.tar.gz

Uses the SQLite backup API for consistent snapshots. A pre-restore backup is automatically created before overwriting.

Restore Without Confirmation

./voltrus restore voltrus-backup-20260503-143022.tar.gz --force

Custom Config Path

./voltrus restore backup.tar.gz --config /etc/voltrus/prod.yaml

CLI Reference

Voltrus includes several CLI subcommands beyond the main server.

Git-Friendly Configuration

Export your entire configuration to human-readable YAML files for version control:

./voltrus config export ./my-config

# Creates:
#   my-config/devices/
#   my-config/metrics/
#   my-config/dashboards/
#   my-config/flows/

# Track in git
cd my-config
git init
git add .
git commit -m "Initial config"

# Validate before importing
./voltrus config validate ./my-config

# Import on a new server
./voltrus config import ./my-config

Diff-friendly format: git diff shows exactly what changed in device addresses, register maps, alarm thresholds, and dashboard layouts.

Deployment Guide

Voltrus is designed to run anywhere: a $4 VPS, an industrial PC, or any x86_64 server.

Linux VPS (systemd)

Copy the binary and config to /opt/voltrus/, then install the included service file:

sudo cp deploy/voltrus.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable voltrus
sudo systemctl start voltrus

Windows Service

Use nssm or Windows Service Wrapper to run voltrus.exe as a background service. No installation wizard required.

OT Network Deployment & EDR Compatibility (v0.36.0)

When deploying to Windows-based SCADA servers with endpoint security (Defender, Trellix, CrowdStrike), add exclusion paths to prevent performance degradation:

# Generate recommended exclusions for your installation
voltrus edr report

# Generate PowerShell script for Windows Defender
voltrus edr exclusions-ps1 > defender-exclusions.ps1

# Run as Administrator
powershell -ExecutionPolicy Bypass -File defender-exclusions.ps1

For Active Directory-managed environments, use Group Policy to deploy exclusions across all SCADA servers. Run voltrus edr gpo-guide for step-by-step instructions.

API endpoints for programmatic access: GET /api/v1/edr/report, GET /api/v1/edr/exclusions, GET /api/v1/edr/exclusions/ps1, GET /api/v1/edr/gpo-guide

Hardware Certification & Edge Deployment (v0.38.0)

Voltrus runs on a wide range of hardware, from Raspberry Pi to enterprise servers. Use the hardware certification tools to test and verify your deployment platform:

# Check hardware compatibility
voltrus hw report

# Run performance benchmarks (~20 seconds)
voltrus hw benchmark

# View official hardware compatibility matrix
voltrus hw compat-matrix

# Generate edge deployment guide for your platform
voltrus hw edge-deploy

# Raspberry Pi quick-start
voltrus hw rpi-quickstart

Hardware Compatibility Matrix

Recommendations based on testing with typical SCADA workloads. Actual performance depends on tag count, polling rate, and enabled features.

Raspberry Pi Quick Start

# 1. Flash Raspberry Pi OS Lite (64-bit) to SD card
# 2. Enable SSH: touch /boot/firmware/ssh
# 3. SSH in and download Voltrus:
curl -L https://voltrus.id/downloads/voltrus-arm64-latest.tar.gz | tar xz
sudo mv voltrus /usr/local/bin/

# 4. Create config
mkdir -p /etc/voltrus /var/lib/voltrus
cat > /etc/voltrus/config.yaml << 'EOF'
server_port: 8080
db_path: /var/lib/voltrus/voltrus.db
auth_secret: YOUR_RANDOM_SECRET_HERE
retention:
  hot_days: 1
  warm_days: 30
  enabled: true
EOF

# 5. Set up auto-start (systemd)
voltrus hw edge-deploy  # Generates full service file

# 6. Start
voltrus /etc/voltrus/config.yaml
# Open: http://<PI_IP>:8080

API endpoints: GET /api/v1/hw/report, POST /api/v1/hw/benchmark, GET /api/v1/hw/compatibility-matrix, GET /api/v1/hw/edge-deploy

Docker (Optional)

While Voltrus is a single binary, you can containerize it if your infrastructure requires it:

FROM scratch
COPY voltrus /app/
COPY config.yaml /app/
COPY static /app/static
EXPOSE 3000
WORKDIR /app
ENTRYPOINT ["/app/voltrus"]

Authentication

Voltrus supports both local authentication and enterprise SSO out of the box.

Local Authentication

Enabled by default. Users are stored in the local SQLite database with Argon2 password hashing. Admin can create and manage users through the UI.

Single Sign-On

Enterprise licence. Add an sso: block to config.yaml with any of the three providers. Users sign in with the buttons on the login page, get a local account named after the provider (ldap:alice), and their role follows their groups at every sign-in. Secrets can come from environment variables.

sso:
  public_url: https://scada.example.com

  saml:                      # SAML 2.0: Azure AD, ADFS, Okta, Keycloak
    enabled: true
    label: "Azure AD"
    idp_metadata_url: https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app-id>
    role_mapping:
      default_role: viewer
      groups:
        - group: "<group object id>"
          role: admin

  oidc:                      # OpenID Connect, with PKCE
    client_id: voltrus
    client_secret_env: VOLTRUS_OIDC_CLIENT_SECRET
    groups_claim: groups

  ldap:                      # Active Directory over LDAPS or StartTLS
    enabled: true
    url: ldaps://dc1.corp.example:636
    bind_dn: CN=svc-voltrus,OU=Service,DC=corp,DC=example
    bind_password_env: VOLTRUS_LDAP_BIND_PASSWORD
    base_dn: DC=corp,DC=example
    user_filter: (sAMAccountName={username})
    nested_groups: true

oidc_issuer: https://login.example.com/realms/voltrus

SAML responses are verified against the signing certificate from your IdP metadata, with protection against signature wrapping and replay. LDAP connections verify the server certificate; plain ldap:// is refused unless you allow it explicitly.

Role-Based Access

Four built-in roles with custom role support (included in Core):

• Admin: Full access: devices, users, system settings, config
• Operator: Dashboard, alarm acknowledgment, recipe loading
• Viewer: Read-only dashboard access and history viewing
• Custom: Per-screen and per-action permissions (included in Core)

Compliance & Security

RBAC with Audit Trail

Included in Core. Granular role-based access control with per-screen and per-action permissions. All user actions are logged to an append-only audit trail table.

• Admin: Full access: devices, users, system settings, config
• Operator: Dashboard, alarm acknowledgment, recipe loading
• Viewer: Read-only dashboard access
• Custom: Define your own permission sets

Audit log captures: user, action, timestamp, before/after values. Immutable: records cannot be deleted or modified.

FDA 21 CFR Part 11 Mode

Enterprise licence. Enables support workflows for regulated industries for regulated industries (pharma, food, beverage):

• Electronic signatures with reason codes for critical actions
• Audit trail meeting CFR Part 11 requirements
• Record integrity verification (checksums on audit records)
• Automatic logout / session timeout enforcement
• Password complexity and rotation policies
• "Authority to change" workflow: changes require approval

Enable in config.yaml:

compliance:
  cfr_part_11: true
  session_timeout_minutes: 15
  password_min_length: 12
  password_require_special: true

Multi-Site Hub

Integrator licence. One Voltrus instance aggregates data from multiple remote sites:

1. Each site runs its own Voltrus instance (existing single-binary model)
2. One hub instance subscribes to each site's SSE stream
3. Hub dashboard shows all sites with grouping and labeling
4. Hub auto-discovers devices from connected sites

# Hub configuration in config.yaml
hub:
  sites:
    - name: "Plant A, Jakarta"
      url: "http://192.168.1.100:3000"
      api_key: "site-a-api-key"
    - name: "Plant B, Surabaya"
      url: "http://192.168.2.100:3000"
      api_key: "site-b-api-key"

OEE / Downtime Tracking

Included in Core. Track machine states and calculate Overall Equipment Effectiveness without PLC program changes: uses existing Modbus/MQTT data.

• Machine states: Running, Idle, Faulted, Setup, Maintenance
• OEE = Availability x Performance x Quality
• Configurable downtime reason codes
• Shift-based reporting (per-shift, per-day, per-week)

RTSP Video Integration

Enterprise licence. Display live camera feeds on the dashboard and capture alarm-triggered snapshots.

• RTSP stream ingestion from IP cameras (Hikvision, Dahua, Axis, generic)
• MJPEG snapshot capture on alarm trigger
• Snapshots stored in SQLite alongside alarm events
• No transcoding: direct stream proxy to browser

PDF Reporting

Integrator licence. Schedule automated report generation:

• Daily, weekly, or monthly report schedules
• HTML template to PDF conversion
• Includes: summary stats, alarm log, trend charts, uptime metrics
• Email delivery (uses SMTP configuration)

External Integration & BI Connectors (v0.39.0)

Voltrus can push data to external BI tools, monitoring systems, and storage. These integration endpoints are included in Core.

Prometheus Exporter

Voltrus exposes a standard Prometheus endpoint for IT/OT bridging. No authentication required.

# Prometheus scrape config
scrape_configs:
  - job_name: 'voltrus'
    scrape_interval: 15s
    static_configs:
      - targets: ['your-voltrus-server:8080']
    metrics_path: /metrics

Available metrics:

• voltrus_tag_value{device,tag,unit}: current tag values
• voltrus_device_up{device}: device online status (1=online, 0=offline)
• voltrus_alarms_active{severity}: active alarm counts

BI Query Endpoint

Query historical data for Power BI, Metabase, or custom integrations (included in Core).

# JSON query (Power BI: Get Data > Web)
GET /api/v1/integration/bi/query?devices=plc1&from=now-24h&to=now&limit=1000

# CSV export
GET /api/v1/integration/bi/query?format=csv&from=1710000000&to=1710086400

# Filter by metrics
GET /api/v1/integration/bi/query?metrics=voltage,current&from=now-1h

Query parameters: devices, metrics, from, to, limit, offset, format (json/csv).

Time formats: ISO 8601 (2024-03-09T00:00:00Z), unix timestamp (1710000000), or relative (now-1h, now-7d).

Grafana Integration

Use the Infinity data source or JSON API plugin to connect Grafana to Voltrus (included in Core).

# Query endpoint (returns [value, timestamp_ms] format)
GET /api/v1/integration/grafana/query?devices=plc1&from=now-1h

# Search endpoint (list available metrics)
GET /api/v1/integration/grafana/search

Outbound Webhooks

Push alarm and tag change events to external systems like Slack, Teams, or custom APIs (included in Core).

# Create an outbound webhook via API
POST /api/v1/integration/webhooks/outbound
{
  "name": "Slack Alert",
  "url": "https://hooks.slack.com/services/...",
  "events": "[\"alarm\"]",
  "headers": "{\"Authorization\": \"Bearer xxx\"}"  
}

# Test a webhook
POST /api/v1/integration/webhooks/outbound/{id}/test

Event types: alarm (fires on every alarm), tag_change (fires on each persistence tick). Supports retry with exponential backoff and device filtering.

Scheduled Data Export (Egress)

Automatically export data to filesystem or S3-compatible storage on a schedule (included in Core).

# Create a daily export job via API
POST /api/v1/egress/jobs
{
  "name": "Daily Backup",
  "schedule": "daily",
  "format": "csv",
  "destination": "/mnt/exports",
  "time_range": "24h",
  "compression": true
}

# S3-compatible storage
{
  "destination": "s3://my-bucket/voltrus/",
  "schedule": "every_6h"
}

# CLI commands
voltrus egress list          # List all egress jobs
voltrus egress run 1         # Manually trigger job #1

Schedules: hourly, daily, weekly, or every_Nm/every_Nh/every_Nd. Formats: csv or parquet. Optional gzip compression.

Connection Info

Auto-generated connection details for all BI tools:

GET /api/v1/integration/connection-info

License Activation

Core needs no licence and never phones home. An install with no licence is Core and works fully; the steps below apply only to Integrator and Enterprise licences. Monthly keys keep their features for 7 days after the paid period ends, then the install falls back to Core. Core is never limited by licence state. Online installs can refresh a monthly activation, and offline installs import a new activation file.

Voltrus uses an air-gap friendly license system for the licensed editions. Each license is bound to one server via hardware fingerprinting, and activation works even on completely offline networks.

How It Works

The activation flow is designed for industrial environments where servers may not have internet access. Your license key is already embedded in the request file. No need to enter it again on the web page:

1. Your server generates a license-request.bin file containing its hardware fingerprint and your Polar.sh license key
2. You copy this file to any PC with internet and upload it to the activation page
3. The activation server validates your license key and returns a signed license-activation.bin
4. You copy the activation file back to your server and import it
5. The server verifies the cryptographic signature and binds the license to its hardware fingerprint

Step 1: Generate License Request

On your Voltrus server, run:

./voltrus --generate-request YOUR_POLAR_LICENSE_KEY

This creates license-request.bin in the current directory. This file contains your server's hardware fingerprint and license key.

Step 2: Upload to Activation Server

Copy license-request.bin to a computer with internet access and upload it at:

https://activate.voltrus.id

The server will validate your license key and return license-activation.bin.

Step 3: Import Activation

Copy the returned license-activation.bin back to your Voltrus server and run:

./voltrus --import-activation license-activation.bin

If successful, you'll see:

License activated successfully: YOUR_POLAR_LICENSE_KEY

Step 4: Verify

Check your license status anytime:

./voltrus --license-status

Expected output when valid:

{
  "status": "Valid",
  "license_key": "polar_sh_key_abc123",
  "expires_at": "2026-05-01T12:05:00Z",
  "days_remaining": 365
}

Moving to a New Server

If you need to move your installation to new hardware:

1. Contact support to clear the existing hardware binding
2. Repeat the activation steps on the new server

Alternatively, if you have access to the admin panel at activate.voltrus.id/admin, support can transfer the license directly.

CLI Reference

Quick Online Activation

If your server has internet access, activate in one step:

./voltrus --online-activate YOUR_LICENSE_KEY

This generates the request, contacts the activation server, and imports the activation, all in one command. No file transfer needed.

Troubleshooting

Binary won't start

Symptom: Permission denied or command not found.
Fix: Ensure the binary has execute permissions on Linux:

chmod +x voltrus

Modbus connection timeout

Symptom: Dashboard shows "offline" for all devices.
Fix: Verify network connectivity and firewall rules. Test with the included Modbus simulator:

./modbus-sim --port 5020

Port already in use

Symptom: Error binding to port 3000.
Fix: Change the port in config.yaml or stop the existing process:

lsof -i :3000
kill -9 <PID>

Lost admin password

Symptom: Cannot log in, lost the initial password.
Fix: Run the CLI command to reset:

./voltrus --reset-admin-password

This generates a new random password and prints it to the terminal. You will be required to change it on next login.

Still stuck?

Contact support with your config.yaml (redact secrets) and any error logs:

[email protected]