Home monitoring for a Raspberry Pi and a USB camera, operated through a web dashboard, apps for your phone and computer, or Telegram, Signal and Discord. It records continuously to local storage, notices movement, and lets you look at your home with two buttons: View photo and View video.
- Records 24/7 to five-minute MP4 segments, copying the camera's own H.264 or encoding with libx264. Old footage is deleted after a retention period, or earlier when the disk fills up: oldest footage without motion first, so there is always room for new recordings.
- Detects motion on small low-resolution frames, with zones, schedules and filters for light switches and sensor noise.
- HOME and AWAY modes. At home, movement is logged but nobody is woken up. Away, alerts arrive with a snapshot. The mode can be set by button, command, timer, or automatically from your phone's presence in the Wi-Fi.
- Telegram first. Large buttons, German and English, a simple view for
everyday users and an advanced view for administrators. Commands work as plain
text (
foto,video 30,abwesend 2h) and as ordinary sentences ("Kannst du mir ein Foto schicken?", "Ich bin wieder da"). - Better pictures on request. Sharper picks the least blurred of several pictures and enlarges the area around a person; Zoom in and Brighter work on the last photo or alert.
- Trusted people (optional). Enroll family members with a name and photos, videos or a picture taken by the camera — or straight from an alert about an unknown person. A bar shows how well each person is learned and which pictures are missing. Unknown people are reported with a photo. Several pictures are judged together, so a family member seen badly once is not reported as a stranger. Who is this? on an event teaches pi-guard a face the camera saw, or that a face is not someone, also for many faces in a row by swiping cards. Learn at the camera takes 20 seconds of varied views in the camera's own angle and light, and Why recognition works or not shows in numbers what holds it back.
- Alarm. Sound the alarm (or your own uploaded sound) on a speaker, and stop it, from the chat.
- Emergency contacts. After an SOS from a phone, or if alerts stay unconfirmed, contacts get a message, and what you chose for each: the place, photos and sound, events, and the emergency medical data as a PDF or only a note that data exist.
- Web dashboard. Live picture and sound, talk through the
speaker, image tools, trusted people, device selection, settings and logs;
installable as an app with push notifications; login by password or key file
with optional two-factor codes, hardware keys, several users (admins, members
and viewers) and your own colours, font and logo. Also a weekly plan, a security
scan, storage clean-up and Wi-Fi QR codes. A setup assistant on first login and
a tutorial with a guided tour, also in the apps, through the assistant and with
/tutorialin chats. - Network (optional). Pi-hole statistics and presence, devices in the LAN, a WireGuard VPN with your own devices, a disguised way for networks that block WireGuard (AmneziaWG), an optional exit through Mullvad (also multi-hop) or your own server with one switch each and per device, sharing the home and guest Wi-Fi by QR code, a safe fixed-IP script, and help with moving to a new home, router or Pi (see backups).
- Linked households (optional). Look after a grandmother's pi-guard from your own: her state, her alarms and every SOS, and her dashboard, without being in her Wi-Fi or VPN and with nothing opened at her home. She decides what you may do, and each household can be a contact of the other: second line, emergency contact, SOS. See linked households.
- Optional, off by default: Signal (via signal-cli), person detection, recognition of enrolled people, microphone clips, speaker playback, MQTT / Home Assistant.
- Nothing leaves the device except the messages you ask for and what an optional part you turn on needs (an AI provider for the assistant, Mullvad, update checks on GitHub, a linked helper's Pi). No cloud account, no telemetry, and no open ports unless you help another household.
| Web dashboard | Live picture and sound, contacts as their own page (face, account, messengers, emergency role, VPN, own pictures with a ring for their rights, a second line before the emergency contacts, and invitations with the dashboard link, apps, login details with a temporary password and a VPN access), where each messenger's messages go, events, weekly plan with calendars, network, settings in a normal and an expert view, a security check with fixes that can be undone, logs in tabs, and members who get only the areas, add-ons and settings you grant. A System page with health checks, the device and its hardware, and updates of the Pi and the apps; notifications as a staircase from at once over the second line and emergency contacts to SOS. Light, dark or as the system. On by default at https://<pi>:8443. |
| Accessibility | Text size, magnifier, colour-blind filters, reading aloud, visible alerts for deaf people, typed speech for people who cannot talk, screen-reader labels, and commands by voice or chat. See dashboard. |
| Android app | The dashboard with alerts without Google, alone or with messengers only for the second line, emergencies and SOS, a VPN like Mullvad's with split tunneling and auto-connect, SOS with camera pictures, photos and sound from the phone and a followed place, finding and tracking lost phones, and an inconspicuous look if you want one. |
| Desktop app | The dashboard in its own window for Linux, Windows and macOS, trusting only your pi-guard's certificate. On Linux also a VPN with kill switch, lockdown, split tunneling and a quantum-resistant tunnel. |
| Server | A small Rust agent connects a PC or NAS: status, security check, updates, Docker, Compose and Git, safe shutdown; and services watched for outages. |
| Add-ons | Server, emergency medical data with PDF, medication plan (BMP or a Markdown table) and a card that opens when logged in, Kid Protect with filters and times without internet for children's devices, network analysis, smart home, remote commands, AI assistant with its costs that also explains settings and changes them with an undo, reviews the security check, and can look at alarm pictures as an emergency contact, offline voice control with a wake phrase, a reverse proxy like frp, more languages, and alerts into Slack, Matrix, Rocket.Chat and Mastodon. Each can be switched off or removed with its data. |
| Plugins | Your own add-ons with commands, pages and API routes, from a ZIP or a Git link, checked before they run. See plugins. |
| Ways home | IPv4, IPv6, a rented server or Tailscale, for every kind of internet connection, and a name that follows the home's address through Cloudflare DDNS. See network. |
| Training | pgtrain on a computer with an NVIDIA GPU: is this me, similar photos, thresholds from your own photos, and a person detector trained on pictures of rooms. Pictures stay on that computer. See training. |
| Updates | Agents and apps update themselves with signed releases, which a compromised Pi cannot fake. The Pi installs only signed releases too, so a hacked GitHub account cannot reach it. One command, scripts/ship.sh, releases everything; new minor and major versions install themselves, patches are offered. See updates. |
| System | Package |
|---|---|
| Arch Linux | .pacman, or ./scripts/install-desktop.sh (downloads newest, then self-updates) |
| Debian, Ubuntu, Linux Mint | .deb, or ./scripts/install-desktop.sh |
| Fedora, openSUSE | .rpm, or ./scripts/install-desktop.sh |
| Other Linux | ./scripts/install-desktop.sh, .AppImage, Flatpak |
| Windows | scripts/install-desktop.ps1, or the .exe installer |
| macOS | .zip |
| Android | .apk from the dashboard under System › Updates, or an invitation link from there |
Build them with scripts/build-desktop.sh and scripts/build-android.sh, see desktop app.
- Raspberry Pi 4 (2 GB is enough) or Pi 5 with Raspberry Pi OS Lite 64-bit (Bookworm or newer); other Debian/Ubuntu ARM64 or x86_64 machines work too
- a USB (UVC) camera; a High Endurance microSD card or a USB SSD
- optional: a Telegram account (the dashboard works without it)
See docs/hardware.md for tested and expected hardware.
git clone https://github.com/lytexdev/pi-guard.git
cd pi-guard
sudo ./scripts/install.shThe installer asks for language, time zone and optionally a Telegram bot token,
creates a pi-guard system user, writes /etc/pi-guard/pi-guard.env and a
config.yaml for the detected camera, turns the dashboard on at
https://<pi>:8443, prints a one-time first login, installs a systemd service
and runs pi-guard doctor. Then: install the certificate from /ca.crt, sign
in, finish the setup assistant, and open Help & tutorial. Details:
docs/installation.md and
docs/dashboard.md.
Docker Compose is available as an alternative: docs/docker.md.
Open the bot in Telegram and press Start:
pi-guard
Your camera is working.
Recording is switched on.
What would you like to do?
[ View photo ]
[ View video ]
[ Camera status ]
[ Notifications ]
[ Help ]
Administrators also see More functions (mode, events, users, invitations, sounds). Add family members with Invite someone; they receive a link and join as viewers. Command reference: docs/telegram.md.
pi-guard doctor check camera, encoder, storage, Telegram, Signal
pi-guard status service state, mode, recordings, recent events
pi-guard cameras detected cameras and a config snippet
pi-guard mode away --for 3h
pi-guard presence status one presence check, per source
pi-guard audio devices
pi-guard telegram test --send
pi-guard logs -f
| Installation | native install, update, uninstall |
| Configuration | .env and config.yaml reference |
| Telegram | bot setup, users, commands and aliases |
| Signal | optional, unofficial; signal-cli setup |
| Privacy | what is stored, what leaves the device, legal notes |
| Hardware | cameras, audio, storage |
| Docker | optional container deployment |
| Dashboard | web dashboard, certificates, app and push |
| Discord | commands and alerts through a Discord bot |
| alerts and exports by email | |
| Mobile app | Android app with VPN, alerts, finding phones and SOS |
| Desktop app | The dashboard as an app for Windows, Linux and macOS |
| Backups | Encrypted backups to Nextcloud, rsync or Borg, and moving to a new home, router or Pi |
| Reverse proxy | Reach services behind NAT through your own server, like frp, in Rust |
| Voice | Talk to the Pi offline: wake phrase, button, push to talk; typed speech |
| Updates | How agents and apps update themselves, signed and verified |
| VPN | Kill switch, lockdown, split tunneling, quantum-resistant tunnel, privacy upstream |
| Network | Pi-hole, WireGuard, fixed address |
| Linked households | Look after another pi-guard without being in its network |
| Add-ons | Service watcher, network analysis, smart home, remote commands, AI assistant |
| Official Cloud API setup and its limits | |
| Public access | Domain, reverse proxy and safe login |
| Plugins | Write your own add-ons |
| API | Tokens and endpoints for your own scripts |
| Server | Connect PCs and NAS: status, security check, updates, Docker, Compose, Git |
| Training | Thresholds and a better person detector, on your own GPU |
| Architecture | how the parts fit together; SQLite schema migrations, no ORM |
| Performance | measurements and limits |
| Troubleshooting | common problems |
German: Installation · Bedienung · Dashboard · Add-ons · Handy-App · Netzwerk · Sprache · Datenschutz · Training · Backup · Discord · E-Mail · WhatsApp · Reverse-Proxy · Verbundene Haushalte
A camera in a home records people who did not choose to be recorded: visitors, carers, neighbours, children. Read docs/privacy.md before installing. Audio recording and face recognition are switched off by default and need deliberate configuration.
Licensed under the MIT LICENSE.
The software is provided "AS IS", without warranty of any kind, to the maximum extent permitted by applicable law.
pi-guard is free. If you want to support it, donations are welcome and entirely optional.
| Monero (XMR) | 89udnKEYMZCBCaoaTYwSLuJBnQRMVPWxW4kNanra4d4GCdgKN5UNjHKU9zk77jvrU726YQYQqeM2PAUhR8jTMrYU6d5cLMp |
| Bitcoin (BTC) | 3B8PdpJnmL7rQyHhBytKtvUT7NgQfraBEH |
| Litecoin (LTC) | MShzshtse85i6ZkwiB1VKNGRNmEL5Dc3VX |