connect_ssh
Open a persistent SSH connection to a remote host and return a session ID for running commands. Supports password or key-based authentication and captures the server's welcome banner.
Instructions
Opens a persistent SSH connection to a REMOTE host and returns a session_id.
The connection stays open across tool calls until closed with `disconnect`;
drive it with `execute`. Host keys are auto-accepted (no prompt).
WHEN TO USE:
- Use this for a shell on a remote host. For a shell on the LOCAL machine
running this server, use `create_local` instead.
- Reuse an existing session_id rather than reconnecting per command.
AUTHENTICATION (key-based recommended):
- Password: pass `username` + `password`.
- Key: pass `username` + `key_filepath` (absolute path). If both a password
and a key are given, the key is tried first.
Captures the MOTD/welcome banner for up to `banner_timeout` seconds. Raises
on authentication failure, hostname/DNS errors, or connection timeout.
Returns a dict:
- session_id: identifier for this connection (pass to `execute`).
- banner: the server's MOTD, or "" if none arrived before banner_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. Omit if using key-based authentication | |
| key_filepath | No | Optional absolute path to a private key file for key-based auth; must be readable by the server process. If both this and password are supplied, the key is attempted first | |
| banner_timeout | No | The timeout in seconds to wait for the MOTD/welcome banner after the connection opens |