sshepherd
Overview
sshepherd is a compiled Bun/TypeScript CLI that lets an agent operate a real remote server over SSH — health checks, docker/systemd service control, log tailing, config file edits, read-only Postgres introspection, and declarative deploys — without ever seeing a password, private key, hostname, username, or port. Every operation shells out to the system ssh binary through a single transport path and returns the same typed Envelope<T> (ok, alias, data, error), never a raw terminal dump. The agent passes only a name — an ssh alias, a Postgres target, or a deploy recipe — that resolves entirely outside the process.
When to Use This Skill
- Use when you need to check a remote server's health (disk, memory, CPU, ports, OOM history) without handing the agent SSH credentials.
- Use when working with remote docker or systemd services — listing, inspecting, or restarting them — or tailing their logs.
- Use when the user asks to read or edit a remote config file, run a declarative deploy from a named recipe, introspect a remote Postgres database read-only, or audit SSH/security posture on a box.
How It Works
Step 1: Declare targets once, outside any prompt
Every connection detail is declared ahead of time and never appears on the command line: ssh aliases in ~/.ssh/config, Postgres targets in ~/.config/sshepherd/targets.toml, deploy recipes in recipe TOML files. OpenSSH resolves the real HostName/User/Port/IdentityFile internally.
Step 2: Invoke a group + action by name
This repository does not ship the sshepherd executable. The user must install or build a reviewed upstream release outside the current workspace and provide its explicit absolute path. Verify it is an executable regular file, not a symlink, before use. Never auto-discover or execute ./dist/sshepherd from the repository being operated on.
sshepherd <group> <action> [positionals...] [--flag value]
Nine command groups — hosts, check, logs, services, deploy, config, db, files, security — 52 ops total. Output is JSON to stdout by default; add --pretty for a human-readable table/key-value view. The response only ever echoes back the alias it was given — there is no host/user/port/ip field anywhere in the response type, structurally.
Step 3: Discover the command surface
"/absolute/path/to/sshepherd" --help # list groups
"/absolute/path/to/sshepherd" check --help # list actions + flags for one group
Examples
Example 1: Server health overview
"/absolute/path/to/sshepherd" check overview lms-server
Returns a JSON envelope with disk, memory, CPU, listening ports, and OOM history for the host behind the lms-server alias — the agent never learns the host's address.
Example 2: Restart a docker service and tail its logs
"/absolute/path/to/sshepherd" services restart lms-server --name api
"/absolute/path/to/sshepherd" logs tail lms-server --name api --lines 100
Example 3: Read-only Postgres introspection
"/absolute/path/to/sshepherd" db tables prod
prod is a pg-target name that resolves to how to reach psql on a host — never a database password. psql runs inside the target container, authenticated by peer/trust/.pgpass already on the remote.
Best Practices
- ✅ Declare every alias/target/recipe ahead of time in
~/.ssh/config / targets.toml / recipe TOML — never inline connection details.
- ✅ Pass only names (alias, pg-target, recipe) to the CLI; let OpenSSH own authentication.
- ✅ Use
--pretty for human review and default JSON output for machine parsing.
- ❌ Don't try to inject a hostname, user, port, or password into a command — the CLI has no field for them.
- ❌ Don't reach for the
ssh2 npm library or hand-rolled SSH; the whole point is delegating to the trusted system ssh binary.
Limitations
- This skill does not replace environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, or safety boundaries are missing.
- Requires the system OpenSSH client and pre-declared aliases/targets/recipes; it cannot connect to a host that has not been configured outside the agent.
- Postgres access is read-only introspection by design.
Security & Safety Notes
- Zero-knowledge credential model: the agent never sees a password, private key, hostname, username, or port. It only ever passes an ssh alias, a pg-target name, or a recipe name; the real connection tuple is resolved by OpenSSH outside the process, and every response echoes back only the alias.
- Never reads private key material. Authentication happens entirely inside OpenSSH's own trusted code path.
- Confirmation gate on mutations: destructive/mutating actions (service restart, config write, deploy) require an explicit
--yes confirm flag.
- Human-only credential entry: the separate
setup ssh-alias install action opens a one-shot local browser form that only a human can type a password into — the agent can trigger and wait on it but never sees, logs, or relays the password.
- Environment expectation: run against hosts you are authorized to operate.
Common Pitfalls
- Problem: Trying to pass a hostname or password directly to a command.
Solution: Register the target first (
setup ssh-alias register / setup db-target), then reference it only by name.
- Problem: A mutating action returns without doing anything.
Solution: Add the
--yes confirm flag — mutations are gated by design.
Related Skills
@devops-automation - When you need broader CI/CD or infrastructure-as-code automation beyond SSH ops.
1---2name: sshepherd3description: "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."4category: devops5risk: critical6source: community7source_repo: Antheurus/sshepherd8source_type: community9date_added: "2026-07-15"10author: Antheurus11tags: [ssh, devops, cli, server-ops, postgres, deploy, zero-knowledge]12tools: [claude, cursor, gemini, codex]13license: "MIT"14license_source: "https://github.com/Antheurus/sshepherd/blob/main/LICENSE"15plugin:16 targets:17 codex: blocked18 claude: blocked19 setup:20 type: manual21 summary: "Requires a separately installed, user-approved sshepherd executable at an explicit absolute path."22 docs: SKILL.md23metadata:24 source: https://skillmd.com/skills/mhassan0000/sshepherd25---2627# sshepherd2829## Overview3031`sshepherd` is a compiled Bun/TypeScript CLI that lets an agent operate a real remote server over SSH — health checks, docker/systemd service control, log tailing, config file edits, read-only Postgres introspection, and declarative deploys — without ever seeing a password, private key, hostname, username, or port. Every operation shells out to the system `ssh` binary through a single transport path and returns the same typed `Envelope<T>` (`ok`, `alias`, `data`, `error`), never a raw terminal dump. The agent passes only a *name* — an ssh alias, a Postgres target, or a deploy recipe — that resolves entirely outside the process.3233## When to Use This Skill3435- Use when you need to check a remote server's health (disk, memory, CPU, ports, OOM history) without handing the agent SSH credentials.36- Use when working with remote docker or systemd services — listing, inspecting, or restarting them — or tailing their logs.37- Use when the user asks to read or edit a remote config file, run a declarative deploy from a named recipe, introspect a remote Postgres database read-only, or audit SSH/security posture on a box.3839## How It Works4041### Step 1: Declare targets once, outside any prompt4243Every connection detail is declared ahead of time and never appears on the command line: ssh aliases in `~/.ssh/config`, Postgres targets in `~/.config/sshepherd/targets.toml`, deploy recipes in recipe TOML files. OpenSSH resolves the real `HostName`/`User`/`Port`/`IdentityFile` internally.4445### Step 2: Invoke a group + action by name4647This repository does not ship the `sshepherd` executable. The user must install or build a reviewed upstream release outside the current workspace and provide its explicit absolute path. Verify it is an executable regular file, not a symlink, before use. Never auto-discover or execute `./dist/sshepherd` from the repository being operated on.4849```50sshepherd <group> <action> [positionals...] [--flag value]51```5253Nine command groups — `hosts`, `check`, `logs`, `services`, `deploy`, `config`, `db`, `files`, `security` — 52 ops total. Output is JSON to stdout by default; add `--pretty` for a human-readable table/key-value view. The response only ever echoes back the `alias` it was given — there is no host/user/port/ip field anywhere in the response type, structurally.5455### Step 3: Discover the command surface5657```bash58"/absolute/path/to/sshepherd" --help # list groups59"/absolute/path/to/sshepherd" check --help # list actions + flags for one group60```6162## Examples6364### Example 1: Server health overview6566```bash67"/absolute/path/to/sshepherd" check overview lms-server68```6970Returns a JSON envelope with disk, memory, CPU, listening ports, and OOM history for the host behind the `lms-server` alias — the agent never learns the host's address.7172### Example 2: Restart a docker service and tail its logs7374```bash75"/absolute/path/to/sshepherd" services restart lms-server --name api76"/absolute/path/to/sshepherd" logs tail lms-server --name api --lines 10077```7879### Example 3: Read-only Postgres introspection8081```bash82"/absolute/path/to/sshepherd" db tables prod83```8485`prod` is a pg-target name that resolves to *how* to reach `psql` on a host — never a database password. `psql` runs inside the target container, authenticated by peer/trust/`.pgpass` already on the remote.8687## Best Practices8889- ✅ Declare every alias/target/recipe ahead of time in `~/.ssh/config` / `targets.toml` / recipe TOML — never inline connection details.90- ✅ Pass only names (alias, pg-target, recipe) to the CLI; let OpenSSH own authentication.91- ✅ Use `--pretty` for human review and default JSON output for machine parsing.92- ❌ Don't try to inject a hostname, user, port, or password into a command — the CLI has no field for them.93- ❌ Don't reach for the `ssh2` npm library or hand-rolled SSH; the whole point is delegating to the trusted system `ssh` binary.9495## Limitations9697- This skill does not replace environment-specific validation, testing, or expert review.98- Stop and ask for clarification if required inputs, permissions, or safety boundaries are missing.99- Requires the system OpenSSH client and pre-declared aliases/targets/recipes; it cannot connect to a host that has not been configured outside the agent.100- Postgres access is read-only introspection by design.101102## Security & Safety Notes103104- **Zero-knowledge credential model:** the agent never sees a password, private key, hostname, username, or port. It only ever passes an ssh alias, a pg-target name, or a recipe name; the real connection tuple is resolved by OpenSSH outside the process, and every response echoes back only the alias.105- **Never reads private key material.** Authentication happens entirely inside OpenSSH's own trusted code path.106- **Confirmation gate on mutations:** destructive/mutating actions (service restart, config write, deploy) require an explicit `--yes` confirm flag.107- **Human-only credential entry:** the separate `setup ssh-alias install` action opens a one-shot local browser form that only a human can type a password into — the agent can trigger and wait on it but never sees, logs, or relays the password.108- Environment expectation: run against hosts you are authorized to operate.109110## Common Pitfalls111112- **Problem:** Trying to pass a hostname or password directly to a command.113 **Solution:** Register the target first (`setup ssh-alias register` / `setup db-target`), then reference it only by name.114- **Problem:** A mutating action returns without doing anything.115 **Solution:** Add the `--yes` confirm flag — mutations are gated by design.116117## Related Skills118119- `@devops-automation` - When you need broader CI/CD or infrastructure-as-code automation beyond SSH ops.