자체 호스팅 Claude Managed Agents 시작하기

이 빠른 시작 가이드에서는 Docker Compose를 사용하여 한 대의 머신에서 자체 호스팅 Claude Managed Agents를 시작합니다. Compose 스택은 서버, 서버의 PostgreSQL 데이터베이스, 그리고 각 세션을 자체 샌드박스 컨테이너에서 실행하는 워커 집합으로 구성됩니다. 그런 다음 터미널에서 에이전트와 대화하고, 에이전트의 도구 호출이 샌드박스 컨테이너에서 실행되었는지 확인합니다. 그런 다음 서버의 콘솔에서 세션을 열 수 있습니다.

프로덕션의 경우 Anthropic은 릴리스에 포함된 두 개의 Helm 차트를 권장합니다. Kubernetes에 배포하기를 참조하세요.

사전 요구 사항

• 릴리스 아카이브: 다운로드 접근 권한을 요청하려면 Anthropic 계정 팀에 문의하세요.
• Claude API 키: 서버가 모델 호출에 사용합니다. Claude Console에서 생성하세요.
• Docker: Docker Engine 최신 버전과 Compose 플러그인(이전 버전의 docker-compose가 아닌 docker compose).
• CPU가 2개 이상인 호스트: x86-64 또는 Arm. 더 작은 호스트에서는 .env를 생성할 때 CMA_SANDBOX_CPUS를 해당 호스트의 CPU 수로 설정하세요.
• 첫 시작 시 네트워크 접근: 첫 빌드에서는 Docker Hub, Alpine 패키지 저장소, GitHub 릴리스에서 항목을 가져옵니다.
• 도구: Docker를 실행하는 머신에 openssl과 ant CLI가 필요합니다.

스택 시작하기

1. 1

   아카이브 압축 해제

   아카이브를 압축 해제하고, 해당 아카이브의 compose 디렉터리에서 작업하세요. 명령에서 <archive>를 .tar.gz를 제외한 아카이브 이름으로 바꾸세요.

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

   

   umask가 022보다 엄격하면 바이너리가 다른 사용자에 대한 실행 권한을 잃어 서버 컨테이너가 바이너리를 시작할 수 없습니다. 이 경우 umask를 022로 설정하고 아카이브를 다시 압축 해제하세요.

2. 2

   .env 파일 생성

   Compose는 docker-compose.yml과 같은 위치에 있는 .env 파일에서 스택의 시크릿을 읽습니다. 파일을 생성하세요:

   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

   

   편집기에서 .env를 열고 sk-ant-...를 Claude API 키로 바꾸세요. 나머지는 이 블록이 생성합니다: 데이터베이스 비밀번호, 애플리케이션이 보내는 서버 API 키, 그리고 서버에 저장된 시크릿을 암호화하는 키입니다.

3. 3

   컨테이너 시작

   스택을 빌드하고 시작한 다음 서버의 로그를 추적하세요:

   docker compose up --build -d
   docker compose logs -f cma-server

   

   로그에 msg="cma-server listening"이 포함된 줄이 표시되면 Ctrl+C를 눌러 로그 추적을 중지하세요.

4. 4

   서버 준비 상태 확인

   curl -s http://127.0.0.1:8400/cma-server/readyz

   

   준비된 서버는 "status":"ready"로 응답합니다. 시작 직후에는 첫 검사가 실행되는 몇 초 동안 "status":"degraded"로 응답할 수 있습니다. 계속 degraded 상태로 남아 있거나 "status":"not_ready"로 응답하면 문제 해결을 참조하세요.

첫 세션 실행

ant CLI를 사용하여 터미널에서 에이전트를 생성하고 대화합니다.

1. 1

   CLI가 서버를 가리키도록 설정하기

   같은 디렉터리에서 두 번째 터미널을 열고 ant 전용으로 사용하세요. 자체 호스팅 서버에서 API 호출하기에서 설명하는 것처럼, 다음 명령은 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)

   

   docker compose 명령은 첫 번째 터미널에서 실행하세요. 이 터미널에서 docker compose up을 실행하면 Compose가 이 변수들을 서버에 전달하며, 서버는 Claude API 대신 자기 자신을 호출합니다.

2. 2

   에이전트 생성

   명령 다음에 나오는 파일을 quickstart-agent.md로 저장한 다음 명령을 실행하세요. 이 파일은 에이전트에게 내장 도구를 제공하고, 먼저 사용자에게 묻지 않고 도구를 실행할 수 있도록 합니다.

   CLI

   

   ant apply --yes quickstart-agent.md

   quickstart-agent.md

   

   ---
   name: Quickstart agent
   model: claude-opus-5-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful assistant.

   이 명령은 먼저 404 오류와 함께 could not determine the organization and workspace라는 경고를 출력한 다음 에이전트를 생성합니다. 자체 서버에서는 예상된 동작입니다.

3. 3

   세션 시작

   다음 명령은 에이전트와 스택의 환경을 찾아 세션을 시작하고, 세션의 ID를 SESSION_ID에 저장합니다. 스택은 환경 이름을 compose-sandbox로 지정합니다.

   AGENT_ID=$(ant beta:agents list --format raw \
     --transform 'data.#(name=="Quickstart agent").id' --raw-output)
   ENVIRONMENT_ID=$(ant beta:environments list --format raw \
     --transform 'data.#(name=="compose-sandbox").id' --raw-output)
   SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \
     --environment-id "$ENVIRONMENT_ID" --transform id --raw-output)

   
4. 4

   에이전트에게 명령 실행 요청

   터미널을 세션에 연결하세요:

   ant beta:sessions connect "$SESSION_ID"

   

   이 명령은 세션의 채팅 뷰를 엽니다. 다음 메시지를 보내세요:

   Run `hostname` with the bash tool and tell me the output.

   

   에이전트는 cma-sandbox-로 시작하는 호스트 이름으로 응답합니다. 이는 명령을 실행한 샌드박스 컨테이너의 이름으로, 도구가 사용자의 머신이 아닌 샌드박스에서 실행되었음을 확인해 줍니다.

5. 5

   샌드박스 컨테이너 찾기

   채팅은 열어 두세요. 첫 번째 터미널에서 샌드박스 컨테이너 목록을 확인하세요:

   docker ps --filter label=cma-server.sandbox

   

   목록에 에이전트가 보고한 컨테이너가 표시됩니다. 컨테이너는 턴이 끝나고 약 1분 후에 종료되며, 세션의 다음 메시지는 새 컨테이너를 시작합니다. 목록이 비어 있으면 에이전트에게 hostname을 다시 실행하도록 요청하고, 에이전트가 응답하는 동안 컨테이너 목록을 다시 확인하세요.

   채팅을 종료하려면 해당 터미널에서 Ctrl+C를 누르세요. 세션은 계속 실행됩니다.

서버에서 콘솔 사용해 보기

이 섹션은 선택 사항입니다. 콘솔에는 single sign-on이 필요합니다. 콘솔을 사용해 보려면 릴리스의 모의 로그인 공급자로 스택을 다시 시작하세요. 머신의 포트 8080이 사용 중이 아니어야 합니다.

1. 1

   모의 로그인 공급자로 스택 다시 시작

   첫 번째 터미널에서 다음 명령을 실행하세요:

   export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml
   docker compose up --build -d

   

   export 줄은 첫 번째 터미널에만 적용되므로, docker compose를 위해 새로 여는 모든 터미널에서 이 줄을 다시 실행하세요. 이 스택에서 서버의 설정을 변경하려면 compose.config.yaml이 아니라 compose.config.oidc.yaml을 편집한 다음 docker compose restart cma-server를 실행하세요.

2. 2

   세션 열기

   같은 머신의 브라우저에서 http://127.0.0.1:8400/을 열고 Continue with SSO를 클릭한 다음 데모 관리자인 alice를 선택하세요. 사이드바에서 Sessions를 선택한 다음 세션을 선택하세요.

   페이지는 에이전트가 작업하는 동안 업데이트되며, 이 페이지에서 에이전트에게 메시지를 보낼 수 있습니다.

콘솔에서도 에이전트를 생성하고 세션을 시작하려면 콘솔에서 에이전트 실행하기를 참조하세요.

스택 중지하기

첫 번째 터미널에서 다음 명령을 실행하세요:

docker compose down --remove-orphans

이 명령은 컨테이너를 삭제하고 데이터베이스는 유지합니다. 데이터베이스와 그 안의 모든 에이전트, 세션, 세션 기록까지 삭제하려면 docker compose down --remove-orphans -v를 실행하세요.

문제 해결

• 아카이브에 compose 디렉터리가 없는 경우: 아카이브에 이전 릴리스가 들어 있으며, 이 페이지의 명령이 해당 릴리스와 맞지 않습니다. Anthropic 계정 팀에 현재 릴리스를 요청하세요. 실행 중인 배포를 현재 릴리스로 옮기려면 자체 호스팅 Claude Managed Agents 업그레이드를 참조하세요.
• 서버가 시작되지 않는 경우: docker compose logs migrate를 실행하세요. 일회성 migrate 컨테이너가 데이터베이스 테이블을 생성합니다. 서버가 시작되기 전에 이 컨테이너가 상태 0으로 종료되어야 합니다.
• 준비 상태 검사가 계속 degraded로 남아 있거나 모든 턴이 실패하는 경우: ANTHROPIC_BASE_URL이 http://127.0.0.1:8400인 터미널에서 docker compose up을 실행했다면, 서버는 Claude API 대신 자기 자신을 호출합니다. 해당 변수가 설정되지 않은 첫 번째 터미널에서 docker compose up -d를 다시 실행하세요. 그렇지 않다면 서버 로그에 무엇이 실패했는지 표시됩니다. 로그를 읽으려면 docker compose logs -f cma-server를 다시 실행하세요.
• 준비 상태 검사가 not_ready로 응답하는 경우: 응답에서 상태가 failed인 검사를 찾으세요:
  • upstream: Claude API가 Claude API 키를 거부했습니다. .env에서 ANTHROPIC_API_KEY를 수정한 다음 첫 번째 터미널에서 docker compose up -d를 다시 실행하세요. 셸에서도 ANTHROPIC_API_KEY를 설정하고 있다면 Compose는 셸의 값을 사용하므로, 먼저 unset ANTHROPIC_API_KEY를 실행하세요.
  • database: 데이터베이스가 서버의 로그인을 거부했거나(예를 들어 비밀번호가 잘못된 경우), 데이터베이스에 대한 열린 연결이 끊어졌습니다. 어느 쪽인지 확인하려면 docker compose logs -f cma-server를 다시 실행하세요.
• 에이전트는 응답하지만 도구 호출이 끝나지 않는 경우: 해당 환경을 폴링하는 워커가 없는 것입니다. docker compose logs sandbox로 워커 로그를 확인하세요. Docker 데몬의 소켓에 연결할 수 없는 워커는 CMA_DOCKER_SOCKET을 언급하는 메시지와 함께 종료됩니다. .env에서 해당 변수를 데몬의 소켓 경로로 설정한 다음 첫 번째 터미널에서 docker compose up -d를 다시 실행하세요.
• 워커가 실행 중인데도 도구 호출이 끝나지 않는 경우: 스택은 10개의 워커를 시작하며, 각 워커는 한 번에 한 세션의 컨테이너를 실행합니다. 세션은 생성될 때 유휴 워커를 하나 차지하며, 메시지를 한 번도 받지 않은 세션은 최대 1시간 동안 워커를 유지합니다. 10개가 모두 사용 중이면 다른 세션의 도구 호출은 워커를 기다립니다. "샌드박스 컨테이너 찾기" 단계의 docker ps 명령이 10개의 컨테이너를 표시한다면, 사용하지 않는 세션을 보관하세요:
  1. 첫 번째 터미널에서 docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'를 실행하세요. 각 컨테이너에 해당하는 세션의 ID가 출력됩니다. 대기 중인 세션은 아직 컨테이너가 없으므로 목록에 나타나지 않습니다.
  2. 두 번째 터미널에서 Ctrl+C를 눌러 채팅을 종료하고, 목록에 있는 세션 중 사용하지 않는 각 세션에 대해 ant beta:sessions archive --session-id <session-id>를 실행하세요.
  3. ant beta:sessions connect "$SESSION_ID"를 다시 실행하세요. 워커가 해당 세션을 차지하면 도구 호출이 완료됩니다.

다음 단계