headlesswifihelper

Headless Raspberry Pi's are challenging to connect to new networks. This project creates an access point any time your pi is booted without a known network, enabling easy internet access. Through the captive portal, you can pick a network, enter credentials, and optionally write an API key to an .env file.

Tested on Raspberry Pi OS Trixie with NetworkManager as the network backend (the default on Trixie). Older images that still use dhcpcd / wpa_supplicant are not supported.

Install

sudo apt update && sudo apt install -y git
cd ~
git clone https://github.com/tomunderwood99/headless_wifi_helper.git
cd headless_wifi_helper

# Optional Flags - Combine as needed:
#   --env-file /path/to/.env
#   --env-key-name MBTA_API_KEY
#   --ap-ssid "HeadlessWifiHelper"
#   --ap-password "mypassword"

# Examples:
# sudo ./deployment/setup.sh --env-file /home/pi/myproject/.env --env-key-name MBTA_API_KEY
# sudo ./deployment/setup.sh --ap-ssid "MyPi-Setup" --ap-password "mypassword"

sudo ./deployment/setup.sh

Setting a strong password is always recommended. If you do not set a password, the setup script will generate a random one for you.

Configuration

Values end up in /etc/systemd/system/wifi_configurator.service. Set them at install with the flags above, or edit the unit later and run sudo systemctl daemon-reload.

Variable	Default	Purpose
AP_SSID	PiWifiSetup	Hotspot Wi‑Fi name. flag: --ap-ssid.
AP_PASSWORD	(autogenerated)	Hotspot passphrase (≥ 12 chars). flag: --ap-password. The installer rejects the in-source default setupwifi and generates a 16-char random password when the flag is omitted; the runtime also refuses to start with the literal default.
ENV_FILE_PATH	/home/pi/.env	.env path for the optional portal API key. flag: --env-file; omit for the fallback path.
ENV_KEY_NAME	API_KEY	Variable name written into .env. flag: --env-key-name; omit from unit to use the in-code default API_KEY.
WIFI_REGDOMAIN	(unset)	No install flag. Add Environment=WIFI_REGDOMAIN=US (or your ISO code) in the unit if nmcli hotspot fails for regulatory reasons.

Using the project

1. Boot a Pi with no known networks in range.
2. After ~30 seconds the PiWifiSetup (or whatever you set the SSID to) hotspot will appear.
3. Connect — most phones pop the portal automatically; otherwise open http://192.168.4.1.
4. Pick a network, enter credentials, optionally paste an API key, hit Save Credentials.
5. Click Reboot Now.

Integration with other services

Add to any service that should wait for WiFi:

[Unit]
After=network-online.target
Wants=network-online.target

License

MIT — © 2026 Thomas Underwood