ai-ssh

Agent-friendly SSH CLI and skill for real remote operations over Paramiko.

ai-ssh is built for AI agents that need to connect to Linux hosts, run commands, inspect services, transfer files, and make safe remote changes using structured JSON results instead of brittle plain-text shell parsing.

What It Does

• Test SSH connectivity with connect
• Run non-interactive commands with exec
• Run privileged commands with sudo
• Upload and download files with upload and download
• Read and write remote text files with read, write, and write-b64
• Run local scripts remotely with exec-local-script
• Collect system information with stat
• Diagnose systemd services with service-fail-summary and service-watch
• Run long jobs with job-run and job-status
• Watch network and process activity with net-watch and proc-watch
• Use persistent tmux-backed shells with shell-open, shell-send, and shell-close

Why This Exists

Typical SSH automation for agents is fragile for three reasons:

1. Local shell quoting breaks before the command ever reaches SSH
2. Plain stdout parsing is inconsistent across commands and environments
3. Multi-step remote workflows need state, ordering, and structured results

ai-ssh addresses those issues by:

• returning JSON from every subcommand
• preferring high-level operations over raw ssh and scp
• providing safer transport options like --cmd-file, exec-local-script, and write-b64
• making long-running tasks and service diagnostics explicit

Good Defaults For Agents

Use the simplest safe path.

• Use connect first for new credentials
• Use exec for short, read-only inspection commands
• Use --cmd-file instead of inline --cmd for anything non-trivial on Windows PowerShell
• Use exec-local-script when the task is naturally a script
• Use upload for complex JSON, YAML, shell scripts, and multiline content
• Use job-run for long-running installs, downloads, builds, and migrations
• Use service-fail-summary and service-watch for systemd troubleshooting

Important Execution Rule

Dependent remote actions must be run sequentially.

Do not parallelize steps like:

• write -> read
• upload -> exec
• job-run -> job-status
• shell-open -> shell-send -> shell-close

Parse the JSON from the earlier step first, confirm success, then continue.

Windows PowerShell Guidance

Inline commands are the main source of avoidable failures on Windows.

Avoid inline --cmd when the command contains:

• $
• ; or &&
• braces
• nested quotes
• multiple file paths
• awk or sed

Prefer:

• --cmd-file
• exec-local-script
• upload
• write-b64

Example

python scripts/cli.py connect --host 10.0.0.10 --user root --password secret
python scripts/cli.py exec --host 10.0.0.10 --user root --password secret --cmd hostname
python scripts/cli.py job-run --host 10.0.0.10 --user root --password secret --cmd-file .\install.sh --log /tmp/install.log --exit-file /tmp/install.exit

Example job-run result:

{
  "success": true,
  "started": true,
  "job_id": "...",
  "job_ref": "job-abc123def456",
  "status": "running",
  "log": "/tmp/install.log",
  "exit_file": "/tmp/install.exit"
}

Repository Layout

• SKILL.md: full skill instructions for agent use
• scripts/cli.py: main CLI entrypoint
• scripts/*.py: SSH, SFTP, systemd, job, tmux, and utility modules

Status

The project is designed around real agent usage rather than theoretical SSH examples. It has been exercised against real remote hosts for:

• connectivity
• read-only inspection
• remote file read and write
• PowerShell quoting fallback paths
• background jobs
• systemd diagnostics
• tmux-backed persistent shell flows

License

BSD 2-Clause. See LICENSE.