Connect to a remote host via SSH. Returns a session_id for use with all other tools. Supports password and key-based authentication.

Args: host: Hostname or IP address of the remote server. username: SSH username (default: root). password: Password for authentication. Leave empty for key-based auth. key_path: Path to SSH private key file. Leave empty for password auth. port: SSH port (default: 22). timeout: Connection timeout in seconds (default: 60).

Returns: Session info dict with session_id, host, and connection status.

List all active SSH sessions with their connection status and details.

Returns: List of session info dicts.

Close an SSH session and release all its resources (shell, SFTP, port forwards). WARNING: this kills any running processes in the session.

Args: session_id: The session ID returned by ssh_connect.

Returns: Confirmation message.

Execute a command on the remote host and return structured output. Each call runs in an independent exec channel -- no state is shared between calls (use ssh_shell_* tools for persistent state).

Args: session_id: The session ID returned by ssh_connect. command: Shell command to execute. timeout: Maximum seconds to wait for the command to finish (default: 120).

Returns: Dict with stdout, stderr, and exit_code.

Execute a command with sudo on the remote host. If the user already has passwordless sudo, leave sudo_password empty.

Args: session_id: The session ID returned by ssh_connect. command: Shell command to execute under sudo. sudo_password: Password for sudo prompt (empty for passwordless sudo). timeout: Maximum seconds to wait (default: 120).

Returns: Dict with stdout, stderr, and exit_code.

Create an SSH port forward (local -> remote). Connections to 127.0.0.1:local_port will be tunneled through SSH to remote_host:remote_port.

If local_port is 0, a random available port is chosen.

Args: session_id: The session ID returned by ssh_connect. remote_port: Port on the remote side to forward to. local_port: Local port to listen on (0 = auto-assign). remote_host: Host on the remote side (default: localhost, i.e. the SSH server itself).

Returns: Dict with forward_id, local_port, remote_host, and remote_port.

List all active port forwards for an SSH session.

Args: session_id: The session ID returned by ssh_connect.

Returns: List of forward info dicts.

Close a specific port forward.

Args: session_id: The session ID returned by ssh_connect. forward_id: The forward ID returned by ssh_forward_port.

Returns: Confirmation message.

Upload a local file to the remote host via SFTP.

Args: session_id: The session ID returned by ssh_connect. local_path: Path to the file on the local machine. remote_path: Destination path on the remote host.

Returns: Confirmation message with file size.

Download a file from the remote host to the local machine via SFTP.

Args: session_id: The session ID returned by ssh_connect. remote_path: Path to the file on the remote host. local_path: Destination path on the local machine.

Returns: Confirmation message with file size.

Read a text file on the remote host and return its contents. For large files, use max_bytes to limit the amount read.

Args: session_id: The session ID returned by ssh_connect. remote_path: Path to the file on the remote host. max_bytes: Maximum bytes to read (default: 1MB). Set to 0 for no limit.

Returns: File contents as text.

Write text content to a file on the remote host via SFTP.

Args: session_id: The session ID returned by ssh_connect. remote_path: Path to the file on the remote host. content: Text content to write. append: If True, append to existing file instead of overwriting (default: False).

Returns: Confirmation message with bytes written.

List files and directories at a path on the remote host via SFTP.

Args: session_id: The session ID returned by ssh_connect. remote_path: Directory path on the remote host (default: current directory).

Returns: List of dicts with name, size, modified timestamp, and is_dir flag.

Open a persistent interactive shell on the SSH session. The shell preserves working directory, environment variables, and running processes across multiple send/read calls. Ideal for screen/tmux, long builds, etc.

If a shell is already open, this is a no-op (returns existing shell info).

Args: session_id: The session ID returned by ssh_connect. term: Terminal type (default: xterm). width: Terminal width in columns (default: 200). height: Terminal height in rows (default: 50).

Returns: Confirmation that the shell is open.

Send text to the interactive shell. By default appends Enter (newline) and waits briefly to capture output.

Args: session_id: The session ID returned by ssh_connect. data: Text to send to the shell. press_enter: Whether to append a newline after the text (default: True). wait: Seconds to wait for output after sending (default: 1.0). read_lines: Number of tail lines to return from the shell buffer (default: 100).

Returns: Recent shell output (tail of buffer).

Read the current content of the interactive shell buffer. Use this to poll for output from long-running commands without sending anything.

Args: session_id: The session ID returned by ssh_connect. lines: Number of tail lines to return (default: 100).

Returns: Recent shell output (tail of buffer).

Send a control character to the interactive shell. Common keys: "c" for Ctrl+C (interrupt), "d" for Ctrl+D (EOF), "z" for Ctrl+Z (suspend), "l" for Ctrl+L (clear screen), "a" for Ctrl+A (screen prefix).

Args: session_id: The session ID returned by ssh_connect. key: Single letter for the control key (e.g. "c" sends Ctrl+C).

Returns: Confirmation and recent shell output.

Wait for the shell output to contain a specific pattern, or for the output to stabilize (no new output for two poll intervals). Useful for waiting on long-running commands to complete.

Args: session_id: The session ID returned by ssh_connect. pattern: Text pattern to wait for (e.g. a shell prompt like "$ " or "# "). If empty, waits for output to stabilize. timeout: Maximum seconds to wait (default: 300). poll_interval: Seconds between polls (default: 2.0). lines: Number of tail lines to return (default: 100).

Returns: Shell output when the pattern is found or output stabilizes.