Client Configuration

Network Weather can be configured via a JSON file at ~/.nwx/config.json. All settings are optional — if no config file exists, the app uses built-in defaults.

Config File Location

Platform	Path
macOS	~/.nwx/config.json

Create the directory and file:

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

---

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.

---

Example Config

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

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

---

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)