connect_ssh
Establish a persistent SSH connection, returning a session ID for subsequent command execution via execute. Supports key-based and password authentication with auto-acceptance of host keys.
Instructions
Opens a persistent SSH connection and returns a session_id for use with
`execute`. The connection stays open until `disconnect`. Host keys are
auto-accepted. For local commands, call `execute` directly — no session needed.
PARAMETER GUIDANCE: Reuse session_id across multiple execute calls —
each connect_ssh opens a new TCP connection. key_filepath is tried
first when both key and password are provided; password acts as
fallback. With neither, SSH agent and system defaults are used. The
username defaults to the OS user if omitted. host is resolved at
connect time; unresolvable names raise an error. banner_timeout
controls MOTD capture — if exceeded, banner returns "" (not an error);
set to 0 to skip capture entirely.
SIDE EFFECTS: Opens a TCP socket with a 30-second keepalive. Leaks
the socket if `disconnect` is never called.
ERRORS: Raises on auth failure, unresolvable host, refused connection,
or network timeout.
RETURNS: {"session_id": str, "banner": str}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Hostname or IP of the SSH server (e.g. '192.168.1.10', 'example.com') | |
| port | No | SSH port number, 1–65535 | |
| password | No | Password for password-based auth; omit for key-based auth | |
| username | No | Login user for authentication; omit to use SSH agent or OS default | |
| key_filepath | No | Absolute path to a private key file (e.g. '/home/user/.ssh/id_rsa') | |
| banner_timeout | No | Max seconds to capture the MOTD/welcome banner after login |