Setup guide

Guided setup for the current project image

The main path is browser-based and approachable, but this is still a project build. The purpose of this guide is to make the current public image easy to evaluate without pretending the project is already a polished commercial appliance.

Download the Pi image View on GitHub

What you need

Raspberry Pi 4 or 5

4 GB RAM recommended

A microSD card

16 GB or larger, good quality

Official power supply

Plus your home Wi-Fi details

Gateway mode (full IDS/IPS) also needs one AP-capable USB Wi-Fi adapter. Passive mode needs nothing extra.

Step 01

Flash the image to an SD card

Download the latest .img.xz from GitHub Releases. Open Raspberry Pi Imager, choose Use Custom, select the file, pick your SD card, and write it. There are no config files to edit and nothing to type into a terminal.

Recommended hardware: Raspberry Pi 4 or 5 with 4 GB RAM, a good-quality SD card, and the official power supply.

Step 02

Connect to the setup hotspot

Insert the card, power on the Pi, and wait about a minute. On first boot it opens an open Wi-Fi hotspot named IoTSentinel-Setup. Join that network from your phone or laptop. A browser page opens automatically. If it does not, visit http://10.42.0.1:8050/setup.

The hotspot re-opens automatically if the Pi ever loses Wi-Fi later, so you can never lock yourself out.

Step 03

Create your admin account and join Wi-Fi

In the wizard, select your home Wi-Fi network and enter its password so the Pi can reach the internet. Then create an admin account and set a strong password. IoTSentinel forces you to change the default credential, so there is no weak password left behind.

Security from the first screen: bcrypt hashing, login rate-limiting, and optional two-factor and biometric passkeys later in settings.

Step 04

Choose your monitoring mode

Pick Passive for instant, plug-and-play visibility using just the Pi. Or pick Gateway for full IDS/IPS, which routes device traffic through the Pi for real-time ML anomaly detection and inline blocking. Gateway needs one AP-capable USB Wi-Fi adapter.

Not sure? Start Passive. You can switch modes later without re-flashing.

Step 05

Turn on the optional features you want

Enable email alerts and push notifications (ntfy, Telegram, Discord, webhook), pick an AI provider or turn on a fully local model with privacy mode, and switch on AbuseIPDB threat intelligence. Every option is off by default and clearly explained.

Privacy mode keeps the entire AI stack on the Pi, so nothing about your traffic leaves the device.

Step 06

Optionally enable remote access

If you want to reach the dashboard from anywhere, turn on remote access. IoTSentinel sets up a permanent HTTPS URL through Tailscale Funnel with no port forwarding and no VPN configuration.

Leave it off to keep the dashboard strictly LAN-only. It is your choice.

Step 07

You are protected

Review your choices and finish. The Pi reboots onto your home network and the dashboard comes up. Devices appear within moments, vulnerabilities are scanned on join, and the AI starts explaining anything that needs your attention. Install the dashboard as an app from your browser for one-tap access.

Need the full technical detail?

The complete README, architecture notes, and a shipped HTML setup guide live in the repository.

Open the repository