SpyBara
Go Premium

self-hosted-environments.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 55 additions and 79 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Sat 3 23:57 Tue 6 23:59 Sat 10 23:01 Wed 14 22:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59 Sat 24 22:59 Mon 26 22:57 Thu 29 23:57 Fri 30 23:01

자체 호스팅 환경

조직이 제어하는 인프라에서 Claude Code 클라우드 세션을 실행합니다: 자체 호스팅 환경을 설정하고, 러너를 배포하고, 세션을 자신의 컴퓨팅으로 라우팅합니다.

[!NOTE]

자체 호스팅 환경은 Team 및 Enterprise 플랜에서 공개 베타 상태이며 기본적으로 비활성화되어 있습니다. 활성화 경로 및 제외 사항은 가용성 및 제한 사항을 참조하세요.

자체 호스팅 환경은 조직이 운영하는 인프라에서 Claude Code 클라우드 세션을 실행합니다. 클라우드 세션은 개발자의 머신이 아닌 다른 곳에서 실행되는 모든 세션입니다. 개발자는 claude.ai, 모바일 및 데스크톱 앱, claude --cloud를 사용한 터미널, 클라우드 예약 작업에서 이러한 세션을 시작합니다. 기본적으로 클라우드 세션은 Anthropic의 인프라에서 실행됩니다.

자체 호스팅 환경에서는 동일한 세션이 네트워크 내부에서 실행됩니다. 개발자 경험은 가용성 및 제한 사항의 차이점과 배포 페이지의 알려진 문제를 제외하고는 동일합니다.

팀이 클라우드 세션을 사용하지 않으면 여기서 구성할 것이 없습니다: 터미널이나 IDE의 세션은 항상 개발자 자신의 머신에서 실행됩니다. Claude Code를 자신의 항상 켜져 있는 머신에서 실행하고 다른 디바이스에서 구동하려면 원격 제어를 사용하세요. 이는 Pro 및 Max 플랜에서도 사용 가능합니다. 설정할 준비가 되면 빠른 시작으로 바로 이동하세요. 먼저 보안 태세를 검토하려면 프로덕션에 배포부터 시작하세요. 이 페이지의 나머지 부분은 자체 호스팅이 어떻게 작동하는지와 언제 선택해야 하는지를 설명합니다.

자체 호스팅 환경이 작동하는 방식

자체 호스팅에는 세 가지 부분이 있습니다:

  • 환경: 클라우드 세션을 보낼 수 있는 명명된 대상입니다. 조직은 claude.ai 관리 설정에서 환경을 생성하며, 각 환경은 러너 집합을 그룹화합니다.
  • 러너: 네트워크 내부의 호스트에서 실행되는 프로그램입니다. 러너는 세션을 실행합니다. 개념은 자체 호스팅 CI 러너와 동일합니다.
  • 세션: 개발자가 시작한 하나의 Claude Code 작업입니다.

개발자가 클라우드 세션을 시작하면, 세션 시작 UI는 Anthropic 호스팅 환경과 조직이 생성한 환경을 나열하는 환경 선택기를 표시합니다. 조직의 환경을 선택하면, Anthropic의 제어 평면이 세션을 환경의 큐에 배치하고, 러너가 이를 요청하고, 개발자가 선택한 저장소를 복제하고, 호스트에서 Claude Code 프로세스를 시작하여 실행합니다. 러너는 구성한 자격 증명으로 git 호스트에 인증합니다. git 구성에서 옵션을 다룹니다. 세션은 네트워크 내부에서 내부 서비스에 도달하며, 내부인 경우 git 호스트도 동일한 방식으로 도달합니다. Anthropic으로의 트래픽, 즉 큐 폴링, 세션의 이벤트 스트림, 그리고 기본적으로 모델 추론은 api.anthropic.com으로의 아웃바운드 HTTPS이며, 세션이 도달할 수 있는 추가 호스트의 짧은 목록은 네트워크 요구 사항에 있습니다. Anthropic은 절대 네트워크에 연결하지 않습니다.

자체 호스팅 환경의 아키텍처 다이어그램: 네트워크 경계에는 러너, 그 내부의 두 Claude Code 세션 프로세스, 그리고 git 호스트가 포함되어 있으며, api.anthropic.com 외부에는 큐, 세션 스트림, 추론이 있습니다. 러너는 큐를 폴링하고 git 호스트에 도달하며, 각 세션 프로세스는 자신의 스트림, 추론, git 연결을 열고, 모든 연결은 네트워크에서 아웃바운드이며 인바운드는 없습니다.

다이어그램의 두 Claude Code 상자는 세션 프로세스입니다: 한 러너가 동시에 두 세션을 실행하며, 구성된 용량까지입니다. 러너는 한 번에 하나의 소유자를 제공하며 첫 번째 세션을 요청할 때 해당 소유자에게 잠깁니다. 따라서 체크아웃된 코드는 소유자 간에 혼합되지 않습니다. 러너 수명 주기에서 규칙을 다룹니다.

러너를 직접 시작하고 계속 실행하거나, 자동 스케일링 오케스트레이터를 실행할 수 있습니다. 이는 호스팅하는 두 번째 프로세스로, 세션이 큐에 대기할 때 러너를 시작합니다. 각 러너는 작업이 완료되면 자동으로 종료됩니다. 어느 쪽이든, 환경을 한 번 설정하면 지원되는 모든 표면의 선택기에 나타납니다.

가용성 및 제한 사항

롤아웃을 계획하기 전에 다음을 확인하세요:

자체 호스팅을 하는 이유

대부분의 팀은 실행하거나 유지할 인프라가 필요 없는 Anthropic 호스팅 환경으로 더 잘 제공됩니다. 자체 호스팅은 네트워크, 도구 또는 규정 준수 요구 사항이 제어하는 인프라에서 세션 실행을 유지해야 하는 팀을 위한 것입니다. 그렇다면 이것이 당신이라면, 그것이 수반하는 운영 소유권을 계획하세요: 러너 이미지를 구축하고 유지하며, 플릿을 운영하고, 네트워크를 제어합니다.

대신, 자체 호스팅은 네트워크 액세스, 사용자 정의 도구 및 규정 준수 제어를 제공합니다:

  • 네트워크 액세스: 세션은 네트워크 내부에서 실행되며 공개 인터넷에 노출하지 않고 내부 서비스, 데이터베이스 및 레지스트리에 도달할 수 있습니다.
  • 사용자 정의 도구: 러너 이미지에 컴파일러, SDK 및 내부 CLI를 사전 설치하여 모든 세션이 빌드할 준비가 된 상태로 시작됩니다.
  • 규정 준수: 저장소 체크아웃 및 빌드 산출물은 직접 제어하는 인프라에 남아 있습니다. 세션 콘텐츠는 여전히 api.anthropic.com으로 전송됩니다.

환경, 러너, 세션

환경은 claude.ai 관리자 설정의 Cloud environments 페이지에서 관리하며, 러너는 사용자가 자체 인프라에서 시작하고 관리하는 프로세스입니다.

핵심 개념

다음 용어는 셀프 호스팅 관련 페이지 전반에 등장합니다.

용어 설명
환경 claude.ai 설정에서 생성하는, 이름이 지정된 러너 그룹입니다. 세션은 개별 러너가 아닌 환경으로 라우팅됩니다.
환경 시크릿 러너가 환경에 인증하고 등록할 때 사용하는 단일 공유 자격 증명입니다. 환경 생성 시 한 번만 표시되며, 관리자 UI에서는 environment key로 표시됩니다.
러너 사용자가 배포하는 장기 실행 프로세스입니다. 러너는 환경에 등록하고, 러너 토큰을 받은 다음, 세션을 폴링합니다.
세션 claude.ai, 모바일 앱 또는 예약 작업이나 에이전트 같은 다른 Anthropic 사용 환경에서 시작된 하나의 Claude Code 작업입니다. 각 세션은 러너가 생성하는 자식 Claude Code 프로세스로 실행됩니다.

API 필드, 토큰 클레임, 메트릭 이름에서 환경은 pool로, 환경 ID는 pool_id로 나타납니다. 레퍼런스에서 deprecated된 pool 플래그 이름을 포함해 두 표기의 대응 관계를 확인할 수 있습니다.

러너는 한 번에 한 명의 소유자만 처리합니다. 러너가 처음 가져가는 세션이 러너를 해당 세션의 소유자에게 고정하며, 이후 러너는 구성된 용량까지 해당 소유자의 세션만 실행합니다. 소유자가 누구인지는 세션이 시작된 방식에 따라 달라집니다.

  • 사용자가 시작한 세션: 소유자는 해당 사용자의 계정입니다.
  • Claude Tag 채널 세션: Claude는 사용자 계정 없이 이러한 세션을 실행하므로, 소유자는 세션을 시작한 Claude Tag 에이전트입니다. 해당 에이전트가 시작하는 모든 채널 세션은 Slack 메시지를 보낸 사람과 관계없이 동일한 소유자를 가지므로, 에이전트에 고정된 러너를 1보다 큰 --capacity 값으로 실행하거나 양수의 --drain-grace-sec 값으로 실행하면 해당 러너는 서로 다른 사람이 시작한 세션을 처리합니다.

따라서 최소 플릿 크기는 사용자와 Claude Tag 에이전트를 모두 포함해 동시에 활성 상태일 것으로 예상되는 소유자 수입니다.

세션 수명 주기

개발자가 세션을 시작하고 환경을 선택하면, Anthropic의 컨트롤 플레인이 해당 세션을 환경의 대기열에 넣습니다. 이후 과정은 다음과 같습니다.

  1. 여유 용량이 있는 러너가 세션을 가져가고 해당 세션에 대한 리스를 보유합니다.
  2. 러너는 저장소를 작업 디렉터리에 클론하고 자식 Claude Code 프로세스를 생성합니다.
  3. 자식 프로세스는 HTTPS를 통해 이벤트를 스트리밍하며, 러너는 계속 폴링합니다. 각 폴링은 리스를 갱신하고 하트비트 역할도 합니다.
  4. 러너가 폴링을 멈추면 약 60초 후 리스가 만료됩니다. 이후 서버가 세션을 다른 러너용 대기열에 다시 넣기까지 몇 분, 때로는 그 이상이 걸릴 수 있습니다.

러너는 각 폴링 요청에 10초를 부여합니다. 요청이 시간 초과되거나, 유실되거나, 러너가 파싱할 수 없는 응답을 받으면, 러너는 다음 예정된 폴링을 기다리지 않고 실행 중인 세션을 계속 처리하면서 1~2초 후에 재시도합니다. 예를 들어 폴링에 자체 페이지로 응답하는 가로채기 프록시는 러너가 파싱할 수 없는 응답을 생성합니다. 요청이 이러한 방식으로 다시 실패할 때마다 러너는 다음 재시도까지의 간격을 최대 20초까지 두 배로 늘리며, 리스 만료가 임박하면 간격을 줄입니다.

러너 수명 주기

러너가 처음 가져가는 세션이 러너를 해당 세션의 소유자에게 고정하며, 러너는 해당 소유자에 대해 최대 --capacity개의 세션을 동시에 실행합니다. 러너에 활성 세션이 있고 종료 신호를 받지 않았으며 은퇴 시간에 도달하지 않은 동안, 러너는 고정된 소유자의 대기 중인 작업을 계속 가져갑니다. 세션이 끝난 후 어떻게 되는지는 --drain-grace-sec에 따라 달라집니다.

  • 기본값 0인 경우: 러너는 더 이상 폴링하지 않고 활성 세션이 끝나는 즉시 종료되므로, Kubernetes 같이 러너를 배포한 오케스트레이터가 새 디스크로 러너를 재시작하여 어떤 소유자든 처리할 수 있는 상태로 만들 수 있습니다.
  • 양수 값인 경우: 러너는 종료하기 전에 해당 초만큼 고정된 소유자의 대기열을 계속 폴링합니다.

이 수명 주기는 러너가 소유자 간에 디스크 상태를 삭제할 필요 없이 각 소유자의 체크아웃된 코드를 격리합니다.

인프라가 러너를 중지하는 방식에 따라 --retire-at이 필요한지가 결정됩니다. SIGTERM을 전달하는 종료에는 플래그가 필요하지 않습니다. 러너는 종료 타이밍에 설명된 대로 드레인하거나, --defer-shutdown-max-min을 설정한 경우 이미 보유한 세션을 계속 처리합니다. 반면 샌드박스 수명 제한이나 스팟 인스턴스 회수처럼 인프라가 신호 없이, 또는 드레인하기에 너무 짧은 유예 기간으로 알려진 시각에 호스트를 제거한다면, 해당 시각보다 몇 분 앞선 값으로 --retire-at <epoch-seconds>를 전달합니다. 은퇴 시간이 되면 다음이 진행됩니다.

  1. 러너가 새 작업 수락을 중단합니다.
  2. 러너는 --release-idle-session-min 플래그가 사용하는 것과 동일한 해제 경로를 통해 각 활성 세션을 해제하므로, 사용자가 다음 메시지를 보내면 세션이 새 러너에서 재개됩니다. 러너가 각 세션을 해제하는 시점은 세션 상태에 따라 달라집니다.
    • 턴 진행 중인 세션은 해당 턴이 끝난 후 해제됩니다. 러너는 먼저 세션의 프로세스가 Anthropic에 턴 종료를 보고할 때까지 최대 SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS 동안 기다립니다. v2.1.280 이전에는 러너가 턴이 끝나는 즉시 세션을 해제했습니다.
    • 턴이 끝났지만 백그라운드 작업이 계속 실행 중이면, 러너는 최대 60초 동안 기다린 후 작업이 여전히 실행 중이더라도 세션을 해제합니다. 작업은 끝났지만 그 결과를 읽는 후속 턴이 아직 실행되지 않았다면, 러너는 해당 턴이 끝날 때까지 세션을 유지하며, 해당 턴이 시작되기까지 최대 SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS 동안만 기다립니다.
  3. 모든 세션이 해제되면 러너는 종료 코드 0으로 종료됩니다.

종료 시점 이후까지 이어지는 턴은 여전히 유실됩니다. 여유 시간 산정 방법은 종료 타이밍에서 다룹니다. --retire-at이 없으면 신호 없는 호스트 종료는 크래시와 구별되지 않습니다. 컨트롤 플레인은 정상적인 해제가 아닌 워커 유실로 기록하고, 세션은 다른 러너용 대기열에 다시 들어갑니다.

네트워크 경로

러너와 세션은 여러 종류의 아웃바운드 연결을 생성하며, Anthropic으로부터의 인바운드 연결은 필요하지 않습니다.

  • 컨트롤 플레인: 러너는 api.anthropic.com을 폴링하여 작업을 가져오고 설정 진행 및 실패 이벤트를 게시하며, 모두 아웃바운드 HTTPS를 사용합니다. 폴링은 러너의 하트비트 역할도 합니다.
  • Git: 러너는 배포에서 제공하는 자격 증명으로 인증하여 HTTPS 또는 SSH를 통해 git 호스트에서 클론하고 푸시합니다. 세션별로 발급되는 자격 증명을 포함한 옵션은 git 구성을 참조하세요. Anthropic git 프록시를 사용하면 github.com 저장소에 대한 git 트래픽은 대신 api.anthropic.com을 거칩니다.
  • 세션 자식 프로세스: 자식 Claude Code 프로세스는 api.anthropic.com으로의 세션 이벤트 스트림을 유지하며, 모델 추론 및 세션 중 실행되는 git 명령을 위한 자체 아웃바운드 호출을 수행합니다. Anthropic 관리 git을 사용하는 세션에서는 자식 프로세스가 github.com에 대한 git 및 gh 트래픽을 api.anthropic.com으로 여는 WebSocket 연결을 통해 전송합니다.
  • SCM 커넥터: 선택 사항인 오케스트레이터 SCM 커넥터는 사용할 수 없으므로 해당 터널은 열리지 않습니다. 이 터널은 api.anthropic.com으로의 WebSocket 연결입니다.

전체 이그레스 목록은 네트워크 요구 사항을 참조하세요. 위 다이어그램은 선택 사항인 SCM 커넥터와 Anthropic 관리 git 연결을 제외한 이러한 경로를 보여줍니다.

기본적으로 모델 추론은 Anthropic API를 사용합니다. 컨트롤 플레인이 각 세션에 API 엔드포인트를 전달하며, 세션은 Anthropic이 발급한 세션 범위 OAuth 토큰으로 인증합니다. 대신 자체 클라우드 계정으로 모델 요청을 보내려면 Bedrock 또는 Agent Platform으로 모델 요청 보내기를 참조하세요.

기업 이그레스 프록시가 지원됩니다. 러너와 선택 사항인 자동 확장 오케스트레이터는 HTTPS_PROXY 및 NO_PROXY 같이 네트워크 구성에 설명된 프록시 및 mTLS 환경 변수를 따르며, 이 변수는 각 프로세스의 환경에 설정합니다. 이 변수는 컨트롤 플레인 호출, 오케스트레이터의 SCM 커넥터 WebSocket, HTTPS 원격 저장소에 대한 기본 제공 클론에 적용되며, 세션은 러너로부터 이 변수를 상속합니다. 세션 스트리밍은 HTTPS를 통한 서버 전송 이벤트를 사용하므로, 경로상의 프록시는 응답을 버퍼링해서는 안 됩니다.

프록시에 Proxy-Authorization 헤더도 필요한 경우, 러너가 프록시로 여는 각 연결에 해당 헤더를 추가할 수 있습니다. 이그레스 프록시에 인증하기를 참조하세요.

인프라에 남아 있는 것

저장소 체크아웃, 빌드 아티팩트, 시크릿 및 세션이 생성하거나 수정하는 모든 파일은 프로비저닝한 머신에 남아 있습니다. 대화 자체(프롬프트, 응답 및 도구 결과 포함)는 api.anthropic.com으로 이동하며, Anthropic은 다른 지원되는 사용 환경에서 세션을 재개할 수 있도록 세션 트랜스크립트를 저장합니다. 러너가 Amazon Bedrock 또는 Google Cloud의 Agent Platform으로 모델 요청을 보내는 경우에도 대화는 여전히 세션의 이벤트 스트림을 통해 api.anthropic.com으로 이동합니다.

자체 호스팅 환경은 세션 실행을 네트워크로 이동합니다. 제어 평면은 Anthropic 호스팅입니다: 세션 오케스트레이션, 큐잉 및 claude.ai 인터페이스는 Anthropic의 인프라에서 계속 실행됩니다.

시작하기

자체 호스팅 환경 페이지는 수행 중인 작업별로 구성됩니다:

  • 빠른 시작: Claude Code 설치, 환경 생성, 러너 시작 및 첫 번째 세션 라우팅
  • 프로덕션에 배포: 보안 강화, 네트워크 이그레스, git 자격 증명, Kubernetes 및 Compose 레시피, 알려진 문제 및 문제 해결
  • 세션 사용자 정의: 세션별 자격 증명, 수명 주기 훅, 온디맨드 러너, MCP 서버 및 권한에 대한 래퍼 스크립트
  • 엔드 투 엔드 테스트: 러너 이미지를 프로모션하기 전에 검증하는 CI 스모크 테스트
  • 참조: 모든 CLI 플래그, 환경 변수, 메트릭 및 상태 엔드포인트
  • 세션 ID 검증: 액세스를 부여하기 전에 자신의 서비스에서 세션 토큰을 검증합니다.