--- title: 자체 호스팅 Claude Managed Agents의 데이터 및 접근 url: https://platform.claude.com/docs/ko/managed-agents/self-hosted-data-and-access description: 자체 호스팅 Claude Managed Agents가 네트워크 외부로 무엇을 보내는지, 로그, 트레이스 및 메트릭이 어디로 전송되는지, 데이터가 얼마나 오래 보관되는지, 누가 서버에 접근할 수 있는지, 그리고 테넌트를 어떻게 분리하는지 설명합니다. --- 자체 호스팅 Claude Managed Agents에 대한 접근 권한을 요청하려면 Anthropic 계정 팀에 문의하세요. [자체 호스팅 Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/self-hosted)를 사용하면 서버와 해당 데이터베이스, 그리고 워커가 에이전트의 셸 및 파일 도구를 실행하는 샌드박스를 사용자가 직접 운영합니다. 이 페이지는 보안 검토에서 제기되는 질문에 답합니다. 서버의 추론 공급자는 서버의 모델 호출에 응답하는 서비스입니다. 서버는 해당 공급자가 Claude API일 때만 Anthropic에 연결합니다. Anthropic은 서버나 서버 로그에 원격으로 접근할 수 없습니다. ## 네트워크 외부로 전송되는 항목 ### 서버가 만드는 모든 연결 서버는 다음 대상에만 연결합니다: * 추론 공급자 * 서버의 데이터베이스 * 서버의 모델 호출용 자격 증명을 발급하는 서비스(서버가 서비스에서 해당 자격 증명을 받는 경우) * 클라우드 제공업체의 모델 목록 조회 서비스(추론 공급자가 별도의 서비스에서 모델 목록을 제공하는 경우) * 허용한 MCP 서버 * 세션이 사용하는 저장소를 위해 허용한 Git 호스트 * OpenTelemetry 컬렉터(구성한 경우) * 싱글 사인온을 위해 지정한 ID 제공업체(구성한 경우) * 시크릿 매니저 또는 키 관리 서비스(구성한 경우) * 해당 시크릿 매니저 또는 키 관리 서비스에 대한 서버의 자격 증명을 발급하는 서비스 * 서버가 호출하도록 구성한 기타 모든 서비스 기본 추론 공급자는 Claude API입니다. 다른 추론 공급자를 구성하면 모델 호출은 대신 그곳으로 전송됩니다. 서버는 Claude API가 추론 공급자일 때만 Anthropic에 연결합니다. 추론 공급자가 웹 검색 및 웹 가져오기 도구를 제공하는 경우, 추론 공급자가 해당 도구를 실행합니다. 서버는 이를 위해 자체적으로 연결하지 않습니다. 이 도구는 서버 설정에서 직접 활성화하기 전까지 꺼져 있습니다. 서버의 트래픽을 확인하려면 이그레스 프록시 또는 방화벽 로그를 이 목록과 비교하세요. 서버가 Claude API에 보내는 요청에는 `User-Agent` 헤더가 포함됩니다. [서버 소프트웨어를 명시하는 필드](https://platform.claude.com/docs/ko/managed-agents/self-hosted-data-and-access#fields-that-name-the-server-software)를 참조하세요. ### 워커가 접근할 수 있는 대상 이 대상 목록은 서버만을 다룹니다. [이그레스 게이트웨이](https://platform.claude.com/docs/ko/managed-agents/self-hosted/agent-identity#environment-variable-credentials)를 실행하는 경우, 이 게이트웨이는 지정한 호스트에 연결하며 해당 호스트용으로 저장한 자격 증명 값을 그 호스트에 보냅니다. 워커는 별개입니다. 워커는 실행되는 컨테이너, VM 또는 기타 샌드박스에 허용한 네트워크 접근 권한을 그대로 가집니다. 에이전트가 워커를 통해 실행하는 모든 명령도 동일한 네트워크 접근 권한을 가집니다. ### 서버가 추론 공급자에 보내는 내용 각 모델 호출에는 프롬프트, 도구 입력, 도구 결과를 포함하여 지금까지의 대화가 담겨 있습니다. Claude API가 추론 공급자인 경우, 각 모델 호출에는 최대 세 개의 헤더도 포함됩니다. 이 헤더에는 서버가 생성한 ID가 담깁니다: | 헤더 | 담는 내용 | | ----------------------------------------- | --------------- | | `anthropic-managed-agents-session-id` | 호출이 처리하는 세션의 ID | | `anthropic-managed-agents-agent-id` | 해당 세션의 에이전트 ID | | `anthropic-managed-agents-environment-id` | 해당 세션의 환경 ID | ID에는 이름이나 콘텐츠가 담기지 않지만, 서버가 ID를 생성한 시간은 인코딩되어 있습니다. 이 헤더를 통해 Anthropic은 사용량을 세션, 에이전트 또는 환경별로 귀속할 수 있습니다. 이 헤더를 끄는 설정은 없습니다. `ANTHROPIC_BASE_URL`이 프록시나 게이트웨이를 가리키는 경우, 헤더는 그곳으로 전송됩니다. 다른 추론 공급자를 사용하는 경우 서버는 이 헤더를 절대 보내지 않습니다. Claude API가 추론 공급자인 경우, 서버는 또한 모델 호출에 사용하는 자격 증명이 유효한지 Claude API에 확인합니다. 이 확인은 시작 시 수행되며, `health.check_interval`을 변경하지 않는 한 이후 60초마다 수행됩니다. 이러한 확인에서는 추론이 실행되지 않으며, 세 헤더 중 어느 것도 포함되지 않습니다. ### 서버 소프트웨어를 명시하는 필드 Claude API에 대한 모든 요청에는 서버 소프트웨어와 그 버전을 나타내는 `User-Agent` 헤더가 포함됩니다. 헤더 자체는 사용자의 배포를 식별하지 않습니다. 모든 Claude API 요청과 마찬가지로, API 키가 사용자의 조직을 식별합니다. Anthropic은 이 헤더를 사용하여 자체 호스팅 Managed Agents의 사용량을 집계할 수 있습니다. 모델 호출에는 요청 본문의 `metadata.user_id`로 `cma-server` 레이블도 포함될 수 있습니다. 이 레이블은 모든 서버에서 동일하므로 레이블 자체는 사용자의 배포, 사용자, 세션을 식별하지 않습니다. 호출이 Anthropic에 도달하는 경우, 프록시가 `User-Agent` 헤더를 제거했더라도 Anthropic은 이 레이블을 사용하여 자체 호스팅 Managed Agents의 사용량을 집계할 수 있습니다. 호출에 레이블이 포함되는지 여부는 호출이 전송되는 대상에 따라 달라집니다: * **서버가 다음 호출에는 레이블을 보냅니다:** Claude API, Microsoft Foundry, 그리고 Claude API와 동일한 요청을 수락하는 모델 게이트웨이로 보내는 호출. * **서버는 다음 호출에는 `metadata.user_id`를 절대 보내지 않습니다:** Amazon Bedrock, Claude Models on Google Cloud (Google managed), 그리고 다른 요청 형식을 사용하는 모델 게이트웨이로 보내는 호출. 모델 게이트웨이나 프록시가 호출을 다른 공급자에게 전달하는 경우, `metadata.user_id`도 함께 전달될 수 있습니다. `metadata.user_id`가 포함된 호출에서는 사용자가 운영하는 프록시나 게이트웨이가 요청 본문에서 이를 수락해야 합니다. 해당 필드를 거부하면 모든 모델 호출이 실패합니다. ## 로그, 트레이스 및 메트릭의 전송 위치 서버는 로그를 표준 오류에 기록합니다. Docker, Kubernetes 또는 서비스 관리자에서 서버를 실행하는 경우, 해당 시스템이 표준 오류에서 로그를 수집합니다. 서버는 표준 OpenTelemetry 환경 변수로 활성화하기 전까지 트레이스나 메트릭을 기록하지 않습니다. 또한 해당 변수가 가리키는 곳으로만 이를 전송합니다. Prometheus 엔드포인트도 메트릭을 노출할 수 있습니다. [서버가 수신 대기하는 위치](https://platform.claude.com/docs/ko/managed-agents/self-hosted-data-and-access#where-the-server-listens)를 참조하세요. ## 데이터 보관 기간 로그, 트레이스, 메트릭의 보관 기간은 사용자의 로그 파이프라인, 컬렉터, 트레이싱 백엔드가 결정합니다. 서버는 로그 파일을 보관하지 않으며 트레이스나 메트릭을 저장하지 않습니다. 서버는 에이전트, 세션, 세션 기록 등 그 밖의 모든 데이터를 사용자의 데이터베이스에 저장합니다. 기본값대로 데이터베이스를 설정하지 않으면 서버는 해당 데이터를 메모리에 보관하며, 재시작하면 데이터가 삭제됩니다. 시크릿 매니저를 구성하면 서버는 새로 생성되는 각 [볼트 자격 증명](https://platform.claude.com/docs/ko/managed-agents/vaults)의 시크릿을 데이터베이스 대신 시크릿 매니저에 보관합니다. 이전에 저장한 시크릿은 데이터베이스에 그대로 남아 있습니다. 세션과 그 기록은 사용자가 삭제할 때까지 데이터베이스에 유지됩니다. 서버는 아카이브 여부와 관계없이 오래되었다는 이유로 세션을 삭제하지 않습니다. API를 통해 세션을 삭제하면 해당 세션과 그 기록이 데이터베이스에서 제거되지만, 서버는 세션의 ID를 유지합니다. 세션이 실행 중인 동안에는 서버가 삭제를 거부할 수 있습니다. 삭제는 데이터베이스 백업, 내보낸 로그와 트레이스, 에이전트가 [메모리 스토어](https://platform.claude.com/docs/ko/managed-agents/memory)에 기록한 내용 등 다른 곳에 있는 사본에는 적용되지 않습니다. Kubernetes에서는 [세션 볼륨 해제](https://platform.claude.com/docs/ko/managed-agents/self-hosted/kubernetes#free-a-sessions-volume)에 설명된 대로, 삭제 후에도 세션의 `/workspace` 볼륨이 그대로 남습니다. 서버가 모델에 보내는 내용과 모델이 반환하는 내용은 사용자 조직과 모델을 제공하는 공급자 간의 계약이 적용됩니다. 해당 계약의 데이터 보존 조건이 적용됩니다. Claude API가 모델을 제공하는 경우, 사용자 조직이 Anthropic과 맺은 데이터 보존 계약 및 설정이 적용됩니다. 사용자 조직이 [제로 데이터 보존(ZDR)](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope) 방식을 사용하는 경우, 해당 방식은 다른 Messages API 호출과 동일하게 이러한 모델 호출에 적용됩니다. API 및 데이터 보존 페이지에서는 Claude Managed Agents를 [ZDR 적용 대상이 아닌 항목](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#what-zdr-does-not-cover)으로 기재하고 있습니다. 이는 Anthropic이 서비스를 운영하는 경우, Anthropic은 사용자가 세션 기록을 삭제할 때까지 이를 저장하기 때문입니다. 세션 기록을 누가 저장하는지는 서비스를 누가 운영하는지에 따라 달라집니다: * **Anthropic이 운영하는 경우:** Anthropic이 세션 기록을 저장합니다. [자체 호스팅 샌드박스](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes)를 사용하는 경우 사용자는 샌드박스만 호스팅하며, 나머지는 Anthropic이 실행합니다. * **자체 호스팅 Managed Agents로 사용자가 운영하는 경우:** 사용자가 세션 기록을 직접 저장합니다. ## 서버에 접근할 수 있는 주체 Anthropic은 서버나 서버 로그에 원격으로 접근할 수 없습니다. 애플리케이션과 워커가 서버에 연결합니다. 서버는 절대 워커에 연결하지 않습니다. ### 서버가 수락하는 자격 증명 Anthropic은 서버가 수락하는 자격 증명을 하나도 발급하지 않으며, 어떤 자격 증명도 보유하지 않습니다. 서버가 수락하는 모든 자격 증명은 다음 중 하나입니다: * 사용자가 설정하거나 생성한 자격 증명 * 사용자의 ID 공급자가 발급한 자격 증명 * 서버가 작업 단위마다 워커에 전달하는 토큰처럼 서버가 직접 생성한 자격 증명 ### 서버가 수신 대기하는 위치 서버는 하나의 주소와 포트에서 API 요청을 수락합니다. 서버는 두 개의 리스너를 추가로 여는데, 각 리스너는 사용자가 켠 경우에만 열립니다. | 리스너 | 기본 활성화 여부 | 기본 주소 | 요구하는 항목 | | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | API 요청 | 예 | `127.0.0.1:8400`이며, 동일한 머신에서만 접근할 수 있습니다. 주소와 포트를 변경하려면 `server.addr`를 설정하세요. | [서버가 수락하는 자격 증명](https://platform.claude.com/docs/ko/managed-agents/self-hosted-data-and-access#credentials-that-the-server-accepts)을 참조하세요. | | 웹 페이지인 [서버의 콘솔](https://platform.claude.com/docs/ko/managed-agents/self-hosted/console) | 예. 제공을 중단하려면 [콘솔 끄기](https://platform.claude.com/docs/ko/managed-agents/self-hosted/console#turn-off-the-console)를 참조하세요. | API 요청과 동일한 주소 및 포트 | 페이지를 불러오는 데는 접근할 수 있는 누구에게도 아무것도 요구하지 않습니다. 콘솔에서 작업을 수행하려면 ID 제공업체를 통해 로그인해야 합니다. | | Prometheus 메트릭 엔드포인트 | 아니요 | `localhost:9464`이며, 동일한 머신에서만 접근할 수 있습니다 | 자격 증명 없음 | | [이그레스 게이트웨이](https://platform.claude.com/docs/ko/managed-agents/self-hosted/agent-identity#environment-variable-credentials)용 서버 리스너 | 아니요 | 모든 인터페이스의 포트 8410 | 게이트웨이의 키 | 마지막 두 리스너에 대한 자세한 내용은 다음과 같습니다: * **Prometheus 메트릭 엔드포인트:** 자격 증명을 요구하지 않으므로, 누가 접근할 수 있는지는 수신 대기 위치에 따라 달라집니다. `OTEL_METRICS_EXPORTER`를 `prometheus`로 설정하고 주소를 설정하지 않으면 기본 주소에서 수신 대기합니다. 서버 Helm 차트를 통해 켜면 모든 서버 파드의 포트 9464에서 수신 대기합니다. 이 경우 NetworkPolicy가 해당 트래픽을 차단하지 않는 한, 파드 주소로 가는 경로가 있는 모든 대상이 이 엔드포인트에 접근할 수 있습니다. * **이그레스 게이트웨이용 리스너:** 이그레스 게이트웨이는 샌드박스와 인터넷 사이에 있는 선택적 프록시입니다. 서버는 별도의 포트에서 게이트웨이를 위해 수신 대기합니다. 이 리스너는 일반 HTTP로 통신하며, 응답에는 저장된 자격 증명 값이 담깁니다. Compose 스택과 서버 Helm 차트는 게이트웨이만 이 리스너에 접근할 수 있도록 합니다. 다른 방식으로 서버를 실행하는 경우에도 동일하게 설정하세요. Docker Compose 스택은 Docker 호스트의 루프백 주소인 `127.0.0.1`에 포트 8400을 게시합니다. Docker Engine 28.3.3 이상을 실행하세요. 일부 이전 릴리스에서는 호스트의 로컬 네트워크에 있는 머신이 루프백에 게시된 포트에 접근할 수 있습니다. 포트를 다른 주소에 게시하려면 `.env`에서 `CMA_PUBLISH_ADDRESS`를 설정하세요. ## 멀티테넌시 각 배포는 하나의 신뢰 수준에서 하나의 “tenant”(테넌트)를 제공합니다. 한 배포 내의 환경들은 신뢰 수준을 분리하지 않습니다. 서버 API 키는 모든 환경에 접근할 수 있습니다. 역할이 있는 모든 호출자는 모든 환경에서 세션을 실행할 수 있고, 해당 환경의 워커가 접근할 수 있는 모든 네트워크와 파일에 도달할 수 있습니다. | 분리 대상 | 방법 | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 테넌트 | 각 테넌트에 자체 데이터베이스, 서버 API 키, 워커를 갖춘 별도의 배포를 제공하세요. | | 신뢰 수준이 다른 워크로드 | 각 신뢰 수준에 테넌트와 동일한 방식으로 설정한 별도의 배포를 제공하세요. 예를 들어 신뢰할 수 있는 코드와 신뢰할 수 없는 코드, 또는 일부 호출자만 사용할 수 있는 시스템에 접근하는 워커가 있습니다. | | 한 배포 내의 호출자 | [싱글 사인온](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configure#single-sign-on)을 켜고, 그룹을 `developer` 또는 `user` 역할에 매핑하며, 서버 API 키는 관리자용으로만 보관하세요. [각 역할의 권한](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configure#what-each-role-can-do)에서 해당 호출자가 볼 수 있는 항목을 확인할 수 있습니다. | ### 시크릿 매니저, 싱글 사인온 및 모델 게이트웨이 배포에서 다음 서비스 중 하나를 사용하는 경우, 해당 서비스에서도 배포를 분리하세요: * **시크릿 매니저:** [시크릿 매니저 제한 사항](https://platform.claude.com/docs/ko/managed-agents/self-hosted/agent-identity#limits)에 설명된 대로 배포 간 시크릿을 분리하세요. * **싱글 사인온:** 각 배포에 다른 배포가 나열하지 않는 `audiences` 항목을 지정하여 다른 배포의 토큰을 거부하도록 하세요. 각 신뢰 수준의 배포에서는 해당 수준에서 허용된 호출자에게만 역할을 부여하고, `default_role`은 설정하지 마세요. * **[모델 게이트웨이](https://platform.claude.com/docs/ko/managed-agents/self-hosted/inference-provider#model-gateway):** 배포를 구분하려면, `inference.headers` 아래에서 `x-tenant-id`와 같은 헤더에 배포마다 고유한 값을 지정하세요. ### 역할이 제한하지 않는 항목 역할은 호출자가 자신의 토큰으로 보내는 요청만 제한합니다. 에이전트가 실행하는 코드는 해당 샌드박스가 보유한 모든 자격 증명으로 서버를 호출할 수 있습니다. [환경 키](https://platform.claude.com/docs/ko/managed-agents/self-hosted#the-three-credentials)는 해당 환경의 모든 세션에서 이벤트를 읽고 도구 결과를 게시할 수 있습니다. 따라서 각 세션을 자체 샌드박스에서 실행하고, 환경 키는 해당 샌드박스 밖에 두세요. [자체 호스팅 Claude Managed Agents 시작하기](https://platform.claude.com/docs/ko/managed-agents/self-hosted/quickstart)와 [Kubernetes에 배포하기](https://platform.claude.com/docs/ko/managed-agents/self-hosted/kubernetes)의 스택은 이렇게 구성되어 있습니다.