Skip to content

README.md

Latest commit

 

History

History
123 lines (85 loc) · 3.33 KB

README.md

File metadata and controls

123 lines (85 loc) · 3.33 KB
Raw

Headless Proton Bridge Installer

Interactive, safety-focused installer for building and running Proton Mail Bridge without a GUI on a systemd-based Linux server.

The project targets Debian/Ubuntu and Fedora/RHEL-family systems on x86_64. It builds Proton Mail Bridge from Proton's official source repository with the upstream build-nogui target.

Warning

This is an independent community project. Proton designs Bridge for local connections. Direct LAN exposure is unsupported and disabled by default.

Safety model

  • ./install.sh performs a read-only inspection by default.
  • Installation requires sudo ./install.sh --apply and an exact INSTALL confirmation.
  • Localhost and private-tunnel modes preserve the upstream 127.0.0.1 binding.
  • Direct LAN mode requires EXPOSE-LAN, a private bind address, an allowlisted private CIDR, and active firewalld.
  • Proton credentials and 2FA codes are entered only in Proton Bridge's own CLI.
  • The service uses a locked system account, a dedicated GPG key, a pass store, and systemd hardening.
  • Unknown distributions, unsupported architectures, unexpected upstream source layouts, and failed service checks are rejected.

Requirements

  • A paid Proton Mail plan that includes Bridge.
  • x86_64 Linux with systemd.
  • Internet access during dependency installation and compilation.
  • Disk space for the source build and local encrypted mailbox cache.

Read-only inspection

./install.sh

Installation

sudo ./install.sh --apply

The installer asks for a network mode and release tag, installs build dependencies, verifies or installs the required Go toolchain from go.dev, creates a dedicated service account and keychain, builds Bridge, opens the CLI for login, and optionally enables the service.

Network modes

  1. Localhost — recommended; upstream binding is unchanged.
  2. Private tunnel — recommended; Bridge still binds to localhost. Use SSH, WireGuard, or Tailscale.
  3. Direct LAN — unsupported; patches the selected source tag to one private IPv4 address and adds source-restricted firewalld rules.

Example SSH tunnel from a client:

ssh -N \
  -L 1143:127.0.0.1:1143 \
  -L 1025:127.0.0.1:1025 \
  user@bridge-server

Never expose Bridge's IMAP or SMTP ports to the public internet.

Login and account information

sudo ./bridge-cli.sh

Inside the CLI:

login
info
exit

The info command displays Bridge-generated IMAP and SMTP credentials. They are not the Proton account password.

Service

sudo systemctl status proton-bridge
sudo journalctl -u proton-bridge -f

Update

./update.sh
sudo ./update.sh --apply

Uninstall

Preserve account data and cache:

sudo ./uninstall.sh

Permanently delete the service account, vault, GPG key, credentials, and cache:

sudo ./uninstall.sh --purge

Purge mode requires two confirmations.

Paths used by an installation

/etc/systemd/system/proton-bridge.service
/etc/headless-proton-bridge-installer.conf
/opt/proton-bridge/releases/<version>/bridge
/usr/local/bin/proton-bridge
/usr/local/src/proton-bridge
/var/lib/proton-bridge

References

  • https://github.com/ProtonMail/proton-bridge
  • https://proton.me/support/bridge-for-linux
  • https://ndo.dev/blog/headless_protonbridge/

License

GNU GPL v3.0 or later.