Safe, observable fan control for Linux laptops — one supervisor, a clear terminal UI and a scriptable CLI.
NeoSense is a Rust application that puts a practical, safety-first interface on top of NBFC (Notebook FanControl). It adds automatic, preset and manual fan modes, temperature-driven profiles, a Ratatui terminal UI and structured JSON output — while keeping every fan write behind a single supervised backend with leases, verification and automatic recovery.
Relationship to NBFC. NeoSense does not replace NBFC. NBFC still owns the embedded controller, the laptop configuration and the vendor critical-temperature behavior. NeoSense owns the user workflow and the safety policy in front of it.
Stable release: v2.4.0 (published 2026-11-19). Linux only; there are no Windows or macOS builds.
███╗ ██╗ ███████╗ ██████╗ ███████╗ ███████╗ ███╗ ██╗ ███████╗ ███████╗
████╗ ██║ ██╔════╝ ██╔═══██╗ ██╔════╝ ██╔════╝ ████╗ ██║ ██╔════╝ ██╔════╝
██╔██╗ ██║ █████╗ ██║ ██║ ███████╗ █████╗ ██╔██╗ ██║ ███████╗ █████╗
██║╚██╗██║ ██╔══╝ ██║ ██║ ╚════██║ ██╔══╝ ██║╚██╗██║ ╚════██║ ██╔══╝
██║ ╚████║ ███████╗ ╚██████╔╝ ███████║ ███████╗ ██║ ╚████║ ███████║ ███████╗
╚═╝ ╚═══╝ ╚══════╝ ╚═════╝ ╚══════╝ ╚══════╝ ╚═╝ ╚═══╝ ╚══════╝ ╚══════╝
- Why NeoSense
- How it works
- Capabilities
- Install
- First run
- Everyday use
- Terminal UI
- Safety model
- Diagnostics
- Supported platforms
- Known limitations
- Documentation
- Development
- Everyday control in one command.
neosense silent,balanced,maximumorauto— or pick a mode from the TUI Dashboard. - One writer. Only the root
neosensedsupervisor talks to NBFC and hardware. The CLI and TUI use a local JSON protocol and are read-only when the supervisor is unavailable. - Honest telemetry. Requested target, backend-accepted target, EC readback
and physical response are separate concepts. Missing or stale sensors are
unavailable, never0 °C; EC percentages are never presented as RPM. - Fail-safe by design. Fixed targets are leases. Lease expiry, stale telemetry, NBFC critical mode, failed verification or a supervisor crash returns fans to NBFC automatic mode. A failed recovery is reported and retried a bounded number of times.
- Policy-gated profiles. Quiet, Balanced and Performance curves are applied per fan only when mapping, temperatures and backend guarantees allow it; blocked fans stay automatic and are reported with reasons.
- One install entry point.
neosense.shdetects the distribution, checks versioned dependencies, reports backend/controller conflicts and verifies the result. It never rewrites NBFC configuration or stops another controller.
neosense (CLI) ──┐
neosense tui ─┴── Unix JSON IPC ──► neosensed (root, sole writer)
├── sensor registry (hwmon/thermal/NVIDIA)
├── NBFC backend
├── safety policy, leases, verification
└── systemd READY / WATCHDOG / STOPPING
- The CLI (
neosense) and TUI (neosense tui) read state from the supervisor and never collect hardware data or invoke NBFC for live values. - The supervisor (
neosensed) is the only NBFC client and the only fan writer. It runs as a systemd service with a watchdog and anExecStopPostfail-safe. - The shell installer only handles installation, removal and systemd integration.
| Area | What you get |
|---|---|
| Modes | Auto (NBFC curve), Silent 25%, Balanced 60%, Maximum 100% |
| Manual control | CPU, GPU or both logical fans, 20–100%, with confirmation |
| Profiles | Quiet / Balanced / Performance closed loops and persistent custom curves |
| Leases | 15-minute manual/preset lease with supervisor-verified recovery |
| Interfaces | Ratatui TUI, human CLI, stable --json output, shell completions |
| Diagnostics | Read-only diagnose, control readiness, hardware identity, validation history |
| Service | systemd Type=notify, watchdog, sandboxing, root-owned IPC socket |
- Linux with systemd and hwmon/thermal sensors.
x86_64is the tested target. - A configured NBFC installation, 0.5.4 or newer for protected manual control
(0.5.3 supports read-only diagnostics and
auto). sudofor installation. Rust/Cargo 1.85+ is needed only for source builds.- For the socket, your user must join the
neosensegroup after installation.
Download both assets from the latest release, verify the checksum, extract and install:
VERSION=2.4.0
curl -LO "https://github.com/NeonMC23/NeoSense/releases/download/v${VERSION}/neosense-${VERSION}-x86_64-unknown-linux-gnu.tar.gz"
curl -LO "https://github.com/NeonMC23/NeoSense/releases/download/v${VERSION}/SHA256SUMS"
sha256sum -c SHA256SUMS
tar -xzf "neosense-${VERSION}-x86_64-unknown-linux-gnu.tar.gz"
cd "neosense-${VERSION}-x86_64-unknown-linux-gnu"
sudo ./neosense.shRun the installer only from a trusted checkout or a checksum-verified archive: it executes bundled shell modules and package-manager operations as root.
git clone https://github.com/NeonMC23/NeoSense.git
cd NeoSense
sudo ./neosense.shneosense.sh detects the host, checks dependencies, prepares a supported backend
when possible, installs the software and runs a read-only verification. Useful
options:
--dry-run show privileged actions without performing them
--yes authorize package and software installation non-interactively
--software-only install without a ready fan backend; does not start control
--no-start do not enable or start the supervisor
--no-restart leave an already-running supervisor untouched
--install-backend allow a distro NBFC package install (explicit consent)
A missing or incompatible backend stops the default install before NeoSense
software changes. The installer never downloads arbitrary upstream scripts and
never modifies NBFC configuration. See docs/INSTALL.md for
the full dependency matrix, distribution status and recovery rules.
# Join the service group, then start a new login session.
sudo usermod -aG neosense "$USER"
# log out and back in, or: newgrp neosense
# If the installer did not start the service (e.g. --no-start):
sudo systemctl enable --now neosensed
neosense service status
neosense status
neosense tuineosense service status distinguishes healthy, degraded, permission-denied,
not-running and stale-socket states. Without the group, the CLI can read local
files but cannot reach the supervisor socket.
neosense auto # return all fans to NBFC automatic mode
neosense silent --yes # fixed 25% on both logical fans
neosense balanced --yes # fixed 60%
neosense maximum --yes # fixed 100%Silent, Balanced and Maximum are fixed logical targets, not hidden temperature curves. They use the same policy, backend verification and 15-minute lease as manual control. A fixed target is a backend percentage, not physical RPM.
neosense set cpu 50 --yes # one logical channel
neosense set gpu 50 --yes
neosense set both 50 --yes # both channels, all-or-nothing preflight
neosense auto fan 0 # return one fan to automatic
neosense auto # return all fans to automaticManual targets are bounded to 20–100%; 0% is refused. The supervisor preflights every requested fan and refuses the operation when the safety policy cannot establish a safe state. A mid-operation backend failure is reported as a structured partial failure and triggers automatic recovery.
Profiles are temperature-driven curves, distinct from fixed presets.
neosense profile list # catalogue and compatibility
neosense profile preview quiet # local calculation, no write
neosense profile apply quiet --yes # supervisor-owned closed loop
neosense profile state
neosense profile clear # end regulation, return to automaticEligible fans are regulated; blocked fans return to automatic and are listed
with reasons. Built-in curves are Quiet, Balanced and Performance. Custom curves
are stored in /var/lib/neosense/profiles.json and edited with
neosense profile custom ... or from the TUI Profiles view. See
docs/PROFILES.md and
docs/CUSTOM_PROFILES.md.
Every command that reports state supports --json, including status,
diagnose, fans, sensors, hardware identity, control readiness and
profile evaluations. JSON errors use a stable {"error":{"code","message","details"}}
shape with the documented process exit code.
neosense status --json | jq '.control.stage'
neosense diagnose --json | jq '.checks[] | select(.status != "ok")'neosense tui is the primary interactive interface, designed for an 80×24
terminal and usable smaller.
| View | Purpose |
|---|---|
| Dashboard | Mode, both fans, temperatures, safety and one-key mode switching |
| Fan Control | Select CPU, GPU or Both, set or adjust a target, return to automatic |
| Presets | Silent / Balanced / Maximum cards or list, applied immediately |
| Profiles | Apply, preview, deactivate and edit thermal profiles |
| Sensors | Role, value, trust, status, provider and path |
| System | NBFC, supervisor, IPC socket and active warnings |
| Diagnostics | Control readiness, calibration prerequisites and grouped checks |
The masthead adapts to the terminal: full banner with telemetry at large sizes,
a compact two-row wordmark at medium sizes and a one-line wordmark on small
terminals. A strict printable-ASCII banner is used on non-UTF-8 locales or with
NEOSENSE_ASCII=1.
| Key | Action |
|---|---|
Tab / ← → |
Change view (1–7 jump directly) |
s / b / m / a |
Dashboard: Silent / Balanced / Maximum / Auto |
↑ ↓ |
Select a fan, preset or profile |
Enter |
Apply the selected preset or profile |
m / b |
Fan Control: set selected fan / both fans |
+ / - |
Fan Control: adjust by 5% |
a |
Automatic mode: Dashboard, Fan Control selection or Profiles |
A |
Return all fans to automatic (any view) |
p / d |
Profiles: preview / deactivate |
r / ? / q |
Refresh, help, quit |
Mode changes are immediate. Manual percentage changes still ask y/n because
they write fan targets directly. See docs/TUI.md for the full
key map.
- Single writer. Only
neosensedwrites fan state. The CLI and TUI never open NBFC, EC, ACPI, WMI or PWM interfaces directly. - No invented values. Missing, invalid, stale or unreadable sensors are
null/unavailable, never0 °C. - Evidence before control. Manual control requires fresh trusted temperatures, a known mapping, backend guarantees and explicit confirmation.
- Bounded targets. Manual percentages are 20–100%; every target is a lease.
- No false success. Requested value, backend target, EC readback and physical response remain separate.
- Fail safe. Lease expiry, lost sensors, NBFC critical mode, failed
verification or supervisor failure trigger automatic recovery. A failed
recovery is recorded as
fail-safe, retried twice with a short backoff and then reported through supervisor health so systemd can restart the service; startup andExecStopPostre-assert automatic mode. - Per-fan profile gating. Profiles apply only to fans that pass policy; the rest stay automatic.
- Actionable warnings. Every warning carries a severity, cause and next safe step; colour is never the only signal.
The IPC socket is root:neosense, mode 0660; the supervisor applies these
permissions before signalling readiness. See docs/SYSTEMD.md.
Start read-only:
neosense status
neosense diagnose
neosense control readiness --json
neosense service status
neosense sensors list
neosense hardware identity
neosense validation history| Symptom | Meaning | Next step |
|---|---|---|
Permission denied on the socket |
User is not in neosense, or the session predates group membership |
sudo usermod -aG neosense "$USER", then log in again |
Supervisor unavailable |
neosensed is not running or is unhealthy |
systemctl status neosensed; sudo systemctl enable --now neosensed |
| Manual control refused (exit 8) | Safety policy: temperature, mapping, insecure NBFC socket or NBFC < 0.5.4 | Read the reason; neosense diagnose lists blockers |
| EC readback shows 100% at a lower target | NBFC clamps raw EC words against its write range | Treat EC as a backend percentage, not RPM |
| GPU control blocked | NBFC declares @CPU; no fresh NVIDIA die temperature is available |
Keep automatic control; check the NVIDIA driver |
stale / not fresh |
The supervisor snapshot aged out | neosense sensors watch; check supervisor health |
| Profile partially applied | Some fans failed policy | Blocked fans and reasons are reported; they stay automatic |
Exit codes: 0 success · 2 usage · 3 not found · 4 permission ·
5 diagnostic failure · 6 degraded · 7 backend/service unavailable ·
8 unsafe operation refused · 9 configuration/profile invalid ·
10 verification failed.
| Item | Status |
|---|---|
| Acer Nitro AN515-57, i5-11400H, RTX 3050, patched NBFC 0.5.4 | Primary validated machine; CPU/GPU actuator response operator-attested, no RPM calibration |
| NBFC 0.5.4+ | Recommended; protected manual control |
| NBFC 0.5.3 | Read-only diagnostics and auto; manual control refused |
| Fedora / Nobara, Debian / Ubuntu, Arch, openSUSE | Detection and package adapters implemented; full flow mock-tested, hardware validation only on the Acer target |
| Other laptops | Validate read-only with neosense diagnose --json before enabling control |
x86_64 |
Tested release target |
aarch64 source builds |
Accepted by the installer; no hardware validation |
- Physical validation is operator-attested, not RPM calibration. The CPU channel was accepted at 0/50/100%; the GPU channel was observed at 50/75/100% with CPU automatic and verified Auto recovery. A percentage target does not prove the same physical speed.
- No independent RPM/airflow reference. The kernel exposes no Acer hwmon fan input; provisional EC tach words are raw candidates and never enter regulation.
- EC readback is not RPM.
IndependentReadMinMaxValues=falsemakesCurrentSpeed=100%a clamp artifact in this configuration. - GPU telemetry is indirect. Both NBFC channels declare
@CPU; the GPU channel may use a fresh trusted NVIDIA die temperature as a guard, not as physical fan mapping. - Profiles are reference curves, not measured fan-response curves.
- Single-machine evidence. No broad laptop compatibility claim is made.
fan releaseis intentionally unavailable untilreset-ec/firmware return is validated.- VM validation is software-only. The Fedora 44 VM exercised install, systemd, upgrade, rollback and uninstall without EC/fan hardware; it is not backend-ready hardware validation.
Hardware evidence and boundaries:
docs/HARDWARE.md ·
docs/VALIDATION_RESULTS.md ·
docs/CALIBRATION_READINESS.md ·
docs/PHYSICAL_VALIDATION_PROTOCOL.md.
| Document | Contents |
|---|---|
docs/CLI.md |
CLI reference, JSON schemas, exit codes |
docs/TUI.md |
Views, keys, interaction and safety behavior |
docs/INSTALL.md |
Installer, dependency matrix, distribution status, recovery |
docs/HOST_INSTALL.md |
Root deployment history, upgrade, rollback, uninstall |
docs/SYSTEMD.md |
Unit, watchdog, IPC and fail-safe behavior |
docs/PROFILES.md |
Thermal curve engine and application boundaries |
docs/CUSTOM_PROFILES.md |
Persistent curve schema, editing and recovery |
docs/HARDWARE.md |
Per-fan evidence, registers and readback semantics |
docs/VALIDATION_RESULTS.md |
Physical validation record |
docs/CALIBRATION_READINESS.md |
Calibration prerequisites and blockers |
docs/IMPLEMENTATION.md |
Implementation status and resolved findings |
docs/ROADMAP.md |
Feature status, evidence and next steps |
docs/RELEASE_NOTES_2.4.0.md |
Current release notes and limitations |
CHANGELOG.md |
User-visible changes |
docs/RELEASE.md |
Release process and checklist |
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
cargo build --release --locked
./packaging/test-installer-isolated.sh
./installer/tests/run-tests.sh
./packaging/test-release-archive.sh dist/neosense-*.tar.gzTests never write fan state. They cover NBFC parsing, sensor fixtures, NVIDIA
parsing, policy, presets, profiles, storage recovery, IPC, daemon lifecycle, TUI
rendering and installer rollback. Hardware-dependent checks are separate and
require explicit authorization. See CONTRIBUTING.md and
SECURITY.md.
MIT © 2026 NeoSense Open Source Contributors. See LICENSE.