## Список рантаймов

`GET /v1/infra/runtimes`

Возвращает список ID готовых рантаймов для передачи в [`POST /v1/infra/servers/:id/deploy`](./deploy.md) (параметр `runtime`). Рантайм — необязательный параметр: если нужный стек входит в список, передайте его ID и платформа установит пакеты автоматически. Если нет — на отдельной виртуальной машине деплой без `runtime` полностью рабочий: установите нужное ПО через `preStart` в теле запроса. У galaxy-приложения `runtime` обязателен, а `preStart` не применяется. На [`POST /v1/infra/servers`](/docs/infra/servers/create) рантайм без `source` НЕ принимается с 2026-04-25 — см. `RUNTIME_PARAM_REMOVED`. В одношаговом создании galaxy-приложения `runtime` передаётся вместе с `source` и `start` в этом же запросе. Каждый рантайм — это набор системных пакетов (nodejs, python, nginx, базы данных), устанавливаемых на сервер. Оценочное время установки — 2–4 минуты для базовых, до 4+ минут для комбинаций с несколькими пакетами.

## Примеры

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

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/runtimes
```

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

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/infra/runtimes
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/infra/runtimes', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data: runtimes } = await res.json()
runtimes.forEach(r => console.log(`${r.id}: ${r.name} (${r.estimatedSetupTime}s)`))
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/infra/runtimes', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив рантаймов |
| `data[].id` | string | ID рантайма, передаётся как `runtime` при деплое (`POST /v1/infra/servers/:id/deploy`) |
| `data[].name` | string | Название для отображения пользователю |
| `data[].packages` | array\<string\> | Список пакетов, устанавливаемых на отдельной виртуальной машине (для справки) |
| `data[].estimatedSetupTime` | number | Оценочное время установки в секундах |
| `data[].supportedPlacements` | array\<string\> | Где рантайм доступен: `["standalone"]` — только отдельная виртуальная машина, `["standalone","galaxy"]` — ещё и галактика. Проверяйте это поле перед деплоем в галактику: рантайм с базой данных туда не ставится |

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

```json
{
  "success": true,
  "data": [
    {
      "id": "node20",
      "name": "Node.js 20",
      "packages": ["nodejs-20", "npm", "pm2"],
      "estimatedSetupTime": 120,
      "supportedPlacements": ["standalone", "galaxy"]
    },
    {
      "id": "node20-pg",
      "name": "Node.js 20 + PostgreSQL",
      "packages": ["nodejs-20", "npm", "pm2", "postgresql-16"],
      "estimatedSetupTime": 180,
      "supportedPlacements": ["standalone"]
    },
    {
      "id": "python311-rag",
      "name": "Python 3.11 + RAG (pgvector + Redis)",
      "packages": ["python3.11", "pip", "postgresql-16", "pgvector", "redis"],
      "estimatedSetupTime": 240,
      "supportedPlacements": ["standalone"]
    }
  ]
}
```

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

401 — не передан API-ключ:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

- **На 2026-04-22 платформа предлагает 15 рантаймов:** шесть вариантов Node.js 20 (чистый, с PostgreSQL, MySQL, Redis, комбинации, RAG-стек), пять вариантов Python 3.11 (аналогично), два варианта PHP 8.3 (чистый и с MySQL) и `static` для SPA-статики. Актуальный снимок всегда — в ответе эндпоинта.
- **Команда запуска зависит от рантайма — её указывают в поле `start` деплоя.** На отдельной виртуальной машине рантайм ставит версионированную команду: `node20*` — `node`, `python311*` — `python3.11`, `php83*` — `php8.3`, `static` — `nginx`. Команды `python` на такой машине нет, а `python3` остаётся системным интерпретатором Ubuntu 24.04 — это версия 3.12. Команда `python3.11` работает и в галактике, поэтому такой `start` подходит обеим моделям размещения. Пакетный менеджер `pip` рантайм привязывает к 3.11, поэтому `pip install` в поле `install` ставит зависимости в тот же интерпретатор, который запускает приложение.
- **Откуда `pip` берёт пакеты.** Платформа задаёт каталог пакетов по умолчанию — зеркало, доступное из нашего облака (сам `pypi.org` оттуда не отвечает: установка зависала бы и сообщала «нет подходящей версии» на существующей версии). Настройка машинная, поэтому её видит и авто-установка `requirements.txt`, и ваша команда в поле `install`, и `pip`, запущенный вручную через `exec`. **Ваш выбор сильнее нашего:** `--index-url` в `requirements.txt` или в команде установки перебивает значение по умолчанию. Переменная `PIP_INDEX_URL` из поля `env` на сборку в галактике НЕ влияет — окружение приезжает в контейнер при запуске, а зависимости ставятся раньше, на сборке образа; на отдельной виртуальной машине она работает. Если вам важна неизменность пакетов — используйте `--require-hashes` с зафиксированными хешами: это единственный механизм, который защищает от подмены на стороне каталога. Менеджеры `poetry` и `uv` нашу настройку не читают — задавайте им индекс их собственными средствами.
- **RAG-рантаймы** (`node20-rag`, `python311-rag`) — готовая среда для схемы RAG (retrieval-augmented generation — ответ LLM с обогащением контекстом из внешних источников): PostgreSQL с расширением pgvector для векторных представлений и Redis для кэша. Сразу после установки можно подключать LlamaIndex / LangChain.
- **`static`** — рантайм для одностраничных приложений и статических сайтов: устанавливает nginx. После установки nginx запускается системным сервисом на порту 80 с конфигурацией по умолчанию и каталогом `/var/www/html` — он **не** раздаёт распакованный архив и не слушает порт 3000. Чтобы отдавать сборку из `/opt/app` на порту 3000 с возвратом на `index.html` для клиентских маршрутов, задайте `preStart`, который создаёт серверный блок nginx и освобождает порт 80, а в `start` запустите nginx на переднем плане:

    ```bash
    # preStart: серверный блок nginx на порту 3000 + отключение системного nginx на порту 80
    cat >/etc/nginx/conf.d/app.conf <<'NGINX'
    server {
      listen 3000 default_server;
      listen [::]:3000 default_server;
      root /opt/app;
      index index.html;
      location / { try_files $uri $uri/ /index.html; }
    }
    NGINX
    rm -f /etc/nginx/sites-enabled/default
    systemctl disable --now nginx
    nginx -t
    ```

    В теле деплоя: `preStart` — команда выше, `start` — `nginx -g 'daemon off;'`, `port` — `3000`, `hardening` — `"off"`. Рецепт рассчитан на отдельную виртуальную машину: у galaxy-приложения поля `preStart` и `hardening` не применяются. Поле `start` обязательно: платформа запускает приложение как systemd-юнит `app.service` и отдельного юнита для nginx рантайм не создаёт. Подходит для сборок React/Vue/Svelte — положите `dist/` в архив.

    Значение `"hardening": "off"` здесь обязательно. По умолчанию платформа запускает приложение под непривилегированной учётной записью, а nginx в этом рецепте пишет служебные файлы и журналы за пределами каталога приложения — под такой учётной записью он не запустится. Платформа вернёт прежний режим сама, но на неудачную попытку и её проверку работоспособности уйдёт около минуты на каждом деплое. Описание поля — [Полный деплой](./deploy.md).
- **Рантаймам `php83`, `php83-mysql` и вариантам с MySQL (`node20-mysql`, `node20-mysql-redis`, `python311-mysql`) нужен `"hardening": "off"`.** После установки MySQL пускает по локальному сокету только администратора, а PHP-FPM работает отдельным системным сервисом — под непривилегированной учётной записью приложение не подключится к базе. Платформа вернёт прежний режим сама, но попытка и её проверка работоспособности займут время на каждом деплое. Передайте `"hardening": "off"` в теле деплоя, чтобы её пропустить. Это не нужно приложениям, которые ходят в MySQL по TCP с паролем.
- **Комбинированные рантаймы работают только на отдельной виртуальной машине.** Суффиксы `-pg` / `-mysql` / `-redis` / `-rag` описывают шаблон отдельной машины: там рядом с языком действительно ставится PostgreSQL / MySQL / Redis. Galaxy-приложение — один контейнер языка на общем хосте, базы данных в нём не поднимаются и переменные подключения (`DATABASE_URL`, `PG*` и т.п.) не проставляются, поэтому деплой такого рантайма в галактику **отклоняется**: ответ `400` с кодом `GALAXY_RUNTIME_DB_UNSUPPORTED`, полем `details.suggestedRuntime` (языковая замена — например `node20` вместо `node20-pg`) и подсказкой. Какие рантаймы куда можно ставить, машинно видно в каталоге [GET /v1/infra/runtimes](./runtimes.md): у каждого элемента есть `supportedPlacements` — `["standalone"]` или `["standalone","galaxy"]`. Поля `name` и `packages` описывают установку на отдельной машине и не меняются. Приложению в галактике нужна база — возьмите языковой рантайм и передайте строку подключения к внешней (managed) БД через `env`, либо разверните приложение на отдельной виртуальной машине с исходным рантаймом.
- **Один и тот же ID рантайма может означать разные патч-версии в галактике и на отдельной виртуальной машине.** В галактике рантайм собирается из официального Docker-образа (`node:20-slim`, `python:3.11-slim`, `php:8.3-cli`, `nginx:alpine`) — версия следует тегу образа. На отдельной виртуальной машине major-версия закреплена и соответствует заявленной (Node.js 20, Python 3.11, PHP 8.3, PostgreSQL 16), патч-версия следует источнику установки. Если критична точная версия — проверяйте её внутри приложения на целевой модели хоста, а не полагайтесь только на ID рантайма.
- **`estimatedSetupTime` — оценочное, не гарантированное.** Зависит от нагрузки apt-зеркал, скорости сети виртуальной машины, конкретной сборки образа Ubuntu. Закладывайте 2× от указанного при автоматизации.
- **Если нужного стека нет в списке — используйте `preStart` на отдельной виртуальной машине.** Сервер — чистая Ubuntu 24.04 с рут-доступом. В поле `preStart` деплоя можно выполнить любые `apt-get install`, скачать бинари, настроить окружение. Результат сохраняется между деплоями (кроме директории `extractTo`, которую очищает `cleanDeploy: true`). Для разовых операций — [`POST /exec`](./exec.md).

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

- [Создать сервер](/docs/infra/servers/create)
- [Полный деплой](./deploy.md)
- [Получить сервер](/docs/infra/servers/get)