ssh

ssh

ssh utilities for remote dispatch

RunResult(returncode: int, stdout: str, stderr: str) dataclass

Result of a remote command execution

TunnelResult(returncode: int, pid: int | None, command: list[str], stderr: str = '') dataclass

Result of starting an SSH local port forward.

hosts() -> list[str]

Parse ~/.ssh/config to list accessible hosts.

Returns a list of host names/aliases defined in the SSH config. Excludes wildcard patterns and special entries.

run(cmd: str | list[str], host: str, timeout: float | None = None) -> RunResult

Execute a command remotely on a host via SSH.

Runs in a login shell to ensure environment variables are loaded. Retries on transient connection errors with exponential backoff.

Parameters:

Name	Type	Description	Default
cmd	str | list[str]	Command to execute (string or list of args)	required
host	str	SSH host (name, alias, or user@host)	required
timeout	float | None	Optional timeout in seconds	None

Returns:

Type	Description
RunResult	RunResult with returncode, stdout, and stderr

run_many(cmd: str | list[str], hosts: list[str], timeout: float | None = None) -> dict[str, RunResult]

Execute a command on multiple hosts in parallel.

Parameters:

Name	Type	Description	Default
cmd	str | list[str]	Command to execute	required
hosts	list[str]	List of SSH hosts	required
timeout	float | None	Optional timeout in seconds per host	None

Returns:

Type	Description
dict[str, RunResult]	Dict mapping host -> RunResult

copy_to(local_path: str | Path, host: str, remote_path: str, timeout: float | None = None) -> RunResult

Copy a local file/directory to a remote host via scp.

Parameters:

Name	Type	Description	Default
local_path	str | Path	Local file or directory path	required
host	str	SSH host	required
remote_path	str	Destination path on remote host	required
timeout	float | None	Optional timeout in seconds	None

Returns:

Type	Description
RunResult	RunResult with returncode, stdout, and stderr

copy_from(host: str, remote_path: str, local_path: str | Path, timeout: float | None = None) -> RunResult

Copy a remote file/directory to local via scp.

Parameters:

Name	Type	Description	Default
host	str	SSH host	required
remote_path	str	Source path on remote host	required
local_path	str | Path	Local destination path	required
timeout	float | None	Optional timeout in seconds	None

Returns:

Type	Description
RunResult	RunResult with returncode, stdout, and stderr

is_reachable(host: str, timeout: float = 5.0) -> bool

Check if a host is reachable via SSH.

Parameters:

Name	Type	Description	Default
host	str	SSH host to check	required
timeout	float	Connection timeout in seconds	5.0

Returns:

Type	Description
bool	True if host is reachable

forward_port(host: str, local_port: int, remote_port: int) -> TunnelResult

Start a background SSH tunnel forwarding local_port -> remote localhost:remote_port.

Parameters:

Name	Type	Description	Default
host	str	SSH host (name, alias, or user@host)	required
local_port	int	Local port to bind	required
remote_port	int	Remote port on localhost to forward to	required

Returns:

Type	Description
TunnelResult	TunnelResult with PID on success