Operate remote servers over SSH without exposing credentials

sshepherd is a Bun/TypeScript CLI for operating remote servers through named SSH aliases, database targets, and deployment recipes. It covers server health checks, Docker and systemd service control, log inspection, remote configuration edits, file operations, security checks, and declarative deployment. Its command surface contains nine groups: hosts, check, logs, services, deploy, config, db, files, and security.

Every operation uses the system OpenSSH executable through one transport path. The caller supplies a name rather than a hostname, username, port, password, or private key. Connection details resolve outside the process, and the CLI returns a typed Envelope with ok, alias, data, and error fields. JSON is the default output; --pretty produces a table or key-value view for human inspection. The response structure echoes the alias without exposing connection fields or a raw terminal dump.

Use this skill to inspect disk, memory, CPU, listening ports, and OOM history on an authorized server, or to list, inspect, restart, and examine logs for remote services. It also applies to approved configuration changes, recipe-based deployments, read-only PostgreSQL introspection, and SSH or security posture checks. PostgreSQL support is intentionally read-only; it is not a database modification workflow.

The skill requires the system OpenSSH client and targets declared outside the agent's prompts. It cannot connect to an unconfigured host. Missing inputs, permissions, or safety boundaries require clarification, and the workflow does not replace environment-specific validation, testing, or expert review. Broader CI/CD or infrastructure-as-code work is outside the described SSH operations surface.

SSH aliases are configured in ~/.ssh/config, PostgreSQL targets in ~/.config/sshepherd/targets.toml, and deployment recipes in TOML files. OpenSSH resolves HostName, User, Port, and IdentityFile internally. Database target names identify how to reach psql on a host; psql runs inside the target container using authentication already established remotely through peer, trust, or .pgpass.

The documented command shape is:

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

The executable is not supplied by this skill repository. A user must install or build a reviewed upstream release outside the workspace and provide its explicit absolute path. Before use, that path must be verified as an executable regular file rather than a symlink. The workflow forbids discovering and executing a repository-local dist/sshepherd binary. Group and action help then expose available flags.

Health operations return structured measurements, log actions return requested log information, and database introspection returns items such as table listings. Mutating actions, including service restarts, configuration writes, and deployments, require the explicit --yes confirmation flag. A mutation that does nothing should be checked for that required confirmation.

The tool relies on trusted system OpenSSH rather than ssh2 or a custom SSH implementation. Target registration uses named setup actions instead of inline connection details. A separate SSH-alias installation action opens a one-shot local browser form for human-only password entry. The agent may trigger and wait for that form, but must never see, log, or relay the password or read private key material.