Turn a Raspberry Pi into a hardened Tailscale SSH jump host for private machines.
Pi Remote Bridge is a small, scriptable toolkit for leaving a Raspberry Pi on a trusted network and using it as a remote SSH bridge. It is useful for homelabs, workshops, labs, remote workstations, and any private network where you want stable SSH access without opening public inbound ports.
laptop -> Tailscale -> pi-bridge -> SSH ProxyJump -> private host
| Feature | Description |
|---|---|
| Tailscale SSH bridge | Reach the Pi through Tailscale and SSH onward with ProxyJump. |
| Hardened baseline | Installs SSH, UFW, fail2ban, unattended upgrades, NetworkManager, and a health timer. |
| No private keys on the Pi | Downstream SSH keys stay on your laptop. The Pi acts as a transport hop. |
| Wi-Fi setup scripts | Supports normal SSID/password Wi-Fi and generic WPA/WPA2 Enterprise profiles. |
| Health checks | Periodically verifies internet, Tailscale, and configured target host reachability. |
| macOS flashing helpers | Optional Raspberry Pi Imager wrappers for repeatable SD card setup. |
Clone the repo and create a local config:
git clone https://github.com/<your-username>/pi-remote-bridge.git
cd pi-remote-bridge
cp config/bridge.env.example config/bridge.envFlash Raspberry Pi OS Lite from macOS:
bash scripts/mac-download-image.sh
bash scripts/mac-check-sd.sh /dev/diskN
DISK=/dev/diskN bash scripts/mac-flash-sd.shBoot the Pi, SSH in, and run the bootstrap:
bash scripts/pi-bootstrap.sh
bash scripts/tailscale-up.shConfigure the long-term network:
bash scripts/configure-wifi-home.sh
# or
bash scripts/configure-wifi-enterprise.shAfter key-based or Tailscale SSH is verified:
bash scripts/harden-ssh.shAdd docs/ssh-config.example to your local ~/.ssh/config and edit the
placeholders:
Host pi-bridge
HostName pi-bridge.example-tailnet.ts.net
User pi
IdentityFile ~/.ssh/id_ed25519
Host internal-host
HostName server.internal
User your-user
ProxyJump pi-bridge
IdentityFile ~/.ssh/id_ed25519Then connect through the bridge:
ssh internal-hostScripts load config/bridge.env when present. Secrets are prompted
interactively and should not be committed.
Common values:
HOSTNAME_TARGET=pi-bridge
TAILSCALE_HOSTNAME=pi-bridge
PI_USER=pi
SSH_PUBKEY=$HOME/.ssh/id_ed25519.pub
TARGET_HOSTS=server1.local:22,server2.local:22Pi Remote Bridge is an SSH jump host, not a general-purpose network router. It does not enable routed LAN access or require public inbound ports.
Read SECURITY.md before leaving a device unattended.
MIT