SSH-доступ и SSH-ключи через AI-ассистента

AI-ассистент, подключённый через MCP (https://api.app.blackbox.md/mcp), может по вашей просьбе получить прямой SSH-доступ к вашим серверам и управлять SSH-ключами в аккаунте и на сервере. Доступ ассистенту даёт API-токен, созданный в разделе «Личный кабинет» → «API-токены» (blackbox.md/ru/account/api-tokens). Теми же ключами можно управлять и вручную: на странице «SSH-ключи» в личном кабинете и в карточке сервера на странице «Мои серверы» в панели app.blackbox.md.

Доступно: владельцу аккаунта blackbox.md — по API-токену с разрешениями из таблицы ниже. Серверные инструменты работают на серверах, которые вы заказали сами, и на серверах компании, на которые BLACKBOX выдал вам права управления. На серверах с отметкой «Обслуживается» в панели (только просмотр) они не работают — изменения на таких серверах запрашивайте у нас.

Инструменты и нужные разрешения

• На странице токенов эти разрешения называются «Просматривать пароли/доступы к серверам» (servers:credentials), «Читать список моих SSH-ключей» (ssh_keys:read) и «Добавлять и удалять мои SSH-ключи» (ssh_keys:write). Инструменты, для которых у токена нет разрешения, ассистенту не видны. Подробнее: Разрешения токенов (scopes).
• Лимиты общие для всех токенов аккаунта и не зависят от лимитов панели. Все инструменты MCP вместе принимают не более 120 вызовов в минуту.

Прямой SSH-доступ для ассистента

get_server_ssh_access выдаёт ассистенту собственный SSH-ключ для сервера — ключ агента. BLACKBOX создаёт ключ Ed25519 с комментарием blackbox-agent-…, добавляет его в /root/.ssh/authorized_keys и возвращает вместе с данными для подключения.

1. Попросите ассистента, например: «Дай мне SSH-доступ к серверу IP_СЕРВЕРА, хочу скопировать файлы через rsync».

2. Ассистент вызывает get_server_ssh_access. AI-клиент может попросить вас одобрить вызов.

3. В ответе приходит:

   Поле	Содержимое
   host, port, username	IP-адрес сервера, порт SSH и пользователь root
   private_key	приватная часть ключа в формате OpenSSH, без парольной защиты
   public_key, fingerprint	публичная строка ssh-ed25519 … blackbox-agent-… и отпечаток SHA256:…
   ssh_command	готовая команда ssh -i <keyfile> -p ПОРТ root@IP; вместо <keyfile> подставьте путь к файлу с ключом
   created, rotated, previous_key_removed	создан ли ключ только что, был ли он заменён и удалён ли старый

• Каждый вызов выдаёт один и тот же ключ и заново устанавливает его на сервер, если ключ тем временем удалили. На серверах, заказанных на blackbox.md, ключ агента обычно добавляется при создании сервера; если сервер тогда его не получил, ключ создаётся при первом вызове.
• На одном сервере только один ключ агента, общий для всех ваших токенов.
• С regenerate=true создаётся новый ключ, а старый удаляется с сервера. Если удалить старый не получилось, в ответе будет previous_key_removed: false — тогда удалите в панели ключ blackbox-agent-…, отпечаток которого не совпадает с отпечатком из ответа.

Для обычных команд ключ ассистенту не нужен: он пользуется run_server_command (Выполнение команд на сервере через AI). Ключ агента пригодится, чтобы копировать файлы через rsync или scp, работать в интерактивной сессии в собственном терминале и подключать инструменты, которым нужно настоящее SSH-соединение (например, VS Code Remote - SSH или Ansible). Сам ассистент может им воспользоваться, только если AI-клиент выполняет команды на вашем компьютере (например, Claude Code или Cursor); иначе он передаст ключ и команду вам.

Как подключиться с ключом агента из своего терминала

1. Явно попросите ассистента показать приватный ключ: по инструкции он не выводит пароли и ключи в переписку без прямой просьбы.

2. Скопируйте весь текст — от -----BEGIN OPENSSH PRIVATE KEY----- до -----END OPENSSH PRIVATE KEY----- включительно — в новый файл, например ~/.ssh/blackbox_agent. После последней строки нажмите Enter, чтобы файл заканчивался переводом строки, иначе SSH может ответить invalid format.

3. В macOS и Linux ограничьте права на файл и подключитесь:

   chmod 600 ~/.ssh/blackbox_agent
   ssh -i ~/.ssh/blackbox_agent -p 22 root@IP_СЕРВЕРА

4. В Windows проверьте, что у файла не появилось расширение .txt. В PowerShell оставьте доступ к файлу только своему пользователю (иначе SSH может отклонить ключ с сообщением UNPROTECTED PRIVATE KEY FILE) и подключитесь:

   icacls $env:USERPROFILE\.ssh\blackbox_agent /inheritance:r /grant:r "$($env:USERNAME):(R)"
   ssh -i $env:USERPROFILE\.ssh\blackbox_agent -p 22 root@IP_СЕРВЕРА

Копирование файлов с тем же ключом:

rsync -avz -e "ssh -i ~/.ssh/blackbox_agent" ./site/ root@IP_СЕРВЕРА:/var/www/site/
scp -i ~/.ssh/blackbox_agent backup.tar.gz root@IP_СЕРВЕРА:/root/

Подробнее: Передача файлов на сервер (scp, rsync, SFTP). Для постоянного личного доступа установите свой ключ: ключ агента любой ассистент может в любой момент заменить через regenerate=true.

Ключи в аккаунте

list_ssh_keys, add_ssh_key и delete_ssh_key работают с теми же ключами, что и страница «SSH-ключи» (blackbox.md/ru/account/ssh-keys, «Личный кабинет» → «SSH-ключи»): ключ, добавленный ассистентом, появится там, и наоборот. Правила те же (SSH-ключи в аккаунте (blackbox.md)):

• не более 20 ключей на аккаунт (иначе too_many_keys);
• одна строка публичного ключа ssh-ed25519, ssh-rsa (не короче 2048 бит), ecdsa-sha2-nistp256/384/521, sk-ssh-ed25519@openssh.com или sk-ecdsa-sha2-nistp256@openssh.com (иначе invalid_public_key, unsupported_key_type или key_too_weak);
• название обязательно, в одну строку, не длиннее 80 символов;
• приватный ключ не принимается (private_key_submitted), как и уже сохранённый ключ (duplicate_key).

Пример: «Сохрани в моём аккаунте этот публичный ключ под названием „Рабочий ноутбук“». add_ssh_key не устанавливает ключ ни на один сервер — для этого ассистент затем вызывает add_server_ssh_key. И наоборот, delete_ssh_key удаляет ключ только из аккаунта: на серверах, где он установлен, ключ работает, пока вы не удалите его с каждого сервера.

Ключи на сервере

Эти инструменты используют управляющее подключение BLACKBOX — без вашего пароля и ключа. add_server_ssh_key, list_server_ssh_keys и remove_server_ssh_key работают с /root/.ssh/authorized_keys, как и раздел «Добавить SSH-ключ» в карточке сервера (Добавление и удаление SSH-ключей на сервере).

• Вставленный ключ устанавливается только на этот сервер и в аккаунте не сохраняется.
• set_server_password_auth делает то же, что кнопки «Отключить вход по паролю» и «Включить вход по паролю»: записывает настройки в файл в каталоге /etc/ssh/sshd_config.d/, проверяет их, перезагружает конфигурацию SSH и восстанавливает прежние настройки, если какой-то шаг не удался. Отметка в карточке меняется на «Только ключ» или «Пароль + ключ» (Включение и отключение входа по паролю по SSH). Просите ассистента пользоваться этим инструментом, а не править sshd_config командами.

Примеры: «Установи ключ „Рабочий ноутбук“ на сервер IP_СЕРВЕРА», «Какие SSH-ключи установлены на сервере IP_СЕРВЕРА?»

Защита от потери доступа

Ассистенту предписано спрашивать подтверждение, прежде чем удалить ключ с сервера, отключить вход по паролю или заменить ключ агента. Но само окно подтверждения показывает AI-клиент — не отключайте в его настройках одобрение действий.

Важно Защита не заменяет собственную проверку. Прежде чем отключать пароль или удалять ключ, убедитесь в новом терминале, что входите со своим ключом, и не закрывайте текущую сессию. Веб- и VNC-консоли у клиентов нет; если доступ потерян, см. Потерян доступ к серверу (пароль или ключ).

Как отозвать SSH-доступ ассистента

Безопасность Приватный ключ из get_server_ssh_access даёт доступ root — храните его как пароль. Он проходит через AI-клиент и его провайдера, как и любой результат инструментов. Не пересылайте его в мессенджерах и не сохраняйте в репозиториях кода.

1. Отзовите токены, которыми больше не пользуетесь: «Личный кабинет» → «API-токены» → «Отозвать» (API-токены: создание, копирование и отзыв). Иначе любой токен с servers:credentials при следующем вызове вернёт ключ на сервер.
2. Удалите ключ агента в панели: в карточке сервера «Добавить SSH-ключ» → «Установленные ключи» → строка с комментарием blackbox-agent-… → «Удалить», затем подтвердите. Появится сообщение «Ключ удалён.» (Ключи BLACKBOX на вашем сервере).
3. Если SSH-доступ ассистенту ещё нужен, попросите новый ключ с regenerate=true. Вызов без regenerate вернул бы на сервер старый ключ.

Частые ошибки

Полный список: Лимиты и коды ошибок MCP.

Частые вопросы

Почему ассистент говорит, что у него нет инструмента get_server_ssh_access? У токена нет разрешения «Просматривать пароли/доступы к серверам» (servers:credentials). Добавить разрешение к существующему токену нельзя — создайте новый.

Я удалил ключ агента в панели, а он появился снова. Почему? Ассистент с токеном, у которого есть servers:credentials, снова запросил SSH-доступ, и get_server_ssh_access вернул тот же ключ на место. Отзовите неиспользуемые токены или запросите новый ключ с regenerate=true.

Работает ли доступ через ассистента на сервере «Только ключ»? Да. Ключ агента устанавливается через управляющее подключение BLACKBOX, а вход по ключу работает и при отключённом входе по паролю.