Thanks for looking. perbrowser is deliberately small: one POSIX shell script, no dependencies beyond the pinned wireproxy binary. Contributions that keep it that way are very welcome.
brew install shellcheck bats-core
shellcheck perbrowser # must be clean
bats tests/ # must pass. Runs offline against a fake $HOMEThe tests stub launchctl, curl, lsof, and sleep, so they never touch
your real agents or the network. If you add behavior, add a test.
- POSIX sh only (
set -eu, no bashisms). shellcheck must stay clean. - One file. If a feature can't fit tastefully in the single script, it probably belongs in a fork or a v2 discussion first.
- Security-sensitive defaults are not negotiable: confs stay
600, wireproxy stays pinned + checksum-verified, health checks test real traffic (not logs), leak-prevention flags stay on. - macOS behavior is verified on Apple Silicon; Intel is best-effort. Say in your PR which you tested on.
Roughly in order of demand:
- Firefox support. Different mechanism entirely: a dedicated profile
with
user.jsprefs (network.proxy.*,media.peerconnection.*) instead of command-line flags. Needs thought about tamper-resistance: prefs can be changed in-app, flags can't. - Linux support. Same design, systemd user units instead of launchd,
.desktopentries instead of.appbundles. The script is structured so platform bits (plist/app generation,launchctl) are isolated functions. - More Chromium-family browsers (Vivaldi, Arc, Opera): mostly a matter of adding the app name mapping and testing the flags actually apply.
doctorchecks: more failure modes from the wild, each with a safe auto-fix or a printed remedy.
perbrowser doctor <name> output plus the tail of
~/.config/perbrowser/<name>/wireproxy.log covers most of what's needed.
Never paste your wg.conf or anything containing PrivateKey.