SSH Server Manager

A local-first SSH host and credential manager for humans and AI agents. One CLI (serverctl) and a loopback-only web UI to add, import, test, and connect to your servers — with every password and passphrase stored in your operating system's native credential vault, never in a plaintext file.

简体中文说明 · Documentation · Security model · Website

🤖 Using an AI agent? The skill deploys to every agent on your machine in one line — dependencies, links, and health check included. See the agent deployment guide.

Why this exists

Most SSH managers make you choose between convenience and custody:

• Cloud-synced clients (subscription GUIs) keep your credentials on someone else's infrastructure.
• Plain ~/.ssh/config keeps you in control but handles no passwords, no vault, and gives AI coding agents an easy way to leak secrets.
• sshpass-style wrappers put passwords in files, env vars, or shell history.

SSH Server Manager is different by construction:

Quick start

git clone https://github.com/xiayh0107/servers-connect.git
cd servers-connect/ssh-server-manager
./scripts/bootstrap          # Windows: scripts\bootstrap.cmd
./scripts/serverctl doctor   # verify ssh, vault backend, and dependencies

Add a server and connect:

./scripts/serverctl credential add-password work-password   # prompts locally, stores in OS vault
./scripts/serverctl server add web1 --hostname web1.example.com --username deploy --credential work-password
./scripts/serverctl server test web1
./scripts/serverctl connect web1

Or import everything you already have:

./scripts/serverctl server import          # preview only
./scripts/serverctl server import --apply

Prefer a GUI? ./scripts/serverctl ui opens the local web interface in your browser with a one-time tokenized URL.

Features

• Connection profiles — alias, host, port, user, project/scenario tags, notes, ordered ProxyJump chains (with cycle detection).
• Three credential kinds — vault-backed passwords, private keys with optional vault-backed passphrases, and ssh-agent/OpenSSH defaults. Credentials are reusable across servers and protected against deletion while referenced.
• OpenSSH import — parses your ~/.ssh/config (following Include), resolves each literal alias with ssh -G, previews before applying.
• Managed config rendering — atomic, user-only-permission writes to ~/.ssh/ssh-server-manager.conf; your original config always loads last so unrelated defaults keep working.
• Connection testing — server test reports latency and a classified error code (authentication-failed, host-key-untrusted, timeout, dns-failed, …) and records history.
• Remote execution — serverctl exec alias -- cmd args, with --shell for pipelines, --stdin/--stdin-binary for streaming files, --reuse N for ControlMaster connection sharing (macOS/Linux), and --json for machine-readable results.
• Local web UI — manage servers and credentials, test connections, create/rename/delete tags and bulk-assign searchable hosts, choose system/light/dark themes, import config, browse remote directories read-only over SFTP, copy file references for an agent, and reveal a stored secret after passkey or master-password re-authentication. Connection status expires instead of staying green. Inspect or shut down a background instance with serverctl ui --status / --stop — no pid bookkeeping.
• Diagnostics — serverctl doctor checks ssh availability and version, SFTP availability, vault backend safety, database and config paths, and Python dependencies.

Platform support

Details and headless-server notes: docs/platforms.md. CI runs the full test suite on all three platforms.

For AI agents

This project ships as an Agent Skill (SKILL.md) so Claude Code, Codex, and other agents can manage servers safely: agents get structured JSON output and connection error classification, while the AskPass architecture keeps secrets out of the model's context by design.

The skill also encodes conversation UX, not just commands: agents answer inventory questions from a single --json call, hand interactive shells to your terminal and proxy follow-up commands through exec (connect refuses to run without a TTY instead of hanging), and clean up a background UI with serverctl ui --stop.

Deploy the skill with one line:

curl -fsSL https://raw.githubusercontent.com/xiayh0107/servers-connect/main/install.sh | sh

It links the skill into every detected agent (~/.claude/skills, ~/.codex/skills, …), installs dependencies, and runs doctor. Windows uses install.ps1. See docs/ai-agents.md.

Documentation

License

MIT