macOS Installation

macOS Installation

ZenTune operates on macOS for AMD Ryzen Hackintosh environments (APUs and desktop processors). Because macOS lacks a /sys virtual filesystem and forbids unauthenticated userland PCI configuration access, ZenTune communicates with the processor SMU via kernel extensions or authorized IOKit bridge drivers.

---

1. System requirements

Verify host compatibility before proceeding:

• Platform: macOS 11 Big Sur through macOS 26 Tahoe running on an AMD Ryzen processor (Zen 1 through Zen 5 architectures). Apple Silicon and Intel systems are unsupported.
• Privilege elevation: Administrator credentials via sudo. Systemd run0 is Linux-specific; macOS unconditionally uses sudo.
• Python runtime: Python 3.10 or newer (python3 --version).
• Terminal emulator: Minimum terminal window dimensions of 50 columns by 25 rows.
• SMU access layer: One of two supported hardware access paths must be active:
  1. DirectHW (Priority 1, Recommended): DirectHW.kext loaded with System Integrity Protection (SIP) configured to permit third-party kernel extensions (csr-active-config = 03080000). Enables SMU mailbox tuning and physical memory mapping for raw PM table inspection via zenmaster --sensors / zenmaster --table CLI. Note that Home tab sensor plots in the TUI are Linux-only (active = [] on macOS in homeView.py); the Home tab displays only the navigation menu on macOS.
  2. IOPCIBridge Kext-Free Fallback (Priority 2, Tuning Only): Runs zenmaster.iopci requiring the debug=0x144 kernel boot argument. Functions without kernel extensions. Supports full frequency, power, and curve tuning, but cannot map physical memory.

Adaptive Mode and Linux-specific platform controls (ASUS WMI, power-profiles-daemon, CCD affinity) are unavailable on macOS. Preset application, Custom Preset editing, Automations, and periodic reapply loops operate identically to Linux.

---

2. Setting up SMU access backends

ZenTune inspects available SMU backends on startup in Assets/core/hardware.py:

1. zenmaster.directhw.is_loaded()  --> If active, use DirectHW (tuning + CLI telemetry)
2. zenmaster.iopci.is_available()  --> If debug=0x144 in boot-args, use IOPCIBridge (tuning only)
3. Neither found                   --> Refuse launch with "No SMU access path is available"

2.1 Option A: DirectHW (Recommended for SMU tuning & CLI telemetry)

DirectHW maps physical memory ranges, allowing zenmaster to poll the SMU Power Management (PM) table via CLI (zenmaster --sensors) for raw clock, wattage, and temperature readouts. Note that Home tab sensor plots in the TUI are Linux-only (active = [] on macOS in homeView.py).

1. Download and deploy DirectHW.kext into your OpenCore EFI/OC/Kexts/ directory and register it in config.plist under Kernel -> Add.
2. Configure System Integrity Protection (SIP) to permit third-party kexts:
   • In OpenCore config.plist, navigate to NVRAM -> Add -> 7C436110-AB2A-4BBB-A880-FE41995C9F82.
   • Set csr-active-config to <03080000> (Data).
3. Reboot the machine.
4. Verify that the extension is active:

   kextstat | grep -i directhw

   The output should list com.coresystems.DirectHW or equivalent identifier.

---

2.2 Option B: Kext-free fallback via IOPCIBridge

If you prefer not to lower SIP or run non-Apple kernel extensions, ZenTune can access PCI configuration registers through the IOKit IOPCIBridge user client using zenmaster.iopci.

1. Append debug=0x144 to your kernel boot arguments:
   • In OpenCore config.plist, navigate to NVRAM -> Add -> 7C436110-AB2A-4BBB-A880-FE41995C9F82 -> boot-args.
   • Add debug=0x144 alongside existing flags (e.g., keepsyms=1 alcid=1 debug=0x144).
2. Reboot the system.
3. Confirm the kernel argument registered:

   sysctl kern.bootargs

   Verify that debug=0x144 appears in the output string.

Note

When using zenmaster.iopci, hardware tuning (applying limits, curve optimizer offsets, and Premade presets) functions completely. However, because physical memory mapping is restricted, CLI PM table inspection (zenmaster --sensors) is unavailable. Note that in the ZenTune TUI, Home tab live sensor graphs are Linux-only on all backends.

---

3. Install ZenTune

Run the installation script in a standard user terminal session:

curl -fsSL https://raw.githubusercontent.com/HorizonUnix/ZenTune/main/install.sh | bash

Do not execute the installer under root. The script requests sudo credentials only when configuring system paths.

What the installer performs:

1. Detects Darwin kernel architecture.
2. Checks for prerequisites (curl, unzip, Python 3.10+).
3. Extracts application code to /opt/zentune/src/.
4. Creates an isolated virtual environment at /opt/zentune/venv/ with dependencies (pyzmq, textual, textual-plotext, zenmaster).
5. Generates the executable launcher script at /usr/local/bin/zentune.
6. Assigns ownership of /opt/zentune to your user account to facilitate unprivileged config management.

To install from a local repository checkout instead of downloading a release archive:

git clone https://github.com/HorizonUnix/ZenTune.git
cd ZenTune
./install.sh --local

---

4. First run & launchd service registration

Start ZenTune:

zentune

The initial launch opens the three-step configuration wizard:

1. Welcome: Verifies terminal capabilities and dimensions. Select Begin setup.
2. Background daemon: Select Install / enable daemon. ZenTune requests your administrator password via sudo and provisions the system launchd service unit:
   • Service label: com.horizonunix.zentune
   • Property list file: /Library/LaunchDaemons/com.horizonunix.zentune.plist
   • Standard output and error logs: /var/log/zentune.log
   • IPC socket address: ipc:///var/run/zentune.sock (mode 0o666)
   • Auto-restart: KeepAlive: SuccessfulExit = false
3. Hardware detection: Probes processor family, stepping, and SMU architecture via zenmaster. Once verified, select Finish.

---

5. Interface overview on macOS

On macOS, platform-incompatible features are hidden automatically:

• The Adaptive Mode tab and its settings are suppressed.
• The System controls (power-profiles-daemon, ASUS WMI, CCD core affinity) are suppressed.
• All core tuning functions remain active: Premade (1), Custom (2), Auto (4), Info (5), Status (6), and Settings (7).

---

6. Updating

When updates are published, ZenTune flags them during startup.

• In-app update: Select About (?) -> Check updates -> Update now.
• Command-line update: Re-execute the installer:

  curl -fsSL https://raw.githubusercontent.com/HorizonUnix/ZenTune/main/install.sh | bash

Your custom presets (/opt/zentune/src/Assets/custom.json) and configuration values (config.ini) persist across updates.

---

7. Uninstalling

To remove ZenTune completely:

curl -fsSL https://raw.githubusercontent.com/HorizonUnix/ZenTune/main/install.sh | bash -s -- --uninstall

To run without confirmation prompts in automated deployment scripts:

ZENTUNE_ASSUME_YES=1 bash install.sh --uninstall

The uninstaller purges:

• LaunchDaemon definition: /Library/LaunchDaemons/com.horizonunix.zentune.plist
• Binary wrapper: /usr/local/bin/zentune
• Application files and venv: /opt/zentune
• Runtime socket and daemon lock: /var/run/zentune.sock, /var/run/zentune_daemon.lock
• Client lock: /tmp/zentune_tui.lock