ssh_session_open
Open a persistent SSH session to run multiple commands with shared state or interactive programs. Returns a session ID for use with ssh_session_exec; close with ssh_session_close when done.
Instructions
Open a persistent SSH session that reuses the connection across commands. Use when you need multiple commands with shared state (e.g. cd to a directory and then operate in it) or interactive programs. For isolated commands prefer ssh_execute (simpler, stronger isolation guarantee). Available modes: exec (default, independent commands), shell (stateful sh: cd and variables persist), pty (shell with TTY for interactive programs). sudo=true ONLY if allow_sudo=true (see ssh_list_servers); if allow_sudo=false DO NOT retry. mode=pty ONLY if allow_pty=true. Every ssh_session_exec is preflighted against the current signer policy, so policy reloads revalidate target and bastion access, end-user groups, sudo, sudo_user, PTY, and the host's physical route for already-open sessions. On command-policy hosts, mode=exec is allowed; mode=shell and mode=pty are rejected. Returns session_id for use with ssh_session_exec. IMPORTANT: always close the session with ssh_session_close when done; an open session holds an SSH connection and is otherwise closed when the certificate that opened it expires, or after an idle or maximum-lifetime timeout (whichever comes first).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | exec (default): isolated commands with no shared state. shell: persistent sh, cd and environment variables survive across ssh_session_exec calls. pty: shell with pseudo-terminal for interactive programs (editors, less, etc.); requires allow_pty=true. If allow_pty=false DO NOT use pty. | |
| sudo | No | if true, start with sudo -n elevation (NOPASSWD). In mode=shell/pty elevates the whole shell process. In mode=exec prepends sudo to each individual command. Requires allow_sudo=true in ssh_list_servers. If allow_sudo=false DO NOT retry. | |
| server | Yes | logical name of the target host (see ssh_list_servers) | |
| sudo_user | No | target user for sudo (empty = root). Must be in the host's allowed_sudo_users list. | |
| ttl_seconds | No | connection certificate validity in seconds; omit to use the maximum allowed by the host policy |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| serial | Yes | ||
| session_id | Yes |