Lib.rs

                         ███████╗███████╗███████╗██╗  ██╗
                         ██╔════╝██╔════╝██╔════╝██║  ██║
                         █████╗  ███████╗███████╗███████║
                         ██╔══╝  ╚════██║╚════██║██╔══██║
                         ███████╗███████║███████║██║  ██║
                         ╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝
                          Enterprise SSH Client for the Terminal

A pure-Rust SSH client with a rich TUI — concurrent sessions, real-time host monitoring, fleet management, and connection diagnostics. All from your terminal.

✨ Feature Highlights

🎬 Demo

7 key views: Dashboard → Session Terminal → Host Monitor → Split-Pane → Command Palette → File Browser → Port Forwarding

🖥️ TUI Preview

Dashboard — Hosts Tab

┌──────────────────────────────────────────────────────────────────────┐
│ ESSH │ [1] Sessions  [2] Hosts  [3] Fleet  [4] Config  │ ?:Help │ 14:32:07 │
├──────────────────────────────────────────────────────────────────────┤
│ Hosts (4)                                                            │
│                                                                      │
│  Name            Hostname             Port  User     Status          │
│ ─────────────────────────────────────────────────────────────────── │
│» web-prod-1      10.0.1.10            22    deploy   ● Online        │
│  web-prod-2      10.0.1.11            22    deploy   ● Online        │
│  db-primary      10.0.2.10            22    dba      ● Online        │
│  staging-1       10.0.3.5             2222  matt     ○ Unknown       │
│                                                                      │
├──────────────────────────────────────────────────────────────────────┤
│ Enter:Connect  Alt+1-9:Session  a:Add  /:Search  r:Refresh  q:Quit │
└──────────────────────────────────────────────────────────────────────┘

Session View — Active Terminal

┌──────────────────────────────────────────────────────────────────────┐
│ ESSH ── [1] web-prod-1  [2] db-primary  [3] staging-1 ── 14:33:42 │
├──────────────────────────────────────────────────────────────────────┤
│ deploy@web-prod-1:~$ htop                                          │
│                                                                      │
│  (full terminal output — colors, cursor, alternate screen)          │
│                                                                      │
│                                                                      │
│                                                                      │
├──────────────────────────────────────────────────────────────────────┤
│ RTT:12.3ms  ↑1.2KB/s  ↓48.5KB/s  Loss:0.0%  ●Excellent  Up:1h24m │
├──────────────────────────────────────────────────────────────────────┤
│ Alt+←→:Switch  Alt+s:Split  Alt+f:Files  Alt+p:Fwd  Alt+d:Detach  Alt+w:Close│
└──────────────────────────────────────────────────────────────────────┘

Host Monitor — Remote htop (Alt+m)

┌──────────────────────────────────────────────────────────────────────┐
│ ESSH ── [1] web-prod-1  [2] db-primary ────────────── 14:34:18     │
├──────────────────────────────────────────────────────────────────────┤
│ CPU   23.4%  ▁▂▃▃▂▅▃▂▁▂▃▄▅▆▅▃▂▁▂▃▃▂▁▁▂▃▅▆▅▃▂▂▃▃▂▁▂▃▃▂          │
│       ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 23%                  │
│       Core 0: ██████░░░░░  28%    Core 1: █████░░░░░░  19%          │
│       Core 2: ███████░░░░  31%    Core 3: █████░░░░░░  15%          │
│──────────────────────────────────────────────────────────────────── │
│ MEM   3.2G / 8.0G (40%)  Swap: 0B / 2.0G                          │
│       ▁▁▂▂▂▂▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃                  │
│       ████████████████░░░░░░░░░░░░░░░░░░░░░░░░ 40%                  │
│──────────────────────────────────────────────────────────────────── │
│ LOAD  0.82  0.64  0.55    UPTIME  14d 6h 32m                      │
│──────────────────────────────────────────────────────────────────── │
│ DISK  /               12.4G      7.6G ██████████ 62%                │
│       /data           84.2G    115.8G █████░░░░░ 42%                │
│──────────────────────────────────────────────────────────────────── │
│ NET   RX ▁▂▃▂▁▂▃▅▃▂▁ 48.5KB/s   TX ▁▁▁▂▁▁▁▂▁▁▁ 1.2KB/s          │
│──────────────────────────────────────────────────────────────────── │
│ Top Processes (by CPU)                                              │
│  PID     Name                      CPU%    MEM%    RSS              │
│  1842    node                       8.2     3.1    256M             │
│  2104    nginx                      4.1     0.8     64M             │
│  3921    postgres                   3.7     5.2    420M             │
│  1203    containerd                 2.1     1.4    112M             │
├──────────────────────────────────────────────────────────────────────┤
│ Esc:Terminal  s:Sort(→mem)  p:Pause  r:Refresh  ↑↓:Scroll          │
└──────────────────────────────────────────────────────────────────────┘

📦 Installation

From crates.io

cargo install essh

From Source

git clone https://github.com/matthart1983/essh.git
cd essh
cargo build --release
# Binary is at ./target/release/essh

🚀 Quick Start

# Launch the TUI dashboard
essh

# Direct connect to a host
essh connect user@hostname

# Connect with a specific key
essh connect user@hostname -i ~/.ssh/id_ed25519

# Connect with password authentication
essh connect user@hostname --password

# Import hosts from your SSH config
essh hosts import

# Run a command across a host group
essh run web-servers -- uptime

On first launch, ESSH creates ~/.essh/ with a default config.toml. Navigate the Hosts tab, select a host, and press Enter to connect.

⚙️ Configuration

ESSH uses a TOML config file at ~/.essh/config.toml. Initialize or edit it:

essh config init    # Create default config
essh config edit    # Open in $EDITOR
essh config show    # Print current config

Example Configuration

[general]
default_user = "deploy"
default_key = "~/.ssh/id_ed25519"
tofu_policy = "prompt"       # strict | prompt | auto
cache_ttl = "30d"
log_level = "info"

[diagnostics]
enabled = true
display = "status_bar"       # status_bar | overlay | hidden
export_format = "jsonl"
keepalive_interval = 15

[host_monitor]
enabled = true
cpu_interval = 1
memory_interval = 2
process_count = 15
history_samples = 60

[session]
auto_reconnect = true
reconnect_max_retries = 5
max_concurrent = 9
scrollback_lines = 10000
recording = false            # Set true to record sessions as asciicast v2
notification_patterns = []

[fleet]
probe_enabled = true
probe_interval = 60          # Seconds between TCP health probes
probe_timeout = 5            # Seconds before probe timeout
latency_history_samples = 30 # Sparkline data points per host

[security]
min_key_bits = 3072
allowed_ciphers = [
    "chacha20-poly1305@openssh.com",
    "aes256-gcm@openssh.com",
    "aes128-gcm@openssh.com",
]
allowed_kex = [
    "curve25519-sha256",
    "curve25519-sha256@libssh.org",
]

[audit]
enabled = true

# Define hosts
[[hosts]]
name = "web-prod-1"
hostname = "10.0.1.10"
port = 22
user = "deploy"
key = "~/.ssh/deploy_key"

[hosts.tags]
env = "production"
role = "web"

[[hosts]]
name = "db-primary"
hostname = "10.0.2.10"
user = "dba"
jump_host = "web-prod-1"

[hosts.tags]
env = "production"
role = "database"

# Define host groups (matched by tags)
[[host_groups]]
name = "web-servers"

[host_groups.match_tags]
role = "web"

[host_groups.defaults]
user = "deploy"
key = "~/.ssh/deploy_key"

Data Directory Structure

~/.essh/
├── config.toml          # Main configuration
├── cache.db             # SQLite host key & host cache
├── audit.log            # Structured JSON audit log
├── sessions/            # Per-session diagnostic logs (JSONL)
├── recordings/          # Session recordings (if enabled)
└── known_cas/           # Trusted CA certificates

⌨️ Keyboard Reference

Global (all views)

Dashboard

Session Terminal

Host Monitor

📋 CLI Reference

essh                                  Launch TUI dashboard
essh connect <user@host>              Direct SSH connection
  -p, --port <PORT>                     Port (default: 22)
  -i, --identity <FILE>                 Private key file
  --password                            Use password auth

essh hosts list [--tag key=value]     List cached hosts
essh hosts add <hostname>             Add host to cache
  -p, --port <PORT>                     Port (default: 22)
  -n, --name <NAME>                     Display name
  -u, --user <USER>                     Username
  --tag <key=value>                     Tag (repeatable)
essh hosts remove <hostname>          Remove host from cache
essh hosts import [path]              Import from SSH config
essh hosts health [--group <name>]    Run TCP health checks

essh keys list                        List cached keys
essh keys add <path> [-n name]        Add a private key
essh keys remove <name>               Remove a key

essh session list                     List session recordings
essh session replay <id>              Replay recorded session (asciicast)
                                        Space:pause  +/-:speed  q:quit

essh diag <session_id>                Show session diagnostics

essh run <group> -- <command>         Execute across a host group

essh config init                      Initialize default config
essh config edit                      Open config in $EDITOR
essh config show                      Print current config

essh audit tail [-l lines]            Show recent audit entries

🔐 Security

• TOFU Host Key Verification — Three policies: strict (reject unknown), prompt (ask user), auto (trust on first use). Host key fingerprints are cached in SQLite.
• Configurable Cipher Suites — Restrict allowed ciphers, key exchange algorithms, and MACs.
• Minimum Key Strength — Enforce minimum key bit length (default: 3072).
• Structured Audit Trail — Every connection attempt, auth result, and host key event is logged as structured JSON.

🏗️ Architecture & Tech Stack

Module Structure

src/
├── main.rs              # Entry point, TUI event loop, CLI dispatch, auto-reconnect
├── cli/                 # Clap command definitions
├── config/              # TOML config parsing & defaults (incl. [fleet] section)
├── ssh/                 # russh client, auth (key/password/agent), host key verification
├── session/             # Session state, VirtualTerminal (vt100), SessionManager
├── tui/                 # TUI views
│   ├── dashboard.rs     # Dashboard with 4 tabs, host search/filter bar
│   ├── session_view.rs  # Terminal renderer, tab bar, status bar
│   ├── host_monitor.rs  # CPU/MEM/Disk/Net/Process panels
│   ├── filebrowser_view.rs  # Two-pane file browser UI
│   ├── portfwd_view.rs      # Port forwarding manager panel
│   ├── help.rs          # Help overlay popup
│   ├── command_palette.rs  # Fuzzy-matched command palette (Ctrl+P)
│   └── widgets.rs       # Sparklines, bar gauges, formatters
├── filetransfer/        # Two-pane file browser, upload/download via SSH exec
├── fleet/               # Live fleet health — background TCP probes, latency tracking
├── notify/              # Background activity notification matching (regex)
├── portfwd/             # Port forwarding manager, local TCP proxy
├── recording/           # Session recording (asciicast v2) & replay
├── monitor/             # Remote host metric collection
│   ├── collector.rs     # SSH exec-based metric gathering
│   ├── parser.rs        # /proc & command output parsing
│   └── history.rs       # Sparkline ring buffers
├── diagnostics/         # Connection quality engine, JSONL logging
├── cache/               # SQLite host key & host/key CRUD
├── audit/               # Structured JSON audit logger
└── event.rs             # Async event handler (keys, ticks, SSH data)

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes with tests (cargo test)
4. Ensure formatting (cargo fmt) and lints pass (cargo clippy)
5. Open a pull request

Building & Testing

cargo build              # Debug build
cargo build --release    # Release build
cargo test               # Run all tests (154 tests)
cargo clippy             # Lint checks
cargo fmt --check        # Format check

📄 License

MIT — see LICENSE for details.

_{Built with 🦀 Rust — inspired by the Netwatch aesthetic}