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, using the camera's own H.264 or the Pi's hardware encoder. 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 link or PDF.
- Web dashboard. Live picture and sound, talk through the
speaker, image tools, trusted people, device selection, settings,
statistics 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 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 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), optional privacy upstream (multi-hop / Mullvad / Tor), a safe fixed-IP script, and help with moving to a new home, router or Pi (see backups).
- 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. No cloud account, no open ports, no telemetry. If you want to help, you can switch on a weekly report of anonymous counts, shown to you before anything is sent.
| Web dashboard | Live picture and sound, people, 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. 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, a VPN like Mullvad's with split tunneling and auto-connect, quick actions such as all fine or away from the app icon, 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. See network. |
| Training | pgtrain on a computer with an NVIDIA GPU: is this me, similar photos, thresholds from your photos and the Pis' anonymous statistics, 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 with automatic updates |
| Debian, Ubuntu, Linux Mint | .deb |
| Fedora, openSUSE | .rpm |
| Other Linux | .AppImage, Flatpak |
| Windows | .exe installer |
| macOS | .zip |
| Android | .apk from the dashboard under Settings › Apps, 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
- a Telegram account
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 the Telegram bot token and your Telegram user ID,
creates a pi-guard system user, writes /etc/pi-guard/pi-guard.env and a
config.yaml for the detected camera, installs a systemd service, and runs
pi-guard doctor. Details: docs/installation.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 |
| 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 |
| Performance | measurements and limits |
| Troubleshooting | common problems |
German: Installation · Bedienung · Dashboard · Netzwerk · Datenschutz · Training · Backup
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 |