Выполнить команду

POST /v1/infra/servers/:id/exec

Выполняет shell-команду на BLACKHOLE-сервере через агент туннеля. Полный стандартный вывод (stdout), поток ошибок (stderr) и код возврата передаются клиенту. По умолчанию ответ — JSON после завершения команды (рекомендуется для AI-агентов и скриптов). На STANDALONE для построчного прогресса передайте ?stream=true и читайте SSE-события stdout/stderr/exit. Отказ при выполнении команды приходит в потоковом режиме событием error.

Для AI-агентов и MCP-клиентов обязательно используйте JSON-режим (без ?stream=true) — SSE они разбирать не умеют. Официальный MCP-клиент платформы Вайбкод (инструмент manage_server_deploy) снимает этот параметр сам и всегда работает в JSON-режиме.

Потоковый режим даёт живой прогресс, но не увеличивает предельное время выполнения: синхронный предел одинаков для JSON и потокового режима и равен timeout + 30 секунд, а сам timeout ограничен 600 секундами. На STANDALONE для более долгой работы с сохранением результата используйте async=true — см. «Durable exec — длительная команда» ниже. Другой вариант — самостоятельно управлять фоновой задачей.

На каких серверах работает

Тип сервера приходит в поле kind ответов GET /v1/infra/servers и GET /v1/infra/servers/:id.

Параметры

Поля запроса (body)

Проверка по OpenAPI. Стандартный requestBody допускает timeout до 86400 секунд, чтобы обычные валидаторы и сгенерированные клиенты принимали поддерживаемые запросы async=true на STANDALONE. Схема тела не учитывает параметр async: синхронный API по-прежнему отклоняет timeout больше 600 секунд, даже если стандартная схема пропускает тело. Контракты по режимам описаны в #/components/schemas/InfraSyncExecRequest (до 600 секунд) и #/components/schemas/InfraDurableExecRequest (до 86400 секунд). Расширение x-vibe-request-schema проверяет собранные {query,body} с учётом режима; вид сервера проверяется во время исполнения.

Расширение x-vibe-request-schema проверяет собранный объект {query, body}: предел таймаута по режиму и допустимое сочетание async/stream. Вид сервера проверяется при вызове API; выбор схемы длительного тела не отменяет требование STANDALONE.

Для workdir очистка пути предшествует проверке. Следующие префиксы запрещены даже внутри разрешённого корня: /etc/shadow, /etc/passwd, /etc/sudoers, /etc/cron, /etc/ssh/, /root/.ssh/, /root/.gnupg/, /root/.bashrc, /root/.profile, /root/.bash_history. Запрещённый путь даёт EXEC_WORKDIR_DENIED, недоступная директория — EXEC_WORKDIR_NOT_FOUND, путь к файлу — EXEC_WORKDIR_NOT_DIR. Длительный запрос может получить HTTP 502 за запрещённый путь до запуска; принятая задача возвращает последующие проверки директории через операцию. См. коды отказа длительного exec.

Примеры

curl — личный ключ

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/exec" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la /opt/app", "timeout": 30}'

curl — OAuth-приложение

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/exec" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm ci --production", "workdir": "/opt/app", "timeout": 180}'

JavaScript — личный ключ

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/exec`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      command: 'node -v',
      timeout: 10,
    }),
  }
)
const { data } = await res.json()
console.log(`exit ${data.exitCode} за ${data.duration}ms:\n${data.stdout}`)

JavaScript — OAuth-приложение

// Команда с переменными окружения и рабочей директорией
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/exec`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      command: 'npx tsx scripts/seed.ts',
      workdir: '/opt/app',
      env: { DATABASE_URL: 'postgresql://localhost/mydb' },
      timeout: 60,
    }),
  }
)

Поля ответа

Длительный ответ 202 не содержит вывода команды или кода возврата. Сохранённые поля читайте через разрешённую ручку исхода операции.

Пример ответа

{
  "success": true,
  "data": {
    "exitCode": 0,
    "stdout": "Linux epd65hdv07p8g89c0c06 6.8.0-107-generic #107-Ubuntu SMP PREEMPT_DYNAMIC Fri Mar 13 19:51:50 UTC 2026 x86_64 x86_64 x86_64 GNU/Linux\n",
    "stderr": "",
    "duration": 5,
    "truncated": false,
    "operationId": "clz9k2m4x0001qw8h3f7d2n5q"
  }
}

Длительная команда отдельной машины принята (202):

{
  "success": true,
  "data": {
    "operationId": "clz9k2m4x0001qw8h3f7d2n5q",
    "status": "running",
    "statusUrl": "/v1/infra/operations/clz9k2m4x0001qw8h3f7d2n5q"
  }
}

Пример ответа при ошибке

409 EXEC_BUSY — приём команд занят. Отказ платформенного лока возвращает сигналы повтора из этого примера:

{
  "success": false,
  "error": {
    "code": "EXEC_BUSY",
    "message": "Another operation is running on this server",
    "retryable": true,
    "retryAfter": 10
  }
}

Если ответ содержит retryable: true и retryAfter, он также несёт заголовок Retry-After с тем же интервалом в секундах. Соблюдайте этот интервал; поле error.hint.autoExpiresInSeconds, если оно есть, задаёт полный верхний предел жизни лока. Агентский отказ длительному запуску возвращает error.operationId без retryable, retryAfter и Retry-After. Прочитайте эту операцию до нового запроса exec; неизвестный исход требует сверки состояния и независимого подтверждения остановки команды.

Ошибки

Ошибки эндпоинта делятся на две группы, и отдаются они по-разному. Отказ до запуска команды приходит с настоящим HTTP-статусом. Отказ во время выполнения приходит в теле ответа на отдельной виртуальной машине (kind: "STANDALONE"). У galaxy-приложения (kind: "GALAXY_APP") он приходит со статусом 502, и исключений там два: занятость exec-канала (EXEC_BUSY) приходит настоящим 409, потому что это отказ «занято», а не сбой, а EXEC_NO_EXIT — с 200 и success: false.

Ошибки до запуска команды

Отказы после приёма длительной задачи

HTTP 202 может предшествовать отказу, обнаруженному до запуска пользовательской команды. Опрашивайте возвращённую операцию; status: "failed" и data.error.code обозначают доказанный отказ, а unknown не разрешает новый exec. Истёкшее окно запуска или отказ рабочей директории описаны в таблице отказов длительного exec. Неизвестный исход имеет data.error: null; отсутствие кода ошибки не означает успех.

Ошибки во время синхронного выполнения

HTTP-статус не отражает результат команды. На отдельной виртуальной машине (kind: "STANDALONE") соединение удерживается на всё время выполнения, а статус 200 отправляется до его начала — поэтому и успешная, и провалившаяся команда приходят с кодом 200. Признак отказа — поле success: false и объект error в теле ответа. Проверяйте success в теле, а не HTTP-статус: клиент, который ветвится по статусу, посчитает провалившуюся команду успешной. У galaxy-приложения (kind: "GALAXY_APP") та же ошибка приходит со статусом 502. Исключений два, те же, что в таблице видов сервера выше: EXEC_BUSY приходит как 409, а EXEC_NO_EXIT — как 200 с success: false. Поэтому проверять success в теле нужно на обоих видах серверов.

Состав `hint` у `EXEC_TIMEOUT`

Подсказка приходит в JSON-ответе и SSE-событии error. Агентский EXEC_BUSY на обоих поддерживаемых видах сервера использует GET /v1/infra/servers/:id/operations?kind=exec как recoveryAction. Сначала прочитайте исход операции. /unstick нужен только при подтверждённой утечке синхронного мьютекса независимо подтверждённой простаивающей отдельной машины. На STANDALONE работающая длительная задача занимает канал после освобождения платформенного лока с 202. Опрашивайте её операцию; при неизвестном исходе нужны поддержка и независимое подтверждение полной остановки. Отсутствие autoExpiresInSeconds не доказывает утечку мьютекса. Восстановление туннеля и удаление лока не снимают ограничение приёма длительной задачи. В Galaxy команды выполняются синхронно с пределом 600 секунд и общим каналом для всех приложений и выкладок; задача соседнего приложения может не попасть в ваш список операций, поэтому пустой список не доказывает простой хоста.

Отказ связи с туннелем приходит в том же виде — со своим кодом в поле error.code (например TUNNEL_NOT_FOUND или GATEWAY_TIMEOUT: …). Часть gateway-кодов несёт детали после двоеточия (GATEWAY_UNREACHABLE: …, GATEWAY_TIMEOUT: …), поэтому сопоставляйте error.code по префиксу, а не по точному совпадению. В потоковом режиме (?stream=true) эти же ошибки приходят SSE-событием error. Данные события несут code и message, а у EXEC_TIMEOUT, GATEWAY_TIMEOUT и агентского EXEC_BUSY — ещё и hint. Подсказка у GATEWAY_TIMEOUT говорит главное: код возврата не получен, поэтому исход команды неизвестен и она может продолжать выполняться на сервере — не запускайте её повторно вслепую, сначала проверьте состояние. Поля success в них нет — признаком отказа служит само событие error.

Полный список общих ошибок API — Ошибки.

Известные особенности

• Спящую отдельную виртуальную машину команда будит сама. Если сервер (kind: "STANDALONE") в статусе sleeping, платформа запускает пробуждение и ждёт его в том же запросе — до 6.5 минут, и только потом выполняет команду. Отдельный вызов /wake не нужен, но клиентский таймаут запроса это время обязан пережить. Если сервер не поднялся, приходит 503 WAKE_TIMEOUT и сервер возвращается в sleeping — команда не выполнялась, повторный запрос безопасен.
• Команда исполняется через /bin/sh. Поле command запускается интерпретатором /bin/sh — это минимальный POSIX-шелл (dash), не bash. Конструкции, специфичные для bash (set -o pipefail, [[ … ]], массивы), в нём недоступны и завершаются ошибкой. Запускайте их явно — через command: "bash -c 'set -o pipefail; …'" либо файлом-скриптом command: "/bin/bash /opt/app/script.sh".
• Блокировка на уровне сервера. Синхронный /exec и /deploy берут платформенный лок; окно лока синхронного exec — timeout + 90 секунд, deploy — 15 минут. Длительный exec отдельной машины освобождает этот лок после 202, но занимает свой канал на всё время задачи с запрошенным таймаутом до 86400 секунд. Проверка завершения может продлить занятость сверх таймаута команды. Неизвестный исход требует проверки и подтверждения остановки; /unstick и DELETE /lock не снимают ограничение длительной задачи. Exec Galaxy синхронный, ограничен 600 секундами, а канал хоста общий для всех приложений и выкладок. Зависший синхронный лок восстанавливайте только после независимого подтверждения простоя по состоянию сервера и логам.
• Общий максимум вывода — 1 МиБ (1 048 576 байт), суммарно на stdout и stderr. Это один бюджет на два потока, а не по 1 МиБ на каждый: если команда пишет и в stdout, и в stderr, обрезка считается по их сумме. Когда вывод больше лимита, приходит truncated: true и хвост обрезается. Команда при этом отработала, exitCode корректный. Для большого вывода перенаправляйте в файл: command: "my-cmd > /opt/app/output.log 2>&1" и потом читайте через /exec cat /opt/app/output.log.
• .env из /deploy не загружается автоматически. Systemd подгрузит .env при старте сервиса, но не для разовых команд через /exec. Если нужны DATABASE_URL / API-ключи — передавайте в поле env: { env: { DATABASE_URL: "..." } }.
• Два таймаута в сумме дают timeout + 30 секунд. Агент убивает процесс ровно по timeout. Gateway ждёт ещё 30 секунд на финальные события и только потом отдаёт EXEC_TIMEOUT.
• Поддержание соединения в JSON-режиме. Если команда выполняется дольше 15 секунд, сервер периодически шлёт пробелы в тело ответа — это предотвращает таймауты nginx и промежуточных прокси. Пробелы идут внутри уже открытого JSON-объекта, поэтому тело с первого байта выглядит как JSON ({), а не начинается с пробелов: и строгие клиенты, и обычные парсеры читают его одинаково, снимать пробелы вручную не нужно.
• Клиентский таймаут: убедитесь, что он межбайтовый, а не общий. Keepalive-пробелы сбрасывают таймауты «на тишину», поэтому классические сокет-таймауты Python (urlopen(..., timeout=300), read-таймаут requests) сами по себе долгую команду в JSON-режиме не оборвут. Обрывают две другие вещи. Первая — клиенты и обёртки с настоящим wall-clock-дедлайном на весь запрос (например, aiohttp с ClientTimeout(total=…) или собственный дедлайн агент-фреймворка): keepalive против них бессилен. Вторая — серверный параметр timeout самой команды (по умолчанию 300 секунд): по его истечении агент завершает процесс и приходит EXEC_TIMEOUT независимо от клиентских настроек — не путайте с обрывом на своей стороне. Практика: в Python задавайте раздельные таймауты — requests.post(url, json=body, headers=headers, timeout=(10, 60)) — 10 секунд на connect и 60 на паузу между байтами. В синхронном режиме, если клиент оборвал соединение, лок на сервере держится ещё до timeout + 90 секунд (EXEC_BUSY для повторных вызовов). Команды дольше нескольких минут надёжнее запускать фоновой задачей — см. «Фоновые задачи» ниже. На спящем сервере это правило вступает в силу не сразу: пробелы идут только после пробуждения, поэтому до первого байта ответа проходит до 6.5 минут полной тишины, и рецепт timeout=(10, 60) оборвёт запрос ещё до запуска команды. Либо поднимите межбайтовый таймаут выше этого окна, либо разбудите машину заранее вызовом /wake с wait=true и вызывайте /exec уже на готовой.

Принудительное освобождение канала

На STANDALONE EXEC_BUSY без autoExpiresInSeconds может означать работающую длительную задачу, а не утечку мьютекса агента. Сначала прочитайте исход операции или найдите запуск в списке операций сервера с kind=exec. Пока задача работает, ждите. Исход unknown не подтверждает остановку: сверьте состояние и логи и обратитесь в поддержку. Не разрывайте туннель и не удаляйте лок работающей или неподтверждённой длительной задачи; /unstick не снимает её ограничение приёма. Используйте POST /v1/infra/servers/:id/unstick для восстановления лока только после независимого подтверждения простоя, с учётом ограничений этой ручки.

Как выбрать режим

Четыре режима вызова и когда каждый уместен:

Для синхронного exec общий дедлайн запроса на стороне клиента не ставьте меньше значения timeout команды — иначе клиент оборвёт соединение раньше, чем сервер успеет ответить. Спящий сервер добавляет к этому дедлайну до 6.5 минут на пробуждение — пример ниже рассчитан на уже запущенную машину. Пример раздельных таймаутов для Python:

import requests
r = requests.post(
    f"{VIBE_URL}/v1/infra/servers/{SERVER_ID}/exec",
    headers={"X-Api-Key": VIBE_API_KEY},
    json={"command": "npm ci --production", "workdir": "/opt/app", "timeout": 600},
    timeout=(10, 60),   # 10 секунд на соединение, 60 на паузу между байтами
)

Поднять timeout у /exec шагу install не поможет — у шагов деплоя свой предел в 300 секунд, отдельный от синхронного предела 600 у /exec.

Важно: умолчание timeout — 300 секунд, а не 600. Синхронный потолок 600 существует, но чтобы им воспользоваться, поле надо передать явно. Команда, рассчитанная на девять минут и запущенная без timeout, будет снята на пятой.

Если ожидание оборвалось

Транспортный таймаут, разрыв соединения или перезапуск клиента прекращают только ожидание ответа. Команда на сервере при этом не останавливается и может доработать до конца уже после того, как клиент получил ошибку. Поэтому повторный запуск изменяющей команды может применить изменение второй раз.

Чтобы этого избежать, принятый запуск обычно получает идентификатор — но это не гарантия: если в синхронном режиме платформа не смогла завести запись, идентификатора не будет, а команда всё равно выполняется. В длительном режиме отдельной машины запись обязательна, и идентификатор возвращается с 202. Когда он есть, он приходит тремя каналами:

• заголовок ответа X-Vibe-Operation-Id — на отдельной виртуальной машине уходит до начала выполнения команды, поэтому доживает до клиента даже когда тело ответа потеряно. У синхронного exec galaxy-приложения он приходит только с терминальным ответом: эта ветка не открывает поток, поэтому при обрыве ожидания идентификатор до клиента не доезжает и запуск ищется в списке операций сервера с ?kind=exec,
• первый кадр event: operation при ?stream=true — только у синхронного exec на отдельной виртуальной машине. Браузерный EventSource заголовков ответа не отдаёт, поэтому для него это единственный ранний канал,
• поле operationId в теле — data.operationId при успехе, error.operationId при отказе.

Порядок восстановления:

1. Не повторяйте изменяющую команду вслепую.
2. Запросите GET /v1/infra/operations/:operationId. Если идентификатор потерян, найдите запуск в списке операций сервера с параметром ?kind=exec.
3. Статус succeeded означает, что команда отработала до конца, а её собственный вердикт лежит в exitCode. Повторять не нужно.
4. Статус failed платформа ставит, только когда может доказать, что команда не запускалась, — например при EXEC_BUSY. Это доказывает только отказ этой попытке. При EXEC_BUSY сначала сверьте занявшую канал операцию, включая прежнюю попытку с потерянным подтверждением; неизвестный исход занятой операции не разрешает новый exec.
5. Статус unknown означает, что исход не доказан и команда может выполняться прямо сейчас. Сверьтесь с состоянием сервера и журналом до решения о повторе.

Для синхронного exec запись хранит исход попытки — статус, код возврата и причину отказа — без вывода команды. С async=true stdout/stderr сохраняются в операции; другой вариант — самостоятельно управлять фоновой задачей и читать журнал.

Фоновые задачи

Для синхронного JSON и потокового exec timeout ограничен 600 секундами, а по его истечении агент завершает всю процесс-группу принудительно (SIGKILL, без grace-паузы). На отдельной машине для более долгих операций — установки пакетов, восстановления дампа БД, тяжёлой сборки — используйте долговременный async=true, если нужен сохранённый вывод. Другой вариант — самостоятельно управлять фоновой задачей: /exec вернётся мгновенно, канал освободится (второй вызов не упрётся в EXEC_BUSY), а процесс продолжит работать независимо от HTTP-соединения.

Рекомендуемый способ — транзиентный systemd-юнит

{ "command": "systemctl reset-failed restore-db 2>/dev/null; systemd-run --unit=restore-db /bin/bash /opt/data/restore.sh", "timeout": 30 }

Задача получает собственный cgroup и живёт независимо от exec-сессии. Управление — стандартными вызовами:

• статус: { "command": "systemctl is-active restore-db" } — active (идёт), inactive (завершилась успешно), failed (упала).
• логи: journald подхватывает вывод юнита автоматически — читайте через GET /v1/infra/servers/:id/logs?service=restore-db.
• systemctl reset-failed <имя> перед повторным запуском — иначе systemd откажет в создании юнита с именем упавшей задачи.

Лёгкий вариант — фон с редиректом вывода

{ "command": "(cd /opt/app && npm run build > /tmp/build.log 2>&1 &)", "timeout": 10 }

Редирект обоих потоков в файл обязателен — он освобождает пайпы exec-сессии. Прогресс: { "command": "tail -20 /tmp/build.log" }.

Анти-паттерн — голый `nohup`

nohup cmd & без редиректа не работает: в пайпе (а не терминале) nohup не перенаправляет вывод, фоновый процесс наследует пайп exec-сессии, агент ждёт его закрытия до самого timeout — и затем принудительно завершает всю процесс-группу, включая ваш «фоновый» процесс. Всегда добавляйте > файл 2>&1.

Не вставляйте значения секретов в command. На отдельной машине передавайте их через env; в galaxy-приложении загружайте внутри контейнера из существующего защищённого файла или настроенного хранилища секретов приложения. Синхронный exec журналирует на агенте первые 200 символов команды. Длительный worker отключает этот журнал, но сама команда может раскрыть секреты через вывод или дочерние процессы. Помните также, что шаги install/preStart у /deploy имеют собственный таймаут 300 секунд — тяжёлые установки выносите в разовый /exec или фоновую задачу, а не в install-скрипт.

Durable exec — длительная команда

Для долгой команды вызовите POST /v1/infra/servers/:id/exec?async=true только на сервере STANDALONE. Ответ: HTTP 202, X-Vibe-Operation-Id и data: {operationId, status: "running", statusUrl}. Опрашивайте GET /v1/infra/operations/:operationId; после потери подтверждения не отправляйте второй /exec. Если идентификатор потерян, найдите запуск в списке операций сервера с kind=exec.

Тело принимает timeout от 1 до 86400 секунд (по умолчанию 300). async=true несовместим с stream=true. Любой другой вид сервера получает 400 DURABLE_EXEC_UNSUPPORTED_SERVER_KIND до блокировки, создания операции и отправки команды, без синхронного перехода. Exec Galaxy остаётся синхронным с пределом 600 секунд. Исполнение, не поддерживающее длительные задачи, отказывает до запуска; синхронного перехода нет.

Задача переживает потерю HTTP-ответа и переподключение. Её канал занят на всё время задачи, хотя после 202 платформенный лок освобождён; другие exec и команды выкладки получают EXEC_BUSY. Читайте операцию вместо повторного exec или вызова /unstick. Завершённая операция отдаёт stdout, stderr, duration в миллисекундах, truncated и доказанный exitCode; общий предел вывода — 1 МиБ. Вывод хранится зашифрованным в семидневном окне исхода. Приватный вывод доступен только ключу в области операции, принадлежащему пользователю-создателю: ротация ключа того же владельца сохраняет доступ, передача другому владельцу — нет. succeeded включает ненулевой код выхода; unknown не разрешает повтор команды. Перезагрузка машины или потеря процесса могут оставить неизвестный исход, требующий проверки и подтверждения остановки. Чтение сверяет результат без запуска команды. Отмена и автоматический повтор недоступны.

Исполнение хранит не более 64 записей задач на отдельной машине, включая завершённые задачи в семидневном окне хранения. При заполнении новая команда отклоняется до исполнения с HTTP 502 EXEC_JOB_CAPACITY и error.operationId. Сначала прочитайте операцию, затем дождитесь допустимой очистки по сроку хранения или обратитесь в поддержку; автоматического повтора нет. Очистка при приёме запроса удаляет только просроченные результаты с подтверждённой остановкой. Если задача прервана до сохранения результата, подтверждённая остановка оставляет исход unknown, но через семь суток запись допускается к штатной очистке. Активные задачи и неподтверждённая остановка не очищаются только потому, что прошло семь суток. /unstick и удаление лока не снимают ограничение приёма длительной задачи.

Смотрите также

• Полный деплой
• Исход операции
• Последние операции сервера
• Снять зависший лок
• Логи сервиса
• Загрузить файл
• Восстановить туннель
• Быстрый цикл выпуска
• Galaxy-приложение