How g3ntrix/shade works
Shade is a guided macOS client for a local traffic-tunneling proxy. Users configure a profile in the setup wizard, start the core from the dashboard or menu bar, and optionally enable macOS system-proxy routing or full-tunnel mode. The Python proxy handles HTTP/SOCKS traffic, optional HTTPS interception and ad blocking, then relays requests through Apps Script; the app also exposes profile sharing, diagnostics, speed checks, and optional exit relays. Some feature links are based on README documentation because their implementations were not sampled.
Main entry points: AppState.swift App state · proxy_server.py Local proxy · DashboardView.swift Dashboard · domain_fronter.py Domain-front relay
Components 24
macOS client
- App navigation
macos-app/Sources/Shade/ContentView.swift - Guided setup
macos-app/Sources/Shade/Views/SetupView.swift - Dashboard
macos-app/Sources/Shade/Views/DashboardView.swift - Menu controls
macos-app/Sources/Shade/Views/MenuBarView.swift - Speed check
macos-app/Sources/Shade/Models/AppState.swift
State and services
- App settings
macos-app/Sources/Shade/Models/AppSettings.swift - App state
macos-app/Sources/Shade/Models/AppState.swift - Config storage
macos-app/Sources/Shade/Services/ConfigStore.swift - Core supervisor
macos-app/Sources/Shade/Services/CoreManager.swift - System proxy
macos-app/Sources/Shade/Services/SystemProxy.swift - Certificate trust
macos-app/Sources/Shade/Services/CertManager.swift - Network info
macos-app/Sources/Shade/Services/NetworkInfo.swift
Proxy runtime
- Core entry point
main.py - Local proxy
src/proxy_server.py - HTTPS interception
src/mitm.py - Ad blocking
src/adblock.py - SOCKS relay
src/udp_socks_relay.py
Relay and integrations
- Domain-front relay
src/domain_fronter.py - HTTP/2 transport
src/h2_transport.py - Relay codec
src/codec.py - Exit relay option
macos-app/Sources/Shade/Services/ExitRelayPackager.swift
Other components
- Mac user
- Apps Script
- Phone or tablet
Connections 25
- Mac user → App navigation: uses
README.md - App navigation → Guided setup: routes to
macos-app/Sources/Shade/ContentView.swift - App navigation → Dashboard: routes to
macos-app/Sources/Shade/ContentView.swift - Guided setup → App state: configures
macos-app/Sources/Shade/Views/SetupView.swift - Dashboard → App state: controls
macos-app/Sources/Shade/Views/DashboardView.swift - Menu controls → App state: controls
macos-app/Sources/Shade/Views/MenuBarView.swift - App state → App settings: reads
macos-app/Sources/Shade/Models/AppState.swift - App state → Config storage: writes config
macos-app/Sources/Shade/Models/AppState.swift - App state → Core supervisor: starts core
macos-app/Sources/Shade/Models/AppState.swift - App state → Certificate trust: installs trust
macos-app/Sources/Shade/Models/AppState.swift - App state → System proxy: enables proxy
macos-app/Sources/Shade/Models/AppState.swift - App state → Network info: queries
macos-app/Sources/Shade/Views/DashboardView.swift - Core supervisor → Core entry point: launches
macos-app/Sources/Shade/Services/CoreManager.swift - Core entry point → Local proxy: starts
main.py - Local proxy → Domain-front relay: relays requests
src/proxy_server.py - Local proxy → HTTPS interception: uses
src/proxy_server.py - Local proxy → Ad blocking: filters domains
src/proxy_server.py - Local proxy → SOCKS relay: dispatches SOCKS
src/proxy_server.py - Domain-front relay → HTTP/2 transport: sends requests
src/domain_fronter.py - Domain-front relay → Relay codec: encodes payloads
src/domain_fronter.py - HTTP/2 transport → Relay codec: uses
src/h2_transport.py - Domain-front relay → Apps Script: tunnels through
README.md - Phone or tablet → Local proxy: connects by SOCKS
README.md - Dashboard → Exit relay option: offers relay setup
macos-app/Sources/Shade/Views/DashboardView.swift - Dashboard → Speed check: runs test
macos-app/Sources/Shade/Views/DashboardView.swift