Home/Docs/Getting Started/Install on Linux

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.service runs as root in the background. It owns the engine, your profiles and the settings.
  • ProxyBridgeGUI is 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