Подробное руководство по работе с этими инструментами.

Прочитайте нужную тему перед первой интерактивной сессией, первым туннелем или сохранением нового сервера: там разобраны нерабочие пути, на которые иначе уходит по несколько попыток.

Показать сохранённые серверы, живые соединения, сессии и туннели.

Первый инструмент, с которого стоит начинать: отвечает на вопрос «что у меня уже есть» одним вызовом.

Подключиться к серверу по имени либо по адресу с логином и паролем/ключом.

Если сервер неизвестен, подключение происходит без всякого конфига, а доступы НЕ сохраняются: в ответе придёт next_action с требованием спросить у пользователя имя и вызвать ssh_save_server. Не придумывайте имя сами.

Сохранить сервер под именем, которое назвал пользователь.

Обычно вызывается сразу после ssh_connect с его pending_id — тогда живое соединение просто переименовывается и переподключения не происходит.

Удалить сохранённый сервер. Заметки удаляются только по явному запросу.

Закрыть соединение с сервером вместе с его сессиями и туннелями.

Снять закрепление ключа хоста.

Вызывать только после того, как пользователь явно подтвердил, что сервер был пересоздан. Молча повторять подключение после расхождения ключей — ровно то, чего добивается перехватчик.

Импортировать серверы из старого блочного servers.env.

По умолчанию только показывает, что будет импортировано: покажите результат пользователю прежде, чем писать.

Выполнить команду на сервере и дождаться результата.

Для всего, что длится дольше пары минут (apt upgrade, docker pull), берите background=true: команда отвяжется от сессии и переживёт её, а вывод уйдёт в файл. Увеличивать таймаут вместо этого — путь к зависшему вызову.

Выполнить одну команду на нескольких серверах параллельно.

Сбой одного сервера не отменяет остальные — в ответе будет и результат, и ошибка, каждая рядом со своим именем.

Прочитать факты и заметки о сервере.

Записать заметку о сервере — она переживёт перезапуск и новую сессию.

Перечитать факты о сервере: ОС, ядро, диск, установленное ПО, порты.

Показать журнал выполненных действий — что и когда делали с серверами.

Залить локальный файл на сервер и проверить, что он долетел целым.

Для содержимого, которое вы сами составили, лучше ssh_file_write — он идемпотентен, умеет проверку конфига и делает резервную копию.

Скачать файл с сервера на эту машину и сверить контрольную сумму.

Прочитать текстовый файл с сервера. Большие файлы обрезаются.

Положить файл на сервер атомарно и идемпотентно.

Порядок намеренный: сверить хеш, залить во временный, проверить временный, переставить через rename. На месте боевого файла никогда не оказывается непроверенное содержимое, а повторный вызов с тем же текстом ничего не делает и честно сообщает changed=false.

Показать содержимое каталога на сервере.

Перекинуть файл с одного сервера на другой через эту машину.

Идёт потоком через локальный временный файл: так не требуется никакого доверия между серверами, которого между ними обычно и нет.

Открыть интерактивную оболочку на сервере.

Нужна там, где команда что-то спрашивает или рисует полноэкранный интерфейс: nano, whiptail, htop, меню панелей. Для обычных команд берите ssh_run — он дешевле. Сессию по окончании закрывайте.

Отправить текст и/или нажатия клавиш в сессию и дождаться реакции.

Работайте циклом: отправили — прочитали — посмотрели на экран — решили. Две отправки подряд вслепую почти всегда приводят к застрявшей сессии.

Ввести пароль в приглашение sudo, passwd или установщика.

Предпочитайте server_password: тогда пароль берётся из хранилища внутри процесса и вообще не проходит через переписку. Никогда не отправляйте пароль обычным ssh_shell_send — тот пишет текст в журнал.

Дочитать вывод сессии, ничего не отправляя — для длящихся команд.

Изменить размер окна сессии. Полезно, если TUI обрезает содержимое.

Закрыть интерактивную сессию.

Показать имена клавиш, которые понимает ssh_shell_send.

Поднять туннель до сервера.

Панель, слушающую на 127.0.0.1:2053, открывают как kind='local' с dest_host='127.0.0.1', dest_port=2053 — и она становится доступна по возвращённому адресу. Туннель живёт до конца сессии Claude Code.

Закрыть туннель. Без аргумента закрывает все.