mole
Linux · macOS · Windows · *BSD
mole runs here, on your laptop — ssh-agent or ~/.ssh/id_*
Everything mole handles for you
From auto-discovered dev servers to periodic health checks — mole removes the busywork of port forwarding.
Under the hood
Four goroutines, one SSH client, no port list to maintain.
Connect
Open one SSH client connection to the remote. ssh-agent or ~/.ssh/id_* keys; aliases resolved via ssh -G.
Discover
Enumerate the remote's TCP listeners (ss/netstat) every 15 s, or fall back to probing discover_ports. Skip exclude_ports.
Forward
For each port, bind 127.0.0.1:<port> locally; on a local connection, dial 127.0.0.1:<port> through the tunnel and bridge bytes both ways.
Heal
A watchdog reconnects the SSH session if it dies; re-discovery picks up new servers; UNFWD prunes dead ones.
Colourised, structured, skimmable
Every line gets a colour-graded level badge, a dimmed timestamp, and repeated events collapse to a single line with a (×N) counter.
mole logs renders the daemon's structured log with coloured level badges, a distinct green FORWARD badge when a port starts forwarding and a burnt-orange UNFWD badge when a dead remote port is pruned, dimmed timestamps, and (×N) collapsing of repeated lines.
Running in three commands
Three commands. Under a minute from curl to forwarded ports.
$ curl -fsSL https://raw.githubusercontent.com/Luqueee/mole/main/scripts/install.sh | sh $ mole init $ mole status # what's forwarded right now
mole logs -f # pretty, colourised, live
mole down # stop the background daemon mole init writes the config, then offers to start mole in the background for you. From there it keeps the tunnel up and forwards new servers as they appear.
The full CLI surface
Eight commands cover the full lifecycle. mole help lists them all.
| Command | What it does |
|---|---|
| mole up› | Start the forwarder in the foreground (add -d to background it). |
| mole down› | Stop a backgrounded mole (started with up -d). |
| mole status› | Query the local admin API for live stats + forwarded ports. |
| mole logs› | Show the daemon log, colourised; -f to follow. |
| mole init› | Generate a mole.yaml interactively (or scripted). |
| mole update› | Update mole in place to the latest release (re-runs the installer). |
| mole version · mole help› | The obvious. |
Runs on your machine
Same source, same commands, every desktop OS.
Linux glibc & musl
curl -fsSL https://raw.githubusercontent.com/Luqueee/mole/main/scripts/install.sh | sh
macOS Intel & Apple Silicon
curl -fsSL https://raw.githubusercontent.com/Luqueee/mole/main/scripts/install.sh | sh
Windows PowerShell 5+
irm https://raw.githubusercontent.com/Luqueee/mole/main/scripts/install.ps1 | iex
FreeBSD Unix-like
curl -fsSL https://raw.githubusercontent.com/Luqueee/mole/main/scripts/install.sh | sh
Common questions
If yours isn't here, the README and the GitHub Issues have the rest.
How is mole different from `ssh -L`?
A single SSH client multiplexes every forwarded port. mole auto-discovers what's listening on the remote, so you don't keep a port list. It transparently reconnects when the tunnel drops, and `mole logs` gives you colourised, structured output.
Does it work with my existing `~/.ssh/config`?
Yes. Pass an alias as the remote (e.g. `mole up --remote dev`) and mole resolves it via `ssh -G` — HostName, User, Port, IdentityFile, Include and Match are all honoured.
Where does the binary run — on my laptop or the remote?
On your laptop. The remote only needs sshd. The mole daemon opens the SSH connection, enumerates listeners over the encrypted channel, and binds the forwarded ports on 127.0.0.1 locally.
What if the SSH connection drops?
A watchdog goroutine reconnects the tunnel. Re-discovery picks up any new servers that came up while the connection was down, and a UNFWD badge prunes ports that closed on the remote.