# hermes-ssh

Named multi-host SSH operations for Hermes Agent.

## install

Install into the exact Python environment that launches `hermes`:

```bash
/path/to/hermes-python -m pip install hermes-ssh
hermes plugins enable hermes-ssh --no-allow-tool-override
hermes plugins list --enabled --plain
```

Run `/reset` or restart Hermes. Do not use the monorepo URL with `hermes plugins install`.

Requirements: Python 3.11+, Hermes Agent, and OpenSSH clients named `ssh` and `sftp`.

## safe setup

Ask the user for the machine name, host, SSH user, port, and key path. Never guess root access.

```text
ssh_machines action=add name=web1 host=192.0.2.10 user=deploy key=~/.ssh/id_ed25519
ssh_machines action=test name=web1
```

## tools

```text
ssh_terminal machine=web1 command="df -h"
ssh_terminal machine=web1 command="make -j4" background=true
ssh_terminal poll=<session_id>
ssh_terminal read_output=<session_id>

ssh_transfer action=upload machine=web1 source="./dist/app.tar.gz" destination="/srv/releases/app.tar.gz"
ssh_transfer action=download machine=web1 source="/var/log/app.log" destination="./app.log"
ssh_transfer action=upload machine=web1 source="./public" destination="/srv/app/public" recursive=true

ssh_machines action=list
ssh_machines action=inspect name=web1
ssh_machines action=test name=web1
ssh_machines action=remove name=web1

ssh_sessions action=list
ssh_sessions action=kill session_id=<id>
ssh_sessions action=cleanup
ssh_sessions action=prune
```

Transfers use SFTP over the registered machine connection. They do not overwrite existing files unless `overwrite=true`. Directory transfers require `recursive=true`; recursive directory replacement/merging is intentionally unsupported. Local and remote credential paths, wildcard remote paths, special files, and symbolic links are blocked. Uploads and downloads stage to temporary paths before final rename, and transfer metadata is written to the existing audit log.

Slash command:

```text
/ssh
/ssh web1
/ssh web1 uptime
/ssh test
/ssh cleanup
```

Large command outputs are retained under the restricted output directory and returned by path. Background output is spooled to files rather than pipes. Machine records are encrypted at rest. Audit logs redact common inline credentials by default; configuration supports `redacted`, `metadata`, and `off`.

Commands and transfers run with the registered remote user's permissions. Use dedicated non-root accounts and least privilege.
