Skip to content

Configuration

Jump to bottom
Le Khanh Binh edited this page Sep 13, 2026 · 2 revisions

Configuration

ZenTune stores its configuration in Assets/config.ini, generated automatically during the initial setup wizard.

Standard install location:

/opt/zentune/src/Assets/config.ini

On macOS, the source installation resides at the same path (/opt/zentune/src/Assets/config.ini), but the runtime socket and daemon PID lock directory use /var/run instead of Linux /run.

All configuration writes from the application are atomic: settings are written to a unique temporary file in the target directory, flushed to disk via os.fsync(), and atomically swapped into place via os.replace().

Canonical Schema

The configuration parser writes sections in a strict canonical order: [User], [Settings], [Automations], [Adaptive], and [Info]. Any custom or unrecognized sections appended to the file are preserved at the end during serialization.

Example config.ini 

[User]
mode = Balanced

[Settings]
time = 3
reapply = 0
applyonstart = 1
autostartadaptive = 0
softwareupdate = 1
debug = 0
defaulttab = home
privilegetool = auto
theme = textual-dark

[Automations]
onac =
onbattery =
onresume =

[Adaptive]
preset =
interval = 2

[Info]
cpu = AMD Ryzen 7 7840HS with Radeon 780M Graphics
signature = Family 25, Model 116, Stepping 1
architecture = Zen 3 - Zen 4
family = PhoenixPoint
type = Amd_Apu
variant =

[User]

The [User] section controls the currently active power and performance preset.

Key Type Description
mode string Active preset name. Accepts built-in tiers (Eco, Balanced, Performance, Extreme) or custom preset names.

Built-in Presets

Preset Target Behavior
Eco Reduces power limits, minimizes fan noise, and optimizes thermal margins for battery operation.
Balanced Balanced daily profile matching factory sustained operating points.
Performance Elevated sustained power limits (STAPM/Fast/Slow or PPT/TDC/EDC) for compute-intensive workloads.
Extreme Maximum platform power limits within platform thermal and VRM electrical safety boundaries.

Custom presets configured in the editor are saved into custom.json. When referenced inside config.ini, custom preset identifiers use a _custom_preset suffix internally, though the user interface renders the plain display name. Refer to Custom Presets for parameter options.

[Settings]

The [Settings] section governs daemon execution loops, startup behaviors, UI themes, and privilege escalation methods.

Key Default Values Description
time 3 1 to 86400 Reapply timer interval in seconds. Clamped strictly between 1 and 86400 seconds (1s to 24h) by parse_interval().
reapply 0 0 or 1 Enables background timer loop to periodically re-assert preset parameters.
applyonstart 0 0 or 1 Instructs the background daemon to apply the saved preset when the system service boots.
autostartadaptive 0 0 or 1 Instructs the daemon to launch the saved Adaptive Mode profile on service startup. Linux only.
softwareupdate 1 0 or 1 Checks GitHub for updated releases when the terminal interface initializes.
debug 0 0 or 1 Enables verbose debug logging in the daemon and displays build metadata in the interface header.
defaulttab home string Starting tab on launch: home, power, custom, adaptive, automations, hardware, status, settings.
privilegetool auto auto, sudo, run0 Privilege escalation tool used for service operations. auto detects sudo first, then run0. macOS always uses sudo.
theme textual-dark string Textual interface theme identifier (e.g. textual-dark, textual-light).

Loop and Automation Interactions

  • applyonstart vs TUI: The TUI client applies the currently configured preset when launched. Setting applyonstart = 1 ensures the headless systemd service or launchd daemon asserts hardware limits even if no user logs into the graphical interface.
  • reapply Execution: When enabled, the daemon executes _apply_once() every time seconds. If power automation slots are populated (onac or onbattery), the reapply loop evaluates the power state each cycle and switches profiles if power source state changed.
  • Reapply Time Clamping: Values passed to time are strictly clamped between 1 second and 86400 seconds. Out-of-range values or malformed input revert to the 3-second default.

[Automations]

The [Automations] section maps power state events to specific preset names.

Key Default Values Description
onac (empty) preset name Preset applied when AC power connects. Mapped to Preset on Battery Charge in the interface.
onbattery (empty) preset name Preset applied when discharging on battery. Mapped to Preset on Battery Discharge in the interface.
onresume (empty) preset name Preset applied once whenever system wakes from sleep, suspend, or hibernation.

Operational Rules

  • Activation: Automations do not require a separate master toggle. Setting a preset name in onac or onbattery activates the power-state monitor thread. Leaving a slot blank preserves whatever preset was already active when that event occurs.
  • Anti-Flap Delay: The power monitor enforces a 3.0-second cooldown (time.monotonic() - last_smu_apply < 3.0) between successive hardware writes to prevent rapid toggling when connecting chargers.
  • Resume Delay: Following system wake from suspend or hibernation, the suspend monitor pauses for 5.0 seconds (_POST_SUSPEND_WAIT_S = 5.0) before applying the onresume preset. This delay permits kernel ACPI subsystems, embedded controllers, and CPU clocks to stabilize.
  • Refer to Automations for monitoring loop implementation details.

[Adaptive]

The [Adaptive] section configures the dynamic hardware tuning loop. Parameter definitions and target values are stored separately in adaptive.json.

Key Default Values Description
preset (empty) preset name Identifier of the active adaptive tuning preset stored in adaptive.json.
interval 2 1 to 8 seconds Evaluation frequency in seconds. Clamped strictly between 1 and 8 seconds by the daemon loop.

Platform Restrictions

Adaptive Mode operates exclusively on Linux. The feature relies on Linux-specific sysfs sensors, hwmon interfaces, and dynamic governor adjustments. On macOS, the Adaptive tab and associated configuration options are disabled.

When active, the daemon writes a session marker file to {RUNTIME_DIR}/zentune_adaptive. Refer to Adaptive Mode for algorithm details.

[Info]

The [Info] section records CPU architecture and board identifiers detected during system initialization. The zenmaster library populates these fields by inspecting /proc/cpuinfo and kernel sysfs nodes on Linux, or CPUID sysctl values on macOS.

Key Description
cpu Full processor model string reported by hardware.
signature CPUID signature string containing Family, Model, and Stepping.
architecture Zen architecture generation (e.g. Zen 3 - Zen 4, Zen 5 - Zen 6).
family AMD processor codename (e.g. Rembrandt, PhoenixPoint, StrixPoint, Raphael).
type Processor package classification: Amd_Apu, Amd_Desktop_Cpu, or Intel.
variant Hardware variant identifier for device-specific presets. Defaults to empty for generic systems.

Framework Laptop Variant Detection

ZenTune detects specific laptop models by evaluating /sys/class/dmi/id/sys_vendor and product_name. The detected string is written to variant:

  • AMDFrameworkLaptop16Ryzen7040_RX7700S: Framework Laptop 16 equipped with dedicated AMD Radeon RX 7700S graphics.
  • AMDFrameworkLaptop16Ryzen7040: Framework Laptop 16 using integrated Radeon 780M graphics.
  • AMDFrameworkLaptop13Ryzen7040_RyzenAI300: Framework Laptop 13 powered by AMD Ryzen 7040 or Ryzen AI 300 series processors.

If you clear the variant field (variant = ), ZenTune disables the hardware-specific preset table and falls back to generic processor family power profiles.

To override hardware classification manually, select Settings (7) -> Edit CPU info in the interface.

Daemon Management Across Platforms

The ZenTune daemon requires root privileges to interact with SMU mailboxes and kernel sysfs nodes. Depending on the operating system, service lifecycles are handled through platform-native init systems or direct invocation.

Linux: systemd

The service unit is installed at /etc/systemd/system/zentune.service.

# Check service status
systemctl status zentune.service

# Restart service
sudo systemctl restart zentune.service
# Or with systemd-run0:
run0 systemctl restart zentune.service

# View daemon journal logs
journalctl -u zentune.service -n 50 --no-pager

macOS: launchd

The launch daemon configuration resides at /Library/LaunchDaemons/com.horizonunix.zentune.plist.

# Check service status
sudo launchctl print system/com.horizonunix.zentune

# Kickstart daemon
sudo launchctl kickstart -k system/com.horizonunix.zentune

# View daemon output log
tail -n 50 /var/log/zentune.log

Manual Console Execution

For systems running alternative init systems (such as OpenRC, runit, or s6), or for interactive debugging sessions, launch the daemon directly from a root terminal:

# Using sudo:
sudo /opt/zentune/venv/bin/python3 /opt/zentune/src/Assets/daemon/daemon.py

# Using run0 on systemd systems:
run0 /opt/zentune/venv/bin/python3 /opt/zentune/src/Assets/daemon/daemon.py

Configuration Reset

To reset configuration files to clean factory defaults:

  1. Inside Interface: Navigate to Settings (7) and select Reset all settings. The application wipes config.ini, custom.json, and adaptive.json, then prompts the setup wizard.
  2. Terminal Execution:
rm /opt/zentune/src/Assets/config.ini
zentune

Report an issue · Releases

Home

Getting started

Using the app

Internals

Clone this wiki locally