Skip to content

Settings

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

Settings

SSH Pilot's settings let you customize every aspect of the application. Open them with Ctrl+, (Cmd+, on macOS) or from the application menu (hamburger menu on Linux, File menu on macOS).

The settings window has a sidebar with categories on the left and settings on the right.

Interface

Language

Choose your display language. Select "System Default" to follow your operating system's language setting.

App Startup

Choose what happens when SSH Pilot starts:

  • Show terminal -- Open a local terminal tab
  • Show start page -- Show the welcome page
  • Restore previous session -- Reopen the tabs from your last session
  • Open a saved session -- Open a specific saved session

Appearance

  • Theme -- Choose Light, Dark, or System (follows your OS setting)
  • Accent color -- Pick a custom accent color with the color picker, or reset to default

Window

  • Remember window size -- Save and restore window dimensions across sessions

Sidebar

Display options

  • Sidebar Mode -- Full (names and details) or Minimal (narrow icon strip)
  • Maximum width -- Slider from 100 to 800 pixels (full mode)
  • Flat Sidebar Rows -- Show connections without indentation
  • Display user@hostname -- Show the username and hostname under each connection name
  • Display connection count -- Show the number of connections in each group
  • Display status indicator -- Show connection status (connected/disconnected)
  • Display port forwarding labels -- Show L/R/D labels for port forwards
  • Display icons -- Show connection and group icons

Sidebar behavior

  • Hide Sidebar on Startup -- Start with the sidebar collapsed
  • When a Terminal Opens -- What happens when any session opens (including local terminals):
    • Do Nothing
    • Minimize to Icons -- switch to the minimal strip
    • Hide Sidebar -- hide completely for a plain terminal
  • Show When No Tab Is Open -- Reveal the sidebar again on the welcome/start page
  • Minimized Row Style -- In the icon strip: Initials or Icon

For a step-by-step “plain terminal” setup (hide or minimize the connection list), see Plain Terminal Mode.

Header Bar Buttons

Toggle which buttons appear in the header bar:

  • Sidebar toggle
  • Split view
  • Command snippets
  • Terminal theme
  • Theme menu
  • Local terminal

Tips

  • Show terminal tips banner -- Display helpful tips at the top of the terminal

Terminal

Appearance

  • Font -- Click to choose your preferred monospace font
  • Color scheme -- Pick from a visual palette of built-in themes (dark, light, dracula, monokai, solarized, and more)
  • Encoding -- Choose the character encoding (UTF-8 is the default and recommended)

Backend

Choose the terminal technology:

  • VTE -- Native GTK terminal widget (default on macOS)
  • PyXterm.js -- xterm.js in a WebKit view (default on Linux, better compatibility)

Keyboard

  • Terminal shortcut pass-through -- Disable all keyboard shortcuts and pass keys directly to the terminal. Enable this if you use text expanders, tiling window managers, or terminal apps that need function keys.
  • Command autocomplete -- Show completions from local history and snippets as you type
  • Suggest from remote history -- Include SSH shell history in autocomplete suggestions

Mouse

  • Copy on selection -- Automatically copy selected text to clipboard
  • Paste on right-click -- Paste clipboard content on right-click (auto-disables when the remote app uses mouse input, like htop or vim)

Preferred Terminal

  • Built-in -- Use SSH Pilot's integrated terminal (default)
  • External terminal -- Open connections in an external terminal application
    • Select your terminal from the dropdown, or enter a custom path

File Management

  • Open in separate window -- Open the file manager in its own window instead of a tab
  • SFTP keepalive interval -- How often to send keepalive packets (prevents timeout on slow connections)
  • SFTP keepalive retry limit -- How many keepalive failures before disconnecting
  • SFTP connection timeout -- How long to wait for the SFTP connection to establish

Shortcuts

This page shows all keyboard shortcuts. Click any shortcut to reassign it.

See Keyboard Shortcuts for the complete reference.

Groups

Appearance

  • Color display mode -- How group colors appear in the sidebar:
    • Colored rows -- Entire row has a colored background
    • Color badges -- Small colored badge next to the name
    • Accent bars -- Colored bar on the left edge
    • Color dots -- Small colored dot next to the name
  • Use group color for child rows -- Connections inherit their group's color
  • Show group color in tabs -- Terminal tabs show a colored indicator matching the group
  • Use group color in terminal backgrounds -- Tint the terminal background with the group color

Layout

  • Fullwidth -- Groups and connections stretch the full sidebar width
  • Nested -- Connections are indented under their group

A live preview shows how your choices look.

SSH Options

These settings apply to all connections and override your ~/.ssh/config:

Setting What it does Default
Connect Timeout Seconds to wait for connection 30
Connection Attempts How many times to retry 3
Apply default keepalive Auto-detect dropped connections On
ServerAlive Interval Seconds between keepalive checks 60
ServerAlive CountMax Failed checks before disconnecting 3
StrictHostKeyChecking How to handle unknown host keys accept-new
BatchMode Disable interactive prompts Off
Enable Compression Compress data in transit (-C) Off
SSH Multiplexing Reuse connections for speed (ControlMaster) Off
SSH Verbosity Verbose logging (-v) Off
SSH Debug Logging Extra debug output Off

Click Reset to Defaults to restore all SSH options.

Security & Credentials

See Credentials for setup and Security for how storage and autofill stay safe.

  • Secret Storage Backend -- Choose where passwords are stored
  • Bitwarden setup -- Configure Bitwarden/Vaultwarden connection
  • rbw setup -- Configure the rbw Bitwarden agent
  • KeePass setup -- Set database path and key file
  • Vault lock timeout -- Auto-lock after inactivity
  • SSH Identity provider -- Choose between system agent, 1Password, or custom socket

Updates

  • Check for updates on startup -- SSH Pilot will check GitHub for new versions when it launches

Plugins

View and manage installed plugins:

  • Enable or disable plugins with the toggle switch
  • Install new plugins from file
  • View plugin information
  • Remove user-installed plugins

Docker Console is disabled by default -- turn it on here when you need it. See Plugins, Docker Console, and Protocols.

Command Snippets

Configure snippet behavior:

  • Open on Startup -- Automatically open the snippets panel when the window starts
  • Insert Only (no execute) -- Paste the command into the terminal without running it
  • Close After Sending -- Close the snippets panel after sending a command

See Snippets for how to create and manage snippets (done in the snippets panel itself, not in Settings).

Advanced

Operation Mode

SSH Pilot supports two operation modes. See Isolated Mode for a detailed comparison.

  • Default Mode (recommended) -- Uses your ~/.ssh/config file
  • Isolated Mode -- SSH Pilot uses its own SSH config, connections, folders, and host keys. Passwords are shared.

Application Behavior

  • Confirm before disconnecting -- Ask for confirmation before closing a terminal with an active connection

Logging

  • Log level -- Choose Info (normal) or Debug (verbose, for troubleshooting)

Next Steps

Clone this wiki locally