Free Space monitor for mounted volumes.

Usage no npm install needed!

<script type="module">
  import homebridgeGrumptechVolmon from 'https://cdn.skypack.dev/homebridge-grumptech-volmon';


Homebridge Volume Monitor

Homebridge Volume Monitor, by GrumpTech, is a Homebridge dynamic platform plug-in that publishes the remaining storage of mounted volumes on macOS/OSX operating systems to Homekit. The remaining storage, computed as a percentage of the total, is presented as a Battery Service accessory. A low battery alert will be issued when the remaining storage falls below a specified threshold.

Change Log

The change history can be viewed here

Security Policy

Please refer to our security policy for information on which versions are receiving security updates and how to report security vulnerabilities.


This plug-in is intended to be used with the homebridge-config-ui-x homebridge management tool. If using homebridge-config-ui-x, simply search for homebridge-grumptech-volmon for installation, plug-in management, and configuration.

To install the plugin manually:
npm install -g homebridge-grumptech-volmon



This plugin is best experienced when running as a module installed and managed by the homebridge-config-ui-x plugin. When running under homebridge-config-ui-x, visiting the plugin settings will allow you to change the polling interval, the default low space alarm threshold, as well as per-volume exceptions/customizations. The per-volume customizations also allow for the low space alarm to be diaabled. This is useful, for example, when the volume is read-only, or not important enough to warrant having an alarm.
Configuration Settings UI Configuration Settings JSON

Setting Description Field Name Parameter Type Data Type Units Default Minimum or Allowed Values Maximum Comments
Polling Interval The time between automatic scans of the system polling_interval Common Number Hours 1 0.083334 744
Low Space Alarm Threshold (Default) Percent of remaining space that will trigger a low battery alert (default) alarm_threshold Common Number Percent 15 1 99
Exclusion List An array of regular expression patterns indicating the volumes to be excluded based on the volume mount point. exclusion_masks Common Array of Strings N/A ^/Volumes/\\.timemachine/.* and ^/System/Volumes/.* By default, time machine and system volumes (on macOS) are excluded. Emulates previous behavior.
Enable Volume Customizations Allow customixations for speficic volumes enable_volume_customizations Common Boolean N/A Off Off On
Volume Identification Method Method for identifying the volume volume_customizations:items:volume_id_method Per-Customization String N/A name name, serial_num
Volume Name Name of the volume volume_customizations:items:volume_name Per-Customization String N/A Required if the volume method is 'name'
Volume Serial Number Serial number of the volume volume_customizations:items:volume_serial_num Per-Customization String N/A Required if the volume method is 'serial_num'. Serial number is shown in the HomeKit device information section.
Low Space Alarm Enable the low space alarm volume_customizations:items:volume_low_space_alarm_active Per-Customization Boolean N/A On Off On Takes prescedence over the default threshold.
Low Space Alarm Threshold Percent of remaining space that will trigger a low battery alert volume_customizations:items:volume_alarm_threshold Per-Customization Number Percent 15 1 99 Takes prescedence over the default threshold. Required if the 'Low Space Alarm' is enabled for this customization.

Additionally, especially if this system will be running other homebridge modules, it is strongly encouraged to run this plugin as an isolated child bridge. This setting page can be found by clicking on the wrench icon on the plugin and then selecting Bridge Settings. With the child bridge enabled, revisiting the setting page after homebridge is rebooted will show a QR code for pairing to the child bridge. The username (mac address) and port are randomly generaged by homebridge-config-ui-x.
Bridge Settings Disabled Postreboot Bridge Settings Disabled Postreboot

Manual Configuration

If you would rather manually configure and run the plugin, you will find a sample config.json file in the ./config folder. It is left to the user to get the plugin up and running within homebridge. Refer to the section above for specifics on the configuration parameters.


When the plugin-starts, it will create a battery service accessory for each volume that does not match any of the patterns in the exclusion list. The battery level for each accessory will be set to the percentage of storage space remaining on the volume. If the amount of remaining storage is below the alert threahold the accessory will show the low battery status.
When viewing the details of an accessory, the accessory information section will display the Volume UUID (if known) under the Serial Number field and the volume format under the Model field. The plug-in version will show under the Firmware field.
Home app ios volume Home app ios volume with alert

The volumes on the system will be rescanned both (a) periodically according to the polling interval specified in the configuration settings and (b) when the contents of operating system specific folders change.
Monitored Folders:

  • OSX / macOS: /Volumes
  • Linux: /media/<username> and /mnt

Control Switches

  • Refresh: This switch, when turned on, is used to initiate a rescan of the volumes on the system. The user is not permitted to turn the switch off. It will automatically turn off when the scan is complete. This allows the user to update the battery service accessories without needing to wait for the polling interval to expire.
  • Purge: When this switch is turned on, battery service accessories that correspond to volumes that are no longer identified, for example ones that have been dismounted, will be removed (or purged). When this switch is off, any volumes that have been dismounted or now match one of the exclusion masks will show the battery level and battery alert as Not Reachable. Homekit applications will render these not reachable differently. For example, the Apple Home app will simply not display the Battery Level and Low Battery Status. Other applications like Home+ 5 app shows the accessories as Error. The state of this switch is persisted across sessions.


If customizing the exclusion_list configuration, it is left to the user to know the volume mount point and to be able to craft an appropriate regular expression for the volume(s) of interest.

It should be noted that the plug-in will not interrogate the system for mounted volumes until at least 10 minutes has elapsed since bootup. This will allow enough time for boot up operations to settle out and allow the system to reach stability.


Not all operating systems are supported. If your operating system or file system type is not supported, submit a request here or, better yet, contribute a solution !!
Currently supported operating systems:

  • OSX / macOS
  • Linux

Known Issues and Planned Enhancements

Refer to the bugs and enhancements listed here


  1. Fork it!
  2. Create your feature/fix branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request


Many thanks to all the folks contributing to Homebridge and to oznu for homebridge-config-ui-x, allowing for the possibility of this sort of fun and learning.


Refer to LICENSE.md for information regarding licensing of this source code.