Развертывание самостоятельно размещаемых окружений в production

Запуск самостоятельно размещаемых runners в production: усиление безопасности, контроль сетевого исходящего трафика, учетные данные git, рецепты Kubernetes и Compose, а также устранение неполадок.

[!NOTE]

Самостоятельно размещаемые окружения находятся в публичной бета-версии на планах Team и Enterprise; раздел Доступность и ограничения охватывает путь включения. Эта страница охватывает запуск флота в production; см. быстрый старт для вашего первого runner и сеанса.

Самостоятельно размещаемое окружение запускает Claude Code облачные сеансы на runners, которые вы развертываете внутри вашей сети, и в production эти сеансы выполняют направленный моделью код от имени всех, кто может отправить сеанс в окружение. Эта страница предназначена для оператора, переводящего рабочее окружение в production. Она проходит через развертывание по порядку: что заблокировать перед подключением реальных систем, исходящий трафик, который требуется флоту, как сеансы аутентифицируются на вашем хосте git, сами рецепты развертывания и что проверить, когда сеансы работают неправильно.

Усиление безопасности развёртывания

Самостоятельно размещаемый runner выполняет произвольный, направленный моделью код на вашей инфраструктуре от имени всех, кто может отправить сессию в его окружение. Это любой член вашей организации Anthropic и любой, кто может запустить сессию канала Claude Tag в области действия, которую Owner направил в окружение. Проработайте каждый элемент перед подключением окружения к production-системам:

Эфемерные контейнеры для каждой сессии: запускайте каждый процесс runner в свежем контейнере или VM, который уничтожается при выходе процесса, с --capacity 1 и значением по умолчанию --drain-grace-sec 0, чтобы каждый контейнер обслуживал ровно одну сессию. При более высокой ёмкости или положительном периоде осушения один контейнер обслуживает несколько сессий от одного заблокированного владельца; см. Runner lifecycle. Не переиспользуйте файловую систему между перезапусками runner, кроме намеренной настройки pre-warmed checkout, и никогда между владельцами.
- Когда runner останавливает сессию, он не отправляет никакого сигнала процессу, который продолжает работать после завершения его shell-команды, например сервису, ставшему демоном. Уничтожение контейнера или VM завершает такой процесс.
Нет широких учётных данных в образе: не включайте долгоживущие SSH-ключи, учётные данные облачного провайдера или личные токены доступа, которые предоставляют больше, чем нужно сессии. Создавайте учётные данные, используемые во время сессии, такие как токены push или API, для каждой сессии из вашего скрипта-обёртки. Начальное клонирование происходит перед запуском обёртки, поэтому обрабатывайте его с помощью хука жизненного цикла checkout или с помощью --use-anthropic-git-proxy, если все репозитории сессии находятся на github.com. Для обоих вариантов см. Configure git.
Держите учётные данные GitHub хоста вдали от сессий: Claude может использовать любые учётные данные GitHub, которые может прочитать сессия, с любым доступом, который эти учётные данные предоставляют. Не допускайте, чтобы собственные учётные данные GitHub хоста runner с широкими правами попадали туда, где их может прочитать сессия. Такими учётными данными может быть личный токен доступа, токен, который gh auth login сохраняет для вашей учётной записи, или GH_TOKEN в окружении runner.
- С Anthropic-managed git: при наличии таких учётных данных Claude обращается к GitHub напрямую, а не через Anthropic-managed git.
- Без Anthropic-managed git: учётные данные для клонирования могут оставаться в образе, если вы ограничите их так строго, как описано в Ship git config in your image.
Держите секрет окружения вдали от хостов, запускающих сессии: секрет окружения может регистрировать runners и получать любую сессию, поставленную в очередь в окружение. На фиксированном флоте он находится на каждом хосте runner, где код любой сессии может прочитать файл секрета. Предпочитайте on-demand runners, где секрет остаётся на хосте оркестратора, который никогда не запускает пользовательский код, и каждый runner получает одноразовый наряд на работу, который регистрирует ровно один runner. На фиксированном флоте рассматривайте файл environment-secret как читаемый каждой сессией и ротируйте секрет после любого подозрения на компрометацию сессии.
Исходящий трафик по умолчанию запрещён: ограничьте исходящий трафик контейнеров runner и сессии на границе вашей собственной сети в каждом окружении; Default-deny egress описывает, что разрешить и почему.
Наименьшие привилегии IAM хоста: вычислительная идентификация, прикреплённая к хосту runner, такая как профиль экземпляра или учётная запись сервиса узла, должна предоставлять только то, что нужно самому runner. Сессии должны получать свои собственные учётные данные через ваш скрипт-обёртку, а не наследовать учётные данные хоста.
Блокируйте сессиям доступ к эндпоинту облачных метаданных: чтобы сессии не использовали идентификацию хоста, требуется блокировать их доступ к эндпоинту облачных метаданных, а политики исходящего трафика на уровне подсети не перехватывают трафик метаданных link-local, поэтому блокируйте его в самом контейнере:
- IMDSv2 с пределом хопов в один
- GKE Workload Identity со скрытием метаданных
- Явный запрет для 169.254.169.254 в сетевом пространстве имён контейнера сессии
Блокировка применяется также к вашему скрипту-обёртке и хукам жизненного цикла, так как они используют тот же контейнер. Аутентифицируйте любой обмен токенами с помощью session JWT в вашем собственном сервисе токенов через разрешённый исходящий трафик или используйте веб-идентификацию на основе файлов, такую как IAM Roles for Service Accounts (IRSA) на Amazon EKS.
Изоляция файловой системы для каждого runner: каждый процесс runner получает свой собственный рабочий каталог, который никакой другой процесс на хосте не может читать или записывать. Сделайте --hooks-dir, скрипт-обёртку и ~/.claude/ хоста доступными сессии только для чтения, либо встроив их в образ, либо смонтировав только для чтения.
Dispatch не имеет контроля доступа на уровне окружения: любой член вашей организации Anthropic может отправить сессию в любое из её окружений. Если Owner направляет каналы Claude Tag в окружение, любой, кого допускает настройка доступа Claude Tag, может запускать сессии канала, которые работают там. По умолчанию это любой участник подключённого рабочего пространства Slack, с учётной записью Claude или без неё. Рассматривайте каждый хост runner как доступный для выполнения кода всеми, кто может отправлять в него сессии, и размещайте на хосте runner только данные и учётные данные, которые все эти люди имеют право читать. --lock-to-account ограничивает, сессии какой учётной записи выполняет данный хост, но не сужает круг тех, кто может отправлять сессии в окружение. Чтобы сделать самостоятельно размещаемые окружения единственным вариантом выбора, Owner может скрыть окружения, размещаемые Anthropic, для всей организации на странице Cloud environments.
Применяйте защиту repo-settings: выберите режим защиты с помощью --confine-repo-settings. Режим по умолчанию warn записывает нарушение в лог и всё равно запускает сессию, enforce отклоняет сессию, а off отключает сканирование. Runner сканирует закоммиченные настройки каждого репозитория на наличие:
- Гранта, который разрешается за пределами собственного рабочего пространства этой сессии: записи additionalDirectories, правила Edit, Write или NotebookEdit в permissions.allow или записи sandbox.filesystem.allowWrite или allowRead
- Непустого блока env
- Переопределения позиции оператора, такого как sandbox.enabled: false
Защита работает независимо от --trust-workspace и не охватывает хуки репозитория, .mcp.json или правила Bash; см. Permissions and tool approval, чтобы узнать, где должны находиться эти гранты.

[!NOTE]

Если в вашей организации включён список разрешённых IP-адресов, добавьте публичные адреса исходящего трафика ваших runners и контейнеров сессий в список разрешённых перед их запуском. Если вы используете on-demand runners, добавьте также адрес хоста оркестратора. Не полагайтесь на список разрешённых как на сетевой контроль для трафика runner или сессий. Вместо этого применяйте default-deny egress на границе вашей собственной сети.

Требования к сети

Runner и порожденные им дочерние сеансы устанавливают исходящие соединения с хостами ниже. Ограничьте исходящий трафик контейнера сеанса этими хостами и конкретными внутренними сервисами, которые сеансам нужно достичь; Default-deny egress охватывает как и почему.

Эти хосты всегда требуются:

Хост	Порт	Используется для
`api.anthropic.com`	443, HTTPS; WSS для git под управлением Anthropic	Плоскость управления runner и потоковая передача сессии, вывод модели, флаги функций, аналитика продукта, получение ключей JWKS, подпись коммитов и git под управлением Anthropic при установке `--use-anthropic-git-proxy`
Ваш git-хост, такой как `github.com` или ваш хост GitHub Enterprise	443 или 22	Клонирование и push репозиториев на каждом git-хосте, который используют сессии runner. Для runner, использующего `--use-anthropic-git-proxy`, см. когда путь к `github.com` всё ещё нужен.

Runner, использующий --use-anthropic-git-proxy, направляет свой git-трафик к github.com через api.anthropic.com, поэтому ему не нужен путь к git-хосту github.com. Этот путь всё ещё нужен, если вы устанавливаете --push-outcome-on-release или выполняете push из хука post-session.

Требуются ли эти хосты, зависит от вашей конфигурации:

Хост	Порт	Когда требуется
`downloads.claude.ai`	443	Во время установки, когда вы устанавливаете или обновляете Claude Code на хосте с помощью встроенного установщика; сам скрипт `install.sh` обслуживается с `claude.ai`. Во время выполнения сеанса только когда сеансы устанавливают плагины из официального рынка Anthropic.
`storage.googleapis.com`	443	Во время выполнения сеанса для количества установок плагинов и метаданных, показанных в `/plugin`.
`code.claude.com` и `claude.com`	443	Поиск документации встроенным агентом claude-code-guide и предварительно одобренные запросы WebFetch во время сеансов. Блокировка этих хостов влияет только на поиск документации.
`*.frame.claudeusercontent.com`	443	Только когда инструмент Artifact доступен для сеансов в вашей организации; значения по умолчанию варьируются по плану, согласно таблице доступности там. Установите `CLAUDE_CODE_DISABLE_ARTIFACT=1` на runner, чтобы держать инструмент отключенным независимо от параметра организации.
`registry.npmjs.org`	443	Когда сеанс устанавливает плагин, как для получения пакетов плагинов npm-source, так и для установки зависимостей Node.js плагина, или когда запускается MCP-сервер, запущенный `npx`
`http-intake.logs.us5.datadoghq.com`	443	Метрики операций Anthropic. Только когда установлено `CLAUDE_CODE_BYOC_ENABLE_DATADOG=1`; отключено по умолчанию в самостоятельно размещаемых окружениях.
`browser-intake-us5-datadoghq.com`	443	Загрузки отчетов об ошибках Anthropic, отправляемые только когда отчетность об ошибках включена для учетной записи сеанса. Подавляется `DISABLE_ERROR_REPORTING=1` или `DISABLE_TELEMETRY=1`.
Эндпоинты вашего облачного провайдера для запросов к модели, поиска моделей и обновления учётных данных, такие как `bedrock-runtime.us-east-1.amazonaws.com` или `aiplatform.googleapis.com`	443	Только когда runner отправляет запросы к модели в Amazon Bedrock или Google Cloud's Agent Platform

Эти хосты не нужно добавлять в список разрешённых хостов для трафика runner или сессий:

statsig.anthropic.com, *.sentry.io, claude.ai и platform.claude.com: эти хосты встречаются в некоторых старых контрольных списках корпоративной сети, но runner к ним не обращается. Получение флагов функций идёт на api.anthropic.com, а runner аутентифицируется с помощью секрета окружения, а не интерактивного OAuth.
mcp-proxy.anthropic.com: самостоятельно размещаемые сессии его не используют. Когда доставка коннекторов включена для вашей организации, коннекторы claude.ai вашей организации попадают в сессии через api.anthropic.com. См. MCP servers.

Следующие процессы на стороне хоста обращаются к claude.ai, поэтому запускайте их с хоста, чей исходящий трафик это позволяет, а не расширяйте исходящий трафик контейнера сессии:

Однострочный установщик: получает install.sh с claude.ai во время установки.
Интерактивный claude auth login: выполняет вход через claude.ai, claude.com и platform.claude.com. Его используют guided setup, режим doctor с входом и CI dispatch. Браузер, в котором вы входите, также загружает браузерные проверки страницы входа claude.ai с hcaptcha.com, *.hcaptcha.com и challenges.cloudflare.com. Если ваша организация использует единый вход (SSO), этот браузер также может быть перенаправлен через sso.claude.com.

Default-deny egress

Развертывайте контейнеры runner и сеанса в сегменте сети или пространстве имен, чей исходящий трафик ограничен хостами в таблице требований к сети, вашим git-хостом и конкретными внутренними сервисами, которые сеансам нужно достичь. Продукт не может проверить или применить это, поэтому применяйте это на границе вашей собственной сети в каждом окружении. Код сеанса направлен моделью и может попытаться подключиться к произвольным хостам; default-deny egress на сетевом уровне ограничивает, где эти попытки могут приземлиться. Это применяется независимо от режима разрешений: набор инструментов, одобренный по умолчанию, уже включает Bash, поэтому исходящий трафик shell работает без подсказки даже без auto mode.

Для деталей о том, какую телеметрию излучает каждый сеанс и как ее отключить, см. Telemetry.

Аутентификация на исходящий прокси

Некоторые корпоративные исходящие прокси требуют заголовок Proxy-Authorization на каждом соединении. Токен в этом заголовке часто ротируется слишком быстро, чтобы писать в URL прокси, который вы устанавливаете в HTTPS_PROXY. Установите HTTPS_PROXY или HTTP_PROXY на URL вашего прокси как обычно, затем установите --proxy-authorization-command или --proxy-authorization-file, чтобы сказать runner, где читать значение заголовка. Оба флага требуют Claude Code v2.1.238 или позже.

Выберите, откуда берется значение `Proxy-Authorization`

Выберите флаг, который соответствует тому, как вы производите токен Proxy-Authorization:

--proxy-authorization-command <command>: выберите это для токена, который вы генерируете по требованию. Runner запускает команду shell и использует ее обрезанный stdout как значение заголовка, например Bearer <token>.
--proxy-authorization-file <path>: выберите это для токена, который другой процесс ротирует на месте. Runner читает файл и использует его обрезанное содержимое как значение заголовка.

Конфигурации, с которыми runner отказывается запускаться

Каждый флаг также имеет форму переменной окружения, указанную рядом с ним в справочнике флагов CLI runner. Перед тем как runner свяжется с вашим прокси или плоскостью управления, он проверяет флаги и их переменные и отказывается запускаться в трех случаях:

Оба флага установлены: один флаг плюс переменная окружения другого флага считается установкой обоих.
Нет URL прокси: ни HTTPS_PROXY ни HTTP_PROXY не содержат URL http:// или https://. Runner читает обе переменные в верхнем или нижнем регистре и не консультирует ALL_PROXY.
Любой флаг передан подкоманде orchestrator: self-hosted-runner orchestrator не принимает флаги или их переменные окружения. Вместо этого передайте флаг каждому runner, который запускает оркестратор.

Что runner изменяет, пока установлен флаг proxy-authorization

С установленным любым флагом runner запускает собственный слушатель и отправляет трафик прокси от себя, своих lifecycle hooks и своих сеансов через этот слушатель. Слушатель добавляет заголовок Proxy-Authorization на пути к вашему прокси.

Слушатель: слушатель является forward proxy на 127.0.0.1. Runner запускает слушатель перед регистрацией в плоскости управления и выходит при запуске, если слушатель не может запуститься.
Переменные прокси: runner переписывает любой из HTTPS_PROXY и HTTP_PROXY, который вы установили, чтобы он указывал на слушатель. Это переписанное значение достигает самого runner, его lifecycle hooks и каждого сеанса, который он запускает.
Ротация токена: ротированный токен вступает в силу без перезагрузки. Для каждого соединения, которое слушатель открывает для вашего прокси, runner запускает вашу команду или читает ваш файл снова и добавляет результат как заголовок.
Окружение сеанса: сеанс достигает вашего прокси только через слушатель. В окружении каждого сеанса runner удаляет ALL_PROXY, удаляет любое написание HTTPS_PROXY или HTTP_PROXY, которое вы не установили, и закрепляет NO_PROXY на собственное значение runner.
Логи: runner никогда не регистрирует значение заголовка.

Настройка git

Раннер управляет извлечением репозиториев, но по умолчанию не настраивает идентификацию или учётные данные git. Вы контролируете образ раннера и окружение его процесса, поэтому конфигурация git тоже в ваших руках. Выберите один из двух подходов:

Позвольте раннеру настроить git: запустите раннер с --configure-git, чтобы он записал ту же конфигурацию идентификации и подписи коммитов, что используют сессии, размещённые Anthropic
Поставляйте конфигурацию git в своём образе: задайте идентификацию и учётные данные для push самостоятельно, например чтобы делать коммиты от имени собственного бота

Для репозиториев на github.com также можно запустить раннер с --use-anthropic-git-proxy или задать CLAUDE_RUNNER_USE_GIT_PROXY=1, чтобы попросить Anthropic обслуживать git для сессий раннера.

Минимальные версии Git на хосте раннера: для подписи коммитов через SSH с --configure-git требуется Git 2.34 или новее, для --use-anthropic-git-proxy — 2.32 или новее, а для возобновления сессий из веток, отправленных с помощью --push-outcome-on-release, — 2.29 или новее. Git 2.24 достаточно, если вы не используете ни одну из этих трёх возможностей и управляете идентификацией git самостоятельно.

Позвольте раннеру настроить git

Запустите раннер с --configure-git или задайте SELF_HOSTED_RUNNER_CONFIGURE_GIT=1, чтобы при запуске он записал глобальную конфигурацию git:

user.name = Claude и user.email = noreply@anthropic.com, как в сессиях, размещённых Anthropic
Подпись коммитов и тегов в формате SSH, проходящая через управляемую раннером прослойку, которая подписывает каждый коммит через сервис подписи Anthropic с использованием собственных учётных данных сессии. Подписи можно проверить на GitHub по опубликованному ключу подписи SSH от Anthropic.
push.negotiate = true, чтобы перед упаковкой push git спрашивал у вашего git-хостинга, какие коммиты у него уже есть. Требуется Claude Code v2.1.257 или новее.
core.hooksPath, указывающий на управляемый раннером каталог хуков. Его хуки commit-msg и prepare-commit-msg добавляют к каждому коммиту трейлер Co-authored-by: для создателя сессии. Трейлер формируется из адреса электронной почты в CCR_SESSION_ACCOUNT_EMAIL и не добавляется, если эта переменная не задана. Если ваш образ уже задаёт core.hooksPath и раннер не использует git под управлением Anthropic, раннер оставляет вашу настройку как есть, не устанавливает эти хуки и выводит предупреждение [runner:git].

Для подписи коммитов требуется git 2.34 или новее; раннер проверяет это при запуске и завершается с ошибкой, если ваш git старше. Этот флаг не настраивает учётные данные для push — их по-прежнему нужно предоставить в образе.

На раннере версии v2.1.280 или новее коммиты, которые вы делаете из хука жизненного цикла checkout или post-session, также подписываются от имени сессии, но без трейлера Co-authored-by:. В разделе Конфигурация git внутри хуков жизненного цикла описаны настройки git, которые раннер фиксирует внутри этих хуков.

С --configure-git или без него Claude Code указывает Claude завершать сообщения коммитов трейлером Claude-Session: <url>, а описания pull request — URL сессии. Чтобы отключить и то и другое, задайте для attribution.sessionUrl значение false в файле ~/.claude/settings.json на хосте раннера, а затем перезапустите раннер.

Поставляйте конфигурацию git в своём образе

Идентификация git требуется для любого коммита. Задайте её на уровне системы в своём Dockerfile, чтобы конфигурация применялась независимо от того, от имени какого пользователя запущен процесс раннера:

RUN git config --system user.name "Claude" && \
    git config --system user.email "noreply@anthropic.com"

Без идентификации git commit завершается ошибкой Please tell me who you are, и сессии не могут продвигаться. Вместо этого можно использовать идентификацию собственного бота; раннер не переопределяет эти значения.

Не встраивайте долгоживущие или широко ограниченные учётные данные для push в общий образ раннера: учётные данные в образе доступны каждой сессии, которую запускает этот образ, кто бы её ни начал. Вместо этого выпускайте краткосрочный токен с минимальной областью действия для каждой сессии в своём скрипте-обёртке, используя идентификацию создателя сессии, декодированную из JWT сессии. Сочетайте это с эфемерным контейнером на каждую сессию, для чего требуется --capacity 1, чтобы никакие учётные данные не переживали сессию, которая их выпустила; см. раздел об усилении защиты.

Если вам необходимо настроить учётные данные для push на уровне образа, например для ключа развёртывания только для чтения, ограничьте их настолько жёстко, насколько позволяет ваш git-хостинг:

Ключ развёртывания SSH, ограниченный одним репозиторием, с перезаписью url.<base>.insteadOf
credential.helper, возвращающий токен с минимальной областью действия
GIT_SSH_COMMAND, указывающий на ключ с узкой областью действия

Какой бы механизм вы ни настроили, он должен работать без запроса ввода, потому что встроенные операции clone и fetch раннера отключают запросы, которые иначе показали бы git, SSH и Git Credential Manager:

Раннер задаёт GIT_TERMINAL_PROMPT=0, поэтому git не запрашивает имя пользователя или пароль.
Раннер запускает SSH с BatchMode=yes, добавленным к вашему GIT_SSH_COMMAND, если вы его задали, поэтому SSH не запрашивает парольную фразу или подтверждение хоста.
Раннер задаёт GCM_INTERACTIVE=never, поэтому Git Credential Manager не открывает диалог входа.
Раннер очищает core.askPass, поэтому если вы используете вспомогательную программу askpass, задайте её через переменную окружения GIT_ASKPASS.

Если ваш git-хостинг отклоняет учётные данные или вы их не настроили, раннер делает несколько повторных попыток, а затем завершает подготовку репозитория с ошибкой, если это репозиторий, в который сессия отправляет результаты. Для репозитория, который сессия только читает, в разделе Устранение неполадок описано, когда раннер вместо этого его пропускает. Раннер не передаёт эти настройки в окружение сессии.

Храните любую программу, указанную в GIT_SSH_COMMAND или GIT_ASKPASS, там, куда сессии не могут записывать, — так же, как контрольный список усиления защиты требует для каталога хуков и скрипта-обёртки. То же относится к любому ключу или файлу в командной строке этой программы. Собственный git раннера запускает эту программу при выполнении clone или fetch.

Если каталоги извлечения принадлежат другому uid, чем процесс раннера, git отказывается с ними работать; добавьте safe.directory:

RUN git config --system --add safe.directory '*'

Используйте git-прокси Anthropic

С git-прокси Anthropic, который также называется git под управлением Anthropic, образу раннера не нужны ключи SSH, вспомогательная программа учётных данных, .netrc или другие учётные данные git для самой сессии. Вместо этого раннер просит Anthropic обслуживать git для его сессий. Для пользовательской сессии, которую обслуживает Anthropic, clone раннера и собственные fetch и push сессии проходят через Anthropic, который использует OAuth-токен GitHub, сохранённый для создателя сессии. Сессии ботов и агентов описаны в разделе Как Anthropic обслуживает git для сессии.

Git-прокси отключён, пока вы не включите его. Раннеру, который обращается к вашему git-хостингу с собственными учётными данными, он не нужен, и git такого раннера работает с любым git-хостингом.

Взамен git-прокси ограничивает то, что поддерживает раннер, и меняет то, что ему нужно:

Только github.com: Anthropic обслуживает сессию, только если все её репозитории находятся на github.com, а git-прокси пока не поддерживает GitHub Enterprise Server. На раннере с git-прокси сессия с репозиторием на другом git-хостинге не запускается.
Учётные данные только для репозиториев сессии: Anthropic предоставляет учётные данные git для репозиториев, входящих в сессию, но не для других репозиториев на том же git-хостинге. Приватный субмодуль, зависимость, которую ваш менеджер пакетов получает через git, или маркетплейс плагинов в другом репозитории не получают учётных данных от Anthropic. Попросите тех, кто создаёт сессии, добавлять каждый репозиторий, который нужен сессии, при её создании.

Каждый запуск облачной запланированной задачи — это сессия с репозиториями задачи, поэтому попросите владельца каждой задачи добавить каждый репозиторий, который нужен её запускам.
Только push веток: push, который удаляет ветку, завершается ошибкой, как и push в ref любого другого типа, например в тег. О том, какие ветки может обновлять push, см. GitHub-прокси.
Подключённые аккаунты GitHub: попросите каждого, кто создаёт пользовательские сессии с репозиторием, подключить GitHub. Без собственного подключения такие сессии не запускаются.
--capacity 1: git-прокси требует одну сессию на процесс раннера, поэтому для параллелизма запускайте больше реплик. Требования перечислены в разделе Включение git-прокси Anthropic.
Заменённая глобальная конфигурация git: раннер удаляет и заменяет глобальную конфигурацию git пользователя, от имени которого он запущен. Запускайте его от имени отдельного пользователя или в контейнере.
Учётные данные хоста для push с хоста: push с помощью --push-outcome-on-release раннера и любой push, который делает ваш хук post-session, по-прежнему используют собственные учётные данные git хоста раннера и его сетевой путь к github.com. Не храните эти учётные данные в глобальной конфигурации git; способы их предоставления описаны в разделе Поставляйте конфигурацию git в своём образе.
Решение для каждой сессии: Anthropic решает для каждой сессии на раннере, обслуживать ли её git, и сессия, которую он не обслуживает, не запускается. Причины описаны в разделе Когда сессии не запускаются на раннере с git-прокси.

[!WARNING]

Когда задан --use-anthropic-git-proxy, раннер удаляет и заменяет глобальную конфигурацию git пользователя, от имени которого он запущен, и не сохраняет резервную копию. Он делает это при запуске и перед каждой сессией. Данные входа или вспомогательная программа учётных данных, которые вы там хранили, теряются. Настройки, которые записывает --configure-git, сохраняются. Запускайте раннер от имени отдельного пользователя или в контейнере, но никогда от своего имени.

Храните несекретные настройки git, такие как идентификация и safe.directory, в системной конфигурации git.

Включение git-прокси Anthropic

Прежде чем запускать раннер с --use-anthropic-git-proxy, убедитесь, что хост раннера отвечает каждому из этих требований. Раннер отказывается запускаться, если требование к capacity или к git не выполнено:

Claude Code v2.1.267 или новее: более ранние версии принимают флаг, но не сообщают Anthropic о запросе на обслуживание git и не выводят строку Registering as opted in, поэтому Anthropic не обслуживает их сессии.
--capacity 1, значение по умолчанию: каждый процесс раннера обрабатывает одну сессию за раз, поэтому для параллелизма запускайте больше реплик.
Git 2.32 или новее: более старые версии git игнорируют конфигурацию git для отдельной сессии, которую раннер настраивает для git-прокси.

[!WARNING]

Рецепты для Kubernetes и Docker Compose на этой странице используют --capacity 4. Если вы добавите --use-anthropic-git-proxy или CLAUDE_RUNNER_USE_GIT_PROXY=1 в один из них, не изменив capacity на 1, раннер будет завершаться при запуске каждый раз, когда оркестратор его перезапускает. Задайте --capacity 1 и запускайте больше реплик для параллелизма. В разделе Когда раннер завершается показана строка, которую выводит раннер.

Чтобы включить git-прокси, добавьте --use-anthropic-git-proxy в команду раннера или задайте CLAUDE_RUNNER_USE_GIT_PROXY=1 в окружении раннера. Эта команда, выполненная в оболочке на хосте раннера, запускает раннер из быстрого старта с включённым git-прокси:

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>' --use-anthropic-git-proxy

При запуске раннер выводит Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy). Затем Anthropic решает для каждой сессии на этом раннере, обслуживать ли её git. Для каждой обслуживаемой сессии раннер записывает в лог строку [runner:session], содержащую governed git ACTIVE. Если вместо этого сессия не запускается, см. Когда сессии не запускаются на раннере с git-прокси.

Как Anthropic обслуживает git для сессии

Для сессии, которую обслуживает Anthropic, clone раннера и собственные fetch и push сессии проходят через Anthropic с аутентификацией собственным краткосрочным токеном сессии:

Пользовательские сессии: Anthropic использует OAuth-токен GitHub, сохранённый для создателя сессии.
Сессии ботов и агентов: Anthropic использует токен установки GitHub App вашей организации.
Перезапись URL: --git-host-rewrite и --git-ssh-rewrite не действуют на репозиторий, который обслуживает git-прокси.

Когда сессии не запускаются на раннере с git-прокси

На раннере, запущенном с --use-anthropic-git-proxy, сессия не запускается, если Anthropic не обслуживает её git. Найдите в логе раннера ошибку git, в которой указан адрес api.anthropic.com, содержащий /git_proxy/.

Для каждой сессии раннер на Claude Code v2.1.267 или новее также записывает в лог либо строку [runner:session], содержащую governed git ACTIVE, если Anthropic обслуживает git сессии, либо одну строку [runner:warn], содержащую the server withheld Anthropic-managed git for this session, если нет. Найдите строку, которую вы видите, среди следующих случаев:

Нет ни governed git ACTIVE, ни строки withheld: раннер старше Claude Code v2.1.267 не записывает ни одну из этих строк, и Anthropic не обслуживает его сессии. Обновите раннер до v2.1.267 или новее, следуя разделу Закрепление версии.
Строка withheld: Anthropic не обслужил сессию. Раннер, который раньше работал с git-прокси, может начать так завершаться без каких-либо изменений с вашей стороны.
- Репозиторий находится не на github.com: сессия, у которой хотя бы один репозиторий находится на другом git-хостинге, например GitHub Enterprise Server, не обслуживается, включая её репозитории на github.com. Отключите git-прокси Anthropic для раннеров этой среды.
- Все репозитории находятся на github.com: сообщите о сбое вашей команде по работе с аккаунтом в Anthropic, указав ID сессии из строки withheld. Anthropic записывает причину на своей стороне.
Строка, содержащая remote: access denied by the git proxy: сессии, которую обслуживает Anthropic, всё равно может быть отказано, например когда политика организации запрещает доступ к git для сессии или у сессии нет авторизации для репозитория. Тогда в логе раннера есть строка, содержащая remote: access denied by the git proxy, и остальная часть этой строки объясняет причину.
GitHub authentication required: появляется, когда у создателя сессии нет работающего подключения GitHub на claude.ai. Clone сессии завершается ошибкой, и ошибка git гласит GitHub authentication required. Please reconnect your GitHub account. Попросите этого человека подключить или переподключить GitHub в настройках claude.ai.

После устранения причины снова запустите сессии, которые не запустились.

Отключение git-прокси Anthropic

Если сессии в среде используют репозиторий на git-хостинге, отличном от github.com, например GitHub Enterprise Server, отключите --use-anthropic-git-proxy для раннеров этой среды.

1. Удалите флаг

Удалите --use-anthropic-git-proxy из команды раннера. Если вы задали CLAUDE_RUNNER_USE_GIT_PROXY в окружении раннера, например в спецификации пода или в файле Compose, удалите её оттуда. В оболочке сбросьте её:

unset CLAUDE_RUNNER_USE_GIT_PROXY

2. Предоставьте раннеру учётные данные git

Предоставьте учётные данные, работающие без запроса ввода, для каждого git-хостинга, который используют сессии раннеров, включая github.com. Любые учётные данные, которые были в глобальной конфигурации git пользователя раннера, утеряны, потому что раннер удалил эту конфигурацию, пока был задан --use-anthropic-git-proxy. Поставляйте учётные данные в своём образе или используйте хук жизненного цикла checkout.

3. Откройте сетевой путь

Разрешите раннеру обращаться к каждому git-хостингу, который используют сессии раннеров, по порту 443 или 22. См. строку о git-хостинге в разделе Сетевые требования.

4. Перезапустите раннеры

Перезапустите раннеры, чтобы они зарегистрировались без git-прокси. Затем снова запустите каждую сессию, которая не запустилась.

Доступ к API GitHub без GitHub CLI

Если в вашем образе раннера нет GitHub CLI, Claude Code может предоставить встроенный gh, чтобы Claude всё равно мог открывать pull request, оставлять комментарии и читать результаты CI. Встроенный gh предназначен для раннеров, использующих git под управлением Anthropic. Он поддерживает одну команду, gh api, которая вызывает REST API GitHub. Требуется Claude Code v2.1.287 или новее в образе раннера.

Эта команда открывает pull request вместо gh pr create. Встроенный gh подставляет {owner} и {repo} для текущего репозитория:

gh api repos/{owner}/{repo}/pulls -f title='Fix' -f head='my-branch' -f base='main'

Учётные данные: встроенный gh отправляет свои REST-запросы через git под управлением Anthropic, который предоставляет учётные данные GitHub на стороне Anthropic, поэтому образу не нужен токен GitHub для этого
Какие сессии его получают: Anthropic решает для каждой сессии, обслуживает ли git под управлением Anthropic gh этой сессии. Если да, строка [runner:session] governed git ACTIVE, которую раннер записывает в лог для сессии, показывает gh_path_shim=true. Если нет, у сессии нет gh
jq: установите jq в образ, если хотите, чтобы работал --jq
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: если окружение сессии задаёт эту переменную, Claude Code не предоставляет встроенный gh, и у сессии нет gh

Если образ включает GitHub CLI, сессии используют его.

Доверие частному центру сертификации при использовании git под управлением Anthropic

Этот раздел применим, если вы задаёте GIT_SSL_CAINFO или GIT_SSL_NO_VERIFY в окружении раннера, сессии которого используют git под управлением Anthropic. Описанная обработка требует, чтобы раннер работал на Claude Code v2.1.283 или новее.

Когда git на раннере должен доверять частному центру сертификации (CA), например тому, которым подписывает сертификаты прокси с TLS-инспекцией, обычные подходы работают следующим образом:

Системное хранилище сертификатов: установите свой CA в системное хранилище сертификатов хоста раннера, и git будет доверять ему без обеих переменных.
GIT_SSL_CAINFO: задайте в ней PEM-файл ваших CA, например GIT_SSL_CAINFO=/etc/ssl/corp-ca.pem.
GIT_SSL_NO_VERIFY: не помогает за прокси, переподписывающим сертификаты. Собственный clone раннера через git под управлением Anthropic проверяет сертификаты, даже когда переменная задана, поэтому этот clone завершается ошибкой, пока git не начнёт доверять вашему CA одним из двух других способов.

Для git-соединений, которые передают токен сессии в git под управлением Anthropic, раннер применяет эти две переменные следующим образом. Хук command запускается с окружением сессии, поэтому получает то же, что и git внутри сессии:

GIT_SSL_CAINFO: по чему git проверяет git под управлением Anthropic, зависит от того, где запущен git:
- Собственные clone и fetch раннера: выполняются без переменной и проверяют git под управлением Anthropic по файлу сертификатов для отдельной сессии, который записывает раннер. Раннер собирает этот файл из системного пакета CA хоста раннера и сертификатов из вашего файла.
- Git внутри сессии: получает конфигурацию http.sslCAInfo с указанием вашего файла вместо переменной, а также записи http.<url>.sslCAInfo, которые проверяют git под управлением Anthropic по файлу для отдельной сессии.
- Хуки checkout и post-session: наследуют переменную без изменений.
GIT_SSL_NO_VERIFY: какие проверки сертификатов остаются отключёнными, зависит от того, где запущен git:
- Собственные clone и fetch раннера: выполняются без переменной и проверяют предъявленный им сертификат.
- Git внутри сессии: получает конфигурацию http.sslVerify=false вместо переменной, поэтому проверки остаются отключёнными для других хостов. Он также получает записи http.<url>.sslVerify=true, которые сохраняют проверки включёнными для git под управлением Anthropic.
- Хуки checkout и post-session: когда у сессии есть репозиторий в git под управлением Anthropic, получают конфигурацию http.sslVerify=false вместо переменной. Они также получают записи http.<url>.sslVerify=true, которые сохраняют проверки включёнными для git под управлением Anthropic.

Для файла сертификатов отдельной сессии нужен системный пакет CA по пути /etc/ssl/certs/ca-certificates.crt или /etc/pki/tls/certs/ca-bundle.crt на хосте раннера. Также нужен файл GIT_SSL_CAINFO, который может прочитать пользователь раннера, который содержит PEM-блоки CERTIFICATE и размер которого не превышает 1 МиБ. Если раннер не может собрать файл для отдельной сессии, он записывает в лог строку [runner:warn], содержащую did not build the certificate file и причину. Тогда git использует ваш файл как есть для git под управлением Anthropic. Исправьте то, что указано в строке.

Для каждой сессии, использующей git под управлением Anthropic, раннер также записывает в лог строку [runner:warn], которая начинается с governed git: GIT_SSL_CAINFO is set или governed git: GIT_SSL_NO_VERIFY is set. Строка сообщает, что раннер сделал с этой переменной для собственного git, для git внутри сессии и для ваших хуков жизненного цикла. В конце она указывает, нужно ли вам что-либо менять.

Перезапись URL git для частных сетей

URL репозиториев поступают из плоскости управления в формате HTTPS с именем хоста вашего git-хостинга; для GitHub Enterprise это имя хоста, которое вы настроили для интеграции GitHub Enterprise на claude.ai. Два повторяемых флага перезаписывают эти URL перед clone:

--git-host-rewrite <from>=<to>: для split-horizon DNS, когда Anthropic обращается к вашему git-хостингу по внешнему имени хоста, а раннеры должны использовать внутреннее
--git-ssh-rewrite <host>: для git-хостингов, принимающих только SSH, или для хоста раннера, у которого есть только ключ SSH. Например, чтобы клонировать репозитории github.com через SSH, добавьте --git-ssh-rewrite github.com в команду раннера. Тогда раннер перезаписывает https://github.com/owner/repo в git@github.com:owner/repo. SSH должен подключаться без запроса ввода.

Перезапись хоста выполняется первой, поэтому если вам нужны обе, укажите в --git-ssh-rewrite внутреннее имя хоста. Для полного контроля над извлечением используйте хук жизненного цикла checkout.

Постройте образ runner

Anthropic не публикует предварительно построенный образ runner. Постройте свой собственный вокруг бинарного файла claude, наслаивая любой набор инструментов, который нужен вашим репозиториям: языковые среды выполнения, компиляторы, менеджеры пакетов и MCP sidecars.

Рецепты ниже используют --capacity 4, поэтому один контейнер обслуживает до четырех одновременных сеансов от одного заблокированного владельца. Это не обеспечивает изоляцию контейнера для каждого сеанса в разделе усиления безопасности: перед подключением окружения к production-системам либо запустите рецепты на --capacity 1 с одним контейнером на сеанс, либо используйте on-demand runners, которые также держат секрет окружения вне хостов, запускающих сеансы. Если вы добавите Anthropic git proxy к одному из этих рецептов, также измените --capacity на 1.

Этот Dockerfile является минимальной отправной точкой:

FROM debian:bookworm-slim
ARG CLAUDE_CODE_VERSION
RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client jq \
 && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \
      -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude
RUN git config --system user.name "Claude" \
 && git config --system user.email "noreply@anthropic.com" \
 && git config --system --add safe.directory '*'
ENTRYPOINT ["claude"]

Замените linux-x64 на linux-arm64, если ваши узлы ARM, или на linux-x64-musl или linux-arm64-musl на образе на основе musl, таком как Alpine; см. Alpine Linux setup для дополнительных пакетов, которые нужны образам musl. URL является стандартным местоположением выпуска Claude Code, поэтому вы можете проверить загруженный бинарный файл против подписанного манифеста выпуска, как описано в Binary integrity and code signing. Runner требует версию Claude Code 2.1.224 или позже. Постройте образ, затем отправьте его в ваш реестр и ссылайтесь на него в рецептах ниже:

docker build \
  --build-arg CLAUDE_CODE_VERSION="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \
  -t <your-registry>/claude-runner:latest .

Подстановка команды ищет текущий номер выпуска stable и передает его как аргумент сборки, поэтому запуск той же команды после нового стабильного выпуска перестраивает слой загрузки с более новым бинарным файлом. Чтобы закрепить конкретный выпуск для воспроизводимых сборок, передайте номер версии непосредственно как CLAUDE_CODE_VERSION. Замените stable на latest в URL поиска, когда вам нужен выпуск новее, чем стабильный канал, например, тот, который требует недавно запущенная модель.

Размер CPU и памяти для сеансов

Размер контейнера или хоста runner для сеансов, которые он запускает, а не для самого процесса runner. Runner сам опрашивает работу, подготавливает checkout каждого сеанса, запускает ваши lifecycle hooks и запускает и контролирует процессы сеанса. Нагрузка исходит от сеансов: каждый из них является процессом Claude Code плюс все, что он запускает, такое как сборки, наборы тестов, установки пакетов и MCP servers.

Для одного сеанса начните со следующих значений, указанных как запросы и лимиты Kubernetes или эквивалент вашей платформы, и рассматривайте их как отправную точку, а не требование:

Память: запрос и лимит 4 ГиБ каждый, что соответствует минимуму 4 ГБ в системных требованиях Claude Code. Держите их равными, чтобы планировщик учитывал полную память контейнера. Когда контейнер достигает своего лимита памяти, ядро убивает процессы внутри него, что может завершить сеанс в середине задачи.
CPU: запрос 2 CPU и лимит 4 CPU, чтобы сеанс мог всплеснуть выше запроса во время сборок. Ядро дросселирует контейнер на его лимите CPU, а не убивает процессы в нем, поэтому сеансы на лимите работают медленнее, но продолжают работать.

В спецификации контейнера Kubernetes установите эти начальные значения с помощью следующего блока resources:

resources:
  requests:
    cpu: "2"
    memory: 4Gi
  limits:
    cpu: "4"
    memory: 4Gi

Сборки и тесты обычно являются самой большой и наиболее переменной частью нагрузки сеанса, поэтому запустите репрезентативную сборку вашего репозитория, измерьте его пиковый CPU и память и поднимите любое начальное значение, которое не оставляет места для процесса Claude Code на вершине этого пика.

Runner использует --capacity для ограничения количества сеансов, которые он запускает одновременно. Он не делит CPU или память между ними, поэтому сеансы на runner делят CPU и память контейнера. Чтобы ограничить долю одного сеанса, применяйте лимиты из вашего скрипта-обертки. То, что дать одному контейнеру, поэтому зависит от того, сколько сеансов он обслуживает одновременно:

Один сеанс на runner: дайте каждому контейнеру значения одного сеанса. Используйте эту размер на --capacity 1, которую раздел усиления безопасности рекомендует, и для on-demand runners, где вы устанавливаете значения на рабочую нагрузку, которую ваш spawn-runner hook отправляет, такую как шаблон pod Kubernetes Job.
Несколько сеансов на runner: на --capacity выше одного, умножьте значения одного сеанса на емкость, потому что до такого количества сеансов может работать в контейнере одновременно. Рецепты Kubernetes и Docker Compose запускают --capacity 4 без лимитов CPU или памяти, поэтому добавьте лимиты, размер которых соответствует емкости, которую вы запускаете.

Kubernetes

Runner обслуживает GET /healthz на порту 8080 по умолчанию, конфигурируемом с помощью --health-port, поэтому зонды Kubernetes работают без дополнительной настройки. Конечная точка возвращает 200 всякий раз, когда процесс живой, поэтому зонды ниже обнаруживают мертвый процесс, а не застрявший; чтобы поймать runner, который перестал опрашивать, установите оповещение на серию last_poll_age_seconds из /metrics. Развертывание ниже монтирует секрет окружения из Kubernetes Secret, указывает зонды liveness и readiness на /healthz и устанавливает период завершения 90 секунд. См. Shutdown timing для того, почему период завершения имеет значение.

Манифест не устанавливает resources CPU или памяти на контейнер runner. Добавьте блок, размер которого соответствует емкости, которую вы запускаете, как описано в Size CPU and memory for sessions.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-runner
  namespace: claude-runners
spec:
  replicas: 3
  selector:
    matchLabels:
      app: claude-runner
  template:
    metadata:
      labels:
        app: claude-runner
        app.kubernetes.io/part-of: claude-code-self-hosted-runner
    spec:
      terminationGracePeriodSeconds: 90
      containers:
        - name: runner
          image: <your-registry>/claude-runner:latest
          args:
            - self-hosted-runner
            - --environment-secret-file
            - /etc/claude/environment-secret
            - --capacity
            - "4"
            - --base-dir
            - /workspace
          volumeMounts:
            - name: environment-secret
              mountPath: /etc/claude
              readOnly: true
          ports:
            - name: health
              containerPort: 8080
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 30
      volumes:
        - name: environment-secret
          secret:
            secretName: claude-runner-environment-secret

Развертывание выше живет в пространстве имен claude-runners. Сначала создайте пространство имен:

kubectl create namespace claude-runners

Создайте поддерживающий Secret из локального файла, содержащего значение, которое вы скопировали на шаге Copy environment key в пользовательском интерфейсе администратора, чтобы секрет никогда не появлялся в истории вашей оболочки. Запустите (umask 077 && cat > ./environment-secret), вставьте секрет, нажмите Enter, затем Ctrl-D. Затем создайте Secret и удалите файл:

kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

Docker Compose

Сервис Compose ниже перезапускает runner всякий раз, когда он выходит, что охватывает как сбои, так и нормальный выход после осушения. Политика перезагрузки Docker перезапускает тот же контейнер с его записываемым слоем нетронутым, поэтому runner возвращается на переиспользованной файловой системе, а не на свежей, которую рекомендует позиция усиления безопасности; используйте этот рецепт для оценки, и для production либо пересоздайте контейнер за запуск, либо используйте оркестратор, который это делает.

Docker ждёт дольше перед каждым перезапуском контейнера, который продолжает выходить, вплоть до потолка, поэтому runner, который не может запуститься, не продолжает перезапускаться в плотном цикле под этим рецептом. Когда runner выходит описывает, что проверить, когда это происходит.

services:
  claude-runner:
    image: <your-registry>/claude-runner:latest
    command:
      - self-hosted-runner
      - --environment-secret-file
      - /run/secrets/environment-secret
      - --capacity
      - "4"
      - --base-dir
      - /workspace
    secrets:
      - environment-secret
    restart: always
    stop_grace_period: 90s

secrets:
  environment-secret:
    file: ./environment-secret

Время завершения работы

После SIGTERM runner нужно время, чтобы корректно завершить свои сессии, прежде чем ваш оркестратор его убьёт. Сколько именно, он записывает в лог при запуске, в строке, которая при настройках по умолчанию содержит This runner needs up to 80s. Установите таймаут остановки вашего оркестратора не меньше этого количества секунд: terminationGracePeriodSeconds в Kubernetes, stop_grace_period в Docker Compose или эквивалент на вашей платформе. В Kubernetes значение по умолчанию составляет 30 секунд, поэтому без этой настройки он может остановить pod до того, как runner завершит работу.

При получении SIGTERM runner перестаёт принимать новые сессии. Затем он начинает корректное завершение работы, называемое drain, если только вы не установили --defer-shutdown-max-min, чтобы отложить его. Drain состоит из трёх шагов:

Runner ждёт до --drain-wait-sec секунд, по умолчанию 0, пока завершатся ещё выполняемые ходы.
Он завершает дерево процессов каждой сессии, включая любую команду, которую Claude всё ещё выполнял, но не процесс, продолжающий работать после завершения своей shell-команды.
Он запускает lifecycle-хук post-session.

Runner продолжает опрашивать Anthropic на протяжении всего drain. Благодаря этому его сессии остаются закреплены за ним, и другой runner не подхватит ни одну из них, пока ваш хук post-session ещё сохраняет незафиксированную работу.

Время, записываемое в лог, является суммой следующих значений:

--drain-wait-sec для шага 1, по умолчанию 0 секунд
--session-stop-grace-sec для шага 2, по умолчанию 5 секунд
--post-session-hook-timeout-sec для шага 3, по умолчанию 60 секунд
Фиксированный запас в 15 секунд
Ещё 30 секунд, когда установлен --push-outcome-on-release

При настройках по умолчанию это составляет 0 + 5 + 60 + 15 = 80 секунд. Более высокое значение --capacity не увеличивает это время, потому что runner выполняет drain всех своих сессий одновременно.

Выделите больше времени, если вы устанавливаете любой из этих флагов:

С --retire-at: оставьте между временем retire и временем остановки хоста достаточно времени для завершения типичных ходов, плюс ожидание фоновых задач, которое описывает Runner lifecycle, плюс время, записанное в лог. Вычисляйте время retire при каждом запуске, например date +%s плюс предполагаемое время жизни runner.
С --defer-shutdown-max-min: таймаут остановки также должен охватывать настроенные вами минуты и дополнительное ожидание перед началом drain, 75 секунд при настройках по умолчанию. Оба значения объясняются в разделе Defer the drain past the first signal. Runner также записывает это более длительное время в лог при запуске.

Дайте выполняемым ходам завершиться перед перезапуском

Чтобы дать выполняемым ходам завершиться перед rolling restart, установите --drain-wait-sec и увеличьте таймаут остановки как минимум до этого ожидания плюс 80 секунд. При значении ожидания по умолчанию 0 перезапуск прерывает любой ещё выполняемый ход, и сессия возобновляется на другом runner без своей неотправленной работы.

--drain-wait-sec: примерно столько, сколько длятся ходы и фоновые задачи, которым вы хотите дать завершиться. Это максимум: ожидание заканчивается раньше, если они завершатся первыми.
Ваш таймаут остановки: terminationGracePeriodSeconds в Kubernetes, stop_grace_period в Docker Compose. Например, при --drain-wait-sec 120 замените 90 в рецепте для Kubernetes или Docker Compose на 200.
Если вы изменили другие настройки завершения работы: 80 секунд рассчитаны на настройки по умолчанию. Запустите один runner с вашими флагами и используйте как минимум число из его стартовой строки This runner needs up to, которое включает ожидание. Если установлен --defer-shutdown-max-min, используйте большее число из следующей стартовой строки, после Size the stop timeout to at least. В разделе Время завершения работы перечислено, что увеличивает эти числа.

[!WARNING]

Если таймаут остановки истекает во время ожидания, ваш хост убивает runner, пока работа ещё выполняется. Его сессии не получают хук post-session. Runner также не отменяет регистрацию, поэтому control plane может потребоваться несколько минут, а иногда и больше, чтобы переставить их в очередь.

Опубликуйте статусное сообщение перед перезапуском

Перед перезапуском, который прервёт сессии, попросите Owner опубликовать статусное сообщение в среде на странице администратора Cloud environments. На claude.ai/code участники видят это сообщение в своих сессиях в этой среде. Попросите Owner указать срок действия при публикации или удалить сообщение, когда runner снова заработают.

Defer the drain past the first signal

Установите --defer-shutdown-max-min <n>, если вы хотите, чтобы runner, который вы перезапускаете, продолжал обслуживать сессии, которые он удерживает, до n минут, вместо того чтобы выполнять их drain при первом сигнале. При первом SIGTERM или SIGINT runner прекращает принимать новую работу и продолжает обслуживать сессии, которые он удерживает. Он продолжает опрашивать, чтобы control plane не переставлял эти сессии. Требует Claude Code v2.1.238 или позже.

Что происходит с сессиями, которые runner удерживает после первого сигнала

На первых двух этапах, следующих за сигналом, runner выпускает сессии, и выпущенная сессия возобновляется на свежем runner, когда её пользователь отправляет следующее сообщение. Отсчитывая от первого сигнала, runner проходит через три этапа:

В течение первых n минут: runner обслуживает свои сессии нормально и продолжает применять --startup-timeout-min и --kill-session-after-min. Если вы также установили --release-idle-session-min, runner выпускает любую сессию, пользователь которой был неактивен столько времени; без этого неактивные сессии остаются на runner.
Когда истекают n минут: runner выпускает каждую сессию, которую он всё ещё удерживает, неактивную или нет. Runner ждёт, пока завершится ход сессии, находящейся посреди хода, и ещё до 60 секунд для фоновых задач этого хода, прежде чем выпустить эту сессию.
Когда истекает post-release grace: runner выполняет drain любых сессий, которые он всё ещё удерживает, и control plane сразу же переставляет каждую такую сессию на другой runner. Post-release grace начинается, когда истекают n минут, и составляет 75 секунд при значениях по умолчанию. Если вы установили --drain-wait-sec выше 60 секунд, post-release grace вместо этого составляет --drain-wait-sec плюс 15 секунд.

На любом этапе runner выходит с кодом 0, как только он не удерживает никаких сессий. Второй сигнал сокращает этапы: runner немедленно выполняет drain, как он это делает при первом сигнале без --defer-shutdown-max-min. Как только drain находится в процессе, следующий сигнал принудительно завершает runner. Это верно независимо от того, начал ли drain второй сигнал или истечение post-release grace.

Установите таймаут остановки

Дайте таймауту остановки вашего хоста по крайней мере сумму трёх частей: n минут, которые вы настраиваете, post-release grace и drain, который описывает раздел Время завершения работы. При настройках по умолчанию post-release grace составляет 75 секунд, а drain занимает до 80 секунд, поэтому выделите n минут плюс 155 секунд. Runner выводит эту сумму при запуске всякий раз, когда установлен --defer-shutdown-max-min.

Если таймаут остановки истекает до того, как runner завершит работу, сессии, которые он всё ещё удерживает, не получают хук post-session. Runner не отменяет регистрацию, поэтому control plane может потребоваться несколько минут, а иногда и больше, чтобы переставить эти сессии. Если вы не можете дать таймауту остановки эту сумму, оставьте --defer-shutdown-max-min неустановленным, чтобы runner вместо этого выполнял drain при первом сигнале.

Что достигает работающего хука post-session

Хук post-session и дочерний процесс сессии Claude каждый запускаются в своей собственной POSIX-группе процессов, отдельно от runner, поэтому механизмы остановки достигают их по-разному:

SIGTERM, пока runner уже выполняет drain: немедленно принудительно завершает runner, пропуская всё, что остаётся от drain. Без --defer-shutdown-max-min это второй SIGTERM, который получает runner. Ничто не отправляет сигнал работающему хуку post-session, поэтому на голом хосте, где init-процесс усыновляет осиротевшие процессы, он завершается самостоятельно, но без надзора: его бюджет таймаута больше не применяется, и запись в закрытый канал логов может убить его с SIGPIPE, поэтому хук, который должен пережить принудительное завершение в такой среде, должен перенаправлять свой собственный вывод в файл. В рецептах контейнеров на этой странице runner является PID 1 контейнера и его выход завершает контейнер, а при используемом systemd по умолчанию KillMode=control-group завершение всей cgroup достигает и хука, как описывает пункт Cgroup-wide kills; в обоих случаях рассматривайте принудительное завершение как фатальное для хука и полагайтесь вместо этого на период grace.
Process-group-wide signals, такие как kill -- -<pid> в скрипте-обёртке, управление заданиями оболочки или watchdog на уровне группы: достигают runner и подпроцесса, работающего посреди хука checkout, который намеренно остаётся привязанным к группе, но не работающего хука post-session или дочернего процесса сессии.
Cgroup-wide kills, такие как используемый systemd по умолчанию KillMode=control-group или SIGKILL, который Kubernetes доставляет всему контейнеру, когда истекает terminationGracePeriodSeconds: достигают всего, включая хук. Изоляция группы процессов не защищает от этого, поэтому период grace должен охватывать весь drain.
Собственный таймаут хука: когда хук превышает --post-session-hook-timeout-sec, runner отправляет SIGTERM на всю группу процессов хука, затем SIGKILL две секунды спустя, поэтому рабочий процесс, порождённый хуком, такой как tar, rsync или git, завершается вместе с оболочкой-обёрткой, а не выживает как осиротевший процесс. Надзор runner заканчивается, как только stdio хука закрывается: рабочий процесс, который перенаправил свой собственный вывод в файл и пережил этап SIGTERM, находится вне досягаемости runner.

Когда начинается drain, и снова при принудительном завершении, runner записывает в лог, сколько хуков post-session всё ещё работают, поэтому вы можете отличить тихий drain от того, который находится посреди создания снимка.

Держите базовый каталог и емкость идентичными на всех runners

Если runner умирает в середине сеанса, сервер переставляет сеанс в очередь и другой runner в окружении его подхватывает. Этот runner выводит путь checkout из своего собственного --base-dir и --capacity: --capacity 1 проверяет прямо под --base-dir, и --capacity выше 1 использует вместо этого per-session worktrees. Когда runners в одном окружении используют разные значения для любого флага, рабочий каталог возобновленного сеанса изменяется, и абсолютные пути, которые агент записал ранее, в редактированиях, вызовах инструментов или своих собственных заметках, указывают на местоположение, которое больше не существует.

Используйте одинаковые --base-dir и --capacity на каждом runner в окружении и не используйте значение для каждого хоста, такое как ID экземпляра или имя хоста. Передавайте оба флага явно, как это делают рецепты для Kubernetes и Docker Compose, чтобы ни одно из значений не зависело от значения по умолчанию.

Базовый каталог по умолчанию /workspace, с исключением, которое записывает строка справочника --base-dir. Runner нуждается в доступе на запись к нему. При запуске, перед регистрацией, runner создает каталог и подтверждает, что может писать в него, и выходит с cannot create or write to base directory, когда не может. Runner, запущенный как root, создает по умолчанию /workspace сам. Для non-root runner создайте каталог и дайте пользователю runner владение перед запуском runner, или укажите --base-dir на каталог, который этот пользователь уже владеет.

Переиспользуйте pre-warmed checkout

Для больших репозиториев клонирование может занимать бо́льшую часть времени запуска сессии. Чтобы пропустить холодное клонирование, подготовьте клон самостоятельно по тому пути, где runner хранит собственный. Без checkout хука runner хранит один канонический клон на репозиторий по пути <base-dir>/<repo-owner>/<repo> и переиспользует его между сессиями:

При --capacity 1: runner получает запрошенный ref, отсоединяет HEAD и выполняет жесткий сброс на него, что происходит почти мгновенно, когда изменилось немногое.
При --capacity больше единицы: runner выполняет fetch в этот клон, а затем создает из него отдельный worktree для каждой сессии. Pre-warmed клон экономит загрузку, но не checkout.

Подготовьте клон в образе или на постоянном томе:

Клон в образе: постройте клон в образ runner на этом пути. Каждый свежий контейнер затем начинается с теплым клоном без переиспользования диска.
Клон на постоянном томе: на runners, которые вы предварительно блокируете для учетной записи одного пользователя с --lock-to-account, укажите --base-dir на постоянный том, поэтому диск только когда-либо обслуживает эту учетную запись. Pre-locked runner никогда не подхватывает сеансы канала Claude Tag, поэтому этот вариант не применяется к runners, которые их обслуживают.

Что путь переиспользования делает и не гарантирует:

Любая форма клона работает: полный, неглубокий или однозвездный клон на пути используется как есть. Runner никогда не передает --depth при получении в существующий клон, поэтому полный pre-warm держит свою полную историю и неглубокий остается неглубоким. CLAUDE_RUNNER_FETCH_DEPTH (full, 0 или число; по умолчанию 50) контролирует только холодный клон, который runner делает, когда клон еще не существует.
Отслеживаемые изменения сбрасываются, неотслеживаемые файлы сохраняются: при --capacity 1 каждая сессия начинается с жесткого сброса, который стирает отслеживаемые изменения предыдущей сессии, но runner никогда не запускает git clean, поэтому неотслеживаемые файлы из более ранних сессий заблокированного владельца остаются в дереве.
Каталоги для каждого сеанса также сохраняются: рядом с checkout runner создает записи для каждого сеанса под <base-dir>/_sessions/ для каждого сеанса, который он запускает. Локальный каталог конфигурации Claude сеанса содержит локальную копию транскрипта беседы. Рядом с ним находятся загруженные файлы сеанса, когда сеанс их имеет. Каталог сеанса находится там же: он содержит любые worktrees для каждого сеанса и checkout hook checkouts во время работы сеанса, и он сохраняет все остальное, что Claude написал в нем.

По умолчанию runner оставляет их на месте, когда сеанс заканчивается, поэтому на диске, который пережил процесс runner, они накапливаются. Каждый сеанс запускается как собственный пользователь runner, поэтому любой более поздний сеанс, который обслуживает этот диск, может их прочитать. Если вы сохраняете постоянный --base-dir, размер тома для этого роста. То же самое применяется к любой установке, которая перезапускает runner на той же файловой системе, включая Docker Compose рецепт.
С --remove-session-state, каталоги для каждого сеанса не сохраняются: запустите runner с --remove-session-state, чтобы он удалял каталоги для каждого сеанса по мере завершения сеанса. Удаление является наилучшей попыткой: каталоги остаются, когда runner убивается до того, как его очистка запустится. Канонический клон и файлы, которые сеанс написал в другом месте на хосте, такие как временный каталог, остаются независимо.
С git proxy сброс превращается в checkout: с --use-anthropic-git-proxy runner очищает .git/ клона перед каждой сессией. Он сохраняет хранилище объектов и состояние shallow, а индекс удаляет. Без индекса каждая сессия начинается с полного checkout рабочего дерева вместо почти мгновенного сброса. Runner по-прежнему выполняет fetch в существующий клон, а не клонирует репозиторий заново. Pre-warm подмодулей при использовании прокси не поддерживается.
С git proxy pre-warm в формате reftable теряет свои refs: очищая .git/ перед каждой сессией, runner сохраняет .git/refs/ и удаляет каталог .git/reftable/. Клон, подготовленный в формате refs reftable в git, при этом теряет свои refs, поэтому выполняйте pre-warm клона в формате refs files.
Длинные клоны не нуждаются в обходном пути: runner ограничивает каждую операцию git с помощью 120-секундного наблюдателя без прогресса и 30-минутного жесткого лимита, а не плоского тайм-аута, поэтому медленный холодный клон, который продолжает сообщать о прогрессе, завершается.

Закрепите версию

Дочерний процесс каждой сессии по умолчанию запускает собственный бинарный файл runner, и runner отключает auto-update внутри сессий, которые он порождает. При таком поведении по умолчанию каждая сессия запускает версию, которую вы установили на хосте или встроили в образ. Обновление на уровне хоста вступает в силу в следующий раз, когда runner запускается.

Выберите, какую версию запускают ваши сессии и когда она меняется:

Перед тем как закрепить версию: проверьте версии Claude Code, которые требуют модели, для каждой модели, которую используют ваши сессии. Если модель требует более новую версию, чем та, которую запускают ваши сессии, сервер отклоняет запросы для этой модели с Claude Code does not support this model.
Чтобы держать флот на одной версии: постройте образ с закрепленной версией или на голом хосте установите конкретную версию и отключите auto-updates
Чтобы обновить фиксированный флот: прочитайте записи журнала изменений между вашей версией и той, которую вы устанавливаете, затем установите более новую версию или пересоберите образ и перезапустите runners
Чтобы обновить runners по требованию: прочитайте записи журнала изменений между вашей версией и той, которую вы устанавливаете, затем измените образ, который запускает ваш хук spawn-runner. Каждый новый runner получает новую версию. Runner, который уже запущен, включая резервный runner, запущенный --min-idle, сохраняет свою версию до завершения работы. Не перезапускайте его, потому что его рабочий заказ одноразовый.
Если сессии запускают другой бинарный файл: если вы используете --exec-path или хук command, чтобы запускать бинарный файл Claude Code, отличный от собственного бинарного файла runner, сессии запускают версию этого бинарного файла. Обновляйте этот бинарный файл при обновлении runner.
Плагины: рынки плагинов тоже не auto-update; установите FORCE_AUTOUPDATE_PLUGINS=1 в окружении runner, чтобы позволить плагинам auto-update, пока бинарный файл остается закрепленным

Масштабируйте флот

Ваш оркестратор решает, когда добавлять или удалять runners. Из-за блокировки one-owner-per-runner, минимальное количество реплик - это количество пользователей и агентов Claude Tag, которых вы ожидаете быть активными одновременно; --capacity контролирует параллелизм в пределах сеансов одного владельца, а не на всех владельцах.

Доступны два подхода к масштабированию:

Фиксированный флот: запустите статический набор реплик runner и масштабируйте на Prometheus metrics, которые обслуживает каждый runner
On-demand runners: запустите подкоманду claude self-hosted-runner orchestrator, которая опрашивает Anthropic для сеансов, которые поставлены в очередь без доступного runner и вызывает ваш hook spawn-runner для загрузки одного на сеанс. См. On-demand runners.

Известные проблемы и ограничения

Ниже приведены ограничения в этом выпуске с обходными путями, где они существуют.

Трафик коннектора покидает вашу сеть

Anthropic вызывает инструменты коннектора из своей собственной инфраструктуры, а не из вашего runner. Инструменты коннектора - это коннекторы claude.ai, такие как GitHub, Slack и Linear. Когда Claude использует коннектор в самостоятельно размещаемом сеансе, этот трафик идет через api.anthropic.com, а не исходит из границы вашей сети.

Чтобы держать коннектор вне самостоятельно размещаемых сеансов, отфильтруйте его с помощью allowedMcpServers и deniedMcpServers параметров политики. Claude Code применяет эти параметры к коннекторам, которые Anthropic доставляет, а также к серверам, которые вы сеете с хоста runner и серверам, которые пользователи добавляют, поэтому если вы развертываете список разрешений для других серверов, Claude Code блокирует доставленные коннекторы тоже. Чтобы держать коннекторы доступными наряду со списком разрешений на основе URL, добавьте записи, которые соответствуют путям прокси Anthropic для доставленных коннекторов:

https://api.anthropic.com/v2/ccr-sessions/*
https://api.anthropic.com/v1/code/sessions/*
https://api.anthropic.com/v1/code/mcp/*

Если трафик инструмента должен остаться внутри вашей сети, запустите эквивалентные инструменты как локальные MCP-серверы на образе runner вместо этого. См. MCP servers.

Некоторые сеансы не считаются неактивными

Сеанс, держащий фоновую задачу, которая никогда не заканчивается, не считается неактивным, поэтому --release-idle-session-min не выпустит слот этого сеанса. Сеанс, который ждет одобрения, запрошенного изнутри работающего вызова инструмента, тоже не считается неактивным. Всегда устанавливайте --kill-session-after-min рядом с ним как жесткий упор, чтобы никакой сеанс не мог держать слот неопределенно долго.

--kill-session-after-min является упором для убегающих сеансов. На runner на v2.1.260 или позже, сеанс, который достигает лимита, не завершается сразу. Runner дает ему окно благодати, 15 минут по умолчанию, которое вы можете изменить с помощью SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS:

Если сеанс ждет своего пользователя, runner выпускает его. Если его ход закончился и он держит только фоновые задачи, runner ждет до 60 секунд, чтобы эти задачи завершились, а затем выпускает его. Сеанс возобновляется, когда его пользователь отправляет свое следующее сообщение.
Если ход все еще работает, runner ждет, пока ход закончится, или пока сеанс не будет ждать своего пользователя, и затем выпускает его.
Если сеанс все еще на runner, когда окно благодати истекает, runner завершает его, и любая работа работающего хода потеряна. Ход, ожидающий одобрения, запрошенного изнутри работающего вызова инструмента, - это один способ, которым сеанс переживает окно.

Выпущенный сеанс возобновляется с свежего клона, поэтому работа, которую он не отправил, потеряна в любом случае; см. Resumed sessions lose unpushed work. До v2.1.260, runner завершал каждый сеанс на лимите, после ожидания максимум окна благодати для работающего хода, чтобы закончиться.

Установите флаг выше вашего самого длинного ожидаемого сеанса, такой как --kill-session-after-min 480 для 8 часов. Чтобы освободить слоты из разговоров, которые становятся неактивными, используйте вместо этого --release-idle-session-min.

Дополнительные ограничения

Возобновлённые сессии теряют неотправленную работу: новый runner заново клонирует репозиторий с его начальной ветки, поэтому работа, которую сессия не отправила, теряется.
- Чтобы сохранить закоммиченную работу: задайте --push-outcome-on-release на каждом runner в окружении, поскольку runner без этого флага возобновляет сессию с её начальной ветки. Runner с этим флагом перед освобождением по возможности отправляет (push) ветки результатов сессии, и возобновлённая сессия начинается с этих коммитов. Для push используются собственные учётные данные git хоста runner, в том числе на runner, который использует управляемый Anthropic git. Незакоммиченные изменения всё равно теряются.
- С хуком checkout: репозитории, извлечённые с помощью хука жизненного цикла checkout, не отправляются. Вместо этого сохраняйте их снимки из хука post-session.
- Перед включением флага: ограничьте круг тех, кто может выполнять push в refs claude/* на исходном удалённом репозитории. При возобновлении runner получает ранее отправленную ветку, не проверяя, кто её отправил.
Репозиторий, добавленный в середине сессии, может не клонироваться: Claude клонирует его с помощью git clone по HTTPS. На runner без --use-anthropic-git-proxy клонирование завершается ошибкой аутентификации git, если ничто на хосте не может прочитать репозиторий. По возможности выбирайте все необходимые сессии репозитории при её создании.
Некоторые коннекторы не появляются в самостоятельно размещаемых сеансах: коннектор, который вы еще не подключили в параметрах claude.ai, не указан в самостоятельно размещаемом сеансе, и сеанс не будет вас приглашать подключить его. Подключите его в параметрах сначала, затем запустите свежий сеанс. Добавление коннектора в уже работающий сеанс тоже не делает его инструменты доступными для Claude; запустите свежий сеанс, чтобы подхватить недавно добавленный коннектор.
Когда кто-то архивирует или удаляет сессию либо освобождает её runner из меню сессии: не рассчитывайте на push через --push-outcome-on-release. Чтобы сохранить коммиты в этих случаях, отправляйте HEAD в резервную ветку из хука post-session. Если вы берёте за основу приведённый там пример, сделайте так, чтобы он выполнял push, даже когда незакоммиченных изменений нет, поскольку он выполняет push только после коммита-снимка.

Сообщите о проблеме

Для проблем с самостоятельно размещаемыми окружениями свяжитесь с командой вашего аккаунта Anthropic.

Устранение неполадок

Для пошаговой диагностики запустите подкоманду doctor на хосте runner'а. Подкоманда doctor запускает интерактивную сессию Claude Code с подключёнными логами и состоянием runner'а. Сначала войдите в систему с помощью claude auth login на этом хосте, чтобы сессия могла запрашивать данные о вашем окружении, его runner'ах и его сессиях в очереди. Без этого входа, например когда хост проходит аутентификацию с помощью API-ключа, она ограничена локальным эндпоинтом проверки работоспособности, метриками и логом runner'а, причём лог она читает, только если вы запустили runner с --log-file.

claude self-hosted-runner doctor

Частые проблемы:

Runner не появляется в окружении: убедитесь, что хост может подключиться к api.anthropic.com по HTTPS, секрет окружения актуален, а часы хоста отклоняются от реального времени не более чем на пять минут; большее расхождение приводит к сбою аутентификации. При сбое аутентификации runner записывает в лог [runner:fatal] с причиной отказа.
Runner завершается при запуске с cannot create or write to base directory: runner не может создать --base-dir или записать в него; по умолчанию это /workspace. Исправьте владельца каталога или укажите в --base-dir путь, доступный для записи, как описано в разделе Сохраняйте одинаковые базовый каталог и ёмкость на всех runner'ах. Если вместо этого runner записывает в лог [runner:fatal] с сообщением о том, что истёк таймаут проверки базового каталога, каталог находится на зависшем монтировании NFS или CSI. Проверьте работоспособность монтирования, а не права доступа. Runner выводит оба этих сбоя запуска в stderr до того, как откроет --log-file, поэтому ищите их в терминале или в логах контейнеров вашей платформы, а не в файле лога. До v2.1.225 runner не проверял базовый каталог при запуске, и такая ошибка конфигурации вместо этого приводила к сбою сессий после их принятия.
Runner завершается при запуске с RegisterRunner failed: и ошибкой TLS-сертификата: например, ошибка может быть self signed certificate in certificate chain. Runner не доверяет центру сертификации (CA), выпустившему полученный сертификат, как бывает за прокси с инспекцией TLS. Задайте в окружении runner'а переменную NODE_EXTRA_CA_CERTS с путём к PEM-файлу, содержащему корневой CA прокси.

Для сессий её не нужно задавать повторно — они её наследуют. Git её не читает: для клонирования через этот прокси также задайте GIT_SSL_CAINFO.
Ваш стартовый скрипт выводит ошибку записи, содержащую Resource temporarily unavailable, и завершается: ваш скрипт делит stdout или stderr с запускаемым им процессом claude self-hosted-runner или оркестратора, который переключил этот общий канал или сокет в неблокирующий режим. Когда канал заполнен, запись из вашего скрипта вместо ожидания завершается этой ошибкой операционной системы, и при set -e скрипт завершается.

Чтобы устранить ошибку, направьте вывод runner'а или оркестратора в файл, который может создать пользователь вашего скрипта. Добавьте >> "$HOME/claude-runner.log" 2>&1 к команде, которая его запускает, перед любым &, переводящим её в фоновый режим:
```
claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret >> "$HOME/claude-runner.log" 2>&1
```
Собственный вывод вашего скрипта по-прежнему идёт туда же, куда и раньше, а то, что runner пишет в stdout и stderr, включая ошибки запуска, попадает в этот файл. Используйте это перенаправление оболочки, а не только --log-file, который дублирует лог в файл, пока runner продолжает писать в stdout и stderr. Если вы уже передаёте --log-file, сохраните и его, поскольку перенаправление не меняет того, что попадает в этот файл.
Оркестратор записывает в лог poll failed: с ошибкой TLS-сертификата и продолжает повторные попытки: оркестратор не доверяет CA, выпустившему полученный сертификат, как бывает за прокси с инспекцией TLS. Задайте в окружении оркестратора переменную NODE_EXTRA_CA_CERTS с путём к PEM-файлу, содержащему корневой CA прокси. Задайте её также для runner'ов, которые запускает ваш хук spawn-runner.

Например, строка может заканчиваться на poll failed: self signed certificate in certificate chain — retrying in 1s, где между двоеточием и тире стоят слова TLS-библиотеки. Чтобы убедиться, что проблема устранена, проверьте, что connected имеет значение true в теле ответа /healthz оркестратора.
Сессии остаются в очереди: возможно, каждый работающий runner закреплён за другим владельцем. Проверьте метрику claude_code_self_hosted_runner_locked_account каждого runner'а или поле locked_account его строки лога [runner:health], чтобы узнать, за кем он закреплён. Оба показывают email владельца только после того, как runner получил токен сессии с утверждением act.email, чего никогда не бывает с сессиями агента Claude Tag. Без этого утверждения runner не выдаёт серию locked_account и записывает в лог locked_account=yes, что говорит о том, что runner закреплён, но не за каким владельцем. Добавьте реплики или дождитесь, пока существующий runner завершит работу и перезапустится. Если окружение использует runner'ы по запросу, проверьте вместо этого оркестратор; см. Runner'ы по запросу.
Сессии завершаются сбоем сразу после принятия: откройте сессию в claude.ai/code, чтобы увидеть ошибку. Если ошибка показывает, что git не смог пройти аутентификацию, проверьте учётные данные git runner'а. Для runner'а, запущенного с --use-anthropic-git-proxy, см. Если сессии не запускаются на runner'е с git-прокси.

Базовый каталог, недоступный для записи, останавливает runner при запуске, а не приводит к сбою сессий. См. пункт Runner завершается при запуске с cannot create or write to base directory в этом списке.
Сессии не запускаются на runner'е, для которого задан --use-anthropic-git-proxy: ищите в логе runner'а access denied by the git proxy или ошибку git, в которой указан адрес api.anthropic.com, содержащий /git_proxy/. Чтобы определить, обслуживала ли Anthropic сессию, и устранить причину, см. Если сессии не запускаются на runner'е с git-прокси.
Сессии не могут выйти в сеть через исходящий прокси с аутентификацией: когда источник, заданный с помощью --proxy-authorization-command или --proxy-authorization-file, завершается сбоем, превышает таймаут в 30 секунд или возвращает пустое значение, runner отвечает на это соединение 502 Bad Gateway и записывает причину в лог. Runner скрывает stderr команды в этом логе и никогда не записывает в лог значение заголовка. При использовании --proxy-authorization-command выполните команду на хосте самостоятельно, чтобы убедиться, что она выводит полное значение заголовка в stdout. Если вместо этого runner завершается при запуске с could not start the proxy-authorization listener, он не смог открыть свой loopback-слушатель.
Runner записывает в лог строки Poll failed, содержащие rejecting the malformed poll response: runner получил ответ на опрос очереди работ, тело которого не является ожидаемым JSON очереди. Одна из причин — перехватывающий прокси или captive portal, отвечающий собственной страницей. Если runner подключается через прокси, настройте прокси так, чтобы ответы от api.anthropic.com передавались без изменений.

Runner отклоняет некорректный ответ, учитывает его в категории transport метрики claude_code_self_hosted_runner_poll_errors_total и повторяет попытку по расписанию для неудачных опросов, описанному в разделе Жизненный цикл сессии. Runner продолжает обслуживать свои активные сессии. До v2.1.246 runner воспринимал такой ответ как пустую очередь работ, что могло завершить его активные сессии или привести к его завершению.
Сессия завершается сбоем с no longer exists on the remote или couldn't find remote ref: runner воспринимает сообщение git couldn't find remote ref как удалённую ветку. При этом ветка может по-прежнему существовать. Поищите её на вашем git-хосте точно под тем именем, что указано в сообщении, затем проверьте каждую подходящую причину:
- Ветка удалена: восстановите её, как просит сообщение.
- Ветка существует, и вы не администрируете runner: отправьте администратору runner'а полное сообщение и сообщите, что ветка существует.
- Ветка существует, и у runner'а есть хук checkout: команда git в вашем хуке может вывести couldn't find remote ref в stderr до того, как хук завершится с ненулевым кодом. Найдите эту команду и исправьте ref, который она запрашивает, или remote, из которого она выполняет fetch. Runner передаёт вашему хуку ревизию, запрошенную сессией, в переменной CLAUDE_RUNNER_REPO_REF.
- Ветка существует, и у runner'а нет хука checkout: runner сам получает ветку. Если к репозиторию применяется --git-host-rewrite, убедитесь, что на хосте, на который выполняется перезапись, есть ветка с тем же именем, и отправьте ветку туда, если её нет.
- Ветка существует, и runner старше v2.1.301: обновите runner, как описано в разделе Закрепите версию, чтобы другой сбой показывал собственную ошибку. До v2.1.301 другие сбои, в выводе ошибки которых был couldn't find remote ref, также отображались как удалённая ветка.
После обновления runner'а или устранения причины повторите сессию или запустите новую. Если ни одна из этих проверок не выявила причину, сообщите о проблеме.

Для источника, в который сессия отправляет результаты, удалённая ветка приводит к сбою сессии. Для git-источника, из которого сессия только читает, runner пропускает этот источник и продолжает работу с остальными. Runner завершает сессию сбоем, если пропуск оставил бы её вообще без репозитория. До v2.1.228 такая сессия запускалась в пустом каталоге.
Сессия запускается без одного из своих репозиториев: на runner'е без хука checkout git-хост может отклонить проверку доступа runner'а к репозиторию, из которого сессия только читает. Тогда runner пропускает этот репозиторий, записывает в лог строку [runner:warn] could not access context source с указанием отказа и запускает сессию с остальными репозиториями.

Runner пропускает только явный отказ: хост отвечает, что репозиторий не найден, git не находит учётных данных для хоста или аутентификация не проходит. Сбой сети, таймаут или HTTP 403 по-прежнему приводят к сбою запуска сессии, как и отказ для репозитория, в который сессия отправляет результаты. Runner по-прежнему намеренно завершает сбоем сессию, которую пропуск оставил бы вообще без репозитория. С --use-anthropic-git-proxy runner пропускает только репозиторий, доступ к которому отклоняет сам git-прокси.

Проверка доступа выполняется заново при каждом запуске сессии на runner'е, поэтому, как только git-идентичность runner'а получит доступ на чтение, следующий запуск клонирует репозиторий. До v2.1.274 каждый из этих отказов приводил к сбою запуска сессии.
Сессия не запускается с This runner couldn't read: runner запросил у git-хоста репозиторий со своими учётными данными git и получил ответ «не найдено». Репозиторий не существует, или эти учётные данные не дают доступа к репозиторию.
- Если вы администрируете runner: предоставьте его учётным данным git доступ на чтение к репозиторию, затем запустите новую сессию.
- Если вы запустили сессию: если репозиторий не существует, запустите новую сессию с правильным репозиторием. Если у runner'а нет доступа к репозиторию, попросите администратора runner'а предоставить доступ, затем запустите новую сессию.
Сессии запускаются несколько минут: обычно основное время занимает первоначальное клонирование. Чтобы убедиться в этом, следите за метрикой claude_code_self_hosted_runner_session_init_duration_seconds, и сократите клонирование с помощью предварительно подготовленного checkout или меньшего значения CLAUDE_RUNNER_FETCH_DEPTH.
Ходы завершаются с ошибкой 401: когда ход заканчивается ответом 401 или 403 от Anthropic API, runner получает новый CLAUDE_CODE_OAUTH_TOKEN от Anthropic и передаёт его сессии. Неудавшийся ход не повторяется. Этот токен краткосрочный, и runner ротирует его через stdin сессии.

Когда получение токена не удаётся, runner записывает в лог строку inference_token refresh failed с указанием, когда будет повторная попытка, и продолжает повторять попытки, пока работает сессия.

Если все вызовы начинают завершаться сбоем примерно через 30 минут после начала сессии, вероятно, скрипт-обёртка отключил stdin сессии, поэтому ротации токена не могут до неё дойти; см. Сохраняйте подключёнными stdin и файловый дескриптор 3.

До v2.1.274 runner прекращал повторные попытки получения токена после нескольких неудач и ждал следующего запланированного получения. Неудавшийся ход не вызывал получение токена, поэтому каждый ход завершался ошибкой 401 до следующего запланированного получения.
Ход завершается в claude.ai/code с This model needs a newer version of Claude Code: версия Claude Code, с которой ваши runner'ы запускают сессии, старше, чем требует модель сессии, поэтому API отклоняет запрос. Обновите runner'ы до версии, указанной в сообщении, или более поздней, как описано в разделе Закрепите версию. До этого пользователи могут выбрать в сессии другую модель.
Под завершается принудительно во время drain: увеличьте terminationGracePeriodSeconds как минимум до значения, которое runner записывает в лог при запуске. См. Время завершения работы.

После инициализации логирования runner пишет свой лог жизненного цикла, включая строки [runner:fatal], в stdout, а отладочный вывод — в stderr, всё в виде строк простого текста, а не JSON. Сбои базового каталога, описанные в пунктах выше, выводятся в stderr до этого момента. Сохраняйте оба потока с помощью --log-file, что также позволяет self-hosted-runner doctor отслеживать их, или с помощью средств сбора логов вашей платформы.

Дочерний процесс каждой сессии пишет отдельный отладочный лог. При сбое runner показывает конец этого лога рядом с сессией в claude.ai/code. Если вы не запустили runner с --remove-session-state, он также сохраняет лог неудавшейся сессии на диске и выводит его путь в лог runner'а.

Когда runner завершается

Не перезапускайте runner по запросу, поскольку его рабочее задание одноразовое. Runner, который завершается сразу после запуска, требует иного подхода, чем runner, завершившийся по любой другой причине.

Нормальное завершение: runner завершил свои сессии и выполнил drain, достиг времени вывода из эксплуатации или получил команду остановиться. Перезапустите его, чтобы у окружения снова была ёмкость. Эти завершения описаны в разделе Жизненный цикл runner'а.
Неудачный запуск: runner не может запуститься с заданной ему конфигурацией или на заданном хосте, поэтому он завершается через несколько секунд после запуска и завершается так же при каждом перезапуске. Более быстрый перезапуск не поможет. Кому-то нужно прочитать его вывод и устранить причину.
Потеря связи: runner, который не может связаться с Anthropic дольше срока своей аренды, например пока его хост находится в спящем режиме, может быть удалён из окружения. Когда удалённый runner снова подключается, он завершается. В его логе может быть строка [runner:fatal], содержащая runner record gone server-side или, после более длительного перерыва, poll auth failed. Runner не регистрируется повторно самостоятельно, поэтому перезапустите его.

Настройте супервизор так, чтобы он перезапускал runner при каждом его завершении, увеличивал паузу между перезапусками, когда runner продолжает завершаться сразу после запуска, и оповещал кого-либо, когда это продолжается.

В продакшене пусть супервизор перезапускает runner на чистом диске, в новом контейнере или VM, как рекомендует раздел Усильте защиту развёртывания.

Как распознать неудачный запуск

Когда runner не может запуститься, он выводит строку с причиной, а затем завершается. В большинстве случаев строка содержит [runner:fatal]. В некоторых случаях строка вместо этого начинается с error:, в том числе когда runner не может разобрать свои флаги, не может прочитать секрет окружения или не может создать базовый каталог или записать в него. Следующая строка тогда указывает на --help.

Большинство строк лога начинаются с временной метки и [self-hosted-runner], которые в примере ниже опущены. Например, runner, запущенный с git-прокси Anthropic и ёмкостью больше единицы, выводит строку вроде этой:

[runner:fatal] --use-anthropic-git-proxy requires --capacity 1 (the proxy URL is per-session and linked worktrees share origin). Omit --use-anthropic-git-proxy or set --capacity 1.

Ищите эту строку в стандартном выводе и стандартном потоке ошибок runner'а, в логах контейнеров вашей платформы или в файле, заданном с помощью --log-file. Runner выводит строку error: до того, как откроет файл лога, поэтому ищите её в терминале или в логах контейнера, как отмечено в разделе Устранение неполадок.

При разборе неудачного запуска также помогут следующие моменты:

Строки нет вовсе: runner, который принудительно завершил хост, не выводит ни той, ни другой строки. Если вывод заканчивается без строки [runner:fatal] и без строки error:, проверьте, не остановил ли процесс хост или ваш оркестратор, например из-за превышения лимита памяти.
Код выхода: runner не выделяет отдельный код выхода для ошибок, повторяющихся при каждом запуске. Он завершается с одним и тем же кодом как при ошибке конфигурации, например неподдерживаемом сочетании флагов, так и при сбое, который может устраниться сам, например когда API остаётся недоступным на протяжении собственных повторных попыток runner'а. Решение об увеличении паузы принимайте исходя из того, как скоро runner завершился, а причину выясняйте по выводу runner'а.
Окружение выглядит работоспособным: некоторые шаги запуска выполняются после регистрации runner'а в окружении, например --configure-git и настройка учётных данных git-прокси Anthropic. Если один из этих шагов завершается сбоем, окружение может ещё несколько минут после завершения процесса продолжать отображать этот runner, и страница Cloud environments может показывать Healthy, хотя ни один runner не принимает работу. Если сессии остаются в очереди в окружении, которое выглядит работоспособным, проверьте, не перезапускает ли ваш супервизор runner.

Перезапуск с растущей паузой

Способ получить растущую паузу зависит от вашего супервизора.

Kubernetes: Deployment на этой странице не требует изменений. После завершения контейнера kubelet по умолчанию ждёт перед его перезапуском, и пауза растёт с каждым перезапуском до верхнего предела. Пауза сбрасывается, как только контейнер некоторое время проработает без завершения.

Kubelet применяет ту же паузу и после нормального завершения, если контейнер проработал недолго. Поэтому runner, который часто выполняет drain, тоже может показывать статус CrashLoopBackOff, так что прочитайте вывод, прежде чем заключать, что runner не может запуститься. Команда ниже читает вывод последнего запуска одного пода Deployment:
```
kubectl logs --previous -n claude-runners deploy/claude-runner
```
Если последний запуск был неудачным, строка [runner:fatal] или error: находится среди последних строк вывода. Чтобы прочитать последний запуск другого пода, укажите этот под вместо deploy/claude-runner.
Docker и Docker Compose: рецепт Compose на этой странице не требует изменений. С restart: always Docker ждёт всё дольше перед каждым перезапуском контейнера, который продолжает завершаться, до верхнего предела. Замените <container> на имя контейнера в команде ниже, которая показывает, сколько раз Docker перезапускал контейнер:
```
docker inspect --format '{{.RestartCount}}' <container>
```
Команда выводит число. Если число продолжает расти, Docker продолжает перезапускать runner.
Юнит systemd: по умолчанию systemd ждёт одинаковое время RestartSec перед каждым перезапуском и не увеличивает его, поэтому юнит с Restart=always перезапускает runner, который не может запуститься, каждый раз с одним и тем же интервалом. Когда запуски происходят достаточно часто, чтобы достичь ограничения частоты запусков юнита (по умолчанию пять запусков за 10 секунд), systemd прекращает перезапускать юнит. Юнит остаётся остановленным, пока кто-нибудь не запустит его снова, что systemd разрешает после истечения интервала ограничения частоты запусков или после systemctl reset-failed. Поскольку RestartSec применяется к каждому перезапуску, большее значение также задерживает перезапуск после нормального завершения. Выберите значение, которое уравновешивает эти два случая, и настройте оповещения по счётчику перезапусков юнита.
Цикл в оболочке или собственный супервизор: примените то же правило самостоятельно. Начните с паузы в пять секунд. После каждого запуска, который завершился в пределах минуты, удваивайте паузу перед следующим перезапуском, максимум до пяти минут. После запуска, который длился минуту или дольше, вернитесь к пяти секундам.

Выясните, почему runner продолжает завершаться

Если runner несколько раз подряд завершился сразу после запуска, остановитесь и проверьте следующее, прежде чем снова его перезапускать.

Последняя строка [runner:fatal] или error:: в ней сказано, почему runner остановился. Частые причины перечислены в разделе Устранение неполадок.
Сочетание флагов: git-прокси Anthropic требует --capacity 1. Рецепты на этой странице используют бо́льшую ёмкость, поэтому уменьшите её, когда добавляете прокси в один из них.
Что доступно окружению службы: если runner запускается вручную, но завершается сбоем под вашим супервизором, сравните пользователя, домашний каталог, PATH и лимит памяти. --configure-git и git-прокси Anthropic требуют наличия git в PATH и доступного для записи ~/.gitconfig.
Секрет окружения: если вы отозвали секрет или ошиблись при его вводе, runner выводит строку, содержащую RegisterRunner auth failed.
Вкладка Activity окружения: откройте окружение и выберите Activity. Если там продолжают появляться новые runner'ы и ни один из них не принимает работу, ваш супервизор перезапускает runner.

Для пошаговой диагностики на хосте runner'а запустите подкоманду doctor.

Что дальше

Customize sessions: скрипты-обертки, lifecycle hooks, on-demand runners, MCP servers и разрешения
Test end to end: проверьте новый образ runner из CI перед продвижением
Reference: каждый флаг CLI, переменная окружения и метрика

self-hosted-environments-deploy.md +141 −111

8 8

9> [!NOTE]9> [!NOTE]

10>10>

11> Самостоятельно размещаемые окружения находятся в публичной бета-версии на планах Team и Enterprise; раздел [Доступность и ограничения](/docs/ru/self-hosted-environments#availability-and-limitations) охватывает путь включения. Эта страница охватывает запуск флота в production; см. [быстрый старт](/docs/ru/self-hosted-environments-quickstart) для вашего первого runner и сеанса.11> Самостоятельно размещаемые окружения находятся в публичной бета-версии на планах Team и Enterprise; раздел [Доступность и ограничения](/docs/ru/self-hosted-environments#availability-and-limitations) охватывает путь включения. Эта страница охватывает запуск флота в production; см. [быстрый старт](/docs/ru/self-hosted-environments-quickstart.md) для вашего первого runner и сеанса.

12 12

13[Самостоятельно размещаемое окружение](/docs/ru/self-hosted-environments) запускает Claude Code [облачные сеансы](/docs/ru/claude-code-on-the-web) на runners, которые вы развертываете внутри вашей сети, и в production эти сеансы выполняют направленный моделью код от имени всех, кто может отправить сеанс в окружение. Эта страница предназначена для оператора, переводящего рабочее окружение в production. Она проходит через развертывание по порядку: что заблокировать перед подключением реальных систем, исходящий трафик, который требуется флоту, как сеансы аутентифицируются на вашем хосте git, сами рецепты развертывания и что проверить, когда сеансы работают неправильно.13[Самостоятельно размещаемое окружение](/docs/ru/self-hosted-environments) запускает Claude Code [облачные сеансы](/docs/ru/claude-code-on-the-web.md) на runners, которые вы развертываете внутри вашей сети, и в production эти сеансы выполняют направленный моделью код от имени всех, кто может отправить сеанс в окружение. Эта страница предназначена для оператора, переводящего рабочее окружение в production. Она проходит через развертывание по порядку: что заблокировать перед подключением реальных систем, исходящий трафик, который требуется флоту, как сеансы аутентифицируются на вашем хосте git, сами рецепты развертывания и что проверить, когда сеансы работают неправильно.

14 14

15## Усиление безопасности развёртывания15## Усиление безопасности развёртывания

16 16

18 18

19* **Эфемерные контейнеры для каждой сессии**: запускайте каждый процесс runner в свежем контейнере или VM, который уничтожается при выходе процесса, с `--capacity 1` и значением по умолчанию `--drain-grace-sec 0`, чтобы каждый контейнер обслуживал ровно одну сессию. При более высокой ёмкости или положительном периоде осушения один контейнер обслуживает несколько сессий от одного [заблокированного владельца](/docs/ru/self-hosted-environments#key-concepts); см. [Runner lifecycle](/docs/ru/self-hosted-environments#runner-lifecycle). Не переиспользуйте файловую систему между перезапусками runner, кроме намеренной настройки [pre-warmed checkout](#reuse-a-pre-warmed-checkout), и никогда между владельцами.19* **Эфемерные контейнеры для каждой сессии**: запускайте каждый процесс runner в свежем контейнере или VM, который уничтожается при выходе процесса, с `--capacity 1` и значением по умолчанию `--drain-grace-sec 0`, чтобы каждый контейнер обслуживал ровно одну сессию. При более высокой ёмкости или положительном периоде осушения один контейнер обслуживает несколько сессий от одного [заблокированного владельца](/docs/ru/self-hosted-environments#key-concepts); см. [Runner lifecycle](/docs/ru/self-hosted-environments#runner-lifecycle). Не переиспользуйте файловую систему между перезапусками runner, кроме намеренной настройки [pre-warmed checkout](#reuse-a-pre-warmed-checkout), и никогда между владельцами.

20 * Когда runner останавливает сессию, он не отправляет никакого сигнала процессу, который продолжает работать после завершения его shell-команды, например сервису, ставшему демоном. Уничтожение контейнера или VM завершает такой процесс.20 * Когда runner останавливает сессию, он не отправляет никакого сигнала процессу, который продолжает работать после завершения его shell-команды, например сервису, ставшему демоном. Уничтожение контейнера или VM завершает такой процесс.

21* **Нет широких учётных данных в образе**: не включайте долгоживущие SSH-ключи, учётные данные облачного провайдера или личные токены доступа, которые предоставляют больше, чем нужно сессии. Создавайте учётные данные, используемые во время сессии, такие как токены push или API, для каждой сессии из вашего [скрипта-обёртки](/docs/ru/self-hosted-environments-configuration#wrapper-scripts). Начальное клонирование происходит перед запуском обёртки, поэтому обрабатывайте его с помощью [хука жизненного цикла `checkout`](/docs/ru/self-hosted-environments-configuration#checkout) или с помощью [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), если все репозитории сессии находятся на github.com. Для обоих вариантов см. [Configure git](#configure-git).21* **Нет широких учётных данных в образе**: не включайте долгоживущие SSH-ключи, учётные данные облачного провайдера или личные токены доступа, которые предоставляют больше, чем нужно сессии. Создавайте учётные данные, используемые во время сессии, такие как токены push или API, для каждой сессии из вашего [скрипта-обёртки](/docs/ru/self-hosted-environments-configuration.md#wrapper-scripts). Начальное клонирование происходит перед запуском обёртки, поэтому обрабатывайте его с помощью [хука жизненного цикла `checkout`](/docs/ru/self-hosted-environments-configuration#checkout) или с помощью [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), если все репозитории сессии находятся на github.com. Для обоих вариантов см. [Configure git](#configure-git).

22* **Держите учётные данные GitHub хоста вдали от сессий**: Claude может использовать любые учётные данные GitHub, которые может прочитать сессия, с любым доступом, который эти учётные данные предоставляют. Не допускайте, чтобы собственные учётные данные GitHub хоста runner с широкими правами попадали туда, где их может прочитать сессия. Такими учётными данными может быть личный токен доступа, токен, который `gh auth login` сохраняет для вашей учётной записи, или `GH_TOKEN` в окружении runner.22* **Держите учётные данные GitHub хоста вдали от сессий**: Claude может использовать любые учётные данные GitHub, которые может прочитать сессия, с любым доступом, который эти учётные данные предоставляют. Не допускайте, чтобы собственные учётные данные GitHub хоста runner с широкими правами попадали туда, где их может прочитать сессия. Такими учётными данными может быть личный токен доступа, токен, который `gh auth login` сохраняет для вашей учётной записи, или `GH_TOKEN` в окружении runner.

23 * **С [Anthropic-managed git](#use-the-anthropic-git-proxy)**: при наличии таких учётных данных Claude обращается к GitHub напрямую, а не через Anthropic-managed git.23 * **С [Anthropic-managed git](#use-the-anthropic-git-proxy)**: при наличии таких учётных данных Claude обращается к GitHub напрямую, а не через Anthropic-managed git.

24 * **Без Anthropic-managed git**: учётные данные для клонирования могут оставаться в образе, если вы ограничите их так строго, как описано в [Ship git config in your image](#ship-git-config-in-your-image).24 * **Без Anthropic-managed git**: учётные данные для клонирования могут оставаться в образе, если вы ограничите их так строго, как описано в [Ship git config in your image](#ship-git-config-in-your-image).

25* **Держите секрет окружения вдали от хостов, запускающих сессии**: секрет окружения может регистрировать runners и получать любую сессию, поставленную в очередь в окружение. На фиксированном флоте он находится на каждом хосте runner, где код любой сессии может прочитать файл секрета. Предпочитайте [on-demand runners](/docs/ru/self-hosted-environments-configuration#on-demand-runners), где секрет остаётся на хосте оркестратора, который никогда не запускает пользовательский код, и каждый runner получает одноразовый наряд на работу, который регистрирует ровно один runner. На фиксированном флоте рассматривайте файл environment-secret как читаемый каждой сессией и ротируйте секрет после любого подозрения на компрометацию сессии.25* **Держите секрет окружения вдали от хостов, запускающих сессии**: секрет окружения может регистрировать runners и получать любую сессию, поставленную в очередь в окружение. На фиксированном флоте он находится на каждом хосте runner, где код любой сессии может прочитать файл секрета. Предпочитайте [on-demand runners](/docs/ru/self-hosted-environments-configuration.md#on-demand-runners), где секрет остаётся на хосте оркестратора, который никогда не запускает пользовательский код, и каждый runner получает одноразовый наряд на работу, который регистрирует ровно один runner. На фиксированном флоте рассматривайте файл environment-secret как читаемый каждой сессией и ротируйте секрет после любого подозрения на компрометацию сессии.

26* **Исходящий трафик по умолчанию запрещён**: ограничьте исходящий трафик контейнеров runner и сессии на границе вашей собственной сети в каждом окружении; [Default-deny egress](#default-deny-egress) описывает, что разрешить и почему.26* **Исходящий трафик по умолчанию запрещён**: ограничьте исходящий трафик контейнеров runner и сессии на границе вашей собственной сети в каждом окружении; [Default-deny egress](#default-deny-egress) описывает, что разрешить и почему.

27* **Наименьшие привилегии IAM хоста**: вычислительная идентификация, прикреплённая к хосту runner, такая как профиль экземпляра или учётная запись сервиса узла, должна предоставлять только то, что нужно самому runner. Сессии должны получать свои собственные учётные данные через ваш скрипт-обёртку, а не наследовать учётные данные хоста.27* **Наименьшие привилегии IAM хоста**: вычислительная идентификация, прикреплённая к хосту runner, такая как профиль экземпляра или учётная запись сервиса узла, должна предоставлять только то, что нужно самому runner. Сессии должны получать свои собственные учётные данные через ваш скрипт-обёртку, а не наследовать учётные данные хоста.

28* **Блокируйте сессиям доступ к эндпоинту облачных метаданных**: чтобы сессии не использовали идентификацию хоста, требуется блокировать их доступ к эндпоинту облачных метаданных, а политики исходящего трафика на уровне подсети не перехватывают трафик метаданных link-local, поэтому блокируйте его в самом контейнере:28* **Блокируйте сессиям доступ к эндпоинту облачных метаданных**: чтобы сессии не использовали идентификацию хоста, требуется блокировать их доступ к эндпоинту облачных метаданных, а политики исходящего трафика на уровне подсети не перехватывают трафик метаданных link-local, поэтому блокируйте его в самом контейнере:

31 * GKE Workload Identity со скрытием метаданных31 * GKE Workload Identity со скрытием метаданных

32 * Явный запрет для `169.254.169.254` в сетевом пространстве имён контейнера сессии32 * Явный запрет для `169.254.169.254` в сетевом пространстве имён контейнера сессии

33 33

34 Блокировка применяется также к вашему скрипту-обёртке и хукам жизненного цикла, так как они используют тот же контейнер. Аутентифицируйте любой обмен токенами с помощью [session JWT](/docs/ru/self-hosted-environments-identity) в вашем собственном сервисе токенов через разрешённый исходящий трафик или используйте веб-идентификацию на основе файлов, такую как IAM Roles for Service Accounts (IRSA) на Amazon EKS.34 Блокировка применяется также к вашему скрипту-обёртке и хукам жизненного цикла, так как они используют тот же контейнер. Аутентифицируйте любой обмен токенами с помощью [session JWT](/docs/ru/self-hosted-environments-identity.md) в вашем собственном сервисе токенов через разрешённый исходящий трафик или используйте веб-идентификацию на основе файлов, такую как IAM Roles for Service Accounts (IRSA) на Amazon EKS.

35* **Изоляция файловой системы для каждого runner**: каждый процесс runner получает свой собственный рабочий каталог, который никакой другой процесс на хосте не может читать или записывать. Сделайте `--hooks-dir`, скрипт-обёртку и `~/.claude/` хоста доступными сессии только для чтения, либо встроив их в образ, либо смонтировав только для чтения.35* **Изоляция файловой системы для каждого runner**: каждый процесс runner получает свой собственный рабочий каталог, который никакой другой процесс на хосте не может читать или записывать. Сделайте `--hooks-dir`, скрипт-обёртку и `~/.claude/` хоста доступными сессии только для чтения, либо встроив их в образ, либо смонтировав только для чтения.

36* **Dispatch не имеет контроля доступа на уровне окружения**: любой член вашей организации Anthropic может отправить сессию в любое из её окружений. Если Owner [направляет каналы Claude Tag в окружение](/docs/ru/cloud-environments#set-the-environment-a-claude-tag-channel-uses), любой, кого допускает [настройка доступа Claude Tag](https://claude.com/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude), может запускать сессии канала, которые работают там. По умолчанию это любой участник подключённого рабочего пространства Slack, с учётной записью Claude или без неё. Рассматривайте каждый хост runner как доступный для выполнения кода всеми, кто может отправлять в него сессии, и размещайте на хосте runner только данные и учётные данные, которые все эти люди имеют право читать. [`--lock-to-account`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) ограничивает, сессии какой учётной записи выполняет данный хост, но не сужает круг тех, кто может отправлять сессии в окружение. Чтобы сделать самостоятельно размещаемые окружения единственным вариантом выбора, [Owner](/docs/ru/cloud-environments#organization-shared-environments) может скрыть окружения, размещаемые Anthropic, для всей организации на странице [**Cloud environments**](https://claude.ai/admin-settings/cloud-environments).36* **Dispatch не имеет контроля доступа на уровне окружения**: любой член вашей организации Anthropic может отправить сессию в любое из её окружений. Если Owner [направляет каналы Claude Tag в окружение](/docs/ru/cloud-environments.md#set-the-environment-a-claude-tag-channel-uses), любой, кого допускает [настройка доступа Claude Tag](https://claude.com/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude), может запускать сессии канала, которые работают там. По умолчанию это любой участник подключённого рабочего пространства Slack, с учётной записью Claude или без неё. Рассматривайте каждый хост runner как доступный для выполнения кода всеми, кто может отправлять в него сессии, и размещайте на хосте runner только данные и учётные данные, которые все эти люди имеют право читать. [`--lock-to-account`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) ограничивает, сессии какой учётной записи выполняет данный хост, но не сужает круг тех, кто может отправлять сессии в окружение. Чтобы сделать самостоятельно размещаемые окружения единственным вариантом выбора, [Owner](/docs/ru/cloud-environments.md#organization-shared-environments) может скрыть окружения, размещаемые Anthropic, для всей организации на странице [**Cloud environments**](https://claude.ai/admin-settings/cloud-environments).

37* **Применяйте защиту repo-settings**: выберите режим защиты с помощью [`--confine-repo-settings`](/docs/ru/self-hosted-environments-reference#runner-cli-flags). Режим по умолчанию `warn` записывает нарушение в лог и всё равно запускает сессию, `enforce` отклоняет сессию, а `off` отключает сканирование. Runner сканирует закоммиченные настройки каждого репозитория на наличие:37* **Применяйте защиту repo-settings**: выберите режим защиты с помощью [`--confine-repo-settings`](/docs/ru/self-hosted-environments-reference#runner-cli-flags). Режим по умолчанию `warn` записывает нарушение в лог и всё равно запускает сессию, `enforce` отклоняет сессию, а `off` отключает сканирование. Runner сканирует закоммиченные настройки каждого репозитория на наличие:

38 38

39 * Гранта, который разрешается за пределами собственного рабочего пространства этой сессии: записи `additionalDirectories`, правила `Edit`, `Write` или `NotebookEdit` в `permissions.allow` или записи `sandbox.filesystem.allowWrite` или `allowRead`39 * Гранта, который разрешается за пределами собственного рабочего пространства этой сессии: записи `additionalDirectories`, правила `Edit`, `Write` или `NotebookEdit` в `permissions.allow` или записи `sandbox.filesystem.allowWrite` или `allowRead`

40 * Непустого блока `env`40 * Непустого блока `env`

41 * Переопределения позиции оператора, такого как `sandbox.enabled: false`41 * Переопределения позиции оператора, такого как `sandbox.enabled: false`

42 42

43 Защита работает независимо от [`--trust-workspace`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) и не охватывает хуки репозитория, `.mcp.json` или правила Bash; см. [Permissions and tool approval](/docs/ru/self-hosted-environments-configuration#permissions-and-tool-approval), чтобы узнать, где должны находиться эти гранты.43 Защита работает независимо от [`--trust-workspace`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) и не охватывает хуки репозитория, `.mcp.json` или правила Bash; см. [Permissions and tool approval](/docs/ru/self-hosted-environments-configuration.md#permissions-and-tool-approval), чтобы узнать, где должны находиться эти гранты.

44 44

45> [!NOTE]45> [!NOTE]

46>46>

47> Если в вашей организации включён [список разрешённых IP-адресов](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting), добавьте публичные адреса исходящего трафика ваших runners и контейнеров сессий в список разрешённых перед их запуском. Если вы используете [on-demand runners](/docs/ru/self-hosted-environments-configuration#on-demand-runners), добавьте также адрес хоста оркестратора. Не полагайтесь на список разрешённых как на сетевой контроль для трафика runner или сессий. Вместо этого применяйте default-deny egress на границе вашей собственной сети.47> Если в вашей организации включён [список разрешённых IP-адресов](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting), добавьте публичные адреса исходящего трафика ваших runners и контейнеров сессий в список разрешённых перед их запуском. Если вы используете [on-demand runners](/docs/ru/self-hosted-environments-configuration.md#on-demand-runners), добавьте также адрес хоста оркестратора. Не полагайтесь на список разрешённых как на сетевой контроль для трафика runner или сессий. Вместо этого применяйте default-deny egress на границе вашей собственной сети.

48 48

49## Требования к сети49## Требования к сети

50 50

54 54

56| :- | :- | :- |56| :- | :- | :- |

57| `api.anthropic.com` | 443, HTTPS; WSS для [git под управлением Anthropic](#use-the-anthropic-git-proxy) | Плоскость управления runner и потоковая передача сессии, вывод модели, флаги функций, аналитика продукта, получение ключей [JWKS](/docs/ru/self-hosted-environments-identity), подпись коммитов и git под управлением Anthropic при установке `--use-anthropic-git-proxy` |57| `api.anthropic.com` | 443, HTTPS; WSS для [git под управлением Anthropic](#use-the-anthropic-git-proxy) | Плоскость управления runner и потоковая передача сессии, вывод модели, флаги функций, аналитика продукта, получение ключей [JWKS](/docs/ru/self-hosted-environments-identity.md), подпись коммитов и git под управлением Anthropic при установке `--use-anthropic-git-proxy` |

58| Ваш git-хост, такой как `github.com` или ваш хост GitHub Enterprise | 443 или 22 | Клонирование и push репозиториев на каждом git-хосте, который используют сессии runner. Для runner, использующего [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), см. [когда путь к `github.com` всё ещё нужен](#github-com-egress-with-the-anthropic-git-proxy). |58| Ваш git-хост, такой как `github.com` или ваш хост GitHub Enterprise | 443 или 22 | Клонирование и push репозиториев на каждом git-хосте, который используют сессии runner. Для runner, использующего [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), см. [когда путь к `github.com` всё ещё нужен](#github-com-egress-with-the-anthropic-git-proxy). |

59 59

60Runner, использующий [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), направляет свой git-трафик к `github.com` через `api.anthropic.com`, поэтому ему не нужен путь к git-хосту `github.com`. Этот путь всё ещё нужен, если вы устанавливаете `--push-outcome-on-release` или выполняете push из хука `post-session`.60Runner, использующий [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), направляет свой git-трафик к `github.com` через `api.anthropic.com`, поэтому ему не нужен путь к git-хосту `github.com`. Этот путь всё ещё нужен, если вы устанавливаете `--push-outcome-on-release` или выполняете push из хука `post-session`.

66| `downloads.claude.ai` | 443 | Во время установки, когда вы устанавливаете или обновляете Claude Code на хосте с помощью встроенного установщика; сам скрипт `install.sh` обслуживается с `claude.ai`. Во время выполнения сеанса только когда сеансы устанавливают плагины из официального рынка Anthropic. |66| `downloads.claude.ai` | 443 | Во время установки, когда вы устанавливаете или обновляете Claude Code на хосте с помощью встроенного установщика; сам скрипт `install.sh` обслуживается с `claude.ai`. Во время выполнения сеанса только когда сеансы устанавливают плагины из официального рынка Anthropic. |

67| `storage.googleapis.com` | 443 | Во время выполнения сеанса для количества установок плагинов и метаданных, показанных в `/plugin`. |67| `storage.googleapis.com` | 443 | Во время выполнения сеанса для количества установок плагинов и метаданных, показанных в `/plugin`. |

68| `code.claude.com` и `claude.com` | 443 | Поиск документации встроенным агентом claude-code-guide и предварительно одобренные запросы WebFetch во время сеансов. Блокировка этих хостов влияет только на поиск документации. |68| `code.claude.com` и `claude.com` | 443 | Поиск документации встроенным агентом claude-code-guide и предварительно одобренные запросы WebFetch во время сеансов. Блокировка этих хостов влияет только на поиск документации. |

69| `*.frame.claudeusercontent.com` | 443 | Только когда [инструмент Artifact](/docs/ru/artifacts#availability) доступен для сеансов в вашей организации; значения по умолчанию варьируются по плану, согласно таблице доступности там. Установите `CLAUDE_CODE_DISABLE_ARTIFACT=1` на runner, чтобы держать инструмент отключенным независимо от параметра организации. |69| `*.frame.claudeusercontent.com` | 443 | Только когда [инструмент Artifact](/docs/ru/artifacts.md#availability) доступен для сеансов в вашей организации; значения по умолчанию варьируются по плану, согласно таблице доступности там. Установите `CLAUDE_CODE_DISABLE_ARTIFACT=1` на runner, чтобы держать инструмент отключенным независимо от параметра организации. |

70| `registry.npmjs.org` | 443 | Когда сеанс устанавливает плагин, как для получения пакетов плагинов npm-source, так и для установки зависимостей Node.js плагина, или когда запускается MCP-сервер, запущенный `npx` |70| `registry.npmjs.org` | 443 | Когда сеанс устанавливает плагин, как для получения пакетов плагинов npm-source, так и для установки зависимостей Node.js плагина, или когда запускается MCP-сервер, запущенный `npx` |

71| `http-intake.logs.us5.datadoghq.com` | 443 | Метрики операций Anthropic. Только когда установлено `CLAUDE_CODE_BYOC_ENABLE_DATADOG=1`; отключено по умолчанию в самостоятельно размещаемых окружениях. |71| `http-intake.logs.us5.datadoghq.com` | 443 | Метрики операций Anthropic. Только когда установлено `CLAUDE_CODE_BYOC_ENABLE_DATADOG=1`; отключено по умолчанию в самостоятельно размещаемых окружениях. |

72| `browser-intake-us5-datadoghq.com` | 443 | Загрузки отчетов об ошибках Anthropic, отправляемые только когда [отчетность об ошибках](/docs/ru/data-usage#telemetry-services) включена для учетной записи сеанса. Подавляется `DISABLE_ERROR_REPORTING=1` или `DISABLE_TELEMETRY=1`. |72| `browser-intake-us5-datadoghq.com` | 443 | Загрузки отчетов об ошибках Anthropic, отправляемые только когда [отчетность об ошибках](/docs/ru/data-usage.md#telemetry-services) включена для учетной записи сеанса. Подавляется `DISABLE_ERROR_REPORTING=1` или `DISABLE_TELEMETRY=1`. |

73| Эндпоинты вашего облачного провайдера для запросов к модели, поиска моделей и обновления учётных данных, такие как `bedrock-runtime.us-east-1.amazonaws.com` или `aiplatform.googleapis.com` | 443 | Только когда runner [отправляет запросы к модели в Amazon Bedrock или Google Cloud's Agent Platform](/docs/ru/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform) |73| Эндпоинты вашего облачного провайдера для запросов к модели, поиска моделей и обновления учётных данных, такие как `bedrock-runtime.us-east-1.amazonaws.com` или `aiplatform.googleapis.com` | 443 | Только когда runner [отправляет запросы к модели в Amazon Bedrock или Google Cloud's Agent Platform](/docs/ru/self-hosted-environments-configuration.md#send-model-requests-to-bedrock-or-agent-platform) |

74 74

75Эти хосты не нужно добавлять в список разрешённых хостов для трафика runner или сессий:75Эти хосты не нужно добавлять в список разрешённых хостов для трафика runner или сессий:

76 76

77* **`statsig.anthropic.com`, `*.sentry.io`, `claude.ai` и `platform.claude.com`**: эти хосты встречаются в некоторых старых контрольных списках корпоративной сети, но runner к ним не обращается. Получение флагов функций идёт на `api.anthropic.com`, а runner аутентифицируется с помощью секрета окружения, а не интерактивного OAuth.77* **`statsig.anthropic.com`, `*.sentry.io`, `claude.ai` и `platform.claude.com`**: эти хосты встречаются в некоторых старых контрольных списках корпоративной сети, но runner к ним не обращается. Получение флагов функций идёт на `api.anthropic.com`, а runner аутентифицируется с помощью секрета окружения, а не интерактивного OAuth.

78* **`mcp-proxy.anthropic.com`**: самостоятельно размещаемые сессии его не используют. Когда доставка коннекторов включена для вашей организации, коннекторы claude.ai вашей организации попадают в сессии через `api.anthropic.com`. См. [MCP servers](/docs/ru/self-hosted-environments-configuration#mcp-servers).78* **`mcp-proxy.anthropic.com`**: самостоятельно размещаемые сессии его не используют. Когда доставка коннекторов включена для вашей организации, коннекторы claude.ai вашей организации попадают в сессии через `api.anthropic.com`. См. [MCP servers](/docs/ru/self-hosted-environments-configuration.md#mcp-servers).

79 79

80Следующие процессы на стороне хоста обращаются к `claude.ai`, поэтому запускайте их с хоста, чей исходящий трафик это позволяет, а не расширяйте исходящий трафик контейнера сессии:80Следующие процессы на стороне хоста обращаются к `claude.ai`, поэтому запускайте их с хоста, чей исходящий трафик это позволяет, а не расширяйте исходящий трафик контейнера сессии:

81 81

82* **Однострочный установщик**: получает `install.sh` с `claude.ai` во время установки.82* **Однострочный установщик**: получает `install.sh` с `claude.ai` во время установки.

83* **Интерактивный `claude auth login`**: выполняет вход через `claude.ai`, `claude.com` и `platform.claude.com`. Его используют [guided setup](/docs/ru/self-hosted-environments-quickstart#run-the-guided-setup), режим `doctor` с входом и [CI dispatch](/docs/ru/self-hosted-environments-testing#authenticate-from-ci). Браузер, в котором вы входите, также загружает браузерные проверки страницы входа claude.ai с `hcaptcha.com`, `*.hcaptcha.com` и `challenges.cloudflare.com`. Если ваша организация использует единый вход (SSO), этот браузер также может быть перенаправлен через `sso.claude.com`.83* **Интерактивный `claude auth login`**: выполняет вход через `claude.ai`, `claude.com` и `platform.claude.com`. Его используют [guided setup](/docs/ru/self-hosted-environments-quickstart.md#run-the-guided-setup), режим `doctor` с входом и [CI dispatch](/docs/ru/self-hosted-environments-testing.md#authenticate-from-ci). Браузер, в котором вы входите, также загружает браузерные проверки страницы входа claude.ai с `hcaptcha.com`, `*.hcaptcha.com` и `challenges.cloudflare.com`. Если ваша организация использует единый вход (SSO), этот браузер также может быть перенаправлен через `sso.claude.com`.

84 84

85### Default-deny egress85### Default-deny egress

86 86

87Развертывайте контейнеры runner и сеанса в сегменте сети или пространстве имен, чей исходящий трафик ограничен хостами в [таблице требований к сети](#network-requirements), вашим git-хостом и конкретными внутренними сервисами, которые сеансам нужно достичь. Продукт не может проверить или применить это, поэтому применяйте это на границе вашей собственной сети в каждом окружении. Код сеанса направлен моделью и может попытаться подключиться к произвольным хостам; default-deny egress на сетевом уровне ограничивает, где эти попытки могут приземлиться. Это применяется независимо от режима разрешений: набор инструментов, одобренный по умолчанию, уже включает `Bash`, поэтому исходящий трафик shell работает без подсказки даже без [auto mode](/docs/ru/self-hosted-environments-configuration#permissions-and-tool-approval).87Развертывайте контейнеры runner и сеанса в сегменте сети или пространстве имен, чей исходящий трафик ограничен хостами в [таблице требований к сети](#network-requirements), вашим git-хостом и конкретными внутренними сервисами, которые сеансам нужно достичь. Продукт не может проверить или применить это, поэтому применяйте это на границе вашей собственной сети в каждом окружении. Код сеанса направлен моделью и может попытаться подключиться к произвольным хостам; default-deny egress на сетевом уровне ограничивает, где эти попытки могут приземлиться. Это применяется независимо от режима разрешений: набор инструментов, одобренный по умолчанию, уже включает `Bash`, поэтому исходящий трафик shell работает без подсказки даже без [auto mode](/docs/ru/self-hosted-environments-configuration.md#permissions-and-tool-approval).

88 88

89Для деталей о том, какую телеметрию излучает каждый сеанс и как ее отключить, см. [Telemetry](/docs/ru/self-hosted-environments-reference#telemetry).89Для деталей о том, какую телеметрию излучает каждый сеанс и как ее отключить, см. [Telemetry](/docs/ru/self-hosted-environments-reference.md#telemetry).

90 90

91### Аутентификация на исходящий прокси91### Аутентификация на исходящий прокси

92 92

101 101

102#### Конфигурации, с которыми runner отказывается запускаться102#### Конфигурации, с которыми runner отказывается запускаться

103 103

104Каждый флаг также имеет форму переменной окружения, указанную рядом с ним в [справочнике флагов CLI runner](/docs/ru/self-hosted-environments-reference#runner-cli-flags). Перед тем как runner свяжется с вашим прокси или плоскостью управления, он проверяет флаги и их переменные и отказывается запускаться в трех случаях:104Каждый флаг также имеет форму переменной окружения, указанную рядом с ним в [справочнике флагов CLI runner](/docs/ru/self-hosted-environments-reference.md#runner-cli-flags). Перед тем как runner свяжется с вашим прокси или плоскостью управления, он проверяет флаги и их переменные и отказывается запускаться в трех случаях:

105 105

106* **Оба флага установлены**: один флаг плюс переменная окружения другого флага считается установкой обоих.106* **Оба флага установлены**: один флаг плюс переменная окружения другого флага считается установкой обоих.

107* **Нет URL прокси**: ни `HTTPS_PROXY` ни `HTTP_PROXY` не содержат URL `http://` или `https://`. Runner читает обе переменные в верхнем или нижнем регистре и не консультирует `ALL_PROXY`.107* **Нет URL прокси**: ни `HTTPS_PROXY` ни `HTTP_PROXY` не содержат URL `http://` или `https://`. Runner читает обе переменные в верхнем или нижнем регистре и не консультирует `ALL_PROXY`.

139 139

140Для подписи коммитов требуется git 2.34 или новее; раннер проверяет это при запуске и завершается с ошибкой, если ваш git старше. Этот флаг не настраивает учётные данные для push — их по-прежнему нужно предоставить в образе.140Для подписи коммитов требуется git 2.34 или новее; раннер проверяет это при запуске и завершается с ошибкой, если ваш git старше. Этот флаг не настраивает учётные данные для push — их по-прежнему нужно предоставить в образе.

141 141

142На раннере версии v2.1.280 или новее коммиты, которые вы делаете из хука жизненного цикла `checkout` или `post-session`, также подписываются от имени сессии, но без трейлера `Co-authored-by:`. В разделе [Конфигурация git внутри хуков жизненного цикла](/docs/ru/self-hosted-environments-configuration#git-configuration-inside-lifecycle-hooks) описаны настройки git, которые раннер фиксирует внутри этих хуков.142На раннере версии v2.1.280 или новее коммиты, которые вы делаете из хука жизненного цикла `checkout` или `post-session`, также подписываются от имени сессии, но без трейлера `Co-authored-by:`. В разделе [Конфигурация git внутри хуков жизненного цикла](/docs/ru/self-hosted-environments-configuration.md#git-configuration-inside-lifecycle-hooks) описаны настройки git, которые раннер фиксирует внутри этих хуков.

143 143

144С `--configure-git` или без него Claude Code указывает Claude завершать сообщения коммитов трейлером `Claude-Session: <url>`, а описания pull request — URL сессии. Чтобы отключить и то и другое, задайте для [`attribution.sessionUrl`](/docs/ru/settings-reference#attribution-sessionurl) значение `false` в файле [`~/.claude/settings.json`](/docs/ru/self-hosted-environments-configuration#how-each-session’s-config-is-assembled) на хосте раннера, а затем перезапустите раннер.144С `--configure-git` или без него Claude Code указывает Claude завершать сообщения коммитов трейлером `Claude-Session: <url>`, а описания pull request — URL сессии. Чтобы отключить и то и другое, задайте для [`attribution.sessionUrl`](/docs/ru/settings-reference#attribution-sessionurl) значение `false` в файле [`~/.claude/settings.json`](/docs/ru/self-hosted-environments-configuration#how-each-session’s-config-is-assembled) на хосте раннера, а затем перезапустите раннер.

145 145

154 154

155Без идентификации `git commit` завершается ошибкой `Please tell me who you are`, и сессии не могут продвигаться. Вместо этого можно использовать идентификацию собственного бота; раннер не переопределяет эти значения.155Без идентификации `git commit` завершается ошибкой `Please tell me who you are`, и сессии не могут продвигаться. Вместо этого можно использовать идентификацию собственного бота; раннер не переопределяет эти значения.

156 156

157Не встраивайте долгоживущие или широко ограниченные учётные данные для push в общий образ раннера: учётные данные в образе доступны каждой сессии, которую запускает этот образ, кто бы её ни начал. Вместо этого выпускайте краткосрочный токен с минимальной областью действия для каждой сессии в своём [скрипте-обёртке](/docs/ru/self-hosted-environments-configuration#wrapper-scripts), используя идентификацию создателя сессии, декодированную из JWT сессии. Сочетайте это с эфемерным контейнером на каждую сессию, для чего требуется `--capacity 1`, чтобы никакие учётные данные не переживали сессию, которая их выпустила; см. [раздел об усилении защиты](#harden-your-deployment).157Не встраивайте долгоживущие или широко ограниченные учётные данные для push в общий образ раннера: учётные данные в образе доступны каждой сессии, которую запускает этот образ, кто бы её ни начал. Вместо этого выпускайте краткосрочный токен с минимальной областью действия для каждой сессии в своём [скрипте-обёртке](/docs/ru/self-hosted-environments-configuration.md#wrapper-scripts), используя идентификацию создателя сессии, декодированную из JWT сессии. Сочетайте это с эфемерным контейнером на каждую сессию, для чего требуется `--capacity 1`, чтобы никакие учётные данные не переживали сессию, которая их выпустила; см. [раздел об усилении защиты](#harden-your-deployment).

158 158

159Если вам необходимо настроить учётные данные для push на уровне образа, например для ключа развёртывания только для чтения, ограничьте их настолько жёстко, насколько позволяет ваш git-хостинг:159Если вам необходимо настроить учётные данные для push на уровне образа, например для ключа развёртывания только для чтения, ограничьте их настолько жёстко, насколько позволяет ваш git-хостинг:

160 160

188Взамен git-прокси ограничивает то, что поддерживает раннер, и меняет то, что ему нужно:188Взамен git-прокси ограничивает то, что поддерживает раннер, и меняет то, что ему нужно:

189 189

190* **Только github.com**: Anthropic обслуживает сессию, только если все её репозитории находятся на github.com, а git-прокси пока не поддерживает GitHub Enterprise Server. На раннере с git-прокси сессия с репозиторием на другом git-хостинге [не запускается](#when-anthropic-doesnt-serve-a-session).190* **Только github.com**: Anthropic обслуживает сессию, только если все её репозитории находятся на github.com, а git-прокси пока не поддерживает GitHub Enterprise Server. На раннере с git-прокси сессия с репозиторием на другом git-хостинге [не запускается](#when-anthropic-doesnt-serve-a-session).

191* **Учётные данные только для репозиториев сессии**: Anthropic предоставляет учётные данные git для репозиториев, входящих в сессию, но не для других репозиториев на том же git-хостинге. Приватный субмодуль, зависимость, которую ваш менеджер пакетов получает через git, или маркетплейс плагинов в другом репозитории не получают учётных данных от Anthropic. Попросите тех, кто создаёт сессии, [добавлять каждый репозиторий](/docs/ru/web-quickstart#start-a-task), который нужен сессии, при её создании.191* **Учётные данные только для репозиториев сессии**: Anthropic предоставляет учётные данные git для репозиториев, входящих в сессию, но не для других репозиториев на том же git-хостинге. Приватный субмодуль, зависимость, которую ваш менеджер пакетов получает через git, или маркетплейс плагинов в другом репозитории не получают учётных данных от Anthropic. Попросите тех, кто создаёт сессии, [добавлять каждый репозиторий](/docs/ru/web-quickstart.md#start-a-task), который нужен сессии, при её создании.

192 192

193 Каждый запуск [облачной запланированной задачи](/docs/ru/routines) — это сессия с репозиториями задачи, поэтому попросите владельца каждой задачи [добавить каждый репозиторий, который нужен её запускам](/docs/ru/routines#edit-and-control-routines).193 Каждый запуск [облачной запланированной задачи](/docs/ru/routines.md) — это сессия с репозиториями задачи, поэтому попросите владельца каждой задачи [добавить каждый репозиторий, который нужен её запускам](/docs/ru/routines.md#edit-and-control-routines).

194* **Только push веток**: push, который удаляет ветку, завершается ошибкой, как и push в ref любого другого типа, например в тег. О том, какие ветки может обновлять push, см. [GitHub-прокси](/docs/ru/cloud-environments#github-proxy).194* **Только push веток**: push, который удаляет ветку, завершается ошибкой, как и push в ref любого другого типа, например в тег. О том, какие ветки может обновлять push, см. [GitHub-прокси](/docs/ru/cloud-environments.md#github-proxy).

195* **Подключённые аккаунты GitHub**: попросите каждого, кто создаёт пользовательские сессии с репозиторием, [подключить GitHub](/docs/ru/web-quickstart#connect-github). Без собственного подключения такие сессии [не запускаются](#creator-has-no-github-connection).195* **Подключённые аккаунты GitHub**: попросите каждого, кто создаёт пользовательские сессии с репозиторием, [подключить GitHub](/docs/ru/web-quickstart.md#connect-github). Без собственного подключения такие сессии [не запускаются](#creator-has-no-github-connection).

196* **`--capacity 1`**: git-прокси требует одну сессию на процесс раннера, поэтому для параллелизма запускайте больше реплик. Требования перечислены в разделе [Включение git-прокси Anthropic](#turn-the-anthropic-git-proxy-on).196* **`--capacity 1`**: git-прокси требует одну сессию на процесс раннера, поэтому для параллелизма запускайте больше реплик. Требования перечислены в разделе [Включение git-прокси Anthropic](#turn-the-anthropic-git-proxy-on).

197* **Заменённая глобальная конфигурация git**: раннер [удаляет и заменяет глобальную конфигурацию git](#git-proxy-replaces-global-git-config) пользователя, от имени которого он запущен. Запускайте его от имени отдельного пользователя или в контейнере.197* **Заменённая глобальная конфигурация git**: раннер [удаляет и заменяет глобальную конфигурацию git](#git-proxy-replaces-global-git-config) пользователя, от имени которого он запущен. Запускайте его от имени отдельного пользователя или в контейнере.

198* **Учётные данные хоста для push с хоста**: push с помощью [`--push-outcome-on-release`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) раннера и любой push, который делает ваш [хук `post-session`](/docs/ru/self-hosted-environments-configuration#post-session), по-прежнему используют собственные учётные данные git хоста раннера и его [сетевой путь к `github.com`](#github-com-egress-with-the-anthropic-git-proxy). Не храните эти учётные данные в [глобальной конфигурации git](#git-proxy-replaces-global-git-config); способы их предоставления описаны в разделе [Поставляйте конфигурацию git в своём образе](#ship-git-config-in-your-image).198* **Учётные данные хоста для push с хоста**: push с помощью [`--push-outcome-on-release`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) раннера и любой push, который делает ваш [хук `post-session`](/docs/ru/self-hosted-environments-configuration#post-session), по-прежнему используют собственные учётные данные git хоста раннера и его [сетевой путь к `github.com`](#github-com-egress-with-the-anthropic-git-proxy). Не храните эти учётные данные в [глобальной конфигурации git](#git-proxy-replaces-global-git-config); способы их предоставления описаны в разделе [Поставляйте конфигурацию git в своём образе](#ship-git-config-in-your-image).

216>216>

217> Рецепты для [Kubernetes](#kubernetes) и [Docker Compose](#docker-compose) на этой странице используют `--capacity 4`. Если вы добавите `--use-anthropic-git-proxy` или `CLAUDE_RUNNER_USE_GIT_PROXY=1` в один из них, не изменив capacity на `1`, раннер будет завершаться при запуске каждый раз, когда оркестратор его перезапускает. Задайте `--capacity 1` и запускайте больше реплик для параллелизма. В разделе [Когда раннер завершается](#when-the-runner-exits) показана строка, которую выводит раннер.217> Рецепты для [Kubernetes](#kubernetes) и [Docker Compose](#docker-compose) на этой странице используют `--capacity 4`. Если вы добавите `--use-anthropic-git-proxy` или `CLAUDE_RUNNER_USE_GIT_PROXY=1` в один из них, не изменив capacity на `1`, раннер будет завершаться при запуске каждый раз, когда оркестратор его перезапускает. Задайте `--capacity 1` и запускайте больше реплик для параллелизма. В разделе [Когда раннер завершается](#when-the-runner-exits) показана строка, которую выводит раннер.

218 218

219Чтобы включить git-прокси, добавьте `--use-anthropic-git-proxy` в команду раннера или задайте `CLAUDE_RUNNER_USE_GIT_PROXY=1` в окружении раннера. Эта команда, выполненная в оболочке на хосте раннера, запускает раннер из [быстрого старта](/docs/ru/self-hosted-environments-quickstart#set-up-manually) с включённым git-прокси:219Чтобы включить git-прокси, добавьте `--use-anthropic-git-proxy` в команду раннера или задайте `CLAUDE_RUNNER_USE_GIT_PROXY=1` в окружении раннера. Эта команда, выполненная в оболочке на хосте раннера, запускает раннер из [быстрого старта](/docs/ru/self-hosted-environments-quickstart.md#set-up-manually) с включённым git-прокси:

220 220

221```bash theme={null}221```bash theme={null}

222claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>' --use-anthropic-git-proxy222claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>' --use-anthropic-git-proxy

301Для git-соединений, которые передают токен сессии в git под управлением Anthropic, раннер применяет эти две переменные следующим образом. [Хук `command`](/docs/ru/self-hosted-environments-configuration#command) запускается с окружением сессии, поэтому получает то же, что и git внутри сессии:301Для git-соединений, которые передают токен сессии в git под управлением Anthropic, раннер применяет эти две переменные следующим образом. [Хук `command`](/docs/ru/self-hosted-environments-configuration#command) запускается с окружением сессии, поэтому получает то же, что и git внутри сессии:

302 302

303* **`GIT_SSL_CAINFO`**: по чему git проверяет git под управлением Anthropic, зависит от того, где запущен git:303* **`GIT_SSL_CAINFO`**: по чему git проверяет git под управлением Anthropic, зависит от того, где запущен git:

304 * **Собственные clone и fetch раннера**: выполняются без переменной и проверяют git под управлением Anthropic по файлу сертификатов для отдельной сессии, который записывает раннер. Этот файл содержит системный пакет CA хоста раннера плюс сертификаты из вашего файла.304 * **Собственные clone и fetch раннера**: выполняются без переменной и проверяют git под управлением Anthropic по файлу сертификатов для отдельной сессии, который записывает раннер. Раннер собирает этот файл из системного пакета CA хоста раннера и сертификатов из вашего файла.

305 * **Git внутри сессии**: получает конфигурацию `http.sslCAInfo` с указанием вашего файла вместо переменной, а также записи `http.<url>.sslCAInfo`, которые проверяют git под управлением Anthropic по файлу для отдельной сессии.305 * **Git внутри сессии**: получает конфигурацию `http.sslCAInfo` с указанием вашего файла вместо переменной, а также записи `http.<url>.sslCAInfo`, которые проверяют git под управлением Anthropic по файлу для отдельной сессии.

306 * **Хуки `checkout` и `post-session`**: наследуют переменную без изменений.306 * **Хуки `checkout` и `post-session`**: наследуют переменную без изменений.

307* **`GIT_SSL_NO_VERIFY`**: какие проверки сертификатов остаются отключёнными, зависит от того, где запущен git:307* **`GIT_SSL_NO_VERIFY`**: какие проверки сертификатов остаются отключёнными, зависит от того, где запущен git:

315 315

316### Перезапись URL git для частных сетей316### Перезапись URL git для частных сетей

317 317

318URL репозиториев поступают из плоскости управления в формате HTTPS с именем хоста вашего git-хостинга; для GitHub Enterprise это имя хоста, которое вы настроили для [интеграции GitHub Enterprise](/docs/ru/github-enterprise-server) на claude.ai. Два повторяемых флага перезаписывают эти URL перед clone:318URL репозиториев поступают из плоскости управления в формате HTTPS с именем хоста вашего git-хостинга; для GitHub Enterprise это имя хоста, которое вы настроили для [интеграции GitHub Enterprise](/docs/ru/github-enterprise-server.md) на claude.ai. Два повторяемых флага перезаписывают эти URL перед clone:

319 319

320* `--git-host-rewrite <from>=<to>`: для split-horizon DNS, когда Anthropic обращается к вашему git-хостингу по внешнему имени хоста, а раннеры должны использовать внутреннее320* `--git-host-rewrite <from>=<to>`: для split-horizon DNS, когда Anthropic обращается к вашему git-хостингу по внешнему имени хоста, а раннеры должны использовать внутреннее

321* `--git-ssh-rewrite <host>`: для git-хостингов, принимающих только SSH, или для хоста раннера, у которого есть только ключ SSH. Например, чтобы клонировать репозитории github.com через SSH, добавьте `--git-ssh-rewrite github.com` в команду раннера. Тогда раннер перезаписывает `https://github.com/owner/repo` в `git@github.com:owner/repo`. SSH должен [подключаться без запроса ввода](#git-must-work-without-a-prompt).321* `--git-ssh-rewrite <host>`: для git-хостингов, принимающих только SSH, или для хоста раннера, у которого есть только ключ SSH. Например, чтобы клонировать репозитории github.com через SSH, добавьте `--git-ssh-rewrite github.com` в команду раннера. Тогда раннер перезаписывает `https://github.com/owner/repo` в `git@github.com:owner/repo`. SSH должен [подключаться без запроса ввода](#git-must-work-without-a-prompt).

324 324

325## Постройте образ runner325## Постройте образ runner

326 326

327Anthropic не публикует предварительно построенный образ runner. Постройте свой собственный вокруг бинарного файла `claude`, наслаивая любой набор инструментов, который нужен вашим репозиториям: языковые среды выполнения, компиляторы, менеджеры пакетов и [MCP](/docs/ru/mcp) sidecars.327Anthropic не публикует предварительно построенный образ runner. Постройте свой собственный вокруг бинарного файла `claude`, наслаивая любой набор инструментов, который нужен вашим репозиториям: языковые среды выполнения, компиляторы, менеджеры пакетов и [MCP](/docs/ru/mcp.md) sidecars.

328 328

329Рецепты ниже используют `--capacity 4`, поэтому один контейнер обслуживает до четырех одновременных сеансов от одного заблокированного владельца. Это не обеспечивает изоляцию контейнера для каждого сеанса в [разделе усиления безопасности](#harden-your-deployment): перед подключением окружения к production-системам либо запустите рецепты на `--capacity 1` с одним контейнером на сеанс, либо используйте [on-demand runners](/docs/ru/self-hosted-environments-configuration#on-demand-runners), которые также держат секрет окружения вне хостов, запускающих сеансы. Если вы добавите [Anthropic git proxy](#use-the-anthropic-git-proxy) к одному из этих рецептов, также измените `--capacity` на `1`.329Рецепты ниже используют `--capacity 4`, поэтому один контейнер обслуживает до четырех одновременных сеансов от одного заблокированного владельца. Это не обеспечивает изоляцию контейнера для каждого сеанса в [разделе усиления безопасности](#harden-your-deployment): перед подключением окружения к production-системам либо запустите рецепты на `--capacity 1` с одним контейнером на сеанс, либо используйте [on-demand runners](/docs/ru/self-hosted-environments-configuration.md#on-demand-runners), которые также держат секрет окружения вне хостов, запускающих сеансы. Если вы добавите [Anthropic git proxy](#use-the-anthropic-git-proxy) к одному из этих рецептов, также измените `--capacity` на `1`.

330 330

331Этот Dockerfile является минимальной отправной точкой:331Этот Dockerfile является минимальной отправной точкой:

332 332

343ENTRYPOINT ["claude"]343ENTRYPOINT ["claude"]

344```344```

345 345

346Замените `linux-x64` на `linux-arm64`, если ваши узлы ARM, или на `linux-x64-musl` или `linux-arm64-musl` на образе на основе musl, таком как Alpine; см. [Alpine Linux setup](/docs/ru/setup#alpine-linux-and-musl-based-distributions) для дополнительных пакетов, которые нужны образам musl. URL является стандартным местоположением выпуска Claude Code, поэтому вы можете проверить загруженный бинарный файл против подписанного манифеста выпуска, как описано в [Binary integrity and code signing](/docs/ru/setup#binary-integrity-and-code-signing). Runner требует версию Claude Code 2.1.224 или позже. Постройте образ, затем отправьте его в ваш реестр и ссылайтесь на него в рецептах ниже:346Замените `linux-x64` на `linux-arm64`, если ваши узлы ARM, или на `linux-x64-musl` или `linux-arm64-musl` на образе на основе musl, таком как Alpine; см. [Alpine Linux setup](/docs/ru/setup.md#alpine-linux-and-musl-based-distributions) для дополнительных пакетов, которые нужны образам musl. URL является стандартным местоположением выпуска Claude Code, поэтому вы можете проверить загруженный бинарный файл против подписанного манифеста выпуска, как описано в [Binary integrity and code signing](/docs/ru/setup.md#binary-integrity-and-code-signing). Runner требует версию Claude Code 2.1.224 или позже. Постройте образ, затем отправьте его в ваш реестр и ссылайтесь на него в рецептах ниже:

347 347

348```bash theme={null}348```bash theme={null}

349docker build \349docker build \

351 -t <your-registry>/claude-runner:latest .351 -t <your-registry>/claude-runner:latest .

352```352```

353 353

354Подстановка команды ищет текущий номер выпуска `stable` и передает его как аргумент сборки, поэтому запуск той же команды после нового стабильного выпуска перестраивает слой загрузки с более новым бинарным файлом. Чтобы закрепить конкретный выпуск для воспроизводимых сборок, передайте номер версии непосредственно как `CLAUDE_CODE_VERSION`. Замените `stable` на `latest` в URL поиска, когда вам нужен выпуск новее, чем стабильный канал, например, тот, который [требует недавно запущенная модель](/docs/ru/model-config).354Подстановка команды ищет текущий номер выпуска `stable` и передает его как аргумент сборки, поэтому запуск той же команды после нового стабильного выпуска перестраивает слой загрузки с более новым бинарным файлом. Чтобы закрепить конкретный выпуск для воспроизводимых сборок, передайте номер версии непосредственно как `CLAUDE_CODE_VERSION`. Замените `stable` на `latest` в URL поиска, когда вам нужен выпуск новее, чем стабильный канал, например, тот, который [требует недавно запущенная модель](/docs/ru/model-config.md).

355 355

356## Размер CPU и памяти для сеансов356## Размер CPU и памяти для сеансов

357 357

358Размер контейнера или хоста runner для сеансов, которые он запускает, а не для самого процесса runner. Runner сам опрашивает работу, подготавливает checkout каждого сеанса, запускает ваши [lifecycle hooks](/docs/ru/self-hosted-environments-configuration#lifecycle-hooks) и запускает и контролирует процессы сеанса. Нагрузка исходит от сеансов: каждый из них является процессом Claude Code плюс все, что он запускает, такое как сборки, наборы тестов, установки пакетов и [MCP servers](/docs/ru/mcp).358Размер контейнера или хоста runner для сеансов, которые он запускает, а не для самого процесса runner. Runner сам опрашивает работу, подготавливает checkout каждого сеанса, запускает ваши [lifecycle hooks](/docs/ru/self-hosted-environments-configuration.md#lifecycle-hooks) и запускает и контролирует процессы сеанса. Нагрузка исходит от сеансов: каждый из них является процессом Claude Code плюс все, что он запускает, такое как сборки, наборы тестов, установки пакетов и [MCP servers](/docs/ru/mcp.md).

359 359

360Для одного сеанса начните со следующих значений, указанных как запросы и лимиты Kubernetes или эквивалент вашей платформы, и рассматривайте их как отправную точку, а не требование:360Для одного сеанса начните со следующих значений, указанных как запросы и лимиты Kubernetes или эквивалент вашей платформы, и рассматривайте их как отправную точку, а не требование:

361 361

362* **Память**: запрос и лимит 4 ГиБ каждый, что соответствует минимуму 4 ГБ в [системных требованиях](/docs/ru/setup#system-requirements) Claude Code. Держите их равными, чтобы планировщик учитывал полную память контейнера. Когда контейнер достигает своего лимита памяти, ядро убивает процессы внутри него, что может завершить сеанс в середине задачи.362* **Память**: запрос и лимит 4 ГиБ каждый, что соответствует минимуму 4 ГБ в [системных требованиях](/docs/ru/setup.md#system-requirements) Claude Code. Держите их равными, чтобы планировщик учитывал полную память контейнера. Когда контейнер достигает своего лимита памяти, ядро убивает процессы внутри него, что может завершить сеанс в середине задачи.

363* **CPU**: запрос 2 CPU и лимит 4 CPU, чтобы сеанс мог всплеснуть выше запроса во время сборок. Ядро дросселирует контейнер на его лимите CPU, а не убивает процессы в нем, поэтому сеансы на лимите работают медленнее, но продолжают работать.363* **CPU**: запрос 2 CPU и лимит 4 CPU, чтобы сеанс мог всплеснуть выше запроса во время сборок. Ядро дросселирует контейнер на его лимите CPU, а не убивает процессы в нем, поэтому сеансы на лимите работают медленнее, но продолжают работать.

364 364

365В спецификации контейнера Kubernetes установите эти начальные значения с помощью следующего блока `resources`:365В спецификации контейнера Kubernetes установите эти начальные значения с помощью следующего блока `resources`:

376 376

377Сборки и тесты обычно являются самой большой и наиболее переменной частью нагрузки сеанса, поэтому запустите репрезентативную сборку вашего репозитория, измерьте его пиковый CPU и память и поднимите любое начальное значение, которое не оставляет места для процесса Claude Code на вершине этого пика.377Сборки и тесты обычно являются самой большой и наиболее переменной частью нагрузки сеанса, поэтому запустите репрезентативную сборку вашего репозитория, измерьте его пиковый CPU и память и поднимите любое начальное значение, которое не оставляет места для процесса Claude Code на вершине этого пика.

378 378

379Runner использует `--capacity` для ограничения количества сеансов, которые он запускает одновременно. Он не делит CPU или память между ними, поэтому сеансы на runner делят CPU и память контейнера. Чтобы ограничить долю одного сеанса, применяйте лимиты из вашего [скрипта-обертки](/docs/ru/self-hosted-environments-configuration#wrapper-scripts). То, что дать одному контейнеру, поэтому зависит от того, сколько сеансов он обслуживает одновременно:379Runner использует `--capacity` для ограничения количества сеансов, которые он запускает одновременно. Он не делит CPU или память между ними, поэтому сеансы на runner делят CPU и память контейнера. Чтобы ограничить долю одного сеанса, применяйте лимиты из вашего [скрипта-обертки](/docs/ru/self-hosted-environments-configuration.md#wrapper-scripts). То, что дать одному контейнеру, поэтому зависит от того, сколько сеансов он обслуживает одновременно:

380 380

381* **Один сеанс на runner**: дайте каждому контейнеру значения одного сеанса. Используйте эту размер на `--capacity 1`, которую [раздел усиления безопасности](#harden-your-deployment) рекомендует, и для [on-demand runners](/docs/ru/self-hosted-environments-configuration#on-demand-runners), где вы устанавливаете значения на рабочую нагрузку, которую ваш [`spawn-runner` hook](/docs/ru/self-hosted-environments-configuration#the-spawn-runner-hook) отправляет, такую как шаблон pod Kubernetes Job.381* **Один сеанс на runner**: дайте каждому контейнеру значения одного сеанса. Используйте эту размер на `--capacity 1`, которую [раздел усиления безопасности](#harden-your-deployment) рекомендует, и для [on-demand runners](/docs/ru/self-hosted-environments-configuration.md#on-demand-runners), где вы устанавливаете значения на рабочую нагрузку, которую ваш [`spawn-runner` hook](/docs/ru/self-hosted-environments-configuration#the-spawn-runner-hook) отправляет, такую как шаблон pod Kubernetes Job.

382* **Несколько сеансов на runner**: на `--capacity` выше одного, умножьте значения одного сеанса на емкость, потому что до такого количества сеансов может работать в контейнере одновременно. Рецепты [Kubernetes](#kubernetes) и [Docker Compose](#docker-compose) запускают `--capacity 4` без лимитов CPU или памяти, поэтому добавьте лимиты, размер которых соответствует емкости, которую вы запускаете.382* **Несколько сеансов на runner**: на `--capacity` выше одного, умножьте значения одного сеанса на емкость, потому что до такого количества сеансов может работать в контейнере одновременно. Рецепты [Kubernetes](#kubernetes) и [Docker Compose](#docker-compose) запускают `--capacity 4` без лимитов CPU или памяти, поэтому добавьте лимиты, размер которых соответствует емкости, которую вы запускаете.

383 383

384## Kubernetes384## Kubernetes

414 - /etc/claude/environment-secret414 - /etc/claude/environment-secret

415 - --capacity415 - --capacity

416 - "4"416 - "4"

417 - --base-dir

418 - /workspace

417 volumeMounts:419 volumeMounts:

418 - name: environment-secret420 - name: environment-secret

419 mountPath: /etc/claude421 mountPath: /etc/claude

445kubectl create namespace claude-runners447kubectl create namespace claude-runners

446```448```

447 449

448Создайте поддерживающий Secret из локального файла, содержащего значение, которое вы скопировали на шаге [**Copy environment key**](/docs/ru/self-hosted-environments-quickstart#set-up-manually) в пользовательском интерфейсе администратора, чтобы секрет никогда не появлялся в истории вашей оболочки. Запустите `(umask 077 && cat > ./environment-secret)`, вставьте секрет, нажмите Enter, затем Ctrl-D. Затем создайте Secret и удалите файл:450Создайте поддерживающий Secret из локального файла, содержащего значение, которое вы скопировали на шаге [**Copy environment key**](/docs/ru/self-hosted-environments-quickstart.md#set-up-manually) в пользовательском интерфейсе администратора, чтобы секрет никогда не появлялся в истории вашей оболочки. Запустите `(umask 077 && cat > ./environment-secret)`, вставьте секрет, нажмите Enter, затем Ctrl-D. Затем создайте Secret и удалите файл:

449 451

450```bash theme={null}452```bash theme={null}

451kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret453kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

467 - /run/secrets/environment-secret469 - /run/secrets/environment-secret

468 - --capacity470 - --capacity

469 - "4"471 - "4"

472 - --base-dir

473 - /workspace

470 secrets:474 secrets:

471 - environment-secret475 - environment-secret

472 restart: always476 restart: always

489 493

490Runner продолжает опрашивать Anthropic на протяжении всего drain. Благодаря этому его сессии остаются закреплены за ним, и другой runner не подхватит ни одну из них, пока ваш хук `post-session` ещё сохраняет незафиксированную работу.494Runner продолжает опрашивать Anthropic на протяжении всего drain. Благодаря этому его сессии остаются закреплены за ним, и другой runner не подхватит ни одну из них, пока ваш хук `post-session` ещё сохраняет незафиксированную работу.

491 495

492Поскольку `--drain-wait-sec` по умолчанию равен `0`, rolling restart прерывает любой ещё выполняемый ход, и сессия возобновляется на другом runner без своей [неотправленной работы](#additional-limitations). Чтобы позволить ходам сначала завершиться, установите `--drain-wait-sec` и соответственно увеличьте таймаут остановки.

~~493~~

494Время, записываемое в лог, является суммой следующих значений:496Время, записываемое в лог, является суммой следующих значений:

495 497

496* `--drain-wait-sec` для шага 1, по умолчанию 0 секунд498* `--drain-wait-sec` для шага 1, по умолчанию 0 секунд

506* **С [`--retire-at`](/docs/ru/self-hosted-environments-reference#runner-cli-flags)**: оставьте между временем retire и временем остановки хоста достаточно времени для завершения типичных ходов, плюс ожидание фоновых задач, которое описывает [Runner lifecycle](/docs/ru/self-hosted-environments#runner-lifecycle), плюс время, записанное в лог. Вычисляйте время retire при каждом запуске, например `date +%s` плюс предполагаемое время жизни runner.508* **С [`--retire-at`](/docs/ru/self-hosted-environments-reference#runner-cli-flags)**: оставьте между временем retire и временем остановки хоста достаточно времени для завершения типичных ходов, плюс ожидание фоновых задач, которое описывает [Runner lifecycle](/docs/ru/self-hosted-environments#runner-lifecycle), плюс время, записанное в лог. Вычисляйте время retire при каждом запуске, например `date +%s` плюс предполагаемое время жизни runner.

507* **С [`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal)**: таймаут остановки также должен охватывать настроенные вами минуты и дополнительное ожидание перед началом drain, 75 секунд при настройках по умолчанию. Оба значения объясняются в разделе [Defer the drain past the first signal](#defer-the-drain-past-the-first-signal). Runner также записывает это более длительное время в лог при запуске.509* **С [`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal)**: таймаут остановки также должен охватывать настроенные вами минуты и дополнительное ожидание перед началом drain, 75 секунд при настройках по умолчанию. Оба значения объясняются в разделе [Defer the drain past the first signal](#defer-the-drain-past-the-first-signal). Runner также записывает это более длительное время в лог при запуске.

508 510

511### Дайте выполняемым ходам завершиться перед перезапуском

512

513Чтобы дать выполняемым ходам завершиться перед rolling restart, установите `--drain-wait-sec` и увеличьте таймаут остановки как минимум до этого ожидания плюс 80 секунд. При значении ожидания по умолчанию `0` перезапуск прерывает любой ещё выполняемый ход, и сессия возобновляется на другом runner без своей [неотправленной работы](#additional-limitations).

514

515* **`--drain-wait-sec`**: примерно столько, сколько длятся ходы и фоновые задачи, которым вы хотите дать завершиться. Это максимум: ожидание заканчивается раньше, если они завершатся первыми.

516* **Ваш таймаут остановки**: `terminationGracePeriodSeconds` в Kubernetes, `stop_grace_period` в Docker Compose. Например, при `--drain-wait-sec 120` замените `90` в рецепте для [Kubernetes](#kubernetes) или [Docker Compose](#docker-compose) на `200`.

517* **Если вы изменили другие настройки завершения работы**: 80 секунд рассчитаны на настройки по умолчанию. Запустите один runner с вашими флагами и используйте как минимум число из его стартовой строки `This runner needs up to`, которое включает ожидание. Если установлен [`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal), используйте большее число из следующей стартовой строки, после `Size the stop timeout to at least`. В разделе [Время завершения работы](#shutdown-timing) перечислено, что увеличивает эти числа.

518

519> [!WARNING]

520>

521> Если таймаут остановки истекает во время ожидания, ваш хост убивает runner, пока работа ещё выполняется. Его сессии не получают хук `post-session`. Runner также не отменяет регистрацию, поэтому control plane может потребоваться несколько минут, а иногда и больше, чтобы переставить их в очередь.

522

509### Опубликуйте статусное сообщение перед перезапуском523### Опубликуйте статусное сообщение перед перезапуском

510 524

511Перед перезапуском, который прервёт сессии, попросите [Owner](/docs/ru/cloud-environments#organization-shared-environments) опубликовать статусное сообщение в среде на [странице администратора **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). На [claude.ai/code](https://claude.ai/code) участники видят это сообщение в своих сессиях в этой среде. Попросите Owner указать срок действия при публикации или удалить сообщение, когда runner снова заработают.525Перед перезапуском, который прервёт сессии, попросите [Owner](/docs/ru/cloud-environments.md#organization-shared-environments) опубликовать статусное сообщение в среде на [странице администратора **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). На [claude.ai/code](https://claude.ai/code) участники видят это сообщение в своих сессиях в этой среде. Попросите Owner указать срок действия при публикации или удалить сообщение, когда runner снова заработают.

512 526

513### Defer the drain past the first signal527### Defer the drain past the first signal

514 528

545 559

546Если runner умирает в середине сеанса, сервер переставляет сеанс в очередь и другой runner в окружении его подхватывает. Этот runner выводит путь checkout из своего собственного `--base-dir` и `--capacity`: `--capacity 1` проверяет прямо под `--base-dir`, и `--capacity` выше `1` использует вместо этого per-session worktrees. Когда runners в одном окружении используют разные значения для любого флага, рабочий каталог возобновленного сеанса изменяется, и абсолютные пути, которые агент записал ранее, в редактированиях, вызовах инструментов или своих собственных заметках, указывают на местоположение, которое больше не существует.560Если runner умирает в середине сеанса, сервер переставляет сеанс в очередь и другой runner в окружении его подхватывает. Этот runner выводит путь checkout из своего собственного `--base-dir` и `--capacity`: `--capacity 1` проверяет прямо под `--base-dir`, и `--capacity` выше `1` использует вместо этого per-session worktrees. Когда runners в одном окружении используют разные значения для любого флага, рабочий каталог возобновленного сеанса изменяется, и абсолютные пути, которые агент записал ранее, в редактированиях, вызовах инструментов или своих собственных заметках, указывают на местоположение, которое больше не существует.

547 561

548Используйте одинаковые `--base-dir` и `--capacity` на каждом runner в окружении и не используйте значение для каждого хоста, такое как ID экземпляра или имя хоста.562Используйте одинаковые `--base-dir` и `--capacity` на каждом runner в окружении и не используйте значение для каждого хоста, такое как ID экземпляра или имя хоста. Передавайте оба флага явно, как это делают рецепты для [Kubernetes](#kubernetes) и [Docker Compose](#docker-compose), чтобы ни одно из значений не зависело от значения по умолчанию.

549 563

550Базовый каталог по умолчанию `/workspace`, с исключением, которое записывает строка справочника [`--base-dir`](/docs/ru/self-hosted-environments-reference#runner-cli-flags). Runner нуждается в доступе на запись к нему. При запуске, перед регистрацией, runner создает каталог и подтверждает, что может писать в него, и выходит с `cannot create or write to base directory`, когда не может. Runner, запущенный как root, создает по умолчанию `/workspace` сам. Для non-root runner создайте каталог и дайте пользователю runner владение перед запуском runner, или укажите `--base-dir` на каталог, который этот пользователь уже владеет.564Базовый каталог по умолчанию `/workspace`, с исключением, которое записывает строка справочника [`--base-dir`](/docs/ru/self-hosted-environments-reference#runner-cli-flags). Runner нуждается в доступе на запись к нему. При запуске, перед регистрацией, runner создает каталог и подтверждает, что может писать в него, и выходит с `cannot create or write to base directory`, когда не может. Runner, запущенный как root, создает по умолчанию `/workspace` сам. Для non-root runner создайте каталог и дайте пользователю runner владение перед запуском runner, или укажите `--base-dir` на каталог, который этот пользователь уже владеет.

551 565

579 593

580Выберите, какую версию запускают ваши сессии и когда она меняется:594Выберите, какую версию запускают ваши сессии и когда она меняется:

581 595

582* **Перед тем как закрепить версию**: проверьте [версии Claude Code, которые требуют модели](/docs/ru/model-config#available-models), для каждой модели, которую используют ваши сессии. Если модель требует более новую версию, чем та, которую запускают ваши сессии, сервер отклоняет запросы для этой модели с [Claude Code does not support this model](/docs/ru/errors#claude-code-does-not-support-this-model).596* **Перед тем как закрепить версию**: проверьте [версии Claude Code, которые требуют модели](/docs/ru/model-config.md#available-models), для каждой модели, которую используют ваши сессии. Если модель требует более новую версию, чем та, которую запускают ваши сессии, сервер отклоняет запросы для этой модели с [Claude Code does not support this model](/docs/ru/errors.md#claude-code-does-not-support-this-model).

583* **Чтобы держать флот на одной версии**: постройте образ с закрепленной версией или на голом хосте установите конкретную версию и [отключите auto-updates](/docs/ru/setup#disable-auto-updates)597* **Чтобы держать флот на одной версии**: постройте образ с закрепленной версией или на голом хосте установите конкретную версию и [отключите auto-updates](/docs/ru/setup.md#disable-auto-updates)

584* **Чтобы обновить фиксированный флот**: прочитайте записи [журнала изменений](/docs/en/changelog) между вашей версией и той, которую вы устанавливаете, затем установите более новую версию или пересоберите образ и перезапустите runners598* **Чтобы обновить фиксированный флот**: прочитайте записи [журнала изменений](/docs/en/changelog.md) между вашей версией и той, которую вы устанавливаете, затем установите более новую версию или пересоберите образ и перезапустите runners

585* **Чтобы обновить runners по требованию**: прочитайте записи [журнала изменений](/docs/en/changelog) между вашей версией и той, которую вы устанавливаете, затем измените образ, который запускает ваш [хук `spawn-runner`](/docs/ru/self-hosted-environments-configuration#the-spawn-runner-hook). Каждый новый runner получает новую версию. Runner, который уже запущен, включая резервный runner, запущенный [`--min-idle`](/docs/ru/self-hosted-environments-reference#orchestrator-cli-flags), сохраняет свою версию до завершения работы. Не перезапускайте его, потому что его рабочий заказ одноразовый.599* **Чтобы обновить runners по требованию**: прочитайте записи [журнала изменений](/docs/en/changelog.md) между вашей версией и той, которую вы устанавливаете, затем измените образ, который запускает ваш [хук `spawn-runner`](/docs/ru/self-hosted-environments-configuration#the-spawn-runner-hook). Каждый новый runner получает новую версию. Runner, который уже запущен, включая резервный runner, запущенный [`--min-idle`](/docs/ru/self-hosted-environments-reference#orchestrator-cli-flags), сохраняет свою версию до завершения работы. Не перезапускайте его, потому что его рабочий заказ одноразовый.

586* **Если сессии запускают другой бинарный файл**: если вы используете [`--exec-path`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) или [хук `command`](/docs/ru/self-hosted-environments-configuration#command), чтобы запускать бинарный файл Claude Code, отличный от собственного бинарного файла runner, сессии запускают версию этого бинарного файла. Обновляйте этот бинарный файл при обновлении runner.600* **Если сессии запускают другой бинарный файл**: если вы используете [`--exec-path`](/docs/ru/self-hosted-environments-reference#runner-cli-flags) или [хук `command`](/docs/ru/self-hosted-environments-configuration#command), чтобы запускать бинарный файл Claude Code, отличный от собственного бинарного файла runner, сессии запускают версию этого бинарного файла. Обновляйте этот бинарный файл при обновлении runner.

587* **Плагины**: рынки плагинов тоже не auto-update; установите `FORCE_AUTOUPDATE_PLUGINS=1` в окружении runner, чтобы позволить плагинам auto-update, пока бинарный файл остается закрепленным601* **Плагины**: рынки плагинов тоже не auto-update; установите `FORCE_AUTOUPDATE_PLUGINS=1` в окружении runner, чтобы позволить плагинам auto-update, пока бинарный файл остается закрепленным

588 602

592 606

593Доступны два подхода к масштабированию:607Доступны два подхода к масштабированию:

594 608

595* **Фиксированный флот**: запустите статический набор реплик runner и масштабируйте на [Prometheus metrics](/docs/ru/self-hosted-environments-reference#prometheus-metrics), которые обслуживает каждый runner609* **Фиксированный флот**: запустите статический набор реплик runner и масштабируйте на [Prometheus metrics](/docs/ru/self-hosted-environments-reference.md#prometheus-metrics), которые обслуживает каждый runner

596* **On-demand runners**: запустите подкоманду `claude self-hosted-runner orchestrator`, которая опрашивает Anthropic для сеансов, которые поставлены в очередь без доступного runner и вызывает ваш hook `spawn-runner` для загрузки одного на сеанс. См. [On-demand runners](/docs/ru/self-hosted-environments-configuration#on-demand-runners).610* **On-demand runners**: запустите подкоманду `claude self-hosted-runner orchestrator`, которая опрашивает Anthropic для сеансов, которые поставлены в очередь без доступного runner и вызывает ваш hook `spawn-runner` для загрузки одного на сеанс. См. [On-demand runners](/docs/ru/self-hosted-environments-configuration.md#on-demand-runners).

597 611

598## Известные проблемы и ограничения612## Известные проблемы и ограничения

599 613

609* `https://api.anthropic.com/v1/code/sessions/*`623* `https://api.anthropic.com/v1/code/sessions/*`

610* `https://api.anthropic.com/v1/code/mcp/*`624* `https://api.anthropic.com/v1/code/mcp/*`

611 625

612Если трафик инструмента должен остаться внутри вашей сети, запустите эквивалентные инструменты как локальные MCP-серверы на образе runner вместо этого. См. [MCP servers](/docs/ru/self-hosted-environments-configuration#mcp-servers).626Если трафик инструмента должен остаться внутри вашей сети, запустите эквивалентные инструменты как локальные MCP-серверы на образе runner вместо этого. См. [MCP servers](/docs/ru/self-hosted-environments-configuration.md#mcp-servers).

613 627

614### Некоторые сеансы не считаются неактивными628### Некоторые сеансы не считаются неактивными

615 629

641 655

642## Устранение неполадок656## Устранение неполадок

643 657

644Для управляемой диагностики запустите подкоманду doctor на хосте runner. Подкоманда doctor запускает интерактивный сеанс Claude Code с логами и состоянием runner прикрепленными. Сначала войдите с `claude auth login` на этом хосте, чтобы сеанс мог запросить ваше окружение, его runners и его поставленные в очередь сеансы. Без этого входа, например, когда хост аутентифицируется с помощью ключа API, он ограничен локальной конечной точкой здоровья, метриками и логом runner, и он читает лог только если вы запустили runner с `--log-file`.658Для пошаговой диагностики запустите подкоманду doctor на хосте runner'а. Подкоманда doctor запускает интерактивную сессию Claude Code с подключёнными логами и состоянием runner'а. Сначала войдите в систему с помощью `claude auth login` на этом хосте, чтобы сессия могла запрашивать данные о вашем окружении, его runner'ах и его сессиях в очереди. Без этого входа, например когда хост проходит аутентификацию с помощью API-ключа, она ограничена локальным эндпоинтом проверки работоспособности, метриками и логом runner'а, причём лог она читает, только если вы запустили runner с `--log-file`.

645 659

646```bash theme={null}660```bash theme={null}

647claude self-hosted-runner doctor661claude self-hosted-runner doctor

648```662```

649 663

650Распространенные проблемы:664Частые проблемы:

651 665

652* **Runner не появляется в окружении**: подтвердите, что хост может достичь `api.anthropic.com` через HTTPS, секрет окружения текущий и часы хоста находятся в пределах пяти минут от реального времени; большее смещение вызывает отказ аутентификации. Runner регистрирует `[runner:fatal]` с причиной отказа при отказе аутентификации.666* **Runner не появляется в окружении**: убедитесь, что хост может подключиться к `api.anthropic.com` по HTTPS, секрет окружения актуален, а часы хоста отклоняются от реального времени не более чем на пять минут; большее расхождение приводит к сбою аутентификации. При сбое аутентификации runner записывает в лог `[runner:fatal]` с причиной отказа.

653* **Runner выходит при запуске с `cannot create or write to base directory`**: runner не может создать или писать в `--base-dir`, который по умолчанию `/workspace`. Исправьте владение каталога или укажите `--base-dir` на записываемый путь, как описано в [Keep the base directory and capacity identical across runners](#keep-the-base-directory-and-capacity-identical-across-runners). Если runner вместо этого регистрирует `[runner:fatal]`, говоря, что проверка базового каталога истекла по времени, каталог находится на зависшем монтировании NFS или CSI. Проверьте здоровье монтирования, а не разрешения. Runner печатает оба эти отказа при запуске в stderr перед открытием `--log-file`, поэтому ищите их в терминале или логах контейнера вашей платформы, а не в файле логов. До v2.1.225, runner не проверял базовый каталог при запуске, и эта неправильная конфигурация не удавалась сеансам после подхвата вместо этого.667* **Runner завершается при запуске с `cannot create or write to base directory`**: runner не может создать `--base-dir` или записать в него; по умолчанию это `/workspace`. Исправьте владельца каталога или укажите в `--base-dir` путь, доступный для записи, как описано в разделе [Сохраняйте одинаковые базовый каталог и ёмкость на всех runner'ах](#keep-the-base-directory-and-capacity-identical-across-runners). Если вместо этого runner записывает в лог `[runner:fatal]` с сообщением о том, что истёк таймаут проверки базового каталога, каталог находится на зависшем монтировании NFS или CSI. Проверьте работоспособность монтирования, а не права доступа. Runner выводит оба этих сбоя запуска в stderr до того, как откроет `--log-file`, поэтому ищите их в терминале или в логах контейнеров вашей платформы, а не в файле лога. До v2.1.225 runner не проверял базовый каталог при запуске, и такая ошибка конфигурации вместо этого приводила к сбою сессий после их принятия.

654* **Runner завершается при запуске с `RegisterRunner failed:` и ошибкой TLS-сертификата**: например, ошибка может быть `self signed certificate in certificate chain`. Runner не доверяет центру сертификации (CA), стоящему за полученным сертификатом, что бывает за прокси с TLS-инспекцией. Задайте в окружении runner переменную [`NODE_EXTRA_CA_CERTS`](/docs/ru/network-config#custom-ca-certificates), указывающую на PEM-файл с корневым CA прокси.668* **Runner завершается при запуске с `RegisterRunner failed:` и ошибкой TLS-сертификата**: например, ошибка может быть `self signed certificate in certificate chain`. Runner не доверяет центру сертификации (CA), выпустившему полученный сертификат, как бывает за прокси с инспекцией TLS. Задайте в окружении runner'а переменную [`NODE_EXTRA_CA_CERTS`](/docs/ru/network-config#custom-ca-certificates) с путём к PEM-файлу, содержащему корневой CA прокси.

655 669

656 Повторно задавать её для сессий не нужно: они её наследуют. Git её не читает: для клонирования через этот прокси задайте также [`GIT_SSL_CAINFO`](#trust-a-private-certificate-authority-with-anthropic-managed-git).670 Для сессий её не нужно задавать повторно — они её наследуют. Git её не читает: для клонирования через этот прокси также задайте [`GIT_SSL_CAINFO`](#trust-a-private-certificate-authority-with-anthropic-managed-git).

657* **Ваш скрипт запуска выводит ошибку записи, содержащую `Resource temporarily unavailable`, и завершается**: ваш скрипт использует общий stdout или stderr с процессом `claude self-hosted-runner` или [оркестратора](/docs/ru/self-hosted-environments-configuration#on-demand-runners), который он запускает, а этот процесс перевёл общий канал или сокет в неблокирующий режим. Когда канал заполнен, запись из вашего скрипта завершается этой ошибкой операционной системы вместо ожидания, и при `set -e` скрипт завершается.671* **Ваш стартовый скрипт выводит ошибку записи, содержащую `Resource temporarily unavailable`, и завершается**: ваш скрипт делит stdout или stderr с запускаемым им процессом `claude self-hosted-runner` или [оркестратора](/docs/ru/self-hosted-environments-configuration.md#on-demand-runners), который переключил этот общий канал или сокет в неблокирующий режим. Когда канал заполнен, запись из вашего скрипта вместо ожидания завершается этой ошибкой операционной системы, и при `set -e` скрипт завершается.

658 672

659 Чтобы устранить ошибку, направьте вывод runner или оркестратора в файл, который может создать пользователь вашего скрипта. Добавьте `>> "$HOME/claude-runner.log" 2>&1` к команде, которая его запускает, перед любым `&`, переводящим её в фоновый режим:673 Чтобы устранить ошибку, направьте вывод runner'а или оркестратора в файл, который может создать пользователь вашего скрипта. Добавьте `>> "$HOME/claude-runner.log" 2>&1` к команде, которая его запускает, перед любым `&`, переводящим её в фоновый режим:

660 674

661 ```bash theme={null}675 ```bash theme={null}

662 claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret >> "$HOME/claude-runner.log" 2>&1676 claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret >> "$HOME/claude-runner.log" 2>&1

663 ```677 ```

664 678

665 Собственный вывод вашего скрипта по-прежнему идёт туда же, куда и раньше, а то, что runner пишет в stdout и stderr, включая ошибки запуска, попадает в этот файл. Используйте это перенаправление оболочки, а не только [`--log-file`](/docs/ru/self-hosted-environments-reference#runner-cli-flags), который дублирует лог в файл, тогда как runner продолжает писать в stdout и stderr. Если вы уже передаёте `--log-file`, оставьте его тоже, потому что перенаправление не меняет того, что попадает в этот файл.679 Собственный вывод вашего скрипта по-прежнему идёт туда же, куда и раньше, а то, что runner пишет в stdout и stderr, включая ошибки запуска, попадает в этот файл. Используйте это перенаправление оболочки, а не только [`--log-file`](/docs/ru/self-hosted-environments-reference#runner-cli-flags), который дублирует лог в файл, пока runner продолжает писать в stdout и stderr. Если вы уже передаёте `--log-file`, сохраните и его, поскольку перенаправление не меняет того, что попадает в этот файл.

666* **Оркестратор записывает в лог `poll failed:` с ошибкой TLS-сертификата и продолжает повторные попытки**: оркестратор не доверяет CA, стоящему за полученным сертификатом, что бывает за прокси с TLS-инспекцией. Задайте в окружении оркестратора переменную [`NODE_EXTRA_CA_CERTS`](/docs/ru/network-config#custom-ca-certificates), указывающую на PEM-файл с корневым CA прокси. Задайте её также для runners, которые запускает ваш хук `spawn-runner`.680* **Оркестратор записывает в лог `poll failed:` с ошибкой TLS-сертификата и продолжает повторные попытки**: оркестратор не доверяет CA, выпустившему полученный сертификат, как бывает за прокси с инспекцией TLS. Задайте в окружении оркестратора переменную [`NODE_EXTRA_CA_CERTS`](/docs/ru/network-config#custom-ca-certificates) с путём к PEM-файлу, содержащему корневой CA прокси. Задайте её также для runner'ов, которые запускает ваш хук `spawn-runner`.

667 681

668 Например, строка может заканчиваться на `poll failed: self signed certificate in certificate chain — retrying in 1s`, где между двоеточием и тире стоит текст TLS-библиотеки. Чтобы убедиться, что проблема устранена, проверьте, что в теле ответа [`/healthz`](/docs/ru/self-hosted-environments-reference#health-endpoint) оркестратора `connected` имеет значение `true`.682 Например, строка может заканчиваться на `poll failed: self signed certificate in certificate chain — retrying in 1s`, где между двоеточием и тире стоят слова TLS-библиотеки. Чтобы убедиться, что проблема устранена, проверьте, что `connected` имеет значение `true` в теле ответа [`/healthz`](/docs/ru/self-hosted-environments-reference#health-endpoint) оркестратора.

669* **Сеансы остаются поставленными в очередь**: каждый онлайн runner может быть заблокирован для другого владельца. Проверьте метрику `claude_code_self_hosted_runner_locked_account` каждого runner [metric](/docs/ru/self-hosted-environments-reference#prometheus-metrics) или поле `locked_account` его строки логов `[runner:health]`, чтобы увидеть, кто его держит. Оба показывают email владельца только после того, как runner получил токен сеанса, несущий претензию `act.email`, которую сеансы агента Claude Tag никогда не делают. Без претензии runner не излучает серию `locked_account` и регистрирует `locked_account=yes`, что говорит вам, что runner заблокирован, но не для какого владельца. Добавьте реплики или ждите, пока существующий runner осушится и перезагрузится. Если окружение использует on-demand runners, проверьте оркестратор вместо этого; см. [On-demand runners](/docs/ru/self-hosted-environments-configuration#on-demand-runners).683* **Сессии остаются в очереди**: возможно, каждый работающий runner закреплён за другим владельцем. Проверьте [метрику](/docs/ru/self-hosted-environments-reference.md#prometheus-metrics) `claude_code_self_hosted_runner_locked_account` каждого runner'а или поле `locked_account` его строки лога `[runner:health]`, чтобы узнать, за кем он закреплён. Оба показывают email владельца только после того, как runner получил токен сессии с утверждением `act.email`, чего никогда не бывает с сессиями агента Claude Tag. Без этого утверждения runner не выдаёт серию `locked_account` и записывает в лог `locked_account=yes`, что говорит о том, что runner закреплён, но не за каким владельцем. Добавьте реплики или дождитесь, пока существующий runner завершит работу и перезапустится. Если окружение использует runner'ы по запросу, проверьте вместо этого оркестратор; см. [Runner'ы по запросу](/docs/ru/self-hosted-environments-configuration.md#on-demand-runners).

670* **Сессии завершаются сбоем сразу после получения**: откройте сессию в claude.ai/code, чтобы увидеть ошибку. Наиболее распространённые причины — отсутствие [учётных данных git](#configure-git) в образе runner и неустановленные инструменты сборки. Для runner, запущенного с `--use-anthropic-git-proxy`, см. [Когда сессии не запускаются на runner с git-прокси](#when-anthropic-doesnt-serve-a-session). Базовый каталог, недоступный для записи, останавливает runner при запуске, а не приводит к сбою сессий. См. пункт **Runner завершается при запуске с `cannot create or write to base directory`** в этом списке.684* **Сессии завершаются сбоем сразу после принятия**: откройте сессию в claude.ai/code, чтобы увидеть ошибку. Если ошибка показывает, что git не смог пройти аутентификацию, проверьте [учётные данные git](#configure-git) runner'а. Для runner'а, запущенного с `--use-anthropic-git-proxy`, см. [Если сессии не запускаются на runner'е с git-прокси](#when-anthropic-doesnt-serve-a-session).

671* **Сессии не запускаются на runner, для которого задан `--use-anthropic-git-proxy`**: найдите в логе runner `access denied by the git proxy` или ошибку git, в которой указан адрес `api.anthropic.com`, содержащий `/git_proxy/`. Чтобы определить, обслуживала ли Anthropic эту сессию, и устранить причину, см. [Когда сессии не запускаются на runner с git-прокси](#when-anthropic-doesnt-serve-a-session).

672* **Сеансы не могут достичь сеть через аутентифицирующий исходящий прокси**: когда источник, который вы установили с помощью [`--proxy-authorization-command` или `--proxy-authorization-file`](#authenticate-to-an-egress-proxy), не удается, истекает по времени после 30 секунд или дает пустое значение, runner отвечает на это соединение `502 Bad Gateway` и регистрирует почему. Runner редактирует stderr команды в этом логе и никогда не регистрирует значение заголовка. С `--proxy-authorization-command`, запустите команду самостоятельно на хосте, чтобы подтвердить, что она печатает все значение заголовка на stdout. Если runner вместо этого выходит при запуске с `could not start the proxy-authorization listener`, он не мог открыть свой слушатель loopback.

673* **Runner регистрирует строки `Poll failed`, содержащие `rejecting the malformed poll response`**: runner получил ответ на опрос работы, чье тело не является ожидаемым JSON очереди, чаще всего потому что что-то между runner и `api.anthropic.com`, такое как перехватывающий прокси или captive portal, ответил своей собственной страницей. Runner отклоняет ответ, считает его под видом `transport` метрики `claude_code_self_hosted_runner_poll_errors_total` [metric](/docs/ru/self-hosted-environments-reference#prometheus-metrics) и повторяет попытку по расписанию отказа опроса, описанному в [Session lifecycle](/docs/ru/self-hosted-environments#session-lifecycle). Runner продолжает обслуживать свои живые сеансы. Конфигурируйте прокси, чтобы пропустить ответы от `api.anthropic.com` без изменений. До v2.1.246, runner читал такой ответ как пустую очередь работы, которая могла закончить его живые сеансы или заставить его выйти.

674* **Ветка сеанса больше не существует на удаленном**: для источника git, который сеанс только читает, runner пропускает этот источник и продолжает на оставшихся. Для источника, на который сеанс отправляет результаты, удаленная ветка, обычно потому что она была объединена и auto-deleted, не удается сеанс с ошибкой, называющей репозиторий и ветку и просящей вас восстановить ветку и повторить попытку. Runner не удается сеанс с той же ошибкой, когда пропуск оставил бы его без репозитория вообще. До v2.1.228, такой сеанс начинался в пустом каталоге.

675* **Сеанс начинается без одного из его репозиториев**: на runner без [`checkout` hook](/docs/ru/self-hosted-environments-configuration#checkout), хост git может отказать в доступе runner для репозитория, который сеанс только читает. Runner затем пропускает этот репозиторий, регистрирует строку `[runner:warn] could not access context source`, называющую отказ, и начинает сеанс на оставшихся.

676 685

677 Runner пропускает только явный отказ: хост отвечает, что репозиторий не найден, git не находит учетные данные для хоста или аутентификация не удается. Сбой сети, тайм-аут или HTTP `403` все еще не удается запустить сеанс, как и отказ для репозитория, на который сеанс отправляет результаты. Runner все еще не удается сеанс, который пропуск оставил бы без репозитория вообще. С [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), runner пропускает только репозиторий, который сам git proxy отрицает.686 Базовый каталог, недоступный для записи, останавливает runner при запуске, а не приводит к сбою сессий. См. пункт **Runner завершается при запуске с `cannot create or write to base directory`** в этом списке.

687* **Сессии не запускаются на runner'е, для которого задан `--use-anthropic-git-proxy`**: ищите в логе runner'а `access denied by the git proxy` или ошибку git, в которой указан адрес `api.anthropic.com`, содержащий `/git_proxy/`. Чтобы определить, обслуживала ли Anthropic сессию, и устранить причину, см. [Если сессии не запускаются на runner'е с git-прокси](#when-anthropic-doesnt-serve-a-session).

688* **Сессии не могут выйти в сеть через исходящий прокси с аутентификацией**: когда источник, заданный с помощью [`--proxy-authorization-command` или `--proxy-authorization-file`](#authenticate-to-an-egress-proxy), завершается сбоем, превышает таймаут в 30 секунд или возвращает пустое значение, runner отвечает на это соединение `502 Bad Gateway` и записывает причину в лог. Runner скрывает stderr команды в этом логе и никогда не записывает в лог значение заголовка. При использовании `--proxy-authorization-command` выполните команду на хосте самостоятельно, чтобы убедиться, что она выводит полное значение заголовка в stdout. Если вместо этого runner завершается при запуске с `could not start the proxy-authorization listener`, он не смог открыть свой loopback-слушатель.

689* **Runner записывает в лог строки `Poll failed`, содержащие `rejecting the malformed poll response`**: runner получил ответ на опрос очереди работ, тело которого не является ожидаемым JSON очереди. Одна из причин — перехватывающий прокси или captive portal, отвечающий собственной страницей. Если runner подключается через прокси, настройте прокси так, чтобы ответы от `api.anthropic.com` передавались без изменений.

678 690

679 Проверка доступа запускается снова каждый раз, когда сеанс начинается на runner, поэтому как только git identity runner имеет доступ на чтение, следующий старт клонирует репозиторий. До v2.1.274, каждый из этих отказов не удавался запустить сеанс.691 Runner отклоняет некорректный ответ, учитывает его в категории `transport` [метрики](/docs/ru/self-hosted-environments-reference.md#prometheus-metrics) `claude_code_self_hosted_runner_poll_errors_total` и повторяет попытку по расписанию для неудачных опросов, описанному в разделе [Жизненный цикл сессии](/docs/ru/self-hosted-environments#session-lifecycle). Runner продолжает обслуживать свои активные сессии. До v2.1.246 runner воспринимал такой ответ как пустую очередь работ, что могло завершить его активные сессии или привести к его завершению.

680* **Сессия не запускается с ошибкой `This runner couldn't read`**: runner запросил репозиторий у git-хоста, используя свои [учётные данные git](#configure-git), и получил ответ о том, что репозиторий не найден. Репозиторий не существует, или эти учётные данные не дают доступа к нему.692* **Сессия завершается сбоем с `no longer exists on the remote` или `couldn't find remote ref`**: runner воспринимает сообщение git `couldn't find remote ref` как удалённую ветку. При этом ветка может по-прежнему существовать. Поищите её на вашем git-хосте точно под тем именем, что указано в сообщении, затем проверьте каждую подходящую причину:

693

694 * **Ветка удалена**: восстановите её, как просит сообщение.

695 * **Ветка существует, и вы не администрируете runner**: отправьте администратору runner'а полное сообщение и сообщите, что ветка существует.

696 * **Ветка существует, и у runner'а есть хук `checkout`**: команда git в вашем хуке может вывести `couldn't find remote ref` в stderr до того, как хук завершится с ненулевым кодом. Найдите эту команду и исправьте ref, который она запрашивает, или remote, из которого она выполняет fetch. Runner передаёт вашему хуку ревизию, запрошенную сессией, в переменной [`CLAUDE_RUNNER_REPO_REF`](/docs/ru/self-hosted-environments-configuration#checkout).

697 * **Ветка существует, и у runner'а нет хука `checkout`**: runner сам получает ветку. Если к репозиторию применяется [`--git-host-rewrite`](#rewrite-git-urls-for-private-networks), убедитесь, что на хосте, на который выполняется перезапись, есть ветка с тем же именем, и отправьте ветку туда, если её нет.

698 * **Ветка существует, и runner старше v2.1.301**: обновите runner, как описано в разделе [Закрепите версию](#pin-the-version), чтобы другой сбой показывал собственную ошибку. До v2.1.301 другие сбои, в выводе ошибки которых был `couldn't find remote ref`, также отображались как удалённая ветка.

699

700 После обновления runner'а или устранения причины повторите сессию или запустите новую. Если ни одна из этих проверок не выявила причину, [сообщите о проблеме](#report-an-issue).

701

702 Для источника, в который сессия отправляет результаты, удалённая ветка приводит к сбою сессии. Для git-источника, из которого сессия только читает, runner пропускает этот источник и продолжает работу с остальными. Runner завершает сессию сбоем, если пропуск оставил бы её вообще без репозитория. До v2.1.228 такая сессия запускалась в пустом каталоге.

703* **Сессия запускается без одного из своих репозиториев**: на runner'е без [хука `checkout`](/docs/ru/self-hosted-environments-configuration#checkout) git-хост может отклонить проверку доступа runner'а к репозиторию, из которого сессия только читает. Тогда runner пропускает этот репозиторий, записывает в лог строку `[runner:warn] could not access context source` с указанием отказа и запускает сессию с остальными репозиториями.

704

705 Runner пропускает только явный отказ: хост отвечает, что репозиторий не найден, git не находит учётных данных для хоста или аутентификация не проходит. Сбой сети, таймаут или HTTP `403` по-прежнему приводят к сбою запуска сессии, как и отказ для репозитория, в который сессия отправляет результаты. Runner по-прежнему намеренно завершает сбоем сессию, которую пропуск оставил бы вообще без репозитория. С [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) runner пропускает только репозиторий, доступ к которому отклоняет сам git-прокси.

706

707 Проверка доступа выполняется заново при каждом запуске сессии на runner'е, поэтому, как только git-идентичность runner'а получит доступ на чтение, следующий запуск клонирует репозиторий. До v2.1.274 каждый из этих отказов приводил к сбою запуска сессии.

708* **Сессия не запускается с `This runner couldn't read`**: runner запросил у git-хоста репозиторий со своими [учётными данными git](#configure-git) и получил ответ «не найдено». Репозиторий не существует, или эти учётные данные не дают доступа к репозиторию.

681 * **Если вы администрируете runner**: предоставьте его учётным данным git доступ на чтение к репозиторию, затем запустите новую сессию.709 * **Если вы администрируете runner**: предоставьте его учётным данным git доступ на чтение к репозиторию, затем запустите новую сессию.

682 * **Если сессию запустили вы**: если репозиторий не существует, запустите новую сессию с правильным репозиторием. Если у runner нет доступа к репозиторию, попросите администратора runner предоставить доступ, затем запустите новую сессию.710 * **Если вы запустили сессию**: если репозиторий не существует, запустите новую сессию с правильным репозиторием. Если у runner'а нет доступа к репозиторию, попросите администратора runner'а предоставить доступ, затем запустите новую сессию.

683* **Сеансы занимают минуты для запуска**: начальный клон обычно доминирует. Смотрите метрику `claude_code_self_hosted_runner_session_init_duration_seconds` [metric](/docs/ru/self-hosted-environments-reference#prometheus-metrics), чтобы подтвердить, и сократите клон с помощью [pre-warmed checkout](#reuse-a-pre-warmed-checkout) или меньшего `CLAUDE_RUNNER_FETCH_DEPTH`.711* **Сессии запускаются несколько минут**: обычно основное время занимает первоначальное клонирование. Чтобы убедиться в этом, следите за [метрикой](/docs/ru/self-hosted-environments-reference.md#prometheus-metrics) `claude_code_self_hosted_runner_session_init_duration_seconds`, и сократите клонирование с помощью [предварительно подготовленного checkout](#reuse-a-pre-warmed-checkout) или меньшего значения `CLAUDE_RUNNER_FETCH_DEPTH`.

684* **Ходы завершаются с ошибкой 401**: когда ход завершается ошибкой 401 или 403 от Anthropic API, runner получает от Anthropic свежий [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ru/self-hosted-environments-configuration#wrapper-scripts) и передаёт его сессии. Неудавшийся ход не повторяется. Этот токен краткосрочный, и runner ротирует его через stdin сессии.712* **Ходы завершаются с ошибкой 401**: когда ход заканчивается ответом 401 или 403 от Anthropic API, runner получает новый [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ru/self-hosted-environments-configuration#wrapper-scripts) от Anthropic и передаёт его сессии. Неудавшийся ход не повторяется. Этот токен краткосрочный, и runner ротирует его через stdin сессии.

713

714 Когда получение токена не удаётся, runner записывает в лог строку `inference_token refresh failed` с указанием, когда будет повторная попытка, и продолжает повторять попытки, пока работает сессия.

685 715

686 Когда fetch не удается, runner регистрирует строку `inference_token refresh failed`, которая говорит, когда он будет повторять попытку, и он продолжает повторять попытку столько, сколько работает сеанс.716 Если все вызовы начинают завершаться сбоем примерно через 30 минут после начала сессии, вероятно, скрипт-обёртка отключил stdin сессии, поэтому ротации токена не могут до неё дойти; см. [Сохраняйте подключёнными stdin и файловый дескриптор 3](/docs/ru/self-hosted-environments-configuration.md#keep-stdin-and-file-descriptor-3-attached).

687 717

688 Если каждый вызов начинает не удаваться примерно через 30 минут в сеанс, скрипт-обертка, вероятно, разорвал stdin сеанса, поэтому ротации токенов не могут достичь его; см. [Keep stdin and file descriptor 3 attached](/docs/ru/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached).718 До v2.1.274 runner прекращал повторные попытки получения токена после нескольких неудач и ждал следующего запланированного получения. Неудавшийся ход не вызывал получение токена, поэтому каждый ход завершался ошибкой 401 до следующего запланированного получения.

719* **Ход завершается в claude.ai/code с `This model needs a newer version of Claude Code`**: версия Claude Code, с которой ваши runner'ы запускают сессии, старше, чем требует модель сессии, поэтому API [отклоняет запрос](/docs/ru/errors.md#claude-code-does-not-support-this-model). Обновите runner'ы до версии, указанной в сообщении, или более поздней, как описано в разделе [Закрепите версию](#pin-the-version). До этого пользователи могут выбрать в сессии другую модель.

720* **Под завершается принудительно во время drain**: увеличьте `terminationGracePeriodSeconds` как минимум до значения, которое runner записывает в лог при запуске. См. [Время завершения работы](#shutdown-timing).

689 721

690 До v2.1.274, runner прекратил повторять попытку неудачного fetch после нескольких попыток и ждал следующего запланированного. Неудачный turn не вызвал fetch, поэтому каждый turn не удавался с 401 до следующего запланированного fetch.722После инициализации логирования runner пишет свой лог жизненного цикла, включая строки `[runner:fatal]`, в stdout, а отладочный вывод — в stderr, всё в виде строк простого текста, а не JSON. Сбои базового каталога, описанные в пунктах выше, выводятся в stderr до этого момента. Сохраняйте оба потока с помощью `--log-file`, что также позволяет `self-hosted-runner doctor` отслеживать их, или с помощью средств сбора логов вашей платформы.

691* **Ход в claude.ai/code завершается ошибкой `This model needs a newer version of Claude Code`**: версия Claude Code, с которой ваши runners запускают сессии, старше той, что требуется модели сессии, поэтому API [отклоняет запрос](/docs/ru/errors#claude-code-does-not-support-this-model). Обновите runners до версии, указанной в сообщении, или более поздней, как описано в разделе [Закрепление версии](#pin-the-version). До тех пор пользователи могут выбрать в сессии другую модель.

692* **Pod убивается в середине осушения**: поднимите `terminationGracePeriodSeconds` по крайней мере на значение, которое runner регистрирует при запуске. См. [Shutdown timing](#shutdown-timing).

693 723

694После инициализации логирования runner записывает лог своего жизненного цикла, включая строки `[runner:fatal]`, в stdout, а отладочный вывод — в stderr, всё в виде обычных текстовых строк, а не JSON. Сбои базового каталога, описанные в пунктах об устранении неполадок выше, выводятся в stderr ещё до этого момента. Сохраняйте оба потока с помощью `--log-file`, что также позволяет `self-hosted-runner doctor` их просматривать, или с помощью сбора логов вашей платформы.724Дочерний процесс каждой сессии пишет отдельный отладочный лог. При сбое runner показывает конец этого лога рядом с сессией в claude.ai/code. Если вы не запустили runner с [`--remove-session-state`](/docs/ru/self-hosted-environments-reference#runner-cli-flags), он также сохраняет лог неудавшейся сессии на диске и выводит его путь в лог runner'а.

695 725

696Каждый процесс дочернего сеанса пишет отдельный отладочный лог. При отказе runner выводит хвост логов рядом с сеансом в claude.ai/code. Если вы не запустили runner с [`--remove-session-state`](/docs/ru/self-hosted-environments-reference#runner-cli-flags), он также сохраняет лог неудачного сеанса на диске и печатает его путь в логе runner.726### Когда runner завершается

697 727

698### Когда runner выходит728Не перезапускайте [runner по запросу](/docs/ru/self-hosted-environments-configuration.md#on-demand-runners), поскольку его рабочее задание одноразовое. Runner, который завершается сразу после запуска, требует иного подхода, чем runner, завершившийся по любой другой причине.

699 729

700Не перезапускайте [on-demand runner](/docs/ru/self-hosted-environments-configuration#on-demand-runners), потому что его рабочий заказ одноразовый. Runner, который выходит сразу после запуска, требует другой обработки, чем тот, который выходит по любой другой причине.730* **Нормальное завершение**: runner завершил свои сессии и выполнил drain, достиг времени вывода из эксплуатации или получил команду остановиться. Перезапустите его, чтобы у окружения снова была ёмкость. Эти завершения описаны в разделе [Жизненный цикл runner'а](/docs/ru/self-hosted-environments#runner-lifecycle).

731* **Неудачный запуск**: runner не может запуститься с заданной ему конфигурацией или на заданном хосте, поэтому он завершается через несколько секунд после запуска и завершается так же при каждом перезапуске. Более быстрый перезапуск не поможет. Кому-то нужно прочитать его вывод и устранить причину.

732* **Потеря связи**: runner, который не может связаться с Anthropic дольше срока своей [аренды](/docs/ru/self-hosted-environments#session-lifecycle), например пока его хост находится в спящем режиме, может быть удалён из окружения. Когда удалённый runner снова подключается, он завершается. В его логе может быть строка `[runner:fatal]`, содержащая `runner record gone server-side` или, после более длительного перерыва, [`poll auth failed`](/docs/ru/self-hosted-environments-quickstart#set-up-an-environment-and-runner). Runner не регистрируется повторно самостоятельно, поэтому перезапустите его.

701 733

702* **Нормальный выход**: runner завершил свои сеансы и осушился, достиг времени выхода на пенсию или ему было приказано остановиться. Перезапустите его, чтобы окружение снова имело емкость. [Runner lifecycle](/docs/ru/self-hosted-environments#runner-lifecycle) описывает эти выходы.734Настройте супервизор так, чтобы он перезапускал runner при каждом его завершении, увеличивал паузу между перезапусками, когда runner продолжает завершаться сразу после запуска, и оповещал кого-либо, когда это продолжается.

703* **Неудачный старт**: runner не может запуститься с конфигурацией или хостом, который ему был дан, поэтому он выходит через несколько секунд после запуска, и он выходит одинаково каждый раз, когда вы его перезапускаете. Перезапуск его быстрее не помогает. Кто-то должен прочитать его вывод и исправить причину.

704* **Потеря связи**: runner, который не может связаться с Anthropic дольше срока своей [аренды](/docs/ru/self-hosted-environments#session-lifecycle), например пока его хост находится в спящем режиме, может быть удалён из окружения. Когда удалённый runner снова подключается, он завершается. В его логе может появиться строка `[runner:fatal]`, содержащая `runner record gone server-side` или, после более длительного перерыва, [`poll auth failed`](/docs/ru/self-hosted-environments-quickstart#set-up-an-environment-and-runner). Runner не регистрируется повторно самостоятельно, поэтому перезапустите его.

705 735

706Конфигурируйте ваш supervisor, чтобы перезапустить runner всякий раз, когда он выходит, чтобы ждать дольше между перезапусками, когда runner продолжает выходить сразу после запуска, и чтобы сообщить кому-то, когда это продолжает происходить.736В продакшене пусть супервизор перезапускает runner на чистом диске, в новом контейнере или VM, как рекомендует раздел [Усильте защиту развёртывания](#harden-your-deployment).

707 737

708#### Распознайте неудачный старт738#### Как распознать неудачный запуск

709 739

710Когда runner не может запуститься, он печатает строку, которая говорит почему, а затем выходит. Для большинства причин строка содержит `[runner:fatal]`. Для некоторых причин строка начинается с `error:` вместо этого, включая когда runner не может разобрать свои флаги, не может прочитать секрет окружения или не может создать или писать в базовый каталог. Следующая строка затем указывает на `--help`.740Когда runner не может запуститься, он выводит строку с причиной, а затем завершается. В большинстве случаев строка содержит `[runner:fatal]`. В некоторых случаях строка вместо этого начинается с `error:`, в том числе когда runner не может разобрать свои флаги, не может прочитать секрет окружения или не может создать базовый каталог или записать в него. Следующая строка тогда указывает на `--help`.

711 741

712Большинство строк логов начинаются с временной метки и `[self-hosted-runner]`, которые образец ниже опускает. Например, runner, запущенный с прокси Anthropic git и емкостью выше одного, печатает строку, подобную этой:742Большинство строк лога начинаются с временной метки и `[self-hosted-runner]`, которые в примере ниже опущены. Например, runner, запущенный с git-прокси Anthropic и ёмкостью больше единицы, выводит строку вроде этой:

713 743

714```text theme={null}744```text theme={null}

715[runner:fatal] --use-anthropic-git-proxy requires --capacity 1 (the proxy URL is per-session and linked worktrees share origin). Omit --use-anthropic-git-proxy or set --capacity 1.745[runner:fatal] --use-anthropic-git-proxy requires --capacity 1 (the proxy URL is per-session and linked worktrees share origin). Omit --use-anthropic-git-proxy or set --capacity 1.

716```746```

717 747

718Ищите строку в стандартном выводе и стандартной ошибке runner, в логах контейнера вашей платформы или в файле, который вы установили с помощью [`--log-file`](/docs/ru/self-hosted-environments-reference#runner-cli-flags). Runner печатает строку `error:` перед открытием файла логов, поэтому ищите его в терминале или логах контейнера, как отмечает [Troubleshooting](#troubleshooting).748Ищите эту строку в стандартном выводе и стандартном потоке ошибок runner'а, в логах контейнеров вашей платформы или в файле, заданном с помощью [`--log-file`](/docs/ru/self-hosted-environments-reference#runner-cli-flags). Runner выводит строку `error:` до того, как откроет файл лога, поэтому ищите её в терминале или в логах контейнера, как отмечено в разделе [Устранение неполадок](#troubleshooting).

719 749

720Это также помогает, когда вы читаете неудачный старт:750При разборе неудачного запуска также помогут следующие моменты:

721 751

722* **Нет строки вообще**: runner, который хост убивает, не печатает ни одну. Если вывод заканчивается без строки `[runner:fatal]` и без строки `error:`, проверьте, остановил ли хост или ваш оркестратор процесс, например, за превышение лимита памяти.752* **Строки нет вовсе**: runner, который принудительно завершил хост, не выводит ни той, ни другой строки. Если вывод заканчивается без строки `[runner:fatal]` и без строки `error:`, проверьте, не остановил ли процесс хост или ваш оркестратор, например из-за превышения лимита памяти.

723* **Код выхода**: runner не откладывает код выхода для ошибок, которые повторяются при каждом запуске. Он выходит с тем же кодом для ошибки конфигурации, такой как неподдерживаемая комбинация флагов, и для отказа, который может очиститься сам по себе, такой как API, остающийся недостижимым через собственные повторы runner. Основывайте решение ждать дольше на том, как скоро runner выходит, и прочитайте вывод runner, чтобы узнать почему.753* **Код выхода**: runner не выделяет отдельный код выхода для ошибок, повторяющихся при каждом запуске. Он завершается с одним и тем же кодом как при ошибке конфигурации, например неподдерживаемом сочетании флагов, так и при сбое, который может устраниться сам, например когда API остаётся недоступным на протяжении собственных повторных попыток runner'а. Решение об увеличении паузы принимайте исходя из того, как скоро runner завершился, а причину выясняйте по выводу runner'а.

724* **Окружение, которое выглядит здоровым**: некоторые шаги запуска запускаются после того, как runner регистрируется в вашем окружении, такие как [`--configure-git`](#let-the-runner-configure-git) и настройка учетных данных прокси Anthropic git. Если один из этих шагов не удается, окружение может продолжать перечислять этот runner в течение нескольких минут после выхода процесса, и страница **Cloud environments** может читать **Healthy**, пока ни один runner не подхватывает работу. Если сеансы остаются поставленными в очередь в окружении, которое выглядит здоровым, проверьте, перезапускает ли ваш supervisor runner.754* **Окружение выглядит работоспособным**: некоторые шаги запуска выполняются после регистрации runner'а в окружении, например [`--configure-git`](#let-the-runner-configure-git) и настройка учётных данных git-прокси Anthropic. Если один из этих шагов завершается сбоем, окружение может ещё несколько минут после завершения процесса продолжать отображать этот runner, и страница **Cloud environments** может показывать **Healthy**, хотя ни один runner не принимает работу. Если сессии остаются в очереди в окружении, которое выглядит работоспособным, проверьте, не перезапускает ли ваш супервизор runner.

725 755

726#### Перезапуск с растущим ожиданием756#### Перезапуск с растущей паузой

727 757

728Как вы получаете растущее ожидание, зависит от вашего supervisor.758Способ получить растущую паузу зависит от вашего супервизора.

729 759

730* **Kubernetes**: [Deployment](#kubernetes) на этой странице не требует изменений. После выхода контейнера kubelet по умолчанию ждет перед перезапуском контейнера, и ожидание растет при каждом перезапуске до потолка. Ожидание начинается заново, как только контейнер работает некоторое время без выхода.760* **Kubernetes**: [Deployment](#kubernetes) на этой странице не требует изменений. После завершения контейнера kubelet по умолчанию ждёт перед его перезапуском, и пауза растёт с каждым перезапуском до верхнего предела. Пауза сбрасывается, как только контейнер некоторое время проработает без завершения.

731 761

732 Kubelet применяет то же ожидание после нормального выхода, когда контейнер работал только недолго. Runner, который часто осушается, поэтому может также показать статус `CrashLoopBackOff`, поэтому прочитайте вывод перед тем, как вы заключите, что runner не может запуститься. Команда ниже читает вывод последнего запуска из одного pod Deployment:762 Kubelet применяет ту же паузу и после нормального завершения, если контейнер проработал недолго. Поэтому runner, который часто выполняет drain, тоже может показывать статус `CrashLoopBackOff`, так что прочитайте вывод, прежде чем заключать, что runner не может запуститься. Команда ниже читает вывод последнего запуска одного пода Deployment:

733 763

734 ```bash theme={null}764 ```bash theme={null}

735 kubectl logs --previous -n claude-runners deploy/claude-runner765 kubectl logs --previous -n claude-runners deploy/claude-runner

736 ```766 ```

737 767

738 Когда последний запуск был неудачным стартом, строка `[runner:fatal]` или `error:` находится среди последних строк вывода. Чтобы прочитать последний запуск другого pod, назовите этот pod вместо `deploy/claude-runner`.768 Если последний запуск был неудачным, строка `[runner:fatal]` или `error:` находится среди последних строк вывода. Чтобы прочитать последний запуск другого пода, укажите этот под вместо `deploy/claude-runner`.

739* **Docker и Docker Compose**: [Compose recipe](#docker-compose) на этой странице не требует изменений. С `restart: always`, Docker ждет дольше перед каждым перезапуском контейнера, который продолжает выходить, до потолка. Замените `<container>` на имя контейнера в команде ниже, которая читает, сколько раз Docker перезапустил контейнер:769* **Docker и Docker Compose**: [рецепт Compose](#docker-compose) на этой странице не требует изменений. С `restart: always` Docker ждёт всё дольше перед каждым перезапуском контейнера, который продолжает завершаться, до верхнего предела. Замените `<container>` на имя контейнера в команде ниже, которая показывает, сколько раз Docker перезапускал контейнер:

740 770

741 ```bash theme={null}771 ```bash theme={null}

742 docker inspect --format '{{.RestartCount}}' <container>772 docker inspect --format '{{.RestartCount}}' <container>

743 ```773 ```

744 774

745 Команда печатает число. Число, которое продолжает расти, означает, что Docker продолжает перезапускать runner.775 Команда выводит число. Если число продолжает расти, Docker продолжает перезапускать runner.

746* **Модуль systemd**: по умолчанию systemd ждет одинаковый `RestartSec` перед каждым перезапуском и не удлиняет его, поэтому модуль с `Restart=always` перезапускает runner, который не может запуститься в этом же интервале каждый раз. Когда старты приходят достаточно быстро, чтобы достичь лимита скорости запуска модуля, пять стартов в 10 секунд по умолчанию, systemd прекращает перезапуск модуля. Модуль остается остановленным, пока кто-то его снова не запустит, что systemd позволяет, как только интервал лимита скорости прошел или после `systemctl reset-failed`. Потому что `RestartSec` применяется к каждому перезапуску, большее значение также задерживает перезапуск после нормального выхода. Выберите значение, которое балансирует два, и предупредите о счетчике перезапусков модуля.776* **Юнит systemd**: по умолчанию systemd ждёт одинаковое время `RestartSec` перед каждым перезапуском и не увеличивает его, поэтому юнит с `Restart=always` перезапускает runner, который не может запуститься, каждый раз с одним и тем же интервалом. Когда запуски происходят достаточно часто, чтобы достичь ограничения частоты запусков юнита (по умолчанию пять запусков за 10 секунд), systemd прекращает перезапускать юнит. Юнит остаётся остановленным, пока кто-нибудь не запустит его снова, что systemd разрешает после истечения интервала ограничения частоты запусков или после `systemctl reset-failed`. Поскольку `RestartSec` применяется к каждому перезапуску, большее значение также задерживает перезапуск после нормального завершения. Выберите значение, которое уравновешивает эти два случая, и настройте оповещения по счётчику перезапусков юнита.

747* **Цикл shell или ваш собственный supervisor**: применяйте то же правило самостоятельно. Начните с ожидания в пять секунд. После каждого запуска, который закончился в течение минуты, удвойте ожидание для следующего перезапуска, до пяти минут. После запуска, который длился минуту или более, вернитесь к пяти секундам.777* **Цикл в оболочке или собственный супервизор**: примените то же правило самостоятельно. Начните с паузы в пять секунд. После каждого запуска, который завершился в пределах минуты, удваивайте паузу перед следующим перезапуском, максимум до пяти минут. После запуска, который длился минуту или дольше, вернитесь к пяти секундам.

748 778

749#### Проверьте, почему runner продолжает выходить779#### Выясните, почему runner продолжает завершаться

750 780

751Когда runner выходит сразу после запуска несколько раз подряд, остановитесь и проверьте это перед перезапуском снова.781Если runner несколько раз подряд завершился сразу после запуска, остановитесь и проверьте следующее, прежде чем снова его перезапускать.

752 782

753* **Последняя строка `[runner:fatal]` или `error:`**: она говорит почему runner остановился. [Troubleshooting](#troubleshooting) перечисляет распространенные причины.783* **Последняя строка `[runner:fatal]` или `error:`**: в ней сказано, почему runner остановился. Частые причины перечислены в разделе [Устранение неполадок](#troubleshooting).

754* **Комбинация флагов**: [Anthropic git proxy](#use-the-anthropic-git-proxy) требует `--capacity 1`. Рецепты на этой странице используют более высокую емкость, поэтому понизьте ее, когда вы добавляете прокси к одному из них.784* **Сочетание флагов**: [git-прокси Anthropic](#use-the-anthropic-git-proxy) требует `--capacity 1`. Рецепты на этой странице используют бо́льшую ёмкость, поэтому уменьшите её, когда добавляете прокси в один из них.

755* **Что может достичь окружение сервиса**: если runner запускается вручную и не удается под вашим supervisor, сравните пользователя, домашний каталог, `PATH` и лимит памяти. `--configure-git` и прокси Anthropic git нужны git на `PATH` и записываемый `~/.gitconfig`.785* **Что доступно окружению службы**: если runner запускается вручную, но завершается сбоем под вашим супервизором, сравните пользователя, домашний каталог, `PATH` и лимит памяти. `--configure-git` и git-прокси Anthropic требуют наличия git в `PATH` и доступного для записи `~/.gitconfig`.

756* **Секрет окружения**: если вы отозвали секрет или неправильно его напечатали, runner печатает строку, которая содержит `RegisterRunner auth failed`.786* **Секрет окружения**: если вы отозвали секрет или ошиблись при его вводе, runner выводит строку, содержащую `RegisterRunner auth failed`.

757* **Вкладка Activity окружения**: откройте окружение и выберите **Activity**. Если новые runners продолжают появляться там и ни один не подхватывает работу, ваш supervisor перезапускает runner.787* **Вкладка Activity окружения**: откройте окружение и выберите **Activity**. Если там продолжают появляться новые runner'ы и ни один из них не принимает работу, ваш супервизор перезапускает runner.

758 788

759Для управляемой диагностики на хосте runner запустите [подкоманду doctor](#troubleshooting).789Для пошаговой диагностики на хосте runner'а запустите [подкоманду doctor](#troubleshooting).

760 790

761## Что дальше791## Что дальше

762 792

763* [Customize sessions](/docs/ru/self-hosted-environments-configuration): скрипты-обертки, lifecycle hooks, on-demand runners, MCP servers и разрешения793* [Customize sessions](/docs/ru/self-hosted-environments-configuration.md): скрипты-обертки, lifecycle hooks, on-demand runners, MCP servers и разрешения

764* [Test end to end](/docs/ru/self-hosted-environments-testing): проверьте новый образ runner из CI перед продвижением794* [Test end to end](/docs/ru/self-hosted-environments-testing.md): проверьте новый образ runner из CI перед продвижением

765* [Reference](/docs/ru/self-hosted-environments-reference): каждый флаг CLI, переменная окружения и метрика795* [Reference](/docs/ru/self-hosted-environments-reference.md): каждый флаг CLI, переменная окружения и метрика

self-hosted-environments-deploy.md 2026-10-21 23:02 UTC to 2026-10-22 22:58 UTC

Развертывание самостоятельно размещаемых окружений в production

Усиление безопасности развёртывания

Требования к сети

Default-deny egress

Аутентификация на исходящий прокси

Выберите, откуда берется значение Proxy-Authorization

Конфигурации, с которыми runner отказывается запускаться

Что runner изменяет, пока установлен флаг proxy-authorization

Настройка git

Позвольте раннеру настроить git

Поставляйте конфигурацию git в своём образе

Используйте git-прокси Anthropic

Включение git-прокси Anthropic

Как Anthropic обслуживает git для сессии

Когда сессии не запускаются на раннере с git-прокси

Отключение git-прокси Anthropic

Доступ к API GitHub без GitHub CLI

Доверие частному центру сертификации при использовании git под управлением Anthropic

Перезапись URL git для частных сетей

Постройте образ runner

Размер CPU и памяти для сеансов

Kubernetes

Docker Compose

Время завершения работы

Дайте выполняемым ходам завершиться перед перезапуском

Опубликуйте статусное сообщение перед перезапуском

Defer the drain past the first signal

Что происходит с сессиями, которые runner удерживает после первого сигнала

Установите таймаут остановки

Что достигает работающего хука post-session

Держите базовый каталог и емкость идентичными на всех runners

Переиспользуйте pre-warmed checkout

Закрепите версию

Масштабируйте флот

Известные проблемы и ограничения

Трафик коннектора покидает вашу сеть

Некоторые сеансы не считаются неактивными

Дополнительные ограничения

Сообщите о проблеме

Устранение неполадок

Когда runner завершается

Как распознать неудачный запуск

Перезапуск с растущей паузой

Выясните, почему runner продолжает завершаться

Что дальше

Выберите, откуда берется значение `Proxy-Authorization`