homebridge-alarm-dot-com

Homebridge plugin for Alarm.com security systems with real two-factor authentication support.

• Sign in once from the Homebridge UI (or a CLI). Enter your one-time code once; the plugin enrols itself as a trusted device and never asks again.
• One long-lived session. No re-login every few minutes, no login-notification spam, no soft bans.
• Live updates over Alarm.com's WebSocket, with a slow safety-net refresh.
• Partitions appear as HomeKit Security Systems (Stay, Away, Night, Off). Contact, motion, glass-break, smoke, CO, and water sensors appear as the matching HomeKit sensors with battery, fault, tamper, and bypass status.

Requirements

• Homebridge 1.8 or 2.x on Node 22 or 24.
• An Alarm.com login with two-factor authentication enabled (authenticator app, SMS, or email). Alarm.com forces this for most dealers; the plugin tells you if your account still needs it.

Install

Search for alarm-dot-com in the Homebridge UI, or:

npm install -g @omarshahine/homebridge-alarm-dot-com

Sign in

1. Open the plugin settings in the Homebridge UI.
2. Enter your Alarm.com username and password and click Sign in.
3. Pick how to receive the code if you have more than one method, type the code, done.
4. Restart Homebridge.

The trusted-device token is stored in <homebridge storage>/homebridge-alarm-dot-com/auth.json with owner-only permissions. Your password stays in config.json like any other plugin; Alarm.com needs it to open a new session after a restart.

Headless install (HOOBS, Docker, no UI)

npx @omarshahine/homebridge-alarm-dot-com login --username [email protected]

Add --storage-path /path/to/homebridge/storage if your storage directory is not ~/.homebridge. npx @omarshahine/homebridge-alarm-dot-com logout removes the token.

If you cannot run either, put an existing twoFactorAuthenticationId cookie value in the Trusted-device token field under Advanced; it is imported into auth.json on the next start.

Configuration

| Field | Default | Notes | |---|---|---| | username, password | required | Your Alarm.com login | | armingModes.stay/away/night.silentArming | true | Arm without the panel beeping | | armingModes.*.noEntryDelay | false | | | armingModes.*.forceBypass | false | Bypass open sensors when arming | | ignoredDevices | [] | Alarm.com ids such as 12345678-3; ids are logged at startup | | pollIntervalSeconds | 60 | Only used while live updates are down (minimum 30) | | reconcileIntervalMinutes | 30 | Full refresh interval (minimum 5) | | logLevel | info | debug logs every request with secrets redacted |

Options a panel does not support for a given mode are dropped automatically instead of failing the command.

HomeKit mapping

| Alarm.com | HomeKit | |---|---| | Partition | Security System (Night only offered when the panel supports it) | | Contact, shock, glass break | Contact Sensor | | Motion | Motion Sensor | | Smoke | Smoke Sensor | | Carbon monoxide | Carbon Monoxide Sensor | | Water | Leak Sensor | | Panic buttons, sirens, key fobs, phones, image sensors | skipped |

Troubleshooting

| Log message | What to do | |---|---| | rejected the username or password | Fix the credentials in the plugin settings and restart | | needs a one-time verification code | Open the plugin settings and click Sign in (or run the CLI) | | requires two-factor authentication | Enable 2FA on alarm.com, then sign in again | | locked this account | Wait, then restart Homebridge; do not keep retrying | | falling back to polling | Live updates are down; the plugin polls until they recover |

Set logLevel to debug for per-request logging. Cookies, tokens, passwords, and codes are never logged.

Development

npm install
npm test
npm run lint
npm run build

Clean-room implementation. Protocol notes live in docs/superpowers/specs/.

License

MIT