PingKit Agent installs as a Home Assistant app and watches your own network from the machine that is already on. It puts your internet and your devices into Home Assistant over MQTT and, with Guardian, tells your iPhone when the internet goes down or a new device joins.
Get PingKit for iPhoneFree to run, no account. Alerts on your iPhone need Guardian: $2.99 a month or $24.99 a year on iPhone, with a 1-week free trial.
PingKit Agent is the same agent as PingKit Agent for Docker and Raspberry Pi, packaged as a Home Assistant app. (Before Home Assistant 2026.2, apps were called add-ons.) It watches your network while Home Assistant runs and:
It covers Wi-Fi and wired IP devices only, not Zigbee or Z-Wave. It watches; it does not block devices or change anything on your network.
Open PingKit on your iPhone, go to Agents and tap Add an Agent. Keep the 8-character code it shows: it works once, for 10 minutes. No iPhone? Leave the code empty: the agent still watches, shows its pages and sends to your own services.
Press the button below, or in Home Assistant open Settings, Apps, Install app, then Repositories in the menu at the top right, and add https://github.com/pingkit/ha-apps.
Add the repository to your Home Assistant
Install PingKit Agent, paste your code into Claim code in its Configuration tab, save, and start it. Your iPhone shows the agent within a minute. You can clear the code after pairing. In Home Assistant, use the Claim code option rather than the status page's code form.
The app is built for aarch64 and amd64 only. On a Raspberry Pi, Home Assistant OS needs the 64-bit image. Home Assistant builds the app on your machine when you install or update it: the build adds one line to the published PingKit Agent image and compiles nothing, so it takes seconds. Updates arrive through the app store like any other app.
If you have an MQTT broker, such as the Mosquitto broker app, the agent puts your network into Home Assistant by itself. Home Assistant hands it the broker's address and login, so there is nothing to type. Without a broker the agent runs as before.
You get:
consider_home setting). The agent does that waiting itself.Setting it up for a household, testing it with a sleeping phone, and when the Companion app or your router is the better source: Home Assistant presence detection from your own network.
Discovery and state messages are retained on your broker, so the broker keeps your device names, and anyone who can read that broker can read them. They go nowhere else: the broker is your own. The topics and payloads are documented in the agent's repository.
There are no speed test or Wake-on-LAN entities. The agent's daily speed test and Wake-on-LAN through the agent are in PingKit on your iPhone, with Guardian.
The Notification targets option sends the same alerts to services of your own, free and with no iPhone needed: one URL per row, masked on screen. For example:
ntfy://192.168.1.5/home-nettgram://bot-token/chat-id for Telegramdiscord://webhook-id/webhook-tokenpover://user-key@app-token for Pushoverwebhook+http://homeassistant.local:8123/api/webhook/your-id, Home Assistant's own webhook triggerapprise://192.168.1.5:8000/key for anything else, through apprise-apiDuring an outage, a target on your own network hears at once. A target on the internet hears once it is back, in one message with how long the outage lasted. The agent sends a POST to the URL you gave and reads only whether it worked. Every target's URL form.
Home Assistant cannot report its own outage: when its machine loses power, nothing on it can send a message. The agent keeps a connection to PingKit's server, and with PingKit Guardian that server notices when the connection goes quiet and tells your iPhone that the internet looks down at home within about three minutes. When the machine is back, the agent records the time it was not running as unmonitored, never as up.
More ways to be told: Get an iPhone Alert When Home Assistant Goes Offline.
Open Web UI, or the sidebar panel, which is shown to administrators, opens the agent's status page: pairing, the interface and gateway it watches, the last sweep and recent events. Device names and addresses are on the Devices and Timeline pages. In the sidebar they open at once, because your Home Assistant login already guards it and its port answers only Home Assistant. On your network, at http://<this machine's IP address>:7474/, they are behind a six-digit PIN: your iPhone shows it, and the app's log prints it at every start.
The app uses the host's network, because the neighbour (ARP) table and the Bonjour (mDNS) and UPnP (SSDP) announcements only exist on your real network. It asks for nothing else: no added capabilities, no full access, and an AppArmor profile of its own. That gives it a security rating of 7 of 8; the point it loses is the host network.
Home Assistant creates the app's /data folder owned by root, so the app starts as root for one step: before it reads any setting from the network, it gives that folder to its unprivileged user, switches to that user for good and gives up every capability. Its log says so in its first line, privileges_dropped. It never opens a raw socket.
Home Assistant backs the app up while it runs, so the agent keeps watching. A backup includes the agent's pairing, so a restored backup brings the pairing back; someone holding such a backup could act as this agent, so keep backups as private as the machine itself.
Turn on Watchdog on the app's Info tab and Home Assistant restarts the app if it stops answering. It asks /livez, which reads only the agent's own loops, so an internet outage, which the agent is there to record, does not make it restart.
Home Assistant already has ways to see devices on your network. Each does a different job, and they can run together. What each integration does is as its page on home-assistant.io describes it, checked 2026-11-11.
| How it checks | What else it needs | |
|---|---|---|
| PingKit Agent | Sweeps your network and listens for Bonjour and UPnP announcements; checks the internet once a minute; publishes to Home Assistant over MQTT | An MQTT broker for the entities; PingKit on an iPhone with Guardian for push alerts |
| Nmap Tracker | Scans the network for devices with Nmap (local polling) | The addresses to scan |
| Ping (ICMP) | Sends ICMP echo requests to a host, every 30 seconds by default (local polling); a reachability sensor, plus round trip time, jitter and packet loss sensors, and a device tracker that is off by default | One entry per host you want to watch |
| Fing | Reads Fing's device inventory over its Local API (local polling); introduced in Home Assistant 2025.11 | A Fing Agent, Fingbox or Fing Desktop with the Local API on, and its address, port and API key |
If you want latency and packet loss for one host as sensors, the Ping integration does that and PingKit Agent does not. What the agent adds is the internet's state with Internet Down and Restored, new-device alerts after a learning day, a tracker per phone without listing addresses, and, with Guardian, the alert that still arrives when Home Assistant itself is down.
Running the agent is free, with or without an iPhone. The paid part is the relay and the dashboard on your iPhone, and it funds the one person who builds PingKit.
| Free | PingKit Guardian | Guardian Plus | |
|---|---|---|---|
| The agent, its pages, alerts to your own services (webhook, ntfy, Telegram, Discord, Pushover, apprise-api), Home Assistant entities over MQTT | yes | yes | yes |
| Pair an iPhone, see the agent's state | yes | yes | yes |
| The agent's timeline on your iPhone | the last 24 hours | yes | yes |
| History shown, on the iPhone and on the agent's pages (the agent keeps a year on disk either way) | 30 days on the agent's pages | 90 days | 365 days |
| Push to your iPhone for every alert kind, the Live Activity, the widget, Control Center, Siri | yes | yes | |
| The dashboard: devices, outages, loss and latency, speed tests, Wake-on-LAN and other actions from the iPhone | yes | yes | |
| The Internet Outage Report for your provider | yes | yes | |
| Agents | 1 | 1 | up to 5 |
| Phones per agent | 1 | 1 | up to 5 |
Prices in US dollars, each plan with a 1-week free trial. PingKit Guardian is $2.99 a month or $24.99 a year on iPhone and on Mac. Guardian Plus is $9.99 a month or $79.99 a year on iPhone, and $4.99 a month or $39.99 a year on Mac. A subscription bought on either device counts on both, and the higher tier wins. See PingKit Guardian and pricing.
It watches while Home Assistant runs. It sees nothing while the machine is off.
aarch64 and amd64 only: Home Assistant OS on a Raspberry Pi needs the 64-bit image.
Wi-Fi and wired IP devices only, not Zigbee or Z-Wave.
No speed test or Wake-on-LAN entities in Home Assistant.
A device is reported offline after three missed sweeps, up to 45 minutes at the default sweep.
It does not block devices. That is your router's job.
Have a Mac that stays awake instead? The Mac Agent does this from the menu bar. No Home Assistant? Run the agent with Docker or on a Raspberry Pi.
Both names mean the same thing. Home Assistant called apps add-ons before 2026.2, so older guides use the old word. You install it from Settings, Apps, Install app.
Yes, on the 64-bit image. The app is built for aarch64 and amd64 only, so a Raspberry Pi needs the 64-bit Home Assistant OS.
Only for the entities. Without an MQTT broker the agent still watches your network, shows its status page and sends its alerts. With the Mosquitto broker app installed, Home Assistant hands the agent the broker's address and login, so the entities appear with nothing typed.
The agent stops with it, so nothing on that machine can tell you. With PingKit Guardian, PingKit's server notices that the agent's connection has gone quiet and tells your iPhone that the internet looks down at home within about three minutes. When the machine is back, the agent records the time it was not running as unmonitored, never as up.
No account. Running the app, its pages, its Home Assistant entities and its alerts to your own services are free, with or without an iPhone. Alerts in PingKit on your iPhone need PingKit Guardian.
Download PingKit, open Agents and tap Add an Agent for your code. Running the agent is free.
Download Free on the App StoreRequires iOS 17.0 or later and PingKit 4.0 or later. Alerts from your agent need Guardian.