> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GermainUX Agent Settings (Registry)

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

Components
[`Engine`](https://docs.germainux.com/main/germain-ux-engine)
[`JS Profiler`](https://docs.germainux.com/main/germain-ux-js-profiler)
[`Mobile App`](https://docs.germainux.com/main/germain-ux-mobile-app)
[`RPA Bot Recorder`](https://docs.germainux.com/main/germain-ux-rpa-bot-recorder)
[`RUM Windows`](https://docs.germainux.com/main/germainux-rum-windows)
[`Agent`](https://docs.germainux.com/main/germainux-agent)

Availability
2026.2

> [card] [Shared components](#shared-components)
>
> Core startup and logging settings

> [card] [When Changes Take Effect](#when-changes-take-effect)
>
> Restart needed for changes

> [card] [Configure Logging](#configure-logging)
>
> Set per-component log levels

> [card] [Use the Agent Tray Menu](#use-the-agent-tray-menu)
>
> Tray icon quick actions

## Overview

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:

```text theme={null}
HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent
```

Administrator privileges are required to modify this Registry key.

> [!WARNING]
>
> 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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
%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:

```text theme={null}
HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent\Targets
```

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

```text theme={null}
HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent\Targets\{executableName.exe}
```

Example:

```text theme={null}
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:

```text theme={null}
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.

## Use the Agent Tray Menu

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:

* 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:

**1. Verify that the Registry key uses the exact executable filename, including `.exe`**

**2. Confirm that `Enabled` is set to `1`**

**3. Confirm that `ConfigFile` contains an absolute path**

**4. Verify that the configuration file exists and is accessible to the account running the Agent**

**5. Validate the monitoring-configuration JSON**

**6. Confirm that the Agent is running with local administrator privileges**

**7. Restart the Agent after changing Registry values**

**8. Restart the target application**

**9. Open Configurations from the tray menu and inspect the resolved rule**

**10. Review the Agent, Windows UI worker, or CLR profiler logs as applicable**

## Additional Resources

> [card] [Troubleshooting Tips](https://docs.germainux.com/main/germain-enterprise-troubleshooting.md)
>
> Read more

> [card] [Management](https://docs.germainux.com/main/management.md)
>
> More Management Features

## Get Help

> [card] [Contact GermainUX Support](https://docs.germainux.com/main/support.md)
>
> The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

> [card] Can't find what you need?
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.