Claude Managed Agents를 내 서버에서 돌리는 ‘셀프 호스팅’ 공개 — 구성과 시작 방법

앤트로픽이 11월 12일 Claude Managed Agents를 회사 인프라에서 통째로 운영하는 ‘셀프 호스팅’ 방식을 공개했어요. 지금까지는 도구가 실행되는 샌드박스만 직접 둘 수 있었는데, 이제 API 서버, 에이전트 루프, 세션 기록 저장소까지 내 쪽에 둘 수 있어요. 다운로드는 앤트로픽 계정 팀에 요청해야 받을 수 있어요.

무엇이 바뀌었나요

공식 문서는 Managed Agents를 두 부분으로 나눠요. 에이전트의 셸·파일 도구가 실제로 돌아가는 샌드박스, 그리고 API·에이전트 루프·저장소를 맡는 서비스예요. 선택지는 세 가지가 됐어요.

  • 클라우드 샌드박스(기본): 샌드박스, 서비스, 모델 모두 앤트로픽.
  • 셀프 호스팅 샌드박스: 샌드박스만 내가, 서비스와 모델은 앤트로픽.
  • 셀프 호스팅 Managed Agents(이번 발표): 샌드박스와 서비스를 내가, 모델은 앤트로픽 또는 내가 고른 제공자.

모델 제공자로는 Claude API 말고도 Amazon Bedrock, Google Cloud의 Claude 모델(Google 관리형), Microsoft Foundry, 자체 모델 게이트웨이를 고를 수 있어요. 문서는 “에이전트·세션 기록을 직접 저장해야 하거나, 모델 호출을 특정 클라우드로 보내야 할 때” 이 방식을 고르라고 해요. 도구만 내부망에서 돌리면 되는 경우는 기존 셀프 호스팅 샌드박스로 충분하다고 해요.

구성 요소

  • 서버(cma-server): API를 제공하고 에이전트 루프를 돌리며, 에이전트·세션·기록을 저장해요. 셸이나 파일 도구는 직접 실행하지 않아요.
  • 데이터베이스: PostgreSQL 16 이상. 데이터베이스가 없으면 메모리에만 저장해서 재시작하면 사라져요.
  • 워커: 서버에서 작업을 가져와 샌드박스 안에서 도구를 실행해요. ant beta:worker 명령이나 SDK 워커로 띄워요.
  • 관리 CLI(cma-server-admin): 환경과 환경 키를 만들어요.
  • 서버 주소에서 열리는 웹 콘솔도 있는데, 사내 SSO(OpenID Connect)로 로그인해요.

인증 정보는 세 가지로 나뉘어요. 앱이 서버를 부를 때 쓰는 서버 API 키, 서버만 갖는 추론 자격 증명(예: Claude API 키), 워커가 쓰는 환경 키예요.

Docker Compose로 시작하기

공식 퀵스타트는 한 대의 머신에서 Docker Compose로 서버, PostgreSQL, 워커를 함께 띄워요. 필요한 것은 릴리스 압축 파일, Claude API 키, 최신 Docker Engine과 Compose 플러그인, CPU 2개 이상, openssl, ant CLI예요. 문서에 나온 순서를 줄여 옮기면 이래요.

tar -xzf <archive>.tar.gz && cd <archive>/compose

cat > .env <<EOF
CMA_PG_PASSWORD=$(openssl rand -hex 32)
ANTHROPIC_API_KEY=sk-ant-...
CMA_SERVER__API_KEY=$(openssl rand -hex 32)
CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
EOF
chmod 600 .env

docker compose up --build -d
curl -s http://127.0.0.1:8400/cma-server/readyz

준비가 끝나면 "status":"ready"가 돌아와요. 그다음 다른 터미널에서 ant CLI가 내 서버를 보도록 바꿔요. 이때 ANTHROPIC_API_KEY에는 Claude API 키가 아니라 서버 API 키를 넣어요.

export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)
ant apply --yes quickstart-agent.md

문서는 같은 터미널에서 docker compose up을 실행하면 이 변수가 서버로 넘어가 서버가 자기 자신을 부르게 된다고 경고해요. 세션을 열고 에이전트에게 hostname을 실행하게 하면 cma-sandbox-로 시작하는 이름이 나오고, 도구가 샌드박스 컨테이너 안에서 돌았다는 뜻이에요. 이 글의 명령은 공식 문서를 옮긴 것이고, 다운로드 권한이 없어 직접 실행해 보지는 않았어요.

호스팅 서비스와 다른 점

  • 없는 기능: 클라우드 환경(오직 self_hosted 환경만), Messages API·Models API, Files API와 파일 리소스, mcp_oauth 자격 증명, 기본 제공 docx·pdf·pptx·xlsx 스킬, 예약 실행, dreams, 웹훅.
  • 설정해야 켜지는 기능: MCP 서버는 mcp.allowed_hostnames, Git 저장소는 git.allowed_hostnames와 푸시 가능한 브랜치 목록, 웹 검색·가져오기는 web_tools.enabled를 켜야 해요. 문서는 서버가 강제 푸시를 막지 않으니 브랜치 보호는 Git 호스트에서 하라고 해요.
  • 멀티 에이전트: type이 coordinator인 방식만 되고, 어드바이저와 동적 워크플로는 안 돼요.
  • URL로 보낸 이미지·문서: 오류 없이 받아들이지만 모델은 보지 못해요. base64로 보내야 해요.
  • 호스팅 서비스의 데이터는 넘어오지 않아요. 에이전트, 스킬, 자격 증명을 새로 만들어야 해요.

쓰기 전에 알아 둘 점

문서는 에이전트의 bash 도구가 워커 프로세스 권한을 그대로 갖는 실제 셸이라고 강조해요. 격리는 워커를 어디서 띄우느냐에 달려 있어서, 직접 띄운다면 버려도 되는 컨테이너나 VM에서 돌려야 해요. Compose 구성은 개발용이고, 운영에는 Helm 차트를 쓰라고 해요. 또 모델 호출마다 대화 내용과 도구 입출력이 추론 제공자로 나간다는 점도 명시돼 있어요.

출처: Claude Platform 릴리스 노트, Self-hosted Claude Managed Agents, 퀵스타트, 호스팅 서비스와의 차이

Similar Posts