Summary

Introduce a config.system.json file that acts as an admin-managed baseline configuration. User settings in config.json override system defaults key-by-key, giving admins control over defaults while preserving user autonomy.

Motivation

Currently, all configuration lives in ~/.mux/config.json and is fully user-controlled. There is no mechanism for administrators to provide a baseline configuration (e.g., default providers, approved models, feature flags, runtime settings) that applies across all users in a managed deployment.

A system config layer would allow admins to:

• Set organization-wide defaults (providers, models, feature flags)
• Enforce baseline settings while still allowing user overrides on a per-key basis
• Simplify onboarding by pre-configuring sensible defaults

Proposed Behavior

1. Admin provides a config.system.json file (e.g., at ~/.mux/config.system.json or a system-wide path like /etc/mux/config.system.json).
2. On load, the Config class reads config.system.json first as the baseline.
3. User's config.json is then deep-merged on top, overriding the system config key-by-key.
4. Writes continue to go to the user's config.json only — the system file is read-only from Mux's perspective.

Merge semantics

• Shallow or deep merge at the top-level keys (e.g., featureFlagOverrides, taskSettings, provider defaults).
• User-set keys always win over system keys.
• Keys absent from the user config fall through to the system config.

Implementation Notes

• The current config loading lives in src/node/config.ts in the Config class. loadConfigOrDefault() reads ~/.mux/config.json — this is the primary integration point.
• The system config file path could be configurable via an env var (e.g., MUX_SYSTEM_CONFIG) with a sensible default.
• The AppConfigOnDisk schema in src/common/config/schemas should apply to both files.

Created on behalf of @ibetitsmike