LuxMini docs

1. Download the latest .dmg from the Download button.
2. Open the DMG and drag LuxMini.app into your Applications folder.
3. Eject the DMG. You can trash the DMG file. LuxMini keeps itself up to date from here on.

LuxMini is a universal binary (Intel + Apple Silicon) and targets macOS 11 Big Sur or later. It supports Mac mini and Mac Studio; it is not intended for MacBook or iMac models.

LuxMini is signed with Apple Developer ID and notarised by Apple. It opens normally through Gatekeeper without an Open Anyway workaround.

1. Launch LuxMini from Applications after ejecting the DMG.
2. Select Get Started. LuxMini checks whether its minimal LED helper is installed and running.
3. Approve the standard administrator prompt if the helper needs to be installed or repaired. Cancelling keeps the setup open with a clear Retry action.
4. Watch the front LED fade, confirm what you saw, and finish setup. Future launches need no administrator approval unless the helper must be replaced.

Brand-new Mac models can be recognised before their LED profile has been physically verified. LuxMini never silently enables a candidate profile on every machine.

1. LuxMini explains that the model is awaiting validation.
2. If you start the test, it downloads only the candidate profile matching your Mac.
3. The front LED gently fades down and back up, then returns to full brightness.
4. Confirm whether you saw the fade. A successful test enables the profile only for that exact model on your Mac.

The report contains the model identifier and your Yes, No, or technical-error answer. It never includes a serial number or an installation identifier. One user confirmation does not mark a model globally verified; the profile owner reviews it first.

LuxMini lives in your menu bar. The icon itself is a circle whose fill mirrors your LED brightness: full disc at 100%, a thin outline when the LED is off.

• Toggle switch: turns the front LED on or off. Off means physically off, not dimmed to 1%.
• Brightness slider: ranges from 0 to 100%, with no perceptible latency.
• Percent readout: matches what the slider reports.

Auto-dim applies a night-time LED state without overwriting your preferred daytime brightness. Configure it from Settings → Auto-dim.

• Off at sunset turns the LED off after local sunset and restores your manual state after sunrise.
• Evening dim applies the brightness percentage you choose from the configured time.
• A precise location is optional. Without one, LuxMini derives an approximate location from the system time zone.
• A manual LED change temporarily takes priority so the schedule does not fight your input.

A manually entered or detected location stays in macOS preferences on your Mac. It is not uploaded with profile requests.

LuxMini provides three local preset slots. A preset stores the on/off state, brightness, and current effect. Use Save current… to replace a slot, then select the preset from the menu whenever you want to restore it.

LuxMini also restores your last manual state after a restart. Scheduled dimming remains temporary and does not replace that saved preference.

Effects keep running until you pick “Stop” or move the slider, so feel free to leave one on as ambient feedback.

Blink

500 ms on, 500 ms off. Classic heartbeat.

Blink Fast

120 ms on/off. Good for notifications.

Pulse

Sine-wave breathing, full cycle every 2 seconds.

SOS

Morse code for SOS on loop. Dots, dashes, gaps, letter-gaps and word-gaps all observed.

Strobe

45 ms on/off. Party mode. Don't stare.

Stop

Cancels any running effect and restores your last manual brightness.

LuxMini can expose an optional HTTP API for Apple Shortcuts, Home Assistant, AppleScript, and local scripts. It is off by default, listens only on 127.0.0.1, and uses port 4470 unless configured otherwise.

Enable it from Settings → General → Enable local control API. The API does not create an account and is never exposed to your local network by LuxMini.

curl http://127.0.0.1:4470/led
curl -X POST http://127.0.0.1:4470/led \
  -d '{"brightness":128}'

For the complete payloads, CLI commands, and automation examples, see the auditable client documentation.

LED addressing differs between Mac generations. LuxMini keeps this hardware-specific information in small device profiles, allowing a new model to be supported without shipping private infrastructure details inside the app.

• LuxMini requests only the profile matching the current model.
• The response is validated before use and cached locally in ~/Library/Application Support/LuxMini/profile.
• LED control, schedules, presets, and the optional API operate locally on your Mac.
• Network access is limited to update checks, matching-profile delivery, an explicit new-hardware validation response, and optional anonymous diagnostics when you enable them.
• Anonymous diagnostics are disabled by default. If enabled in Settings, they contain only a closed event name, its outcome, the Mac model, and the macOS major version.

There is no LuxMini account and no serial number or installation identifier is created or sent. Diagnostics are stored as aggregate counters, not per-device histories.

Candidate models use the reversible fade confirmation described above. If a model is not recognised, LuxMini warns you and does not claim verified support.

LuxMini uses Sparkle to check for updates about once a day and presents the standard macOS update flow when a new release is available.

You can also trigger a check anytime from menu bar icon → “Check for Updates…”.

A release can include an updated privileged helper. In that case, macOS may ask for administrator approval again before the helper can control the LED.

The LED doesn’t respond

Make sure your Mac model is on the supported list. If your Mac is listed and the LED still doesn't respond, open Settings and run the LED access check. LuxMini verifies the helper handshake, restarts a crashed helper, and offers a repair action when its permissions or version are wrong.

A new Mac asks to test the LED

This is expected for a recognised candidate model. Read the explanation, start the reversible fade test only when you can see the front LED, then answer exactly what you observed. A No answer leaves the candidate profile disabled.

The candidate profile cannot download

Check the internet connection and try again. LuxMini will not run the hardware test without a valid matching profile, and it will not silently fall back to another model's profile.

The local API does not answer

Confirm that it is enabled in Settings → General, then restart LuxMini. The default endpoint is http://127.0.0.1:4470/healthz; it cannot be reached through another computer's IP address.

“App is damaged” message

This means the quarantine attribute got corrupted, usually after a bad copy. Re-download the DMG and reinstall. Do not run xattr shell workarounds.

Admin prompt every launch

The helper lost its admin privileges. Quit LuxMini and relaunch once to re-approve. If it keeps happening, another tool (backup software, antivirus) is probably resetting file permissions inside /Applications.

Menu bar icon disappears

macOS hides menu bar icons when there's no room left. Try the Bartender or Hidden Bar app, or remove icons you don't need.

Three files, three seconds:

1. Quit LuxMini from its menu bar icon.
2. Move /Applications/LuxMini.app to the Trash.
3. Optional: delete preferences with defaults delete com.bastiencantet.luxmini in Terminal.
4. Optional: remove the cached device profile from ~/Library/Application Support/LuxMini.

The privileged helper lives inside the app bundle. Trashing the app removes the executable and helper; preferences and the small cached profile remain only if you choose to keep them.

Bug reports and feature requests go through the Feature request page. Include your Mac model, macOS version, and LuxMini version. I'll reply faster.

LuxMini is free. If it is useful to you, you can support development. Donations help cover the Apple Developer membership, profile hosting, and validation on new Mac hardware.

LuxMini includes a gentle local reminder only after seven days and twenty meaningful menu sessions. It can appear at most twice, ninety days apart, and includes a permanent opt-out. Dismissal choices stay on your Mac.