porthole

Create and manage named SSH port forwards easily.

Porthole wraps ssh to turn tunnel commands into named profiles: define a forward once, then open, close, and inspect it by name. Each open forward runs under a small supervisor process that keeps it alive and reconnects automatically if the connection drops.

Features

Named profiles for local, remote, and dynamic/SOCKS forwards, saved to disk instead of retyped each time.
Multi-hop jump chains, built on ssh -J.
Auto-reconnect with exponential backoff, unless a failure looks permanent (bad auth, host key mismatch, port already bound).
Status and listing with live state, uptime, and reconnect counts, as text or JSON.
Import/export of profiles as a single TOML file, for moving a setup to another machine.
Shell completions for bash, zsh, fish, and others.
Hardened by default: every spawned ssh call ignores the caller's own config, runs in batch mode with no interactive prompts, and applies the same hardening to every hop in a jump chain, not just the final target.

Installation

Requires a Rust toolchain and an ssh binary on PATH.

cargo build --release

The binary is written to target/release/porthole. Place it on PATH, e.g.:

install -Dm755 target/release/porthole ~/.local/bin/porthole

Commands

Command	Aliases	Description
`add`	`mk`, `create`	Save a new forward profile.
`open`	`start`	Start a saved forward as a supervised background process.
`close`	`stop`	Stop a running forward.
`edit`	`change`	Update a saved profile.
`status`		Show detailed status for one forward.
`list`	`ls`	List all saved profiles with live status.
`remove`	`rm`, `delete`	Delete a saved profile.
`wipe`	`reset`	Close and delete every forward, tracked or not.
`transfer`	`data`	Export saved profiles to a file, or import them from one.
`completions`		Generate a shell completion script.

Run porthole or porthole --help for the full flag reference.

`add` / `edit` flags

One of -l/--local, -r/--remote, or -d/--dynamic selects the forward kind (required for add, optional for edit):

Flag	Value	Meaning	Default
`-l, --local`	`[BIND:]PORT:HOST:PORT`	Local forward (this machine -> remote machine).	-
`-r, --remote`	`[BIND:]PORT:HOST:PORT`	Remote forward (remote machine -> this machine).	-
`-d, --dynamic`	`[BIND:]PORT`	Dynamic forward (SOCKS proxy).	-
`--via`	`[USER@]HOST[:PORT]`	Jump-host chain, ending at the connection target. Required.	-
`-u, --user`	`USER`	Default user for the target and any hop without one.	-
`-i, --identity`	`PATH`	Identity file override.	-
`-p, --port`	`PORT`	SSH port of the final target.	`22`
`--reconnect`	`BOOL`	Auto-reconnect on connection drop.	`true`
`--retry-interval`	`SECONDS`	Base delay between reconnection attempts.	`5`
`--backoff-max`	`SECONDS`	Cap on the doubling reconnection delay.	`60`
`--keepalive`	`SECONDS`	SSH `ServerAliveInterval`.	`15`

edit only touches the fields given on the command line; everything else stays as-is.

Examples

# Remote forward, exposing this machine's port 3000 to the remote host.
porthole add expose-app -r 3000:localhost:3000 --via ops@server.example.com

# Dynamic SOCKS proxy.
porthole add socks -d 1080 --via user@gateway

# Two-hop jump chain: bastion1, then bastion2, ending at db-host.
porthole add mydb -l 5432:internal-db:5432 --via bastion1 --via bastion2 -u ops

# Open every profile with reconnect enabled that isn't already running.
porthole open --all

# Run attached in the current shell instead of detaching.
porthole open mydb --foreground

# Force-kill instead of a graceful SIGTERM-then-wait.
porthole close mydb --force

# Machine-readable status/listing.
porthole status mydb --json
porthole list --json

# Back up all profiles, then restore them elsewhere.
porthole transfer --export backup.toml
porthole transfer --import backup.toml

ⓘ Note:
transfer --export does not include identity file contents, only their configured paths; key files need to be copied to the target machine separately.

How a forward stays open

open spawns a detached copy of the porthole binary running an internal supervisor loop for that one profile. The supervisor:

Builds and runs the ssh command for the profile (-N -T plus the right -L/-R/-D flag), holding an advisory file lock for its whole lifetime so status/list can reliably tell if it's still alive.
Watches the connection; once it survives a short grace period it's reported as up.
On a dropped or failed connection, classifies the failure:
- Fatal (bad auth, host key mismatch, port already in use): gives up immediately, state becomes error.
- Known transient (connection refused, DNS failure, timeout): reconnects with exponential backoff.
- Unrecognized: also retries, but gives up after too many consecutive unrecognized failures in a row.
Resets the backoff delay once a connection has stayed up long enough to be considered stable again.
Logs ssh output to a per-profile log file, rotating it once it grows past 10 MB.
Exits cleanly and removes its own state on close (SIGTERM) or Ctrl-C in foreground mode (SIGINT).

State on disk

Profiles: $XDG_CONFIG_HOME/porthole/profiles/<name>.toml
Runtime state, lock, and log for each open forward: $XDG_STATE_HOME/porthole/<name>.{json,lock,log}.

State locations can be overridden with the PORTHOLE_STATE_DIR_OVERRIDE environment variable.

Shell completions

porthole completions bash > /etc/bash_completion.d/porthole
porthole completions zsh  > "${fpath[1]}/_porthole"
porthole completions fish > ~/.config/fish/completions/porthole.fish

7.0 KiB Raw Permalink Blame History