connect_ssh
Establish a persistent SSH connection to a remote server that remains active for sequential command execution. Supports password and key-based authentication.
Instructions
Establishes a persistent, stateful connection to a remote SSH server, automatically accepting host keys.
This session remains active across tool calls, allowing multiple execute commands to run sequentially.
CONNECTION LIFECYCLE:
- Initiates connection and performs handshake.
- Waits up to `banner_timeout` seconds to capture the MOTD/welcome banner.
- Returns a persistent session_id representing this connection.
- The connection remains open until explicitly closed using the `disconnect` tool.
AUTHENTICATION METHODS:
- Username & Password: Use 'username' and 'password' arguments.
- Key-based (Recommended): Provide 'username' and 'key_filepath' (absolute path to private key).
- If both password and private key are provided, key-based authentication is attempted first.
DEFAULT BEHAVIORS:
- Automatically trusts and accepts SSH host keys (no prompt).
- Starts a remote shell session ready to execute commands.
ERROR HANDLING:
- Raises exceptions for authentication failures, hostname resolution issues, or connection timeouts.
- Ensure paths provided in 'key_filepath' are absolute and readable by the server process.
Returns:
A dictionary containing:
- session_id: Unique identifier for the created SSH session (use this for execute commands).
- banner: The server's welcome message/MOTD, or an empty string if timeout.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | The hostname or IP address of the SSH server to connect to (e.g., '192.168.1.10' or 'example.com') | |
| port | No | The port number of the SSH server (default is 22) | |
| username | No | Optional username for authentication. If omitted, the connection will use SSH agent or system defaults | |
| password | No | Optional password for password-based authentication. If using key-based authentication, this can be omitted | |
| key_filepath | No | Optional absolute path to a private key file (SSH key) for key-based authentication | |
| banner_timeout | No | The timeout in seconds to wait for the MOTD/welcome banner after the connection opens |