Privaxy

Next generation tracker and advertisement blocker

A fork of privaxy

This reverts it back to v0.3.1, adding more features, dependency updates, an improved UI, and server-friendly configuration options.

Table of Contents

• About
  • Compared to DNS-based blockers (Pi-hole, AdGuard Home)
• Features
• Installation
  • Debian/Ubuntu
  • RHEL/Fedora/Rocky
  • MIPS
  • Docker
  • From source
  • Docker Compose
• Setup
  • First-run web UI
  • Install the root CA on your client devices
  • Point clients at the proxy
  • Cert-pinned hosts (exclusions)
• Screenshots
• Acknowledgements

About

Privaxy is a MITM HTTP(s) proxy that sits in between HTTP(s) talking applications, such as a web browser and HTTP servers, such as those serving websites.

This app sees all your plaintext, run it on hardware you trust. DO NOT FACE THIS PUBLICLY

By establishing a two-way tunnel between both ends, Privaxy is able to block network requests based on URL patterns and to inject scripts as well as styles into HTML documents.

Operating at a lower level, Privaxy is both more efficient as well as more streamlined than browser add-on-based blockers. A single instance of Privaxy on a small virtual machine, server or even, on the same computer as the traffic is originating from, can filter thousands of requests per second while requiring a very small amount of memory.

Privaxy is not limited by the browser’s APIs and can operate with any HTTP traffic, not only the traffic flowing from web browsers.

Compared to DNS-based blockers (Pi-hole, AdGuard Home)

DNS sinkholes can only answer "is this whole domain allowed or not?". Because Privaxy works at the HTTP layer instead of the DNS layer, it can do things a DNS blocker fundamentally cannot:

• Block by full URL, not just domain — individual paths and query strings can be blocked, so first-party and same-domain ads/trackers (served off a domain you otherwise need) are reachable targets.
• Cosmetic filtering — hide page elements and inject uBlock Origin-style scriptlets, instead of leaving broken gaps where a blocked domain used to be.
• Intercept DNS-over-HTTPS (DoH) — DoH is the mechanism that routinely bypasses DNS-level blockers; Privaxy sees it as HTTPS and can block or redirect it.

The trade-off is that Privaxy is a MITM proxy: clients must trust its root CA and route traffic through it, and it sees plaintext. It complements a DNS blocker more than it strictly replaces one.

Upon initial setup, a lot of your websites/apps will break due to cert pinning. This is a one time occurrence, add websites/endpoints to exlcusions as broken websites are encountered

Features

• Suppport for Adblock Plus filters, such as easylist.
• Web graphical user interface with a statistics display as well as a live request explorer.
• Support for uBlock origin's js syntax.
• Support for uBlock origin's redirect syntax.
• Support for uBlock origin's scriptlets.
• Browser and HTTP client agnostic.
• Support for custom filters.
• Support for excluding hosts from the MITM pipeline.
• DNS-over-HTTPS (DoH) interception — block (default) clients' DoH so they fall back to the system resolver, or redirect queries to a resolver you configure. Closes the DoH bypass that defeats DNS-level blockers.
• Support for protocol upgrades, such as with websockets.
• Automatic filter lists updates.
• Very low resource usage.
  • Around 50MB of memory with approximately 320 000 filters enabled.
  • Able to filter thousands of requests per second on a small machine.
• PAC generation for easy client setup
• filterlists.com integration
• Ability to add custom filters

Installation

You can either utilize the docker image, binary, or the deb avaiable in releases.

Debian/Ubuntu

Download and install the .deb from the release

RHEL/Fedora/Rocky

Download and install the .rpm from the release

MIPS

Download and install the deb/rpm/binary with mips in the name

Docker

docker run -d --name privaxy --restart unless-stopped \
  -p 8100:8100 -p 8200:8200 \
  -v /path/to/conf:/conf \
  ghcr.io/joshrmcdaniel/privaxy:<tag>

• dev is mapped to the develop branch
• latest is mapped to the main branch
• <version> maps to official releases
• <sha> maps to a specific commit

From source

# 1. Frontend 
cd web_frontend
npm i
trunk build --release

# 2. Backend
cd ..
cargo build --release

The frontend must be built before the backend — the server embeds web_frontend/dist/ via include_dir! and won't compile without it.

Build requirements:

• Rust 1.87+
• Node.js
• Trunk

Docker Compose

services:
  privaxy:
    image: ghcr.io/joshrmcdaniel/privaxy
    ports:
      - "8100:8100"
      - "8200:8200"
    volumes:
      - path/to/conf:/conf
    restart: unless-stopped

Tags:

• dev is mapped to the develop branch
• latest is mapped to the main branch
• <version> maps to official releases
• <sha> maps to a specific commit

Setup

1. First-run web UI

Open http://<host>:8200 in a browser. On first launch, the web UI walks you through:

1. Creating a username and password for the web UI. The same account is used for every subsequent login. Programmatic clients can also authenticate via the X-Api-Key header. The key is shown in Settings → Account.
2. Selecting which filter lists to enable (you can also browse filterlists.com from Settings → Filters).

On first run, privaxy auto-generates a root CA + private key and writes them to its config directory. If you'd rather use your own CA, replace the values under [ca] in the config file (or upload via Settings → General) and restart.

2. Install the root CA on your client devices

Privaxy is a MITM proxy: clients must trust its root CA, otherwise every HTTPS site will show a certificate error. Download the CA from Settings → General, then install it as a trusted root on each device:

• Linux (Debian/Ubuntu, system-wide): copy the PEM to /usr/local/share/ca-certificates/privaxy.crt and run sudo update-ca-certificates. Firefox uses its own store — import via Preferences → Privacy & Security → View Certificates → Authorities.
• macOS: open the file in Keychain Access → System keychain → mark Always Trust under the certificate's Trust section.
• Windows: double-click the .crt → Install Certificate → Local Machine → Place all certificates in the following store → Trusted Root Certification Authorities.
• iOS: transfer the file to the device → Settings → General → VPN & Device Management → install the profile → Settings → General → About → Certificate Trust Settings → enable full trust for the Privaxy CA.
• Android: Settings → Security → Encryption & credentials → Install a certificate → CA certificate. Note: most apps on modern Android ignore user-installed CAs unless they opt in via network security config, so privaxy is most useful for browser traffic on mobile.

3. Point clients at the proxy

Two options:

• Manual: configure your browser/OS to use HTTP proxy <host>:8100 for both HTTP and HTTPS.
• PAC (recommended): point the client at http://<host>:8200/proxy.pac. PAC is served unauthenticated so any client on the network can fetch it. Configure direct-bypass rules (internal CIDRs, FQDNs) under Settings → PAC.

4. Cert-pinned hosts (exclusions)

Some sites use certificate pinning or strict TLS and will break if their traffic is intercepted. Privaxy handles this two ways:

• An always-on safety net for Apple's published service hosts (apple.com, icloud.com, etc., per HT210060). This is hardcoded and not user-editable.
• A list of commonly cert-pinned hosts that is pre-populated into your editable exclusions on first config creation. Settings → Exclusions shows the list; the Reset to defaults button re-applies the default list. Source

Excluded hosts are still CONNECT-tunneled through the proxy, they're just not decrypted. Filter rules do not apply to their traffic.

If you find a site that breaks under MITM, add its hostname (wildcards like *.example.com are supported) to Settings → Exclusions and click Save. If it's something common, please open an issue so it can be added to the recommended list.

Recovering access: if you lose the web-UI password, delete the password_hash value from the config file and restart. The web UI will force the setup flow again.

Screenshots

Acknowledgements

Privaxy was originally created by Pierre Barre (Barre/privaxy). This fork stands on top of that work, full credit for the original design and implementation goes to him.

Thanks also to:

• uBlock Origin and Raymond Hill. Privaxy bundles uBlock Origin's scriptlets and web-accessible resources for filter compatibility.
• filterlists.com — for the filter-list directory that powers in-app filter discovery.