Configuring Core configuration

JSON configuration structure and schema reference. Covers the metadata, run conditions, and install behavior that control how the script operates.

Overview

Every Windows gecko configuration file must include a metadata section and a runConditions section. These define the script's identity, execution context, and runtime behavior. All feature modules are optional and gated by their enabled property.

Configuration files reference $schema: "./gecko-config.schema.json" for validation.

Metadata and registry detection

When metadata.enabled is set to true, Windows gecko writes an entry under Software\Microsoft\Windows\CurrentVersion\Uninstall\{guid} in the registry. The installBehavior property determines the registry root - SYSTEM writes to HKLM and USER writes to HKCU. This registry entry is designed to work with Microsoft Intune detection rules, allowing the Win32 app deployment to validate whether the configuration was successfully applied. The entry includes SystemComponent set to 1, which hides it from Apps & features and Programs and Features in the control panel.

The guid property serves as the unique registry key name under the Uninstall path. When used with Microsoft Intune, the detection rule can check for the existence of this key (and optionally the Version value) to confirm a successful installation. If guid is missing or empty, the script logs an error and skips writing metadata registry entries entirely.

Tip

Use the Insert GUID Visual Studio Code extension to quickly generate GUIDs directly in the editor.

If the script is used outside of Microsoft Intune - or in scenarios where registry-based detection is not needed - administrators can set enabled to false to skip writing metadata entirely.

Log file naming

The title property is used to derive the log file name. The title value is sanitized (non-alphanumeric characters are replaced with hyphens) and used as the log file name in the default log directory. If title is not configured, the log file name defaults to the script name - e.g., gecko.log. If the default log directory is not writable, the log file falls back to the %TEMP% folder.

Configuration

The following shows the core configuration structure with metadata and runConditions sections.

{
  "$schema": "./gecko-config.schema.json",
  "metadata": {
    "enabled": true,
    "installBehavior": "[SYSTEM|USER]",
    "guid": "{<GUID>}",
    "title": "<title>",
    "description": "<description>",
    "url": "",
    "version": "<version>",
    "date": "<date>",
    "publisher": "<publisher>",
    "developer": "<developer>"
  },
  "runConditions": {
    "runScriptIn64bitPowerShell": true,
    "requireReboot": false,
    "networkProbe": true,
    "networkProbeCount": 3
  }
}

Dataset properties

The following properties should be present in any configuration file.

Property	Description	Type	Required
metadata
enabled	Gates whether metadata is written to the registry. Set to false when registry-based detection is not needed	Boolean	Yes
installBehavior	Execution context - SYSTEM (HKLM) or USER (HKCU). Determines the registry root for the uninstall entry. If not set or invalid, metadata registry entries are skipped and an error is logged	String	Yes
guid	Unique identifier used as the registry key name under the Uninstall path	String	Yes
title	Configuration title. Also used for log file naming - defaults to the script name if not configured	String	Yes
description	Configuration description	String	No
url	URL for additional information	String	No
version	Configuration version, written to DisplayVersion in the registry	String	Yes
date	Configuration date	String	No
publisher	Publisher name	String	No
developer	Developer name	String	No
runConditions
runScriptIn64bitPowerShell	Ensure the script runs in 64-bit PowerShell. Recommended but defaults to false if not configured	Boolean	No
requireReboot	Request a reboot after script completion	Boolean	No
networkProbe	Enable a lightweight network connectivity probe during environment logging. The probe uses the Windows NCSI endpoint (msftconnecttest.com) to measure latency and report a connectivity rating (Fast, Moderate, Slow). Defaults to false if not configured	Boolean	No
networkProbeCount	Number of probe iterations to run (1-10). The results are averaged to produce the connectivity rating. Defaults to 3 if not configured	Integer	No

Related resources

For more information, see the following resources.

---

Page revised: March 15, 2026