Pwnagotchi: an A2C agent that tunes bettercap to collect WPA handshakes

What Pwnagotchi actually collects, and who the target user is

Pwnagotchi is an A2C-based agent that drives bettercap and learns from the WiFi environment around it. The goal is narrow and stated plainly: maximize the crackable WPA key material it captures, either passively or by running authentication and association attacks. The output is PCAP files containing any handshake form hashcat supports, which the README lists as PMKIDs, full WPA handshakes and half WPA handshakes.

The intended user is not a general developer. This is a physical device project: a Raspberry Pi, a display, a battery, and a WiFi adapter that can do monitor mode and injection. The repository is a Python package plus a builder directory that produces a Raspbian Lite image, and the Makefile is the front door for people who want to build that image rather than download one. If you are looking for a library to embed in an existing Python service, this is the wrong shape. If you want a single-purpose box that sits in a bag and accumulates handshakes while you walk around, it is exactly the right shape.

The A2C loop: epochs, an LSTM policy, and parameters that move

The mechanism is a reinforcement learning loop wrapped around a packet capture and attack tool. Pwnagotchi uses an LSTM with an MLP feature extractor as the policy network for the A2C agent, and it tunes its own parameters over time through the defaults.toml file. Time is measured in epochs, and the README notes that a single epoch can last from a few seconds to minutes depending on how many access points and client stations are visible.

That last detail matters more than it looks. The epoch length is a function of the environment, so the learning rate in wall-clock terms is not fixed. In a dense urban area the agent gets many more decisions per hour than in a quiet suburb. The README is explicit that early epochs are exploration and that results at the start will not be impressive. The agent is sampling combinations of key parameters to find what works for the environment you expose it to.

The second mechanism is inter-device communication. Multiple units in close physical proximity advertise their presence to each other by broadcasting custom information elements, using a parasite protocol built on top of the existing dot11 standard. Over time, units trained together learn to cooperate by dividing the available channels among them. This is a channel-allocation scheme implemented through 802.11 information elements rather than through a central coordinator, which is an unusual design choice and one that only works when the units can hear each other.

Installing Pwnagotchi and running a first session

The README points to https://www.pwnagotchi.ai for documentation and does not include install steps inline. What the repository does show is how the image is built. The Makefile fetches packer, clones the packer-builder-arm-image project, builds it, and then runs packer against builder/pwnagotchi.json. The install target is the dependency step and the image target produces the artifact.

make install
make image

The first command downloads packer 1.7.2, moves the binary to /usr/bin/packer, clones https://github.com/solo-io/packer-builder-arm-image into /tmp/packer-builder-arm-image, builds it, and copies the resulting packer-builder-arm-image binary to /usr/bin. The second runs packer in the builder directory with the pwn_hostname and pwn_version variables, then moves the output to pwnagotchi-raspbian-lite-master.img, generates a sha256 file, and zips both. You should see pwnagotchi-raspbian-lite-master.img and its .sha256 alongside it when the build finishes.

The Python package itself installs system files from builder/data into absolute paths and reloads systemd units. One detail in setup.py is worth reading before you run it: install_file skips any destination under /etc/network/interfaces.d/ if the file already exists, referencing issue 483. That guard exists so an upgrade does not overwrite your network configuration. The installer also runs systemctl enable fstrim.timer, which is aimed at SD card longevity on the Pi.

pip install -r requirements.txt

The requirements file pins tensorflow==1.13.1, stable-baselines==2.7.0, gym==0.14.0, scapy==2.4.3, and numpy==1.20.2, among others. Those pins are old and tightly coupled. TensorFlow 1.13.1 will not install on a current Python, so treat the image as the supported path and the pip install as a development convenience. The repository also ships a web UI through flask==1.0.2, flask-cors==3.0.7 and flask-wtf==0.14.3, which is what the web UI questions in search data are about. The README does not document the port or the default credentials, so check pwnagotchi/defaults.toml before assuming anything about how to reach it.

The release gap and what it means for upgrades

The most recent release is v1.5.5 from 2021-04-18. The last push to the default branch was on 2026-08-19. Those two facts describe a repository where the source has moved but tagged releases have not kept pace. If you build from master, you are building something that is not represented by any release tag, and the version string comes from the source tree rather than from a published artifact.

For a project whose install path is a disk image, this is a real operational cost. There is no release channel to pin to, so reproducibility depends on committing to a specific git revision and building it yourself. The Makefile defaults PWN_VERSION to master, which means a naive make image produces an artifact whose provenance is whatever master happened to be that day. Change that variable to a commit hash if you care about rebuilding the same image twice.

The dependency pins compound the problem. TensorFlow 1.13.1 and stable-baselines 2.7.0 are the versions the code was written against. Upgrading either is not a configuration change; it is a port. Anyone planning to keep this running should expect to freeze the whole environment, including the Python version, rather than track upstream releases of its dependencies.

Where Pwnagotchi is the wrong tool

The clearest limitation is legal and environmental rather than technical. Capturing WPA handshakes and running authentication and association attacks against networks you do not own is illegal in most jurisdictions. The project ships the capability and the README says nothing about authorization. That is a deliberate positioning choice by the author, and it means the burden of staying lawful falls entirely on the operator. If you need a tool with an authorization model built in, this is not it.

The second limitation is hardware. The whole design assumes a Raspberry Pi class device with a WiFi adapter capable of monitor mode and injection, plus a display in the inky and smbus2 dependency range. The requirements list inky==1.2.0, smbus2==0.3.0, spidev==3.4 and Pillow==5.4.1, which are the e-ink display stack. Run this on a laptop and you lose the point of the project: the agent expects to be carried through environments and to run continuously on battery. The README's advice to bring it into novel WiFi environments is not a suggestion, it is how the training data gets generated.

The third limitation is the learning curve itself. Because a single epoch can last from seconds to minutes depending on visible access points and stations, and because the README warns that early performance will not be impressive, anyone expecting immediate results will misjudge the tool. It is a slow instrument. It also depends on bettercap being present and working, so failures in bettercap surface as failures in the agent, and the README does not document a rollback path for a bad parameter set.

Pwnagotchi compared with Flipper Zero

The comparison people search for is Pwnagotchi versus Flipper Zero, and the difference is in what the device does with its radio time. Pwnagotchi is a single-purpose learning agent. Its policy network decides how to spend its time across channels and attacks, and its output is a corpus of PCAP files meant to be cracked offline with hashcat. The device gets better at that one job in the environment you put it in, and multiple units can coordinate channel use through custom dot11 information elements.

Flipper Zero is a multi-protocol handheld for reading and emulating sub-GHz, RFID, NFC and infrared signals, with WiFi handled through separate modules. It does not run a reinforcement learning loop, and it does not tune its own parameters based on what it observes. Choosing between them is choosing between depth in one narrow radio task and breadth across many. If your goal is a handshake corpus from a specific area, Pwnagotchi's epoch-by-epoch adaptation is the thing that has no equivalent in a general-purpose handheld. If your goal is to inspect a badge, a remote or a tag, Pwnagotchi cannot help you at all.

Licence and the cost of running a GPL3 image

The README states that pwnagotchi is released under the GPL3 license, and the badge in the README links to LICENSE.md. The repository metadata reports the licence as NOASSERTION, which is a GitHub classification artifact rather than a statement about the project; the README is the clearer source here. GPL3 is a copyleft licence, and the practical consequence for anyone modifying and distributing the image is that the corresponding source has to be made available under the same terms. Running it privately on your own hardware does not trigger distribution obligations.

There is a second licensing layer worth checking: the dependencies. TensorFlow 1.13.1, stable-baselines 2.7.0 and bettercap each carry their own terms, and the image bundles them together. If you plan to redistribute a built image, review those separately. This is not legal advice, and the license file in the repository is the authority, not this paragraph.

Editorial conclusion

Adopt Pwnagotchi if you want a self-contained Raspberry Pi that learns which channels and attacks yield handshakes in your environment, and you are comfortable building or flashing the image yourself. Do not adopt it if you need a maintained release cadence, a supported cloud service, or anything that works without the specific hardware it targets. Before you commit, verify that you can build the image with the Makefile, that your WiFi adapter supports monitor mode and injection, and that you understand the legal position in your jurisdiction, because the project ships the capability and leaves the legality to you.

Frequently asked questions

Official sources

1. evilsocket/pwnagotchi on GitHub
2. Issues
3. Project website
4. README
5. Releases