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

> Manually control Mac fan speeds with vorssaint-utils. Explore the optional Fan Control beta feature for direct adjustments via privileged helper daemon and Swift APIs.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-09

---

**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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/main.swift).

### Policy and Configuration Layers

**FanControlPolicy** ([`Sources/Vorssaint/Services/FanControlPolicy.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```swift
import Vorssaint

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

```

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

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

```

Alternatively, define a custom temperature response curve:

```swift
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:

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/FanControlPolicy.swift) and corresponding tests at line 14900 of [`MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/main.swift) (daemon entry point), [`Sources/Vorssaint/Services/FanControlPolicy.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/FanControlPolicy.swift) (validation logic), and [`Sources/Vorssaint/Services/FanControlConfiguration.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/FanControlConfiguration.swift) (settings persistence). The build script at [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureRuntime.swift), which ensures the process only runs when the feature is actively enabled, optimizing system resources.