Инфраструктура

Создание и управление виртуальными серверами для деплоя приложений Битрикс24. Каждый сервер невидим из интернета по умолчанию (режим Black Hole) — доступ к приложению только через HTTPS-субдомен app-{id}.vibecode.bitrix24.tech. Управление сервером и деплой — через REST API без SSH.

Скоуп: vibe:infra · Базовый URL: https://vibecode.bitrix24.tech/v1 · Авторизация: заголовок X-Api-Key

Разделы документации

• Провайдеры и каталоги — список провайдеров, тарифов, регионов и образов ОС (4 эндпоинта).
• Серверы — создание, список, детали, правка имени и описания, удаление (5 эндпоинтов).
• Жизненный цикл — старт, стоп, сон, пробуждение, ремонт туннеля, статус провижининга (9 эндпоинтов).
• Пробуждение по расписанию — окна автоматического пробуждения спящего сервера по cron-расписанию (4 эндпоинта).
• Доступ и режимы — политика доступа, список пользователей/отделов, SSH-данные, режим BLACKHOLE↔OPEN (7 эндпоинтов).
• Deploy API — выполнение команд, загрузка файлов, логи, деплой приложения, исход и список операций, порт, метрики, лок, рантаймы (10 эндпоинтов).
• Токены доступа — краткосрочные токены для e2e-проверки и распространяемых ссылок (4 эндпоинта, раздел включается на стороне платформы).
• Что приходит в приложение — Gateway подставляет X-Vibe-Authorization: Bearer, чтение данных пользователя через /v1/me, скелеты обработчика на Node/Python/Go.
• Подписки на события портала — доставка событий Битрикс24 (ONTASKADD и подобных) в приложение через туннель, без опроса (3 эндпоинта).
• Доставка вызовов действий и роботов — обработчик действия или робота на субдомене Black Hole: очередь вызовов, пробуждение спящего сервера, регистрация одиночным запросом.
• Galaxy-приложение — режим размещения «контейнер в общей галактике»: как отличить от обычного сервера (kind), жизненный цикл со сборкой при загрузке кода, стоимость за галактику.
• Восстановление доступа к серверу — сервер работает, но новый ключ его не видит: пустой список, 404 NOT_FOUND, смена управляющего ключа.

Что важно знать сразу

1. Порт приложения — всегда 3000. Black Hole туннель проксирует ровно этот порт, менять его не нужно. Сервер — изолированное окружение: :3000 внутри виртуальной машины никак не связан с портами вашей локальной машины.
2. Deploy API — только для BLACKHOLE. Все /deploy, /exec, /upload, /logs требуют серверов в режиме BLACKHOLE со статусом CONNECTED для агента туннеля. Для OPEN-серверов они вернут ошибку.
3. /deploy и /exec отдают JSON по умолчанию. Это безопасно для AI-агентов и MCP-клиентов — никаких дополнительных параметров запроса не нужно. Если вам действительно нужен потоковый ответ (вывод шагов деплоя в реальном времени в UI), передайте ?stream=true — тогда вернётся SSE (Server-Sent Events). Раньше документация утверждала обратное (по умолчанию SSE, ?stream=false для JSON) — это устарело и больше не соответствует поведению API.
4. accessPolicy — это безопасность. Смена политики с OWNER_ONLY на PORTAL/AUTHENTICATED/PUBLIC открывает приложение другим пользователям. Никогда не меняйте accessPolicy без явного подтверждения пользователя.
5. Сервер — это чистая Ubuntu 24.04, рут-доступ включён. Виртуальная машина создаётся из стандартного образа Ubuntu без предустановленного ПО (кроме агента туннеля). Агент работает от имени пользователя root — в preStart, install и командах /exec sudo не нужен. Исходящий интернет доступен без ограничений: apt-get, curl, wget, pip работают напрямую. Входящий трафик заблокирован кроме туннельного соединения. Само приложение при этом запускается не от root, а под выделенной непривилегированной учётной записью — это касается только процесса приложения, команды деплоя и /exec по-прежнему выполняются с правами администратора. Подробности и как отключить — Деплой приложения.
6. Тариф Битрикс24 играет двойную роль. Во-первых, REST API самого Битрикс24 доступен только на коммерческих тарифах портала — без этого не работают ни приложения, ни прокси /v1/deals, ни боты, ни любой другой вызов, который проксируется в Битрикс24. Во-вторых, поверх этого — создание серверов, деплой и пробуждение требуют доступа к платформе, а чем он открывается, зависит от региона портала: в России — активной подпиской BitrixGPT + Маркетплейс, в Казахстане и Узбекистане — платным или демо-тарифом Битрикс24, в Беларуси — платным или демо-тарифом Битрикс24 либо платной подпиской Битрикс24 Маркет Плюс. AI Router работает независимо от тарифа Битрикс24 — он не проксирует в REST и доступен даже на бесплатных тарифах (BYOK бесплатно, платформенные модели тарифицируются с баланса Вайбкод). Подробности — в разделе «Тариф и доступ» ниже.
7. Авторизация пользователя в приложении. На каждом запросе Gateway проставляет шесть заголовков с префиксом X-Vibe-: Request-Id всегда плюс User-Id, User-Name, User-Role, Portal-Id, Authorization (Bearer vibe_session_<…>) для аутентифицированного запроса. Браузер Authorization-токен не видит и не хранит — он живёт только между Gateway и app-сервером. Для быстрого идентификатора пользователя достаточно заголовка X-Vibe-User-Id. Полный контекст (скоупы, capabilities, тариф, информация о приложении) — одним вызовом GET /v1/me с серверным кэшированием. ID пользователя в ответе /v1/me — data.currentUser.bitrixUserId, домен портала — data.portal. Полная таблица заголовков, BFF-паттерн и скелеты обработчика на Node/Python/Go — Что приходит в приложение.
8. Новая машина засыпает через 60 минут простоя. Отдельная виртуальная машина создаётся с таймаутом простоя 60 минут. Простой считается по входящим запросам к приложению — обращениям к его HTTPS-субдомену. Запросы, которые приложение отправляет само наружу, таймер не сбрасывают, поэтому приложение, которое живёт постоянным опросом внешнего API, через час останавливается вместе с машиной. Допустимые значения таймаута и отключение авто-сна значением null — Настроить авто-сон.
9. Создание серверов требует пользовательской сессии для ключей vibe_app_. POST /v1/infra/servers проходит тарифную проверку, которой нужно знать, кто именно создаёт сервер. Для vibe_api_ пользовательский контекст уже есть в самом ключе, для vibe_app_ обязателен Authorization: Bearer <session> — без него ответ 401 UNAUTHENTICATED с error.hint, указывающим на OAuth-авторизацию. Чтение и Deploy API на уже существующих серверах сессии не требуют — таблица «Авторизация эндпоинтов» ниже сводит все правила в одном месте.

Быстрый старт

Три вызова — создание сервера и запуск приложения.

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

export VIBE_KEY="YOUR_API_KEY"

# 1. Создать сервер (автоматически в режиме Black Hole)
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "bitrix-cloud",
    "name": "my-app",
    "plan": "bc-small",
    "region": "ru-central1-b",
    "image": "fd83esfomhq25p2ono90"
  }'

# 2. Отдельная виртуальная машина — дождаться готовности:
#    status=running И blackholeStatus=CONNECTED.
#    Galaxy-приложение (kind=GALAXY_APP в ответе шага 1) этого состояния
#    не достигает — переходите к шагу 3 сразу, см. примечание ниже.
curl -H "X-Api-Key: $VIBE_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID

# 3. Задеплоить приложение (JSON — режим по умолчанию).
#    Пример ниже — для отдельной виртуальной машины: код берётся
#    по внешнему адресу. Galaxy-приложение принимает только встроенный
#    архив — "source": { "content": "<base64>" }, см. примечание выше.
#    X-Skip-Source-Snapshot: деплой с внешнего URL при включённом
#    хранилище исходников, иначе 409 SNAPSHOT_REQUIRED (см. ниже).
curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/deploy" \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Skip-Source-Snapshot: deploy from external URL" \
  -d '{
    "source": { "url": "https://github.com/user/app/archive/main.tar.gz" },
    "runtime": "node20",
    "install": "cd /opt/app && npm install --production",
    "start": "cd /opt/app && node server.js",
    "port": 3000
  }'

Приложение доступно по адресу https://app-{id}.vibecode.bitrix24.tech — поле appUrl в ответе /deploy.

Деплой с внешнего URL и хранилище исходников. Когда на портале включено хранилище исходников, деплой с внешнего адреса — не из хранилища Вайбкод — возвращает 409 SNAPSHOT_REQUIRED, чтобы история версий приложения не терялась. Заголовок X-Skip-Source-Snapshot: <причина> продолжает деплой без сохранения снимка. Чтобы снимок сохранился, сначала загрузите архив через POST /v1/apps/:id/sources, затем разверните его через { "source": { "versionId": "vN" } }. Подробнее — Хранилище исходников.

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

# То же самое, только добавляется заголовок Authorization: Bearer с токеном сессии
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "bitrix-cloud", "name": "my-app", "plan": "bc-small", "region": "ru-central1-b", "image": "fd83esfomhq25p2ono90" }'

Galaxy-приложение — другой контракт. Если портал размещает приложения в галактиках, тот же POST /v1/infra/servers создаёт galaxy-приложение — контейнер на общем хосте. В ответе создания у него kind равен GALAXY_APP, а createdVia — galaxy. Такое приложение до blackholeStatus: "CONNECTED" не доходит: контейнер собирается загрузкой кода, поэтому шаг 2 для него отпадает, а код загружают сразу после создания. Источник кода при этом — встроенный архив в base64, поле source.content. Вариант source.url доступен там, где платформа включила для вас выкладку по ссылке (иначе 400 GALAXY_DEPLOY_CONTENT_ONLY), и ведёт только в хранилище исходников платформы (иначе 400 GALAXY_SOURCE_URL_NOT_ALLOWED), а source.versionId на создании не принимается — сохранённую версию выкладывают вторым шагом, через POST /v1/infra/servers/:id/deploy. Поля runtime и start обязательны. Нужна именно отдельная виртуальная машина — передайте в теле создания поле placement равным dedicated. Полная модель, жизненный цикл, стоимость и отличия деплоя — Galaxy-приложение.

Полный пример

Реалистичный сценарий на JavaScript — создание сервера, ожидание готовности, деплой, получение URL приложения.

const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function api(method, path, body = null, extraHeaders = {}) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY, ...extraHeaders } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  if (!res.ok) throw new Error(`${method} ${path} → ${res.status}`)
  return res.json()
}

// 1. Выбрать провайдера, тариф, регион, образ
const { data: plans } = await api('GET', '/infra/providers/bitrix-cloud/plans')
const { data: regions } = await api('GET', '/infra/providers/bitrix-cloud/regions')
const { data: images } = await api('GET', '/infra/providers/bitrix-cloud/images')

const plan = plans.find(p => p.id === 'bc-small')
const region = regions.find(r => r.id === 'ru-central1-b')
const image = images[0]

// 2. Создать сервер (всегда в Black Hole)
const { data: server } = await api('POST', '/infra/servers', {
  provider: 'bitrix-cloud',
  name: 'my-crm-bot',
  plan: plan.id,
  region: region.id,
  image: image.id,
})
console.log(`Сервер создан: ${server.id}, субдомен: ${server.subdomain}`)

// 3. Отдельная виртуальная машина: ждать running и CONNECTED.
//    Galaxy-приложение (kind === 'GALAXY_APP') этого состояния не достигает —
//    для него шаг пропускается, код загружается сразу.
let info = server
if (server.kind === 'STANDALONE') {
  while (info.status !== 'running' || info.blackholeStatus !== 'CONNECTED') {
    await new Promise(r => setTimeout(r, 10000)) // 10 секунд между опросами
    const res = await api('GET', `/infra/servers/${server.id}`)
    info = res.data
    console.log(`status=${info.status}, blackhole=${info.blackholeStatus}`)
  }
}

// 4. Задеплоить приложение (JSON — режим по умолчанию).
//    Источник кода ниже — внешний адрес, это вариант для отдельной
//    виртуальной машины. Для galaxy-приложения (kind === 'GALAXY_APP')
//    источник только встроенный: source: { content: '<base64>' }.
//    Заголовок X-Skip-Source-Snapshot нужен при деплое с внешнего URL,
//    когда включено хранилище исходников — иначе 409 SNAPSHOT_REQUIRED.
const deploy = await api('POST', `/infra/servers/${server.id}/deploy`, {
  source: { url: 'https://github.com/user/app/archive/main.tar.gz' },
  runtime: 'node20',
  install: 'cd /opt/app && npm install --production',
  preStart: 'cd /opt/app && npx prisma migrate deploy',
  start: 'cd /opt/app && node server.js',
  port: 3000,
  env: { NODE_ENV: 'production' },
}, { 'X-Skip-Source-Snapshot': 'deploy from external URL' })

console.log(`Приложение живёт: ${deploy.data.appUrl}`)

// 5. Изменить таймаут простоя, если 60 минут по умолчанию не подходят.
//    Допустимые значения — 15, 30, 60, 240 и null, который отключает
//    авто-сон. Приложению с постоянным опросом нужен именно null:
//    исходящие запросы таймер простоя не сбрасывают.
await api('PATCH', `/infra/servers/${server.id}/sleep`, { sleepAfterMinutes: 240 })

Справочник эндпоинтов

Справочник эндпоинтов раздела. Ссылки ведут на страницы с параметрами, примерами и кодами ошибок.

Провайдеры и каталоги:

Серверы:

Жизненный цикл:

Пробуждение по расписанию:

Доступ и режимы:

Deploy API:

Токены доступа:

Подписки на события портала:

Авторизация эндпоинтов

Все инфра-эндпоинты требуют заголовок X-Api-Key. Для ключей vibe_app_ (привязка к OAuth-приложению) часть POST-операций дополнительно требует Authorization: Bearer <session> — без него ответ 401 UNAUTHENTICATED с error.hint. Для ключей vibe_api_ пользовательский контекст уже есть в самом ключе, отдельная сессия не нужна.

Быстрая проверка до вызова: GET /v1/me → data.capabilities.servers.create.available. Для vibe_app_ без сессии возвращается false с reason: "SESSION_REQUIRED" и подсказкой в userMessage — модель сразу видит, что нужно пройти OAuth-авторизацию, а не ловить 401 на самом POST /v1/infra/servers.

Лимиты

Ограничение частоты запросов платформы — общее для всех V1-эндпоинтов, см. раздел «Лимиты и оптимизация».

Статусы сервера

Поле blackholeStatus описывает состояние туннеля агента независимо от status:

Поле kind различает модель размещения: STANDALONE — отдельная виртуальная машина, GALAXY_APP — galaxy-приложение (контейнер в галактике), GALAXY — сама галактика (хост-носитель — её создаёт платформа, не пользователь). У galaxy-приложения blackholeStatus остаётся NONE до загрузки кода — оно не подключается само. Подробнее — Galaxy-приложение.

Поле runtimeStatus — устаревшее, оставлено для совместимости. Для серверов, созданных после 2026-04-25 (когда параметр runtime был убран из POST /v1/infra/servers), всегда возвращается null. Рантайм теперь ставится на этапе POST /:id/deploy, а сигналом готовности служит сам успех шага runtime в ответе деплоя.

Тариф и доступ

У инфраструктуры Вайбкод два уровня условий по доступу.

Уровень 1 — REST API Битрикс24. Сам Битрикс24 открывает REST API только на коммерческих тарифах портала. Это не про Вайбкод: на бесплатных тарифах Битрикс24 попросту не отдаёт REST-ответы. Значит, без коммерческого тарифа Битрикс24 не работают:

• Создание и публикация приложений (POST /api/apps) — регистрируется на портале через REST.
• REST-прокси: /v1/deals, /v1/contacts, /v1/batch, /v1/bots, /v1/tasks и все остальные сущности.
• Боты, чаты, задачи — всё, что проксирует в Битрикс24.

Уровень 2 — Вайбкод-инфраструктура. Сверх первого условия, создание серверов, деплой и пробуждение требуют активной подписки Маркетплейса на портале ЛИБО платного или демо-тарифа Битрикс24. Что из этого — разбирает абзац сразу под списком. Операции этого уровня:

• POST /v1/infra/servers — создание сервера.
• POST /v1/infra/servers/:id/deploy — деплой приложения.
• POST /v1/infra/servers/:id/wake и автоматическое пробуждение при preventWake=true.
• Создание агентов и управляемых ботов (они провижинят серверы под капотом).

Чем открывается доступ, зависит от региона портала. В России — активной подпиской BitrixGPT + Маркетплейс на портале. В Казахстане и Узбекистане — платным или демо-тарифом Битрикс24. В Беларуси доступ открывает любой из трёх путей: платный тариф Битрикс24, демо-тариф Битрикс24 или платная подписка Битрикс24 Маркет Плюс.

Что работает на любом тарифе Битрикс24, включая бесплатный:

• AI Router — POST /v1/chat/completions, POST /v1/audio/transcriptions, GET /v1/models. Не проксирует в Битрикс24, напрямую ходит к провайдерам LLM. С BYOK-ключами — бесплатно, с платформенными моделями — тарифицируется с баланса Вайбкод.
• Базовые эндпоинты платформы: GET /v1/me, GET /v1/feedback, GET /v1/guide — для самоориентации AI-агента.

Проверка до вызова: GET /v1/me → поле capabilities.servers.create.available. Если false — поле capabilities.servers.create.userMessage содержит переведённое объяснение для пользователя.

Принудительное обновление после повышения тарифа: GET /v1/me?refresh=tariff — пропускает кэш, по умолчанию часовой, и запрашивает тариф у Битрикс24 заново.

Доступ к серверам: единственный признак — capabilities.servers.create в ответе GET /v1/me (см. выше). Если доступ закрыт, POST /v1/infra/servers вернёт 402 с кодом проверки доступа (см. «Коды ошибок» ниже). Чем управляется доступ, зависит от региона портала — разбор в «Тариф и доступ» выше.

Заголовки ответа инфра-эндпоинтов:

Коды ошибок проверки доступа перечислены в разделе «Коды ошибок» ниже.

Windows / PowerShell и UTF-8

Кириллица в displayName и description сервера может превратиться в знаки вопроса (?), если запрос отправляется из Windows PowerShell без явной сериализации в UTF-8. Это не проблема отображения на стороне платформы — кириллические байты теряются ещё до отправки HTTP-запроса, на стороне клиента.

Причина. По умолчанию PowerShell перекодирует строку из параметра -Body у Invoke-WebRequest и Invoke-RestMethod в системную кодировку windows-1251, и кириллица теряется ещё до сборки запроса. Заголовок Content-Type: charset=utf-8 здесь не помогает — к моменту его применения исходные байты уже потеряны.

Решение. Передавайте тело запроса массивом байтов UTF-8.

# 1. Кодировка вывода консоли — на кодирование тела запроса не влияет
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# 2. Собрать JSON и преобразовать его в массив UTF-8 байтов
$body = @{
  displayName = 'Уведомления клиентов'
  description = 'Бот отправляет уведомления по сделкам'
} | ConvertTo-Json -Compress

$bytes = [System.Text.Encoding]::UTF8.GetBytes($body)

# 3. Передать в -Body массив байтов, а не строку, и указать кодировку в Content-Type
Invoke-WebRequest `
  -Uri 'https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID' `
  -Method PATCH `
  -Headers @{
    'X-Api-Key'    = 'YOUR_API_KEY'
    'Content-Type' = 'application/json; charset=utf-8'
  } `
  -Body $bytes

Распространённые ошибки:

• Сохранять .ps1 с UTF-8 BOM — старые версии PowerShell могут не разобрать сам скрипт.
• Передавать в -Body строку $body вместо массива байтов $bytes — строка повторно перекодируется через системную кодировку.
• Полагаться только на Content-Type: application/json; charset=utf-8 без UTF8.GetBytes — этот заголовок не восстанавливает потерянные байты, а лишь объявляет серверу заявленную кодировку тела.

Та же сериализация нужна везде, где вы передаёте отображаемое имя и описание: создание сервера, правка имени и описания и деплой приложения — оттуда эти значения попадают в карточку приложения в каталоге Битрикс24.

Node.js (fetch) и Python (requests) кодируют тело в UTF-8 сами, дополнительных шагов не требуется. Проблема специфична для PowerShell.

Коды ошибок

Ошибки инфраструктуры

Ошибки Deploy API

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

В потоковом режиме (?stream=true) отказ приходит SSE-событием error с полями code и message — так отдаёт /exec и деплой при исключении или обрыве транспорта. У деплоя провал отдельного шага приходит иначе — событием step со status: "error" и именем шага. Поля success в потоке нет.

Ошибки проверки доступа и биллинга

Системные ошибки

Полный справочник общих ошибок — Ошибки.

Иконка приложения

Иконка приложения (SVG) показывается в каталоге Битрикс24 и как фавикон во вкладке браузера. Формат, требования и порядок (фавикон-<link> до деплоя, загрузка POST /v1/infra/servers/:id/icon после) — на отдельной странице Иконка приложения.

Рецепты

• Загрузка дампа БД на сервер — залить дамп и восстановить базу в фоне через exec.
• Быстрый цикл выпуска — сократить цикл правок без полного прогона всех шагов.

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

• Обзор API
• Лимиты и оптимизация
• Ключи и авторизация (/v1/me)
• Что приходит в приложение