The Pwnagotchi is an A2C-based “AI” powered by bettercap that learns from its surrounding WiFi environment in order to maximize the crackable WPA key material it captures (either through passive sniffing or by performing deauthentication and association attacks).

Originally created by EvilSocket, it was not maintained and was picked up by Jayofelony, Aliminum-Ice, and WPA2 to continue development.

There is great document on the new website, as well as the original website.

I am using the RaspberryPi Imager software with the Jayofelony image(version 2.8.6 at the time of writing) as I am running a RaspberyPi Zero 2W. If you're running on other hardware, see the other images and choose the one that fits your build.

For this, I will be using Debian as my host machine operating system, but this can also be done on Windows with the Putty software for SSH, 7Zip for extracting the image, and you may need RNDIS drivers from ModCloud which can obtained here. I will not be covering those in here but feel fre to reach out if you would like.


After the image is downloaded, extract it so you have a .img file.

Open the RaspberryPi Imager and choose your device. As I am using a Pi Zero 2W, I will be selecing that.

Then choose the image you want. We will scroll to the bottom and select CUSTOM IMAGE and choose our .img we extracted.

Choose the MicroSD card you have inserted.

When asked if you would like to apply OS customisation, choose No.

It will inform you that the entire SD card will be erased and ask if that is OK. Choose yes.

Once it's done flashing, you're good to plug the Micro SD card into your Pi!


Start by connecting the micro-USB cable to the data port of your Pwnagotchi’s RPi, then connect the other end of that cable to your computer.

  • If your Pwnagotchi has already been booted up at least once before, you will soon see a new Ethernet interface on your host computer.

  • If you have never booted your Pwnagotchi before, it will take a few minutes to boot up or become visible or responsive. DO NOT INTERRUPT YOUR PWNAGOTCHI DURING THIS PROCESS. Just give it time to do it's thing, I recommend ~10 minutes.

When you see a new Ethernet interface on your host computer, you’ll need to configure it with a static IP address of:

DNS (if required): (or whatever)

If everything’s been configured properly, you will now be able to ping either or pwnagotchi.local. If we are able to ping the Pi, we should now be able to connect to your unit using SSH:

ssh pi@

With this plugged into your computer, you can go to the pwnagotchi UI at to see it's face in manual mode. The default username and password is changeme:changeme


We can copy the default config file and make edits to that so we know what formatting and such to use. I find this easier but you can also just copy/paste settings or start on your own. To copy the default config we run:

sudo cp /etc/pwnagotchi/default.toml /etc/pwnagotchi/config.tml

The config location is /etc/pwnagotchi/config.yml , to edit this we can run

sudo nano /etc/pwnagotchi/config.yml

With this open we can modify multiple settings, like the name, WiFi's to whitelist(ignore), the default Web UI login, and plugin settings.


There's a variety of cool plugins we can use, such as Bluetooth pairing so we can access the pwnagotchi fom our phone, uploading to websites, and more. There's some 3rd Party plugins as well.

I like to use the bluetooth so I can access it from my phone while out with it, but that isn't necessary.


Our pwnagotchi will indicate the status via a little BT symbol at the top of the screen. The status codes are:

  • C Connected: This means the connection to the device has been established.

  • NF Not found: This means the connection to the device could not be established (probably because it could not be found).

  • PE Pairing Error: This error occurs on a pairing problem.

  • BE Bnep Error: This error occurs, when the NAP could not be created.

  • AE Address Error: The IP could not be assigned to the NAP interface.


To set this up, in the config file, we find a section to add in our phones bluetooth mac address. Depending on if you're using iPhone or Android will determine which section you use. It's straight forward when reading it.

After we save the setting and put it into Auto mode via the web UI, make your device discoverable via bluetooth, and it should attempt to pair/connect with your phone.

If this does not try to connect after a couple mintes, we may need to manually pair our devices together. To do this, put your phone in discoverable mode. On our pwnagotchi, run

sudo bluetoothctl

and once in the bluetooth-shell, to scan for nearby bluetooth devices, run

scan on

When you see the name/mac address of your phone run:

pair <mac>


trust <mac>

We will soon be prompted on the phone to allow connection from our pwnagotchi hostname.

Once we pair and trust the device, we can see we're connected!


With that, we've got a pwnagotchi setup and connected via Bluetooth. From here, experiment with other plugins, get a nice waveshare sceen and PiSugar battery to make it even more portable! Even checkout ways to cusomize it with Fancygotchi if you're not using Jayofelonys image like I am.

Last updated