자체 호스팅 환경은 Team 및 Enterprise 플랜에서 공개 베타 상태입니다. 가용성 및 제한 사항에서 활성화 경로를 확인하세요. 이 페이지는 첫 번째 세션을 실행하는 방법을 설명합니다. 자체 호스팅 환경에서 자체 호스팅 환경이 무엇인지 확인하고, 프로덕션에 배포에서 강화 및 플릿 레시피를 확인하세요.
필수 조건
조직 및 역할
claude.ai 측에서 필요한 사항:- 자체 호스팅 환경 허용이 클라우드 환경 관리자 페이지에서 Owner에 의해 활성화되어야 합니다. 새로 만들기 버튼은 활성화될 때까지 나타나지 않습니다. 이 역할을 보유하지 않은 경우, 역할을 보유한 사람이 환경을 생성하고 해당 비밀을 제공할 수 있습니다. 이 페이지의 러너 및 터미널 단계에는 claude.ai 역할이 필요하지 않으며, 단계에서 관리자 UI의 상태를 확인하는 경우, 러너의 자체 로그 라인이 동일한 신호를 제공합니다.
- 조직의 GitHub 연결이 필요하므로 개발자가 세션을 시작할 때 저장소를 선택할 수 있습니다.
호스트 및 네트워크
러너 호스트에 필요한 사항:api.anthropic.com,claude.ai및 아래 설치 단계를 위해 리디렉션되는 다운로드 호스트, 그리고 클론을 위해 git 호스트로의 아웃바운드 HTTPS를 사용하는 Linux 또는 macOS 호스트 또는 컨테이너입니다. 네트워크 요구 사항 표에 전체 목록이 있습니다. Windows는 러너 호스트로 지원되지 않습니다. 대신 Linux 컨테이너에서 러너를 실행하세요. 개발자 워크스테이션은 영향을 받지 않습니다. 세션은 브라우저의 claude.ai에서 시작되기 때문입니다.- NTP와 같은 실시간으로 동기화된 시계입니다. 시계가 5분 이상 차이나면 인증이 실패합니다. 문제 해결을 참조하세요.
러너 호스트의 소프트웨어
시작하기 전에 호스트에 설치하세요:- Claude Code v2.1.224 이상, 표준 설치 방법 중 하나를 사용합니다. 러너는 표준
claude바이너리의 일부이며, 이전 버전은self-hosted-runner서브 명령을 인식하지 못합니다. 네이티브 설치 프로그램의 기본latest채널은 각 릴리스를 게시되는 즉시 제공합니다.stable채널, Homebrewclaude-codecask, 그리고 안정적인 apt, dnf, apk 저장소는 약 1주일 뒤에 제공됩니다. 플릿이 실행하는 정확한 버전을 고정하려면 특정 버전 설치를 참조하세요. 컨테이너 이미지의 경우 프로덕션에 배포의 Dockerfile을 참조하세요. - Git 2.24 이상. 배포 페이지의 일부 git 옵션에는 최신 버전이 필요합니다. Git 구성에서 각 하한을 명시합니다.
--environment-secret-file과 같은 플래그를 나열하는 러너의 사용 텍스트를 인쇄합니다. 2.1.224보다 이전 버전에서는 명령이 대신 일반 claude --help 출력을 인쇄합니다. claude update로 업그레이드하거나 latest 채널에서 다시 설치하세요.
환경 및 러너 설정
Claude Code에는 안내식 설정이 포함되어 있습니다. 관리자 UI에서 환경 생성을 안내하는 대화형 Claude Code 세션으로, 저장한 비밀 파일로 로컬 러너를 시작하고, 러너가 등록되었는지 확인하고,./runner-setup/CHEAT-SHEET.md에 치트 시트를 작성합니다. Owner 역할을 보유한 계정으로 claude auth login을 사용하여 로그인한 머신에서 실행하세요. API 키 또는 타사 모델 제공자와는 사용할 수 없습니다. 대화형 세션이 불가능한 호스트에서는 대신 아래의 수동 단계를 사용하세요. 버전 확인이 통과했는지 확인하세요. 2.1.224보다 이전 버전에서는 이 명령이 안내식 설정 대신 단어를 프롬프트로 하는 일반 Claude 세션을 시작합니다. 안내식 설정을 시작하려면 설정 서브 명령을 실행하고 프롬프트를 따르세요:
1
환경 생성
관리자 설정의 클라우드 환경 페이지로 이동하세요. 자체 호스팅 환경 아래에서 새로 만들기를 선택하고, 환경의 이름을 지정한 후 생성을 선택하세요. 마법사의 두 번째 단계에서 환경 키 복사를 선택하여 환경 비밀을 복사하세요. 관리자 UI는 이를 환경 키로 표시합니다. claude.ai는 비밀을 한 번만 표시하며, 나중에 검색할 수 없습니다. 생성 후 365일 후에 만료됩니다. 환경의
ccpool_... ID는 세부 정보 대화 상자에서 계속 표시됩니다. 토큰 검증의 aud 확인 및 CI에서 테스트 세션 디스패치에 필요합니다.비밀을 잃어버렸거나 회전해야 하는 경우, 환경의 구성 탭에서 새 비밀을 생성하고, 새 비밀을 러너에 배포한 후, 이전 비밀을 취소하세요. 취소된 비밀을 보유한 러너는 다음 인증된 폴에서 실패하고 종료되며, poll auth failed를 기록하고, 오케스트레이터가 새 비밀로 다시 시작합니다.2
러너 시작
비밀 디렉토리를 생성하세요. 이 단계와 다음 단계에는 환경 비밀을 파일에 작성하세요. 아래 명령은 터미널에서 읽으므로 비밀이 셸 히스토리에서 벗어납니다. 복사한 값을 붙여넣고, Enter를 누른 후 Ctrl-D를 누르면, 서브셸의 기본 디렉토리를 선택하고, 아래 러너 명령의
/etc/claude 경로에 대한 루트가 필요합니다. 러너 프로세스가 읽을 수 있는 모든 경로가 작동하므로, 다른 경로를 사용하는 경우 두 명령과 --environment-secret-file 값을 함께 조정하세요.umask가 파일을 소유자만 읽을 수 있도록 만듭니다.<writable-dir>을 러너가 쓸 수 있거나 생성할 수 있는 절대 경로로 바꾸세요. 러너는 시작 시 디렉토리를 생성한 후, 저장소를 체크아웃하고 그 아래에 세션별 디렉토리를 생성합니다. --base-dir 없이는 /workspace를 사용하며, 이는 해당 디렉토리가 이미 존재하고 쓸 수 있거나 러너를 루트로 시작하는 경우에만 작동합니다.러너가 경로를 생성하거나 쓸 수 없으면, 등록하지 않고 시작 시 디렉토리의 이름을 지정하는 오류로 종료됩니다. 문제 해결을 참조하세요.그런 다음 --environment-secret-file 및 --base-dir로 러너를 시작하세요. 러너는 환경에 등록하고 작업을 폴링하기 시작합니다. 러너가 종료되면 수동으로 다시 시작하세요. 프로덕션 배포는 종료된 러너를 다시 시작하는 오케스트레이터 아래에서 러너를 실행하며, 일반적으로 재시작당 새로운 파일 시스템을 사용합니다. 사전 준비된 체크아웃 재사용은 지원되는 영구 디스크 설정을 다룹니다.3
러너가 나타나는지 확인
클라우드 환경 페이지로 돌아가세요. 환경의 상태는 러너 시작 후 몇 초 내에 배포된 러너 없음에서 정상으로 변경됩니다. 환경을 열고 활동을 선택하여 러너 자체를 확인하세요.
4
세션을 환경으로 라우팅
claude.ai/code에서 세션을 시작하고 환경 선택기에서 환경을 선택하세요. 자체 호스팅 환경은 Anthropic 호스팅 환경과 함께 나타납니다. 러너는 호스트가 이미 가지고 있는 git 자격 증명으로 클론하므로, 이 호스트가 이미 클론할 수 있는 저장소 또는 공개 저장소를 선택하세요. 프로덕션의 비공개 저장소에 대한 자격 증명 옵션은 Git 구성에 있습니다. 다음 사용 가능한 러너가 대기 중인 세션을 선택하고
Picked up session <session-id>를 기록하며, 활성 개수 및 용량을 함께 기록하므로, 러너의 자체 출력에서 어느 호스트가 세션을 선택했는지 확인할 수 있습니다. claude.ai/code에서 세션이 작동하는 것을 보고 Claude의 답변을 읽으세요. 세션이 대기 중인 경우 문제 해결을 참조하세요.실행 중인 세션에 후속 메시지 전송
세션이 환경에서 실행 중이면,claude auth login으로 로그인한 모든 머신의 claude CLI에서 후속 메시지를 전송하세요. 명령은 세션을 시작한 머신에서 실행할 필요가 없습니다. 명령은 하나의 메시지를 게시합니다:
<session-id>의 경우, 베어 session_... 또는 cse_... ID 또는 세션의 claude.ai/code URL을 전달하세요. 성공적인 전송은 세션 ID 및 보기 링크와 함께 Sent to cloud session.을 인쇄합니다. 수락된 ID 형식, JSON 출력, 계정 및 정책 요구 사항, 오류 참조는 CLI에서 후속 메시지 전송에 있습니다. 명령은 Anthropic 호스팅 세션에 대해 동일하게 작동하기 때문입니다.
다음 단계
- 프로덕션에 배포: 배포를 강화하고, 송신을 제어하고, git 자격 증명을 구성하고, Kubernetes 또는 Compose 아래에서 플릿을 실행합니다.
- 세션 사용자 정의: 래퍼 스크립트, 수명 주기 훅, 온디맨드 러너, MCP 서버, 권한
- 엔드 투 엔드 테스트: 세션을 디스패치하고 Claude의 답변을 읽는 CI 스모크 테스트