셀프호스티드 환경 퀵스타트
기준일: 2026-10-23
공식 기준: Self-hosted environments quickstart
개요
호스트 1대에 러너 1개를 띄워 테스트 세션 1건을 돌리는 최소 구성입니다. 두 단계: (1) 환경 생성 + 러너 시작 + 세션 라우팅, (2) 터미널에서 후속 메시지 전송. claude.ai(환경 생성·상태·라우팅)와 호스트 터미널(러너)을 오갑니다. 실제 저장소·내부 시스템을 붙이기 전에 Deploy to production을 먼저 보세요. 개념은 Self-hosted environments.
핵심 개념
| 항목 | 요구 사항 |
|---|---|
| 조직/역할 | Owner가 Allow self-hosted environments를 켜야 New 버튼 표시. GitHub connector(Owner) + 개발자 개인 GitHub 연결 |
| 호스트/네트워크 | Linux/macOS 호스트 또는 컨테이너. api.anthropic.com, claude.ai(+리다이렉트되는 다운로드 호스트), git 호스트로 아웃바운드 HTTPS. Windows 러너 호스트는 미지원(Linux 컨테이너 사용) |
| 테스트 저장소 | 공개 저장소 또는 호스트가 자격 증명 요청 없이 HTTPS URL로 clone 가능한 저장소 (SSH 키만으로는 불가, 러너는 https:// URL을 clone) |
| 시계 | NTP 등으로 동기화. 5분 넘게 어긋나면 인증 실패 |
| 소프트웨어 | Claude Code v2.1.224+, Git 2.24+ |
준비 확인:
claude self-hosted-runner --help
러너 사용법이 출력되면 준비 완료(--environment-secret-file 등 표시). 2.1.224 미만이면 일반 claude --help가 나오므로 업데이트하거나 컨테이너 이미지를 재빌드합니다.
상세
환경·러너 설정은 가이드 설정 또는 수동 중 선택합니다. 인터랙티브 세션이 불가한 호스트이거나, Owner가 환경을 만들어 secret만 건네준 경우는 수동을 씁니다(가이드 설정은 Owner 로그인 필요).
가이드 설정
환경 생성을 안내하고, 저장한 secret 파일로 로컬 러너를 시작하고, 등록을 확인한 뒤 ./runner-setup/CHEAT-SHEET.md를 씁니다.
- 로그인: Owner 역할 계정으로
claude auth login한 머신에서 실행 (API 키나 서드파티 모델 프로바이더만 쓰면 세션은 시작돼도 조직 확인이 실패) - 버전: 2.1.224 미만이면 setup 명령이 안내 대신 단어를 프롬프트로 한 일반 세션을 시작
claude self-hosted-runner setup
테스트 세션은 직접 시작하지 않으며 claude.ai/code에서 시작하라고 안내합니다. 마지막 단계에서 시작한 러너를 멈추는데, 그 전에 나가면 러너는 계속 실행됩니다. 이어서 쓰려면 ./runner-setup/CHEAT-SHEET.md의 명령으로 러너를 다시 시작합니다.
수동 설정
1. 환경 생성: 관리자 설정의 Cloud environments에서 Self-hosted environments 아래 New → 이름 입력 → Create. 마법사 2단계의 Copy environment key로 secret을 복사합니다. 한 번만 표시되고 이후 조회 불가하며 생성 365일 후 만료됩니다. ccpool_... 환경 ID는 상세 대화상자에 계속 보이며 토큰 검증의 aud 확인과 CI 테스트 디스패치에 필요합니다.
secret 분실/교체: 환경 Configuration 탭에서 새 secret 생성 → 러너에 배포 → 이전 것 revoke. revoke된 secret의 러너는 다음 인증 폴링에서 poll auth failed를 로그하고 종료하며 오케스트레이터가 새 secret으로 재시작합니다.
2. 러너 시작
mkdir -p /etc/claude
secret을 셸 히스토리에 남기지 않고 파일로 저장(붙여넣기 → Enter → Ctrl-D, umask로 소유자만 읽기):
(umask 077 && cat > /etc/claude/environment-secret)
위 명령은 /etc/claude라 root가 필요하고 파일은 실행한 사용자만 읽을 수 있습니다. 러너를 다른 사용자로 돌리면 error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>')로 종료하므로, 그 사용자 권한으로 쓸 수 있는 디렉터리에 만들고 같은 경로를 --environment-secret-file에 넘깁니다.
<writable-dir>은 러너가 쓰거나 만들 수 있는 절대 경로입니다. 러너가 시작 시 만들고 그 아래에 저장소 checkout과 세션별 디렉터리를 만듭니다. --base-dir을 생략하면 /workspace를 쓰며, 이미 존재·쓰기 가능하거나 root로 시작할 때만 동작합니다.
주의: 러너 전용 디렉터리를 쓰세요. 홈 디렉터리나 본인 clone 디렉터리는 안 됩니다. 러너는
<writable-dir>/<repo-owner>/<repo>를 자기 clone으로 간주해 reset하고 파일을 덮어쓰거나 삭제할 수 있습니다. base dir을 만들거나 쓸 수 없으면 등록하지 않고 시작 시 디렉터리 이름이 든 오류로 종료합니다.
claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'
등록되면 Registered: runner_id=<runner-id>를 로그하고 폴링을 시작합니다. 이 명령으로 시작한 러너는 세션 1건을 서빙한 뒤 의도적으로 종료합니다(턴마다가 아님). 더 서빙하려면 종료할 때마다 다시 시작합니다.
3. 러너 확인: Cloud environments 페이지에서 환경 상태가 No runners deployed에서 Healthy로 몇 초 안에 바뀝니다. 환경을 열어 Activity에서 러너를 봅니다. 관리 페이지 권한이 없으면 러너 로그의 Registered: runner_id=<runner-id> 줄이 같은 신호입니다.
4. 세션 라우팅: claude.ai/code에서 세션을 시작하고 환경 선택기에서 내 환경을 고릅니다. 저장소는 위 테스트 저장소 조건을 만족하는 것을 고릅니다. 러너가 Picked up session <session-id>와 active/capacity를 로그합니다.
문제 시:
- 세션이 큐에 머뭄: Troubleshooting
- git 오류
could not read Username for <host URL>: 러너에 HTTPS 자격 증명이 없음 → Configure git으로 자격 증명 공급, 또는 호스트에 SSH 키가 있으면 "Rewrite git URLs for private networks"로 SSH clone
러너가 종료되는 경우
종료하면 다시 시작합니다.
- 할 일 없음:
[runner:exit] account workload drained — exiting. 세션을 archive/delete했거나 세션 시작에 실패한 경우 - 연락 두절:
[runner:fatal]줄이runner record gone server-side또는poll auth failed. 호스트 슬립 등으로 한동안 Anthropic과 끊기면 다음 접속 시 종료할 수 있음
턴이 끝나도 세션은 붙어 있고 러너도 살아 있으므로 러너 재시작 없이 후속 메시지를 보낼 수 있습니다. 프로덕션에서는 종료 시 재시작하고 시작 직후 반복 종료하면 대기를 늘리는 오케스트레이터 아래 배포합니다.
실행 중 세션에 후속 메시지 보내기
claude auth login된 임의 머신의 claude CLI에서 보냅니다(세션을 시작한 머신이 아니어도 됨).
claude -p "your message" --cloud <session-id>
<session-id>는 순수 session_... 또는 cse_... ID 또는 claude.ai/code URL. 성공하면 Sent to cloud session.과 세션 ID, 보기 링크가 출력됩니다. Anthropic 호스티드 세션에도 동일하게 동작합니다(Send follow-ups from the CLI).