alebeck/boring: The `boring` SSH tunnel manager

The boring SSH tunnel manager

Summary

boring is a Go-based command-line tool for managing SSH port-forwarding tunnels. It reads a TOML configuration file and lets engineers start, stop, and group multiple local, remote, and SOCKS5 tunnels through a single binary. The goal stated in the README is to replace ad-hoc ssh -L/-R/-D commands with a declarative, restartable setup.

What it is useful for

Engineers who frequently tunnel through jump hosts or remote machines can use boring to:

• Persistently forward ports to and from remote servers without leaving a terminal running a manual ssh -L command.
• Stand up SOCKS5 proxies for routing browser or CLI traffic through a remote host, using the documented "socks" and "socks-remote" modes.
• Forward traffic over Unix sockets, which is useful when a service exposes a local socket rather than a TCP port.
• Reuse an existing ~/.ssh/config and ssh-agent: the host, user, identity, and port fields fall back to standard SSH config values when omitted.
• Recover from dropped connections via built-in keep-alives (default 120 seconds) and automatic re-connection.
• Organize tunnels into groups so a developer juggling several services can open or close related tunnels with one call, for example boring open -g backend.

How engineers can use it

The README documents three installation paths:

• Homebrew: brew install boring
• Pre-built binaries from the GitHub releases page, placed on $PATH
• Building from source: git clone https://github.com/alebeck/boring && cd boring && make

On Windows, the README notes full support since release 0.6.0, but users have to build from source with Go 1.25 or later using build_win.bat.

After installation, create a config file. On macOS and Windows the default is ~/.boring.toml; on Linux it is $XDG_CONFIG_HOME/boring/.boring.toml, and $BORING_CONFIG overrides the path. A minimal entry looks like:

[[tunnels]]
name = "dev"
local = "9000"
remote = "localhost:9000"
host = "dev-server"

Then boring open -a starts every tunnel, boring open dev* matches by glob pattern, and boring open -g backend opens a group. boring list shows current state and boring edit opens the config in $EDITOR. Shell completions for bash, zsh, and fish can be enabled with eval "$(boring --shell bash)" or the equivalent for other shells.

The control socket lives at /tmp/boringd.sock and logs at /tmp/boringd.log; both can be relocated with $BORING_SOCK and $BORING_LOG_FILE, and $DEBUG enables verbose logging. The repository's GitHub license field is NOASSERTION, so check the source before redistributing.