ssh_exec runs a shell command on a remote device over Tailscale SSH. It uses the Tailscale hostname directly — no IP addresses, no manual known_hosts management. The server spawns a real ssh process using a dedicated key mounted at /root/.ssh/reacher-key.
Windows targets are supported via cmd (default) or powershell. PowerShell commands are automatically encoded as Base64 UTF-16LE before being sent, which prevents quoting and escaping issues.
Parameters
string
required
Tailscale hostname of the target device (e.g.
"myserver"). Use tailscale_status to list available hostnames.string
required
Shell command to execute on the remote device.
string
SSH user to connect as. The schema default is
hazem (the project author’s username — you will almost certainly need to override this). Always specify the correct user for your target device, e.g. ubuntu, root, or your own username.string
Shell to use on Windows targets. Accepted values:
cmd or powershell. Defaults to cmd. Ignored on non-Windows hosts.Return value
boolean
true if the command exited with code 0.string
The target hostname as provided.
string
The SSH user used for the connection.
string
The command that was executed.
string
The shell used (
cmd or powershell).string
Trimmed standard output from the command.
string
Trimmed standard error output.
number
Process exit code.
0 means success.boolean
Present and
true when the command was blocked by a safety rule. Also includes reason and matched_rule fields.boolean
Present and
true when DRY_RUN=true is set. Includes a would_execute field instead of running the command.Usage examples
Safety considerations
Reacher enforces two optional safety layers configured inreacher.config.yaml:
Command blocklist
ssh.blocked_commands is a list of substrings. If any blocked string appears in the command (case-insensitive), the tool returns immediately with success: false and blocked: true — the SSH connection is never made.
Directory allowlist
ssh.allowed_dirs restricts SSH operations to specific paths. The tool parses path tokens from the command (tokens starting with /, ~, or ./) and checks each one against the list. An empty list means no restriction.
Dry-run mode
SetDRY_RUN=true to have ssh_exec evaluate safety rules and return a would_execute response without making any SSH connection. Useful for testing configurations.
All tool calls are written to
reacher-audit.log with timestamp, arguments, and result. Sensitive keys are stripped automatically.Common use cases
- Check logs —
tail,journalctl,caton log files - Inspect processes —
ps,top,htopsnapshots - Run deployments — trigger deploy scripts,
git pull,docker compose up - System health —
df,free,uptime,systemctl status - File inspection — read configs, check file permissions, list directory contents