mirivlad
/
sshkeeper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
sshkeeper/README.md

8.0 KiB
Raw Blame History

sshkeeper

sshkeeper is a Linux console manager for SSH profiles, secrets, and quick OpenSSH launches. It does not replace OpenSSH; it keeps connection metadata in a local SQLite database, keeps passwords/passphrases in an encrypted vault, and starts the system ssh client with the right options.

sshkeeper is not Ansible

sshkeeper does not configure servers, push files, or manage infrastructure. It is an SSH connection manager: it remembers how to reach your servers (bastions, jump chains, port forwards) and launches the system ssh client. Think of it as a smart ~/.ssh/config with a TUI, encrypted secrets, and port forwarding management.

Features

  • Bubble Tea TUI for daily interactive use.
  • CLI commands for scripting and quick edits.
  • Encrypted vault for SSH passwords and key passphrases.
  • Password and key-passphrase auth through a PTY prompt handler, without putting secrets in command-line arguments.
  • Key, SSH-agent, password, and key+passphrase auth modes.
  • Routes / ProxyJump — manage bastion hosts and jump chains with human-readable display.
  • Port forwarding — local, remote, and dynamic (SOCKS) forwards with OpenSSH preview.
  • Tunnel mode — ssh -N for forward-only sessions.
  • Groups, tags, command templates, search, and OpenSSH config generation.
  • Import from ~/.ssh/config.

Install

Install from release

Download the latest Linux x86_64 release from:

https://github.com/mirivlad/sshkeeper/releases/latest

tar -xzf sshkeeper_v0.1.0_linux_amd64.tar.gz
chmod +x sshkeeper-linux-amd64
sudo install -m 0755 sshkeeper-linux-amd64 /usr/local/bin/sshkeeper
sshkeeper

Build from source

git clone https://github.com/mirivlad/sshkeeper.git
cd sshkeeper
go build -o ~/.local/bin/sshkeeper .

Requirements: Go 1.25+, Linux x86_64, system OpenSSH.

First Run

Run the TUI or any command. On the first run, sshkeeper creates its config, database, and vault, then asks for a master password.

sshkeeper

You can also initialize explicitly:

sshkeeper init

Common CLI Commands

# Add profiles with flags
sshkeeper add web --host 10.0.0.10 --user deploy --auth key
sshkeeper add prod --host 10.0.0.20 --user root --auth password
sshkeeper add bastion --host bastion.example.org --user admin --auth key_passphrase --identity-file ~/.ssh/id_rsa

# Or use the interactive CLI prompt
sshkeeper add

# Inspect profiles
sshkeeper list
sshkeeper show web
sshkeeper search prod

# Connect and test
sshkeeper connect web
sshkeeper c web
sshkeeper test web
sshkeeper run web "uptime"

# Groups and templates
sshkeeper group list
sshkeeper template list
sshkeeper template add uptime "uptime"
sshkeeper run-template web uptime

# Tags and startup command
sshkeeper add web --host 10.0.0.10 --user deploy --auth key --tags prod,web --startup-command "tmux attach -t ops"
sshkeeper edit web --tags prod,web --startup-command "tmux attach -t ops"

# OpenSSH config
sshkeeper ssh-config generate
sshkeeper ssh-config install-include

## Routes, Tunnels, and Port Forwards

### Jump host (single bastion)

```bash
sshkeeper route set web --jumps bastion
sshkeeper route show web
# Route: bastion → web@10.0.0.10:22
# Mode: via
# ProxyJump: bastion

Jump chain (multiple hops)

sshkeeper route set prod --jumps bastion,dmz-gw
sshkeeper route show prod
# Route: bastion → dmz-gw → prod@10.0.0.20:22
# Mode: chain
# ProxyJump: bastion,dmz-gw

Local port forward

sshkeeper forward add web --type local --local-port 8080 --remote-addr internal.web --remote-port 80
sshkeeper forward list web
# [1] -L 0.0.0.0:8080:internal.web:80

Dynamic SOCKS proxy

sshkeeper forward add bastion --type dynamic --local-port 1080
sshkeeper forward list bastion
# [1] -D 0.0.0.0:1080

Forward-only tunnel (ssh -N)

sshkeeper tunnel web --forward-only
# Starting tunnel to web with 1 forward(s)...
# Tunnel mode (ssh -N). Press Ctrl+C to exit.

Session with forwards

sshkeeper tunnel web
# Starts SSH session with all configured forwards active.

Commands that only read profile metadata, such as list, show, search, config path, group list, and export, do not require the master password. Commands that need secrets ask for the master password in that process. Adding key or agent profiles does not require unlocking the vault; adding password or key_passphrase profiles asks for the master password before storing the secret.

TUI

Running sshkeeper without arguments opens the TUI.

Screenshots

Main Window

sshkeeper main window

Edit Server

sshkeeper edit server form

sshkeeper group picker

Template Manager

sshkeeper template manager

Route and Forwarding

sshkeeper route screen

sshkeeper port forwards

Key Action
Enter Connect to selected server
Ctrl+R Pick and run a command template on the selected servers
Insert Select or unselect a server, then move to the next row
Ctrl+A Add server
Ctrl+E Edit server
Ctrl+D Delete server
Ctrl+T Test connection
Ctrl+F Search
Ctrl+G Manage tags
Ctrl+P Manage global command templates
Ctrl+W Manage port forwards for selected server
? / F1 Full help screen
Ctrl+X Action menu (delete, test, tags, vault)
Ctrl+Q / Ctrl+C Quit

Templates are global entities and can run on any server. Foreground template runs leave the TUI, show the SSH session in the terminal, and then return to the TUI. Background runs execute the command and show per-server output in a result screen.

In add/edit forms:

Key Action
Tab / Down Next field
Shift+Tab / Up Previous field
/ on Auth Method or Group Pick from list
Enter Move to action / activate
Esc Back

Vault

The vault stores SSH passwords and key passphrases encrypted on disk.

  • Cipher: XChaCha20-Poly1305.
  • KDF: Argon2id, currently 64 MiB memory, 3 iterations.
  • Existing legacy vault files remain readable.
  • Unlock state is process-local. sshkeeper vault unlock verifies the master password, but it does not keep future shell commands unlocked.

Useful commands:

sshkeeper vault status
sshkeeper vault unlock
sshkeeper vault list
sshkeeper vault delete <alias> [ssh_password|key_passphrase]
sshkeeper vault change-password

vault list, vault delete, and vault change-password ask for the master password themselves because they need to decrypt the vault in the current process.

Security

sshkeeper stores SSH passwords and key passphrases in an encrypted local vault and avoids passing secrets through command-line arguments. The project has not had an independent security audit; review the implementation and threat model before using it for high-risk environments.

Data Locations

sshkeeper uses XDG-style app directories:

Data Default path
Config ~/.config/sshkeeper/config.toml
Database ~/.local/share/sshkeeper/sshkeeper.db
Vault ~/.local/share/sshkeeper/vault.bin
Generated OpenSSH config ~/.ssh/config.d/sshkeeper.conf

If XDG_CONFIG_HOME or XDG_DATA_HOME are set, sshkeeper stores data under $XDG_CONFIG_HOME/sshkeeper and $XDG_DATA_HOME/sshkeeper.

Build And Test

go test ./...
go build -o bin/sshkeeper .

bin/ is ignored by git.

Project Layout

sshkeeper/
├── cmd/                 # Cobra CLI commands and TUI launcher
├── internal/config/     # XDG paths and config loading
├── internal/db/         # SQLite migrations and CRUD
├── internal/model/      # Domain models
├── internal/ssh/        # OpenSSH command building, PTY prompt handling
├── internal/tui/        # Bubble Tea UI
├── internal/vault/      # Encrypted vault
└── main.go

License

MIT. See LICENSE.