- An urban beggar who typically stands on a street with a homemade cardboard sign containing either a humorous appeal, a solemn oath, or a sorrowful lamentation. Always accompanied by an outstretched hand or container for bills & loose change; One who panhandles.
- A bum, Hobo, Traveler, Crusty, Street Urchin, Squatter, un-housed (in-between residences at the moment), homeless (one without a home)
- Grifter.
A Raspberry Pi 3B that flies a cardboard sign on every hostile network while quietly guarding the devices behind it, managed only from the mesh. The sensor side (its "hobo SOC") is v2. It exists to solve a problem the author actually has: living on rotating public Wi-Fi where networks are hostile, discovery is off, and captive portals + client isolation make normal homelab reach impossible.
A panhandler with claim to a busy intersection darts in and out of the flow of traffic gathering spare change and other forms of charity, defending his claim to the location, and acting as a silent witness to everything that passes through that single city block. The travel router in this repo does the same for the small footprint its user occupies on the internet every time they go online: an unassuming defender for the devices on the user's mesh today, and its watcher and collector once the v2 sensors land.
One always-on, pocket-sized Linux node with two faces:
- On the hostile LAN (hotel/public Wi-Fi): the most forgettable device on the network — a per-network MAC, no DHCP hostname, no open ports, no mDNS. A panhandler no one looks at twice.
- On the tailnet:
panhandler— a privacy gateway (and, in v2, a sensor platform) you reach from anywhere, through client isolation, with no captive-portal dance.
Built on: NixOS (aarch64, cross-built from the laptop) + nixos-hardware + nix modules.
| Area | Implementation |
|---|---|
| Gateway | Laptop on eth0 (10.73.0.1/24, DHCP); hotel Wi-Fi on wlan0; NAT plus forward filtering (gateway.nix) |
| DNS | Blocky ad and tracker blocking, DoH upstream to Quad9, bound to the trusted side only |
| Egress | Direct (default) or Tor (transparent proxy, fail-closed, no fallback) (egress.nix) |
| Captive portals | A cable client gets a 600 s window to log in through the Pi's uplink (portal.nix) |
| Disguise | Per-SSID stable MAC, no DHCP hostname, no mDNS, ICMP echo dropped on wlan0 |
| At rest | tmpfs root; secrets in LUKS2 (Adiantum) /persist; three independent unlock keyslots |
| Theft response | Boot-cluster detection triggers LOCKDOWN (unlock over the cable only) |
| Control plane | panhandler-webd: Go and Svelte UI on :8080 for Wi-Fi scan, join and forget, egress, portal |
| Tailnet | Restricted ACL: a compromised Pi can reach nothing except phone check-ins (policy) |
Roadmap (v2+, not built): passive network auditor, CertStream sentinel, FOIA watcher,
on-device ML triage, slot-machine dApp fairness watchdog, lost-mode beacon, USB Wi-Fi AP. The
contracts the watchdog will watch (CryptoSpin on Solana/Rust, and a Solidity slot) are audited as
separate projects (BLUEPRINT §7). See RISKS.md §2 for why the
spine comes first.
flowchart LR
subgraph trusted["Trusted side"]
L["Laptop (volnix)<br/>10.73.0.x"]
P["Phone<br/>Termux listener :8463"]
end
subgraph pi["Panhandler (Pi 3B)"]
E["eth0 10.73.0.1<br/>DHCP · Blocky · UI :8080"]
F{{"nftables<br/>default-deny"}}
W["wlan0<br/>cover MAC · 0 open ports"]
T["tailscale0"]
end
H(("Hostile Wi-Fi")) --> I(("Internet"))
L == cable ==> E --> F --> W --> H
F -. Tor mode .-> TOR["tor TransPort"] --> W
T <-. WireGuard mesh .-> L
T <-. WireGuard mesh .-> P
stateDiagram-v2
[*] --> Clamped: firewall start or reload
Clamped --> Direct: saved mode = direct
Clamped --> Tor: saved mode = tor and /persist unlocked
Direct --> Tor: UI or ph-egress tor
Tor --> Direct: UI (tailnet laptop or phone only) or cable SSH
Tor --> Portal: cable client requests portal access
Portal --> Tor: logged in or 600 s expiry
note left of Tor: tor down = traffic blocked, never falls back to Direct
/persist stays sealed until the laptop and phone agree. The phone share is wrapped by a
hardware-Keystore key that requires a fingerprint.
sequenceDiagram
participant Pi
participant Phone
participant Laptop
Pi->>Pi: boot base system, locked tailnet identity
Pi->>Phone: check-in (boot log, cluster count)
Phone-->>Phone: notification, fingerprint tap
Laptop->>Phone: fetch phone share (released for 2 min)
Laptop->>Laptop: key = laptop share ⊕ phone share
Laptop->>Pi: SSH forced command, pushes key
Pi->>Pi: open LUKS /persist, swap to main identity, start Tor
If the phone records three boots inside its cluster window, or the Pi counts consecutive short boots, the box enters LOCKDOWN: the phone refuses to release its share, and only the passphrase or Bitwarden slot over the cable will unlock it.
| Mount | Encrypted | Holds |
|---|---|---|
/ |
tmpfs | Everything else, wiped on reboot |
/nix, /base |
No | Public config, SSH host key, locked tailnet identity, current Wi-Fi only |
/persist |
LUKS2 | Main tailnet identity, sops age key, saved Wi-Fi profiles, Tor state |
You need: a Nix host with flakes and boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
age, sops and rbw (Bitwarden); a Pi 3B with a ≥ 32 GB SD card; an Ethernet cable; and an
Android phone with Termux and Termux:API for the quorum share.
git clone https://github.com/lowcache/thePanhandler && cd thePanhandler
make provision-keys # 1. unlock SSH key → keys/unlock-keys.pub
git add keys/unlock-keys.pub # flakes ignore untracked files
make image # 2. build the SD image (cross-built via binfmt)
make provision-card IMAGE=$TMPDIR/ph-build/sd-image/sd-image/*.img.zst DEVICE=/dev/sdX
# 3. flash, partition, LUKS, split key (destructive, asks first)
make up # 4. cable, wait, unlock, uplink, laptop routes via PiAdapt the host to your setup first: everything personal (login user and key, management peers,
tailnet names, persist UUID, phone URLs, sops file) is in hosts/panhandler.nix;
the generic router is modules/, exported as nixosModules.hobosec for use from
another flake. Also the PI_* and LAPTOP_ETH addresses in the Makefile,
.sops.yaml recipients, and the tailnet policy in security/.
On the phone, run phone/enroll.py once, then run the listener under
termux-services (phone/sv/).
make # list every target
make health # uplink, connectivity, failed units, uptime
make deploy # build, copy and activate over the cable (VIA=tailnet for remote)
make rollback # previous generation
make checks # NixOS VM tests (spine, hardening)| Task | How |
|---|---|
| Join hotel Wi-Fi | UI at http://10.73.0.1:8080 (cable) or the Pi's MagicDNS name (tailnet) |
| Log in to a captive portal | Cable UI, then Open portal, log in, then End bypass |
| Switch to Tor or Direct | UI egress control, or ssh … sudo ph-egress {tor,direct,status} |
| Laptop keeps its own internet | make cable-debug; return with make cable-share |
| Measure throughput | make bench (run once per egress mode) |
Expect a browsing and email shield, not a streaming VPN. The Pi 3B shares one USB 2.0 bus between Ethernet and Wi-Fi (R3).
Blueprint · Threat model · Risks · Hardening · Security fixes · Tailnet policy · Specs and plans
Out of scope: targeted or nation-state attackers, a powered-on seizure, and active scanning of networks you're a guest on. The Panhandler observes passively and never touches anyone else's systems (THREAT-MODEL §2.5).
Contributing · Security policy · Code of conduct · Sponsors · Changelog · MIT License
