Claude Code self-hosted environments 뜯어보기 — 러너 배포와 세션 라이프사이클

mini_knows·2026년 8월 16일

AI코딩에이전트 AI트렌드 Anthropic claudecode selfhosted 셀프호스팅

AI 트렌드·이슈

목록 보기

74/120

안녕하세요, 미니지식공간입니다.

Claude Code self-hosted environments가 2026년 8월 6일 공개 베타로 열렸다. 러너(runner)를 직접 배포해 클라우드 세션을 자기 네트워크 안에서 실행하는 구조라, CI 러너를 운영해 본 팀이라면 정신 모델이 거의 그대로 옮겨간다.

TL;DR

claude self-hosted-runner는 Claude Code v2.1.224 이상에 포함된 서브커맨드다. 별도 바이너리가 아니다.

러너는 첫 세션을 잡는 순간 그 사용자 계정에 잠기고, 기본값에서는 활성 세션이 끝나면 종료된다. 오케스트레이터 아래 두는 것이 전제다.

네트워크는 전부 아웃바운드다. 큐 폴링·이벤트 스트림·추론 모두 api.anthropic.com으로 나가고, 인바운드는 없다.

릴리스 개요

항목	내용
발표일	2026년 8월 6일 (Anthropic 공식 블로그)
상태	공개 베타(public beta), 기본 비활성
대상	Claude Team·Enterprise 조직
선행 조건	조직에 Claude Code on the web 활성화
제외	Zero Data Retention 사용 조직
러너 호스트	Linux 또는 macOS (Windows 미지원, 컨테이너로 대체)
필요 버전	Claude Code v2.1.224 이상, Git 2.24 이상
저장소	GitHub

호스트 준비와 러너 기동

문서가 제시하는 최소 경로는 네 단계다. 먼저 호스트에 서브커맨드가 있는지부터 확인한다. 2.1.224 미만 버전은 이 명령이 일반 claude --help 출력을 내놓기 때문에, 이 출력이 버전 체크를 겸한다.

claude self-hosted-runner --help

--environment-secret-file 같은 플래그가 나열된 usage 텍스트가 보이면 준비된 상태다. 안 보이면 claude update로 올리거나 latest 채널에서 재설치한다. 참고로 native installer의 latest 채널은 릴리스 즉시 반영되지만 stable 채널·Homebrew cask·apt/dnf/apk 저장소는 약 1주 뒤진다고 문서는 안내한다.

시크릿 파일은 셸 히스토리에 남지 않도록 표준 입력으로 넣는다. umask 077을 건 서브셸이라 파일은 소유자만 읽을 수 있다.

mkdir -p /etc/claude
(umask 077 && cat > /etc/claude/environment-secret)

환경 시크릿은 claude.ai 관리자 설정의 Cloud environments 페이지에서 환경을 만들 때 한 번만 보여준다. 나중에 다시 꺼낼 수 없고 생성 후 365일이 지나면 만료된다. 환경 ID는 ccpool_... 형식이며 상세 다이얼로그에서 계속 확인할 수 있다. API 필드·토큰 클레임·메트릭 이름에서는 환경이 pool, 환경 ID가 pool_id로 나타난다.

러너는 시크릿 파일과 베이스 디렉터리를 지정해 띄운다. --base-dir를 생략하면 /workspace가 쓰이는데, 그 디렉터리가 이미 존재하고 쓰기 가능하거나 러너를 root로 띄운 경우에만 동작한다.

claude self-hosted-runner \
  --environment-secret-file '/etc/claude/environment-secret' \
  --base-dir '<writable-dir>'

관리자·소유자 역할 계정으로 claude auth login을 마친 머신이라면, 가이드 세팅이 환경 생성부터 러너 등록 확인까지 대화형으로 진행하고 ./runner-setup/CHEAT-SHEET.md를 남긴다.

claude self-hosted-runner setup

세션 라이프사이클

개발자가 세션을 시작하고 우리 환경을 고르면, Anthropic 컨트롤 플레인이 그 환경의 큐에 세션을 올린다. 이후 흐름은 문서에 네 단계로 정리돼 있다.

여유 용량이 있는 러너가 세션을 클레임하고 리스(lease)를 잡는다.
러너가 작업 디렉터리에 저장소를 클론하고 자식 Claude Code 프로세스를 스폰한다.
자식 프로세스가 HTTPS로 이벤트를 스트리밍하는 동안 러너는 계속 폴링한다. 폴링이 리스를 갱신하면서 하트비트 역할을 겸한다.
러너가 약 60초간 폴링을 멈추면 서버는 세션을 다른 러너로 재큐잉한다.

러너 로그에는 Picked up session <session-id>가 활성 수·용량과 함께 찍히므로, 어느 호스트가 세션을 가져갔는지 러너 출력만으로 확인할 수 있다.

러너 라이프사이클과 종료 플래그

여기가 셀프호스팅에서 가장 헷갈리는 지점이다. 러너는 첫 세션을 잡는 순간 그 세션을 시작한 사용자 계정에 잠기고, 이후 --capacity만큼 그 계정의 세션만 동시에 돌린다. 사용자 간 체크아웃 코드가 섞이지 않는 이유가 이 잠금이다. 그래서 최소 플릿 크기는 동시에 활동할 것으로 보는 사용자 수와 같아진다.

플래그	동작
`--capacity`	잠긴 계정에 대해 동시에 처리할 세션 수
`--drain-grace-sec` (기본 `0`)	0이면 활성 세션이 끝나는 즉시 더 폴링하지 않고 종료. 양수면 그 초 동안 잠긴 계정의 큐를 계속 폴링한 뒤 종료
`--retire-at <epoch-seconds>`	신호 없이 호스트가 파괴되는 환경(스팟 회수, 샌드박스 수명 제한)에서 그 시각 몇 분 전으로 지정
`--release-idle-session-min`	유휴 세션 릴리스 경로. `--retire-at`도 같은 경로로 세션을 놓아준다

기본값 0에서 러너가 바로 종료되는 것은 의도된 설계다. 쿠버네티스 같은 오케스트레이터가 깨끗한 디스크로 다시 띄워 다음 계정을 받게 하려는 것이다. SIGTERM을 주는 종료는 별도 플래그 없이 드레인된다. 반대로 신호 없는 호스트 종료는 컨트롤 플레인 입장에서 크래시와 구분되지 않아, 정상 릴리스 대신 워커 손실로 기록되고 세션이 다른 러너로 재큐잉된다.

--retire-at 시각이 되면 러너는 새 작업을 받지 않고, 진행 중인 턴이 끝나는 대로 세션을 릴리스한다. 턴이 끝났는데 백그라운드 작업이 남아 있으면 최대 60초를 기다린 뒤 릴리스하고, 결과를 읽을 후속 턴이 아직 시작되지 않았다면 SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS가 정한 만큼만 더 기다린다. 모든 세션을 놓아주면 0으로 종료한다.

네트워크 경로

인바운드가 없다는 점이 이 아키텍처의 핵심이다. 문서가 구분하는 아웃바운드 경로는 네 갈래다.

컨트롤 플레인: 러너가 api.anthropic.com으로 작업을 폴링하고 셋업 진행·실패 이벤트를 올린다. 폴링이 하트비트를 겸한다.
SCM 커넥터: 온디맨드 오케스트레이터의 선택적 SCM 커넥터 터널만 WebSocket을 쓴다.
Git: 러너가 HTTPS 또는 SSH로 git 호스트에 클론·푸시한다. 세션별 발급 자격증명이나 api.anthropic.com을 경유하는 Anthropic git 프록시도 선택할 수 있다.
세션 자식 프로세스: 이벤트 스트림을 api.anthropic.com으로 유지하고, 모델 추론과 세션 중 git 명령을 위한 자체 아웃바운드 호출을 만든다.

기업 이그레스 프록시는 지원된다. 러너와 오케스트레이터가 HTTPS_PROXY, NO_PROXY 같은 프록시·mTLS 환경 변수를 존중하고 세션은 러너에서 이를 상속한다. 다만 세션 스트리밍이 HTTPS 위의 SSE(Server-Sent Events)라 경로상의 프록시가 응답을 버퍼링하면 안 된다.

추론은 Anthropic API로 고정된다. 컨트롤 플레인이 세션마다 API 엔드포인트를 내려주고 세션은 Anthropic이 발급한 세션 범위 OAuth 토큰으로 인증하므로, Amazon Bedrock·Google Cloud Agent Platform·Microsoft Foundry·LLM 게이트웨이 경유는 불가능하다.

실행 중인 세션에 메시지 보내기

세션이 우리 환경에서 돌기 시작하면, claude auth login이 된 아무 머신에서나 후속 메시지를 보낼 수 있다. 세션을 시작한 머신일 필요는 없다.

claude -p "your message" --cloud <session-id>

<session-id>에는 session_...이나 cse_... 형태의 ID를 그대로 넣거나, 세션의 claude.ai/code URL을 넣는다. 전송에 성공하면 Sent to cloud session.이 세션 ID·뷰 링크와 함께 출력된다. 이 명령은 Anthropic 호스팅 세션에도 동일하게 동작한다.

도입 전 체크리스트

팀이 클라우드 세션을 실제로 쓰는가. 터미널·IDE 세션만 쓴다면 설정할 것이 없다.
호스트 시계가 NTP로 동기화돼 있는가. 5분 이상 어긋나면 인증이 실패한다.
러너 이미지에 컴파일러·SDK·사내 CLI를 미리 넣어 세션이 바로 빌드에 들어갈 수 있게 했는가.
종료된 러너를 다시 띄울 오케스트레이터를 준비했는가. 러너는 기본적으로 스스로 종료된다.
프로덕션 전에 Deploy to production 문서의 보안 하드닝·이그레스·git 자격증명 항목을 확인했는가.

자주 묻는 질문

Q. Remote Control과 self-hosted environments는 뭐가 다른가?
Remote Control은 개발자 자기 머신에서 도는 세션을 폰·브라우저로 이어 쓰는 기능이고, 그 머신이 세션 실행을 멈추면 세션도 끝나며 claude를 실행한 사용자에게 묶인다. 셀프호스팅 환경은 플랫폼 팀이 운영하는 공용 인프라에서 돌고 조직 내 누구나 쓸 수 있다. Remote Control은 Pro·Max 요금제에서도 쓸 수 있다.

Q. 환경 시크릿을 잃어버리면 어떻게 하나?
환경의 Configuration 탭에서 새 시크릿을 만들고 러너에 배포한 뒤 기존 것을 폐기한다. 폐기된 시크릿을 든 러너는 다음 인증 폴링에서 실패하며 poll auth failed를 남기고 종료되므로, 오케스트레이터가 새 시크릿으로 재기동한다.

Q. 셀프호스팅으로 옮기면 과금이 달라지나?
달라지지 않는다. 셀프호스팅 환경의 세션도 Anthropic 호스팅 환경과 동일하게 조직의 Claude Code 사용량을 소모한다. 바뀌는 것은 과금이 아니라 운영 책임이다.

마무리

셀프호스팅 환경은 새 모델이 아니라 실행 위치를 옮기는 인프라 기능입니다. 네트워크 접근과 사내 툴체인이 필요했던 팀에게는 확실한 해법이지만, 러너 이미지와 플릿을 직접 운영해야 한다는 조건이 붙습니다. Anthropic 스스로 대부분의 조직에는 호스팅형을 권한다고 밝힌 만큼, 요건이 분명한 경우에만 선택하는 편이 좋겠습니다.

관련해서 이전에 정리한 Claude Sonnet 5 API 가격 정리도 함께 보시면 비용 관점을 잡는 데 도움이 됩니다.