Skip to content
Family Filter

A parent's Mac

Building Family Filter for Mac

Section titled “Building Family Filter for Mac”
Terminal window
cd viewer
npm install         # first time only
npm run app         # builds release/Family Filter.app

Building needs Bun (brew install oven-sh/bun/bun) and Xcode’s command-line tools. The app is self-contained: copy it to /Applications on any Apple silicon Mac running macOS 12 or later. It’s signed ad hoc, so the first time it’s opened on another Mac, right-click ▸ Open.

For development, npm start runs the same page in a browser at http://localhost:5173.

On another parent’s Mac

Section titled “On another parent’s Mac”

Two scripts set Family Filter for Mac up on another parent’s Mac. It reads history and runs the filter over Tailscale.

  1. On the Mac with the repo: viewer/scripts/parent-mac-bundle.sh "<their Mac>" makes a folder in filter/private/ holding a copy of the app, a web filter token and a history read token for that Mac, and setup.sh.
  2. AirDrop the folder to that Mac. It holds tokens: never iCloud, Messages or email.
  3. There, with Tailscale installed and connected: bash ~/Downloads/parent-mac-<name>/setup.sh. It checks the Mac, checks that the filter and the history service answer over Tailscale and accept the tokens, installs the app, saves the addresses and tokens in its settings, deletes the token files and opens the app.
  4. Delete the folder on both Macs.

Tokens go in a file, never on screen, the clipboard or a command line.

Family Filter for Mac’s Settings on a parent’s Mac: history folder, Cloudflare categories, web blocking connected, and Connect a phone

History from the Firewalla

Section titled “History from the Firewalla”

Family Filter for Mac can read history from the history service instead of the shared iCloud folder:

  • A local copy. It copies the Firewalla’s files into its own folder (only new bytes each time, checked by checksum) and reads that. It does this every 5 minutes, and when the page loads if the copy is over a minute old. When the Firewalla can’t be reached, it shows the copy as it stands.
  • Archive mode, on one Mac. That Mac’s copy is never trimmed, and it tells the Firewalla what it holds, so the Firewalla can drop files older than its 90-day window. On other Macs, the copy follows the Firewalla’s window.
  • Phones are connected from the archive Mac: Settings ▸ Phones ▸ Connect a phone…. Only the archive Mac’s token can make read tokens for phones.

Source: viewer/README.md