agent-ssh-cli

A CLI-based SSH agent tool that maps ssh-mcp-server capabilities into remote operations callable by agents.

Remote exec · File upload · File download · Connection config · Command whitelist · Command blacklist · Agent Skill integration

AI One-Click Installation · Manual Installation · Configuration · Uninstall and Cleanup · License · Friendly Links

中文 | English

Introduction

This project references the SSH operation design from classfang/ssh-mcp-server and rewrites it as an independent CLI. Thanks to the original project for the ideas and capability foundation.

What it can do:

Free your hands and automate server operations
Deploy code and update Docker deployments
Configure nginx and certificates
Do anything SSH can do

Its capabilities:

List SSH server connections from local configuration
Execute commands on a specified remote server
Upload local files to a remote server with temporary files, resume, and retry
Download files from a remote server to local
Restrict executable commands through command allowlists and blocklists

Upload Reliability

Uploads are written to <remotePath>.part first, with resume metadata in <remotePath>.part.meta. After the temporary file size is verified, it is renamed to the final target path. If an upload is interrupted, running the same upload again resumes from the existing .part size when the local file metadata still matches.

For --no-cache uploads, use Ctrl+C to stop the current CLI process. In daemon mode, agentsshcli stop-daemon stops the connection-pool process, but it affects other tasks in the same daemon and is not a precise per-upload cancel operation.

AI One-Click Installation

Please read https://github.com/sleepinginsummer/agent-ssh-cli/blob/main/AI_INSTALL.md, follow the instructions to install the CLI, and add `SKILL.md`.

Manual Installation

Requirements

Node.js >= 18
npm >= 8
Local network access to the target SSH server
If private key authentication is used, the private key file must be readable by the current user
Prebuilt platform packages support macOS arm64/x64, Linux x64/arm64, and Windows x64

Installation Steps

Install globally:

npm install -g agent-ssh-cli
agentsshcli --help

Import SKILL.md:

Open SKILL.md and add it to the agent.

Configuration

Initialize the configuration. The format parameters are compatible with ssh-mcp-server:

mkdir -p ~/.agent-ssh-cli

Edit ~/.agent-ssh-cli/config.json and fill in the real connection information. The default configuration file path can also be overridden with an environment variable:

You can change the configuration location with the following environment variable:

AGENT_SSH_CONFIG=/path/to/config.json

The configuration file is an array, and each item represents one server:

name: Connection name, must be unique
host: SSH host address
username: SSH username
password / passwordRef / privateKey: Authentication method; keep exactly one authentication type among password, password reference, and private key
port: SSH port, defaults to 22
passphrase: Private key passphrase, only used with privateKey
socksProxy: SOCKS5 proxy address, for example socks5://127.0.0.1:1080; the scheme can also be omitted as 127.0.0.1:1080
jumpHost: Jump host connection name, must reference another name in the config file
pty: Whether to allocate a pseudo-terminal, defaults to false; it can also be enabled per command with exec --pty
allowedLocalPaths: Legacy-compatible field; local paths are not restricted now
commandWhitelist: Command whitelist regular expression array
commandBlacklist: Command blacklist regular expression array

commandWhitelist and commandBlacklist use JavaScript RegExp syntax, not POSIX regular expressions. Write whitespace as \\s; do not use [:space:].

See the full example in example.config.json. Store real connection information in ~/.agent-ssh-cli/config.json.

To reduce password leakage from configuration files, password authentication is passively encrypted the first time that server is used: after you write a plaintext password, the next exec, upload, or download for that server encrypts the password into secrets.json under the config directory, creates a local secret.key, then writes the config back with an empty password and a passwordRef. Later runs decrypt through passwordRef. To change the password, replace the empty password with the new plaintext password; the next connection overwrites the old encrypted value.

Reference configuration

[
  {
    "name": "password-server",
    "host": "192.0.2.10",
    "port": 22,
    "username": "root",
    "password": "",
    "passwordRef": "agentsshcli:password-server",
    "jumpHost": "jump-server",
    "commandBlacklist": [
      "(^|[;&|()\\s])rm(\\s|$)",
      "(^|[;&|()\\s])shutdown(\\s|$)",
      "(^|[;&|()\\s])reboot(\\s|$)"
    ]
  },
  {
    "name": "jump-server",
    "host": "198.51.100.20",
    "port": 22,
    "username": "ubuntu",
    "privateKey": "/path/to/jump_key",
    "passphrase": "******",
    "socksProxy": "socks5://127.0.0.1:1080"
  },
  {
    "name": "key-server",
    "host": "198.51.100.10",
    "port": 22,
    "username": "deploy",
    "privateKey": "/path/to/id_rsa",
    "passphrase": "******",
    "pty": false,
    "allowedLocalPaths": [
      "./tmp",
      "./dist"
    ],
    "commandWhitelist": [
      "^pwd$",
      "^ls(\\s|$)",
      "^cat\\s+/var/log/app\\.log$"
    ],
    "commandBlacklist": [
      "(^|[;&|()\\s])rm(\\s|$)",
      "(^|[;&|()\\s])shutdown(\\s|$)",
      "(^|[;&|()\\s])reboot(\\s|$)"
    ]
  }
]

Test command

agentsshcli list
agentsshcli exec --no-cache password-server "pwd"
agentsshcli exec --pty password-server "tty"
agentsshcli exec password-server --command-file ./script.sh --timeout 60000

Installation is complete.

Uninstall and Cleanup

Update to the latest version:

npm install -g agent-ssh-cli@latest

Remove:

npm uninstall -g agent-ssh-cli
npm cache clean --force
# Delete the configuration file
rm -rf ~/.agent-ssh-cli

License

MIT

Friendly Links

LINUX DO - A New Ideal Community

FilesExpand file tree

README_EN.md

Latest commit

History