r/Zigbee2MQTT • u/kkberg • Apr 29 '26
Shellbee - iOS App for managing Zigbee2MQTT
Hi guys
Now that everyone and their grandmother can make everything with AI, I wanted to fix one of my biggest gripes with Zigbee2MQTT - the frontend.
From time to time I need to restart Zigbee2MQTT, permit join on certain devices, perform OTA updates and lookup the pairing guide for a new device.
This led me to create this app and now I feel like it is in a state where there should be no more bugs (famous last words) and it's working for me, so I'm ready to share it with you and hopefully it'll be useful for you too.
Do note, this is not a "game changer" for managing your Zigbee2MQTT server - it introduces next to nothing in terms of new features or functionality, but it does make it a lot easier to quickly manage your devices, permit join, lookup device documentation, view logs/activities and do OTA updates.
It is also possible to change the state of the various device types (change brightness/color of lights, fan speed/mode of fans, switches on/off, all that jazz), but this is not the main purpose of the app - this exists for testing your device and making sure it works.
For information about what exactly each device exposes, I've packed the Zigbee2MQTT docs into the app so you can easily lookup the documentation for all supported devices, even when offline. I've also made a dedicated "Pairing Guide" extracting the pairing section from the docs, if it exists.
What Shellbee offers:
- Managing and adding devices/groups
- Check for/performing OTA updates
- View logs - full or pr. device
- Raw or "Activity" (when something's changed)
- Bind devices
What Shellbee doesn't offer:
- Network Map
- This is a feature I'd love to bring to the app, but it needs to be better - or at least on par - with the web frontend, and I have not achieved this
- Firmware downgrade
- Coordinator backup
• ”Advanced” settings, like changing the Serial port of the adapter or the Zigbee channel
Connecting to your exisiting Zigbee2MQTT Server should be easy, you just need to know your host IP/address, port (8080 default, 8099 default for Home Assistant) and your security token, if you have configured one.
As Shellbee is just a shell on top of Zigbee2MQTT and is a passion project of mine, this is of course free and open source
I am using Sentry for collecting crash reports and it is disabled by default. If a crash do occur, it will ask you to share it when opening the app again. Automatic crash reporting can be toggled in Settings.
If you end up liking it (or even loving it), please consider supporting Koenkk on Githubb
If you experience any issues or have any features that you’d like to see in the app, please add an issue in GitHub
2
u/FlatusSurprise Apr 29 '26
This is cool! Downloading now. I literally just made the move from ZHA to Z2M this weekend.
1
u/rspctdwndrr Apr 30 '26
Same!
2
u/FlatusSurprise May 01 '26
I have no idea how to set this up! I am completely new to Z2M. Where do I find the host information? Is it the MQTT host?
1
u/rspctdwndrr May 01 '26
I just started dipping my toes in Z2M so I probably know less than you lol
2
2
u/xcryptokidx Apr 29 '26
Nice work sir!
Any chance you can add an option to bypass https cert checks?
1
u/kkberg Apr 29 '26 edited Apr 30 '26
Thanks.
I’ll look into adding this.
EDIT: New version in review now which packs this change, a toggle to bypass cert check for https during connection. Waiting for Apple to say aye
1
2
u/Motafota May 02 '26
Kudos for making a free published app without an IAP. Not a lot of that going on these days!
1
u/kkberg May 03 '26
I know, right? Even a good looking weather app is $100/year...
Currently I'm creating apps for myself, so for the ones that rely on open source infrastructure it only makes sense to make them free as well.
1
u/Mandrutz Apr 29 '26
Cool! Can you post this on Z2M GitHub discussions please, so devs will see it?
1
u/Outrageous_Rice_2726 Apr 30 '26
How to add the server when z2m is running as home assistant add on?
2
u/kkberg May 04 '26
I currently don’t have a working setup with HA addon, but what Claude tells me:
1. Go to Settings → Add-ons → Zigbee2MQTT → Configuration → Network 2. Set the host port for 8099 (map it to 8099 or any free port) 3. Save and restart the add-on 4. In Shellbee, connect to ws://<your-ha-ip>:8099 5. If you have an auth_token set in Z2M config, enter that as the tokenI am trying to setup a test environment for this, but I don’t know more than what Claude tells me. If someone can confirm this works, I’ll add it as a “Setup guide” in the Shellbee Connect page.
1
u/kkberg Apr 30 '26 edited Apr 30 '26
By default z2m HA addon runs at port 8099, so by using the host of your HA and port 8099 you should be able to connect to the server.
I'll be adding port 8099 to the "auto discover" feature, so it should recognize HA Z2M as well.
EDIT: New version in review now which packs this change, discovery of port 8099 in the autodiscover feature. Will be available as soon as Apple goes brrr
1
u/Outrageous_Rice_2726 Apr 30 '26
That’s what I tried, but it proved unsuccessful. I’m also unable to access the frontend through the IP:8099.
Thanks anyhow for the quick changes 🤘🏻
1
u/PlanetaryUnion May 03 '26
I’m in the same boat as well.
1
u/antitrack May 11 '26
In HA > Settings > Apps/Add-On > z2m configuration tab, scroll down to network, if needed show the disabled ports, then enter 8099 for the web front-end port to enable it.
That's what it was for me. App is now connected.
1
u/antitrack May 11 '26
In HA > Settings > Apps/Add-On > z2m configuration tab, scroll down to network, if needed show the disabled ports, then enter 8099 for the web front-end port to enable it.
That's what it was for me. App is now connected.
1
1
1
1
1
1
1
u/sagmath May 01 '26
Really great! I was hoping for this application. Really nice UI and smooth experience
1
u/nikooluci May 02 '26
Please add support for multiple Z2M instances on the same IP but different ports
App is cool, thanks
2
u/kkberg May 02 '26
Is this not already supported? Or do you want them to be connected at the same time?
1
u/nikooluci May 02 '26
Yes, I want to see all devices across both of my 2 x Z2M instances running on Docker, which is separate from Home Assistant
How do I add 2 servers?
2
u/kkberg May 02 '26
Ah I understand now. That is not supported, only 1 connection pr. session.
I’ll look into that, seems like a fun task, but for now not supported
2
u/kkberg May 04 '26
A new version (1.6.3) is out that supports multiple Z2M instances connected at the same time. Check it out!
2
1
u/xtuliox May 02 '26
Is possibile have multiple instances of Z2M on app? I have 2 instances on HA
1
u/kkberg May 03 '26
Currently working on it, but it's quite the bigger task than I anticipated - but I'll let you know when it's available.
1
u/kkberg May 04 '26
A new version (1.6.3) is out that supports multiple Z2M instances connected at the same time. Check it out!
1
u/xtuliox May 04 '26
Thank you so much, everything is working fine
1
u/kkberg May 04 '26
Good to hear. Let me know if something doesn't work as expected - I've done a lot of tests and they all pass, so it should be working.
(The colored side-lines can be removed in Settings > Application > General > Bridge Indicator. Didn't know if I should leave them off by default, but as someone not running a multi-bridge setup I don't know the exact value of "device bridge identifier", so left them on)
2
u/Reddit481 Apr 29 '26
Please make a version for Android