Administrator Guide

Client Configuration

Configure Network Weather via config.json or nwx.config

Network Weather can be configured via a JSON file. All settings are optional; if no config file exists, the app uses built-in defaults.

Config File Location

macOS

The configuration file is located in the user's home directory:

Platform	Path	Description
macOS	`~/.nwx/config.json`	User preference directory

Windows

Windows supports three config file locations in order of precedence:

Priority	Source	Path	Description
1 (highest)	Machine Policy	`%ProgramData%\NetworkWeather\nwx.config`	Machine-wide policy deployed by MSP/GPO (read-only for standard users).
2	App Directory	`<InstallDirectory>\nwx.config`	Alongside `nwx.exe` (deployed by MSP in MSIX packages).
3 (lowest)	User Preference	`%LOCALAPPDATA%\NetworkWeather\nwx.config`	User preference directory (also falls back to `config.json`).

Config File Creation

macOS (Bash)

Create the directory and file:

mkdir -p ~/.nwx
cat > ~/.nwx/config.json << 'EOF'
{
  "suppressWelcomeFlow": true
}
EOF

Windows (PowerShell)

Create the user preference directory and file:

New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\NetworkWeather"
Set-Content -Path "$env:LOCALAPPDATA\NetworkWeather\nwx.config" -Value @'
{
  "suppressWelcomeFlow": true
}
'@

macOS Supported Settings

All fields are optional. Only include what you want to override.

Updates & Onboarding

Key	Type	Default	Description
`suppressWelcomeFlow`	boolean	`false`	Skip onboarding flow (for enterprise/MSP silent installs)
`disableSparkle`	boolean	`false`	Disable Sparkle auto-updates; use C2-based update checking instead
`appcastURL`	string	(Info.plist)	Custom Sparkle appcast URL for internal update servers

Logging

Key	Type	Default	Description
`logLevel`	string	`"info"`	Log verbosity: `"trace"`, `"debug"`, `"info"`, `"warning"`, `"error"`

Measurement Intervals

Key	Type	Default	Description
`measurementIntervalAC`	number	`300`	Full measurement cycle on AC power (seconds)
`measurementIntervalBattery`	number	`900`	Full measurement cycle on battery (seconds)

Topology Discovery

Key	Type	Default	Description
`maxPathsToDiscover`	integer	`1`	Paths to discover per endpoint (multipath detection)
`topologyCacheTTL`	number	`300`	How long topology results are cached (seconds)

Hop Monitoring

Key	Type	Default	Description
`hopPingIntervalAC`	number	`5`	Per-hop ping interval on AC power (seconds)
`hopPingIntervalBattery`	number	`15`	Per-hop ping interval on battery (seconds)

Health Analysis

Key	Type	Default	Description
`healthAnalysisInterval`	number	`30`	Minimum time between health analysis runs (seconds)
`healthAnalysisLoggingDebounce`	number	`300`	Rate limiting for health analysis log output (seconds)

HTTP Probing

Key	Type	Default	Description
`httpProbeIntervalAC`	number	`30`	HTTP probe interval on AC power (seconds)
`httpProbeIntervalBattery`	number	`90`	HTTP probe interval on battery (seconds)

Gateway Telemetry

Key	Type	Default	Description
`gatewayTelemetryRefreshIntervalAC`	number	`300`	Gateway data refresh on AC power (seconds)
`gatewayTelemetryRefreshIntervalBattery`	number	`900`	Gateway data refresh on battery (seconds)

Notifications

Key	Type	Default	Description
`notificationsEnabled`	boolean	`true`	Enable macOS notifications for network impairments
`notificationMinSeverity`	string	`"warning"`	Minimum severity to trigger a notification: info, warning, critical

UI Behavior

Key	Type	Default	Description
`openUIAtLaunch`	boolean	`true`	Open the main window at launch. Set to `false` to launch silently into menu bar.

This setting can also be toggled from the menu bar dropdown ("Open UI at Launch"). The config file value takes priority over the menu bar toggle.

macOS Example Config

Enterprise deployment with onboarding suppressed, Sparkle disabled, and more frequent measurements:

{
  "suppressWelcomeFlow": true,
  "disableSparkle": true,
  "logLevel": "info",
  "measurementIntervalAC": 120,
  "measurementIntervalBattery": 600
}

Windows Supported Settings

Windows supports a structured, nested JSON format (with flat compatibility mappings for common macOS keys). Only include fields you wish to override. All time intervals are defined in milliseconds.

C2 Configuration (`c2`)

Key	Type	Default	Description
`c2.environment`	string	`"production"`	Environment for C2 check-in: `"production"` or `"staging"`
`c2.channel`	string	`"stable"`	Release channel: `"stable"` or `"beta"`
`c2.c2_base_url`	string	`"https://api.networkweather.com"`	Base URL of the C2 management server
`c2.telemetry_enabled`	boolean	`true`	Enable client metric and state telemetry
`c2.telemetry_level`	string	`"info"`	Telemetry verbosity: `"debug"`, `"info"`, `"warn"`, `"error"`
`c2.crash_reporting_enabled`	boolean	`true`	Enable Sentry crash reporting

MSP & Organization Registration (`registration`)

Key	Type	Default	Description
`registration.mspId`	string	`""`	MSP identifier for partner enrollment
`registration.orgId`	string	`""`	Organization identifier within MSP
`registration.organizationName`	string	`""`	Human-readable organization name to display in the UI

Monitoring & Probe Settings (`probeSettings`)

Key	Type	Default (ms)	Description
`probeSettings.hopPingIntervalAC`	number	`5000`	Per-hop ping interval on AC power
`probeSettings.hopPingIntervalBattery`	number	`15000`	Per-hop ping interval on battery
`probeSettings.httpProbeIntervalAC`	number	`30000`	HTTP/HTTPS probe interval on AC power
`probeSettings.httpProbeIntervalBattery`	number	`60000`	HTTP/HTTPS probe interval on battery
`probeSettings.pathDiscoveryIntervalAC`	number	`120000`	Traceroute re-discovery interval on AC power
`probeSettings.pathDiscoveryIntervalBattery`	number	`300000`	Traceroute re-discovery interval on battery

Logging Settings (`logging`)

Key	Type	Default	Description
`logging.level`	string	`"info"`	Log level: `"debug"`, `"info"`, `"warn"`, `"error"`
`logging.redactPII`	boolean	`false`	Redact personally identifiable information from local logs

Behavior Settings (`behaviorSettings`)

Key	Type	Default	Description
`behaviorSettings.suppressWelcomeFlow`	boolean	`false`	Skip onboarding welcome flow

Windows Flat/macOS Compatibility Keys

For easier cross-platform scripting, the Windows client automatically maps the following flat top-level keys to their nested counterparts:

Flat Key	Nested Destination	Type
`mspId`	`registration.mspId`	string
`orgId`	`registration.orgId`	string
`organizationName`	`registration.organizationName`	string
`logLevel`	`logging.level`	string
`suppressWelcomeFlow`	`behaviorSettings.suppressWelcomeFlow`	boolean

Windows Example Config

Complete Nested Config

{
  "c2": {
    "environment": "production",
    "channel": "stable",
    "c2_base_url": "https://api.networkweather.com",
    "telemetry_enabled": true
  },
  "registration": {
    "mspId": "msp-acme-corp",
    "orgId": "org-client-123",
    "organizationName": "Acme Corporation"
  },
  "probeSettings": {
    "hopPingIntervalAC": 5000,
    "hopPingIntervalBattery": 15000,
    "httpProbeIntervalAC": 30000,
    "httpProbeIntervalBattery": 60000
  },
  "logging": {
    "level": "info",
    "redactPII": false
  },
  "behaviorSettings": {
    "suppressWelcomeFlow": true
  }
}

Flat Compatibility Config

{
  "mspId": "msp-acme-corp",
  "orgId": "org-client-123",
  "organizationName": "Acme Corporation",
  "logLevel": "debug",
  "suppressWelcomeFlow": true
}

Windows Enterprise Management (GPO & Policy)

On Windows, IT administrators can enforce settings and enforce management lock by placing the config file in the Machine Policy directory: %ProgramData%\NetworkWeather\nwx.config

When any key is defined in the Machine Policy configuration file:

Management Lock Active: That key is locked machine-wide.
Override Blocked: Standard users, user-level config files (%LOCALAPPDATA%), and app-level config files cannot override that key.
Registry/GPO Deployment: This allows IT administrators to deploy policy securely via Group Policy, Intune, or custom scripts without worrying about local user modification.

Windows Override Priority (highest to lowest)

Priority	Source	Path	User-writable?
1 (highest)	Machine Policy	`%ProgramData%\NetworkWeather\nwx.config`	No (Requires local admin)
2	App Directory	`<InstallDirectory>\nwx.config` (Alongside `nwx.exe`)	No (Read-only/MSIX container)
3	User Preference	`%LOCALAPPDATA%\NetworkWeather\nwx.config`	Yes
4 (lowest)	Built-in defaults	None	N/A

Managed Preferences (MDM)

On macOS, IT administrators can enforce settings via MDM configuration profiles. MDM-pushed values take priority over config.json and cannot be overridden by the user.

Bundle ID domain: com.networkweather.nwx.macos

Supported MDM Keys

All config.json settings can also be pushed via MDM. When a key is MDM-managed, it is locked and cannot be overridden by the user or config file.

Key	Type	Description
`suppressWelcomeFlow`	Bool	Skip onboarding
`disableSparkle`	Bool	Disable Sparkle auto-updates
`appcastURL`	String	Custom appcast URL
`c2BaseURL`	String	Override C2 server URL
`neverAsksForAdmin`	Bool	Block privilege escalation prompts
`logLevel`	String	Override log level
`mspId`	String	MSP identifier for partner enrollment
`orgId`	String	Organization identifier within MSP
`measurementIntervalAC`	Number	Full measurement cycle on AC power (seconds)
`measurementIntervalBattery`	Number	Full measurement cycle on battery (seconds)
`maxPathsToDiscover`	Number	Paths to discover per endpoint
`topologyCacheTTL`	Number	Topology cache validity (seconds)
`hopPingIntervalAC`	Number	Per-hop ping interval on AC power (seconds)
`hopPingIntervalBattery`	Number	Per-hop ping interval on battery (seconds)
`healthAnalysisInterval`	Number	Minimum time between health analysis runs (seconds)
`healthAnalysisLoggingDebounce`	Number	Health analysis log rate limit (seconds)
`httpProbeIntervalAC`	Number	HTTP probe interval on AC power (seconds)
`httpProbeIntervalBattery`	Number	HTTP probe interval on battery (seconds)
`gatewayTelemetryRefreshIntervalAC`	Number	Gateway data refresh on AC power (seconds)
`gatewayTelemetryRefreshIntervalBattery`	Number	Gateway data refresh on battery (seconds)
`notificationsEnabled`	Bool	Enable impairment notifications
`notificationMinSeverity`	String	Minimum notification severity (info/warning/critical)
`openUIAtLaunch`	Bool	Open main window at launch
`verboseWiFiIE`	Bool	Log detailed WiFi IE capabilities per BSSID

Example .mobileconfig Profile

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>com.networkweather.nwx.macos</string>
      <key>PayloadIdentifier</key>
      <string>com.networkweather.nwx.macos.managed</string>
      <key>PayloadUUID</key>
      <string>A1B2C3D4-E5F6-7890-ABCD-EF1234567890</string>
      <key>PayloadVersion</key>
      <integer>1</integer>

      <!-- Updates & Onboarding -->
      <key>disableSparkle</key>
      <true/>
      <key>suppressWelcomeFlow</key>
      <true/>
      <key>neverAsksForAdmin</key>
      <true/>

      <!-- UI Behavior -->
      <key>openUIAtLaunch</key>
      <false/>
      <key>notificationsEnabled</key>
      <true/>
      <key>notificationMinSeverity</key>
      <string>warning</string>

      <!-- Measurement Tuning (seconds) -->
      <key>measurementIntervalAC</key>
      <integer>120</integer>
      <key>measurementIntervalBattery</key>
      <integer>600</integer>
    </dict>
  </array>
  <key>PayloadIdentifier</key>
  <string>com.example.corp.nwx-policy</string>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadUUID</key>
  <string>F1E2D3C4-B5A6-7890-1234-567890ABCDEF</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  <key>PayloadDisplayName</key>
  <string>Network Weather - IT Policy</string>
</dict>
</plist>

Override Priority (highest to lowest)

Priority	Source	User-writable?
1 (highest)	MDM managed preferences	No
2	`~/.nwx/config.json`	Yes
3 (lowest)	Built-in defaults	—

Deploying Config Files

Pre-install (Recommended)

Place the config file before installing the application:

mkdir -p ~/.nwx
cp config.json ~/.nwx/config.json

Via MDM

Deploy the file to each user's home directory:

/Users/<username>/.nwx/config.json

Or use Managed Preferences via a .mobileconfig profile for settings that should be enforced by IT policy.

Validation & Error Handling

Missing file: Not an error — all defaults used
Invalid JSON: Logged as error to stderr, defaults used
Unknown keys: Silently ignored (forward-compatible)
Active overrides: Logged to stderr on startup (e.g., Active config overrides: logLevel, disableSparkle)