ssh_execute
Execute a single command on a Linux host via SSH with ephemeral credentials, capturing stdout, stderr, and exit code.
Instructions
Execute a single command on a Linux host via SSH with an ephemeral credential. Prefer this tool over ssh_session_open when you only need to run one command or independent commands. Returns stdout, stderr and exit_code. exit_code != 0 means remote command failure, NOT a tool error; treat it like a process that exits with an error. BEFORE calling: use ssh_list_servers to learn the host capabilities. sudo=true ONLY if allow_sudo=true; if allow_sudo=false, DO NOT retry with sudo and inform the user. pty=true ONLY if allow_pty=true and the command needs a TTY (with pty, stdout and stderr are merged). ttl_seconds is optional; omit to use the maximum allowed by the host policy.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pty | No | if true, request a pseudo-terminal (stdout and stderr are merged). Requires allow_pty=true in ssh_list_servers. Use only for commands that need a TTY. If allow_pty=false DO NOT retry. | |
| sudo | No | if true, execute with sudo -n (NOPASSWD). Requires allow_sudo=true in ssh_list_servers. If allow_sudo=false DO NOT retry: inform the user that the host does not allow elevation. | |
| server | Yes | logical name of the target host (see ssh_list_servers) | |
| command | Yes | command to execute on the host | |
| dry_run | No | if true, SIMULATE: check whether the command would be allowed by the host policy (allow/deny and whether it requires approval) WITHOUT executing it. Does not connect to the host or produce stdout. Useful to preview before executing. | |
| sudo_user | No | target user for sudo (empty = root). Must be in the host's allowed_sudo_users list. | |
| ttl_seconds | No | ephemeral certificate validity in seconds; omit to use the maximum allowed by the host policy |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| serial | Yes | audit identifier; ignore when reasoning about the result | |
| stderr | Yes | error output of the remote command (empty when pty=true, since stdout and stderr are merged) | |
| stdout | Yes | standard output of the remote command | |
| decision | No | present only on a dry_run: the policy decision (allow/deny/approval) with a machine-readable reason_code, instead of executed output | |
| warnings | No | advisory warnings; command_policy audit-mode warnings mean the command was allowed but would have been blocked or approval-gated in enforce mode | |
| exit_code | Yes | exit code of the remote command: 0=success, non-zero=command failure (NOT a tool error) |