> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Настройка сеансов в самостоятельно размещаемых окружениях > Настройте сеансы самостоятельно размещаемого окружения с помощью скриптов-оболочек для учетных данных для каждого сеанса, хуков жизненного цикла и порождения средств выполнения по требованию. Самостоятельно размещаемые окружения находятся в публичной бета-версии на планах Team и Enterprise; [владелец](/docs/ru/cloud-environments#organization-shared-environments) включает их, активируя **Allow self-hosted environments** на [странице администратора **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). На этой странице предполагается наличие работающего средства выполнения; см. [краткое руководство](/docs/ru/self-hosted-environments-quickstart) для настройки и [Deploy to production](/docs/ru/self-hosted-environments-deploy) для рецептов флота. [Самостоятельно размещаемое окружение](/docs/ru/self-hosted-environments) запускает [облачные сеансы](/docs/ru/claude-code-on-the-web) Claude Code на вашей собственной инфраструктуре, выполняемые процессом средства выполнения, который вы развертываете. Без конфигурации это средство выполнения клонирует репозиторий сеанса, порождает Claude Code и выполняет очистку. Эта страница предназначена для инженера платформы, управляющего средствами выполнения: она охватывает точки расширения для случаев, когда эти значения по умолчанию не подходят, от подготовки учетных данных для каждого сеанса до полной замены checkout. Оболочки и хуки запускаются как исполняемые файлы на хосте средства выполнения, который работает на Linux или macOS, и примеры на этой странице предполагают оболочку POSIX. Несколько переменных окружения хука на этой странице по-прежнему используют `pool`, такие как `CLAUDE_RUNNER_POOL_ID`; флаги CLI и имена переменных окружения используют `environment`, такие как `--environment-secret-file`.

Скрипты-оболочки

Используйте скрипт-оболочку, когда каждому сеансу требуется настройка, которую средство выполнения не может выполнить самостоятельно: подготовка краткосрочных учетных данных, ограниченных создателем сеанса, экспорт секретов, специфичных для окружения, подготовка цепочек инструментов языка или применение ограничений ресурсов вокруг дочернего процесса. Средство выполнения запускает вашу оболочку вместо двоичного файла Claude Code один раз за сеанс. Завершите оболочку, выполнив `exec` в `$CLAUDE_RUNNER_CLAUDE_BIN`, собственный двоичный файл средства выполнения, чтобы сигналы и коды выхода распространялись правильно. Укажите `--exec-path` или `SELF_HOSTED_RUNNER_EXEC_PATH` на оболочку при запуске средства выполнения: ```bash theme={null} claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --exec-path /etc/claude/session-wrapper.sh ``` Средство выполнения устанавливает следующие переменные в окружении оболочки: | Переменная | Описание | | :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | JWT сеанса с префиксом `sk-ant-cc-`. Его утверждение `act` идентифицирует создателя сеанса с электронной почтой создателя и предметом поставщика удостоверений вышестоящего уровня, когда поверхность создания записала их. Значение — это токен во время порождения; обновления поступают через stdin дочернего процесса, поэтому оболочка видит только начальное значение. См. [Verify session identity](/docs/ru/self-hosted-environments-identity). | | `CCR_SESSION_ACCOUNT_EMAIL` | Электронная почта создателя сеанса, предварительно извлеченная средством выполнения из утверждения `act.email` токена без проверки подписи. Подходит для маркировки, такой как трейлеры коммитов. Когда электронная почта управляет выдачей учетных данных, проверьте токен и прочитайте утверждение из него вместо этого; см. [Provision credentials scoped to the session creator](#provision-credentials-scoped-to-the-session-creator). Не установлена, когда токен не содержит электронную почту создателя. Рассматривайте как личную информацию. | | `CLAUDE_RUNNER_CLIENT_PLATFORM` | Поверхность клиента, которая создала сеанс, такая как `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` или `scheduled_trigger`. Anthropic записывает значение один раз при создании сеанса, поэтому оболочка и каждый хук жизненного цикла видят одно и то же значение. Используйте его только для аналитики внедрения и маркировки, а не как сигнал авторизации. Не установлена, когда сеанс не имеет записанной или распознанной поверхности, поэтому ссылайтесь на нее как `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` под `set -u`. Требует Claude Code v2.1.229 или позже. | | `CLAUDE_RUNNER_CLAUDE_BIN` | Абсолютный путь к собственному двоичному файлу Claude Code средства выполнения. Завершите вашу оболочку с помощью `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` для передачи закрепленному двоичному файлу без жесткого кодирования пути установки. | | `CLAUDE_CODE_REMOTE_SESSION_ID` | ID сеанса в форме с тегом `cse_...`. Это тот же сеанс, который [хуки жизненного цикла](#lifecycle-hooks) видят как `CLAUDE_RUNNER_SESSION_ID` в форме `session_...`; переменные UUID совпадают в обоих случаях, и замена префикса `cse_` на `session_` дает ID, показанный в URL сеанса. | | `CLAUDE_CODE_REMOTE_SESSION_UUID` | Тот же ID сеанса в канонической форме UUID для систем, которые используют UUID в качестве ключа. | | `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Абсолютный путь к файлу для каждого сеанса, содержащему текущий JWT сеанса, поддерживаемый в актуальном состоянии при обновлении токенов. Подпроцессы оболочки читают его для своего заголовка `Authorization` при загрузке вложений, которые пользователь добавил в сеанс. `exec` сохраняет переменную автоматически; оболочка, которая перестраивает окружение дочернего процесса, должна перенести переменную, иначе загрузки вложений молча прекратятся. | | `CLAUDE_CONFIG_DIR` | Каталог конфигурации Claude для каждого сеанса, написанный при запуске сеанса из снимка конфигурации хоста средства выполнения, который средство выполнения захватывает при запуске; см. [Permissions and tool approval](#permissions-and-tool-approval). Записи здесь изолированы для этого сеанса. | | `ANTHROPIC_BASE_URL` | URL базы API, который будет использовать дочерний процесс, доставленный плоскостью управления для каждого сеанса и обычно `https://api.anthropic.com`. Не переопределяйте его: учетные данные вывода сеанса — это выданный Anthropic токен OAuth, который другие поставщики не принимают, поэтому вывод в самостоятельно размещаемых окружениях не маршрутизируется в другие места. | | `CLAUDE_CODE_OAUTH_TOKEN` | Краткосрочный токен доступа OAuth, который дочерний процесс использует для вывода модели, ограниченный выводом модели и загрузкой файлов только, с временем жизни около 30 минут. Средство выполнения переминтирует его перед истечением и доставляет ротацию через stdin дочернего процесса, поэтому оболочка, которая не [сохраняет stdin прикрепленным](#keep-stdin-and-file-descriptor-3-attached), видит только начальное значение. Не полагайтесь на список разрешенных IP-адресов вашей организации для ограничения использования этого токена: рассматривайте его как учетные данные носителя, которые остаются пригодными для использования примерно 30 минут при утечке, и не логируйте его, не записывайте на диск и не пересылайте вне контейнера сеанса. | Оболочка также наследует остальную часть управляемого окружения дочернего процесса, включая любые переменные окружения, предоставленные сервером. `exec` распространяет все это автоматически; если ваша оболочка порождает дочерний процесс другим способом, пересылайте полное окружение.

Сохраняйте stdin и дескриптор файла 3 прикрепленными

stdin дочернего процесса — это канал управления средства выполнения. Ротации токенов и сигналы конца сеанса поступают на него. Средство выполнения также открывает канал на дескриптор файла 3 и читает сигналы активности дочернего процесса из него для управления тайм-аутами простоя и запуска. Простой `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` сохраняет оба автоматически. Если ваша оболочка переводит дочерний процесс в фоновый режим с помощью простого `&`, она разрывает stdin дочернего процесса: сеанс выглядит здоровым до истечения примерно 30-минутного времени жизни начального токена OAuth, затем каждый вызов API не выполняется с `401 authentication_error`. Если ваша оболочка должна переводить дочерний процесс в фоновый режим, например для сохранения ловушки разборки, сохраните stdin на дескриптор файла 4 или выше и повторно прикрепите его явно: ```bash theme={null} exec 4<&0 "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&4 4<&- & CHILD=$! trap 'teardown' EXIT wait "$CHILD" ``` Не закрывайте и не переиспользуйте дескриптор файла 3 в оболочке. Перенаправление stdout и stderr дочернего процесса в порядке.

Подготовка учетных данных, ограниченных создателем сеанса

Используйте подкоманду `decode-token` для чтения утверждений из JWT сеанса. Она читает токен из аргумента, из `CLAUDE_CODE_SESSION_ACCESS_TOKEN` или из stdin в этом порядке; см. [Verify the token inside the session](/docs/ru/self-hosted-environments-identity#verify-the-token-inside-the-session) для того, что она проверяет. Пример ниже декодирует идентификацию создателя, обменивает его на краткосрочные учетные данные AWS и выполняет exec в Claude Code: ```bash theme={null} #!/bin/bash # Key on the stable Anthropic user ID and require a human creator. CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \ | jq -re '.act.sub // "" | select(startswith("user:"))') \ || { echo "decode-token: verification failed or no human creator" >&2; exit 1; } creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \ || { echo "credential exchange failed" >&2; exit 1; } eval "$creds" exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" ``` Используйте `jq -re` вместо `jq -r`, когда извлеченное утверждение управляет решением авторизации, чтобы отсутствующее утверждение выходило с ненулевым кодом вместо передачи буквальной строки `null` вниз по потоку. Сеансы, созданные удостоверением услуги организации, такие как сеансы ботов и агентов, содержат предмет `agent:` вместо `user:`, поэтому этот пример отказывает им; если ваше окружение обслуживает эти сеансы, явно решите, должна ли оболочка вернуться к учетным данным по умолчанию для них вместо выхода. Когда обмен учетными данными нуждается в предмете SSO или электронной почте вместо этого, прочитайте `.act.attested_by.sub` или `.act.email` и обработайте их отсутствие: токен содержит их только когда поверхность создания записала их, и [сеанс, отправленный CLI](/docs/ru/self-hosted-environments-testing#run-the-test-loop), может не иметь ни того, ни другого. Для полной справки утверждений и проверки из служб вне средства выполнения см. [Verify session identity](/docs/ru/self-hosted-environments-identity).

Lifecycle hooks

Lifecycle hooks заменяют этапы конвейера runner'а для каждой сессии вашими собственными скриптами. Укажите runner'у на директорию с hooks с помощью `--hooks-dir ` или `SELF_HOSTED_RUNNER_HOOKS_DIR`. Runner ищет исполняемые файлы с известными именами; любой hook, который отсутствует, переходит к встроенному поведению, поэтому вам нужно написать только те, которые вам нужны. Hooks запускаются с собственными привилегиями runner'а, и дочерние процессы сессии используют тот же UID, поэтому монтируйте директорию hooks в режиме только для чтения или встраивайте её в образ, чтобы код сессии не мог её изменять; см. [раздел об усилении безопасности](/docs/ru/self-hosted-environments-deploy#harden-your-deployment). Эти hooks отличаются от [Claude Code hooks](/docs/ru/hooks), которые запускаются внутри сессии; lifecycle hooks запускаются на runner'е, вокруг сессии.

checkout

Запускается один раз на репозиторий вместо встроенного клонирования и получения данных runner'а. Используйте hook для клонирования из зеркала сквозного доступа, инициализации рабочего дерева из архива или применения аутентификации git для каждой сессии. Runner устанавливает: | Variable | Description | | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CLAUDE_RUNNER_REPO_URL` | URL репозитория для клонирования, после применения любых `--git-host-rewrite` и `--git-ssh-rewrite` | | `CLAUDE_RUNNER_REPO_REF` | Ревизия для проверки: ветка, тег или SHA коммита, как её запросила сессия. Пусто означает ветку по умолчанию репозитория. | | `CLAUDE_RUNNER_CHECKOUT_PATH` | Абсолютный путь, где должно остаться рабочее дерево | | `CLAUDE_RUNNER_SESSION_ID` | ID сессии в форме с тегом `session_...`, для логирования и корреляции | | `CLAUDE_RUNNER_SESSION_UUID` | Тот же ID сессии в канонической форме UUID | | `CLAUDE_RUNNER_API_BASE_URL` | Базовый URL API Anthropic для вызовов в области сессии | | `CLAUDE_RUNNER_CLIENT_PLATFORM` | Поверхность клиента, которая создала сессию, такая как `web_claude_ai`, `desktop_app` или `ios`. Не установлено, когда сессия не имеет записанной или распознанной поверхности. | | `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Токен доступа сессии для вызовов API в области сессии | Скрипт должен оставить рабочее дерево в `CLAUDE_RUNNER_CHECKOUT_PATH`, проверенное на запрошенной ревизии. Отсоединённая HEAD в порядке; runner создаёт рабочую ветку сессии сверху. Runner проверяет, что путь содержит `.git` после этого; если ваш hook материализует источник, не основанный на git, такой как Perforce или распакованный tarball, установите `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` в окружении runner'а, чтобы пропустить эту проверку. Потоки на основе Git, такие как создание рабочей ветки и отправка результатов, требуют проверки git, поэтому экспортируйте результаты из деревьев, не основанных на git, с помощью [`post-session` hook](#post-session). Runner не передаёт учётные данные git в hook. Вместо этого создайте учётные данные клонирования для каждой сессии из идентификации сессии: проверьте `CLAUDE_CODE_SESSION_ACCESS_TOKEN` с помощью стандартной библиотеки JWT для конечной точки JWKS под `CLAUDE_RUNNER_API_BASE_URL`, как описано в [Verify the token from your service](/docs/ru/self-hosted-environments-identity#verify-the-token-from-your-service), затем попросите вашу службу учётных данных выдать краткосрочные учётные данные клонирования для идентификации в утверждении `act` токена. `CLAUDE_RUNNER_CLAUDE_BIN` не установлен в окружении checkout-hook, поэтому подкоманда `decode-token` недоступна здесь. Возврат к любой аутентификации git, которая уже есть на хосте, такой как SSH агент, помощник учётных данных или `.netrc`, также является вариантом. Когда hook завершается с ненулевым кодом или завершается с кодом 0 без оставления пригодной для использования проверки, то, что делает runner, зависит от репозитория: * **Репозиторий, в который сессия отправляет результаты**: runner отмечает сеанс как неудачный, и при ненулевом выходе выводит пользователю конец stderr скрипта. * **Репозиторий, из которого сессия только читает**, такой как репозиторий, добавленный к запущенной сессии: runner логирует строку `[runner:warn]` с деталями отказа, отправляет шаг `Skipped` в сессию, удаляет всё, что hook оставил в пути проверки, и продолжает с оставшимися репозиториями. Когда runner не может немедленно удалить путь, он повторяет удаление в конце сессии. Если пропуск оставляет сессию вообще без репозитория, runner отмечает сеанс как неудачный в любом случае. До v2.1.228 runner отмечал сеанс как неудачный при отказе hook для любого репозитория, поэтому репозиторий только для чтения, который hook не мог обслуживать, отмечал сеанс как неудачный снова при каждом новом runner'е, на котором сессия возобновлялась. Runner удаляет путь проверки после завершения сессии.

post-session

Запускается один раз на сессию, после выхода дочернего процесса Claude Code и перед тем, как runner разбирает рабочее пространство. Этот hook — ваш единственный шанс сохранить незафиксированную работу: при `--capacity` выше одного runner удаляет рабочие деревья для каждой сессии сразу после возврата hook'а, а при `--capacity 1` переиспользуемый [канонический клон](/docs/ru/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout) жёстко сбрасывается при запуске следующей сессии, поэтому незафиксированные отслеживаемые изменения не сохраняются ни в одном случае. Типичные применения — отправка ветки снимка незафиксированных изменений, архивирование логов или отправка события завершения сессии в ваши собственные системы. Hook срабатывает при каждом завершении сессии, где был порождён дочерний процесс, независимо от причины; значения `CLAUDE_RUNNER_EXIT_REASON` ниже перечисляют случаи. Он не может срабатывать, когда runner завершается неожиданно, такой как вытеснение VM или потеря питания; если вам нужны гарантии против неожиданного завершения, делайте снимки периодически изнутри сессии с помощью Claude Code `PostToolUse` hook вместо этого. Runner устанавливает: | Variable | Description | | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLAUDE_RUNNER_SESSION_ID` | ID сессии в форме с тегом `session_...` | | `CLAUDE_RUNNER_SESSION_UUID` | Тот же ID сессии в канонической форме UUID | | `CLAUDE_RUNNER_EXIT_REASON` | Как завершилась сессия; см. значения ниже таблицы | | `CLAUDE_RUNNER_WORKSPACE_PATHS` | Разделённые двоеточиями абсолютные пути рабочих деревьев сессии. Пусто для сессий с нулевым репозиторием. | | `CLAUDE_RUNNER_DEBUG_LOG_PATH` | Путь к логу отладки сессии, всё ещё на диске во время выполнения hook'а | | `CLAUDE_RUNNER_API_BASE_URL` | Базовый URL API Anthropic для вызовов в области сессии | | `CLAUDE_RUNNER_CLIENT_PLATFORM` | Поверхность клиента, которая создала сессию, такая как `web_claude_ai`, `desktop_app` или `ios`. Не установлено, когда сессия не имеет записанной или распознанной поверхности. Требует Claude Code v2.1.229 или позже. | | `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Токен доступа сессии для вызовов API в области сессии | `CLAUDE_RUNNER_EXIT_REASON` принимает одно из четырёх значений: * `completed`: сессия завершилась чисто. Процесс Claude Code завершился нормально, или сессия была архивирована или удалена, пока она всё ещё работала. * `failed`: процесс Claude Code упал, или настройка не удалась после его запуска. * `interrupted`: runner остановил сессию. Он освободил сессию, чтобы освободить слот, сессия истекла при запуске, сервер переместил сессию с этого runner'а, runner был в режиме дренирования, или сессия превысила свой лимит [`--kill-session-after-min`](/docs/ru/self-hosted-environments-reference#runner-cli-flags). * `abandoned`: зарезервировано для сессии, которую заявил другой runner. Hook в настоящее время не срабатывает в этом случае. [Счётчики жизненного цикла сессии](/docs/ru/self-hosted-environments-reference#session-lifecycle-counter-semantics) считают освобождение, истечение времени при запуске и перемещение сервера как `completed` вместо `interrupted`, потому что runner чисто вернул слот. Ожидайте этого различия, если вы сравниваете квитанции hook'а со счётчиками. Статус выхода hook'а никогда не влияет на результат сессии; отказ логируется и игнорируется. Runner ждёт до `--post-session-hook-timeout-sec`, 60 секунд по умолчанию, при каждом завершении сессии, включая завершение runner'а. Этот пример сохраняет незафиксированную работу в ветку спасения: ```bash theme={null} #!/usr/bin/env bash set -u IFS=':' # Pin config the session could have planted in the checkout's .git/config: # -c overrides beat repo-local settings, blocking session-written fsmonitor, # hook-path, and gpg-program config from executing code with the hook's # privileges. Repo-local credential.helper, core.sshCommand, and pushurl # still apply; if the hook holds credentials the session didn't, pin the # push URL and helper too (see the note below the script). g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \ -c commit.gpgsign=false "$@"; } for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do cd "$ws" 2>/dev/null || continue [ -z "$(g status --porcelain 2>/dev/null)" ] && continue g add -A g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true done ``` Hook отправляет с любыми учётными данными git, доступными в его собственном окружении на хосте runner'а. При [позиции без учётных данных в образе](/docs/ru/self-hosted-environments-deploy#configure-git), включая когда встроенный клон проходит через прокси git Anthropic, их нет, поэтому создайте краткосрочные учётные данные отправки внутри hook'а перед отправкой: обменяйте токен сессии, который hook получает в `CLAUDE_CODE_SESSION_ACCESS_TOKEN`, с вашей собственной службой токенов, проверив его как [Verify session identity](/docs/ru/self-hosted-environments-identity) описывает. Когда hook держит учётные данные, которые сессия не держала, также закрепите, где он отправляет: замените `origin` на предоставленный оператором URL и передайте `-c credential.helper=` плюс ваш собственный помощник, чтобы конфиг, который сессия написала, не мог перенаправить учётную отправку.

Hook timing when the runner releases a session

Освобождённая сессия может возобновиться на другом runner'е. На runner'е версии 2.1.236 или позже то, что сессия делала при освобождении, решает, может ли она возобновиться до завершения этого hook'а: * **Неактивна после хода или истекла при запуске**: runner останавливает дочерний процесс и запускает этот hook до завершения. Только после этого он освобождает сессию. Сообщение пользователя, отправленное во время выполнения hook'а, не может возобновить сессию на другом runner'е до завершения hook'а. * **Ожидание ответа пользователя на подсказку, такую как подсказка разрешения**: runner сначала освобождает сессию, затем запускает этот hook. Сообщение пользователя, отправленное во время выполнения hook'а, может возобновить сессию на другом runner'е до завершения hook'а. Это применяется всякий раз, когда runner освобождает сессию: при истечении времени неактивности, при [`--retire-at`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) времени и, на runner'е версии 2.1.260 или позже, при лимите [`--kill-session-after-min`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) сессии. Сессия, чей ход закончился и которая содержит только фоновые задачи, считается неактивной здесь. До v2.1.236 runner сначала освобождал сессию, а затем запускал этот hook в обоих случаях. Во время дренирования `SIGTERM` runner держит аренду сессии до завершения hook'а; см. [Shutdown timing](/docs/ru/self-hosted-environments-deploy#shutdown-timing).

command

Запускается один раз на сессию после checkout, вместо встроенного порождения дочернего процесса. Hook получает то же окружение, что и [wrapper script](#wrapper-scripts), и должен `exec` в `"$CLAUDE_RUNNER_CLAUDE_BIN"` таким же образом. Используйте `command` hook, чтобы держать всю настройку в одной директории hooks; используйте `--exec-path`, когда wrapper находится в другом месте. Если `--exec-path` также установлен, флаг имеет приоритет и `command` hook игнорируется. Всегда `exec` собственный бинарный файл runner'а вместо разрешённого PATH `claude`; иначе вы нарушите [закрепление версии](/docs/ru/self-hosted-environments-deploy#pin-the-version).

Средства выполнения по требованию

Вместо запуска фиксированного флота вы можете загрузить одно средство выполнения за сеанс. Оркестратор — это отдельная, без состояния подкоманда, которая опрашивает Anthropic на предмет запросов на порождение, по одному за сеанс, который находится в очереди без доступного средства выполнения, и запускает ваш хук `spawn-runner` для каждого. Ваш хук отправляет рабочую нагрузку на вашу платформу: Kubernetes Job, экземпляр EC2, Nomad dispatch. Средства выполнения по требованию улучшают гигиену учетных данных. На фиксированном флоте секрет окружения находится на каждом хосте средства выполнения, который является тем же хостом, на котором запускается код пользователя. С оркестратором секрет окружения остается только на хосте оркестратора, который никогда не запускает код пользователя; каждое порожденное средство выполнения получает одноразовый наряд на работу, который регистрирует ровно одно средство выполнения и затем истекает. Чтобы запустить оркестратор, передайте секрет окружения и каталог хуков, содержащий исполняемый скрипт `spawn-runner`: ```bash theme={null} claude self-hosted-runner orchestrator \ --environment-secret-file /etc/claude/environment-secret \ --hooks-dir /etc/claude/hooks ``` Оркестратор не сохраняет состояние между опросами, поэтому вы можете запустить две или более реплик против одного и того же окружения для доступности. Каждый запрос на порождение заявляется на стороне сервера ровно одной репликой. Все реплики должны использовать одно и то же значение `--expected-spawn-seconds`; см. [контракт хука](#the-spawn-runner-hook).

Хук spawn-runner

Оркестратор запускает `${hooks-dir}/spawn-runner` один раз за запрос на порождение. Хук должен отправить работу асинхронно, без ожидания загрузки средства выполнения, и вернуться в течение `--hook-timeout`, 60 секунд по умолчанию. Хук получает: | Переменная | Описание | | :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLAUDE_RUNNER_WORK_ORDER_FILE` | Путь к временному файлу, содержащему подписанный JWT наряда на работу, с которым регистрируется новое средство выполнения. Удалено после выхода хука. Не логируйте содержимое файла. | | `CLAUDE_RUNNER_ORDER_ID` | Непрозрачный ключ идемпотентности, уникальный для каждого запроса на порождение и безопасный для имен ресурсов Kubernetes. Используйте его как ключ дедупликации вашего провизионера. | | `CLAUDE_RUNNER_SESSION_ID` | Сеанс, для которого предназначен этот запрос. Пусто для запросов предварительного прогрева, которые загружают резервное средство выполнения перед любым конкретным сеансом, когда установлен [`--min-idle`](/docs/ru/self-hosted-environments-reference#orchestrator-cli-flags), поэтому не предполагайте, что переменная установлена. | | `CLAUDE_RUNNER_SESSION_UUID` | Тот же ID сеанса в канонической форме UUID. Пусто для запросов предварительного прогрева. | | `CLAUDE_RUNNER_ATTEMPT` | Сколько запросов на порождение было у этого сеанса. `0` для запросов предварительного прогрева. | | `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Время сервера из заголовка HTTP `Date` ответа опроса. Когда хук проверяет `exp` JWT наряда на работу, сравнивайте с этим значением вместо локальных часов, чтобы допустить перекос. Пусто, когда шлюз опустил заголовок. | | `CLAUDE_RUNNER_POOL_ID` | ID окружения, к которому должно присоединиться новое средство выполнения, в форме `ccpool_...` | | `CLAUDE_RUNNER_ACCOUNT_ID` | Помеченный ID учетной записи, которая поставила сеанс в очередь, для маршрутизации по учетной записи, квоты или возврата средств. Пусто, когда недоступно, и всегда пусто для сеансов канала Claude Tag, которые не ставит в очередь ни одна учетная запись. | | `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Электронная почта учетной записи, которая поставила сеанс в очередь. Пусто, когда недоступно. Рассматривайте электронную почту как личную информацию и не логируйте ее. | | `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL первого источника git сеанса для маршрутизации на средство выполнения с этим репозиторием предварительно прогретым. Пусто, когда сеанс не имеет источников git. | | `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Ревизия первого источника git сеанса: ветка, SHA или тег. Пусто, когда не указано. | | `CLAUDE_RUNNER_REPO_SOURCES` | JSON массив `{url, revision}` для всех источников git сеанса для хуков, которые маршрутизируют на вторичный репозиторий. Пусто, когда нет источников. | | `CLAUDE_RUNNER_CORRELATION_ID` | ID корреляции, предоставленный при создании сеанса, повторно отправленный, чтобы хук мог сопоставить этот наряд на работу с запросом, который создал сеанс. Пусто, когда сеанс не имеет ни одного. | | `CLAUDE_RUNNER_CLIENT_PLATFORM` | Поверхность клиента, которая создала сеанс, такая как `web_claude_ai`, `desktop_app`, `ios` или `scheduled_trigger`, для аналитики внедрения. Не установлена, когда сеанс не имеет записанной или распознанной поверхности, и для запросов предварительного прогрева; проверьте ее с помощью `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, что остается безопасным под `set -u`. | Порожденное средство выполнения регистрируется с нарядом на работу вместо секрета окружения: * **Запустите его с нарядом на работу**: укажите [`--environment-secret-file`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) на файл, содержащий JWT наряда на работу, или установите `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` на значение JWT. * **Скопируйте JWT перед выходом хука**: оркестратор удаляет файл наряда на работу после выхода хука, поэтому скопируйте JWT в рабочую нагрузку, которую вы отправляете, такую как Kubernetes Secret на порожденном Job, вместо передачи пути файла. * **Используйте `--capacity 1` на порожденных средствах выполнения**: наряд на работу, привязанный к сеансу, регистрирует ровно одно средство выполнения, привязанное к этому сеансу, поэтому более высокая емкость добавляет слоты, которые никогда не получают работу, и средство выполнения логирует предупреждение при запуске. * **Нарядные работы предварительного прогрева регистрируют без привязки**: резервное средство выполнения не привязано к сеансу и заявляет поставленную в очередь работу, как средство выполнения фиксированного флота. Контракт имеет четыре правила, независимые от провизионера: 1. **Будьте идемпотентны на `CLAUDE_RUNNER_ORDER_ID`.** Переделивка одного и того же запроса должна порождать не более одного средства выполнения. Выведите детерминированное имя ресурса из ID и позвольте вашей платформе отклонить дубликат. 2. **Не повторяйте рабочую нагрузку.** Один ID заказа означает не более одной созданной рабочей нагрузки. Если средство выполнения никогда не регистрируется, Anthropic повторно запрашивает с новым ID заказа после `--expected-spawn-seconds`. 3. **Используйте контракт кода выхода.** Выход 0 означает отправлено. Выход 1 означает повторяемый отказ; сеанс отступает и переоффертируется. Выход 2 или выше означает неповторяемый; сеанс блокируется от порождения снова до тех пор, пока [владелец](/docs/ru/cloud-environments#organization-shared-environments) не выберет **Retry** на нем на вкладке **Activity** окружения. При ненулевом выходе хвост stderr хука появляется там как причина отказа, поэтому напишите действенную ошибку в stderr и никогда не секреты. Для запроса предварительного прогрева нет сеанса для отказа: оркестратор логирует ненулевой выход локально только, и сервер повторно запрашивает порождение после аренды. 4. **Установите `--expected-spawn-seconds` на по крайней мере ваше время загрузки p99.** Это аренда на стороне сервера. Все реплики оркестратора должны использовать одно и то же значение. Все, что хук пишет в stdout или stderr, появляется в логе оркестратора с автоматически удаленными учетными данными. Если сеансы остаются в очереди, проверьте тело `/healthz` оркестратора на предмет количества в очереди, затем откройте вкладку **Activity** вашего окружения на [странице администратора **Cloud environments**](https://claude.ai/admin-settings/cloud-environments): разверните неудачный сеанс там для его ошибки порождения и выберите **Retry** для повторного запроса.

MCP серверы

Чтобы сделать [MCP серверы](/docs/ru/mcp) доступными в каждом сеансе, добавьте их во время сборки образа с помощью той же команды `claude mcp add`, используемой при установке на рабочем столе. Если ваше средство выполнения — это простой процесс, а не контейнер, запустите ту же команду от пользователя средства выполнения на хосте, затем перезагрузите средство выполнения: оно читает конфигурацию хоста один раз при запуске. Флаг `--scope user` требуется; область по умолчанию пишет под ключом для каждого каталога, который средство выполнения не заполняет в сеансы. Например, в вашем Dockerfile: ```dockerfile theme={null} RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080 ``` Средство выполнения снимает конфигурацию хоста один раз при запуске. Снимок захватывает ключ `mcpServers` из `.claude.json` хоста, который находится рядом, а не внутри `~/.claude/`, и средство выполнения заполняет только этот ключ в изолированную конфигурацию каждого сеанса; состояние учетной записи и история проекта отбрасываются. Чтобы подтвердить, что серверы достигли сеансов, запустите сеанс в окружении и попросите Claude перечислить его инструменты MCP; средство выполнения также логирует предупреждение при запуске для любой захваченной записи, чей `type` оно не распознает, и отбрасывает запись, поэтому вы можете увидеть, почему этот сервер отсутствует в сеансах. Когда установлен `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR`, средство выполнения читает `.claude.json` из этого каталога вместо этого, поэтому указание переменной на пустой каталог также отключает заполнение MCP. Claude Code также загружает MCP серверы из других источников: * Файл MCP [управляемый на уровне предприятия](/docs/ru/managed-mcp) по его стандартному системному пути: `/etc/claude-code/managed-mcp.json` на хостах средства выполнения Linux, `/Library/Application Support/ClaudeCode/managed-mcp.json` на хостах macOS. Используйте его для заблокированных флотов, где только серверы, указанные администратором, могут загружаться. См. [exclusive control with managed-mcp.json](/docs/ru/managed-mcp#exclusive-control-with-managed-mcp-json) для правил приоритета. Когда этот файл находится на хосте средства выполнения, Claude Code пропускает MCP серверы, которые плоскость управления Anthropic доставляет в сеанс, включая разъемы claude.ai, и называет их в предупреждении на stderr дочернего процесса сеанса, которое средство выполнения записывает на уровне логирования `debug`. До v2.1.229 эти сеансы выходили при запуске с `You cannot dynamically configure MCP servers when an enterprise MCP config is present`. * Ключ [`managedMcpServers`](/docs/ru/settings-reference#managedmcpservers) в [управляемых настройках](/docs/ru/managed-settings) на хосте средства выполнения: предоставляет HTTP и SSE серверы без принятия исключительного управления, поэтому серверы из других источников по-прежнему загружаются. Требует Claude Code v2.1.259 или позже. * `/.mcp.json`: область проекта. Зафиксируйте файл в репозитории; его серверы автоматически одобрены в облачных сеансах. Когда доставка разъемов включена для вашей организации, плоскость управления Anthropic доставляет разъемы, которые вы настроили на claude.ai, в интерактивно созданные сеансы через конфигурацию MCP, предоставленную сервером, маршрутизируемую через `api.anthropic.com`. Сеансы, созданные программно, такие как [CLI dispatches](/docs/ru/self-hosted-environments-testing#run-the-test-loop), не получают доставку разъемов; дайте им MCP серверы через любой из других источников, которые этот раздел перечисляет вместо этого. Токен OAuth дочернего процесса не содержит область для прямой выборки разъемов, поэтому дочерний процесс не пытается эту выборку сам; доставка управляется сервером. `settings.json` не содержит определения MCP сервера, и в схеме настроек нет поля `mcpServers` верхнего уровня. В управляемых настройках предоставляйте серверы с помощью ключа [`managedMcpServers`](/docs/ru/settings-reference#managedmcpservers) вместо этого. Сеансы наследуют окружение средства выполнения, поэтому установите [`ENABLE_TOOL_SEARCH`](/docs/ru/mcp#scale-with-mcp-tool-search) там для управления поиском инструментов MCP для каждого сеанса, который порождает средство выполнения; страница MCP охватывает значения.

Подсказка сеансов для отправки их работы

Размещенные Anthropic сеансы запускают хук [`Stop`](/docs/ru/hooks#stop), хук Claude Code, который запускается, когда Claude заканчивает отвечать, который подсказывает Claude зафиксировать и отправить его работу. Средство выполнения не устанавливает один. Без него сеанс, который заканчивается с незафиксированными изменениями, оставляет эту работу только на диске средства выполнения, и кнопка **Create PR** в claude.ai/code остается неактивной до тех пор, пока ветка не существует на удаленном. Эталонная реализация ниже имеет две части. Объедините блок настроек в `~/.claude/settings.json` на хосте средства выполнения, который средство выполнения заполняет в каждый сеанс, и сохраните скрипт как `~/.claude/hooks/stop-hook-nudge.sh` на хосте средства выполнения и сделайте его исполняемым: ```json theme={null} { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "timeout": 10, "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\"" } ] } ] } } ``` ```sh theme={null} #!/bin/sh # Stop-hook reference implementation for self-hosted runners. # # Nudges Claude once per turn if the project directory has uncommitted # changes OR unpushed commits, so work isn't lost when an idle session # is released and so the "Create PR" button on claude.ai/code lights up. # # Runner-level (no repo changes): drop this file at ~/.claude/hooks/ on # the runner host and merge the accompanying Stop-hook settings block # into ~/.claude/settings.json — the runner seeds both into every session. # Repo-level alternative: commit to /.claude/hooks/ and change the # settings.json command path to $CLAUDE_PROJECT_DIR/.claude/hooks/. # # stdin: hook JSON payload (see https://code.claude.com/docs/en/hooks) # stdout: {"decision":"block","reason":"..."} to nudge, or nothing to allow stop. # Re-entry guard: the harness sets stop_hook_active=true when re-invoking # the Stop hook after a block. Bail so we only nudge once per turn. The # harness emits compact JSON (no space after the colon), which this # pattern relies on; use jq if you need a whitespace-tolerant check. in=$(cat) case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac d="$CLAUDE_PROJECT_DIR" # Not a git repo → nothing to nudge. git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0 # No remote → "push to the remote" is unsatisfiable; bail. [ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0 # Uncommitted changes (staged, unstaged, or untracked). Exclude .claude/ # entirely — operator-seeded settings and CLI-written runtime state # (scheduler lock, worktrees, routine state) live there and neither is # "uncommitted work" the model needs to push. s=$(git -C "$d" status --porcelain -- . ':(exclude).claude/' 2>/dev/null) if [ -n "$s" ]; then printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}' exit 0 fi # Unpushed commits. Count commits on HEAD not reachable from any # remote-tracking ref or FETCH_HEAD. This works uniformly for: # - init+fetch checkouts (runner default: only FETCH_HEAD exists) # - clone-based checkouts (origin/* exist) # - the runner default: the child starts on the session's outcome # branch, which the runner creates after checkout # - detached HEAD, when a custom setup skips that branch creation # With no reference point at all (never fetched), stay silent rather # than false-positive on a read-only turn. base="" git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD" if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then exit 0 fi # shellcheck disable=SC2086 # $base is either "" or "FETCH_HEAD", intentional word-split unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0 if [ "$unpushed" -gt 0 ]; then branch=$(git -C "$d" symbolic-ref --short -q HEAD) if [ -n "$branch" ]; then # $branch is attacker-influenced — git-check-ref-format(1) allows `"` # in ref names. `\` is forbidden (rule 10) but escaped anyway as cheap # defense-in-depth. # Escape JSON metacharacters before interpolating into the hand-built # payload so a branch like x","continue":false can't inject keys into # the hook-output JSON the harness parses. $unpushed is safe — the # -gt guard above rejects anything that isn't a plain integer. branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g') printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc" else printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed" fi exit 0 fi exit 0 ``` Хук подсказывает Claude зафиксировать и отправить перед завершением сеанса и остается молчаливым, когда каталог не является репозиторием git или не имеет удаленного.

Разрешения и одобрение инструментов

Самостоятельно размещаемый сеанс не имеет прикрепленного терминала, поэтому неотвеченная подсказка разрешения блокирует ход до тех пор, пока пользователь не ответит в UI. Плоскость управления Anthropic отправляет список инструментов каждого сеанса и правила разрешений с полезной нагрузкой работы; конфигурация по умолчанию предварительно одобряет обычные вызовы инструментов, включая `Bash`, и облачные сеансы [предварительно одобряют редактирование файлов независимо от режима](/docs/ru/permission-modes#switch-permission-modes). Вызов, который ничто не предварительно одобряет, подсказывает через UI сеанса. Закрепляйте только автоматический режим в окружении, контейнеры сеансов которого работают с [сетевым исходящим трафиком по умолчанию запретить](/docs/ru/self-hosted-environments-deploy#default-deny-egress) и остальной частью [раздела hardening](/docs/ru/self-hosted-environments-deploy#harden-your-deployment). Обычные вызовы инструментов, включая запросы сети `Bash`, запускаются без человека в цикле как на наборе инструментов по умолчанию предварительно одобренных, так и в автоматическом режиме, поэтому граница сети — это то, что ограничивает, где эти вызовы могут достичь. Чтобы минимизировать подсказки независимо от того, что отправляет плоскость управления, закрепите [автоматический режим](/docs/ru/permission-modes#eliminate-prompts-with-auto-mode) из вашего скрипта-оболочки или хука [`command`](#command). Автоматический режим позволяет сеансам запускаться без обычных подсказок разрешения: отдельная модель классификатора проверяет действия перед их запуском и блокирует те, которые она отклоняет, и явные правила запроса по-прежнему вынуждают подсказку; страница режимов разрешений охватывает то, что классификатор проверяет. Средство выполнения добавляет вычисленные сервером флаги перед вызовом оболочки, и для флагов с одним значением, таких как `--permission-mode`, парсер соблюдает последнее вхождение, поэтому флаг, который вы добавляете после `"$@"`, переопределяет значение, отправленное сервером: ```bash theme={null} #!/bin/bash exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto ``` Чтобы предварительно одобрить конкретные инструменты вместо этого, добавьте `--allowed-tools` с вашими правилами, например `--allowed-tools "Bash(bazel *) Bash(yarn *) mcp__internal__*"`. Флаги списков, такие как `--allowed-tools` и `--disallowed-tools`, накапливаются при вхождениях вместо переопределения, поэтому ваши правила применяются поверх любых правил, которые отправляет плоскость управления. Чтобы сузить, добавьте `--disallowed-tools`, который отрицает инструменты, даже если другое правило их разрешает.

Как собирается конфигурация каждого сеанса

Средство выполнения дает каждому сеансу свой собственный каталог конфигурации, заполненный из снимка в памяти `~/.claude/` хоста, который средство выполнения захватывает один раз при запуске: `settings.json`, `CLAUDE.md`, хуки, агенты, команды и навыки в вашем образе средства выполнения применяются к каждому сеансу как базовая линия уровня пользователя. Поскольку снимок берется при запуске, изменения конфигурации на работающем хосте вступают в силу только после перезагрузки средства выполнения. Установите `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` для заполнения из другого пути или укажите его на пустой каталог для отключения заполнения. Зафиксированный в репозитории `.claude/settings.json` накладывается сверху как настройки проекта. Сеансы также читают [`managed-settings.json`](/docs/ru/settings#where-settings-live) из стандартного системного пути в вашем образе средства выполнения. Применяются ли его ключи наряду с [управляемыми сервером настройками](/docs/ru/server-managed-settings) следует [как Claude Code объединяет управляемые источники](/docs/ru/managed-settings#how-claude-code-combines-managed-sources): по умолчанию, когда ваша организация доставляет любые управляемые сервером ключи, сеансы игнорируют файл образа средства выполнения, кроме [ключей, которые Claude Code читает из каждого источника администратора](/docs/ru/managed-settings#keys-read-from-every-admin-source), такие как блок `env`, блокировки песочницы, пути двоичных файлов песочницы и `forceRemoteSettingsRefresh`. См. [приоритет настроек](/docs/ru/settings#settings-precedence). Когда плоскость управления Anthropic предоставляет сеансу [хуки Claude Code](/docs/ru/hooks), средство выполнения устанавливает их рядом, а не над вашей собственной конфигурацией. Требует Claude Code v2.1.229 или позже. * **Где они приземляются**: средство выполнения пишет каждый предоставленный скрипт хука в зарезервированный подкаталог `hooks/.ccr-launcher/` каталога конфигурации сеанса и регистрирует скрипты в отдельном файле настроек, который он передает сеансу с помощью `--settings`, оставляя заполненный `settings.json` и ваши собственные скрипты в `hooks/` нетронутыми. Средство выполнения пересоздает зарезервированный подкаталог для каждого сеанса и не заполняет содержимое хоста в `~/.claude/hooks/.ccr-launcher/` в сеансы. * **Кто их создает**: плоскость управления заполняет скрипты из фиксированных констант в своем собственном развертывании, никогда не из входных данных для каждого сеанса или третьей стороны. * **Что по-прежнему их управляет**: хуки, доставленные через `--settings`, входят в обычную объединенную конфигурацию хука, а не в управляемый уровень, поэтому ваши управляемые настройки по-прежнему применяются. `disableAllHooks` отключает их, и они не входят в категории, которые [`allowManagedHooksOnly`](/docs/ru/settings-reference#allowmanagedhooksonly) сохраняет загруженными.

Правила разрешений, зафиксированные в репозитории

Не помещайте запись `"Edit"`, `"Write"` или `"NotebookEdit"` без квалификации в зафиксированный в репозитории `permissions.allow`. Правило инструмента файла без квалификации соответствует инструменту независимо от пути, предоставляя записи в любом месте на хосте вместо только рабочей области, поэтому охрана ограничения области записи средства выполнения отмечает сеанс; с [`--confine-repo-settings enforce`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) она отказывает в порождении сеанса вместо логирования и продолжения. См. [раздел hardening](/docs/ru/self-hosted-environments-deploy#harden-your-deployment). Репозиторий не нуждается в правиле инструмента файла вообще: облачные сеансы [предварительно одобряют редактирование файлов независимо от режима](/docs/ru/permission-modes#switch-permission-modes). Если вы все же зафиксируете правило, ограничьте его рабочей областью, такой как `"Edit(/**)"`; одна ведущая косая черта относительна к корню проекта, который является рабочей областью сеанса. Правила инструмента файла без квалификации в порядке в `settings.json` оператора на уровне хоста, так как этот файл не зафиксирован в репозитории. `defaultMode` из `auto` соблюдается только из файла настроек на уровне образа или пользователя, поэтому проверенный репозиторий не может предоставить себе автоматический режим. Для того, какие режимы облачные сеансы принимают и полный синтаксис правила, см. [режимы разрешений](/docs/ru/permission-modes).

Что дальше

* [Reference](/docs/ru/self-hosted-environments-reference): каждый флаг CLI, переменная окружения и метрика * [Verify session identity](/docs/ru/self-hosted-environments-identity): проверьте токен сеанса из служб вне средства выполнения