A health and diagnostics tool for Matter devices, to use next to your existing controller.
When Google Home, Apple Home or Alexa report a device as not responding, they usually don't say why.
matter-peek can help you find out.
It is added to your Matter devices as an additional admin, next to the controller you already use, and shows what the devices report about themselves: uptime and reboots, Wi-Fi signal and Thread mesh links, free heap and stack, and crash logs.
It can also commission devices, show and edit their full data model, and update their firmware. Optionally, an AI assistant can look through all of this for you and answer your questions about it.
It runs locally on your network and does not need an account. It is a single self-contained executable, written in Rust and built on rs-matter. Builds for Linux, Windows and Android are under Download.
See the screenshots for more.
- Health and logs. Uptime, reboots, network faults, and heap and stack usage, updated live. A health check judges the signs of crashes, the heap, the stacks and the link of each device. Crash and diagnostic logs are retrieved over BDX.
- Commissioning and sharing. Commissioning over IP or Bluetooth LE, onto Wi-Fi or Thread. Devices can be added from other ecosystems, or shared with them.
- Data model. All clusters, attributes, commands and events, by name and updated live, with controls for common device types.
- Thread mesh. A view of the Thread mesh built from Matter data only, without Thread credentials. Problems it detects are described in plain words.
- OTA updates. matter-peek acts as the OTA Provider for your devices: upload an image, then start the update.
- AI. An MCP server for Claude, Cursor and other MCP clients, and a built-in assistant that works with any OpenAI-compatible model, including local ones.
Other features include multiple fabrics, network management, a time source and a common filter language. The web UI, the CLI and the app all use the same API.
matter-peek consists of two executables:
matter-peek: the server with the web UI, the CLI, the MCP server and the terminal chat, in a single file. It also runs on headless machines, such as a Raspberry Pi, a NAS or a container.matter-peek-app: the web UI as an app, on the desktop and on Android. It either runs its own controller, or connects to amatter-peekserver.
No official releases yet.
Pre-release builds from the latest commit on main can be downloaded from here.
| Platform | File | What is in it |
|---|---|---|
| Linux, x86_64 | matter-peek-x86_64-linux-<time>.tar.gz |
matter-peek, static, for any distribution; matter-peek-app, for glibc 2.35 or newer (Ubuntu 22.04, Debian 12) with WebKitGTK 4.1 (libwebkit2gtk-4.1-0) |
| Linux, aarch64 (Raspberry Pi) | matter-peek-aarch64-linux-<time>.tar.gz |
matter-peek, static, for any distribution |
| Windows 10 and 11, x86_64 | matter-peek-x86_64-windows-<time>.zip |
matter-peek.exe and matter-peek-app.exe; not tried on Windows yet |
| Android 7 and newer, 64-bit ARM | matter-peek-aarch64-android-<time>.apk |
the app: open the file on the phone to install it |
<time> is when the build was made, in UTC (for example 20261028143005). The Linux and Windows archives also contain a script that installs matter-peek as a service: see Run as a service.
matter-peek is fully usable, but not yet released. Planned next:
cargo install matter-peekfrom crates.io: the names are reserved, but the real crates wait for an rs-matter release that has everything matter-peek uses.- Releases for Linux, Windows and macOS, in place of the CI builds above.
- The app in Google Play, and an app for iPhone.
Note: the server asks for an access token, which it shows when it starts. There is no TLS yet: the token and everything else travel unencrypted, so use the server on a network you trust, or reach it through a VPN or an SSH tunnel.
Both executables can be built on Linux (x86_64 or aarch64) with Rust 1.92 or newer. You can use the Rust packaged by your distribution, or install it with rustup. On Ubuntu 24.04, whose newest packaged Rust is 1.91, use rustup.
# Option 1: Rust from your distribution (this also installs the C toolchain Rust needs for linking)
sudo apt install cargo # Ubuntu 26.04, Debian testing
sudo apt install -t trixie-backports cargo # Debian 13, Raspberry Pi OS (backports enabled)
# Option 2: Rust from rustup
sudo apt install build-essential # the C toolchain Rust needs for linking
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # then open a new shellmatter-peek
cargo install --locked --git https://github.com/sysgrok/matter-peek matter-peekmatter-peek-app
sudo apt install pkg-config libwebkit2gtk-4.1-dev libdbus-1-dev
cargo install --locked --git https://github.com/sysgrok/matter-peek matter-peek-appNotes:
cargo installputs the executables in~/.cargo/bin. rustup adds that directory to yourPATHautomatically. If you installed Rust from your distribution, that is not the case, and you need to add it to yourPATHyourself.- The package names above are for Debian, Ubuntu and Raspberry Pi OS. Other distributions provide the same packages under their own names.
- To find devices, both executables use Avahi when it runs, else systemd-resolved when its mDNS is on (
MulticastDNS=yes), else their own mDNS responder. To commission over Bluetooth, they use BlueZ. Most desktop systems already run Avahi and BlueZ. If yours does not, install them withsudo apt install avahi-daemon bluez.
Static builds, Raspberry Pi builds and the Android app are described in Building. To run matter-peek as a service, see Run as a service.
matter-peek serve # then open the address it shows: http://127.0.0.1:17335/?token=…To add devices, either commission a new device from the Commission page, or add a device you already use with another controller. For the latter, first share the device from that controller (Google Home: Linked Matter apps & services; Apple Home: Turn On Pairing Mode; Home Assistant: Share device), then commission it with the code it shows.
The same from the command line:
matter-peek discover # list the commissionable devices nearby
matter-peek commission 34970112332 --ble --wifi Home --wifi-password '...'
matter-peek list net:thread is:offline # list the devices matching a filter
matter-peek peek 0x1B67B # show a device's health
matter-peek health 0x1B67B # check it: crashes, heap, stacks, link
matter-peek logs 0x1B67B crash # retrieve its crash log
matter-peek thread findings # show the problems found in the Thread mesh
matter-peek --helpThe web UI can also be installed as an app of its own: an iPhone, for example, adds it to its home screen. See the user guide.
If a server is running, pass --server ws://127.0.0.1:17335 so that the CLI uses it. As the user who runs the server, the CLI finds its access token by itself; otherwise, give it with --token (matter-peek token prints it). Without a server, the CLI runs its own controller.
matter-peek serve listens on this machine alone by default. --listen 0.0.0.0:17335 makes it reachable from the network, for example from the app on a phone or a browser on another computer.
Using AI:
# Claude Code, or any other MCP client (read-only unless you add --allow-mutate)
claude mcp add matter-peek -- matter-peek --server ws://127.0.0.1:17335 mcp
# The built-in assistant, here with a local model
matter-peek assistant set --url http://localhost:11434/v1 --model qwen3.5:9b
matter-peek chat "Which of my Thread devices have weak links?"To keep matter-peek serve running in the background, and start it at boot, the Linux and Windows downloads come with a script that sets this up. For a build from source, the scripts are in service/.
Linux (systemd), in the unpacked download:
sudo ./install-service.sh # with a build from source: --bin ~/.cargo/bin/matter-peek
journalctl -u matter-peek -f # its log
sudo ./install-service.sh --uninstallThe service runs as the system user matter-peek, which the script creates, with its store and its access token in /var/lib/matter-peek. The script copies the executable to /usr/local/bin; running it again updates it.
Windows, in the unpacked download, from a PowerShell started as administrator:
powershell -ExecutionPolicy Bypass -File .\install-service.ps1
powershell -ExecutionPolicy Bypass -File .\install-service.ps1 -UninstallThis runs matter-peek serve at boot, as a scheduled task of the SYSTEM account, with its store and its access token in C:\ProgramData\matter-peek. It lets private and domain networks reach it through Windows Firewall. It keeps no log yet, and it has not been tried on Windows yet.
Both listen on the whole network, at port 17335, and end by showing the address to open, with the server's access token in it. --listen (-Listen on Windows) changes that: 127.0.0.1:17335 keeps the server to the machine it runs on. Read the note under Status: there is no TLS yet. Uninstalling keeps the store, because it holds the keys of our fabrics: without them, our devices can only be factory reset.
To set up a service another way, matter-peek --store-dir <dir> serve keeps the store in <dir>, as both scripts do.
The store can be backed up to a file encrypted with a passphrase, and restored, from the web UI or with matter-peek export and matter-peek import. The app can also move its store to a server. The guide describes how.
- Screenshots: the pages and pop-ups of the web UI
- User guide: devices and filters, fabrics, sharing, time, the Thread mesh, the data model
- AI: the MCP server and the assistant
- Building: the crates, static builds, the app on Android, working on the web UI
- Design: the architecture and the roadmap
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.