ShellyLanMan
Discover, monitor and manage Shelly devices on your LAN — one go-to app, with an MCP server for AI assistants.
A single lightweight Docker container that runs standalone, or inside Home Assistant as an app with extra features.
ShellyLanMan is a network-based tool for monitoring and managing Shelly IoT devices. It automatically discovers devices on the local network and shows key information such as Wi-Fi strength, cloud connectivity, uptime, temperature and meter readings. Devices can be controlled directly, and configuration backup and restore are available from the toolbar. Firmware management is built in, with a QR code for a quick download of the firmware, so you can update a device through the Shelly's own access point.
It started from ShellyScanner by usnasoft and is built on its basis — its features, terminology and Shelly know-how — then developed further as a web application of its own: pages that work together for a first-time user, an MCP server for AI assistants, a Home Assistant app and integration, eight languages. No desktop, no VNC, no Java, no cloud. Why · Quick start · Features · Pages · Screenshots · AI assistants (MCP) · REST API · Home Assistant · Security · Configuration · Development · Contributing · Support · Credits
✨ Why ShellyLanMan
- One place for every Shelly on the LAN — Gen1 to Gen4, Pro, BLU through their gateways, range-extender clients and protected devices.
- Runs where your other services run — one Docker image for
amd64andarm64(Raspberry Pi 4/5), opened from any browser, also on a phone. - Local first — nothing leaves your LAN except what ShellyScanner also does (the devices' own firmware checks) and an opt-in release check. No account, no telemetry.
- Firmware without the cloud — a QR code gives your phone the firmware file from ShellyLanMan, to update a device through its own access point.
- In your language — English, Nederlands, Deutsch, Français, Español, Italiano, Български, 中文.
- Better than the phone app — Shelly's own app is built around the cloud and shows only part of what the devices can do. ShellyLanMan talks to the devices directly, in any browser, also on your phone, with every setting, script, schedule and backup.
- For AI assistants — a built-in MCP server: Claude Code, Claude Desktop or a local model can read your devices and, if you allow it, switch, configure and script them. Locally, with confirmation for anything destructive.
- At home in Home Assistant — an app in the sidebar behind Home Assistant's login, in Home Assistant's own colours, and an integration that puts ShellyLanMan's status, configuration backups and settings checklist next to your Shelly devices in Home Assistant, plus its tools for Assist.
- More than ShellyScanner — on top of all of ShellyScanner's functions: pages that work together (one selection for Devices, Checklist and Firmware, buttons that say why they are not available), the MCP server and Home Assistant support above, scenes, eight languages, colour palettes (the Home Assistant look by default), installable as an app, release notes in the app.
🚀 Quick start
Linux with Docker Engine. Save this as docker-compose.yml (it is the
docker-compose.yml of this repository; every option is in it,
the optional ones in comments):
# ShellyLanMan — compose file. Every option is listed below; the ones in
# comments are optional.
#
# Host networking is the default on purpose: mDNS discovery needs multicast on
# your LAN, which Docker's bridge network does not pass (ARCHITECTURE.md §2.5).
# Linux only.
#
# Start / apply a change: docker compose up -d
# Update: docker compose pull && docker compose up -d
services:
shellylanman:
image: ghcr.io/wimmme/shellylanman:latest
# Only used when you build from a clone of the repository (docker compose up -d --build).
build: .
container_name: shellylanman
network_mode: host
# Bridge mode instead (no mDNS discovery; use an IP-range scan): remove
# network_mode above and map the port, host port on the left:
# ports:
# - "3082:3082"
volumes:
- data:/data
environment:
- TZ=${TZ:-UTC} # time zone of the logs and the UI
# Port of the web UI and API (default 3082). Settings → General → Ports
# shows it; change it here and run `docker compose up -d`.
# - SHELLYLANMAN_PORT=3082
# Extra allowed browser origins: the host name(s) of your reverse proxy,
# comma separated.
# - SHELLYLANMAN_ORIGINS=shelly.example.net
# Data directory inside the container (default /data, the volume above).
# - SHELLYLANMAN_DATA=/data
# Forgotten UI password: uncomment, `docker compose up -d` once (the password
# is removed, see the log), comment it out again and `docker compose up -d`.
# - SHELLYLANMAN_RESET_PASSWORD=1
# Set by the Home Assistant app only — do not set them here:
# SHELLYLANMAN_INGRESS, SHELLYLANMAN_INGRESS_FROM, SHELLYLANMAN_MCP_LOCAL
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
volumes:
data:
docker compose up -d
Open http://<your-host>:3082. There is nothing to configure beforehand: a
first-run dialog appears in the browser.
Or with docker run:
docker run -d --name shellylanman --network host -v shellylanman-data:/data \
--restart unless-stopped ghcr.io/wimmme/shellylanman:latest
Images are published for linux/amd64 and linux/arm64 (Raspberry Pi 4/5 with
a 64-bit OS). Tags: latest, X.Y and X.Y.Z.
Update
docker compose pull && docker compose up -d
Use docker compose up -d, not docker restart — a restart keeps the old image.
To stay on one release line, use a tag such as ghcr.io/wimmme/shellylanman:0.9
instead of latest. The changes of each release are in CHANGELOG.md.
Before a major version, save the data volume (it holds settings, archive, backups):
docker run --rm -v shellylanman_data:/data -v "$PWD":/backup alpine tar czf /backup/shellylanman-data.tgz -C /data .
(docker volume ls shows the volume's name: compose prefixes it with the project
directory, e.g. shellylanman_data; the docker run example uses shellylanman-data). To go back, start the previous tag with the saved
volume content.
Forgotten password
When a UI password is set (Settings → Security) and forgotten, start ShellyLanMan
once with SHELLYLANMAN_RESET_PASSWORD=1: it removes the password and logs out every
browser (the log says so). With compose, uncomment the line in docker-compose.yml:
environment:
- SHELLYLANMAN_RESET_PASSWORD=1
then docker compose up -d, open ShellyLanMan (no password now), comment the line out
again and docker compose up -d once more — otherwise every restart removes the
password again. With docker run, start it once with -e SHELLYLANMAN_RESET_PASSWORD=1
and then without it. Set a new password in Settings → Security.
In the Home Assistant app there is no environment variable to set: open ShellyLanMan in Home Assistant's sidebar and change or switch the password off in Settings → Security — there the current password is not asked, you are logged in to Home Assistant.
Why host networking
ShellyLanMan finds devices with mDNS, which uses multicast on your LAN.
Docker's default bridge network does not pass that multicast into the
container, so discovery by mDNS only works with network_mode: host (Linux).
In bridge mode (-p 3082:3082) everything else works and devices can be found
with an IP-range scan. Details: ARCHITECTURE.md §2.5.
Configuration
Everything is set in the browser, except what is needed before the UI is up. In
Docker that is a few environment variables — all of them are in
docker-compose.yml, the optional ones in comments; in the Home
Assistant app it is the app's options (Configuration tab), which set the same
variables. Settings → General → Ports shows the ports in use and where they are set.
Set by the Home Assistant app's start script only (do not set them yourself):
Shellys with a password
Supported, as in ShellyScanner. Protected Shellys show up as not logged until ShellyLanMan knows their password:
- One password for all — Settings → Network → Restricted login: the user (Gen1;
Gen2+ always use
admin) and password ShellyLanMan tries on every protected Shelly. - Per device — tick the device and press Login (the Reload button becomes Login for a device that is not logged in): its own password, which wins over the default.
The passwords are stored encrypted in /data and never sent back to the browser. With
the Home Assistant integration, Add Shellys to Home Assistant passes them on to Home
Assistant's Shelly integration, so you do not type them twice.
What is stored in /data
Chart readings are kept in memory only (24 hours). Details:
ARCHITECTURE.md §2.6.
Behind a reverse proxy
Terminate TLS at the proxy, forward WebSocket upgrades for /ws, and set
SHELLYLANMAN_ORIGINS to the public host name. The UI password is off by
default — set one in Settings → Security, or add authentication at the proxy,
if the UI is reachable beyond your own LAN. See SECURITY.md.
Phones fetch firmware files from ShellyLanMan itself (the QR code and Download button of
the firmware wizard, /fw/…). The link uses the address the browser used; when a phone
cannot reach ShellyLanMan there, set Settings → Network → Address of ShellyLanMan for
phones, for example http://192.168.1.10:3082.
🧭 Features
Everything ShellyScanner does, in the browser, and pages that work together:
-
One selection for Devices, Checklist and Firmware: tick devices on one page and the others show those devices (or all, with one click). Every button says what it does and, when it is grey, why.
-
Discovery by mDNS (all interfaces or one), IP-range scan or offline, Gen1 to Gen4, Pro, BLU devices through their gateways (also the ones a gateway only relays, with a wizard that identifies their model), range-extender clients, protected devices, an archive of known devices with notes and keywords.
-
Devices table with all columns, filters, views, device information, live logs, controls (relays, rollers, lights, thermostats, …), reboot, CSV export and print.
-
Configuration of one or many devices (Wi-Fi, login, MQTT, NTP, cloud, …), the configuration checklist and deferred tasks for devices that are offline.
-
Backup and restore (
.sbk, compatible with ShellyScanner), kept on the server. -
Firmware check and update with live progress, plus one new feature: a QR code for a local firmware download, to update a device through its own access point.
-
Scripts (with a code editor) and KVS, schedulers (Gen2+, Wall Display thermostat, BLU TRV) and charts with 24 hours of history.
-
Appearance: dark and light themes, colour palettes, fonts and sizes, per browser.
-
Installable app (PWA) on phones, tablets and desktops when ShellyLanMan is served over HTTPS (for example behind a reverse proxy) or on
localhost; on a plainhttp://<ip>:3082browsers offer only a home-screen shortcut.
What leaves your LAN: the devices' own firmware checks (as with ShellyScanner); Shelly's firmware index when you open the Firmware page; the ShellyLanMan release check only if you switch it on (off by default). No telemetry.
📑 Pages
📸 Screenshots
 |  |
| Devices — every Shelly with its readings and controls (here a dimmer's slider); three ticked | Checklist — the same selection, settings worth checking |
 |  |
| Firmware — current, stable and beta, and the Shelly index | Charts — readings of the selected devices over time |
 |  |
| Script editor — edit, upload and run the device's scripts | Device info — everything the device reports |
 |  |
| Logs — the device's live debug log | Identify BLU devices — the model of a BLU device a gateway only relays |
 |
On a phone the pages get the full width; the navigation is behind ☰:
Updating a Shelly through its own access point, step by step (an illustration, not a recording):
🤖 AI assistants (MCP)
ShellyLanMan has a built-in Model Context Protocol server, so an AI assistant — Claude Code, Claude Desktop, or a local model — can ask about your devices and, if you allow it, switch them. It is local only: the assistant talks to ShellyLanMan, ShellyLanMan talks to the devices on your LAN. No Shelly cloud account, nothing leaves your network except what your AI client itself sends to its model.
Switch it on in Settings → MCP. That makes a token (shown once) and gives you the command to paste, for example:
claude mcp add --transport http shellylanman http://<your-host>:3082/mcp \
--header "Authorization: Bearer <token>"
Scenes are named lists of device actions stored in ShellyLanMan (/data/scenes.json).
On by default but read-only unless you choose otherwise, a bearer token on every request over the network (none exists until you make one under Settings → MCP), browser requests from other sites refused, and every action that changes something written to the log. Devices are named by name, host name, IP or MAC.
🔌 REST API
Everything the web page does goes through a REST API under /api/v1, and anything you
can do in the page you can do from a script. It is described in OpenAPI 3.1 at
/api/v1/openapi.json (also linked on the About page): import it into Postman, Swagger UI
or a code generator. It is on the same address and port as the page, so any machine on
your LAN can use it. With a UI password set, send the session cookie or the MCP token as
Authorization: Bearer <token> (a read-only token may only read); without a password
no login is needed. Changes are pushed over the WebSocket /ws.
🏠 Home Assistant
shellylanman-ha packages ShellyLanMan
for Home Assistant:
- App (Home Assistant OS): ShellyLanMan in the sidebar, behind Home Assistant's login, with a Home Assistant look in light and dark.
- Integration (HACS): ShellyLanMan's status, configuration backup and settings checklist per Shelly, on a device that Home Assistant links to the Shelly integration's device, and ShellyLanMan's tools for Assist. Works with the app and with the Docker container.
The Shellys themselves — relays, lights, meters — come from Home Assistant's own Shelly integration. The ShellyLanMan integration helps there: Configure → Add Shellys to Home Assistant lists the Shellys ShellyLanMan knows that the Shelly integration does not have yet (also the ones Home Assistant did not discover) and adds the ticked ones through the Shelly integration's own steps, passwords included when ShellyLanMan may hand them out.
Step by step: shellylanman-ha.
Questions, ideas, feedback: the thread on the Home Assistant Community.
🔒 Security
- Keep it on your LAN. ShellyLanMan can change the configuration of your devices; do not expose it to the internet. For remote access use a reverse proxy with TLS and authentication.
- Optional password (Settings → Security, off by default) — one password, no user name; a login page with Stay logged in; slower after five wrong tries. Without it anyone who can reach the port can use ShellyLanMan; a warning is logged at start and shown once per browser. In Home Assistant's sidebar Home Assistant's login applies. Forgotten: see Forgotten password.
- Secrets at rest — device and Wi-Fi passwords are encrypted in
/datawith AES-256-GCM; they are never sent back to the browser. - Browser protection — same-origin checks on every state-changing request and the WebSocket, a strict Content Security Policy, no third-party scripts or fonts.
- Destructive actions (reboot, restore, firmware update, port change) always ask
for confirmation, and the API requires
confirm: true. - MCP is on by default but read-only unless you allow control or configuration, and over the network it needs a token, which exists only once you make one. The Home Assistant app's own listener (loopback only) needs none.
- Report vulnerabilities privately: see
SECURITY.md.
💻 Development
Only Docker is needed:
sh tools/verify.sh # typecheck, tests, gofmt, vet, go test -race, image build
Try it without hardware: go run ./cmd/shellysim testdata/gen1/SHPLG-S testdata/gen2/Plus1
starts simulated devices on ports 8081 and 8082. See CONTRIBUTING.md.
🤝 Contributing
Issues and pull requests are welcome, from typo fixes to new pages. Check the
open issues first, and open one before a
large change so the approach can be agreed. You do not need Shelly devices to
contribute: the simulator (cmd/shellysim) plays recorded devices. See
CONTRIBUTING.md.
☕ Support
ShellyLanMan is free and open source, and always will be. If it saves you time, a coffee (or a few tokens for coding) is welcome — and never expected.
Bugs and ideas: open an issue.
🙏 Credits
- ShellyScanner by Antonio Flaccomio (usnasoft) — the starting point and the basis of ShellyLanMan: its features, the terminology and the Shelly know-how, and code ported from it (GPL-3.0). ShellyLanMan has since been developed further on its own. More at https://www.usna.it/shellyscanner/. Beyond the credits, he deserves a coffee too.
- MikroDash by SecOps-7 — the idea, the inspiration and the basis of the look and feel: design tokens, palettes and appearance settings (MIT). Beyond the credits, SecOps-7 deserves a coffee too.
- Shelly-MCP by Buggy1111 (Michal Bugy) — the model for ShellyLanMan's MCP server: its tools for AI assistants, the confirmation gates and scenes (MIT; no code taken). Beyond the credits, he deserves a coffee too.
- CodeMirror 6 (script editor), Chart.js (charts), go-qrcode (QR codes) — MIT;
fonts under the SIL Open Font License. Full list in
THIRD_PARTY_NOTICES.md.
⚖️ Disclaimer
ShellyLanMan is an independent project. It started from ShellyScanner and is built on its basis, developed further on its own; it is not affiliated with ShellyScanner, and not affiliated with or endorsed by usnasoft or Shelly Group. Shelly is a trademark of its owner.
