Skip to content

Connections

Jump to bottom
Mehdi edited this page Sep 3, 2026 · 8 revisions

Connections

This guide covers everything about creating, editing, organizing, and managing your SSH connections in SSH Pilot.

How Connections Work

SSH Pilot reads your existing ~/.ssh/config file to discover servers. When you connect, it uses your system's native OpenSSH client. This means every SSH feature you use in the terminal -- ProxyJump, custom keys, port forwarding -- works automatically in SSH Pilot.

Creating a New Connection

Step 1 -- Open the Connection Editor

Click the + button at the top of the sidebar, or press Ctrl+Shift+N (Cmd+N on macOS).

Step 2 -- Fill in the Details

The connection editor has several tabs. At minimum, fill in the General tab:

Field What to enter Example
Name A friendly nickname My Web Server
Hostname Server IP or domain 192.168.1.100 or example.com
Username Your login name ubuntu or root
Port SSH port (default: 22) 22

Step 3 -- Save

Click Save or press Ctrl+S (Cmd+S on macOS). The connection appears in your sidebar.

Editing a Connection

  1. Right-click the connection in the sidebar
  2. Select Edit Connection
  3. Make your changes
  4. Click Save

Connection Editor Tabs

The connection editor has several tabs for advanced configuration:

Authentication

Choose how SSH Pilot logs in to the server:

  • Password -- Enter and save a password (stored securely in your credential manager)
  • Public Key -- Select an SSH key file for key-based authentication
  • Certificate -- Optionally provide a certificate file
  • PKCS#11 Provider -- For hardware security keys (YubiKey, etc.)

Forwarding

Configure what gets forwarded through the SSH connection:

  • Agent Forwarding -- Forward your SSH agent to the remote server
  • X11 Forwarding -- Forward X11 display for graphical apps
  • Port Forwarding -- Set up local, remote, or dynamic (SOCKS) port forwards

Proxy

Set up multi-hop connections using ProxyJump:

  1. Click Add Proxy Hop
  2. Select an existing connection as the jump host
  3. Add multiple hops if needed

Advanced

For power users:

  • Pre-command -- Command to run before connecting
  • Local command -- Command to run on your machine after connecting
  • Remote command -- Command to run on the server after connecting
  • Extra SSH config -- Additional SSH options for this connection
  • Aliases -- Alternative hostnames for this connection

Middle-Click Shortcuts

You can use the middle mouse button for quick actions in the sidebar:

  • Middle-click a connection -- Opens the connection in a new tab (same as Ctrl+Enter)
  • Middle-click a group -- Opens all connections in that group, each in its own tab. If the group has many connections, you will be asked to confirm first.

This works anywhere in the connection list without needing to open a context menu.

Organizing Connections

Groups

Groups let you organize connections into folders:

  1. Right-click a connection in the sidebar
  2. Select Move to Group > New Group
  3. Enter a group name and pick a color

Tips:

  • Groups can be nested (group within a group)
  • You can drag connections between groups

Right-clicking a group

Right-click a group header to access:

  • Edit Group -- Change the group name and color
  • Open in Split View -- Open all connections in the group in a split view
  • Run Command -- Execute a command on all connections in the group
  • Ungroup -- Move the group's connections to the root level (nested groups only)
  • Delete Group -- Remove the group (connections are kept, just ungrouped)

Right-clicking a tag

Right-click a tag in the sidebar to access:

  • Rename Tag -- Change the tag name
  • Open in Split View -- Open all connections with that tag in a split view

Colors

Each group can have a color (red, blue, green, orange, purple, cyan, or gray). The color appears as:

  • A badge next to the group name
  • A colored bar behind connections in that group
  • Optionally, a tinted terminal background

Configure group colors in Settings > Groups.

Tags

Tags create virtual groups without moving connections:

  1. Right-click a connection
  2. Select Add Tag
  3. Enter a tag name

Tags appear as filter buttons in the sidebar. Click a tag to show only connections with that tag.

Sorting Connections

Click the sort button at the bottom of the sidebar to cycle through sort modes:

  • Manual -- Your custom order (drag to reorder)
  • Alphabetical -- Sort by name
  • By Host -- Sort by hostname
  • By Group -- Group connections together

Searching Connections

Press Ctrl+F (Cmd+F on macOS) to focus the sidebar search bar. Type to filter connections by name, hostname, or tags.

You can also use the Omni-search by pressing Shift+Shift (double-tap Shift) to search connections, snippets, and actions all at once.

Deleting Connections

  1. Right-click the connection in the sidebar
  2. Select Delete
  3. Confirm the deletion

You can also select multiple connections with Ctrl+click and press Delete to remove them all at once.

Right-Click Context Menu

Right-click a connection in the sidebar to see all available actions:

Connection actions

  • Open New Connection -- Connect in a new terminal tab
  • Edit Connection -- Open the connection editor
  • Open in Split View -- Add this connection to a split-view tab
  • Run Command on Host -- Execute a remote command (SSH connections only)
  • Duplicate Connection -- Create a copy of this connection
  • Copy Address -- Copy the hostname/IP to clipboard
  • Copy SSH Command -- Copy the full ssh user@host command to clipboard
  • Verify Configuration -- Check that the SSH config is valid (SSH connections only)

File & key actions

  • Manage Files -- Open the SFTP file manager
  • Copy Key to Server -- Deploy your public key (ssh-copy-id)
  • Manage authorized_keys… -- Edit the remote authorized_keys file (Authorized Keys)

Network actions

  • Wake on LAN -- Send a magic packet to wake the server (only if a MAC address is configured)
  • Open in System Terminal -- Open the connection in your external terminal app (SSH connections only)

Group actions

  • Move to Group -- Move the connection to an existing group
  • Copy to Group -- Add the connection to a group without removing it from its current location
  • Ungroup / Remove from Group -- Remove the connection from its group

Start page

  • Pin to Start Page -- Pin the connection to the welcome page for quick access
  • Unpin from Start Page -- Remove the pin

Plugin actions

  • Docker Console -- Open the Docker/Podman manager for this host (if the plugin is enabled)

Delete

  • Delete -- Remove the connection (asks for confirmation)

Multi-Select Actions

Select multiple connections with Ctrl+click (or Cmd+click on macOS), then right-click:

  • Open New Connections -- Open each selected connection in a new tab
  • Open in Split View -- Open all selected connections in a split view
  • Run Command on Hosts -- Execute the same command on all selected servers (if all support remote commands)
  • Wake on LAN -- Wake all selected servers that have MAC addresses configured
  • Move to Group / Copy to Group / Ungroup -- Batch group operations
  • Pin to Start Page / Unpin from Start Page -- Batch pin operations
  • Delete -- Delete all selected connections

Viewing Effective SSH Config

To see exactly how OpenSSH will connect to a server:

  1. Right-click the connection
  2. Select Verify Configuration

This shows the resolved configuration as if you ran ssh -G <hostname>.

Next Steps

Clone this wiki locally