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

​

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

claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --exec-path /etc/claude/session-wrapper.sh

​

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

exec 4<&0
"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&4 4<&- &
CHILD=$!
trap 'teardown' EXIT
wait "$CHILD"

​

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

#!/bin/bash
# Key on the stable Anthropic user ID and require a human creator.
CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \
  | jq -re '.act.sub // "" | select(startswith("user:"))') \
  || { echo "decode-token: verification failed or no human creator" >&2; exit 1; }

creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \
  || { echo "credential exchange failed" >&2; exit 1; }
eval "$creds"

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"

​

Lifecycle hooks

​

checkout

• Репозиторий, в который сессия отправляет результаты: runner отмечает сеанс как неудачный, и при ненулевом выходе выводит пользователю конец stderr скрипта.
• Репозиторий, из которого сессия только читает, такой как репозиторий, добавленный к запущенной сессии: runner логирует строку [runner:warn] с деталями отказа, отправляет шаг Skipped в сессию, удаляет всё, что hook оставил в пути проверки, и продолжает с оставшимися репозиториями. Когда runner не может немедленно удалить путь, он повторяет удаление в конце сессии. Если пропуск оставляет сессию вообще без репозитория, runner отмечает сеанс как неудачный в любом случае.

​

post-session

• completed: сессия завершилась чисто. Процесс Claude Code завершился нормально, или сессия была архивирована или удалена, пока она всё ещё работала.
• failed: процесс Claude Code упал, или настройка не удалась после его запуска.
• interrupted: runner остановил сессию. Он освободил сессию, чтобы освободить слот, сессия истекла при запуске, сервер переместил сессию с этого runner’а, runner был в режиме дренирования, или сессия превысила свой лимит --kill-session-after-min.
• abandoned: зарезервировано для сессии, которую заявил другой runner. Hook в настоящее время не срабатывает в этом случае.

#!/usr/bin/env bash
set -u
IFS=':'
# Pin config the session could have planted in the checkout's .git/config:
# -c overrides beat repo-local settings, blocking session-written fsmonitor,
# hook-path, and gpg-program config from executing code with the hook's
# privileges. Repo-local credential.helper, core.sshCommand, and pushurl
# still apply; if the hook holds credentials the session didn't, pin the
# push URL and helper too (see the note below the script).
g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \
        -c commit.gpgsign=false "$@"; }
for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do
  cd "$ws" 2>/dev/null || continue
  [ -z "$(g status --porcelain 2>/dev/null)" ] && continue
  g add -A
  g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue
  g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true
done

​

Hook timing when the runner releases a session

• Неактивна после хода или истекла при запуске: runner останавливает дочерний процесс и запускает этот hook до завершения. Только после этого он освобождает сессию. Сообщение пользователя, отправленное во время выполнения hook’а, не может возобновить сессию на другом runner’е до завершения hook’а.
• Ожидание ответа пользователя на подсказку, такую как подсказка разрешения: runner сначала освобождает сессию, затем запускает этот hook. Сообщение пользователя, отправленное во время выполнения hook’а, может возобновить сессию на другом runner’е до завершения hook’а.

​

command

​

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

claude self-hosted-runner orchestrator \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks

​

Хук spawn-runner

• Запустите его с нарядом на работу: укажите --environment-secret-file на файл, содержащий JWT наряда на работу, или установите SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET на значение JWT.
• Скопируйте JWT перед выходом хука: оркестратор удаляет файл наряда на работу после выхода хука, поэтому скопируйте JWT в рабочую нагрузку, которую вы отправляете, такую как Kubernetes Secret на порожденном Job, вместо передачи пути файла.
• Используйте --capacity 1 на порожденных средствах выполнения: наряд на работу, привязанный к сеансу, регистрирует ровно одно средство выполнения, привязанное к этому сеансу, поэтому более высокая емкость добавляет слоты, которые никогда не получают работу, и средство выполнения логирует предупреждение при запуске.
• Нарядные работы предварительного прогрева регистрируют без привязки: резервное средство выполнения не привязано к сеансу и заявляет поставленную в очередь работу, как средство выполнения фиксированного флота.

1. Будьте идемпотентны на CLAUDE_RUNNER_ORDER_ID. Переделивка одного и того же запроса должна порождать не более одного средства выполнения. Выведите детерминированное имя ресурса из ID и позвольте вашей платформе отклонить дубликат.
2. Не повторяйте рабочую нагрузку. Один ID заказа означает не более одной созданной рабочей нагрузки. Если средство выполнения никогда не регистрируется, Anthropic повторно запрашивает с новым ID заказа после --expected-spawn-seconds.
3. Используйте контракт кода выхода. Выход 0 означает отправлено. Выход 1 означает повторяемый отказ; сеанс отступает и переоффертируется. Выход 2 или выше означает неповторяемый; сеанс блокируется от порождения снова до тех пор, пока владелец не выберет Retry на нем на вкладке Activity окружения. При ненулевом выходе хвост stderr хука появляется там как причина отказа, поэтому напишите действенную ошибку в stderr и никогда не секреты. Для запроса предварительного прогрева нет сеанса для отказа: оркестратор логирует ненулевой выход локально только, и сервер повторно запрашивает порождение после аренды.
4. Установите --expected-spawn-seconds на по крайней мере ваше время загрузки p99. Это аренда на стороне сервера. Все реплики оркестратора должны использовать одно и то же значение.

​

MCP серверы

RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar
RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080

• Файл MCP управляемый на уровне предприятия по его стандартному системному пути: /etc/claude-code/managed-mcp.json на хостах средства выполнения Linux, /Library/Application Support/ClaudeCode/managed-mcp.json на хостах macOS. Используйте его для заблокированных флотов, где только серверы, указанные администратором, могут загружаться. См. exclusive control with managed-mcp.json для правил приоритета. Когда этот файл находится на хосте средства выполнения, Claude Code пропускает MCP серверы, которые плоскость управления Anthropic доставляет в сеанс, включая разъемы claude.ai, и называет их в предупреждении на stderr дочернего процесса сеанса, которое средство выполнения записывает на уровне логирования debug. До v2.1.229 эти сеансы выходили при запуске с You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• Ключ managedMcpServers в управляемых настройках на хосте средства выполнения: предоставляет HTTP и SSE серверы без принятия исключительного управления, поэтому серверы из других источников по-прежнему загружаются. Требует Claude Code v2.1.259 или позже.
• <repo>/.mcp.json: область проекта. Зафиксируйте файл в репозитории; его серверы автоматически одобрены в облачных сеансах.

​

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

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\""
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# Stop-hook reference implementation for self-hosted runners.
#
# Nudges Claude once per turn if the project directory has uncommitted
# changes OR unpushed commits, so work isn't lost when an idle session
# is released and so the "Create PR" button on claude.ai/code lights up.
#
# Runner-level (no repo changes): drop this file at ~/.claude/hooks/ on
# the runner host and merge the accompanying Stop-hook settings block
# into ~/.claude/settings.json — the runner seeds both into every session.
# Repo-level alternative: commit to <repo>/.claude/hooks/ and change the
# settings.json command path to $CLAUDE_PROJECT_DIR/.claude/hooks/.
#
# stdin: hook JSON payload (see https://code.claude.com/docs/en/hooks)
# stdout: {"decision":"block","reason":"..."} to nudge, or nothing to allow stop.

# Re-entry guard: the harness sets stop_hook_active=true when re-invoking
# the Stop hook after a block. Bail so we only nudge once per turn. The
# harness emits compact JSON (no space after the colon), which this
# pattern relies on; use jq if you need a whitespace-tolerant check.
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# Not a git repo → nothing to nudge.
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# No remote → "push to the remote" is unsatisfiable; bail.
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# Uncommitted changes (staged, unstaged, or untracked). Exclude .claude/
# entirely — operator-seeded settings and CLI-written runtime state
# (scheduler lock, worktrees, routine state) live there and neither is
# "uncommitted work" the model needs to push.
s=$(git -C "$d" status --porcelain -- . ':(exclude).claude/' 2>/dev/null)
if [ -n "$s" ]; then
  printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}'
  exit 0
fi

# Unpushed commits. Count commits on HEAD not reachable from any
# remote-tracking ref or FETCH_HEAD. This works uniformly for:
#   - init+fetch checkouts (runner default: only FETCH_HEAD exists)
#   - clone-based checkouts (origin/* exist)
#   - the runner default: the child starts on the session's outcome
#     branch, which the runner creates after checkout
#   - detached HEAD, when a custom setup skips that branch creation
# With no reference point at all (never fetched), stay silent rather
# than false-positive on a read-only turn.
base=""
git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD"
if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then
  exit 0
fi
# shellcheck disable=SC2086  # $base is either "" or "FETCH_HEAD", intentional word-split
unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0
if [ "$unpushed" -gt 0 ]; then
  branch=$(git -C "$d" symbolic-ref --short -q HEAD)
  if [ -n "$branch" ]; then
    # $branch is attacker-influenced — git-check-ref-format(1) allows `"`
    # in ref names. `\` is forbidden (rule 10) but escaped anyway as cheap
    # defense-in-depth.
    # Escape JSON metacharacters before interpolating into the hand-built
    # payload so a branch like x","continue":false can't inject keys into
    # the hook-output JSON the harness parses. $unpushed is safe — the
    # -gt guard above rejects anything that isn't a plain integer.
    branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g')
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc"
  else
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed"
  fi
  exit 0
fi

exit 0

​

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

#!/bin/bash
exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto

​

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

• Где они приземляются: средство выполнения пишет каждый предоставленный скрипт хука в зарезервированный подкаталог hooks/.ccr-launcher/ каталога конфигурации сеанса и регистрирует скрипты в отдельном файле настроек, который он передает сеансу с помощью --settings, оставляя заполненный settings.json и ваши собственные скрипты в hooks/<name> нетронутыми. Средство выполнения пересоздает зарезервированный подкаталог для каждого сеанса и не заполняет содержимое хоста в ~/.claude/hooks/.ccr-launcher/ в сеансы.
• Кто их создает: плоскость управления заполняет скрипты из фиксированных констант в своем собственном развертывании, никогда не из входных данных для каждого сеанса или третьей стороны.
• Что по-прежнему их управляет: хуки, доставленные через --settings, входят в обычную объединенную конфигурацию хука, а не в управляемый уровень, поэтому ваши управляемые настройки по-прежнему применяются. disableAllHooks отключает их, и они не входят в категории, которые allowManagedHooksOnly сохраняет загруженными.

​

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

​

Что дальше

• Reference: каждый флаг CLI, переменная окружения и метрика
• Verify session identity: проверьте токен сеанса из служб вне средства выполнения