Pwnagotchi

This is a fork of the original pwnagotchi project, actively maintained and modernised for the Raspberry Pi Zero 2 W and current toolchains. The upstream project has been archived; this fork is the recommended path for new builds.

The original RPi Zero W is not supported. The board is underpowered for this workload and its BCM2835/ARMv6 architecture is incompatible with this fork's armv7l build target. Issues about the original RPi Zero W will be closed immediately.

---

What is Pwnagotchi?

Pwnagotchi is an A2C-based AI that uses bettercap to learn from its surrounding WiFi environment, maximising the crackable WPA key material it captures — either passively, or by performing deauthentication and association attacks. Captured material is stored as PCAP files containing any handshake format supported by hashcat, including PMKIDs, full and half WPA handshakes.

The AI uses an LSTM with MLP feature extractor as its policy network for the A2C agent. Unlike typical RL simulations, Pwnagotchi learns over real time measured in epochs. Expose it to novel WiFi environments and it will improve. See the Usage docs for details.

---

This Fork: What's Different

This fork targets the Raspberry Pi Zero 2 W (BCM2710A1, armv7l) and replaces every pre-compiled binary with a source build. It has diverged substantially from the archived upstream.

Supported hardware

Board	Status
Raspberry Pi Zero 2 W	✅ Primary target
Raspberry Pi 3B+	✅ Supported
Raspberry Pi 4	✅ Supported
Raspberry Pi Zero W (original)	❌ Not supported

Key changes from upstream

OS and platform

• Replaced Kali-Pi with Raspberry Pi OS Bullseye Lite 32-bit — eliminates the Kali dependency chain that caused more problems than it solved
• Build target is armv7l (not armv6l) — compiler flags explicitly set via ARCHFLAGS=-arch armv7l

Build pipeline — all binaries compiled from source

• nexmon compiled from source via DrSchottky/nexmon; firmware patches built for all supported boards:
  • RPi Zero 2 W: bcm43436b0/9_88_4_65 and bcm43430a1/7_45_41_46
  • RPi 3B+ / 4: bcm43455c0/7_45_206
• bettercap v2.41.5 compiled from source (Go 1.24.4); no pre-compiled binary trust required
• Go 1.24.4 installed from official upstream — replaces any distribution Go package

Stability fixes

• WiFi power-save mode explicitly disabled — prevents BRCM firmware crashes during packet injection and deauth attacks
• bettercap.py WebSocket client hardened with try/except on all errors and reconnection logic — eliminates silent disconnection failures
• pwnagotchi.service crash recovery improved

Dependency management

• requirements.in is the source of truth for Python dependencies; key packages pinned for platform compatibility (gym==0.14.0, stable-baselines==2.10.2, websockets~=8.1, flask~=1.0, numpy~=1.21.4)
• requirements.txt is not committed — it is regenerated on every image build by pip-compile running inside the armhf environment (Python 3.9, piwheels), ensuring correct platform-specific resolution
• pwngrid and its cloud dependency (api.pwnagotchi.ai) removed — the upstream pwngrid project is unmaintained and the API is defunct. The on_peer_detected and on_peer_lost plugin callbacks no longer fire.

Extra plugins installed (require manual config.toml entries to enable):

• ups_hat_c.py — Waveshare UPS HAT C support
• mastodon.py — Mastodon social posting
• aircrackonly.py — deletes empty PCAP files
• handshakes-m.py — handshake management

Developer experience

• CLAUDE.md at repo root for Claude Code sessions
• docs/design.md — full modernisation design document with phase-by-phase plans
• tests/test_phase1_removal.py — regression test suite (stdlib unittest, no extra dependencies)

---

Releases

Downloads are available on the Releases page. The latest stable release is v1.8.5. The v1.9.0 build (incorporating all modernisation work above) is in progress.

---

Configuration

User configuration lives at /etc/pwnagotchi/config.toml. Do not edit /etc/pwnagotchi/default.toml — it is overwritten on every restart.

Example entries for the bundled plugins:

# Waveshare UPS HAT C
main.plugins.ups_hat_c.enabled = true
main.plugins.ups_hat_c.label_on = true
main.plugins.ups_hat_c.shutdown = 5

# Mastodon
main.plugins.mastodon.enabled = true
main.plugins.mastodon.access_token = "your-token-here"
main.plugins.mastodon.instance = "https://your.instance"

---

Building from Source

The image is built using Packer + Ansible + QEMU. Requires packer (≥1.8.3), qemu-user-static, binfmt-support, and root.

# Build the full image
sudo make image

# Compile locale .mo files only
make langs

# Clean all build artifacts
make clean

The build pipeline:

1. Packer downloads the Raspberry Pi OS Bullseye Lite base image
2. Ansible provisions the image inside a QEMU ARM chroot: installs packages, builds nexmon, builds bettercap, runs pip-compile to generate requirements.txt for the armhf platform, installs pwnagotchi
3. The image is shrunk with pishrink and compressed

---

Contributing

See CONTRIBUTING.md. All commits must be git commit -s signed-off (DCO). Do not mix refactors with fixes in the same PR.

---

Links

	Official Links
Website	pwnagotchi.ai
Forum	community.pwnagotchi.ai
Slack	pwnagotchi.slack.com
Subreddit	r/pwnagotchi
Twitter	@pwnagotchi

---

Support

If you find this fork useful, contributions can be sent to:

BTC: 1CdEWNasdBbu4mB8QgfhFnWwKjHJVJaWZF

---

License

pwnagotchi is made with ♥ by @evilsocket and the dev team. This fork is maintained by @aluminum-ice. Released under the GPL3 license.