셀프호스티드 환경 (Self-hosted environments)
기준일: 2026-10-23
공식 기준: Self-hosted environments
개요
셀프호스티드 환경은 Claude Code 클라우드 세션을 조직이 운영하는 인프라에서 실행합니다. 클라우드 세션은 개발자 머신 밖에서 도는 모든 세션(claude.ai, 모바일/데스크톱 앱, claude --cloud, 클라우드 예약 작업)입니다. 기본은 Anthropic 인프라에서 실행되고, 셀프호스티드 환경을 고르면 같은 세션이 내 네트워크 안에서 돕니다. 개발자 경험은 가용성 제약을 빼면 동일합니다.
- Team·Enterprise 플랜 퍼블릭 베타, 기본 off (2.1.224+ 에서
claude self-hosted-runner도입). - 터미널·IDE 세션은 항상 개발자 머신에서 돌므로 설정할 것이 없습니다. 항상 켜 둔 내 머신을 다른 기기에서 쓰려면 Remote Control이 맞습니다(Pro/Max도 가능).
- 바로 설정하려면 Quickstart, 보안 먼저 보려면 Deploy.
핵심 개념
| 용어 | 설명 |
|---|---|
| Environment | claude.ai 설정에서 만드는 러너 그룹의 이름 붙은 목적지. 세션은 개별 러너가 아니라 환경으로 라우팅 |
| Environment secret | 러너가 환경에 인증·등록할 때 쓰는 단일 공유 자격 증명. 생성 시 한 번만 표시(관리 UI 라벨은 environment key) |
| Runner | 직접 배포하는 장수 프로세스. 환경에 등록 → 러너 토큰 수령 → 세션 폴링 |
| Session | 개발자가 시작한 Claude Code 작업 1건. 러너가 자식 Claude Code 프로세스로 실행 |
| Owner | 러너가 첫 세션을 집을 때 고정되는 소유자. 사용자 세션은 그 사용자 계정, Claude Tag 채널 세션은 해당 Claude Tag 에이전트 |
- API 필드·토큰 클레임·메트릭 이름에서는 환경이
pool, 환경 ID가pool_id로 나타납니다(deprecatedpool플래그 이름 포함). - 러너는 한 번에 한 owner만 서빙하므로 최소 플릿 크기 = 동시에 활성인 owner 수(사용자 + Claude Tag 에이전트).
상세
동작 방식
세 부분: 환경(admin 설정에서 생성) / 러너(내 네트워크 호스트의 프로그램, 셀프호스티드 CI 러너와 같은 개념) / 세션.
개발자가 세션을 시작하면 환경 선택기에 Anthropic 호스티드 환경과 조직 환경이 함께 나옵니다. 내 환경을 고르면 Anthropic 컨트롤 플레인이 세션을 환경 큐에 넣고, 러너가 claim → 선택한 저장소 clone → 호스트에서 Claude Code 프로세스 시작. 모든 연결은 아웃바운드 HTTPS이며 Anthropic이 내 네트워크로 들어오지 않습니다(인바운드 없음).
러너는 직접 계속 띄워 두거나, 세션이 큐에 쌓일 때 러너를 띄우는 autoscaling orchestrator(on-demand runners)를 쓸 수 있고, 러너는 일이 끝나면 스스로 종료합니다.
가용성과 제약
- 플랜: Team/Enterprise 퍼블릭 베타. Owner가 Cloud environments 관리 페이지에서 Allow self-hosted environments를 켜야 하며 조직의 클라우드 세션이 활성이어야 함.
- ZDR/HIPAA: Zero Data Retention 또는 HIPAA 구성 조직은 사용 불가.
- 모델 추론: 기본은 Anthropic API. 러너를 설정하면 Amazon Bedrock 또는 Google Cloud Agent Platform으로 보낼 수 있으나 세션 내용은 두 경우 모두 Anthropic으로 갑니다. 이렇게 구성한 러너에는 server-managed settings와 claude.ai 조직 정책이 세션에 전달되지 않습니다.
- Surface: claude.ai/code, 모바일/데스크톱 앱, 클라우드 예약 작업, 터미널(
claude --cloud또는--environment디스패치), Claude Tag. Claude Security와 Code Review 세션은 아직 라우팅되지 않음. Claude Tag 세션은 Access bundles 미지원. - 저장소: GitHub에서 checkout (GitHub Enterprise Server는 별도 네트워크 요구사항).
- 과금: Anthropic 호스티드 환경과 동일하게 조직의 Claude Code 사용량으로 집계.
왜 셀프호스트하는가
대부분은 인프라가 필요 없는 Anthropic 호스티드가 적합합니다. 셀프호스팅은 러너 이미지 빌드·플릿 운영·네트워크 통제를 직접 맡는 대신 다음을 얻습니다.
- 네트워크 접근: 내부 서비스·DB·레지스트리를 공용 인터넷에 노출하지 않고 접근
- 커스텀 툴링: 컴파일러·SDK·내부 CLI를 러너 이미지에 미리 설치
- 컴플라이언스: checkout·빌드 산출물이 내 인프라에 머뭄. 세션 내용(프롬프트·응답·툴 결과)은 여전히
api.anthropic.com으로 가고 Anthropic이 transcript를 저장
세션 오케스트레이션·큐잉·claude.ai UI(컨트롤 플레인)는 계속 Anthropic이 호스팅합니다.
세션 라이프사이클
- 여유 용량이 있는 러너가 세션을 claim하고 lease를 쥠
- 러너가 작업 디렉터리에 저장소를 clone하고 자식 Claude Code 프로세스를 spawn
- 자식이 HTTPS로 이벤트를 스트리밍, 러너의 폴링은 lease 갱신 + heartbeat 역할
- 러너가 폴링을 멈추면 lease가 약 60초 후 만료되고, 서버가 다른 러너로 requeue하는 데 몇 분 이상 걸릴 수 있음
폴링 요청당 10초 제한. 타임아웃·유실·파싱 불가 응답(예: 프록시가 자기 페이지로 응답)이면 라이브 세션은 유지한 채 1~2초 후 재시도하며, 연속 실패마다 간격을 두 배로(최대 20초), lease 만료가 가까우면 간격을 줄입니다.
러너 라이프사이클
첫 세션이 러너를 그 owner에 고정하고, 러너는 --capacity까지 동시 세션을 실행합니다. 활성 세션이 끝난 뒤 동작은 --drain-grace-sec가 결정합니다.
- 기본
0: 세션이 끝나자마자 종료 → Kubernetes 같은 오케스트레이터가 깨끗한 디스크로 재시작해 어떤 owner든 서빙 가능 - 양수: 그 초만큼 같은 owner 큐를 계속 폴링한 뒤 종료
SIGTERM으로 끝나는 환경은 별도 플래그가 필요 없습니다(드레인 또는 --defer-shutdown-max-min). 시그널 없이 특정 시각에 호스트가 파괴되는 경우(샌드박스 수명 제한, 스팟 회수 등)는 그 몇 분 전 epoch 초로 --retire-at <epoch-seconds>를 줍니다. retire 시점에:
- 새 작업을 받지 않음
- 활성 세션을
--release-idle-session-min과 같은 release 경로로 해제 → 사용자의 다음 메시지에 새 러너에서 재개. 턴 진행 중이면 턴 종료 후 해제하며 세션 프로세스의 턴 종료 보고를SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS까지 기다립니다(2.1.280+, 이전에는 턴 종료 즉시 해제). 턴 종료 후 백그라운드 태스크가 남으면 최대 60초 기다린 뒤 해제하고, 결과를 읽는 후속 턴은SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS까지 시작을 기다립니다. - 모든 세션이 해제되면 exit 0
--retire-at이 없으면 시그널 없는 호스트 kill은 crash와 구분되지 않아 컨트롤 플레인이 lost worker로 기록하고 세션은 다른 러너로 requeue됩니다. 킬보다 오래 가는 턴은 여전히 유실됩니다.
네트워크 경로
| 경로 | 내용 |
|---|---|
| 컨트롤 플레인 | 러너가 api.anthropic.com을 폴링(= heartbeat), setup 진행/실패 이벤트 전송 (아웃바운드 HTTPS) |
| Git | 러너가 HTTPS/SSH로 내 git 호스트에 clone·push. Anthropic git proxy를 쓰면 github.com 트래픽이 api.anthropic.com을 경유 |
| 세션 자식 | 이벤트 스트림, 모델 추론, 세션 중 git 명령. Anthropic-managed git이면 git/gh 트래픽을 api.anthropic.com WebSocket으로 전송 |
| SCM connector | 선택 사항인 orchestrator SCM connector는 현재 사용 불가라 터널이 열리지 않음 |
- 추론은 기본 Anthropic API이며 컨트롤 플레인이 엔드포인트를 전달하고 세션은 Anthropic 발급 세션 범위 OAuth 토큰으로 인증합니다.
- 사내 egress 프록시 지원: 러너와 orchestrator가 Network configuration의
HTTPS_PROXY,NO_PROXY및 mTLS 환경 변수를 따르며 각 프로세스 환경에 설정합니다(세션은 러너에서 상속). 세션 스트리밍이 SSE이므로 경로상 프록시는 응답을 버퍼링하면 안 됩니다. Proxy-Authorization헤더가 필요한 프록시는 "Authenticate to an egress proxy"(2.1.238+--proxy-authorization-command/--proxy-authorization-file)를 참고하세요.
내 인프라에 남는 것
저장소 checkout, 빌드 산출물, 시크릿, 세션이 만들거나 수정하는 파일은 내가 준비한 머신에 남습니다. 대화(프롬프트·응답·툴 결과)는 api.anthropic.com으로 가며 Anthropic이 transcript를 저장해 다른 surface에서 재개할 수 있게 합니다.
버전별 변경 요약 (2.1.224 이후)
- 2.1.224:
claude self-hosted-runner도입 - 2.1.229: 서버가 공급하는 Claude Code hook을 셀프호스티드 러너 세션에서 지원, Windows는 명시적
--base-dir필요 - 2.1.238:
--defer-shutdown-max-min,--proxy-authorization-command/--proxy-authorization-file - 2.1.248:
--client-label <label>(또는SELF_HOSTED_RUNNER_CLIENT_LABEL) - 2.1.268:
--remove-session-state - 2.1.271:
--drain-marker-file <path>,--host-config-snapshot disk|memory - 2.1.281: wrapper·
commandhook이--system-prompt/--append-system-prompt를 덧붙인다면--system-prompt-file/--append-system-prompt-file로 바꿔야 함 (system prompt가 파일로 전달됨) - 2.1.287: 내장
gh api(REST 전용) — Anthropic-managed git 세션, GitHub CLI 미설치 머신 - 2.1.299: orchestrator
--shutdown-drain-sec - 2.1.307: checkout hook 기본 30분 후 중단 →
--checkout-hook-timeout-min상향 또는0 - 2.1.309: 새 러너로 옮겨 간 세션에서 중단된 툴 호출을 "결과 불명"으로 표시