# How the Fan Control Helper Is Managed in vorssaint-utils: XPC Service Architecture Explained

> Discover how the fan control helper in vorssaint-utils uses a privileged XPC service with file locks and watchdog timers to manage fan speeds securely and efficiently.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: internals
- Published: 2026-09-08

---

**The fan control helper in vorssaint-utils is a privileged XPC service that runs as root and mediates all fan-speed operations through a file-based locking mechanism, watchdog timers, and secure inter-process communication.**

The vorssaint-utils repository provides a low-level macOS utility suite for hardware management, with its **fan control helper** serving as a critical privileged component that bridges unprivileged client applications with the System Management Controller (SMC). Unlike direct hardware access, this helper implements a robust safety architecture to ensure only one process controls fans at a time and automatic control is restored if clients disconnect unexpectedly.

## Core Components of the Fan Control Helper Architecture

The helper’s implementation lives primarily in [`Sources/FanControlHelper/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/main.swift) and is structured around three coordinated subsystems that manage access, state, and communication.

### FanControlController: Central Orchestration Engine

The `FanControlController` class serves as the primary state machine for manual fan operations. It maintains the current **owner UUID**, cooling level, active configuration, and an internal watchdog timer. According to the source code, this controller handles four primary operations: `applyConfiguration`, `heartbeat`, `restoreAutomatic`, and the legacy `startLegacySession`.

When a session starts, the controller coordinates with `FanControlOwnership` to acquire an exclusive lock and create a marker file at `/var/run/vorssaint-fan-control.active`. It also initializes a `DispatchSourceTimer` that triggers `watchdogTick` every second to monitor fan integrity and temperature trends.

### FanControlOwnership: Secure Lock Management

To prevent race conditions between multiple applications, the helper implements `FanControlOwnership` using **file-based locking**. The mechanism opens `/var/run/vorssaint-fan-control.lock` with `O_EXCL` flags and applies `flock` (exclusive, non-blocking) to guarantee atomic access.

The ownership validator ensures both the lock file and marker file are regular files owned by root with mode `0600`, preventing privilege escalation attacks. If acquisition fails, the controller returns `.failure(.alreadyControlled)` immediately, ensuring only one manual control session exists system-wide.

### XPC Communication Layer

The `FanControlListenerDelegate` and `FanControlSession` classes expose the `FanControlXPCProtocol` to client applications. When a client connects, the delegate creates a new `FanControlSession` instance and registers an **invalidation handler** that notifies `FanControlController` when the connection drops.

This layer tracks active connection counts so the helper can invoke `scheduleExitIfIdle` to terminate gracefully when no clients remain. The mach service name is defined in [`Sources/FanControlHelper/FanControlIdentifiers.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/FanControlIdentifiers.swift), which also specifies code-signing requirements for the privileged helper tool registered via `Resources/com.vorssaint.utils.fan-control.plist`.

## Session Lifecycle and Safety Mechanisms

### Startup and Privilege Verification

Upon launch, the helper verifies it executes as root by checking `geteuid() == 0`. It then instantiates a singleton `FanControlController` and creates an `NSXPCListener` bound to the mach service identifier. Signal handlers for `SIGTERM` and `SIGINT` route to `controller.shutdown` to ensure automatic fan control restoration during forced termination.

### Session Control and Heartbeat Protocol

Clients initiate control by calling `applyConfiguration` with a serialized `FanControlConfiguration` object specifying cooling levels 0–5. The controller validates the request, acquires the ownership lock, and delegates hardware operations to `FanControlHardware` (abstracted in [`Sources/FanControlHelper/FanControlHardware.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/FanControlHardware.swift)).

To prevent timeout-based restoration during active use, clients must send periodic heartbeats that reset the internal `lastHeartbeatUptime` timestamp. Missing heartbeats trigger the watchdog to invoke `performRestore`, which returns fans to automatic control.

### Watchdog Timer and Automatic Recovery

Every second, the `watchdogTick` method evaluates fan status, temperature trends, and timeout conditions. If the controller detects hardware anomalies or expired heartbeats, it automatically executes `performRestore`. This safety mechanism ensures that even if the client application crashes without calling `restoreAutomatic`, the system returns to thermal self-management.

### Graceful Shutdown

When XPC connections close and cooling is inactive, `scheduleExitIfIdle` schedules an `exit(EXIT_SUCCESS)`. The shutdown sequence attempts a clean restore of automatic fan control before termination, though the watchdog provides redundancy if this fails.

## Practical Code Examples

The following patterns demonstrate common interactions with the fan control helper from both the service and client perspectives.

```swift
// Acquire exclusive lock and create active session marker
guard ownership.acquire() else { 
    return .failure(.alreadyControlled) 
}
guard ownership.createMarker() else {
    ownership.release()
    return .failure(.controlFailed)
}

```

```swift
// Apply manual cooling configuration from client application
let sessionID = UUID()
let configuration = FanControlConfiguration.manual(level: 3)   // level 0-5
let data = FanControlIPC.encode(configuration)

helper.applyConfiguration(data) { responseData in
    let response = FanControlIPC.decodeResponse(responseData)
    // Handle .success or .failure cases
}

```

```swift
// Maintain session liveness via heartbeat
helper.heartbeat { responseData in
    // Resets internal timeout counters to prevent automatic restoration
}

```

```swift
// Explicitly restore automatic fan control
helper.restoreAutomatic { responseData in
    // Returns .success when automatic SMC control is re-enabled
}

```

## Summary

- The **fan control helper** operates as a root-privileged XPC service in vorssaint-utils, mediating between unprivileged apps and SMC hardware.
- **Exclusive access** is enforced via `FanControlOwnership` using file locks at `/var/run/vorssaint-fan-control.lock` with `O_EXCL` and `flock` semantics.
- **Safety mechanisms** include a one-second watchdog timer (`DispatchSourceTimer`) that automatically restores automatic fan control if clients disconnect or heartbeats expire.
- All implementation resides in [`Sources/FanControlHelper/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/main.swift), with hardware abstraction in [`FanControlHardware.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FanControlHardware.swift) and service identifiers in [`FanControlIdentifiers.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FanControlIdentifiers.swift).

## Frequently Asked Questions

### Why does the fan control helper require root privileges?

The helper requires root access because macOS restricts SMC (System Management Controller) registers to root-only processes. The XPC architecture allows unprivileged applications to request fan speed adjustments safely while the privileged helper performs the actual hardware writes, following Apple's modern security model for privileged helper tools.

### How does vorssaint-utils prevent multiple applications from controlling fans simultaneously?

The system uses `FanControlOwnership` to implement **file-based locking** with exclusive, non-blocking flock operations on `/var/run/vorssaint-fan-control.lock`. If another process already holds the lock, subsequent `acquire()` attempts return `.failure(.alreadyControlled)`, ensuring deterministic single-controller semantics.

### What happens if the client application crashes during manual fan control?

The watchdog timer (`watchdogTick`) detects missed heartbeats or connection invalidation through the XPC session’s invalidation handler. Upon detection, it automatically invokes `performRestore` to return fans to automatic control, preventing thermal damage from stalled manual settings.

### Where is the fan control helper tool registered with macOS?

The launch agent configuration is stored in `Resources/com.vorssaint.utils.fan-control.plist`, which registers the helper as a privileged XPC service. The mach service identifier is defined in [`Sources/FanControlHelper/FanControlIdentifiers.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/FanControlIdentifiers.swift), ensuring proper code-signing validation during the XPC connection establishment.