Skip to content
urzeyePublic

About

⚡ Keyboard-driven SSH manager TUI with recursive Include, dotfiles-friendly managed mode, atomic backups & effective config display.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

105 Commits

Folders and files

Repository files navigation

lazyssh logo

⚡ lazyssh

A modern, keyboard-first terminal SSH manager designed for real-world SSH setups

Recursive OpenSSH Include • Dotfiles-friendly Managed Mode • Non-destructive Safe Writes • Instant Terminal Productivity

English | 简体中文

GitHub release Go Version License Build Status Platform

Note

lazyssh is an independent, actively maintained continuation and enhanced fork of Adembc/lazyssh. The upstream repository is no longer actively maintained. This fork addresses real-world SSH workflows: multi-file Include configs, dotfiles synchronisation, managed write isolation, cascading pattern resolution, and rock-solid terminal ergonomics. All foundational credit and appreciation go to the original creator, Adembc.


📑 Table of Contents


💡 About lazyssh

lazyssh is an interactive, keyboard-driven SSH manager for your terminal, inspired by tools like lazydocker and k9s but purpose-built for OpenSSH workflows.

Managing dozens of servers across cloud providers, home labs, jump hosts, and client environments often leaves developers drowning in forgotten IP addresses, complicated proxy flags, and fragile ~/.ssh/config files. Most terminal pickers assume a simple flat file and overwrite custom comments or break symlinked dotfiles.

lazyssh solves this comprehensively:

  • Recursively parses your entire OpenSSH Include hierarchy (e.g. conf.d/, OrbStack, Colima).
  • Isolates user edits into a dedicated managed file so your version-controlled root dotfiles stay untouched.
  • Computes cascading wildcards (Host *, Host lab-*) to display the true, effective connection configuration.
  • Operates strictly with non-destructive atomic writes and rolling backups.
  • Provides a lighting-fast keyboard navigation experience with fuzzy search, panel jumps, SCP command generation, SFTP launching, and port forwarding.

🌟 Key Highlights

📁 Advanced Config & Dotfiles Architecture

  • Recursive Include Support: Traverses full OpenSSH Include trees (including wildcards like ~/.ssh/conf.d/*.conf, OrbStack, etc.) instead of assuming a single flat config file.
  • Managed Mode (--managed-mode): Reads the complete config tree from your root config, but isolates all additions, updates, and deletions to a dedicated managed file (such as ~/.ssh/config.local).
  • Read-Only Protection: Hosts originating from included or external files are visually tagged with [inc] and protected against accidental edits. A dedicated --ssh-config-readonly flag provides safe browsing mode.
  • Effective Values Resolution: Automatically computes and displays cascading OpenSSH directives (e.g., global Host * defaults, pattern-based Host dev-* rules, root inheritance) so you see the exact parameters OpenSSH will use.
  • Safe Host Ordering: Automatically places newly created hosts before matching wildcard rules to guarantee OpenSSH first-match precedence.
  • Full Syntax Fidelity: Robust handling of quoted host entries (Host "example-name"), multi-alias lines, and negated patterns (Host !foo bar-*).

🛡️ Non-Destructive & Resilient File Writes

  • Atomic File Swapping: Configuration updates are written to temporary files and atomically renamed to prevent file corruption during sudden interruptions.
  • Symlink Preservation: Modifies symlink targets in-place instead of replacing symlinks with regular files, keeping dotfile repositories intact.
  • Dual-Layer Backups: Creates a baseline .original.backup before the very first modification, plus rolling timestamped backups (config.local-YYYYMMDD-HHMMSS-lazyssh.backup) with automatic 10-version rotation.
  • Portable Identity Paths: Normalizes private key paths under $HOME to portable ~/.ssh/... formats for seamless multi-machine dotfile sharing.
  • Metadata Separation: Tags, pinned states, and connection statistics are saved to ~/.lazyssh/metadata.json without dirtying or rewriting your SSH config files.

⌨️ Terminal UX & Keyboard Ergonomics

  • Fast Fuzzy Search: Multi-field fuzzy search ranks hosts by relevance across alias, hostname, user, and tags.
  • Numbered Panel Switching: Instantly jump between Search (0 or /), Host List (1), and Details (2).
  • Collapsible Search Bar: Press / to show/hide the search bar and maximize vertical terminal space.
  • Persisted Sorting & Themes: Toggle sorting by Alias or Last Connection (s), reverse order (S), and toggle Dark/Light themes (T) with persisted preferences.
  • Mouse & Terminal Resiliency: Safe mouse-click handling ensures j/k navigation, focus state, and input backspaces remain completely reliable.

🚀 Connection, Forwarding & Transfer Helpers

  • Instant Connection: Hit Enter to launch OpenSSH. Diagnostic error output is retained if a connection fails.
  • Clone Host (C): Duplicate any existing host configuration into an Add form with an auto-incremented alias and clean stats.
  • Import from Clipboard (v): Paste a raw ssh user@host -p 2222 -i ... command line directly into a structured form with automatic OpenSSH flag parsing.
  • SCP Command Helper (P): Interactive upload/download SCP command builder with automatic client capability detection (OpenSSH -s SFTP protocol vs legacy quoting, POSIX vs Windows PowerShell quoting) and 1-click clipboard copy.
  • System SFTP Integration (F): Launch the system sftp client directly for the selected host and cleanly return to lazyssh upon exit.
  • Port Forwarding Wizard (f / x): Setup Local (-L), Remote (-R), or Dynamic SOCKS5 (-D) tunnels with forward-only or forward+SSH modes, and stop active tunnels with one keypress.
  • Active Session Monitor: Auto-refreshing read-only panel displaying currently active local SSH processes.
  • Ping Health Check (g): Check host reachability on demand using actual configured target parameters.

📷 Screenshots

Click to expand / collapse screenshots

📋 Main Host Management & Active Sessions

Host list view and active sessions

Browse configured hosts, inspect real-time effective SSH options, monitor active local sessions, and view source config markers.


🔎 Intelligent Fuzzy Search

Fuzzy host search

Search across aliases, hostnames, usernames, and tags with smart relevance ranking.


➕ Tabbed Host Editor (5 Categories)

Tabbed host editor

Full control over OpenSSH options organized into Basic, Connection, Forwarding, Authentication, and Advanced tabs.


🔐 Instant SSH Connection & SCP Helper

SSH connection and command helpers

Launch direct sessions, build robust SCP commands, or open SFTP file management with zero friction.


🚀 Startup Loader

Startup screen

Clean, asynchronous startup loading your complete Include hierarchy.


📦 Installation

Option 1: mise (Recommended)

If you use mise-en-place, install lazyssh directly from GitHub Releases:

# Install and activate globally
mise use -g github:urzeye/lazyssh@latest

# Verify installation
lazyssh --version

To pin a specific version:

mise use -g github:urzeye/lazyssh@v2026.6.4

Option 2: Go Install

If you have Go installed (Go 1.22+):

go install github.com/urzeye/lazyssh/cmd@latest

Ensure your $GOPATH/bin or $HOME/go/bin is in your $PATH.

Option 3: Pre-compiled Binaries

Download pre-compiled binaries for your operating system and architecture from the GitHub Releases page:

OS Architecture Archive Format
Linux x86_64 (amd64), aarch64 (arm64), i386, armv6 .tar.gz
macOS Apple Silicon (arm64), Intel (amd64) .tar.gz
Windows x86_64 (amd64), arm64, i386 .zip

Unpack the archive and move the lazyssh binary into your system PATH (e.g. /usr/local/bin on Linux/macOS).

Option 4: Build from Source

# Clone repository
git clone https://github.com/urzeye/lazyssh.git
cd lazyssh

# Build binary into ./bin/lazyssh
make build

# Or run directly
make run

⚡ Quick Start & CLI Workflows

# 1. Open the interactive TUI (defaults to ~/.ssh/config)
lazyssh

# 2. Launch directly with a fuzzy search filter
lazyssh prod
lazyssh --filter dev

# 3. Headless direct connect (bypasses the TUI, preserves SSH exit codes)
lazyssh -c production-server

# 4. Connect and automatically exit the TUI when the session ends
lazyssh --exit-after-session

# 5. Combine custom config file with headless connection
lazyssh --sshconfig ~/.ssh/work_config -c bastion

# 6. Safe read-only mode (prevents any config modifications)
lazyssh --ssh-config-readonly
# or via environment variable:
export LAZYSSH_SSH_CONFIG_READONLY=1
lazyssh

🧭 Deep Dive: Dotfiles & Managed Mode

The Problem

Power users often maintain their primary SSH configurations inside Git-tracked dotfile repositories (e.g. ~/.ssh/config is a symlink or contains shared company defaults). Using traditional SSH GUIs or TUIs can overwrite comments, break symlinks, or pollute version control with ad-hoc test hosts.

The Solution: Managed Mode

With lazyssh's Managed Mode, you can read from your root config hierarchy while directing all writes to a dedicated local file:

# ~/.ssh/config (Tracked in dotfiles git repo)
Include ~/.orbstack/ssh/config
Include ~/.ssh/config.d/*.conf
Include ~/.ssh/config.local      # <-- lazyssh writes exclusively here!

Host *
    ServerAliveInterval 60
    TCPKeepAlive yes

Run lazyssh with managed mode enabled:

lazyssh \
  --sshconfig ~/.ssh/config \
  --managed-mode \
  --managed-sshconfig ~/.ssh/config.local
~/.ssh/config (Root Config / Dotfiles Repo)
 ├── Include ~/.orbstack/ssh/config  [Read-Only: marked with [inc]]
 ├── Include ~/.ssh/config.d/*.conf  [Read-Only: marked with [inc]]
 └── Include ~/.ssh/config.local     [Writable Target: adds/edits land here]

What Managed Mode Guarantees:

  1. Full Visibility: All hosts across all included files are parsed and listed.
  2. Safe Isolation: Adding a host, editing, or deleting only modifies ~/.ssh/config.local.
  3. Accidental Edit Guard: Attempting to edit or delete a host defined in an external or root file is blocked with a clear warning indicating its source file.
  4. Cascading Inheritance: Global settings from Host * in ~/.ssh/config cascade seamlessly into the UI's effective value display.
  5. OpenSSH Consistency: Connections always use --sshconfig ~/.ssh/config, ensuring 100% fidelity with native ssh command behavior.

🛡️ Safe Writes & Automatic Backups

lazyssh treats your SSH configuration with surgical precision:

  • Atomic Saves: Config changes are written to a temporary sibling file first and then atomically renamed (os.Rename), eliminating partial-write corruptions.
  • Symlink Protection: If your config file is a symlink, lazyssh resolves the target path and updates the destination file directly, preserving the symlink untouched.
  • Baseline Backup: Before the very first modification to a config file, a sibling .original.backup is created (e.g. config.original.backup).
  • Rolling Backups: Subsequent writes automatically generate timestamped backups (e.g. config-20261118-190516-lazyssh.backup). Up to 10 rolling backups are retained automatically with older files pruned.
  • Portable IdentityFile Normalization: Keys located inside the user's home directory are normalized to ~/.ssh/... relative syntax, avoiding machine-specific absolute path issues when syncing configs across devices.
  • Minimal Diff Updates: Only targeted host blocks are touched; your blank lines, indentation, comments, and untouched directives remain intact.

⌨️ Keyboard Shortcuts Reference

Navigation & Focus

Key Action
0 / / Focus / Toggle collapsible search bar
1 Focus server list
2 Focus server details panel
↑ ↓ / j k Navigate through server list
Enter Connect via SSH to the selected server
q Quit lazyssh

Server Management

Key Action
a Add a new server
C Clone selected server into a prefilled Add form
v Import SSH command from clipboard into Add form
e Edit selected server (disabled for read-only / included hosts)
d Delete selected server with confirmation dialog
t Edit server tags (saved to metadata without rewriting config)
p Pin / unpin server to the top of the list

Command Generation, SFTP & Tunnels

Key Action
c Copy SSH connection command to system clipboard
h Copy server host alias to system clipboard
P Open interactive SCP command generator (upload / download)
F Launch system sftp client for selected server
f Open interactive Port Forwarding wizard (Local, Remote, Dynamic)
x Stop active port forwarding tunnel for selected server
g Ping selected server to test reachability
r Refresh background data (servers and active sessions)

View & Preferences

Key Action
s Switch sort field (Alias ↔ Last Connection Time)
S Reverse current sort direction (Ascending ↔ Descending)
T Toggle Color Theme (Dark ↔ Light) with persisted preference

Inside Host Editor Forms

Key Action
Ctrl+H / Ctrl+← Switch to Previous tab
Ctrl+L / Ctrl+→ Switch to Next tab
Ctrl+S Save host configuration
Esc Cancel / Return to main view

🔐 Security Architecture

lazyssh is designed with strict security boundaries:

  • Zero Credential Storage: lazyssh never stores, inspects, or transmits private keys, passphrases, or passwords.
  • OpenSSH Passthrough: All SSH connections, port tunnels, and SFTP sessions are executed by delegating directly to the system OpenSSH binary (ssh, sftp). Existing ssh-agent keys and hardware tokens (YubiKey/FIDO2) work out-of-the-box.
  • Permission Safety: Writes respect original file permissions (0600 / 0644) to guarantee OpenSSH permission checks never fail.
  • Syntax Validation: Pasted SSH commands and imported flags are sanitized and validated against OpenSSH specifications before being accepted into forms.

🤝 Contributing

Contributions, bug reports, and suggestions are warmly welcome!

# 1. Fork and clone the repository
git clone https://github.com/urzeye/lazyssh.git
cd lazyssh

# 2. Run quality checks and tests
make test
make lint

# 3. Create a feature branch and submit a PR
git checkout -b feat/my-new-feature

📄 License & Attribution

This project is licensed under the Apache License 2.0.

Acknowledgments & Upstream Credits

Maintained with ❤️ by urzeye and community contributors.

About

⚡ Keyboard-driven SSH manager TUI with recursive Include, dotfiles-friendly managed mode, atomic backups & effective config display.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Contributors

Languages