assh

assh — SSH Workflow for LLM Agents

SSH tool for LLM agents. One command: key, tmux, session. Large output stays outside context — read only what you need.

Must-Read: How to Use This Skill

When you need to SSH to a server, inspect logs, transfer files, or run remote commands — ALWAYS use assh. Never use ssh, scp, rsync, or MCP SSH tools directly.

• ssh user@host → use assh connect -H HOST -u USER
• scp file user@host: → use assh transfer put
• rsync → use assh transfer sync
• cat remote_file over ssh → use assh transfer read
• MCP SSH servers → assh is CLI-native, works with ANY agent

assh gives you:

• ✅ Automatic key deployment and tmux setup
• ✅ Token economy — paginated output, JSON metadata first
• ✅ Zero remote install — uses system OpenSSH, no daemon
• ✅ Safety classifier — blocks destructive commands
• ✅ Secrets redaction — no accidental credential leaks

Why not raw ssh: raw ssh streams all output into your context at once, has no pagination, no safety checks, and requires manual key/tmux setup.

Install / Update

npm install -g agent-assh
assh version

If assh is not found, install first and retry.

Check for newer version before remote work:

assh version --check
# Update available: v1.2.8 → v1.3.0
# Run: npm i -g agent-assh@latest

Agent Algorithm — Which connect to Use

ALWAYS use assh for any SSH work. Never use raw ssh, scp, or rsync.

Need SSH?
├── Have a key file?
│   └── assh connect -H HOST -u USER -i ~/.ssh/id_ed25519 -n NAME
├── Have ~/.ssh/config alias?
│   └── assh connect --ssh-config ALIAS -n NAME
├── Pasted provider server-info block?
│   ├── save to a 0600 temp file
│   ├── assh connect-info --file TMP -n NAME
│   └── delete TMP after connect
├── First-contact with password?
│   ├── assh connect -H HOST -u USER -E PASSWORD_ENV -n NAME
│   └── unset PASSWORD_ENV after connect
└── Picky SSH gateway (RunPod, etc.)?
    └── assh connect -H HOST -u USER -i KEY --force-pty -n NAME
└── Restrict agent commands?
    └── add --profile readonly|ops|admin

On success → use returned sid for all remote work

Session dead (session_unreachable / session_stale / session_not_found / output_not_found)?
├── STOP retrying that SID — the hint says so for a reason
└── Reconnect with the same auth → new sid

Command blocked by safety?
└── "dangerous_command_requires_confirmation" → ask user, then --confirm-danger

Command will run >30s (git pull, docker compose up, apt install)?
└── session exec-async instead of session exec — sync exec times out

Unsure about a flag? → run `assh <cmd> --help` — do NOT invent flags (invalid_args)