Развертывание самостоятельно размещаемых окружений в 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, чтобы узнать, где должны находиться эти гранты.

​

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

• 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.

• Однострочный установщик: получает 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

​

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

​

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

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

​

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

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

​

Что runner изменяет, пока установлен флаг 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: запустите раннер с --configure-git, чтобы он записал ту же конфигурацию идентичности и подписи коммитов, что используется в сессиях, размещённых Anthropic
• Поставлять конфигурацию git в образе: задайте идентичность и учётные данные для push самостоятельно, например чтобы делать коммиты от имени собственного бота

​

Позволить раннеру настроить 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 и раннер не использует управляемый Anthropic git, раннер сохраняет вашу настройку, пропускает установку этих хуков и выводит предупреждение [runner:git].

​

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

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

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

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

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

​

Использование git-прокси Anthropic

• Только 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-прокси.

​

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

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

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

​

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

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

​

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

• Нет ни 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. Клонирование сессии завершается ошибкой, и ошибка git содержит GitHub authentication required. Please reconnect your GitHub account. Попросите этого человека подключить или переподключить GitHub в настройках claude.ai.

​

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

unset CLAUDE_RUNNER_USE_GIT_PROXY

​

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

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

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

​

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

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

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

​

Добавление репозиториев github.com в сессии каналов Claude Tag

​

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

• --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 должен подключаться без интерактивного запроса.

​

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

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"]

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

​

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

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

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

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

​

Задайте каждой сессии собственный лимит памяти

• В контейнере: запускайте один runner на контейнер и задайте лимит памяти контейнера, например limits.memory в Kubernetes, --memory в Docker или mem_limit в файле Compose. Следите, чтобы сумма лимитов контейнеров была меньше памяти хоста, потому что когда память заканчивается на самом хосте, ядро может завершать процессы в любом месте хоста.
• Под systemd без контейнера: задайте MemoryMax для unit-а runner и запускайте один runner на хост, потому что runner, использующие один и тот же --base-dir в одной файловой системе, совместно используют клонированные туда репозитории. Например, при --capacity 1 и без хука checkout их сессии в одном репозитории могут одновременно работать в одном и том же checkout. Чтобы запустить несколько runner на одном хосте, выделите каждому контейнер.

​

Оставьте запас под лимитами процессов и потоков

​

Где задать каждый лимит

​

Измерьте пик одной сессии

​

Проверьте лимит pids.max

• Проверьте, был ли достигнут pids.max: найдите в логе ядра хоста, например с помощью dmesg, строку, содержащую cgroup: fork rejected by pids controller in и путь cgroup. Ядро записывает её в лог только в первый раз, когда отказывает в создании процесса или потока в этой cgroup, поэтому ищите по всему логу.
• Узнайте действующий лимит: прочитайте pids.max в каталоге cgroup runner и в каждом каталоге выше него. Наименьшее значение и есть действующий лимит, а max означает отсутствие лимита на этом уровне.

​

Kubernetes

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

kubectl create namespace claude-runners

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

​

Docker Compose

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

​

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

1. Runner ждёт до --drain-wait-sec секунд, по умолчанию 0, пока завершатся ещё выполняемые ходы.
2. Он завершает дерево процессов каждой сессии, включая любую команду, которую Claude всё ещё выполнял, но не процесс, продолжающий работать после завершения своей shell-команды.
3. Он запускает lifecycle-хук 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

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

​

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

​

Defer the drain past the first signal

​

Что происходит с сессиями, которые 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 секунд.

​

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

​

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

• 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.

​

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

​

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

• При --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, которые их обслуживают.

• Глубина клона: создавайте клон без --depth, с --single-branch или без него. Runner никогда не передает --depth при выполнении fetch в клон с удаленным репозиторием origin, даже если вы задали CLAUDE_RUNNER_FETCH_DEPTH. С полным клоном каждая сессия загружает только те коммиты, которых нет в клоне. С неглубоким клоном сессия в ветке, ответвившейся до самого старого коммита клона, загружает всю историю этой ветки.
• Отслеживаемые изменения сбрасываются, неотслеживаемые файлы сохраняются: при --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 использует ваш клон

​

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

• Перед тем как закрепить версию: проверьте версии 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, пока бинарный файл остается закрепленным

​

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

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

​

Освобождение простаивающих сессий во фиксированном флоте

• Ряды выше этого времени, например 1800 для 30 минут: простаивающие сессии удерживают эти слоты, поэтому задайте --release-idle-session-min
• Все ряды ниже него: ни одна сессия не простаивала так долго. Добавьте runners или задайте --kill-session-after-min для сессий, которые никогда не переходят в простой.
• Runner без рядов: его не удерживает ни одна сессия. См. Sessions stay queued в разделе Устранение неполадок.
• Runner, метрики которого не отвечают: его процесс мог завершиться. См. An environment that looks healthy в разделе Когда runner завершает работу.

• Неотправленная работа: освобождённая сессия возобновляется при следующем сообщении, но без работы, которую она не отправила (push). Чтобы сохранить её коммиты, см. Resumed sessions lose unpushed work.
• Завершение runner: runner, освободивший свою последнюю сессию, начинает обычное завершение. Настройте ваш супервизор так, чтобы он перезапускал его на чистой файловой системе, как описано в разделе Усиление защиты развёртывания.
• Сессии, которые никогда не переходят в простой: также задайте --kill-session-after-min, потому что некоторые сессии не считаются простаивающими

​

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

​

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

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

​

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

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

​

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

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

​

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

​

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

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 в этом списке.
• Сессия принята, но Claude так и не отвечает на её первое сообщение: если ваши runner’ы подключаются к api.anthropic.com через прокси, настройте его так, чтобы ответ /worker/events/stream сессии передавался по мере поступления. Увеличение таймаутов runner’а не поможет. Чтобы подтвердить причину по логу runner’а, см. Сессия принята, но Claude так и не отвечает на её первое сообщение.
• Сессии не запускаются на 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’а предоставить доступ, затем запустите новую сессию.
• Сессии запускаются или возобновляются несколько минут: одна из причин — клонирование с нуля. В парке, где каждый runner запускается на пустом диске без хука checkout, runner заново клонирует репозитории сессии, прежде чем запустить Claude Code. Сессия, которая возобновляется на пустом диске, снова ждёт того же клонирования. Чтобы избежать клонирования с нуля, предоставьте предварительно подготовленный checkout. Если вы уже его предоставляете, убедитесь, что runner его использует. Если runner сам создаёт клон и завершается после одной сессии, уменьшите CLAUDE_RUNNER_FETCH_DEPTH со значения по умолчанию в 50 коммитов, чтобы получать меньше истории. Если вы используете хук, он выполняется вместо клонирования runner’ом, поэтому вместо этого проверьте, что делает ваш хук. Следите за метрикой claude_code_self_hosted_runner_session_init_duration_seconds, чтобы видеть, сколько времени занимают запуски.
• Ходы завершаются с ошибкой 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 завершил свои сессии и выполнил drain, достиг времени вывода из эксплуатации или получил команду остановиться. Перезапустите его, чтобы у окружения снова была ёмкость. Эти завершения описаны в разделе Жизненный цикл runner’а.
• Неудачный запуск: runner не может запуститься с заданной ему конфигурацией или на заданном хосте, поэтому он завершается через несколько секунд после запуска и завершается так же при каждом перезапуске. Более быстрый перезапуск не поможет. Кому-то нужно прочитать его вывод и устранить причину.
• Потеря связи: runner, который не может связаться с Anthropic дольше срока своей аренды, например пока его хост находится в спящем режиме, может быть удалён из окружения. Когда удалённый runner снова подключается, он завершается. В его логе может быть строка [runner:fatal], содержащая runner record gone server-side или, после более длительного перерыва, poll auth failed. Runner не регистрируется повторно самостоятельно, поэтому перезапустите его.

​

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

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

​

Сессия принята, но Claude так и не отвечает на её первое сообщение

GET https://api.anthropic.com/v1/code/sessions/<session-id>/worker/events/stream

• Не буферизуйте ответ: передавайте его по мере поступления. Его тип содержимого — text/event-stream.
• Позвольте ответу оставаться открытым: он может оставаться открытым до часа. Если у прокси есть таймаут бездействия, сделайте его значительно больше 15 секунд, поскольку по умолчанию Anthropic отправляет keep-alive как минимум с такой частотой.

​

Подтвердите причину по логу runner’а

1. Дождитесь истечения --startup-timeout-min, по умолчанию 15 минут. Затем runner останавливает сессию и записывает в лог строку, которая содержит no child output for и заканчивается на — releasing.
2. Найдите в логе runner’а SDKStartup: SSE. Эти строки следуют за строкой finished: interrupted, через несколько строк после строки из шага 1. У большинства из них нет временной метки, поэтому сборщик логов может показывать их в другом месте.
3. Найдите строку в этой таблице:

​

Остановите повторные попытки сессии

​

Что дальше

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