Version: v2.0.10

ModBridge is a modern, robust Modbus TCP proxy manager with an elegant web interface. It multiplexes and manages Modbus connections and provides detailed monitoring, logging, and security in a compact, easy-to-deploy package.

All detailed information about configuration (Web UI & headless) and usage can be found in the GitHub Wiki.

• ⚙️ Configuration (WebUI & Headless)
• 🔧 Features & API
• 🩺 Troubleshooting

A proxy is not a cable. ModBridge sits between your client (Home Assistant, SCADA, your own script) and the Modbus device and solves the problems that arise there:

Always active, no configuration needed:

• Transaction matching — towards the device, ModBridge assigns its own transaction IDs and discards responses that do not belong to the current request. Without this, a late response becomes the answer to the next request, and from then on every query fails.
• Time budget per request — when it expires, the client gets a clean Modbus exception instead of a late response nobody is waiting for anymore.

Configurable per proxy, off by default:

In the web interface:

• Device profiles — about 60 entries in seven categories (inverters, heat pumps, ventilation, meters, storage, wallboxes, general). They fill the form with values that fit the device class and change nothing else.
• Measure the device — probes gap, connections, and response time on the real device and suggests values instead of guessing. Read access only, 90 seconds at most, and nothing is applied until you click. For the duration, the proxy disconnects connected clients and accepts no new ones; they reconnect on their own afterwards.

Details in the Wiki: Configuration and Troubleshooting.

A sluggish device makes every client wait. The cache keeps exactly the registers that are actually queried warm, and the background poller refreshes them on its own schedule — the client gets its answer immediately, and the device is asked less often.

Both are off by default, because the trade-off should be a deliberate choice: a cached value is not the live value. Writes never go through the cache and invalidate the affected entries.

Instead of estimating values, ModBridge measures them on the device in front of you: the gap between requests is shortened step by step until the device starts discarding requests, and the last clean step gets a safety margin.

The install script handles everything: binary download, systemd service with autostart, and setup as a system-wide CLI command (modbridge).

curl -sSL https://raw.githubusercontent.com/Xerolux/modbridge/main/scripts/modbridge.sh | sudo bash -s install

# 1. Download the script
curl -sSL -o modbridge.sh https://raw.githubusercontent.com/Xerolux/modbridge/main/scripts/modbridge.sh
chmod +x modbridge.sh

# 2. Install (interactive, with menus)
sudo bash modbridge.sh install

# 3. Afterwards 'modbridge' is available system-wide
sudo modbridge status

After installation, ModBridge starts automatically on every system boot. All configured proxies are started automatically as well.

modbridge                          # Interactive TUI menu (whiptail)
modbridge install [--auto]         # Install (or reinstall)
modbridge update [--auto]          # Update
modbridge start                    # Start the service
modbridge stop                     # Stop the service
modbridge restart                  # Restart the service
modbridge status                   # Show status
modbridge logs [-f]                # Logs (live with -f)
modbridge health                   # Health check
modbridge config                   # Edit config (nano/vi)
modbridge backup                   # Back up config + DB
modbridge version                  # Show version
modbridge uninstall                # Remove completely

The script automatically checks for a newer version on every invocation. If one is available, it downloads the new version and restarts itself. No manual intervention required.

# Checks for script updates automatically, then installs
sudo modbridge install

# Skip the update check
NO_UPDATE=1 sudo modbridge install

ModBridge protects your data during updates and reinstalls:

Update process in detail:

1. Service is stopped
2. Config is automatically backed up to /opt/modbridge/backups/
3. Old binary is kept as modbridge.backup.TIMESTAMP
4. New binary is downloaded
5. Service is restarted
6. If startup fails → automatic rollback to the previous binary

Reinstall (e.g. after switching variants Full ↔ Headless):

sudo modbridge install --force
# Config and DB are preserved, only the binary is replaced

# Create a backup
sudo modbridge backup
# → /opt/modbridge/backups/config-20260401_120000.json
# → /opt/modbridge/backups/db-20260401_120000.db

# Edit the config
sudo modbridge config

# Restart the service after config changes
sudo modbridge restart

Alternative installation via Docker Compose:

version: '3.8'

services:
  modbridge:
    image: ghcr.io/xerolux/modbridge:latest
    container_name: modbridge
    restart: unless-stopped
    ports:
      - "8080:8080"
      - "5020-5030:5020-5030" # Port range for proxies
    volumes:
      - ./config.json:/app/config.json
      - ./data:/app/data

docker-compose up -d

After installation (Full variant), the web UI is available at:

http://<SERVER-IP>:8080

The admin password is generated automatically on first start and printed to the logs:

modbridge logs | grep -i password

Dashboard — the state of all proxies at a glance	Control — create, start, and group proxies
Proxy dialog — profile, gap, cache, protocol	Measurement report — every step traceable, applied on click

More views — devices, logs, dark theme, and mobile format — in the Wiki.

Want to get your hands dirty or compile the project from source? See the Wiki for make commands, frontend builds, and more.

Local build:

make build
./modbridge

Contributions are welcome! Please read CONTRIBUTING.md for details.

MIT License — see LICENSE for details.

• Xerolux - GitHub

Version: 2.0.10 | Status: Beta | Last updated: August 2026