Operate remote servers over SSH without exposing credentials

sshepherd is a compiled Bun/TypeScript CLI that enables agents to operate real remote servers over SSH through a credential-free interface. It provides health checks, docker/systemd service control, log tailing, config file edits, read-only Postgres introspection, and declarative deploys - all without the agent ever seeing passwords, private keys, hostnames, usernames, or ports. Every operation shells out to the system ssh binary through a single transport path and returns the same typed Envelope<T> structure (ok, alias, data, error) instead of raw terminal dumps.

Use sshepherd when you need an agent to perform server operations, service management, or database introspection on remote infrastructure without exposing sensitive credentials to the agent's context. It fits scenarios where you want typed, structured responses rather than parsing raw shell output, and where you need to manage Docker containers, systemd services, or perform declarative deployments through an agent.

Do not use sshepherd when you need the agent to have direct access to credentials for dynamic server discovery, or when you require operations beyond the supported set (health checks, docker/systemd control, log tailing, config edits, Postgres introspection, and deploys). It is not suitable when raw terminal interaction or commands outside the defined operation set are required.

The agent provides only a name - an SSH alias, a Postgres target, or a deploy recipe - that resolves entirely outside the process. The system handles all credential resolution and connection details externally.

Every operation returns a typed Envelope<T> object containing ok (success boolean), alias (the name passed), data (operation-specific payload), and error (failure details if applicable). This consistent structure eliminates the need to parse raw terminal output.

The CLI shells out to the system ssh binary for all remote operations, using your existing SSH configuration and key management. It integrates with Docker for container management, systemd for service control, and Postgres for read-only database introspection on remote servers.

This tool is built for teams deploying agents that need to manage remote infrastructure without credential exposure. DevOps engineers and platform teams who want agents to perform routine server operations - checking service health, restarting containers, tailing logs, or inspecting database state - while maintaining strict credential isolation will find this valuable. It differs from direct SSH libraries by providing a credential-blind interface with structured, typed responses instead of raw shell output.