SSH Profile

Network-aware SSH config profile selector.

ssh-profile answers one question -- which profile applies on the network this machine is on right now? -- so your ~/.ssh/config can pick the SSH options that fit. One shared ~/.ssh/config + ssh-profile.toml pair then works across all your machines and networks, instead of per-machine configs that drift.

Features

• Network-aware profile selection -- detect which profile applies on the current network and use it as an ssh_config Match exec predicate.
• Four detection tiers, evaluated as a first-match-wins cascade: hostname, cidr (wired IPv4), gateway_mac, and ssid.
• Safe by design -- predicate mode is silent on stdout; lenient runtime loading fails toward the conservative unknown profile; a broken ssh-profile fails the connection loudly rather than misconnecting.
• Validation built in -- --check-config checks the profile data file and your ~/.ssh/config references; --check-tools checks for the existence of the ip/ping/iw tools.
• Fast -- a short-TTL cache speeds up the burst of ssh-profile invocations generated by an ssh connection; the initial network detection is shared across the burst.
• One shared config -- a common ~/.ssh/config + ssh-profile.toml pair can be used (sync'd) across machines avoiding per-machine drift.

Installation

ssh-profile is a CLI tool hosted on PyPI, so a common installation method is to use pipx as follows:

pipx install ssh-profile

Other install methods (plain pip, uv, from source) are covered in the Installation guide.

Quick start

ssh-profile reads its profiles and detection rules from ~/.ssh/ssh-profile.toml. Here is a simple example with two profiles -- one matched by Wi-Fi SSID, the other by a wired IPv4 range:

[profiles]
home       = "Trusted home LAN"
work-wired = "Office, wired"

[[tiers]]
kind  = "ssid"
rules = [{ ssid = "HomeNet", profile = "home" }]

[[tiers]]
kind  = "cidr"
rules = [{ network = "203.0.113.0/24", profile = "work-wired" }]

With that file in place, ssh-profile prints the profile that matches the current machine's network:

$ ssh-profile
home

Use the profile name in an ssh_config Match exec predicate to select SSH host options by profile (excerpted -- see the Configuration guide for the full pattern):

Match originalhost myserver exec "ssh-profile home"
    HostName 10.0.0.50
    User me

Match originalhost myserver exec "ssh-profile work-wired"
    HostName myserver.internal
    ProxyJump bastion.work
    User me.work

Validate the profile data file and ~/.ssh/config references after each edit:

ssh-profile --check-config

Project links

• PyPI: https://pypi.org/project/ssh-profile/
• Documentation: https://sck.gitlab.io/ssh-profile/
• Source & issues: https://gitlab.com/sck/ssh-profile

License

MIT. Created in 2026 by Scott Karlin.