자체 호스팅 환경에서 세션 사용자 정의

​

래퍼 스크립트

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

​

설정되지 않을 수 있는 변수에 기본값 지정

​

스크립트가 확장하는 인수와 변수를 따옴표로 묶기

• 인수: "$@"로 그대로 전달하세요
• 변수: "${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}"와 같이 각 변수를 따옴표로 묶으세요. 예를 들어 Slack 스레드 링크에는 ? 및 &가 포함될 수 있습니다.
• eval 및 sh -c 문자열: 따옴표 안이라도 eval 또는 sh -c가 실행하는 문자열에 값을 치환하지 마세요. 대신 해당 문자열이 변수를 참조하도록 하세요.

​

stdin 및 파일 디스크립터 3을 연결된 상태로 유지

exec 9<&0   # the runner uses 3, and from v2.1.309 reserves 4 and 5
"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&9 9<&- &
CHILD=$!
trap 'teardown' EXIT
wait "$CHILD"

• 파일 디스크립터 3: 자식의 활동 신호를 러너에 전달합니다. 래퍼에서 이를 닫거나 재사용하지 마세요.
• 파일 디스크립터 4 및 5: Claude Code v2.1.309 이상의 러너는 이를 자식용으로 예약합니다. 래퍼에서 이를 닫거나 재사용하지 마세요. 래퍼가 둘 중 하나를 사용하는 경우(예: stdin 저장) 해당 용도를 6에서 9 사이의 디스크립터로 옮기세요. 이 범위는 이전 버전에서도 비어 있습니다.
• stderr: 래퍼 또는 자식이 0이 아닌 값으로 종료되면 러너는 stderr의 마지막 줄을 세션에 게시하고 자체 로그에 출력합니다. 세션 사용자가 해당 줄을 보게 되므로 stderr에 비밀을 출력하지 말고, 래퍼를 배포하기 전에 set -x를 제거하세요. stderr를 리디렉션해도 세션은 계속 실행되지만, 러너는 종료 코드만으로 실패를 보고합니다.

​

시스템 프롬프트 플래그 전달

• 그대로 전달: exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"로 래퍼를 종료하면 파일 플래그가 다른 모든 인수와 함께 전달됩니다. 이를 제거하거나 다시 작성하지 마세요. 세션에서 프롬프트 파일 플래그가 누락되면 제어 평면이 해당 세션에 보낸 지침 없이 실행됩니다.
• v2.1.281 이상의 러너에서는 추가한 파일 플래그가 서버의 플래그에 더해지지 않고 이를 대체함: 각 프롬프트 파일 플래그는 단일 값을 받으며 Claude Code는 마지막 항목을 유지하므로, "$@" 뒤에 --append-system-prompt-file <path>를 추가하면 해당 파일의 내용이 서버의 추가 지침을 대체합니다. 서버의 지침 위에 지침을 추가하려면 러너 이미지의 CLAUDE.md에 넣으세요. 러너는 이를 모든 세션의 사용자 수준 구성에 시드합니다.

​

세션 시작 시 Argument list too long 해결

Session <id> finished: failed — reason: child exited 126: /opt/wrapper.sh: line 9: /usr/local/bin/claude: Argument list too long

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --append-system-prompt "$(cat /opt/team-instructions.md)"

​

세션 작성자로 범위가 지정된 자격 증명 프로비저닝

#!/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" "$@"

​

라이프사이클 훅

​

checkout

​

훅에서 git 자격 증명 얻기

• 세션별 clone 자격 증명: 서비스에서 토큰 검증하기에 설명된 대로, 표준 JWT 라이브러리를 사용하여 CLAUDE_RUNNER_API_BASE_URL 아래의 JWKS 엔드포인트에 대해 CLAUDE_CODE_SESSION_ACCESS_TOKEN을 검증합니다. 그런 다음 자격 증명 서비스가 토큰의 act 클레임에 있는 ID에 대해 수명이 짧은 clone 자격 증명을 발급하도록 합니다. 해당 자격 증명은 act.sub를 키로 사용하고, act.email을 요구하지 마십시오.
• 호스트 git 인증: SSH 에이전트, 자격 증명 헬퍼 또는 .netrc와 같이 호스트에 이미 있는 git 인증을 사용합니다.

​

훅이 실패하는 경우

• 세션이 결과를 push하는 저장소: 러너는 세션을 실패 처리하며, 0이 아닌 코드로 종료된 경우 스크립트 stderr의 마지막 부분을 사용자에게 표시합니다. 실패 이유를 짧은 한 줄로 stderr에 마지막으로 기록한 다음 0이 아닌 코드로 종료하십시오. stderr에 비밀 정보를 출력하지 말고, 훅을 배포하기 전에 set -x를 제거하십시오. 훅 stderr의 마지막 약 4 KB 안에 git의 couldn't find remote ref가 나타나면 러너는 대신 브랜치가 삭제되었다고 보고합니다. 그러면 세션의 오류 메시지는 해당 브랜치가 원격에 더 이상 존재하지 않는다고 알리고 사용자에게 브랜치를 복원하도록 요청합니다. 해당 브랜치가 존재한다면 세션이 no longer exists on the remote 또는 couldn't find remote ref로 실패하는 경우를 참조하십시오.
• 세션이 읽기만 하는 저장소(예: 실행 중인 세션에 추가된 저장소): 러너는 해당 저장소를 건너뛰고 나머지 저장소로 계속 진행합니다. 러너는 세션에 Skipped 단계를 게시하고 훅이 체크아웃 경로에 남긴 내용을 제거합니다. Skipped 단계에 checkout 훅이 언급되어 있으면 러너 로그의 [runner:warn] checkout hook failed 줄에서 실패 세부 정보를 확인하십시오. 단계에 소스 ref가 no longer exists on remote라고 표시되면 세션이 no longer exists on the remote 또는 couldn't find remote ref로 실패하는 경우를 참조하십시오. 건너뛴 결과 세션에 저장소가 하나도 남지 않으면 러너는 결국 세션을 실패 처리합니다.

​

post-session

• completed: 세션이 정상적으로 종료되었습니다. Claude Code 프로세스가 정상 종료되었거나, 세션이 보관 또는 삭제된 후 스스로 종료되었습니다.
• failed: Claude Code 프로세스가 충돌했거나, 프로세스 시작 후 설정이 실패했습니다.
• interrupted: 러너가 다음 중 한 가지 경우로 세션을 중지했습니다.
  • 러너가 슬롯을 비우기 위해 세션을 해제했습니다.
  • 세션이 시작 시 시간 초과되었습니다.
  • 서버가 세션을 이 러너에서 다른 곳으로 옮겼습니다.
  • 프로세스가 종료되기 전에 러너의 폴링이 보관 또는 삭제를 감지했습니다.
  • 러너가 드레이닝 중이었습니다.
  • 세션이 --kill-session-after-min 제한을 초과했습니다.
• abandoned: 다른 러너가 가져간(claim한) 세션을 위해 예약된 값입니다. 현재 해당 경우에는 훅이 실행되지 않습니다.

#!/usr/bin/env bash
set -u
export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
IFS=':'
# -c overrides beat repo-local settings, blocking session-written fsmonitor,
# hook-path, and gpg-program config from executing code with the hook's
# privileges. -c commit.gpgsign=false also leaves these rescue commits
# unsigned under --configure-git.
# Repo-local credential.helper and pushurl still apply, and on a runner
# before v2.1.280 so does core.sshCommand; see the note below the script
# before you give this push a credential.
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

​

러너가 세션을 해제할 때의 훅 실행 시점

• 턴 이후 유휴 상태이거나 시작 시 시간 초과된 경우: 러너는 자식 프로세스를 중지하고 이 훅을 끝까지 실행합니다. 그 후에야 세션을 해제합니다. 훅이 실행되는 동안 보낸 사용자 메시지는 훅이 끝나기 전에 다른 러너에서 세션을 재개할 수 없습니다.
• 권한 프롬프트와 같은 프롬프트에 사용자가 응답하기를 기다리는 경우: 러너는 먼저 세션을 해제한 다음 이 훅을 실행합니다. 훅이 실행되는 동안 보낸 사용자 메시지는 훅이 끝나기 전에 다른 러너에서 세션을 재개할 수 있습니다.

​

라이프사이클 훅 내부의 git 구성

• Git 훅: 사용자가 값을 제공하지 않으면 core.hooksPath는 /dev/null이므로, git은 저장소의 .git/hooks에 있는 훅과 ~/.gitconfig가 지정하는 모든 hooks 디렉터리를 건너뜁니다. 값을 제공하려면 러너 환경에서 core.hooksPath를 GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n 쌍으로 export하십시오. 러너는 시스템 git 구성에서도 core.hooksPath를 읽지만, 러너의 사용자가 해당 파일, 그 파일이 지정하는 디렉터리, 또는 그 안의 훅 파일에 쓸 수 없는 경우에만 사용합니다. 러너가 값을 무시하면 시작 시 [runner:warn] 줄에 해당 값과 이유가 표시됩니다.
• 파일 시스템 모니터: core.fsmonitor가 비어 있으므로, 훅 안의 git은 설정 파일이 지정한 모니터 프로그램을 실행하지 않습니다.
• 원격 프로토콜: GIT_ALLOW_PROTOCOL은 https:http:ssh입니다. 로컬 경로, file:// URL 또는 git:// URL을 사용하는 clone, fetch, push는 fatal: transport 'file' not allowed 또는 fatal: transport 'git' not allowed로 실패합니다.
• SSH 명령 및 자격 증명 프롬프트: 훅 안의 git은 설정 파일의 core.sshCommand와 core.askPass를 무시합니다. 자체 SSH 명령을 사용하려면 러너 환경에 GIT_SSH_COMMAND를 설정하십시오. 자격 증명 프롬프트 프로그램을 사용하려면 같은 곳에 GIT_ASKPASS를 설정하십시오. 세션은 러너의 환경을 상속하므로 두 변수 모두 세션 자체의 git에도 전달됩니다. 둘 중 어느 것에도 자격 증명을 넣지 마십시오.
• gpg 프로그램: gpg.program, gpg.openpgp.program, gpg.x509.program, gpg.ssh.program은 러너가 설정하는 경로이며, 설정 파일의 값은 절대 사용되지 않습니다.
• 커밋 서명: --configure-git을 사용하면 훅에서 만든 커밋은 세션으로서 서명됩니다. 이 플래그가 없으면 commit.gpgsign과 tag.gpgsign은 false입니다.

• 구성 쌍: 러너 환경에서 export한 GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n 쌍은 같은 키에 대한 러너의 값을 대체합니다. 쌍의 번호는 0부터 매기고 GIT_CONFIG_COUNT를 쌍의 개수로 설정하십시오. count가 알리는 마지막 쌍이 없으면 러너는 사용자의 모든 쌍을 무시하고 시작 시 [runner:warn] 줄을 로그에 기록합니다.
• Git 환경 변수: 러너는 GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND, GIT_ASKPASS를 러너 환경에 설정한 그대로 둡니다.
• git -c 옵션: 훅 안의 git -c 옵션은 러너의 것이든 사용자의 것이든 GIT_CONFIG_KEY_n 쌍을 재정의합니다. 그러나 git이 모든 구성보다 먼저 읽는 GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND, GIT_ASKPASS는 변경하지 않습니다.

​

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를 제출하는 워크로드(예: 스폰된 Job의 Kubernetes Secret)에 복사하고, 파일 경로를 전달하지 마십시오.
• 스폰된 러너에서 --capacity 1을 사용합니다: 세션 바운드 작업 지시서는 정확히 하나의 러너를 해당 세션에 바운드하여 등록하므로, 더 높은 용량은 작업을 받지 않는 슬롯을 추가하며, 러너는 시작 시 경고를 로깅합니다.
• 사전 워밍 작업 지시서는 언바운드로 등록합니다: 대기 중인 러너는 세션에 바운드되지 않으며 고정 플릿 러너처럼 대기 중인 작업을 클레임합니다.

1. CLAUDE_RUNNER_ORDER_ID에서 멱등성을 유지합니다. 동일한 요청의 재전달은 최대 하나의 러너를 스폰해야 합니다. 주문 ID에서 결정론적 리소스 이름을 파생시키고 플랫폼이 중복을 거부하도록 합니다. 대신 CLAUDE_RUNNER_SESSION_ID를 키로 사용하지 마십시오. 세션의 모든 재요청은 새 주문 ID와 함께 동일한 세션 ID를 전달합니다. 세션 ID로 이름을 짓거나 중복 제거한 워크로드는 첫 번째 워크로드가 존재하는 동안 다시 생성되지 않습니다.
2. 워크로드를 재시도하지 마십시오. 하나의 주문 ID는 최대 하나의 생성된 워크로드를 의미합니다. 러너가 등록되지 않으면 Anthropic은 --expected-spawn-seconds 후 새 주문 ID로 재요청합니다.
3. 종료 코드 계약을 사용합니다. 결과에 맞는 상태로 종료합니다:
   • 종료 0: 제출됨.
   • 종료 1, 또는 --hook-timeout이 끝날 때 여전히 실행 중: 재시도 가능한 실패. 세션은 백오프되고 다시 제공됩니다. 연속으로 10번 요청이 실패하면 종료 2 이상일 때와 마찬가지로 차단됩니다.
   • 종료 2 이상: 재시도 불가능한 실패. 사용자가 세션에 새 메시지를 보내거나 Owner가 환경의 Activity 탭에서 해당 세션의 Retry를 선택할 때까지 세션은 다시 스폰되지 않습니다.
   세션이 백오프되는 동안에는 Activity 탭에 스폰 오류 없이 Queued로 표시되므로, 오케스트레이터의 로그에서 훅의 출력을 확인하십시오. 차단되면 세션은 Failed로 표시됩니다. 세션을 확장하면 훅 stderr의 마지막 512자에서 가져온 스폰 오류를 확인할 수 있습니다. stderr에는 조치 가능한 오류를 작성하고 시크릿은 작성하지 마십시오. 셸 훅에서는 일시적인 실패를 재시도 가능한 상태로 유지하십시오. 사전 워밍 요청의 경우 실패할 세션이 없습니다: 오케스트레이터는 0이 아닌 종료를 로컬에만 로깅하고, 서버는 --expected-spawn-seconds 리스가 만료된 후 스폰을 재요청합니다.
4. --expected-spawn-seconds를 최소한 스폰 요청부터 러너 등록까지의 p99 시간으로 설정합니다. 오케스트레이터가 스폰 요청을 받은 시점부터 측정하고, 부팅 시간뿐 아니라 플랫폼에서 용량을 기다리는 시간도 포함하십시오. 이 값은 서버 측 리스이며 작업 지시서도 함께 만료되므로, 워크로드가 이보다 오래 걸리는 러너는 등록할 수 없습니다. 모든 오케스트레이터 복제본은 동일한 값을 사용해야 합니다.

​

다시 연 세션이 Queued 상태로 유지되거나 Failed로 표시되는 문제 해결하기

name="runner-${CLAUDE_RUNNER_SESSION_ID}"

1. 세션의 첫 번째 스폰 요청에서 훅은 해당 이름으로 워크로드를 생성하고 러너가 시작됩니다
2. 러너가 종료되고(예: --release-idle-session-min 이후), 나중에 사용자가 세션을 다시 엽니다
3. 세션의 다음 스폰 요청은 동일한 세션 ID와 새 주문 ID를 전달하므로 훅은 같은 이름을 만듭니다
4. 러너가 종료될 때 아무것도 첫 번째 요청의 워크로드를 제거하지 않아 플랫폼에 해당 워크로드가 여전히 남아 있다면, 훅은 새 워크로드를 생성하지 않고 러너도 시작되지 않습니다
5. 이후 해당 세션의 모든 스폰 요청이 같은 방식으로 끝납니다

name="runner-${CLAUDE_RUNNER_ORDER_ID}"

• Queued: 세션이 자동으로 다음 스폰 요청을 받습니다
• Failed: Owner로서 해당 세션의 Retry를 선택하거나, 세션의 사용자가 새 메시지를 보내도록 하십시오

​

유휴 상태일 때 온디맨드 러너 종료하기

​

백그라운드 프로세스의 출력을 파일로 보내기

your-background-command >> "$HOME/claude-runner.log" 2>&1 &

• 훅이 종료되고 약 1초 후 오케스트레이터는 exited, but a process it started still has the hook's stdout or stderr open을 로그에 기록합니다. 그 줄 이후로는 해당 출력을 [runner:hook:spawn-runner:after-exit jti=<order id>] 아래에 최대 64KB까지 더 기록한 다음 나머지는 버립니다.
• 오케스트레이터가 종료되면 프로세스가 그곳에 쓰는 작업은 실패합니다.

• Activity 탭, 실패한 세션의 스폰 오류: spawn-runner hook timed out after 60000ms 또는 훅 stderr의 마지막 줄들.
• 오케스트레이터 로그: timed out after 60000ms, sending SIGTERM to process tree.

​

러너를 기다리지 않고 훅 종료하기

• 타임아웃이 러너를 중지시키는 원인인지 확인하려면: 오케스트레이터의 로그에서 모든 스폰 요청마다 timed out after 60000ms, sending SIGTERM to process tree가 있는지 확인하십시오. 60000은 밀리초 단위의 --hook-timeout 값입니다.
• 해결하려면: 훅이 러너를 플랫폼에 제출하고 0으로 종료하도록 하십시오. 대신 --hook-timeout을 늘리면 러너가 더 나중에 중지될 뿐입니다.

​

셸 훅에서 일시적인 실패를 재시도 가능한 상태로 유지하기

set -e
PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }
trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

• 단독 exit 2 이상: trap이 설정되면 종료 1이 됩니다. 어떤 재시도로도 해결할 수 없는 오류의 경우 대신 permanent "namespace claude-runners does not exist"처럼 이유와 함께 permanent를 호출하십시오. $( ), ( ) 또는 파이프 내부가 아닌 메인 셸에서 호출하십시오.
• exec: exec는 셸을 대체하여 trap이 실행되지 않으므로, 훅의 마지막 명령을 exec로 시작하지 마십시오.
• 두 번째 EXIT trap: 두 번째 trap ... EXIT는 첫 번째를 대체하므로 두 trap을 하나로 병합하십시오. 정리 명령을 rc=$?; 바로 뒤에 넣고 각각을 || true;로 끝내십시오. 그러면 정리 작업이 성공 시뿐 아니라 실패 시에도 실행되며, 정리 명령이 실패해도 훅의 종료 상태가 설정되지 않습니다. 다음 병합된 trap은 그 형태를 보여 주며, your-cleanup-command는 사용자 자신의 명령을 나타냅니다:
  trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
  
• 실패해도 되는 명령: 훅이 이전에 set -e를 사용하지 않았다면, 이제 아무것도 찾지 못한 조회처럼 0이 아닌 값을 반환하는 첫 번째 명령에서 멈춥니다. 훅이 결과에 따라 동작한다면 해당 명령을 if의 조건으로 만드십시오. 결과를 무시한다면 명령 뒤에 || true를 붙이십시오.
• 워크로드를 제출하는 명령: 이 명령 뒤에는 || true를 붙이지 마십시오. || true를 붙이면 할당량 초과 등으로 플랫폼이 제출을 거부하더라도 훅이 0으로 종료하며, 세션은 시작되지 않은 러너를 계속 기다리게 됩니다. 훅의 첫 번째 규칙에 따라 워크로드 이름을 CLAUDE_RUNNER_ORDER_ID를 기준으로 지정하십시오. 그러면 이미 존재한다는 응답은 동일한 요청의 재전달이므로, 그 응답만 성공으로 처리하십시오. 그 밖의 응답은 stderr에 출력하고 종료 1로 종료하거나, 어떤 재시도로도 해결할 수 없다면 permanent를 호출하십시오. 다음 예시는 워크로드만 담은 job.yaml을 사용하여 kubectl create에 대해 이를 수행합니다:
  if ! out=$(kubectl create -f job.yaml 2>&1); then
    case "$out" in
      *AlreadyExists*) ;;
      *) printf '%s\n' "${out:-kubectl create failed}" >&2; exit 1 ;;
    esac
  fi
  
  그러면 오케스트레이터의 로그에 해당 메시지가 표시됩니다. 훅이 다른 객체도 생성한다면 각 객체의 이름을 주문 ID를 기준으로 지정하고, 각각에 별도의 명령을 사용하며, 이미 존재한다는 응답을 같은 방식으로 성공으로 처리하십시오. 시크릿을 담는 객체의 경우 명령의 출력 대신 고정된 메시지를 출력하십시오.

​

Bedrock 또는 Agent Platform으로 모델 요청 보내기

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

env | grep -E 'CLAUDE_CODE_USE_(BEDROCK|VERTEX)'

​

Anthropic API 세션과 달라지는 점

• claude.ai의 정책: 서버 관리형 설정은 이러한 세션에 도달하지 않습니다. Owner가 Claude Code 관리자 설정에서 지정하는 조직 정책도 도달하지 않으므로, Claude Code는 세션 내에서 이를 적용하지 않습니다. 의존하는 규칙은 러너 이미지의 관리형 설정 파일에 넣으십시오.
• 계정 스킬: 이러한 세션은 개인의 claude.ai 계정에서 활성화된 스킬을 다운로드하지 않습니다. 각 세션의 구성이 조합되는 방식을 참조하십시오.
• 파일: claude.ai나 모바일 또는 데스크톱 앱에서 세션에 첨부한 파일은 세션에 도달하지 않으며, Claude는 SendUserFile 도구로 파일을 다시 보낼 수 없습니다. 대신 입력 파일을 저장소나 러너에 두십시오.
• 모델 선택: Anthropic의 컨트롤 플레인이 각 세션의 모델을 전송하며, 모델 없이 세션이 시작되면 Claude Code는 해당 제공업체의 기본값을 사용합니다. 러너 환경의 ANTHROPIC_MODEL이나 ANTHROPIC_DEFAULT_MODEL로는 모델을 선택할 수 없지만, 별칭이 무엇으로 해석되는지는 고정할 수 있습니다.
  • ANTHROPIC_MODEL 및 ANTHROPIC_DEFAULT_MODEL: 제공업체 페이지의 예시에서는 ANTHROPIC_MODEL을 설정하지만, 러너는 세션에 전달하는 환경에서 이 두 변수를 제거합니다.
  • 모델 계열별 고정 변수: Amazon Bedrock 및 Agent Platform의 모델 버전 고정에 나오는 변수는 세션에 도달합니다. 이 변수는 opus 같은 별칭이 무엇으로 해석되는지를 결정하며, 전체 모델 ID가 무엇으로 해석되는지는 결정하지 않습니다.
• 계정에서 제공하지 않는 모델: 세션이 모델 이름이 포함된 오류와 함께 메시지에서 실패할 수 있습니다. 개발자가 선택할 수 있는 모델, 모델 버전 고정에 설명된 백그라운드 모델, 자동 모드가 사용하는 분류기 모델을 활성화하십시오. Amazon Bedrock에서는 정책에서 각 모델을 허용하십시오.
• 웹 검색 및 빠른 모드: 웹 검색은 Amazon Bedrock에서 사용할 수 없으며, 빠른 모드는 두 제공업체 모두에서 사용할 수 없습니다. 제공업체에 따라 달라지는 기타 기능은 제공업체별로 달라지는 CLI 기능을 참조하십시오.

​

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 파일: Linux 러너 호스트에서는 /etc/claude-code/managed-mcp.json, macOS 호스트에서는 /Library/Application Support/ClaudeCode/managed-mcp.json입니다. 관리자가 나열한 서버만 로드할 수 있도록 잠긴 플릿에 사용합니다. 우선순위 규칙은 managed-mcp.json을 통한 배타적 제어를 참조하세요. 이 파일이 러너 호스트에 있으면 Claude Code는 claude.ai 커넥터를 포함하여 Anthropic의 컨트롤 플레인이 세션에 전달하는 MCP 서버를 건너뛰고, 세션 자식 프로세스의 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: 프로젝트 범위입니다. 프로젝트 스레드 외부에서는 파일을 저장소에 커밋하면 해당 서버가 클라우드 세션에서 자동 승인됩니다. 여러 저장소가 있는 세션에서는 최대 하나의 저장소 파일만 로드됩니다.
• 래퍼 스크립트에서 지정하는 --mcp-config 파일: exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json과 같이 "$@" 뒤에 플래그를 덧붙입니다. 세션 도중 세션에 전달된 서버가 업데이트될 때 이 파일의 서버가 계속 실행되도록 하려면, exec처럼 래퍼가 전체 환경을 자식 프로세스에 전달하도록 합니다. v2.1.299 이전에는 이 파일의 stdio, HTTP, SSE 서버가 해당 서버를 명시하지 않은 첫 번째 업데이트 시점에 종료되었습니다.

​

첫 턴 전에 MCP 서버 대기하기

• 세션 시작: 도구 목록을 처음 가져오기 전에, 세션은 항목에 alwaysLoad: true를 설정한 HTTP 또는 SSE 서버를 기본적으로 최대 5초 동안 기다리며, 러너 환경에서 MCP_CONNECTION_NONBLOCKING=0을 설정한 경우에는 모든 서버를 기다립니다. 그 외의 경우 HTTP 및 SSE 서버는 백그라운드에서 연결됩니다. 세션이 여기서 대기하는 동안에는 초기화가 느려집니다. MCP_CONNECT_TIMEOUT_MS로 5초 기본값을 변경할 수 있습니다.
• 첫 턴: 메시지가 도착한 후, 첫 턴은 아직 연결 중인 stdio 서버를 최대 2초 동안 기다립니다. 세션이 여기서 대기하는 동안에는 첫 응답이 느려집니다. 이 대기 시간을 변경하려면 러너 환경에서 CLAUDE_CODE_MCP_STARTUP_WAIT_MS를 설정합니다. 이 설정은 대기 대상 서버를 변경하지 않습니다. Claude Code v2.1.274 이상이 필요합니다.

RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user

​

기본 제공 세션 도구 끄기

{
  "permissions": {
    "deny": [
      "mcp__Claude_Code_Remote",
      "mcp__claude-code-remote",
      "mcp__bf7c680d-5fdc-5ef4-b4a0-abadb619bf0a"
    ]
  }
}

​

세션에 작업 푸시 프롬프트

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

#!/bin/sh
# 자체 호스팅 러너용 Stop 훅 참조 구현입니다.
#
# 프로젝트 디렉토리에 커밋되지 않은 변경 사항 또는 푸시되지 않은 커밋이 있으면
# 턴당 한 번 Claude에 프롬프트하므로 유휴 세션이 해제될 때 작업이 손실되지 않고
# claude.ai/code의 "Create PR" 버튼이 켜집니다.
#
# 러너 수준(저장소 변경 없음): 이 파일을 러너 호스트의 ~/.claude/hooks/에 놓고
# 함께 제공되는 Stop 훅 설정 블록을 ~/.claude/settings.json에 병합합니다.
# 러너가 둘 다 모든 세션에 시드합니다.
# 저장소 수준 대안: <repo>/.claude/hooks/에 커밋하고 settings.json 명령 경로를
# $CLAUDE_PROJECT_DIR/.claude/hooks/로 변경합니다.
#
# stdin: 훅 JSON 페이로드 (https://code.claude.com/docs/en/hooks 참조)
# stdout: {"decision":"block","reason":"..."} 프롬프트하거나 중지를 허용하려면 아무것도 없음.

# 재진입 가드: 하네스는 블록 후 Stop 훅을 다시 호출할 때 stop_hook_active=true를
# 설정합니다. 종료하므로 턴당 한 번만 프롬프트합니다. 하네스는 컴팩트 JSON을 내보내며
# (콜론 뒤에 공백 없음), 이 패턴은 이에 의존합니다. 공백 허용 검사가 필요하면 jq를 사용하세요.
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# 강화: 이 스크립트는 Claude Code의 Bash 샌드박스 외부에서 실행되므로, git 호출은
# 체크아웃의 git 설정에 지정된 프로그램을 시작할 수 있는 일부 기능을 건너뜁니다.
# 모두 건너뛰지는 않으므로 샌드박스에만 의존하지 마세요.
GIT_OPTIONAL_LOCKS=0
export GIT_OPTIONAL_LOCKS
git() { command git -c core.fsmonitor= -c core.hooksPath=/dev/null "$@"; }

# git 저장소가 아님 → 프롬프트할 것이 없습니다.
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# 원격이 없음 → "원격으로 푸시"는 불가능합니다. 종료합니다.
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# 커밋되지 않은 변경 사항 (스테이징됨, 스테이징되지 않음 또는 추적되지 않음).
# .claude/ 전체를 제외합니다 — 운영자가 시드한 설정과 CLI가 작성한 런타임 상태
# (스케줄러 잠금, worktree, 루틴 상태)가 그곳에 있으며, 둘 다 모델이 푸시해야 하는
# "커밋되지 않은 작업"이 아닙니다.
s=$(git -C "$d" status --porcelain --ignore-submodules=dirty -- . ':(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

# 푸시되지 않은 커밋. 모든 원격 추적 ref 또는 FETCH_HEAD에서 도달할 수 없는
# HEAD의 커밋 수를 계산합니다. 이는 다음에 대해 균일하게 작동합니다:
#   - init+fetch 체크아웃 (러너 기본값: FETCH_HEAD만 존재)
#   - 복제 기반 체크아웃 (origin/* 존재)
#   - 러너 기본값: 자식이 세션의 결과 브랜치에서 시작하며,
#     러너가 체크아웃 후 이 브랜치를 생성합니다.
#   - 분리된 HEAD, 사용자 정의 설정이 해당 브랜치 생성을 건너뛸 때
# 참조 지점이 전혀 없으면 (한 번도 페치되지 않음) 읽기 전용 턴에서
# 거짓 양성을 피하기 위해 아무것도 출력하지 않습니다.
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는 "" 또는 "FETCH_HEAD"이며 의도적 단어 분할입니다.
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는 공격자의 영향을 받을 수 있습니다 — git-check-ref-format(1)은 ref 이름에
    # `"`를 허용합니다. `\`는 금지되지만 (규칙 10) 저렴한 심층 방어로 어쨌든 이스케이프합니다.
    # 직접 구성한 페이로드에 보간하기 전에 JSON 메타문자를 이스케이프하므로
    # x","continue":false와 같은 브랜치가 하네스가 구문 분석하는 훅 출력 JSON에
    # 키를 주입할 수 없습니다. $unpushed는 안전합니다 — 위의 -gt 가드가
    # 일반 정수가 아닌 모든 것을 거부합니다.
    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

• git ID: 러너 이미지에서 user.name과 user.email을 설정하거나, --configure-git으로 러너를 시작합니다
• 푸시 자격 증명: Anthropic 관리형 git을 사용하거나, 이미지에 git 구성 포함에 설명된 대로 자격 증명을 제공합니다
• 재개된 세션의 경우: 환경의 모든 러너에 --push-outcome-on-release를 설정합니다. 그러면 재개된 세션은 Claude가 세션의 브랜치에 푸시한 커밋에서 시작합니다. 이 플래그의 제한 사항은 재개된 세션에서 푸시되지 않은 작업이 손실됨을 참조하세요.

​

서브모듈과 Stop 훅

• 서브모듈의 새 커밋: .gitmodules에서 해당 서브모듈에 ignore = all을 설정하더라도, 상위 저장소가 이를 기록할 때까지 Claude에 프롬프트합니다
• 서브모듈의 커밋되지 않은 파일: Claude에 프롬프트하지 않으므로 해당 작업은 러너의 디스크에만 남습니다
• 서브모듈의 푸시되지 않은 커밋: Stop 훅은 푸시 여부를 확인하지 않으므로, 상위 저장소가 다른 누구도 페치할 수 없는 커밋을 가리킬 수 있습니다

​

이전 버전의 Stop 훅 스크립트 교체

• 시기: 세션이 Bash 샌드박스를 켠 상태로 실행된다면 지금 교체합니다. 그렇지 않다면 다음 이미지 빌드나 러너 재시작 시 교체합니다.
• 변경 사항: 서브모듈의 커밋되지 않은 파일은 더 이상 Claude에 프롬프트하지 않습니다. .gitmodules에서 ignore = all로 표시된 서브모듈의 새 커밋은 이제 프롬프트합니다.

​

권한 및 도구 승인

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

​

각 세션의 구성이 조합되는 방식

• 프로젝트 설정: 프로젝트 스레드 외부에서는 저장소에 커밋된 .claude/settings.json이 사용자 수준 기준선 위에 계층으로 적용됩니다. 여러 저장소가 있는 세션에서는 최대 하나의 저장소 파일만 적용됩니다.
• 관리형 설정: 세션은 러너 이미지의 표준 시스템 경로에서 managed-settings.json을 읽습니다. 해당 키가 서버 관리형 설정과 함께 적용되는지 여부는 Claude Code가 관리형 소스를 결합하는 방식을 참조하십시오.

• 설치 위치: 러너는 제공된 각 훅 스크립트를 세션 설정 디렉터리의 예약된 hooks/.ccr-launcher/ 하위 디렉터리에 작성하고, --settings로 세션에 전달하는 별도의 설정 파일에 스크립트를 등록합니다. 이때 초기화된 settings.json과 hooks/<name>에 있는 사용자 자신의 스크립트는 변경되지 않습니다. 러너는 세션마다 예약된 하위 디렉터리를 다시 생성하며, ~/.claude/hooks/.ccr-launcher/에 있는 호스트 콘텐츠를 세션으로 초기화하지 않습니다.
• 작성 주체: 컨트롤 플레인은 세션별 입력이나 서드 파티 입력이 아닌, 자체 배포의 고정된 상수로 스크립트를 채웁니다.
• 여전히 적용되는 제어: --settings를 통해 전달된 훅은 관리형 계층이 아닌 일반적인 병합 훅 구성에 포함되므로, 관리형 설정이 여전히 적용됩니다. disableAllHooks는 이 훅을 비활성화하며, 이 훅은 allowManagedHooksOnly가 계속 로드하는 범주에 속하지 않습니다.

​

서버 관리형 설정을 가져오지 못한 세션 중지

• Claude Tag 채널 세션: Owner가 Claude Tag 채널을 라우팅하는 환경의 러너에서는 이 키를 넣지 마십시오. Anthropic API는 이러한 세션의 서버 관리형 설정 요청을 거부하므로, 키가 설정되어 있으면 세션이 시작되지 않습니다. 이러한 세션의 규칙은 러너 이미지의 managed-settings.json에 넣으십시오. 이 세션은 해당 파일을 여전히 읽습니다. 다른 세션에 이 키를 사용하려면 해당 세션을 별도의 환경에서 실행하십시오.
• Bedrock 또는 Agent Platform: 이러한 제공자의 세션은 서버 관리형 설정을 가져오지 않으므로, 키 설정 여부와 관계없이 시작됩니다. 대신 동일한 managed-settings.json에서 규칙을 적용하십시오.

{
  "forceRemoteSettingsRefresh": true
}

​

여러 저장소가 있는 세션의 저장소 설정

• 기본값인 --capacity 1과 기본 제공 체크아웃 사용 시: 세션은 저장소 목록의 첫 번째 저장소에서 시작됩니다. 해당 저장소의 .claude/settings.json이 프로젝트 설정으로 적용되고 .mcp.json이 로드되며, 다른 저장소의 파일은 적용되거나 로드되지 않습니다.
• 1보다 큰 --capacity 또는 checkout 훅 사용 시: 세션은 체크아웃이 포함된 세션별 디렉터리에서 시작됩니다. 어떤 저장소의 .claude/settings.json도 프로젝트 설정으로 적용되지 않고, 어떤 저장소의 .mcp.json도 로드되지 않으며, 훅 명령의 $CLAUDE_PROJECT_DIR은 체크아웃이 아닌 해당 디렉터리가 됩니다.

​

저장소에 커밋된 권한 규칙

​

다음 단계

• 참조: 모든 CLI 플래그, 환경 변수 및 메트릭
• 세션 ID 확인: 러너 외부 서비스에서 세션 토큰 검증