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:

<code>cp config.yaml.example config.yaml
nano config.yaml</code>

3. Run

Linux:

<code>./voltrus</code>

Windows:

<code>voltrus.exe</code>

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

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

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.

<code>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</code>

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

<code>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"</code>

Protocol Support

Voltrus supports five industrial protocols. 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:

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

Siemens S7 Configuration

Enterprise tier. Add S7 devices through the web UI. Supported blocks: DB, I/O, Markers, Timers, Counters.

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

Allen-Bradley EtherNet/IP Configuration

Enterprise tier. Supports tag browsing — discover available tags from the controller.

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

Modbus TCP Auto-Discovery

Scan a subnet for Modbus TCP devices and auto-generate device configuration:

<code>./voltrus discover --range 192.168.1.0/24 --port 502</code>

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

Alarm Notifications

Four notification channels are available. All work on-premise with zero cloud dependency.

Email (SMTP)

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

<code>smtp:
  host: "smtp.client-network.local"
  port: 587
  from: "voltrus@client-network.local"
  username: "voltrus"
  password: "smtp-password"
  use_tls: true</code>

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:

<code>web_push:
  vapid_subject: "mailto:admin@yourcompany.com"
  vapid_public_key: "BP..."
  vapid_private_key: "priv..."</code>

Users subscribe through the notification settings panel in the dashboard.

SMS

Professional tier. Uses email-to-SMS carrier gateways — no external SMS service required:

SMS piggybacks on the SMTP configuration above. No separate service needed.

REST API

Voltrus includes a REST API for programmatic access to device data, alarms, and configuration. Available from Starter tier.

Authentication

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

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

Key Endpoints

Query Parameters

<code># 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</code>

CORS

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

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

Analytics

Statistical process control and analytics endpoints for advanced data analysis. Available from Professional tier.

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).

<code>voltrus --dump-openapi > openapi.json</code>

Python SDK

<code>pip install voltrus</code>

<code>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}")</code>

TypeScript SDK

<code>npm install voltrus</code>

<code>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}`));</code>

Backup & Restore

Create consistent backups of the SQLite database and configuration. Available from Starter tier.

Create Backup

<code>./voltrus backup</code>

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

<code>voltrus-backup-20260503-143022.tar.gz</code>

Restore from Backup

<code>./voltrus restore voltrus-backup-20260503-143022.tar.gz</code>

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

Restore Without Confirmation

<code>./voltrus restore voltrus-backup-20260503-143022.tar.gz --force</code>

Custom Config Path

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

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:

<code>./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</code>

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:

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

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:

<code># 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</code>

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:

<code># Check hardware compatibility for all tiers
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</code>

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

<code># 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</code>

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:

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

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.

SSO / OIDC

To connect to your identity provider, add the oidc block to config.yaml:

<code>auth:
  jwt_secret: "your-secret-here"
  token_expire_hours: 24
  oidc:
    issuer: "https://your-idp.com"
    client_id: "voltrus"
    client_secret: "your-client-secret"
    redirect_uri: "http://localhost:3000/auth/callback"</code>

Supported providers: Keycloak, Auth0, Azure AD, and any standard OpenID Connect provider.

SAML 2.0

Enterprise tier. Connect to Active Directory Federation Services (ADFS) and other SAML providers:

<code>auth:
  saml:
    idp_metadata_url: "https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml"
    entity_id: "voltrus"
    acs_url: "http://localhost:3000/auth/saml/callback"</code>

LDAP

Enterprise tier. Fallback for legacy Active Directory without ADFS:

<code>auth:
  ldap:
    url: "ldap://dc.example.com:389"
    base_dn: "DC=example,DC=com"
    bind_dn: "CN=voltrus,OU=ServiceAccounts,DC=example,DC=com"
    bind_password: "service-account-password"</code>

Group-based role mapping: AD group maps to Voltrus role (Admin, Operator, Viewer). Just-in-time user provisioning on first login.

Role-Based Access

Four built-in roles with custom role support (Professional tier and above):

• 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 (Professional+)

Compliance & Security

RBAC with Audit Trail

Professional tier and above. 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 tier. Enables compliance features 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:

<code>compliance:
  cfr_part_11: true
  session_timeout_minutes: 15
  password_min_length: 12
  password_require_special: true</code>

Multi-Site Hub

Professional tier. One Voltrus instance aggregates data from multiple remote sites:

1. Each site runs its own Voltrus instance (existing single-binary model)
2. One Professional 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

<code># 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"</code>

OEE / Downtime Tracking

Available from Starter tier. 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 tier. 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

Professional tier and above. 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. All integration endpoints are tier-gated.

Prometheus Exporter

Voltrus exposes a standard Prometheus endpoint for IT/OT bridging. No authentication required — tier-gated internally (Professional+).

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

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 (Professional+).

<code># 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</code>

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 (Professional+).

<code># 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</code>

Outbound Webhooks

Push alarm and tag change events to external systems like Slack, Teams, or custom APIs (Starter+).

<code># 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</code>

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 (Professional+).

<code># 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</code>

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:

<code>GET /api/v1/integration/connection-info</code>

License Activation

Voltrus uses an air-gap friendly license system. 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:

<code>./voltrus --generate-request YOUR_POLAR_LICENSE_KEY</code>

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:

<code>https://activate.voltrus.id</code>

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:

<code>./voltrus --import-activation license-activation.bin</code>

If successful, you'll see:

<code>License activated successfully: YOUR_POLAR_LICENSE_KEY</code>

Step 4: Verify

Check your license status anytime:

<code>./voltrus --license-status</code>

Expected output when valid:

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

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:

<code>./voltrus --online-activate YOUR_LICENSE_KEY</code>

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:

<code>chmod +x voltrus</code>

Modbus connection timeout

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

<code>./modbus-sim --port 5020</code>

Port already in use

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

<code>lsof -i :3000
kill -9 <PID></code>

Lost admin password

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

<code>./voltrus --reset-admin-password</code>

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:

support@voltrus.id