PwnIOS is an iOS companion app for Pwnagotchi.
Connect your iPhone or iPad to your Pwnagotchi over WebSocket and get live stats, screen mirroring, GPS sharing, network information, events, and remote control from the app.
- Live dashboard — uptime, battery, temperature, mode, and connection status
- Screen mirroring — mirror the Pwnagotchi display directly on your iOS device
- Network monitoring — discovered access points and current-session handshakes
- GPS sharing — send occasional or live iOS location updates to Pwnagotchi
- Handshake location — write the latest coordinates beside captured handshakes
- Events — a focused activity log with optional verbose detail
- Remote control — switch modes and reboot Pwnagotchi remotely
- PiSugar support — battery monitoring through PiSugar
- WebSocket connection — resilient reconnect, heartbeat, and clean shutdown handling
- iOS 16.0+
- jayofelony's Pwnagotchi fork
- iPhone or iPad with Bluetooth tethering enabled
- Python 3.13 with the
websocketspackage
PwnIOS 2.0.0 is tested with Python 3.13.5 and websockets 17.0.1. Verify the package in Pwnagotchi's own Python environment:
/opt/.pwn/bin/python3 -c "import websockets; print(websockets.__version__)"SSH into your Pwnagotchi and copy pwnios.py into the custom plugin directory configured by your image. For example:
cp pwnios.py ~/custom-plugins/pwnios.pyThe location may differ between images. Use the same directory as your other working custom plugins.
Alternatively, add the PwnIOS plugin repository to your Pwnagotchi configuration:
main.custom_plugin_repos = [
"https://github.com/BraedenP232/pwnios/archive/main.zip",
]Then install it:
sudo pwnagotchi plugins update
sudo pwnagotchi plugins install pwniosEdit:
sudo nano /etc/pwnagotchi/config.tomlAdd or modify the PwnIOS configuration:
[main.plugins.pwnios]
enabled = true
# Display
host = "0.0.0.0"
port = 8082
display = false
display_gps = false
# PiSugar
pisugar = false
# GPS
save_gps_log = true
gps_log_path = "/tmp/pwnagotchi_gps.log"
gps_altitude = 10
# Optional: override mode-aware GPS freshness
# gps_stale_seconds = 300| Option | Default | Description |
|---|---|---|
enabled |
true |
Enable the PwnIOS plugin |
host |
0.0.0.0 |
Interface on which the WebSocket server listens |
port |
8082 |
WebSocket server port |
display |
false |
Display iOS connection status on Pwnagotchi |
display_gps |
false |
Display GPS coordinates on Pwnagotchi |
pisugar |
false |
Enable PiSugar battery monitoring |
save_gps_log |
true |
Save GPS data to a log file |
gps_log_path |
/tmp/pwnagotchi_gps.log |
GPS log file location |
gps_altitude |
10 |
Default altitude included with GPS data when the client does not provide one |
gps_stale_seconds |
300 Live / 1800 Battery Saver | Override how long the most recent GPS fix remains valid |
pwnkill && pwnlogDownload Pwnagotchi Companion from the App Store
Connect your iPhone or iPad to the Pwnagotchi using Bluetooth tethering.
Once the connection is established, the app will show Live.
Live Pwnagotchi statistics including:
- Uptime
- Battery
- Temperature
- Current mode
- Connection status
- Pwnagotchi face
Mirrors the Pwnagotchi display directly in the app.
View discovered access points and handshake activity in real time.
Share your iOS device's GPS location with Pwnagotchi.
GPS data can also be logged for later use and written to a .gps.json sidecar when a handshake is captured.
View connection events and Pwnagotchi activity as they happen.
Configure the connection, appearance, location sharing, and notifications.
Check the following:
- Bluetooth tethering is enabled on your iOS device.
- The PwnIOS plugin is enabled in
config.toml. - Pwnagotchi has been restarted after installing or changing the plugin.
- Your iOS device is connected to the Pwnagotchi's Bluetooth network.
- Port
8082is listening:sudo ss -lntp | grep ':8082'. - The plugin reports a startup line in
pwnlog | grep -i pwnios.
If Bluetooth tethering itself is unreliable, see this Pwnagotchi tethering writeup.
Keep the iOS device close to the Pwnagotchi and check the Pwnagotchi's power stability.
Check pwnlog | grep -i pwnios to determine whether the problem is the Bluetooth route, WebSocket listener, or plugin startup.
Check that:
- The Pwnagotchi display is functioning normally.
- The PwnIOS plugin is running.
- WebSocket traffic is being received.
- Debug logging doesn't show connection or parsing errors.
Restarting both the Pwnagotchi and the app can also clear a stale connection.
- Updated the server for Python 3.13 and the modern
websockets.asyncio.serverAPI. - Added deterministic server startup and shutdown across the plugin's background event-loop thread.
- Improved heartbeat, client cleanup, broadcasting, and connection health behavior.
- Added a server hello message so the app can identify plugin and protocol versions.
- Merged Pwnagotchi agent handshakes with captures from the current plugin session.
- Normalized and deduplicated handshake history by filename, preferring current-session metadata and returning the latest 100 entries.
- Used the same normalized history for dashboard statistics and the app's handshake view.
- Improved AUTO/MANU mode reporting by reading the runtime mode used by Pwnagotchi.
- Added GPS coordinate and accuracy validation plus dedicated acknowledgments for accepted fixes.
- Added mode-aware GPS freshness: five minutes for Live GPS and 30 minutes for Battery Saver, unless configured otherwise.
- Preserved GPS sharing, per-handshake GPS exports, face updates, PiSugar data, and remote controls.
- Reduced noisy routine logging while retaining useful lifecycle and error messages.
PwnIOS is not officially affiliated with the Pwnagotchi project.