How to Manually Control Fan Speeds with vorssaint-utils: A Complete Guide

Yes, vorssaint-utils includes an optional "Fan Control" beta feature that enables direct manual control of Mac fan speeds through a privileged helper daemon and Swift-based configuration APIs.

The vorssaint-utils repository provides sophisticated hardware management capabilities for macOS, including the ability to override automatic thermal management. The manual fan speed control functionality is implemented as an opt-in beta subsystem that communicates directly with the System Management Controller (SMC) to set custom RPM values or temperature-based curves.

Enabling the Fan Control Beta Feature

The fan control subsystem is gated behind the AppFeature.fanControl feature flag, which defaults to disabled according to the test suite in Tests/MetricsTests.swift at line 14737. To access manual controls, users must explicitly enable the beta through the Settings UI or programmatically via the Swift API.

When activated, the main application coordinates with FeatureRuntime.swift to load the helper daemon only when needed, ensuring the privileged process runs exclusively during active fan management sessions. This architecture minimizes security exposure while providing full hardware access.

Architecture of the Fan Control System

The implementation spans multiple specialized components that handle privilege escalation, policy validation, and user interface interactions.

The Fan Control Helper Daemon

At the core lies com.vorssaint.utils.fan‑control, a privileged helper daemon compiled and signed by the build script at line 461 of build.sh. This executable holds the necessary entitlements to read from and write to the SMC fan registers, operations that require root-level permissions on macOS.

The daemon is registered with launchd through Resources/com.vorssaint.utils.fan‑control.plist, with the build process using /usr/libexec/PlistBuddy to clean legacy entries during reinstallation. The main entry point resides in Sources/FanControlHelper/main.swift.

Policy and Configuration Layers

FanControlPolicy (Sources/Vorssaint/Services/FanControlPolicy.swift) contains the pure-Swift logic governing safety validations, including:

• Fan count verification
• RPM bounds checking
• Manual level calculations
• Temperature-to-RPM curve interpolation

All safety constraints are exercised in MetricsTests.swift around line 14900, ensuring that user-defined curves cannot specify dangerous operating points.

FanControlConfiguration handles JSON serialization of user preferences, storing custom curves and manual mode settings for persistence between application launches.

Menu Bar Integration

When enabled, the system displays live RPM values via FanControlPolicy.menuBarValue, with visual width adjustments based on fan count through menuBarWidthUnits. These properties are validated in MetricsTests.swift at line 15055, ensuring accurate real-time monitoring.

Setting Manual Fan Speeds Programmatically

Developers can interact with the fan control system directly through the vorssaint-utils Swift APIs after enabling the feature flag.

Enable the subsystem and launch the helper daemon:

import Vorssaint

// Enable the beta feature (typically done through Settings UI)
AppFeature.fanControl.enable()

Set a continuous manual speed at 50% of maximum RPM:

// Direct manual control
FanControlPolicy.setManualLevel(percentage: 50)

Alternatively, define a custom temperature response curve:

let curve = FanControlCurve(
    sensor: .hottestSoC,
    points: [
        FanControlCurvePoint(temperature: 40, coolingLevel: 0),
        FanControlCurvePoint(temperature: 80, coolingLevel: 80)
    ]
)
FanControlConfiguration.saveCurves([curve])

Retrieve current fan speeds for display purposes:

if let rpms = FanControlPolicy.currentRPMs() {
    print("Current fan RPMs:", rpms)
}

Configuration and Safety Mechanisms

The UI panel exposed in Settings provides a "Manual mode" toggle, an RPM slider for direct control, and a visual curve editor for temperature-based automation. All user inputs pass through FanControlPolicy validation before reaching the SMC.

The system enforces hard limits on minimum and maximum RPM values to prevent hardware damage, with the test suite verifying boundary conditions. When the user disables the feature, FeatureRuntime.swift unloads the helper daemon from launchd, immediately returning thermal management to macOS defaults.

Summary

• vorssaint-utils can control fan speeds manually, but only after explicitly enabling the opt-in Fan Control beta.
• The system uses a privileged helper daemon (com.vorssaint.utils.fan‑control) installed by build.sh to communicate with SMC registers.
• FanControlPolicy enforces safety bounds and calculates RPM values, while FanControlConfiguration persists user settings.
• Manual mode supports both fixed percentage-based speeds and custom temperature curves defined through Swift APIs.
• The feature is fully tested in MetricsTests.swift, covering policy validation, curve mathematics, and menu-bar rendering.

Frequently Asked Questions

How do I enable manual fan control in vorssaint-utils?

Navigate to the Settings window and select the Fan Control tab, then toggle the beta feature on. This activates the AppFeature.fanControl flag and launches the com.vorssaint.utils.fan‑control helper daemon via launchd. The feature defaults to off for security reasons, as confirmed by unit tests in MetricsTests.swift.

Can I damage my Mac by setting fan speeds too low?

No. The FanControlPolicy class enforces hardware-specific RPM minimums and maximums before sending commands to the SMC. According to the source in FanControlPolicy.swift and corresponding tests at line 14900 of MetricsTests.swift, the system prevents submission of values outside safe operating parameters, ensuring hardware protection even in manual mode.

What files handle the fan control functionality?

The primary components reside in Sources/FanControlHelper/main.swift (daemon entry point), Sources/Vorssaint/Services/FanControlPolicy.swift (validation logic), and Sources/Vorssaint/Services/FanControlConfiguration.swift (settings persistence). The build script at build.sh line 461 compiles and signs the helper with required entitlements.

Does manual fan control persist after restarting vorssaint-utils?

Yes. FanControlConfiguration serializes your curves and manual mode settings to JSON, automatically restoring your preferences on application launch. However, the helper daemon itself is managed by FeatureRuntime.swift, which ensures the process only runs when the feature is actively enabled, optimizing system resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}