simtabi/ssh-manager

Profile-based SSH key and config lifecycle manager: one manifest is the source of truth, and ~/.ssh is reproducible output.

A single static binary (sshmgr) with no runtime dependencies. macOS, Linux and Windows are all first-class; OpenSSH is the only requirement.

Install

curl -fsSL https://raw.githubusercontent.com/simtabi/ssh-manager/main/src/scripts/install.sh | bash
sshmgr doctor

Windows: irm https://raw.githubusercontent.com/simtabi/ssh-manager/main/src/scripts/install.ps1 | iex. Also go install github.com/simtabi/ssh-manager/src/v3/cmd/sshmgr@latest, or a binary from Releases. Every path, and where per-user state lives, is in docs/installation.md.

Quick start guide and usage

Getting started

init seeds an empty manifest; add a profile and a host before reconcile mints anything:

sshmgr init                  # create ~/.config/ssh-manager (dirs, perms, seed files)
sshmgr profile add work
sshmgr host add work gh -H github.com -u git      # or edit manifest.json directly
sshmgr import ~/.ssh/config                        # or onboard an existing setup

Usage

Build ~/.ssh from the manifest:

sshmgr reconcile --dry-run   # preview: what would be minted, what would be written
sshmgr reconcile             # build ~/.ssh from the manifest
sshmgr config check          # confirm the file matches the manifest (exit != 0 on drift)

Get a key onto its target:

sshmgr deploy work_gh-ed25519    # ssh-copy-id, gh, glab, a REST API, or manual
sshmgr validate                  # every keypair parses and the halves match

The full walkthrough is in Getting started; everything else is in the documentation index.

Documentation

Guides

• Installation — install paths, requirements, and where per-user state lives.
• Getting started — first run, from init to a deployed key.
• Configuration — the manifest, profiles, hosts, .env, environment variables.
• Architecture — packages, key flows, and why the v2 layout is what it is.
• Release — the tag-driven GoReleaser flow.

Reference

• Feature catalog — every command, what it does, and how it is tested.
• doctor — what it checks, --fix, --json, --strict.
• deploy — installing a public key on its target.
• providers — the adapter catalog and how to extend it.
• VPS keys — cloud account keys and server keys.
• rotate — zero-downtime staged rotation and rollback.
• expiry — rotation age and scheduled reminders.
• knownhosts — pinning host keys into the trust store.
• git — checkouts' GitHub remotes in profile SSH, plain SSH or HTTPS mode.
• vm — local VMs as hosts, addressed through their hypervisor.
• net — reachability and VPN-gated hosts.
• validate — keypair integrity checks.
• bundle — encrypted backup and restore.
• recover — break-glass when you are locked out.
• tui — the interactive menu.

Recipes

• Two GitHub accounts on one machine — one hostname, two identities, neither able to act as the other.
• Keep keys in 1Password — private keys generated and rotated inside a vault; only the .pub on disk.
• Use a GitHub machine user — one bot key with read access to every org repo, rotated in one command.
• Group profiles into categories — internal, clients, others: one directory and one config file each.
• Switch checkouts to profile SSH — each owner's own key, every URL proven before it is written.
• Use a local VM as a devbox — reach a VM by name whatever its IP, and point Docker at it.
• Onboard an existing ~/.ssh — bring a hand-built setup under management without regenerating anything.
• Rotate a key with no downtime — stage, verify, commit; and how to step back.
• Rotate or repair many keys at once — a category or everything in one batch, and rebuilding .pub files.
• Work against a sandbox — exercise every verb without touching your real ~/.ssh.
• Back up, and restore onto a new machine — the only path that recovers the same keys.
• Recover from a locked-out server — break-glass with no working SSH.
• Run it in CI — non-interactive, sandboxed, failing loudly.

Community

Contributing · Security policy · Code of conduct · Changelog

License

MIT © Simtabi LLC — see LICENSE.