Выполнение команд на сервере через AI
Как ассистент выполняет команды от root, лимиты времени и вывода и правила для долгих и интерактивных команд.
На этой странице
Инструмент MCP run_server_command позволяет AI-ассистенту, подключённому к вашему аккаунту через https://api.app.blackbox.md/mcp (Claude, Cursor, VS Code и др.), выполнять shell-команды от root на ваших серверах: ставить пакеты, читать журналы, перезапускать службы. Право на это даёт API-токен, созданный на blackbox.md: «Личный кабинет» → «API-токены» (/account/api-tokens).
Доступно: владельцу аккаунта blackbox.md — через API-токен с разрешением «Выполнять любые команды от root на моих серверах» (servers:exec). Работает на серверах, которые вы заказали, и на серверах компании, где BLACKBOX выдал вам права управления. На серверах с отметкой «Обслуживается» в панели app.blackbox.md (только просмотр) ответ — not_found.
Как это работает
- Ассистент передаёт ID сервера, команду и, при необходимости, максимальное время ожидания.
- BLACKBOX подключается к серверу по SSH под
rootс ключом управления (в панели он называется «Ключ управления (blackbox.md)»), выполняет команду и возвращает результат ассистенту. Ни пароль, ни ключ ассистенту давать не нужно. - Каждый вызов открывает новую сессию, которая начинается в каталоге
/root.cdи переменные окружения между командами не сохраняются: связанные шаги объединяйте в одну команду через&&или используйте абсолютные пути. - Команды ничем не фильтруются: на сервере ассистент может всё, что может
root.
Как попросить ассистента выполнить команду
- На blackbox.md в разделе «Личный кабинет» → «API-токены» создайте токен с отмеченным разрешением «Выполнять любые команды от root на моих серверах». Оставьте отмеченным и «Читать список и статус моих серверов» (
servers:read): без него ассистент не узнает ID сервера. Подробно: API-токены: создание, копирование и отзыв. - Добавьте токен в AI-клиент: Подключение в приложении Claude (пользовательский коннектор) или Подключение из Claude Code, Cursor, VS Code и других клиентов.
- Опишите задачу своими словами и назовите сервер (имя или IP), например: «Установи nginx на мой сервер» или «Покажи, чем занят диск на сервере IP_СЕРВЕРА».
- Как правило, AI-клиент просит подтвердить вызов
run_server_commandи показывает текст команды. Прочитайте команду и подтверждайте, только если понимаете, что она делает. - Ассистент получит результат и расскажет, что произошло.
Параметры и результат
| Параметр | Значения | Примечание |
|---|---|---|
server_id |
ID из ответа list_servers |
неверный ID даёт invalid_server_id или not_found |
command |
от 1 до 8192 символов | пустая команда, команда из одних пробелов или длиннее лимита даёт invalid_command |
timeout_seconds |
от 1 до 300 секунд, по умолчанию 60 | значение вне диапазона приводится к ближайшей границе (600 станет 300), ошибки не будет |
| Поле результата | Что в нём |
|---|---|
exit_code |
код завершения: 0 — успех, другое число — ошибка; null, если время ожидания истекло |
timed_out |
true, если время истекло раньше, чем команда завершилась |
stdout, stderr |
стандартный вывод и вывод ошибок, не более 64 000 символов каждый |
stdout_truncated, stderr_truncated |
true, если вывод обрезан; в конце текста стоит ...[truncated, N more chars]. Если время ожидания истекло, этих полей в результате нет |
duration_ms |
длительность в миллисекундах |
Если процесс завершён сигналом, exit_code — номер сигнала со знаком минус (например, -9 после kill -9) или 128 плюс номер сигнала (137), если о завершении сообщила оболочка (зависит от того, как записана команда). -1 возвращается, когда сервер не сообщил ни код, ни сигнал; тогда stderr заканчивается строкой [terminated by signal]. Неожиданный -9 или 137 обычно означает принудительное завершение, часто из-за нехватки памяти.
Команды без вопросов
Команда выполняется без терминала (TTY), а стандартный ввод закрыт. Поэтому:
- любой вопрос вроде «Do you want to continue? [Y/n]» и любой запрос пароля завершаются ошибкой;
- программы с собственным экраном (
nano,vim,top, консольmysql) не работают; - команды, которые сами не завершаются (
tail -f, сервер, запущенный не в фоне), работают до истечения времени ожидания.
| Вместо | Используйте |
|---|---|
apt install nginx |
DEBIAN_FRONTEND=noninteractive apt-get install -y nginx |
dnf install nginx |
dnf install -y nginx |
top |
top -b -n 1 |
tail -f /var/log/nginx/error.log |
tail -n 100 /var/log/nginx/error.log |
journalctl -u nginx -f |
journalctl -u nginx -n 100 --no-pager |
консоль mysql |
mysql -e "SHOW DATABASES;" |
правка в nano |
sed -i для точечной замены или перезапись файла целиком |
Долгие команды
По умолчанию ассистент ждёт завершения команды 60 секунд и может увеличить это время до 300 секунд. Если время истекло, результат приходит без ошибки: timed_out: true, exit_code: null и вывод, который успел появиться. BLACKBOX процесс не останавливает: он может продолжать работать на сервере.
Важно После
timed_out: trueне просите повторить ту же команду: установка или обновление, запущенные дважды, могут зависнуть или что-то сломать. Сначала отдельной командой проверьте процесс, журнал или состояние службы.
Работу дольше нескольких минут (обновление системы, резервное копирование, сборку) просите запускать в фоне и проверять результат позже.
Параметры --force-confdef и --force-confold в примерах для Ubuntu и Debian сохраняют конфигурационные файлы, которые вы меняли. Без них обновление остановится с ошибкой на первом же вопросе о таком файле.
С nohup
Перенаправляйте вывод в файл, как в примерах: иначе вызов будет ждать процесс до истечения времени ожидания.
Ubuntu и Debian:
nohup bash -c 'DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold upgrade' > /root/upgrade.log 2>&1 &AlmaLinux и CentOS Stream:
nohup dnf -y upgrade > /root/upgrade.log 2>&1 &Проверка позже. Если pgrep ничего не вывел, работа закончена, а результат — в конце журнала:
pgrep -a 'apt-get|dnf'
tail -n 30 /root/upgrade.logС systemd-run
Задача запускается как временная служба, а её вывод попадает в системный журнал.
Ubuntu и Debian:
systemd-run --unit=upgrade-job bash -c 'DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold upgrade'AlmaLinux и CentOS Stream:
systemd-run --unit=upgrade-job dnf -y upgradeПроверка позже. active — задача ещё выполняется, inactive — завершилась успешно, failed — остановилась с ошибкой:
systemctl is-active upgrade-job
journalctl -u upgrade-job -n 50 --no-pagerЧто должно быть на сервере
- ключ управления (в панели — «Ключ управления (blackbox.md)») в
/root/.ssh/authorized_keys; - вход
rootпо ключу разрешён:PermitRootLogin prohibit-password(илиyes), но неno; - сервер запущен и доступен по SSH на порту 22. BLACKBOX подключается только к этому порту, а новый порт может блокировать сетевой фильтр BLACKBOX: прежде чем переносить SSH на другой порт или открывать порт 22 только для своего IP-адреса, напишите в поддержку.
Проверьте действующее значение:
sshd -T | grep -i permitrootloginПодходят результаты permitrootlogin yes, permitrootlogin prohibit-password и permitrootlogin without-password (старое название того же значения).
Если вы просите ассистента изменить настройки SSH или файрвола, держите открытой вторую SSH-сессию, пока не убедитесь, что можете подключиться заново. Веб-консоли и VNC для клиентов нет: если доступ потерян, помочь сможет только поддержка. Что делать, если ключ управления удалён: Ключи BLACKBOX на вашем сервере.
Лимиты и ошибки
Ассистент может выполнить не больше 30 команд в минуту на аккаунт (для всех токенов вместе), а на все инструменты MCP вместе действует лимит 120 вызовов в минуту. Длина команды, время ожидания и объём вывода ограничены, как описано выше.
| Ошибка | Что значит | Что делать |
|---|---|---|
invalid_command |
команда пустая, состоит из одних пробелов или длиннее 8192 символов | проверьте команду; если она слишком длинная, разбейте её на несколько команд |
ssh_connection_failed |
BLACKBOX не смог подключиться: сервер остановлен, перезагружается или не отвечает, ключ управления удалён либо root больше не может входить по ключу |
убедитесь, что сервер работает (Перезагрузка, остановка и запуск сервера), и повторите один раз через минуту; если ошибка не уходит, проверьте условия выше или напишите в поддержку: Как связаться с поддержкой BLACKBOX |
not_found, invalid_server_id |
сервера нет, он не ваш, доступен только для просмотра или ID в неверном формате | попросите ассистента взять ID из list_servers |
rate_limited |
превышен один из лимитов | подождите минуту; вызовы, сделанные во время блокировки, тоже засчитываются |
missing_scope: this token does not have 'servers:exec' |
у токена нет нужного разрешения | создайте новый токен: разрешения существующего изменить нельзя |
Полный список: Лимиты и коды ошибок MCP.
Конфиденциальность и безопасность
BLACKBOX фиксирует только сам факт выполнения команды: сервер, время, длительность, код завершения, длину команды и её отпечаток (хеш). Текст команды и её результат не сохраняются, истории команд в панели нет. При этом поставщик AI-ассистента видит и команду, и всё, что она вернула: без необходимости не просите выводить файлы с паролями и ключами (например, .env).
Опасно Команда от
rootможет удалить данные или закрыть доступ к серверу, а BLACKBOX команды не фильтрует. Перед важными изменениями сделайте резервную копию: Стратегия резервного копирования для вашего сервера.
- BLACKBOX требует от ассистента спрашивать вас перед действиями, которые стоят денег, отменой заказа, удалением SSH-ключей или отключением входа по паролю, но не перед выполнением команд на сервере. Подтверждение в AI-клиенте — единственная проверка, поэтому не включайте для
run_server_commandпостоянное разрешение без подтверждения. - Заведите для
servers:execотдельный токен и отзовите его, когда он станет не нужен: Безопасность токенов и AI-агентов.
Безопасность Когда ассистент читает содержимое из ненадёжных источников (веб-страницы, журналы, письма, чужие файлы), текст оттуда может «попросить» его выполнить команды. Если предложенная команда не связана с вашей задачей, отклоните её.
Частые вопросы
Ассистент говорит, что у него нет инструмента run_server_command. Почему?
У токена нет разрешения servers:exec, а инструменты без разрешения ассистенту не показываются. Создайте новый токен с разрешением «Выполнять любые команды от root на моих серверах» и замените им старый в клиенте.
Нужен ли sudo?
Нет, команды и так выполняются от root. Чтобы выполнить что-то от имени другого пользователя:
runuser -u ИМЯ_ПОЛЬЗОВАТЕЛЯ -- КОМАНДАМожно ли отключить вход по паролю по SSH командой?
Не меняйте PasswordAuthentication командами. Попросите ассистента воспользоваться инструментом set_server_password_auth или нажмите в панели «Отключить вход по паролю» / «Включить вход по паролю»: и инструмент, и кнопки проверяют конфигурацию и не оставят вас без доступа (Включение и отключение входа по паролю по SSH).
Можно ли работать интерактивно или копировать файлы?
Через run_server_command — нет. Для rsync, scp или SSH-сессии в вашем терминале ассистент может запросить SSH-доступ: SSH-доступ и SSH-ключи через AI-ассистента.