ssh_exec — Manual

What it does

Runs a shell command on a remote host over SSH (action: "exec", the default), or moves a file with SCP (action: "scp"). Both credential styles work out of the box: inline host/username/password/key_path for a one-off, or a named connection from ssh_hosts.json for a host you visit repeatedly.

Success is exit_status == 0. Any other status returns success: false with the full output preserved in the error — read it, it is the remote command's own stderr, not a Navi failure.

Parameters

Connecting

Inline — anything ad-hoc:

{"command": "uptime", "host": "192.168.1.168", "username": "ubuntu"}
{"command": "df -h /", "host": "10.0.0.5", "username": "root", "key_path": "~/.ssh/id_ed25519"}
{"command": "whoami", "host": "10.0.0.5", "username": "root", "password": "..."}

Named connection — the host is in ssh_hosts.json. Pass connection instead of the host triple:

{"command": "systemctl status navi", "connection": "prod"}

connection takes precedence, and inline host/username/password/port/key_path override the stored values one by one — useful for the same host under a different user.

With neither a connection that exists nor a host, the call fails with No SSH target specified before any network attempt.

Credentials and host keys

• Key auth — key_path (or client_keys in ssh_hosts.json) is expanded and used first; a password given alongside it becomes a fallback.
• Password-only — key lookup is disabled so asyncssh does not try your local keys first. This is the difference between a clean login and too many authentication failures.
• No credentials at all — asyncssh tries the default keys under ~/.ssh/.
• Host key verification is decided by known_hosts:
  • key absent from the config → verification is skipped (the default for ad-hoc calls);
  • "known_hosts": null (as in the template) → the system ~/.ssh/known_hosts is used;
  • a path → that file is used.
  To verify a host you connect to often, put the path (or an explicit null) in its ssh_hosts.json entry. Skipping is fine for a fresh VPS and wrong for production.

Connections are pooled

A connection is reused within a session (keyed by session + host + port + user, 20-minute TTL). Two sessions touching the same server keep separate pools and never interfere. If the server drops the connection (DisconnectError, ConnectionLost, EOF) the entry is evicted and the command is retried once on a fresh connection; a second failure is returned as-is. PermissionDenied is never retried — fix the credentials instead.

Transferring files

{"action": "scp", "direction": "upload", "connection": "prod",
 "local_path": "/tmp/build.tar.gz", "remote_path": "/opt/app/build.tar.gz"}
{"action": "scp", "direction": "download", "connection": "prod",
 "remote_path": "/var/log/navi.log", "local_path": "/tmp/navi.log"}

Both paths are required; the result says Uploaded: or Downloaded: with both ends. SCP honours the same timeout (default 60 s) — raise it for a large file.

Detaching long commands

Pass "background": true for builds, package installs, backups and anything else that outlives the turn. You get a task_id back immediately and the result arrives as a note at the start of a later turn; inspect it with the tasks tool. When you detach without passing timeout, the executor raises the limit to 300 s for that run — do not leave a detached command at the 60 s default and assume it finished.

Common mistakes

• Omitting username and landing as the Navi host's user, not the intended one.
• Putting the host in command (ssh root@10.0.0.5 uptime) — that depends on local SSH config and key forwarding. Use host/username, or connection.
• Reading a non-zero exit_status as a broken tool. The tool worked; the command failed.
• scp without direction — it defaults to upload, so a download silently needs it.
• Expecting host-key verification. It is off unless the connection says otherwise.