클로드 매니지드 에이전트 셀프호스팅 공개: 신청 조건과 달라지는 점

클로드 매니지드 에이전트 셀프호스팅은 에이전트 서비스 전체를 내 서버나 클라우드 계정에서 돌리는 방식이다. Anthropic은 2026년 11월 12일 Claude Platform 릴리스 노트에서 이 방식을 공개했다. 기존에는 도구가 실행되는 샌드박스만 직접 운영할 수 있었는데, 이제 에이전트·세션·대화 기록을 저장하는 서비스까지 내 인프라로 옮길 수 있다. 쓰려면 공식 문서의 안내대로 Anthropic 담당 팀(account team)에 접근을 요청해야 한다.

클라우드, 셀프호스팅 샌드박스, 셀프호스팅 매니지드 에이전트 차이

매니지드 에이전트는 호스팅할 수 있는 부분이 둘이다. 하나는 에이전트의 도구가 명령을 실행하고 파일을 다루는 샌드박스(컨테이너나 가상 머신 같은 격리 작업 공간)이고, 다른 하나는 API와 에이전트 루프, 에이전트·세션·세션 기록 저장소를 합친 서비스다. 공식 문서의 비교표를 우리말로 옮기면 다음과 같다.

방식	샌드박스	서비스	모델
클라우드 샌드박스(기본)	Anthropic	Anthropic	Anthropic
셀프호스팅 샌드박스	내가	Anthropic	Anthropic
셀프호스팅 매니지드 에이전트	내가	내가	Anthropic 또는 내가 고른 제공자

셀프호스팅 샌드박스는 2026년 5월 19일 릴리스 노트에 먼저 올라왔다. 이번 발표는 그 위에 서비스까지 얹은 것이다. 서버가 도구를 직접 실행하지는 않는다. 서버는 에이전트 루프를 돌리고 모델을 부르며, 도구 실행은 내가 운영하는 워커(작업을 받아 샌드박스에서 실행하는 프로그램)가 맡는다.

클로드 매니지드 에이전트 셀프호스팅을 고르는 경우

공식 문서가 꼽는 이유는 두 가지다. 첫째는 에이전트, 세션, 세션 기록을 내 인프라에 저장해야 하는 경우다. 둘째는 모델 호출을 Amazon Bedrock, 구글 클라우드의 클로드 모델(Google 관리형), Microsoft Foundry, 또는 직접 만든 모델 게이트웨이로 보내야 하는 경우다. 도구만 내 인프라에서 돌리면 충분하다면 Anthropic이 서비스를 운영하는 셀프호스팅 샌드박스를 쓰라고 환경 선택 가이드가 안내한다.

데이터가 어디로 나가는지는 따로 봐야 한다. 서버는 모델을 부를 때마다 지금까지의 대화와 도구 입력·결과를 모델 제공자에게 보낸다. 기본 제공자는 Claude API라서, 제공자를 바꾸지 않으면 대화 내용이 여전히 Anthropic에 간다. 저장 위치가 내 쪽으로 바뀌는 것이지 모델 호출 데이터가 모두 내부에 머무는 것은 아니다.

운영 부담도 커진다. 서버, 데이터베이스, 샌드박스를 직접 운영하고 보안을 책임지며, 새 릴리스가 나오면 직접 설치해야 한다. 공식 보안 경고에 따르면 에이전트의 bash 도구는 워커 프로세스의 권한과 네트워크 접근을 가진 진짜 셸이다. 워커는 이 셸을 격리하지 않으므로, 워커를 직접 띄운다면 지켜야 할 것이 없는 일회용 컨테이너나 가상 머신에서 돌려야 한다.

서버 구성과 자격 증명 세 가지

배포 하나는 서버(cma-server), 데이터베이스, 워커로 이루어진다. 데이터베이스는 PostgreSQL 16 이상이고, 데이터베이스 없이 띄우면 서버가 데이터를 메모리에만 두어 재시작하면 모두 지워진다. 관리자용 명령줄 도구 cma-server-admin은 환경과 환경 키를 만들며 리눅스(x86-64, Arm)와 애플 실리콘 맥에서 돈다. 서버 주소의 웹 화면(콘솔)에서는 회사의 로그인 제공자로 들어가 에이전트를 만들고 세션을 돌릴 수 있다.

자격 증명	누가 갖나	무엇을 인증하나
서버 API 키	내 애플리케이션, ant 명령줄 도구, 관리자 도구	내 서버로 가는 요청. 설치 때 생성된다.
추론 자격 증명	서버	모델 제공자로 가는 서버의 호출. Claude API 키나 클라우드 자격 증명 등.
환경 키	서버에서 일감을 가져가는 워커	한 환경의 작업 대기열과 그 환경의 세션.

호스팅 서비스와 달라지는 점

서버 API는 Anthropic이 운영하는 서비스와 같아서 SDK와 ant 명령줄 도구가 그대로 동작한다. 다만 차이 문서가 예외를 길게 적고 있다. 가장 먼저 알아야 할 점은 기존 호스팅 서비스의 데이터가 복사되지 않는다는 것이다. 에이전트, 스킬, 금고(vault) 자격 증명, 메모리 저장소를 내 서버에서 다시 만들어야 한다.

기능	셀프호스팅 서버에서	대신 할 일
클라우드 환경	없음. self_hosted 환경만 있고 클라우드 환경을 요청하면 400 오류	모든 환경에 셀프호스팅 워커 배포
Messages API, Models API	서버가 제공하지 않음(404)	Claude API나 제공자로 따로 호출
파일 세션 리소스, Files API	없음	워커 작업 디렉터리에 파일을 두거나 base64로 전달
예약 배포, 드림	경로 없음	cron 같은 자체 스케줄러로 세션 시작. 드림은 대체 수단 없음
웹훅	서버가 보내지 않음	이벤트 스트림을 따라가거나 이벤트 목록 조회
mcp_oauth 금고 자격 증명	등록 거부	static_bearer로 저장하고 만료 전에 갱신
docx·pdf·pptx·xlsx 기본 스킬	선언한 에이전트를 거부	스킬 저장소에서 받아 커스텀 스킬로 업로드

꺼진 채 시작하는 기능도 있다. 공식 문서가 설정 방법을 안내한다. MCP 서버는 설정 파일의 mcp.allowed_hostnames에 호스트를 적어야 연결되고 기본 목록은 비어 있다. 호스트는 와일드카드 없이 정확히 일치해야 한다. 웹 검색·웹 가져오기 도구는 web_tools.enabled: true를 켜기 전까지 꺼져 있고, 꺼진 동안 도구 항목이 없는 에이전트는 오류 없이 도구 없이 돈다. 깃 저장소 리소스는 git.allowed_hostnames와 푸시 허용 브랜치(git.allowed_push_refs)를 적어야 한다. 서버는 강제 푸시를 막지 않으므로, 막으려면 깃 호스트에서 브랜치를 보호해야 한다.

모델 제공자에 따라서도 달라진다. 웹 검색 도구는 anthropic, vertex, foundry 제공자에서만, 웹 가져오기는 anthropic과 foundry에서만 모델에 노출된다. 다른 제공자에서는 에이전트가 저장되고 실행되지만 모델이 그 도구를 부를 수 없다. 이런 경우 공식 문서는 검색용 커스텀 도구나 MCP 서버를 붙이라고 안내한다.

모델 호출 제공자 바꾸기

추론 제공자 문서에서 설정 파일의 inference.provider 값은 다섯 가지다.

값	모델 호출이 가는 곳	서버가 쓰는 인증
anthropic(기본)	Claude API	ANTHROPIC_API_KEY
bedrock	Amazon Bedrock	AWS 자격 증명
vertex	구글 클라우드의 클로드 모델(Google 관리형)	Google 기본 애플리케이션 자격 증명
foundry	Microsoft Foundry	Foundry API 키 또는 Microsoft Entra ID
gateway	내가 운영하는 모델 게이트웨이	게이트웨이가 받는 키나 토큰

에이전트는 claude-opus-5-5 같은 Claude API 모델 ID로 모델을 지정하고, 서버가 제공자에 맞게 번역한다. 클라우드 계정의 모델 ID가 다르면 model_id_overrides로 맞춘다. 설정을 바꾼 뒤 서버를 재시작하고 로그에서 upstream credential resolved 줄이 provider 이름과 함께 찍히는지 본다. 이 줄은 자격 증명을 찾았다는 뜻일 뿐 해당 모델이 계정에서 켜져 있다는 증거는 아니다. 모델이 꺼져 있으면 그 모델을 쓰는 첫 턴에 session.error가 나온다.

기본 제공자인 anthropic에서는 서버가 Claude API의 서버 측 폴백을 기본으로 요청한다. 안전 분류기가 요청을 거절하면 더 낮은 성능일 수 있는 다른 클로드 모델이 대신 답하고, 그 변경을 알리는 이벤트는 없다. 끄려면 inference.model_fallback: false를 설정한다. 다른 제공자에서는 이런 요청이 거절로 끝난다.

첫 실행 순서와 성공 확인

공식 빠른 시작은 도커 컴포즈로 한 대의 컴퓨터에서 서버를 띄운다. 개발용이며, 운영에는 Kubernetes용 Helm 차트를 권장한다. 이 스택은 일반 HTTP를 쓰고 기본으로 포트 8400을 로컬 주소(127.0.0.1)에만 연다.

1. 접근 승인 뒤 받은 릴리스 압축 파일을 풀고 compose 디렉터리로 이동한다.
2. .env 파일에 데이터베이스 비밀번호, 내 Claude API 키, 서버 API 키, 저장 비밀 암호화 키를 넣고 권한을 600으로 한다.
3. docker compose up --build -d를 실행하고 서버 로그에 cma-server listening이 나오길 기다린다.
4. curl -s http://127.0.0.1:8400/cma-server/readyz가 "status":"ready"를 답하면 서버가 준비된 것이다. 시작 직후 몇 초는 degraded일 수 있다.
5. 두 번째 터미널에서 ANTHROPIC_BASE_URL을 http://127.0.0.1:8400으로, ANTHROPIC_API_KEY를 내 서버 API 키(Claude API 키 아님)로 설정한다.
6. ant apply --yes quickstart-agent.md로 에이전트를 만들고, 스택이 만든 compose-sandbox 환경으로 세션을 시작해 ant beta:sessions connect로 채팅을 연다.

내 환경에서 직접 해 볼 확인은 두 가지다. 먼저 readyz 응답이 ready인지 보고, 이어서 에이전트에게 hostname 실행을 시켜 본다. 답이 cma-sandbox-로 시작하는 이름이면 도구가 내 컴퓨터가 아닌 샌드박스 컨테이너에서 돈 것이다. 다른 터미널에서 docker ps --filter label=cma-server.sandbox를 실행하면 같은 컨테이너가 보인다. 도구 호출이 끝나지 않으면 환경을 폴링하는 워커가 없다는 뜻이다. 문제 해결 안내대로 이 스택은 워커 10개를 띄우고, 메시지가 없는 세션도 워커를 최대 1시간 잡고 있으므로 쓰지 않는 세션은 보관(archive)해야 한다.

주의할 실수가 하나 있다. 서버를 띄우는 docker compose를 ANTHROPIC_BASE_URL이 내 서버 주소로 설정된 터미널에서 실행하면 서버가 자기 자신을 모델로 호출해 준비 상태가 계속 degraded에 머문다. 컴포즈 명령은 그 변수를 설정하지 않은 첫 번째 터미널에서만 실행한다.

셀프호스팅 샌드박스만 쓰고 있다면

이미 셀프호스팅 샌드박스를 쓴다면 워커 소프트웨어가 같아서 새 서버에 워커를 붙일 수 있다. 다만 웹훅으로 시작하는 워커는 이 서버에서 동작하지 않는다. 샌드박스 쪽 소식은 5월 19일의 셀프호스팅 샌드박스 공개, 5월 29일의 Claude Platform on AWS 지원, 8월 19일의 메모리 저장소 연결이 있었다. 도구만 내 쪽에서 돌리면 되는 팀은 서버까지 운영하는 부담을 지지 않고 샌드박스 방식에 머무는 편이 단순하다.

클라우드 쪽 기능을 쓰던 팀은 옮기기 전에 다른 글을 먼저 확인하는 것이 좋다. 예약 배포와 다이내믹 워크플로우는 위 표대로 셀프호스팅 서버에서 쓸 수 없다.

자주 묻는 질문

셀프호스팅하면 데이터가 Anthropic에 전혀 가지 않나요?

아니다. 기본 설정에서는 모델을 부를 때마다 대화 내용과 도구 결과가 Claude API로 간다. 보내는 곳을 바꾸려면 Bedrock 같은 다른 제공자나 직접 운영하는 게이트웨이를 설정한다.

기존 호스팅 서비스에서 만든 에이전트를 옮길 수 있나요?

복사되지 않는다. 공식 차이 문서에 따르면 세션 기록을 포함해 아무것도 넘어가지 않으므로, 에이전트·스킬·금고 자격 증명·메모리 저장소를 내 서버에서 새로 만들어야 한다.

운영에는 도커 컴포즈를 써도 되나요?

안 된다. 공식 문서는 컴포즈 스택을 개발용으로 규정하고, 운영에는 릴리스에 들어 있는 Helm 차트 두 개로 Kubernetes에 배포하라고 권장한다.