Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on macOS
Block ads system-wide on Android using local VPN-based DNS filtering. No root needed. No data collection.
Saved setup from 2 h ago
Will it work on macOS?
Then run bash setup.sh. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: xcode-select --install
git clone https://github.com/pass-with-high-score/blockads-android.git cd blockads-android
Ruby, JDK
brew install rbenv ruby-build rbenv install --list brew install openjdk@21
bundle install ./gradlew build -x test
./gradlew run
[!TIP] Historical versions of the Go binary (
tunnel.aar) were committed in the past before being moved to GitHub Releases. To avoid downloading ~1.2GB of old binaries, use blobless clone (--filter=blob:limit=1m) to download only ~20MB.
Clone the repository:
git clone --filter=blob:limit=1m https://github.com/pass-with-high-score/blockads-android.git
cd blockads-android
(Or for a shallow clone: git clone --depth=1 https://github.com/pass-with-high-score/blockads-android.git)
(Optional) Build the Go tunnel AAR/JAR from source (with Android 15 16KB page size support):
./scripts/build_tunnel.sh
# Or
./gradlew -Ptunnel.source=local buildGoTunnel
Note: This is completely optional. Gradle automatically resolves a prebuilt, checksum-pinned tunnel.aar from GitHub Releases by default. You do not need Go or NDK unless you are modifying Go code in tunnel/. See docs/TUNNEL.md.
Open the project in Android Studio
Sync Gradle and run the app on a device or emulator
Build from command line:
./gradlew assembleDebug
./gradlew bundleRelease # requires signing key
On macOS: 1 got it running, 0 got stuck.
GitManual AI Agent reads the 8 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.