Runtime Startup Reference

Configure and control all runtime options.

Reference → Solution → Runtime → UI → Startup | Build and Publish | Execution Profiles | Monitor

Main Commands

Execution Controls

Note: All changes must be saved before they appear in runtime when online configuration is enabled.

Execution Profiles

Select environment-specific configuration:

The Production profile uses main configuration without overrides. Other profiles apply configured replacements at startup.

Startup Port Settings

Configure network ports for application access:

AutoStartup Behavior

Windows Platform:

• Configures as Windows Service
• Starts without user login
• Runs under system account

Multiplatform on Remote Devices:

• Configures in TWebServicesRunPrograms.json
• Starts with TWebServices
• Enables remote management

SSL Certificate Configuration

When an SSL Port is configured, a TLS/SSL certificate is required to serve HTTPS connections on that port. Certificate settings are stored per port in TServer.json — changing the SSL Port number requires reconfiguring the certificate for the new port.

To open the certificate dialog: Click the button next to the SSL Port field.

Certificate File mode: Browse for a .pfx or .crt file. For .pfx files, enter the certificate password. When connected to a remote server, the file is uploaded automatically to the Certificates\ subfolder in the server's machine settings directory.

Certificate Store mode: Enter the SHA-1 thumbprint of a certificate already installed in the Windows local machine store. This option is not available when connected to a remote server.

Validate Certificate: Checks the certificate and displays its subject, expiration date, and issuer. Only available when connected to a local server. Validation is required before saving.

Windows Authentication (WA) Configuration

Windows Authentication lets a user sign in to a runtime without typing a username or password, by reusing the Windows session they are already logged into on the client machine. It is intended for installations where the runtime and its clients live inside the same Active Directory domain.

Enabling WA

Under Runtime / Startup, enable WA. Rich Client and Smart Client connections then attach to that port and pass the client's Windows identity to the server instead of credentials. The web client connects via ip. port and wa=true.

How it works

WA does not validate a password — it trusts the Windows/AD logon that the OS already performed. Two preconditions must hold for login to succeed:

1. The user must be currently logged into Windows on a machine that can reach the domain controller.
2. The user account must exist in Active Directory.

If the AD lookup fails, authentication fails — there is no local-password fallback in WA mode.

Permission resolution

After the AD identity is resolved, the user doesn't have to exist in the solution. Instead, the user's AD group membership is matched against the Windows Group → Permission mappings configured in the Security module (for example, DOMAIN\Engineers → permission Engineering). If a matching permission exists in the solution, the session is granted that permission; otherwise the session falls back to Guest. The session itself is held in memory on the server, WA never writes the user into the Runtime Users database.

WA vs LDAP

LDAP is an interactive flow that collects username and password in the login dialog and forwards them to the directory server for validation, returning the group on success (which then feeds the same permission-mapping step). LDAP therefore works for users who are not currently logged into a Windows domain session, while WA works only for users who already are. WA can be used behind IIS or against a runtime hosted outside IIS — IIS is not a requirement. Refer to Security Runtime Users Reference for more information.

Port conflicts and AutoPorts limits

Auto Ports protects against the most common port collision: two FrameworX runtimes for the same solution trying to bind the same port. When the setting is enabled and another FrameworX runtime on the same solution already holds the configured port, the launcher probes forward and binds the next free port instead. Disabled by default; enable it per profile in the Startup Port Settings above.

What Auto Ports does not cover. The mechanism only detects another live FrameworX runtime. It does not bump the port when:

• A previous FrameworX process died without releasing the port (orphan process).
• The port is held in TCP TIME_WAIT (about 30 seconds after a clean stop).
• A non-FrameworX listener is on the same port (another web server, a debug tool, an unrelated service).
• The runtime was just stopped from inside Designer and an internal reference still pins the prior port.

In any of these cases startup fails with a port-in-use error even with Auto Ports enabled.

Recovery when Auto Ports cannot help

1. Identify the process holding the port (PowerShell):
   Get-NetTCPConnection -LocalPort <port> | Select-Object OwningProcess
   Then Get-Process -Id <PID> to see what it is.
2. If it is a stale FrameworX process, end it:
   Stop-Process -Id <PID> -Force
3. If the port is in TIME_WAIT, wait about 30 seconds and retry the runtime startup.
4. If a different process owns the port (a non-FrameworX listener you want to keep), change the configured Port on the Runtime Startup page to a free value, or restart Designer to release any ports held by Designer-side helpers.

Command-Line Service Management (TManageServices.exe)

Runtime services can also be installed and removed from the command line, without opening Designer. The TManageServices.exe utility (located in the product root folder) handles Windows Service install/uninstall for every runtime component and is the same utility invoked internally when you click AutoStartup in Designer.

This is the standard way to integrate with SCCM, Intune, PowerShell DSC, Ansible, Chef, or any unattended deployment pipeline.

TStartup (Runtime) Service

Install the runtime as a Windows Service for a given solution. The service name will be TStartup-<SolutionName>:

TManageServices.exe /installtstartup /solution:"C:\Solutions\Plant1.tproj" /silent

Uninstall the service by solution name:

TManageServices.exe /uninstalltstartup /solution:"Plant1" /silent

Any additional arguments passed on the command line (e.g. /profile:N, /username:..., /port1:..., /wa:true) are forwarded to the service executable at install time so they are applied every time the service starts.

Other Runtime Services

The same utility manages all other FrameworX Windows services:

Unattended Mode

Pass /silent to prevent the utility from pausing on error. When /silent is set (or when stdin is redirected, as in any scripted pipeline), TManageServices.exe returns cleanly with an exit code instead of waiting for a keypress.

Exit codes:

• 0 — Success
• N — Number of failed operations

Help

Run the utility without arguments, or with /? / /help, to print the full command reference:

TManageServices.exe /?

Requirements

• Must be run from an elevated (Administrator) shell — service registration requires elevation
• Supported on Windows only
• On Linux/Docker, run the runtime via systemd instead (see the Linux/Docker Startup section of Runtime Installation Reference)

For end-to-end IT deployment patterns, see IT Deployment RunBook.

Execution Environment

Execution Path Settings

DataHub Service

DataHub Settings:

• Alias: Solution identifier
• Primary/Secondary Host: Server addresses
• Port: TCP communication (default: 30001)
• AccessKey: Authentication

Built-in Broker Settings

Startup Modules

Select modules to activate at startup:

Redundancy Settings

Configure high-availability environment:

Recovery Options

• Switch back to primary: Auto-return when available
• Keep secondary active: Manual switchback required

Command Lines and URLs

Startup Command Line

TStartup.exe /solution:"path\solution.dbsln" /profile:1 /OnlineConfig:true /port1:3301

Parameters:

• /solution: - Solution file path
• /profile: - 1=Dev, 2=Val, 3=Custom
• /OnlineConfig: - Enable online changes
• /wa - Windows Authentication
• /port1: - Override port

Client Access

Network Access Example

Accessing HTML5 from Other Devices:

• Server IP: 192.168.0.8
• Port: 3201
• URL: http://192.168.0.8:3201/html5

Direct Monitor Access:

http://ServerIP:Port/html5/?Monitor=Runtime

Startup Procedure

Step-by-Step Process

1. Launching TStartup.exe
   • Loads the Solution
   • Reads Solution Configuration
   • Parses Command Line Parameters
   • Activates Main Process TServer.exe
2. Starting Real-Time Database
   • TServer.exe loads objects into memory
   • Establishes communication service
3. Modules Startup
   • Each module reads configuration
   • Establishes connection with main process
4. Applying Execution Profiles
   • Development: Local SQLite database
   • Production: SQL server connection
5. Designer Connection
   • Automatic connection for monitoring
6. Client Display Access
   • Remote computers can connect
7. Online Changes
   • Apply without runtime disruption

Platform-Specific Features

Windows-Only Features:

• Windows Authentication
• Windows Service configuration
• OPC Classic support
• Specific security features

In this section...