par-term provides comprehensive SSH host management with automatic discovery, quick connect, SSH profiles, and automatic profile switching on remote connections.
- Overview
- SSH Quick Connect
- Host Discovery
- SSH Profiles
- Automatic Profile Switching
- Remote Tab Title Format
- Remote Clipboard (OSC 52)
- Configuration
- Settings UI
- Troubleshooting
- Related Documentation
The SSH system aggregates hosts from multiple sources and provides quick access via a searchable dialog:
graph TD
Discovery[Host Discovery]
Config[~/.ssh/config]
Known[~/.ssh/known_hosts]
History[Shell History]
MDNS[mDNS/Bonjour]
Aggregator[Discovery Aggregator]
QuickConnect[Quick Connect Dialog]
Profiles[SSH Profiles]
ProfileDrawer[Profile Drawer]
Terminal[Terminal]
Discovery --> Config
Discovery --> Known
Discovery --> History
Discovery --> MDNS
Config --> Aggregator
Known --> Aggregator
History --> Aggregator
MDNS --> Aggregator
Aggregator --> QuickConnect
QuickConnect --> Terminal
Profiles --> ProfileDrawer
ProfileDrawer --> Terminal
style Discovery fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
style Config fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style Known fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style History fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style MDNS fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
style Aggregator fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
style QuickConnect fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
style Profiles fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
style ProfileDrawer fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
style Terminal fill:#880e4f,stroke:#c2185b,stroke-width:2px,color:#ffffff
The Quick Connect dialog provides fast access to all discovered SSH hosts.
Opening Quick Connect:
| Platform | Shortcut |
|---|---|
| macOS | Cmd + Shift + S |
| Linux/Windows | Ctrl + Shift + S |
Features:
- Real-time search filtering by alias, hostname, or username
- Hosts grouped by source (SSH Config, Known Hosts, History, mDNS)
- Keyboard navigation with Up/Down arrows
- Press
Enterto connect,Escapeto cancel
Connection Flow:
- Press
Cmd+Shift+Sto open the dialog - Type to search and filter hosts
- Use arrow keys to select a host
- Press
Enterto connect - The SSH command is sent to the active terminal (e.g.,
ssh -p 2222 user@example.com) - The SSH session begins in the current tab
Note: Before the command is written to the shell, par-term validates the hostname, user, identity file, and ProxyJump host. A host whose fields contain shell metacharacters or begin with
-(for example, a hostile mDNS advertisement) is rejected, and safe values are shell-quoted.
par-term automatically discovers SSH hosts from four sources. Hosts are deduplicated across sources with priority: SSH Config > Known Hosts > History.
Source: ~/.ssh/config
Parses your SSH configuration file for host entries.
Supported directives:
Host— Host alias (multi-host lines likeHost foo barcreate separate entries)HostName— Target hostname or IP addressUser— SSH usernamePort— SSH port numberIdentityFile— Path to private key (tilde~expanded)ProxyJump— Bastion/jump host for tunneling
Note: Wildcard-only entries (e.g.,
Host *orHost *.example.com) are skipped since they represent defaults, not connectable targets.
Source: ~/.ssh/known_hosts
Extracts hostnames from previously-connected hosts.
Supported formats:
- Plain hostnames:
github.com ssh-ed25519 AAAA... - Bracketed ports:
[myserver.example.com]:2222 ssh-rsa AAAA... - Comma-separated:
host1.example.com,192.168.1.1 ssh-rsa AAAA...
Note: Hashed entries (lines starting with
|1|) are skipped because the hostname cannot be extracted.
Sources:
- Bash:
~/.bash_history - Zsh:
~/.zsh_history - Fish:
~/.local/share/fish/fish_history
Scans shell history for previous ssh commands and extracts connection details including user, host, port, and identity file.
Discovers SSH hosts on the local network by browsing the _ssh._tcp.local. service type.
This feature is opt-in. Enable it in Settings > Profiles > SSH > mDNS/Bonjour Discovery, or in config (top-level keys — ssh is a flattened sub-config):
enable_mdns_discovery: true
mdns_scan_timeout_secs: 3 # Range: 1-10 secondsWhen enabled, the Quick Connect dialog shows a spinner while scanning and displays discovered hosts in real time.
Profiles can act as SSH bookmarks by setting SSH-specific fields.
- Open Settings (
F12;Cmd+,on macOS,Ctrl+Shift+,on Windows/Linux) - Navigate to the Profiles tab
- Click + New Profile
- Expand the SSH Connection section
- Fill in the SSH fields:
| Field | Description | Example |
|---|---|---|
| SSH Host | Hostname or IP to connect to | example.com |
| SSH User | SSH username | deploy |
| SSH Port | Port number (blank = 22) | 2222 |
| SSH Identity File | Path to private key | ~/.ssh/id_work |
| SSH Extra Args | Additional SSH flags | -o ServerAliveInterval=60 |
- Click Done, then Save at the bottom of the Settings window
Note: When
SSH Hostis set, opening the profile connects via SSH instead of launching a local shell.
Profiles with ssh_host set can be launched in several ways:
- Profile Drawer: Toggle via the Profiles menu or the on-screen drawer button (when
show_profile_drawer_button: true), then select the profile - New Tab Button: Click the
▾chevron on the tab bar and select the SSH profile
The profile builds the SSH command from its fields:
ssh -p 2222 -i ~/.ssh/id_work deploy@example.com
Extra-argument filtering: ssh_extra_args is tokenized with shell-style quoting, and tokens that enable command execution, forwarding, or tunnels (-A, -D, -R, -L, -W, -w, and denied -o options such as ProxyCommand) are dropped with a logged warning. If the string cannot be parsed, all extra arguments are dropped.
Field Priority: The ssh_host field takes precedence over command. If both are set, par-term launches the SSH connection and ignores command.
par-term can automatically switch profiles when connecting to SSH hosts, providing visual context for remote sessions.
When an SSH session is detected, par-term monitors terminal output for the remote hostname (via OSC 7 shell-integration sequences, emitted as file://hostname/path) and searches for a profile with matching hostname_patterns.
When a match is found:
- Profile icon appears in the tab bar
- Tab title updates to the profile's tab name
- Badge text and styling apply
- Profile command runs after confirmation (if configured)
par-term also detects when an ssh process is running in the terminal. This marks the session as remote so it can revert on disconnect; the profile match itself still comes from the OSC 7 hostname (see Hostname-Based Switching).
When an SSH session ends, par-term automatically reverts to the previous profile:
- Tab icon, title, and badge restore to pre-SSH state
- The revert happens when the SSH process exits
Reversion happens automatically when the SSH process exits or the reported hostname returns to the local machine.
When shell integration detects a remote host (via OSC 7 sequences), par-term can automatically update the tab title to reflect the remote connection. The format is controlled by remote_tab_title_format:
| Value | Format | Example |
|---|---|---|
user_at_host (default) |
user@hostname |
deploy@prod.example.com |
host |
hostname only | prod.example.com |
host_and_cwd |
hostname:~/cwd |
prod.example.com:~/app |
remote_tab_title_format: user_at_host # default
# When true (default), explicit OSC title sequences take precedence over
# remote_tab_title_format. Set to false to always use the format above.
remote_tab_title_osc_priority: trueSettings UI: Settings > Windows & Tabs > Tab Bar > "Remote Tab Title Format"
Note:
remote_tab_title_formatrequires shell integration to be installed on the remote host so that OSC 7 sequences are emitted. See Integrations for installation instructions.
When a remote program copies text — for example, a selection inside a remote tmux session — it typically uses the OSC 52 escape sequence to push that text to your local clipboard. par-term bridges OSC 52 clipboard-set sequences to the system clipboard, so a copy initiated on the remote host lands in your local clipboard and is ready to paste locally (Cmd+V / Ctrl+Shift+V). No shell integration is required; it works over any SSH session.
osc52_clipboard: true # default — set to false to stop programs overwriting your clipboardSee Mouse Features for the full OSC 52 clipboard behavior, including per-pane polling and the focused-pane caveat.
# SSH settings — top-level keys (the `ssh` sub-config is `#[serde(flatten)]`'d
# into Config, so these write to the top of config.yaml, not under a `ssh:` block).
enable_mdns_discovery: false # default: false
mdns_scan_timeout_secs: 3 # range: 1-10, default: 3
ssh_auto_profile_switch: true # default: true
ssh_revert_profile_on_disconnect: true # default: true
# Remote tab title format (also top-level; requires shell integration on the remote host)
remote_tab_title_format: user_at_host # user_at_host | host | host_and_cwd
remote_tab_title_osc_priority: true # OSC titles take priority over formatProfile SSH fields (in profiles.yaml):
- id: 550e8400-e29b-41d4-a716-446655440000
name: Production Server
icon: "🌐"
ssh_host: prod.example.com
ssh_user: deploy
ssh_port: 22
ssh_identity_file: ~/.ssh/id_prod
ssh_extra_args: "-o ServerAliveInterval=60"
badge_text: "🔴 PROD"
badge_color: [255, 0, 0]Keybinding:
keybindings:
- key: "CmdOrCtrl+Shift+S"
action: "ssh_quick_connect"The SSH page of the Profiles tab in Settings (F12) has a section with three sub-sections:
Profile Auto-Switching:
- Toggle auto-switch on SSH connection
- Toggle revert on SSH disconnect
mDNS/Bonjour Discovery:
- Enable/disable mDNS host discovery
- Scan timeout slider (1-10 seconds)
Quick Connect:
- Shows the currently bound chord for
ssh_quick_connect, or a hint to bind the action under Keys > Key Bindings if none is bound - Info about host sources
Hosts not appearing in Quick Connect:
- Verify
~/.ssh/configexists and has validHostentries (not just wildcards) - Check that
~/.ssh/known_hostsis readable - For mDNS hosts, ensure
enable_mdns_discovery: trueis set and devices are on the same network
Profile not auto-switching on SSH:
- Ensure
ssh_auto_profile_switch: truein config - Verify the profile has
hostname_patternsthat match the remote hostname - Shell integration must be installed on the remote host for OSC 7 hostname reporting
mDNS hosts not appearing:
- Enable mDNS in Settings > Profiles > SSH > mDNS/Bonjour Discovery
- Increase
mdns_scan_timeout_secsfor slower networks - Ensure the remote hosts advertise
_ssh._tcpvia Bonjour/Avahi
- Profiles - Profile system and auto-switching
- Integrations - Shell integration for remote hosts
- Keyboard Shortcuts - SSH Quick Connect shortcut
- Tabs - Tab creation and profile selection