GermainUX-Agent Settings (Registry) | Germain Documentation

⚙️ GermainUX Agent Settings

The GermainUX Agent uses machine-wide Windows Registry settings to establish its initial configuration before connecting to the GermainUX server.

🔗 Shared components

These settings are shared by:

Component	Binary
Agent	`GermainUXAgent.exe`
Windows UI worker	`GermainUXRumWindows.exe`
Code Profiler	`GermainUXCodeProfiler.dll`

They allow the components to start, locate the GermainUX server, configure logging, and apply local monitoring rules before centrally managed configuration becomes available.

🗄️ Registry Location

The machine-wide Agent settings are stored under:

HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent

Administrator privileges are required to modify this Registry key.

Modify Registry settings carefully. Incorrect values can prevent the Agent or its monitoring components from starting. Back up the applicable Registry keys before making significant changes.

⌛ When Changes Take Effect

Registry settings are read once when each component starts. Changes do not take effect immediately.

Component	How to apply changes
`GermainUXAgent.exe`	Exit and restart the Agent, or sign out of Windows and sign back in. The Agent starts automatically at login through its scheduled task.
`GermainUXRumWindows.exe`	Restart the target application. The Agent launches a new Windows UI worker when it detects the new target process.
`GermainUXCodeProfiler.dll`	Restart the target application so that the Agent can attach the profiler to the new process.

Only the URL value is created by the installer. Add or modify the other settings using Windows Registry Editor or an authorized deployment script.

For installation instructions, see GermainUX Agent Installation.

📋 Machine-Wide Settings

Value	Type	Default	Used by	Description
`URL`	`REG_SZ`	Required	Agent, Code Profiler, and Windows UI worker	Base URL of the GermainUX server. The Agent cannot start without this value. The Code Profiler and Windows UI worker also use it as a fallback when they have not received another upload endpoint.
`Environment`	`REG_SZ`	Empty	Agent	Limits monitoring rules to the specified environment, such as `production` or `staging`. An empty value allows rules from all environments.
`AgentLogLevel`	`REG_SZ`	`INFO`	Agent	Controls the Agent’s health and status logging. Supported values are `OFF`, `ERROR`, `WARN`, `INFO`, `DEBUG`, and `TRACE`.
`WorkerLogLevel`	`REG_SZ`	`OFF`	Windows UI worker	Controls Windows UI worker logging independently from Agent logging. Enable it only when troubleshooting monitoring for a specific application.
`CLRLogLevel`	`REG_SZ`	`OFF`	Code Profiler	Controls CLR profiler logging independently from the Agent and Windows UI worker. Enable it only when troubleshooting .NET monitoring.
`LogPath`	`REG_SZ`	`%LOCALAPPDATA%\Germain Software\Germain Agent\Logs`	All components	Directory in which Agent, Windows UI worker, and Code Profiler logs are stored.
`PollInterval`	`REG_DWORD`	`60`	Agent	Number of seconds between checks for monitoring-rule changes on the GermainUX server.
`MouseHook`	`REG_DWORD`	`1`	Agent	Controls the low-level mouse hook used to collect mouse and click telemetry. Set to `0` to disable it.
`KeyboardHook`	`REG_DWORD`	`1`	Agent	Controls the low-level keyboard hook used to collect keyboard-command telemetry. Set to `0` to disable it.
`WorkerDebug`	`REG_DWORD`	`0`	Agent	When set to `1`, launches each Windows UI worker with `--wait-for-debugger`, allowing a developer to attach a debugger before processing starts. Keep this value set to `0` during normal operation.
`WorkerStopTimeoutMs`	`REG_DWORD`	`30000`	Agent	Maximum time, in milliseconds, that the Agent waits for a Windows UI worker to stop cleanly and flush pending data after its target application closes. The Agent forcibly terminates the worker after this timeout.

For log filenames and diagnostic procedures, see Agent Troubleshooting.

🌐 Configure the GermainUX Server URL

The URL value must contain the base URL of the GermainUX server.

Example:

https://server.cloud.germainux.com

Do not add an application-specific path unless instructed by Germain Software.

❌ Agent start failure conditions

The Agent cannot start if:

Condition	Detail
Missing URL	The `URL` value is missing.
Invalid URL	The value is empty or invalid.
Network issues	The server cannot be reached because of DNS, proxy, firewall, certificate, or network configuration issues.

After changing the URL, restart the Agent.

💡 Configure Logging

Each component has an independent log level:

Component	Registry value	Default
Agent	`AgentLogLevel`	`INFO`
Windows UI worker	`WorkerLogLevel`	`OFF`
.NET Code Profiler	`CLRLogLevel`	`OFF`

Supported levels, from least to most detailed, are:

OFF
ERROR
WARN
INFO
DEBUG
TRACE

Use DEBUG or TRACE only during troubleshooting. More detailed logging can generate substantial log volume and should normally be disabled after the investigation.

Unless LogPath specifies another directory, logs are written to:

%LOCALAPPDATA%\Germain Software\Germain Agent\Logs

Because %LOCALAPPDATA% is user-specific, the actual log directory belongs to the Windows account running the Agent.

🔍 Local Monitoring Rules

Monitoring rules normally come from the GermainUX server and identify:

Rule aspect	Purpose
Applications	Which applications to monitor
UI monitoring	Whether Windows UI monitoring is enabled
CLR profiling	Whether .NET CLR profiling is enabled
Profile settings	Which monitoring profile and settings to apply

A monitoring rule can also be defined locally in the Registry. Local rules are useful for:

Use case	When to use
Offline testing	Offline testing
Development and troubleshooting	Development and troubleshooting
One-time configuration	A one-time configuration
Non-managed computer	A computer that should not be centrally managed

📁 Local Rule Registry Location

Create one subkey for each executable under:

HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent\Targets

Use the target executable’s filename as the subkey name:

HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent\Targets\{executableName.exe}

Example:

HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent\Targets\MyApplication.exe

The executable name must include the .exe extension and match the name of the process detected by Windows.

🔧 Local Rule Settings

Create the following values under the target executable’s Registry key:

Value	Type	Default	Description
`ConfigFile`	`REG_SZ`	Required	Absolute path to the JSON file containing the monitoring configuration.
`Enabled`	`REG_DWORD`	`1`	Enables the rule. Set to `0` to retain the rule while preventing it from being applied.
`UiaWorkerEnabled`	`REG_DWORD`	`1`	Enables the Windows UI worker. Set to `0` for a headless process or when UI monitoring and session replay are not required.
`ClrAttachEnabled`	`REG_DWORD`	`1`	Enables the .NET CLR Code Profiler. Set to `0` when CLR-level monitoring is not required.

ConfigFile must contain the complete absolute path to a valid monitoring-configuration JSON file.

Example:

C:\GermainUX\Config\MyApplication.json

For the expected JSON structure, see Monitoring Configuration Reference.

⚖️ Local and Server-Provided Rule Priority

A local rule takes priority over a server-provided rule targeting the same executable.

For example, if both the Registry and GermainUX server contain a rule for MyApplication.exe, the Agent applies the local Registry rule.

Local and server-provided rules both appear in the Agent tray icon’s Configurations menu, allowing you to verify:

Verify	Detail
Received rules	Which rules the Agent received
Origin	Whether a rule is local or remote
Active settings	Which rule settings are currently active
Resolved config	The final resolved monitoring configuration

After adding or changing a local rule, restart the Agent.

Right-click the GermainUX Agent icon in the Windows system tray to access the following options:

Menu option	Description
Monitoring Enabled	Pauses or resumes all monitoring without stopping the Agent process. Clear the checkbox to pause monitoring; select it to resume monitoring.
Refresh Config	Immediately retrieves the latest monitoring rules from the GermainUX server instead of waiting for the next `PollInterval`.
Configurations	Displays all known server-provided and local monitoring rules. Select a rule to inspect its effective configuration.
About	Displays information about the installed GermainUX Agent.
Exit	Stops the Agent and its active monitoring until the Agent is started again or the user logs in again.

👁️ Inspect an Effective Configuration

The Configurations submenu lists:

Item	Description
Server-provided rules	Server-provided rules
Separator	A separator
Locally configured Registry rules	Locally configured Registry rules

Selecting a rule opens a read-only view containing:

Field
Rule name
Target executable
Monitoring profile
Overall enabled or disabled state
Windows UI worker state
CLR profiler attachment state
Local or remote origin
Complete resolved configuration JSON

This is the fastest way to confirm the exact configuration currently applied to an application.

🔧 Troubleshoot Registry Configuration

If a monitoring rule is not being applied:

Verify that the Registry key uses the exact executable filename, including .exe.
Confirm that Enabled is set to 1.
Confirm that ConfigFile contains an absolute path.
Verify that the configuration file exists and is accessible to the account running the Agent.
Validate the monitoring-configuration JSON.
Confirm that the Agent is running with local administrator privileges.
Restart the Agent after changing Registry values.
Restart the target application.
Open Configurations from the tray menu and inspect the resolved rule.
Review the Agent, Windows UI worker, or CLR profiler logs as applicable.

ℹ️ Get Help

The Germain Team can help you set this up. Contact GermainUX Support.

Component: Engine, JS Profiler, Mobile App, RPA Bot Recorder, RUM Windows, Agent

Feature Availability: 2026.2