How to Set Up Your Pwnagotchi — A Complete Beginner's Guide

How to Set Up Your Pwnagotchi — A Complete Beginner's Guide

The pocket-sized AI that eats WiFi handshakes for breakfast. Here's how to wake it up.

So you've got a Pwnagotchi (or you're seriously thinking about it). Good. You're about to build one of the most satisfying little devices in the maker world — a pocket AI that wanders around sniffing WiFi handshakes like a digital bloodhound, all while pulling adorable faces on its e-ink display.

This guide will take you from "what even is this thing" to fully operational, without leaving you sobbing over a terminal window at 2 am. Probably.

⚠️ Quick legal bit: The Pwnagotchi is an educational and ethical security research tool. Only use it on networks you own or have explicit permission to test. Don't be that person. Now, onward.

🧠 What Actually Is a Pwnagotchi?

Think Tamagotchi, but instead of feeding it pellets it feeds on WiFi. Technically, it's an AI (using a reinforcement learning algorithm called A2C) running on a Raspberry Pi Zero W, powered by a tool called Bettercap. It passively listens for WPA handshakes and PMKID data from nearby networks, saves them as PCAP files, and gets smarter about where to look over time.

It also has a little face. It gets sad when it's bored. It gets excited when it finds handshakes. It's weirdly endearing for a piece of network security hardware.

🛒 What You'll Need

Before anything else, make sure you've got:

  • Raspberry Pi Zero WH or Zero 2WH — the "W" is non-negotiable, you need the Wi-Fi chip and the "H" too, your going to need the header pins for a screen if you want to see what its doing.
  • Waveshare 2.13" e-ink display (V2, V3, or V4 — just know which one you have, it matters for config)
  • MicroSD card — 16GB or 32GB, stick to a reliable brand like SanDisk or Samsung or KEXIN sd cards which are the ones we use for ours, as these work well. 
  • MicroSD card reader — for flashing the image from your PC
  • Micro USB cable — must support data transfer, not just charging.
  • Power bank or battery — any 5V/2A source works. PiSugar 3 is a popular all-in-one option or the UPS hat from wave share which we generally use. 
  • A case (optional but recommended) — our Noppitlabs case fits perfectly and looks the part 😉

Already got a Noppitlabs Pwnagotchi? Then you're ahead, the hardware is sorted and tested. Jump straight to Step 2.

Step 1 — Flash the SD Card

First, grab the latest Pwnagotchi image from jayofelony's GitHub (he maintains the most up-to-date fork of the project — the original pwnagotchi.ai image is quite old now). At time of writing, version 2.9.x is current.

  1. Download the image file (.img.xz)
  2. Download and install Raspberry Pi Imager (free, from raspberrypi.com)
  3. Open Imager → click "Choose OS" → scroll down to "Use custom" → select your downloaded Pwnagotchi image
  4. Click "Choose Storage" → select your MicroSD card
  5. Hit Next, confirm you're happy to wipe the card, and let it write

This takes around 5 minutes. Go make a brew while its loading.

💡 Pro tip: Do NOT use the Raspberry Pi Imager's customisation options to set a username/password — the Pwnagotchi image handles this itself.

Step 2 — Basic Configuration (Before First Boot)

Once the image is written, your SD card should show two partitions. On Windows you'll only see the boot partition — that's fine.

Inside the boot partition, you'll want to create a file called config.toml. This tells your Pwnagotchi its name, display type, and a few other basics.

Here's a minimal starting config you can paste in:

main.name = "pwnagotchi"
main.lang = "en"
main.whitelist = []

ui.display.enabled = true
ui.display.rotation = 180
ui.display.type = "waveshare_2"

Change ui.display.type to match your screen — common values are waveshare_2, waveshare_3, or waveshare_4. If you're not sure which version your display is, check for a sticker or marking on the back.

Save the file and eject the SD card properly before pulling it out.

Step 3 — First Boot (The Patience Part)

Insert the SD card into your Pi. Now, plug your data-capable Micro USB cable into the port closest to the HDMI port on the Pi Zero because that's the data port, not the power port. They look identical, which is evil.

Connect the other end to your computer.

Now wait. The first boot takes 3–5 minutes because the Pwnagotchi generates its unique RSA keys on startup.

🚨 Do not unplug it during first boot. Seriously. If you interrupt key generation, you could corrupt the install and have to start over. Step away from the cable.

You'll know it's ready when you see the Pwnagotchi face appear on the e-ink display, or when you can detect a new USB network interface on your computer.

Step 4 — Connect via SSH

Your Pwnagotchi creates a USB Ethernet connection so you can talk to it from your PC.

On Windows:

  • You may need to install an RNDIS or USB Ethernet driver — check jayofelony's wiki for the latest driver link
  • Once installed, open Network Settings and configure the new interface with a manual IPv4 address: 10.0.0.1, subnet 255.255.255.0

On Mac/Linux:

  • The interface should appear automatically
  • Set it manually to 10.0.0.1 with subnet 255.255.255.0

Once that's done, open a terminal and SSH in:

ssh pi@10.0.0.2

Default password is raspberry. Change this immediately — you know better.

You should now be in. Welcome to your Pwnagotchi's brain.

Step 5 — Connect to the Web UI

The Pwnagotchi has a surprisingly nice web interface for monitoring what it's up to. While connected via USB, open a browser and go to:

http://10.0.0.2:8080

Default credentials are changeme / changeme. Which, yes, you should change.

From here you can see your Pwnagotchi's face, stats, and activity in real time — great for checking it's actually doing something rather than just sitting there looking confused.

Step 6 — Set It Loose (AUTO Mode)

Up until now your Pwnagotchi has been in MANU mode — it's connected to your PC and behaving itself. To actually let it do its thing, unplug it from your computer and power it from a battery bank instead.

It'll boot into AUTO mode, where it roams freely and starts hunting for handshakes. The face will change expression based on what it finds — happy when it's capturing data, bored when nothing's around, and asleep if it's been quiet for a while.

🔌 Plugin Setup — Making It Smarter

Plugins are where the Pwnagotchi really comes alive. Here are a few worth enabling early on:

  • show_ip — displays the device's IP address on screen, handy for connecting without guessing
  • grid — connects your Pwnagotchi to the global Pwnagotchi network, letting it communicate with other units nearby
  • webcfg — adds a terminal to the web UI so you can edit files without pulling the SD card

To enable plugins, SSH in and edit your config file:

sudo nano /etc/pwnagotchi/config.toml

Add your plugin settings and save with CTRL+S, exit with CTRL+X.

🔧 Common Troubleshooting

The display is blank or shows garbage → Check your ui.display.type in config.toml matches your actual screen version exactly

It's been 10 minutes and nothing's happening on first boot → Check you're using the data port, not the power port. Also check your cable actually supports data

I can't SSH in → Double-check your network interface is set to 10.0.0.1 manually, not DHCP

Seven LED flashes on boot → The Pi can't find the kernel — this usually means the image didn't write correctly. Re-flash the SD card

It just shows a sad face all the time → Honestly, same. But for the Pwnagotchi it usually means no Wi-Fi activity nearby. Take it somewhere busier.

🎉 You're Done

You now have a working Pwnagotchi. It's learning. It's growing. It's slightly concerning how attached you're going to get to it.

From here you can explore custom plugins, crack the collected handshakes with Hashcat (on your own networks!), 3D print custom cases, or just enjoy the weird looks you get when people see a tiny AI face on your desk.

If you bought your Pwnagotchi from us; thank you! If anything in this guide didn't work for your specific setup, drop us a message via the contact page and we'll help you sort it.

Happy hunting. Ethically.

The Noppitlabs team 🔧