ProxyBridge Deployment and Usage Guide

1. Prerequisites

Platform-Specific Requirements

Windows:

Windows 10 or later (64-bit)
Administrator privileges for installation and operation
Visual Studio 2022 or later (for building from source)

macOS:

macOS 13.0 (Ventura) or later
Apple Silicon (ARM) or Intel processor
Xcode 15.0 or later (for building from source)

Linux:

Linux kernel with NFQUEUE support
Root privileges for installation and operation
GCC, Make, and standard build tools
GTK3 development libraries (for GUI build)
Not compatible with WSL1/WSL2

Common Requirements

Git (for cloning repository)
Network access to download dependencies
Proxy server (SOCKS5 or HTTP) for routing traffic

2. Installation

Option A: Pre-built Binaries (Recommended)

Download from official sources only:
- GitHub Releases: https://github.com/InterceptSuite/ProxyBridge/releases
- Official Website: https://interceptsuite.com/download/proxybridge

Platform-specific installation:

Windows:

Download the .msi installer
Run installer with Administrator privileges
Follow installation wizard

macOS:

Download the .pkg installer
Double-click to install
Grant necessary permissions when prompted

Linux:

# Quick install script
curl -Lo deploy.sh https://raw.githubusercontent.com/InterceptSuite/ProxyBridge/refs/heads/master/Linux/deploy.sh
sudo bash deploy.sh

# Or download TAR.GZ archive and extract
tar -xzf proxybridge-linux-*.tar.gz
sudo ./install.sh

Option B: Build from Source

Clone the repository:

git clone https://github.com/InterceptSuite/ProxyBridge.git
cd ProxyBridge

Platform-specific build instructions:

Windows:

# Open solution in Visual Studio
# Build the solution (Release configuration)
# Find binaries in Windows/bin/Release/

macOS:

cd MacOS
xcodebuild -project ProxyBridge.xcodeproj -configuration Release
# Built app in build/Release/

Linux:

cd Linux
make
sudo make install

3. Configuration

Proxy Settings Configuration

ProxyBridge can be configured via GUI or CLI:

GUI Configuration:

Launch ProxyBridge
Navigate to Proxy Settings
Add your SOCKS5 or HTTP proxy:
- Address: Proxy server IP/hostname
- Port: Proxy server port
- Authentication: Username/password if required

CLI Configuration (Linux/Windows):

# Set proxy via command line
proxybridge-cli --proxy socks5://proxy.example.com:1080

# Or use configuration file
proxybridge-cli --config /path/to/config.json

Rule Configuration

Rules control how traffic is routed. Create rules via GUI or JSON configuration:

Example rule configuration file (rules.json):

{
  "rules": [
    {
      "name": "Route Chrome through proxy",
      "process": "chrome.exe",
      "action": "proxy",
      "proxy": "socks5://127.0.0.1:1080",
      "protocol": "tcp",
      "enabled": true
    },
    {
      "name": "Block specific app",
      "process": "blocked-app.exe",
      "action": "block",
      "enabled": true
    },
    {
      "name": "Allow direct connection",
      "process": "trusted-app.exe",
      "action": "direct",
      "enabled": true
    }
  ]
}

Import/Export Rules:

Use GUI: Settings → Rules → Import/Export
Use CLI: proxybridge-cli --import-rules rules.json

Environment Variables

Linux-specific:

# Set library path if needed
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

# Enable debug logging
export PROXYBRIDGE_DEBUG=1

4. Build & Run

Development Build

Windows:

# Clone and build
git clone https://github.com/InterceptSuite/ProxyBridge.git
cd ProxyBridge/Windows
# Open ProxyBridge.sln in Visual Studio
# Build Debug configuration

macOS:

git clone https://github.com/InterceptSuite/ProxyBridge.git
cd ProxyBridge/MacOS
xcodebuild -project ProxyBridge.xcodeproj -configuration Debug
open build/Debug/ProxyBridge.app

Linux:

git clone https://github.com/InterceptSuite/ProxyBridge.git
cd ProxyBridge/Linux
make debug
sudo ./proxybridge --debug

Production Run

Windows:

Launch ProxyBridge GUI from Start Menu
Or run CLI: ProxyBridge.exe --start

macOS:

Open ProxyBridge from Applications folder
Enable network extension when prompted
Grant necessary permissions

Linux:

# Start with GUI
sudo proxybridge-gui

# Or CLI only
sudo proxybridge-cli --start --config /etc/proxybridge/rules.json

# Run as service
sudo systemctl start proxybridge

5. Deployment

Deployment Platforms

For end-users:

Windows: MSI installer deployed via software distribution systems
macOS: PKG installer distributed via direct download
Linux: Package repositories (APT/YUM) or TAR.GZ archives

For enterprise deployment:

Windows (Group Policy/SCCM):

Distribute MSI installer
Configure rules via centralized configuration file
Deploy via Group Policy or SCCM

macOS (MDM):

Package as .pkg with pre-configured rules
Deploy via MDM solution (Jamf, Munki)
Configure network extension profiles

Linux (Configuration Management):

# Ansible playbook example
- name: Deploy ProxyBridge
  hosts: all
  tasks:
    - name: Install dependencies
      apt:
        name: ["build-essential", "libgtk-3-dev"]
        state: present
    
    - name: Download and install ProxyBridge
      get_url:
        url: "https://github.com/InterceptSuite/ProxyBridge/releases/latest/download/proxybridge-linux.tar.gz"
        dest: /tmp/proxybridge.tar.gz
    - unarchive:
        src: /tmp/proxybridge.tar.gz
        dest: /opt/
        remote_src: yes
    
    - name: Deploy configuration
      copy:
        src: files/proxybridge-rules.json
        dest: /etc/proxybridge/rules.json
    
    - name: Start service
      systemd:
        name: proxybridge
        state: started
        enabled: yes

Docker Deployment (Linux only)

FROM ubuntu:22.04

# Install dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libnetfilter-queue-dev \
    && rm -rf /var/lib/apt/lists/*

# Copy ProxyBridge
COPY proxybridge /usr/local/bin/
COPY rules.json /etc/proxybridge/

# Run with necessary capabilities
CMD ["proxybridge", "--config", "/etc/proxybridge/rules.json"]

Build and run:

docker build -t proxybridge .
docker run --cap-add=NET_ADMIN --cap-add=NET_RAW -it proxybridge

6. Troubleshooting

Common Issues and Solutions

Issue: "Permission denied" errors

Solution: Run with administrator/root privileges
Windows: Run as Administrator
Linux/macOS: Use sudo

Issue: Traffic not being routed

Solution:
1. Verify proxy server is running and accessible
2. Check rule configuration matches process names exactly
3. Ensure ProxyBridge service is running
4. On macOS: Verify network extension is enabled in System Settings

Issue: Application crashes or freezes

Solution:
1. Update to latest version
2. Check for conflicting firewall/security software
3. Disable and re-enable ProxyBridge
4. Check logs: proxybridge --log-level debug

Issue: Proxy loops (ProxyBridge routing its own traffic)

Solution: Add exclusion rule for ProxyBridge processes

{
  "process": "proxybridge*",
  "action": "direct",
  "enabled": true
}

Issue: UDP traffic not working

Solution:
1. Ensure proxy server supports UDP (SOCKS5 only)
2. Verify UDP rule is enabled
3. Check firewall allows UDP traffic

Issue: Performance problems

Solution:
1. Reduce number of active rules
2. Use IP/port specific rules instead of wildcards
3. Consider using direct connection for high-bandwidth applications

Platform-specific troubleshooting:

Windows:

Ensure WinDivert driver is properly installed
Check Windows Firewall isn't blocking ProxyBridge
Verify no conflicting VPN/proxy software

macOS:

Check System Settings → Privacy & Security → Network Extensions
Verify ProxyBridge has necessary permissions
Check Console.app for detailed logs

Linux:

Verify kernel has NFQUEUE support: modprobe nfnetlink_queue
Check iptables/nftables isn't conflicting
Verify SELinux/AppArmor isn't blocking

Getting Help

Check existing issues: https://github.com/InterceptSuite/ProxyBridge/issues
Review platform-specific documentation:
- Windows: /Windows/README.md
- macOS: /MacOS/README.md
- Linux: /Linux/README.md
Enable debug logging and include logs when reporting issues

Security Note

Only download from official sources
ProxyBridge doesn't communicate with external servers except GitHub API for update checks
Review and customize rules for your security requirements
Regularly update to latest version for security fixes

How to Deploy & Use ProxyBridge

ProxyBridge Deployment and Usage Guide

1. Prerequisites

Platform-Specific Requirements

Common Requirements

2. Installation

Option A: Pre-built Binaries (Recommended)

Option B: Build from Source

3. Configuration

Proxy Settings Configuration

Rule Configuration

Environment Variables

4. Build & Run

Development Build

Production Run

5. Deployment

Deployment Platforms

Docker Deployment (Linux only)

6. Troubleshooting

Common Issues and Solutions

Getting Help

Security Note