shellylanman

<p align="center"> <img src="docs/images/logo-banner.png" alt="ShellyLanMan — Local · Monitor · Manage" width="420"> </p> <p align="center"> <a href="https://github.com/wimmme/shellylanman/releases"><img src="https://img.shields.io/github/v/release/wimmme/shellylanman?style=flat-square&color=0ea5e9" alt="Release"></a> <a href="https://github.com/wimmme/shellylanman/pkgs/container/shellylanman"><img src="https://img.shields.io/badge/docker-ghcr.io%2Fwimmme%2Fshellylanman-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker image"></a> <img src="https://img.shields.io/badge/platforms-amd64%20%7C%20arm64-6b7280?style=flat-square" alt="Platforms"> <img src="https://img.shields.io/badge/Shelly-Gen1%20%7C%20Gen2%20%7C%20Gen3%20%7C%20Gen4%20%7C%20BLU-1e40af?style=flat-square" alt="Shelly generations"> <img src="https://img.shields.io/badge/languages-8-0f766e?style=flat-square" alt="Languages"> <a href="LICENSE"><img src="https://img.shields.io/github/license/wimmme/shellylanman?style=flat-square&color=161a3a" alt="Licence"></a> </p> # 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](https://github.com/usnasoft/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](#-why-shellylanman) · [Quick start](#-quick-start) · [Features](#-features) · [Pages](#-pages) · [Screenshots](#-screenshots) · [AI assistants (MCP)](#-ai-assistants-mcp) · [Home Assistant](#-home-assistant) · [Security](#-security) · [Configuration](#configuration) · [Development](#-development) · [Contributing](#-contributing) · [Support](#-support) · [Credits](#-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 `amd64` and `arm64` (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](#-ai-assistants-mcp): 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](#-home-assistant) 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. `docker-compose.yml`: ```yaml services: shellylanman: image: ghcr.io/wimmme/shellylanman:latest container_name: shellylanman network_mode: host volumes: - data:/data restart: unless-stopped volumes: data: ``` ```sh 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`: ```sh 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 ```sh 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.6` instead of `latest`. The changes of each release are in [`CHANGELOG.md`](CHANGELOG.md). Before a major version, save the data volume (it holds settings, archive, backups): ```sh 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. ### 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](ARCHITECTURE.md). ### Configuration Everything is set in the browser. A few environment variables exist for things needed before the UI is up: | Variable | Default | Meaning | |---|---|---| | `SHELLYLANMAN_LISTEN` | — | Listen address. Normally the port is set in Settings → General (default 3082); when this variable is set it wins and the setting is locked | | `SHELLYLANMAN_DATA` | `/data` | Data directory | | `SHELLYLANMAN_ORIGINS` | — | Extra allowed browser origins (host names), comma separated, e.g. your reverse proxy's name | | `TZ` | `UTC` | Time zone for logs | ### What is stored in `/data` | File | Content | |---|---| | `secret.key` | Random key created on first start; encrypts secrets in `settings.json` | | `settings.json` | Application settings; device credentials encrypted | | `archive.json` | Device archive: known devices, last address, notes and keywords | | `deferred.json` | Deferred tasks for offline devices (passwords encrypted) | | `backups/<device>/*.sbk` | Device backups (newest N per device, setting) | | `firmware/` | Verified firmware files of the local download (cache) | Chart readings are kept in memory only (24 hours). Details: [`ARCHITECTURE.md` §2.6](ARCHITECTURE.md). ### Behind a reverse proxy Terminate TLS at the proxy, forward WebSocket upgrades for `/ws`, and set `SHELLYLANMAN_ORIGINS` to the public host name. UI authentication is off by default — add authentication at the proxy if the UI is reachable beyond your own LAN. See [`SECURITY.md`](SECURITY.md). ## 🧭 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, 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 plain `http://<ip>:3082` browsers 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 | Page | What it is for | |---|---| | **Devices** | The live table of every device: status, type, name, IP, RSSI, cloud, MQTT, uptime, temperature, measurements and controls. Tick devices, then use the toolbar: Checklist and Firmware for the selection; web UI, settings, charts, backup, restore, reload and reboot for one or more devices; info, logs, scheduler, scripts and notes for one device. Refresh reads the devices' status, Rescan searches the network again. | | **Checklist** | One row per device with the settings worth checking — eco mode, LED, logs, Bluetooth, access point, roaming, Wi-Fi, range extender, scripts, automatic firmware update. Tick devices and switch a setting with the buttons (or right-click a cell). | | **Charts** | Power, energy, voltage, temperature, RSSI and more for the selected devices, with 24 hours of history, zoom, pause and CSV export. | | **Firmware** | Current, stable and beta firmware of the selected devices (or all), update with live progress, and the QR code for the local download. | | **Deferred** | Actions for offline devices, run when the device comes back. | | **Settings** | Scan mode and IP ranges, archive, device credentials, backups, web server port, script editor, appearance (palette, font, how device pages open) and language. | | **About** | What is running (version, runtime, uptime), release notes, dependencies with their licences, credits and help. | ## 📸 Screenshots | | | |---|---| |  |  | | **Devices** (dark) — the live table; three devices ticked | **Checklist** (light) — the same selection, with *Show all devices* | |  |  | | **Firmware** (light) — check, update and the Shelly index | **About** (dark) — version, system information and support | On a phone the pages get the full width; the navigation is behind ☰: <p> <img src="docs/images/screenshot-phone.png" alt="Checklist on a phone" width="240"> <img src="docs/images/screenshot-phone-menu.png" alt="The menu on a phone" width="240"> </p> The screenshots show simulated devices in the Home Assistant palette, which is the start look; `sh tools/screenshots/run.sh` makes them again. ## 🤖 AI assistants (MCP) ShellyLanMan has a built-in [Model Context Protocol](https://modelcontextprotocol.io) 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: ```sh claude mcp add --transport http shellylanman http://<your-host>:3082/mcp \ --header "Authorization: Bearer <token>" ``` | Tools | | |---|---| | Read (always) | `shelly_list_devices`, `shelly_get_device`, `shelly_get_status` and `shelly_get_config` (raw, Gen1 too; passwords masked), `shelly_list_components`, `shelly_get_readings` (24 h of history), `shelly_energy_history` (EM meters), `shelly_firmware_check`, `shelly_checklist`, `shelly_list_backups`, `shelly_script_code`, `shelly_scenes`, `shelly_rpc_read` (Gen2+ `Get*`/`List*` methods, e.g. KVS, schedules, scripts, webhooks) | | Control (*read and control*) | `shelly_switch` (with a flip-back timer), `shelly_light` (with a fade), `shelly_cover`, `shelly_thermostat`, `shelly_scene_run`, `shelly_backup`, `shelly_rescan`; with `confirm: true`: `shelly_reboot`, `shelly_firmware_update` | | Configure (*read, control and configure*) | `shelly_kvs_set`, `shelly_schedule_set`, `shelly_script_create`, `shelly_script_run`, `shelly_webhook_set`, `shelly_virtual_add`, `shelly_scene_set`; with `confirm: true`: `shelly_kvs_delete`, `shelly_schedule_delete`, `shelly_script_put_code`, `shelly_script_eval`, `shelly_script_delete`, `shelly_webhook_delete`, `shelly_virtual_delete`, `shelly_scene_delete`, `shelly_rpc_write` (any Gen2+ method; factory reset also needs `allow_data_loss`), `shelly_device_login` | Scenes are named lists of device actions stored in ShellyLanMan (`/data/scenes.json`). Off by default, read-only unless you choose otherwise, a bearer token on every request, 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. ## 🏠 Home Assistant [`shellylanman-ha`](https://github.com/wimmme/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. [](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fwimmme%2Fshellylanman-ha) [](https://my.home-assistant.io/redirect/hacs_repository/?owner=wimmme&repository=shellylanman-ha&category=integration) Step by step: [`shellylanman-ha`](https://github.com/wimmme/shellylanman-ha#readme). ## 🔒 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. - **UI authentication is off by default** — anyone who can reach the port can use it. A warning is logged at start and shown once per browser. - **Secrets at rest** — device and Wi-Fi passwords are encrypted in `/data` with 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 off by default, needs a token, and is read-only unless you allow control or configuration. - Report vulnerabilities privately: see [`SECURITY.md`](SECURITY.md). ## 💻 Development Only Docker is needed: ```sh 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.md). ## 🤝 Contributing Issues and pull requests are welcome, from typo fixes to new pages. Check the [open issues](https://github.com/wimmme/shellylanman/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`](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. <a href="https://buymeacoffee.com/wimmme"><img src="https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black" alt="Buy me a coffee"></a> <a href="https://www.paypal.com/donate/?business=LPS62D2BRTD2Y&no_recurring=0&item_name=You+help+me+buying+coffee+and+tokens+for+coding+%3A-%29&currency_code=EUR"><img src="https://img.shields.io/badge/Donate-PayPal-0070BA?style=for-the-badge&logo=paypal&logoColor=white" alt="Donate with PayPal"></a> Bugs and ideas: [open an issue](https://github.com/wimmme/shellylanman/issues/new). ## 🙏 Credits - **[ShellyScanner](https://github.com/usnasoft/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](https://github.com/SecOps-7/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](https://github.com/Buggy1111/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`](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. ## 📄 Licence [GPL-3.0-or-later](LICENSE). --- <p align="center">_{Built with the help of <a href="https://claude.ai">Claude</a> by Anthropic.}</p>