gssh

A graphical SSH client connection and configuration manager for Debian/Linux. Manage your ~/.ssh/config hosts through a GUI, edit connection parameters, and open SSH sessions — either in an embedded terminal or by launching your preferred external terminal emulator.

Features

• Visual host management — view, add, edit, and delete Host entries from ~/.ssh/config
• Dedicated fields for the common options: HostName, User, Port, IdentityFile, ProxyJump, ForwardAgent
• Extra options — any arbitrary ssh_config directive via a freeform text area
• Safe writes — atomic file replacement with automatic timestamped backups (.config.bak.YYYYMMDD_HHMMSS) and 0600 permissions
• Config linter — catches unknown/deprecated options, insecure key permissions, invalid ports, undefined ProxyJump references, and pattern-overlap conflicts (first-match-wins)
• Connection test — TCP ping-before-connect with latency display
• Wildcard hosts — supports patterns like *.lab.local
• Search/filter — live filter by alias, hostname, or user
• In-app terminal — embedded PTY-based terminal using pyte for VT220 emulation with 5000-line scrollback and 16-colour ANSI
• External terminal — toggle to launch ssh in konsole, gnome-terminal, xterm, or any detected emulator
• Round-trip safe — preserves comments, preamble, and unknown directives

Requirements

• Python 3.12+
• PyQt6
• pyte
• (Optional) a terminal emulator for external mode: konsole, gnome-terminal, xterm, etc.

Install

From PyPI (recommended)

pip install gssh
gssh

Or run without installing:

uvx gssh          # via uv
pipx run gssh     # via pipx

From source

git clone https://github.com/ggrace519/graphical-ssh.git
cd graphical-ssh
uv sync
uv run gssh

Desktop integration

To add gssh to your application menu:

# If installed via pip, the data files are inside the package:
python -c "import gssh.data; print(gssh.data.__path__)"
sudo cp $(python -c "import gssh.data; print(gssh.data.__path__[0])")/gssh.desktop /usr/share/applications/
sudo cp $(python -c "import gssh.data; print(gssh.data.__path__[0])")/gssh.svg /usr/share/icons/hicolor/scalable/apps/
sudo update-desktop-database

Usage

# Use default ~/.ssh/config
uv run gssh

# Specify a custom config file
uv run gssh -c /path/to/ssh/config

GUI controls

Development

# Run tests with coverage
uv run pytest

# Run the app
uv run gssh

# Run with a test config
uv run gssh -c /tmp/test-config

Project structure

src/gssh/
├── __init__.py       # package metadata
├── __main__.py       # CLI entry point (argparse + QApplication)
├── config.py         # SSH config parser/writer (round-trip safe, atomic writes)
├── models.py         # Qt table model for host entries
├── host_editor.py    # Add/Edit host dialog
├── connect.py        # SSH command builder + launch (in-app or external)
├── terminal.py       # In-app terminal widget (pyte + PTY)
└── main_window.py    # Main window: host list, toolbar, terminal container

tests/
└── test_config.py    # Parser/writer tests (20 tests, 90% config coverage)

Roadmap

• Tier 2: key file management (generate, view, copy public key), known-hosts viewer, connection test, import/export
• Tier 3: port-forwarding manager, per-host tags/notes, system tray quick-connect

License

MIT