Getting Started
Install on Linux
Install ProxyBridge on Linux with the one-line script or the release tarball: requirements (kernel 5.11+, BTF, cgroup v2), what gets installed, verification, updating and uninstalling.
Installing ProxyBridge on Linux
ProxyBridge releases are published on the ProxyBridge GitHub releases page and on the download page.
Requirements
| Needed | Details |
|---|---|
| Kernel 5.11 or newer | ProxyBridge uses eBPF hooks that older kernels do not have |
| BTF | The kernel must expose its type information: /sys/kernel/btf/vmlinux must exist |
| cgroup v2 | The unified hierarchy must be mounted at /sys/fs/cgroup |
| Root | Only to install. Loading eBPF programs needs root, so the installer sets up the ProxyBridge service, which runs as root. The window runs as you, with no sudo |
| GTK 3 | Only for the window (ProxyBridgeGUI). The command line program needs nothing besides the C library. The installer installs GTK 3 if it is missing |
| glibc 2.34 or newer | Ubuntu 22.04, Debian 12 and RHEL 9 and newer have it |
| 64-bit Intel/AMD or ARM64 | There is a release for x86-64 (x64) and one for ARM64 (aarch64). Download the one that matches uname -m (x86_64 or aarch64) |
Check your system with three commands:
uname -r # 5.11 or higher
ls /sys/kernel/btf/vmlinux # must exist
stat -fc %T /sys/fs/cgroup # must print: cgroup2fs
Current Ubuntu, Debian, Fedora, Arch, openSUSE and RHEL releases pass all three. WSL1 and WSL2 do not (their kernels have no BTF or cgroup BPF); use a real machine, a virtual machine or a cloud instance, or the Windows version on the Windows side. Containers are not redirected; see Troubleshooting.
Option 1: one-line install
curl -Lo deploy.sh https://raw.githubusercontent.com/InterceptSuite/ProxyBridge/refs/heads/master/Linux/deploy.sh && sudo bash deploy.sh
The script downloads the latest release into a private temporary folder, checks its SHA-256 against the .sha256 file of the release (it stops if they differ, or if the release has none), refuses an archive with unsafe paths, and then runs the archive's own setup.sh, the same installer as in option 2. It needs curl, tar and sha256sum; jq is optional.
Supported distributions: Debian, Ubuntu, Mint, Pop!_OS, Kali and relatives; Fedora; RHEL, CentOS, Rocky and AlmaLinux; Arch, Manjaro and EndeavourOS; openSUSE and SLES; Void.
Option 2: the release package
Download ProxyBridge-Linux-x64-vX.X.X.tar.gz (or ProxyBridge-Linux-arm64-vX.X.X.tar.gz on ARM64) and its .sha256 file from the releases page, then:
sha256sum -c ProxyBridge-Linux-x64-vX.X.X.tar.gz.sha256 # verify (see below)
tar -xzf ProxyBridge-Linux-x64-vX.X.X.tar.gz
cd ProxyBridge-Linux-x64-vX.X.X
sudo ./setup.sh
Verify the download
Every release has a .sha256 file next to the archive. With both in the same folder, sha256sum -c prints OK when the archive is exactly what was published. To compare by hand, run sha256sum ProxyBridge-Linux-x64-vX.X.X.tar.gz and compare the output with the checksum on the releases page.
What gets installed
| File | Purpose |
|---|---|
/usr/local/bin/ProxyBridge |
The command line program. ProxyBridge --daemon is also the service |
/usr/local/bin/ProxyBridgeGUI |
The window (if the package includes it). Needs no root |
/usr/local/lib/libproxybridge.so |
The engine library |
/etc/systemd/system/proxybridge.service |
The service: the root part of ProxyBridge. See The service |
/usr/share/applications/proxybridge.desktop and icons under /usr/share/icons/hicolor/ |
The launcher entry: ProxyBridge appears in your application menu with its logo |
/etc/proxybridge/ |
Created when you first run it: your profiles and settings (root only) |
The installer does not touch your proxy settings or the firewall. It adds one system service (below) and one group. The command line program and the library are self-contained, so there is nothing else to install for them.
The service
Loading the eBPF programs needs root, but the window should not. ProxyBridge is therefore split in two, like the Windows app:
proxybridge.serviceruns as root in the background. It owns the engine, your profiles and the settings.ProxyBridgeGUIis the window. It runs as you and sends everything to the service through a local socket (/run/proxybridge/ctl.sock): adding a proxy, editing a rule, switching profile, starting the engine, reading the logs. Its file choosers, browser and clipboard are your own.
The installer creates the service, enables it for the next boot and starts it. It also creates the group proxybridge and adds the user who ran sudo to it. Only root and the members of that group can use the service; everybody else is refused. A new member can use it at once, without logging in again:
sudo usermod -aG proxybridge alice
Being in the group lets a person route, block and read the proxy passwords of every user's traffic, so add only people you would trust with sudo for ProxyBridge. Remove someone with sudo gpasswd -d alice proxybridge (their open window is refused within seconds). To keep the installer from adding you, run it as sudo env PB_NO_GROUP_USER=1 ./setup.sh.
Check the service:
systemctl status proxybridge
journalctl -u proxybridge -f
First start
ProxyBridgeGUI # the window: no sudo
sudo ProxyBridge --help # the command line
Or start ProxyBridge from your application menu. On the first start ProxyBridge creates a profile called Default in /etc/proxybridge/profiles/ and opens it. Continue with the Linux quick start.
If the window says the service is not running, start it with sudo systemctl enable --now proxybridge. If it says you are not allowed, you are not in the group: sudo usermod -aG proxybridge $USER. More in Troubleshooting.
Without systemd, or if you prefer not to install the service, a window started with sudo ProxyBridgeGUI runs the engine inside itself, exactly as before.
Updating
Run the one-line install again, or download the new tarball and run sudo ./setup.sh again. The installer replaces the programs and keeps your profiles in /etc/proxybridge. The installer restarts the service with the new version, and an open window reconnects by itself and sends its configuration again. (Routing is briefly off while the service restarts: connections go direct for that moment.)
To see whether a newer version exists without installing anything:
ProxyBridge --update
The window has Help > Check for Updates... and an optional check on start-up. See Settings.
Uninstalling
From the extracted release folder:
sudo ./setup.sh --uninstall # removes programs, the launcher entry and the service; keeps profiles
sudo ./setup.sh --uninstall --purge # also deletes /etc/proxybridge (profiles and settings) and the group
There is nothing else to clean up. ProxyBridge attaches its programs to the kernel in a way that the kernel removes when ProxyBridge ends, and it adds no firewall rules. To confirm, sudo bpftool cgroup tree /sys/fs/cgroup should list nothing named pb_.
Building from source
Install gcc, make, clang, bpftool, curl, bzip2, pkg-config and (for the window) the GTK 3 development package, then:
git clone https://github.com/InterceptSuite/ProxyBridge.git
cd ProxyBridge/Linux
./build.sh # results in Linux/output/
sudo ./setup.sh
The first build downloads pinned, checksum-verified sources of the small libraries it needs and links them in statically. Details are in the Linux README.
Next steps
- Linux quick start: route your first program in five minutes
- Proxy servers and Proxy rules
- Troubleshooting and limits if ProxyBridge does not start
