// Your one-stop guide to setting up and customizing your AI-powered WiFi audit companion //
Pwnagotchi is an A2C-based "AI" powered by bettercap that learns from its surrounding WiFi environment to maximize the crackable WPA key material it captures (either passively or through deauthentication and association attacks).
Think of it as a Tamagotchi for hackers - it has moods, expressions, and learns over time to become more effective at capturing handshakes. The more you walk around with it, the smarter it gets!
Download the latest pwnagotchi image and flash it:
# Download from official releases or community builds
# Use Balena Etcher or Raspberry Pi Imager to flash
# For headless setup, create these files on boot partition:
touch /boot/ssh # Enable SSH
nano /boot/config.toml # Your config fileEdit /etc/pwnagotchi/config.toml:
main.name = "YourPwnagotchiName"
main.lang = "en"
main.whitelist = ["YourHomeWiFi"]
ui.display.enabled = true
ui.display.type = "waveshare_v3"
ui.web.enabled = true
ui.web.address = "0.0.0.0"
ui.web.port = 8080
ui.web.username = "changeme"
ui.web.password = "changeme"Connect via USB (gadget mode) or configure WiFi:
# USB Connection (Pi Zero)
# Connect to data port, access via:
ssh [email protected]
# Web UI available at:
http://10.0.0.1:8080pi:raspberry or changeme:changeme - change them!
The official documentation with installation guides, configuration, and plugin development.
OFFICIAL DOCSOriginal evilsocket repository - the OG pwnagotchi source code.
SOURCE ORIGINALCommunity maintained fork with modern Pi support (Pi 4, Pi 5, Pi Zero 2 W).
COMMUNITY ACTIVE64-bit builds with better performance for newer Pi models.
64-BIT PI5Make your pwnagotchi unique with custom face packs!
The ultimate custom faces repository with 15+ themes including Rick & Morty, Pikachu, Miku, and more!
FACES THEMES MUST-HAVECute e-girl themed face pack by PersephoneKarnstein.
FACES ANIMEFallout-inspired Vault Boy face pack - War never changes!
FACES GAMINGOfficial guide on implementing custom PNG faces.
GUIDE DOCS| Theme | Description | Author |
|---|---|---|
| White Rabbit | Follow the white rabbit... Matrix inspired | CodyTolene |
| Rick Sanchez | Rick from Rick and Morty | PondSec |
| Morty Smith | Morty from Rick and Morty | PondSec |
| Pickle Rick | I'M PICKLE RICK! | PondSec |
| Pwnachu | Pikachu themed pwnagotchi | roodriiigooo |
| Pwnaflipper | Flipper Zero's dolphin crossover | roodriiigooo |
| Pwnaflowey | Flowey from Undertale | roodriiigooo |
| Rebecca | Rebecca from Cyberpunk Edgerunners | Zerodya |
| Hologram (Holo) | Holo from Spice and Wolf | SeverX |
| Mikugotchi | Hatsune Miku themed | SeverX |
| Hackers Movie | Inspired by the 1995 Hackers film | cyberspacemanmike |
| Radical Edward | Ed from Cowboy Bebop | cyberspacemanmike |
| Retro Computer | Classic retro terminal vibes | Curious-Keeper |
| Cynical Girl | Random cynical anime girl | sumeshi |
| E-Girl | Cute e-girl aesthetic | PersephoneKarnstein |
| Vault Boy | Fallout's iconic mascot | JD-2006 & GhosTech-IT |
Collection of community plugins for extended functionality.
PLUGINS COLLECTIONEven more community plugins!
PLUGINS COMMUNITYFor Raspberry Pi 3/4/5 or enhanced capabilities on Pi Zero:
| Adapter | Chipset | Bands | Notes |
|---|---|---|---|
| Alfa AWUS036ACH | RTL8812AU | 2.4/5 GHz | Great range, dual band |
| Alfa AWUS036ACHM | MT7610U | 2.4/5 GHz | Excellent for 5GHz |
| Alfa AWUS036ACM | MT7612U | 2.4/5 GHz | High power, great for Pi5 |
| Alfa AWUS036AXM | MT7921AU | 2.4/5/6 GHz | WiFi 6E support! |
| Panda PAU09 | RT5572 | 2.4/5 GHz | Compact, good support |
| TP-Link TL-WN722N v1 | AR9271 | 2.4 GHz | Classic choice (v1 only!) |
Free online WPA handshake cracking service. Upload your .pcap files!
ONLINE FREETools for capturing and converting WPA handshakes.
TOOLS CONVERSION# Convert .pcap to hashcat format
hcxpcapngtool -o hash.hc22000 capture.pcap
# Crack with hashcat (mode 22000 for WPA)
hashcat -m 22000 hash.hc22000 wordlist.txt
# Use rules for better coverage
hashcat -m 22000 hash.hc22000 wordlist.txt -r best64.ruleThe ultimate collection of security-related wordlists.
COLLECTION MUST-HAVE# Check display type in config
ui.display.type = "waveshare_v3" # or v4, waveshare_2, etc.
# Enable SPI
sudo raspi-config # Interface Options > SPI > Enable
# Check connections - RST, DC, CS, CLK, DIN pins# Check interface is in monitor mode
iwconfig
# Check bettercap is running
sudo systemctl status bettercap
# Check pwnagotchi logs
sudo journalctl -u pwnagotchi -f# Check web config
ui.web.enabled = true
ui.web.address = "0.0.0.0"
ui.web.port = 8080
# Check if service is running
sudo systemctl status pwnagotchi
# Try accessing via IP
http://10.0.0.1:8080 # USB gadget mode
http://192.168.x.x:8080 # WiFi# Check /boot/config.txt has:
dtoverlay=dwc2
# Check /boot/cmdline.txt has:
modules-load=dwc2,g_ether
# On your computer, look for RNDIS gadget deviceActive Reddit community for pwnagotchi enthusiasts.
REDDIT COMMUNITY