autotun

autotun is a terminal UI for discovering and managing SSH port forwards over a single OpenSSH connection. It watches TCP listeners on a remote host, forwards them to local loopback by default, and lets you add, edit, toggle, or reverse tunnels without reconnecting.

Existing SSH configuration works as usual: aliases, keys, agents, ProxyJump, and custom options.

Features

• Discovers remote TCP listeners and auto-forwards them (see Discovery).
• Labels tunnels from remote process names when ss -p can see them.
• Detects application protocols (tcp, http, https, ws) and shows scheme-prefixed local URLs for open forwards.
• Supports forward (-L, remote → local) and reverse (-R, local → remote) tunnels.
• Adds and cancels forwards on one ControlMaster session (no extra SSH transports).
• Rescans remote listeners in the background and tracks service lifecycle.
• Restores previously enabled tunnels after an SSH reconnect.
• Resolves local bind conflicts by trying the next five ports.
• Inline multi-line add/edit forms; help bar toggle with ?.
• Static Linux binaries for x86-64 and ARM64.

Installation

Install script

The installer detects the host architecture, downloads the latest release, verifies its SHA-256 checksum, and installs autotun to $HOME/.local/bin/autotun:

curl -fsSL https://raw.githubusercontent.com/thuanlm215/autotun/main/install.sh | sh

If $HOME/.local/bin is not on your PATH, add it in your shell config or run $HOME/.local/bin/autotun directly.

Install a specific version or choose another destination:

curl -fsSL https://raw.githubusercontent.com/thuanlm215/autotun/main/install.sh \
  | AUTOTUN_VERSION=1.2.0 AUTOTUN_INSTALL_DIR="$HOME/bin" sh

Download and inspect the script first if you prefer not to pipe to sh:

curl -fsSLO https://raw.githubusercontent.com/thuanlm215/autotun/main/install.sh
less install.sh
sh install.sh

Archives and checksums are on the GitHub Releases page.

Build from source

Requires Rust and OpenSSH:

cargo install --git https://github.com/thuanlm215/autotun --locked

Or from a checkout:

cargo build --release --locked
install -Dm755 target/release/autotun "$HOME/.local/bin/autotun"

Usage

autotun user@example.com
autotun development-server

Discover without auto-forwarding:

autotun development-server --no-auto-forward

Scan interval (default 3 seconds):

autotun development-server --interval 5

Reverse forwards at startup, or extra OpenSSH options:

autotun development-server -R 3000 -R 8080
autotun development-server --ssh-arg=-J --ssh-arg=bastion.example.com

Run autotun --help for the full CLI reference.

Controls

Help is shown by default. Press ? to hide or show it.

Key	Action
↑ / ↓, j / k	Move selection
Space	Toggle the selected tunnel on or off
Enter, e	Edit the selected tunnel (inline form)
a	Add a forward (remote → local, -L)
v	Add a reverse (local → remote, -R)
d	Remove a manual tunnel, or ignore a discovered one for this session
r	Rescan remote listeners now
?	Toggle the help bar
q, Ctrl+C	Close tunnels and exit

Esc cancels an open form. It does not quit the app.

Add / edit form

The form opens under the table (one field per line). Field focus is highlighted.

Key	Action
↑ / ↓	Move between fields
Enter	Next field, or save on the last field
Esc	Cancel

While the form is open, the footer shows form help instead of the main shortcut list.

Table columns

Column	Meaning
Direction	Forward (remote → local) or Reverse (local → remote)
Label	Process name from remote ss -p, or a label you set
Remote port	Port on the remote side of the mapping
Local port	Port on the local side of the mapping
URL	Local URL when a forward is on, with detected scheme
Status	ON, off, MANUAL OFF, TARGET DOWN, or an error

Discovery

Autotun runs remote ss -lntp (falls back to ss -lnt / netstat). A port is discovered when:

• the port is greater than 1024, or
• the port is a well-known application listener: 80 or 443

Infrastructure ports such as 22 (ssh) and 53 (DNS) are not auto-discovered. You can still forward any port (including those) with a / v or -R.

Remote listeners created by an enabled reverse tunnel are not re-discovered as forwards. Otherwise reverse-forwarding local Chrome DevTools (9222) would immediately open a second forward back to your machine.

Loopback-only listeners (127.0.0.1, ::1) are included by default (--include-loopback).

Forwarding behavior

Forward (remote → local)

For a remote service on port 3000, autotun prefers:

local 127.0.0.1:3000  →  remote 127.0.0.1:3000

If local 3000 cannot be bound, it tries 3001 … 3005. If none work, the row stays visible with an error in Status.

Reverse (local → remote)

Reverse tunnels are never discovered. Add them with v or --reverse / -R:

remote 127.0.0.1:8080  →  local 127.0.0.1:8080

Lifecycle

• Scans run every three seconds by default.
• A remote service must be missing for two consecutive successful scans before the tunnel is marked TARGET DOWN and an active forward is cancelled.
• Failed scans do not remove tunnels.
• If a service returns and auto-forward is on, the tunnel is re-enabled unless you turned it off with Space (MANUAL OFF). Manual-off survives service restart until you enable the tunnel again or remove it with d.
• Ignoring a discovered tunnel with d also sets manual-off for the session.
• Settings are session-only; nothing is persisted per host.

Protocol and URL

After a forward is enabled, autotun probes the local bind and classifies:

Protocol	How it is detected
https	TLS ServerHello / alert
ws	HTTP 101 Switching Protocols
http	HTTP response
tcp	Default (no higher-level match)

The URL column shows values such as https://127.0.0.1:443 or tcp://127.0.0.1:5432 so terminals can Ctrl/Cmd-click them. Reverse tunnels do not show a local URL.

Binding local privileged ports (80, 443, …) may require elevated rights on your machine; if the preferred port fails, the usual port fallback applies.

How it works

autotun
   └── one SSH ControlMaster transport
       ├── remote listener scans (ss / netstat)
       ├── local forwards (-L)
       └── reverse forwards (-R)

No remote agent, daemon, elevated install, or config file is required on the server.

Requirements and compatibility

• Linux x86-64 or ARM64 for prebuilt binaries (other targets: build from source).
• Local OpenSSH client (ssh).
• Remote ss (iproute2) or netstat.
• Remote SSH server allows TCP forwarding.

Security

• Forwards bind to 127.0.0.1 only; they are not published on the LAN or WAN.
• Reverse forwards are always explicit (v or -R).
• The install script verifies published SHA-256 checksums.
• Authentication and host keys are handled by OpenSSH.

Development

cargo fmt --check
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
tests/install.sh

Optional live SSH tests (need network and credentials):

AUTOTUN_SSH_TEST=1 AUTOTUN_SSH_DEST=user@host \
  cargo test --locked --test ssh_lifecycle -- --nocapture

License

Licensed under the MIT License.