Isaac Browser

Isaac Browser — build notes

A real macOS web browser, written from scratch in Python. PyObjC + WKWebView. Not a shell around Chrome and not a mockup — it creates its own NSWindow, its own WKWebView, and gets its own WebKit renderer process (WebContent / GPU / Networking XPC children), exactly like Safari does.

The goal was a browser that is private by construction rather than by settings: nothing to forget to enable, nothing left behind to clean up.

---

Privacy architecture

• Ephemeral data store. The WKWebView is created with a non-persistent

WKWebsiteDataStore, so history, cookies, localStorage and the HTTP cache exist only in RAM. Nothing is ever written to ~/Library/WebKit or the disk.

• Auto-burn on exit. On quit, all website data types are removed through the

data store API — a clean teardown rather than just letting the process die.

• Tracker filtering. In-page requests to a known tracker/ad domain list are

refused before they go out.

• Anti-fingerprinting. User-Agent, screen dimensions and timezone are spoofed

so the browser does not present a unique, trackable signature.

• Leak surfaces closed. WebRTC and geolocation are blocked, referrers are

stripped, and navigation is HTTPS-only.

• Stealth mode + New Identity. One click discards the current session's

in-memory state and regenerates the fingerprint.

---

The proxy: per-app, never system-wide

The app ships an ephemeral CONNECT proxy on 127.0.0.1:8557 plus a DoH resolver, and it is a deliberate design rule that it routes only the browser's own traffic and never touches the macOS system proxy.

An earlier version did the convenient thing and called:

networksetup -setwebproxy <service> 127.0.0.1 8557
networksetup -setsecurewebproxy <service> 127.0.0.1 8557

Those calls are system-wide. Every other app — Chrome included — got silently repointed at the browser's local proxy, and on quit the teardown ran -setwebproxystate off, which disabled the machine's proxy entirely, including a VPN's. From the user's side: Chrome appeared broken for no visible reason, and it was this browser doing it.

All system-proxy mutation is now deleted; the outbound path uses a per-app opener that never inherits the OS proxy configuration. The proxy toggle affects this app and nothing else.

---

Packaging: four things that stop a Python app opening on macOS 26

1. macOS 26 rejects a shell script as CFBundleExecutable. A bash launcher

makes the bundle look valid and then silently does nothing on double-click. The fix is a compiled Mach-O universal launcher (arm64 + x86_64) that satisfies the loader and then execs the Python framework binary.

2. A fatal port bind killed the app on every launch. The proxy called

bind() with no guard, so a stale process holding 8557 raised OSError: [Errno 48] and took the whole app down before a window appeared. Both the proxy and the local API server are now non-fatal on a busy port, and an already-running check runs first to stop duplicate instances.

3. Editing an app after signing invalidates it. Changing Info.plist or the

icon leaves a stale _CodeSignature and Gatekeeper reports "plist or signature have been modified". Re-sign ad-hoc after every change.

4. Builds need no admin. Everything is assembled into ~/Applications, which

Launchpad and Spotlight both index — no sudo, no password prompt.

Search without an API key

HTML-scraping DuckDuckGo and Google returns 429s and JS challenges. The browser instead queries the DuckDuckGo Instant Answer API and the MediaWiki search API, with a Bing HTML pass as a last resort — keyless, reliable, and not bot-blocked.

Verification

• Window opens on double-click; WebContent/GPU/Networking XPC children

confirm a page genuinely rendered.

• Search returns real results (10–12 per query).
• networksetup -getwebproxy stays Enabled: No with the app running and when

the in-app proxy is toggled on.

• The app, its launcher and the bundle all pass codesign --verify.