sshepherd

name: sshepherd
description: “Zero-knowledge SSH ops CLI — server health checks, docker/systemd control, log tailing, Postgres introspection, and declarative deploys, without ever exposing credentials to the agent.”
category: devops
risk: critical
source: community
source_repo: Antheurus/sshepherd
source_type: community
date_added: “2026-07-15”
author: Antheurus
tags: [ssh, devops, cli, server-ops, postgres, deploy, zero-knowledge]
tools: [claude, cursor, gemini, codex]
license: “MIT”
license_source: “https://github.com/Antheurus/sshepherd/blob/main/LICENSE”
plugin:
targets:
codex: blocked
claude: blocked
setup:
type: manual
summary: “Requires a separately installed, user-approved sshepherd executable at an explicit absolute path.”
docs: SKILL.md

概述

sshepherd是一个编译好的 Bun/TypeScript CLI，让代理可以通过 SSH 操作真实的远程服务器——健康检查、docker/systemd 服务控制、日志跟踪、配置文件编辑、只读 Postgres 内省和声明式部署——而永远不会看到密码、私钥、主机名、用户名或端口。每个操作都通过单一传输路径调用系统的ssh二进制文件，并返回相同的类型化Envelope<T>（ok、alias、data、error），绝不会返回原始终端输出。代理只传递一个名称——ssh 别名、Postgres 目标或部署配方——该名称完全在进程外部解析。

使用本技能的时机

当需要检查远程服务器的健康状况（磁盘、内存、CPU、端口、OOM 历史）而不向代理提供 SSH 凭据时使用。
当处理远程 docker 或 systemd 服务——列出、检查或重启它们——或跟踪其日志时使用。
当用户要求读取或编辑远程配置文件、从命名配方运行声明式部署、以只读方式内省远程 Postgres 数据库或审计服务器上的 SSH/安全态势时使用。

工作原理

步骤 1：一次性声明目标，在任何提示之外

每个连接细节都预先声明，绝不会出现在命令行上：~/.ssh/config中的 ssh 别名、~/.config/sshepherd/targets.toml中的 Postgres 目标、配方 TOML 文件中的部署配方。OpenSSH 在内部解析真实的HostName/User/Port/IdentityFile。

步骤 2：按名称调用组 + 操作

此仓库不附带sshepherd可执行文件。用户必须在当前工作区之外安装或构建经过审查的上游版本，并提供其明确的绝对路径。使用前验证它是可执行常规文件，而不是符号链接。切勿自动发现或执行正在操作的仓库中的./dist/sshepherd。

sshepherd <group> <action> [positionals...] [--flag value]

九个命令组——hosts、check、logs、services、deploy、config、db、files、security——共 52 个操作。默认以 JSON 格式输出到 stdout；添加--pretty以获得人类可读的表格/键值视图。响应只会回显给它的alias——响应类型中结构上不存在主机/用户/端口/IP 字段。

步骤 3：发现命令表面

"/absolute/path/to/sshepherd"--help# 列出组"/absolute/path/to/sshepherd"check--help# 列出某个组的操作 + 标志

示例

示例 1：服务器健康概览

"/absolute/path/to/sshepherd"check overview lms-server

返回一个 JSON 信封，包含lms-server别名后面主机的磁盘、内存、CPU、监听端口和 OOM 历史——代理永远不会知道主机的地址。

示例 2：重启 docker 服务并跟踪其日志

"/absolute/path/to/sshepherd"services restart lms-server--nameapi"/absolute/path/to/sshepherd"logstaillms-server--nameapi--lines100

示例 3：只读 Postgres 内省

"/absolute/path/to/sshepherd"db tables prod

prod是一个 pg 目标名称，它解析为在主机上如何到达psql——绝不是数据库密码。psql在目标容器内运行，通过远程已有的 peer/trust/.pgpass进行认证。

最佳实践

✅ 提前在~/.ssh/config/targets.toml/ 配方 TOML 中声明每个别名/目标/配方——绝不内联连接细节。
✅ 只向 CLI 传递名称（别名、pg 目标、配方）；让 OpenSSH 负责认证。
✅ 使用--pretty进行人工审查，默认 JSON 输出用于机器解析。
❌ 不要尝试向命令中注入主机名、用户、端口或密码——CLI 没有这些字段。
❌ 不要使用ssh2npm 库或手工编写的 SSH；全部意义在于委托给受信任的系统ssh二进制文件。

限制

本技能不能替代特定环境的验证、测试或专家审查。
如果缺少所需输入、权限或安全边界，请停下来并要求澄清。
需要系统 OpenSSH 客户端和预先声明的别名/目标/配方；它无法连接到未在代理外部配置的主机。
按设计，Postgres 访问是只读内省。

安全与安全说明

零知识凭据模型：代理永远不会看到密码、私钥、主机名、用户名或端口。它只传递 ssh 别名、pg 目标名称或配方名称；真实的连接元组由 OpenSSH 在进程外部解析，每个响应只回显别名。
绝不读取私钥材料。认证完全发生在 OpenSSH 自己受信任的代码路径内。
变更确认门禁：破坏性/变更性操作（服务重启、配置写入、部署）需要显式的--yes确认标志。
仅限人工输入凭据：单独的setup ssh-alias install操作会打开一个一次性本地浏览器表单，只有人类才能在其中输入密码——代理可以触发并等待它，但永远不会看到、记录或转发密码。
环境预期：对你有权操作的主机运行。

常见陷阱

问题：尝试直接向命令传递主机名或密码。
解决方案：先注册目标（setup ssh-alias register/setup db-target），然后只按名称引用它。
问题：变更性操作返回但不执行任何操作。
解决方案：添加--yes确认标志——变更操作按设计受门禁保护。