Managed Agents엔터프라이즈 구성

구성 레퍼런스

자체 호스팅 Claude Managed Agents 서버의 설정 위치를 확인하고, 각 설정의 키, 환경 변수, 기본값 및 용도를 조회하세요.

이 페이지에서는 자체 호스팅 Claude Managed Agents 서버의 설정 위치를 보여 주고, 설정을 나열합니다. 기능을 설정하려면 싱글 사인온, 에이전트 ID 및 자격 증명, 추론 프로바이더를 참조하세요.

설정 위치

서버는 하나의 YAML 파일에서 설정을 읽고, 환경에서 자격 증명을 읽습니다.

Docker Compose: 파일은 압축을 푼 아카이브에서 docker-compose.yml 옆에 있는 compose.config.yaml입니다. 파일을 편집한 다음 해당 디렉터리에서 docker compose restart cma-server을 실행하세요.
Kubernetes: 파일은 서버 Helm 차트의 server.config 값입니다. values 파일에서 편집하고 helm upgrade를 실행한 다음, kubectl -n cma-server rollout restart deployment -l anthropic.com/role=server으로 서버를 재시작하세요. Kubernetes에 배포하기를 참조하세요.

서버가 자체 호스팅 페이지에 나와 있는 설정을 거부하면 서버를 업그레이드하세요. 아카이브 최상위에 있는 cma-server.example.yaml에는 일반적인 키에 대한 주석이 달려 있습니다.

자격 증명은 절대 파일에 넣지 않습니다. 서버는 환경 변수 또는 클라우드가 호스트에 연결하는 ID에서 자격 증명을 읽습니다.

Compose 스택에 자격 증명 전달하기

Compose 스택에서 서버 컨테이너는 docker-compose.yml에 있는 cma-server 서비스의 environment: 목록에 있는 변수만 받습니다. 다른 변수를 전달하려면 다음과 같이 하세요:

해당 목록에 변수 이름을 추가하고, .env에서 값을 설정하세요.
자격 증명이 파일인 경우, 파일을 docker-compose.yml 옆에 두고 docker-compose.yml의 x-server-mounts 목록에 - ./gcp-key.json:/etc/cma-server/gcp-key.json:ro와 같은 줄을 추가하세요. 첫 번째 콜론 뒤의 경로는 컨테이너 내부에서의 파일 경로입니다. 이 경로를 .env에서 변수의 값으로 사용하거나, 해당 파일을 지정하는 설정의 값으로 사용하세요.
docker compose up -d를 실행하세요. 재시작으로는 .env를 다시 읽지 않습니다.

업그레이드하면 docker-compose.yml이 교체되므로, 새 릴리스의 스택을 시작하기 전에 해당 릴리스의 파일에서 이 편집을 반복하세요.

표 읽는 방법

각 설정에는 설정 파일의 키가 있으며, 대부분의 설정에는 환경 변수도 있습니다. 변수는 파일보다 우선하고, 파일은 기본값보다 우선합니다. 설정 파일에 알 수 없는 키가 있으면 서버가 시작되지 않으며, 오류에 해당 키의 위치가 표시됩니다.

키: 키의 각 점은 파일에서 한 단계의 중첩을 나타냅니다. 예를 들어 server.addr은 server 섹션의 addr 키입니다.
변수: 변수의 이름은 CMA_ 뒤에 키를 대문자로 쓰고, 각 점 대신 밑줄 두 개를 넣은 것입니다.
파일 전용: 해당 설정에는 변수가 없습니다.
환경 변수 전용: 설정이 파일에 있으면 서버가 시작되지 않습니다.
bedrock 전용 및 유사한 레이블: 해당 설정은 그 프로바이더, 저장소 또는 시크릿 매니저에서만 작동합니다. 다른 것을 사용하는 동안 이 설정을 지정하면 서버가 시작되지 않습니다.
목록: 목록은 파일에서는 YAML 목록이고, 변수에서는 쉼표로 구분된 문자열입니다.
기간: 기간은 30s, 5m, 1h와 같이 단위가 붙은 숫자입니다.
정수: 정수는 부호, 선행 0, 밑줄이 없는 순수한 숫자입니다.

시작 시 서버는 사용자가 설정한 설정과 대부분의 기본값을 로그에 기록하며, 각 값의 출처를 server.addr=0.0.0.0:8400 (file)과 같이 함께 표시합니다. 서버가 직접 생성한 서버 API 키를 제외하고, 비밀 값은 ***로 대체하여 기록합니다.

서버 및 로깅

설정 환경 변수	기본값	설명
`server.addr` `CMA_SERVER__ADDR`	`127.0.0.1:8400`	서버가 수신 대기하는 주소입니다.
`server.api_key` `CMA_SERVER__API_KEY`	없음	서버 API 키입니다. `auth.refuse_server_api_key`가 `true`가 아닌 한 `store.backend: postgres`에서 필수입니다. `memory`에서는 키를 설정하지 않으면 서버가 키를 생성하고 시작 시 로그에 기록합니다.
`server.id_marker` `CMA_SERVER__ID_MARKER`	`local`	서버가 생성하는 각 ID에서 접두사 뒤에 오는 부분입니다. `local`은 `sesn_local_01…`을, `none`은 호스팅 서비스와 마찬가지로 `sesn_01…`을 생성합니다.
`server.shutdown_delay` `CMA_SERVER__SHUTDOWN_DELAY`	`0s`	중지 신호를 받은 후 준비 상태 프로브가 `not_ready`로 응답하는 동안 서버가 계속 서비스하는 시간입니다. 최댓값은 `5m`입니다.
`server.max_connections` `CMA_SERVER__MAX_CONNECTIONS`	`0`	서버가 `server.addr`에서 동시에 열어 두는 최대 연결 수입니다. `0`은 제한 없음을 의미합니다. 한도에 도달하면 새 연결은 다른 연결이 닫히거나 해당 클라이언트가 포기할 때까지 기다립니다. 이벤트 스트림, 워커 폴링, 상태 프로브가 모두 집계됩니다. Kubernetes에서는 프로브가 너무 오래 기다리는 파드를 kubelet이 재시작합니다.
`logging.format` `CMA_LOGGING__FORMAT`	`text`	로그 형식으로, `text` 또는 `json`입니다.
`logging.level` `CMA_LOGGING__LEVEL`	`info`	서버가 기록하는 가장 낮은 수준입니다. 값은 `debug`, `info`, `warn`, `error`입니다.
`logging.errors` `CMA_LOGGING__ERRORS`	`false`	로그에 `4xx` 및 `5xx` 응답의 오류 메시지를 포함할지 여부입니다. 메시지에는 클라이언트가 보낸 값이 인용될 수 있습니다.
`health.check_interval` `CMA_HEALTH__CHECK_INTERVAL`	`60s`	준비 상태 프로브를 위해 서버가 추론 자격 증명을 확인하는 주기입니다. 최솟값은 `5s`입니다.
`health.upstream_affects_readiness` `CMA_HEALTH__UPSTREAM_AFFECTS_READINESS`	`true`	추론 프로바이더가 서버의 자격 증명을 거부하는 동안 준비 상태 프로브가 `503`으로 응답할지 여부입니다.

데이터베이스

이 표에서 store.backend를 제외한 모든 설정은 store.backend: postgres에서만 적용됩니다.

설정 환경 변수	기본값	설명
`store.backend` `CMA_STORE__BACKEND`	`memory`	서버가 데이터를 보관하는 위치입니다. 값은 재시작 시 지워지는 `memory`와 `postgres`입니다.
`store.database_url` `CMA_STORE__DATABASE_URL`	없음	PostgreSQL 연결 문자열입니다. `postgres`에서 필수입니다.
`store.control_database_url` `CMA_STORE__CONTROL_DATABASE_URL`	`store.database_url`의 값	하트비트와 같은 서버 자체 유지 관리 연결에 사용하는 연결 문자열입니다.
`store.listen_database_url` `CMA_STORE__LISTEN_DATABASE_URL`	`store.database_url`의 값	서버가 알림을 수신 대기하는 단일 연결에 사용하는 연결 문자열입니다. 트랜잭션 모드의 커넥션 풀러는 이 연결을 전달할 수 없습니다.
`store.migrate_database_url` `CMA_STORE__MIGRATE_DATABASE_URL`	`store.database_url`의 값	서버의 `migrate` 명령이 사용하는 연결 문자열입니다. 트랜잭션 모드의 커넥션 풀러는 이 연결을 전달할 수 없습니다.
`store.pool_max_conns` `CMA_STORE__POOL_MAX_CONNS`	`24`	한 서버의 풀이 여는 최대 데이터베이스 연결 수입니다. 최솟값은 `4`입니다.
`store.event_poll_interval` `CMA_STORE__EVENT_POLL_INTERVAL`	`25ms`	각 서버가 클라이언트가 스트리밍 중인 세션의 최신 이벤트를 데이터베이스에 요청하는 주기입니다. 다른 서버가 기록한 이벤트는 최대 이 시간 정도 기다린 후 스트림에 도달합니다.
`store.credentials_encryption_key` `CMA_STORE__CREDENTIALS_ENCRYPTION_KEY` 환경 변수 전용	없음	데이터베이스에 저장된 자격 증명을 암호화하는 키로, base64로 인코딩된 32개의 임의 바이트입니다. Docker Compose 및 Kubernetes 설치에서는 이 키를 설정합니다. `store.allow_unencrypted_credentials`가 `true`인 경우를 제외하고, 이 키가 없으면 서버가 시작되지 않습니다.
`store.allow_unencrypted_credentials` `CMA_STORE__ALLOW_UNENCRYPTED_CREDENTIALS`	`false`	서버가 `store.credentials_encryption_key` 없이 시작할 수 있는지 여부입니다. 키가 없으면 서버는 자격 증명을 데이터베이스에 일반 텍스트로 저장합니다. `git.allowed_hostnames`에 호스트가 나열되어 있거나, Docker Compose 또는 서버 Helm 차트로 설치하는 경우 `true`는 효과가 없습니다.
`store.credentials_encryption_keys_retiring` `CMA_STORE__CREDENTIALS_ENCRYPTION_KEYS_RETIRING` 환경 변수 전용	없음	키 교체 중에 서버가 여전히 복호화에 사용할 수 있는 이전 암호화 키입니다. 이 설정에는 `store.credentials_encryption_key`가 필요합니다.

추론 프로바이더

프로바이더를 설정하려면 추론 프로바이더를 참조하세요.

설정 환경 변수	기본값	설명
`inference.provider` `CMA_INFERENCE__PROVIDER`	`anthropic`	서버가 모델 호출을 보내는 곳입니다. 값은 `anthropic`, `bedrock`, `vertex`, `foundry`, `gateway`입니다.
`inference.headers` 파일 전용	없음	서버가 모든 모델 호출에 추가하는 요청 헤더로, 헤더 이름과 값의 맵입니다. 모든 값을 따옴표로 묶으세요. 따옴표로 묶지 않은 값을 YAML이 텍스트로 읽지 않으면(예: `true` 또는 `0042`) 서버는 시작을 거부합니다. `gateway`에서는 값으로 `{ from: request_id }` 또는 `{ from: session_id }`도 사용할 수 있습니다.
`inference.model_fallback` `CMA_INFERENCE__MODEL_FALLBACK`	`true`	`anthropic` 전용. 모델 호출이 서버 측 폴백을 요청할지 여부입니다. 이러한 호출에는 `fallbacks` 필드와 `anthropic-beta: server-side-fallback-2026-07-01` 헤더가 포함됩니다. `ANTHROPIC_BASE_URL`에 지정한 프록시가 이 필드나 헤더를 거부할 수 있습니다. 프록시가 `400` 또는 `422`로 응답하면, 서버는 이들을 제외하고 호출을 다시 보냅니다.
`inference.metadata.user_id` `CMA_INFERENCE__METADATA__USER_ID`	없음	`anthropic` 및 `foundry` 전용, 또는 `format: anthropic-messages`를 사용하는 `gateway`. 서버가 모든 모델 호출에 `metadata.user_id`로 보내는 단일 식별자입니다. 시작 로그에 출력됩니다. 이 설정이 없으면 서버는 `cma-server` 레이블을 보냅니다. `metadata.user_id`를 끌 수는 없습니다. 프로바이더나 프록시가 이를 거부하면 모든 모델 호출이 실패합니다. 네트워크 외부로 전송되는 항목을 참조하세요.

클라우드 프로바이더

설정 환경 변수	기본값	설명
`inference.region` `CMA_INFERENCE__REGION`	없음	`bedrock` 및 `vertex` 전용. AWS 리전 또는 Google Cloud’s Agent Platform의 위치입니다. `vertex`에서 필수입니다. 이 설정이 없으면 `bedrock`은 AWS SDK의 기본 체인이 찾은 리전을 사용합니다.
`inference.project_id` `CMA_INFERENCE__PROJECT_ID`	없음	`vertex` 전용. 호출이 이루어지는 Google Cloud 프로젝트입니다. Google 자격 증명에 프로젝트가 지정되어 있지 않으면 필수입니다.
`inference.api` `CMA_INFERENCE__API`	`invoke_model`	`bedrock` 전용. 호출을 전달하는 Amazon Bedrock API로, `invoke_model` 또는 `messages`입니다. `messages`는 Amazon Bedrock의 Claude(`bedrock-mantle`)에서 설명하는 엔드포인트입니다. 이 경우 서버의 AWS 역할에는 `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream` 대신 `bedrock-mantle:CreateInference`가 필요합니다.
`inference.list_models` `CMA_INFERENCE__LIST_MODELS`	`true`	`bedrock` 전용. 서버가 Amazon Bedrock의 Claude 모델 목록을 읽을지 여부입니다. 이 목록을 통해 에이전트는 서버 릴리스 이후에 출시된 모델을 사용할 수 있습니다.
`inference.model_id_prefix` `CMA_INFERENCE__MODEL_ID_PREFIX`	`us.anthropic.`	`bedrock` 전용. 서버가 각 모델 ID 앞에 붙이는 텍스트입니다. `inference.api: messages`에서는 기본값이 `anthropic.`입니다.
`inference.model_id_overrides` 파일 전용	없음	`bedrock`, `vertex`, `foundry` 전용. 모델 ID를 프로바이더가 기대하는 정확한 ID로 매핑하는 맵입니다. `foundry`에서는 해당 ID가 배포 이름입니다.
`inference.foundry.resource` `CMA_INFERENCE__FOUNDRY__RESOURCE`	없음	`foundry` 전용. Foundry 리소스의 이름입니다. 이 설정 또는 `inference.foundry.base_url` 중 하나만 설정하세요.
`inference.foundry.base_url` `CMA_INFERENCE__FOUNDRY__BASE_URL`	없음	`foundry` 전용. 기본적으로 호출은 `https://<resource>.services.ai.azure.com/anthropic`으로 전송됩니다. 프록시와 같은 다른 주소로 리소스에 접근하려면 대신 해당 URL을 여기에 설정하세요. 이 URL은 `/anthropic`으로 끝납니다.

모델 게이트웨이

이 설정은 inference.provider: gateway에서만 적용됩니다. 모델 게이트웨이를 참조하세요.

설정 환경 변수	기본값	설명
`inference.gateway.url` `CMA_INFERENCE__GATEWAY__URL`	없음	필수. 모델 호출을 수신하는 URL입니다. `bedrock-invoke` 및 `vertex-raw-predict`에서는 `{model}`이 모델 ID가 들어갈 위치를 표시합니다. `vertex-raw-predict`에서는 URL이 `/{model}:rawPredict`로 끝나야 합니다.
`inference.gateway.format` `CMA_INFERENCE__GATEWAY__FORMAT`	없음	필수. 게이트웨이가 수락하는 요청 형식으로, `bedrock-invoke`, `anthropic-messages`, `vertex-raw-predict` 중 하나입니다.
`inference.gateway.model_map` 파일 전용	없음	필수. 에이전트가 지정할 수 있는 각 모델 ID를 게이트웨이가 기대하는 ID로 매핑하는 맵입니다. `inference.headers`와 마찬가지로 모든 값을 따옴표로 묶으세요.
`inference.gateway.streaming` `CMA_INFERENCE__GATEWAY__STREAMING`	`false`	모델이 응답을 생성하는 즉시 도착하도록, 서버가 해당 형식의 스트리밍 호출을 보낼지 여부입니다. `bedrock-invoke`에서는 해당 호출이 `-with-response-stream`이 추가된 동일한 URL로 전송됩니다. `vertex-raw-predict`에서는 해당 호출이 `:rawPredict` 대신 `:streamRawPredict`가 들어간 동일한 URL로 전송됩니다. `inference.gateway.url`에는 `:rawPredict`를 그대로 두세요.
`inference.credentials.supplier` `CMA_INFERENCE__CREDENTIALS__SUPPLIER`	없음	필수. 게이트웨이의 자격 증명을 가져오는 곳입니다. `env`는 하나의 장기 키를, `oauth_exchange`는 단기 토큰을, `azure`는 서버 자체의 Azure ID에 발급된 Microsoft Entra ID 토큰을 의미합니다.
`inference.credentials.env.var` `CMA_INFERENCE__CREDENTIALS__ENV__VAR`	없음	`env`에서 필수. 키를 보관하는 환경 변수의 이름입니다.
`inference.credentials.azure.scope` `CMA_INFERENCE__CREDENTIALS__AZURE__SCOPE`	없음	`azure`에서 필수. 서버가 토큰을 요청하는 스코프로, 게이트웨이 앱 등록의 애플리케이션 ID URI 또는 애플리케이션 ID 뒤에 `/.default`를 붙인 값입니다.
`inference.credentials.send_as.header` `CMA_INFERENCE__CREDENTIALS__SEND_AS__HEADER`	`Authorization`	자격 증명을 전달하는 요청 헤더입니다.
`inference.credentials.send_as.scheme` `CMA_INFERENCE__CREDENTIALS__SEND_AS__SCHEME`	`Bearer`	헤더에서 자격 증명 앞에 오는 단어입니다. `Authorization` 이외의 헤더에서는 기본적으로 스킴이 없습니다.
`inference.credentials.renew_before` `CMA_INFERENCE__CREDENTIALS__RENEW_BEFORE`	`90s`	`oauth_exchange`에서 서버가 토큰을 얼마나 일찍 교체할지를 나타냅니다. 서버는 토큰이 만료되기 이 시간만큼 전에 캐시된 토큰의 사용을 중단하고, 다음 모델 호출을 위해 새 토큰을 가져옵니다. 이 값은 토큰의 수명보다 작게 유지하세요. 서버는 유효 시간이 이 값보다 짧은 토큰을 거부합니다.

단기 게이트웨이 토큰

이 설정은 inference.credentials.supplier: oauth_exchange에서만 적용됩니다. 단기 토큰을 참조하세요. exchange 설정은 그룹 전체가 선택 사항입니다. 이 설정이 없으면 서버는 콜백이 반환한 값을 게이트웨이에 보냅니다.

설정 환경 변수	기본값	설명
`inference.credentials.assertion.url` `CMA_INFERENCE__CREDENTIALS__ASSERTION__URL`	없음	필수. 서명된 어설션을 반환하는 HTTP 콜백의 URL입니다.
`inference.credentials.assertion.auth.type` `CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TYPE`	없음	필수. 서버가 콜백에 인증하는 방법으로, `mtls` 또는 `bearer_file`입니다.
`inference.credentials.assertion.auth.cert_file` `CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CERT_FILE`	없음	`mtls`에서 필수. 서버의 클라이언트 인증서 경로입니다.
`inference.credentials.assertion.auth.key_file` `CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__KEY_FILE`	없음	`mtls`에서 필수. 클라이언트 인증서의 개인 키 경로입니다.
`inference.credentials.assertion.auth.token_file` `CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TOKEN_FILE`	없음	`bearer_file`에서 필수. bearer 토큰을 보관하는 파일의 경로입니다.
`inference.credentials.assertion.auth.ca_file` `CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CA_FILE`	없음	서버가 콜백에 대해 신뢰하는 인증 기관이 포함된 PEM 파일의 경로입니다.
`inference.credentials.assertion.forward_metadata` `CMA_INFERENCE__CREDENTIALS__ASSERTION__FORWARD_METADATA`	없음	서버가 콜백에 값을 보내는 세션 메타데이터 키입니다. 이 값은 요청 본문에서 `session.metadata`로 전달됩니다. 값은 API 호출자가 작성한 그대로이므로, 자체 기록과 대조하여 확인하세요.
`inference.credentials.exchange.token_url` `CMA_INFERENCE__CREDENTIALS__EXCHANGE__TOKEN_URL`	없음	교환 시 필수. 서버가 어설션을 토큰으로 교환하는 OAuth 토큰 엔드포인트입니다.
`inference.credentials.exchange.grant_type` `CMA_INFERENCE__CREDENTIALS__EXCHANGE__GRANT_TYPE`	없음	교환 시 필수. 서버가 보내는 `grant_type`으로, 예를 들어 `urn:ietf:params:oauth:grant-type:jwt-bearer`입니다.
`inference.credentials.exchange.encoding` `CMA_INFERENCE__CREDENTIALS__EXCHANGE__ENCODING`	`form`	서버가 교환 요청을 인코딩하는 방법으로, `form` 또는 `multipart`입니다.
`inference.credentials.exchange.expiry` `CMA_INFERENCE__CREDENTIALS__EXCHANGE__EXPIRY`	`expires_in`	서버가 토큰의 수명을 읽는 위치입니다. `expires_in`은 응답의 `expires_in`과 토큰의 `exp` 클레임 중 더 이른 값을 의미합니다. `jwt_exp`는 `exp` 클레임만을 의미합니다.
`inference.credentials.exchange.headers` 파일 전용	없음	토큰 엔드포인트에 대한 추가 요청 헤더로, 헤더 이름과 값의 맵입니다. `inference.headers`와 마찬가지로 모든 값을 따옴표로 묶으세요.
`inference.credentials.exchange.ca_file` `CMA_INFERENCE__CREDENTIALS__EXCHANGE__CA_FILE`	없음	서버가 토큰 엔드포인트에 대해 신뢰하는 인증 기관이 포함된 PEM 파일의 경로입니다.

싱글 사인온

로그인을 설정하려면 싱글 사인온을 참조하세요.

설정 환경 변수	기본값	설명
`auth.issuers` 파일 전용	없음	서버가 토큰을 수락하는 OpenID Connect 발급자입니다. 발급자 항목을 참조하세요.
`auth.refuse_server_api_key` 파일 전용	`false`	서버가 모든 경로에서 서버 API 키를 거부할지 여부입니다. `true`에는 최소 하나의 발급자가 필요합니다. 이 경우 키를 사용하는 모든 관리자 CLI 명령이 실패합니다.

발급자 항목

auth.issuers의 각 항목은 다음 필드를 사용합니다:

필드	기본값	설명
`name`	없음	필수. 로그 줄에 표시되는 발급자의 레이블입니다. 서버는 이를 각 리소스 생성자 정보의 일부로도 기록합니다.
`issuer_url`	없음	필수. 발급자 토큰의 `iss` 클레임과 정확히 일치하는 발급자의 URL입니다. 서버는 이 호스트와 발급자의 디스커버리 문서에 명시된 `jwks_uri` 호스트에서 서명 키를 가져옵니다. 네트워크가 아웃바운드 연결을 제한하는 경우 두 호스트를 모두 허용하세요.
`audiences`	없음	필수. 토큰의 `aud` 클레임이 가질 수 있는 값입니다. 애플리케이션이 이미 보유한 토큰을 전달하는 경우 각 애플리케이션의 클라이언트 ID를 나열하세요.
`roles`	없음	`group`과 `role` 쌍의 목록입니다. 그룹은 정확히 일치하거나, `*`가 임의의 문자열을, `?`가 한 문자를 나타내는 패턴으로 일치합니다. 역할은 `admin`, `developer`, `user` 중 하나입니다. 일치하는 역할 중 가장 높은 역할이 적용됩니다. `roles`, `default_role` 또는 둘 다 설정하세요.
`default_role`	없음	그룹이 어떤 `roles` 항목과도 일치하지 않는 호출자의 역할입니다. 이 audience에 대한 토큰을 받을 수 있는 모든 사람이 접근 권한을 가져야 하는 경우에만 설정하세요.
`subject_claim`	`sub`	호출자를 식별하는 클레임입니다. `/`로 시작하는 이름은 중첩된 클레임을 가리키는 JSON Pointer입니다.
`stable_subject`	`false`	`subject_claim`이 `sub` 또는 `oid` 이외의 클레임을 지정하는 경우에만 적용됩니다. 프로바이더가 해당 클레임의 개인별 값을 절대 변경하지 않고 다른 사람에게 부여하지도 않음을 확인하려면 `true`로 설정하세요. 서버는 이를 확인하지 않습니다. `false`이면 에이전트 토큰에서 `actor_sub` 및 `actor_iss` 클레임이 생략됩니다.
`groups_claim`	`groups`	호출자의 그룹을 나열하는 클레임입니다. `/`로 시작하는 이름은 중첩된 클레임을 가리키는 JSON Pointer입니다.
`jwks_file`	없음	JSON Web Key Set 파일의 경로입니다. 서버는 이 파일에서 서명 키를 읽으며 발급자에게 접속하지 않습니다.
`login_client_id`	없음	터미널 로그인이 사용하는 애플리케이션의 클라이언트 ID입니다. 하나의 발급자만 이를 설정할 수 있습니다.
`login_scopes`	`[openid]`	로그인이 요청하는 스코프입니다. 이 필드에는 `login_client_id`가 필요합니다.

시크릿 매니저

저장소를 설정하려면 시크릿 매니저를 참조하세요.

설정 환경 변수	기본값	설명
`secret_store.type` `CMA_SECRET_STORE__TYPE`	없음	볼트 자격 증명을 보관하는 시크릿 매니저입니다. 값은 `aws_secrets_manager`, `gcp_secret_manager`, `azure_key_vault`, `hashicorp_vault`입니다. 이 설정이 없으면 볼트 자격 증명은 데이터베이스에 남습니다.
`secret_store.prefix` `CMA_SECRET_STORE__PREFIX`	없음	`secret_store.type`과 함께 사용할 때 필수. 서버가 생성하는 모든 시크릿 이름의 시작 부분입니다. `aws_secrets_manager`와 `hashicorp_vault`에서는 `/`로, `gcp_secret_manager`에서는 `-` 또는 `_`로, `azure_key_vault`에서는 `-`로 끝나야 합니다.
`secret_store.region` `CMA_SECRET_STORE__REGION`	없음	`aws_secrets_manager` 전용이며, 해당 경우 필수. 시크릿을 보관하는 AWS 리전입니다.
`secret_store.project` `CMA_SECRET_STORE__PROJECT`	없음	`gcp_secret_manager` 전용이며, 해당 경우 필수. 시크릿을 보관하는 Google Cloud 프로젝트의 ID입니다.
`secret_store.vault_url` `CMA_SECRET_STORE__VAULT_URL`	없음	`azure_key_vault` 전용이며, 해당 경우 필수. `https://my-vault.vault.azure.net`과 같은 키 볼트의 URL입니다.

HashiCorp Vault

이 설정은 secret_store.type: hashicorp_vault에서만 적용됩니다. 로그인 방법으로 token_file, kubernetes, approle 중 정확히 하나를 설정하세요.

설정 환경 변수	기본값	설명
`secret_store.address` `CMA_SECRET_STORE__ADDRESS`	없음	필수. Vault 서버의 `https://` URL입니다.
`secret_store.namespace` `CMA_SECRET_STORE__NAMESPACE`	없음	마운트와 로그인 방법을 보관하는 Vault Enterprise 네임스페이스입니다.
`secret_store.mount` `CMA_SECRET_STORE__MOUNT`	`secret`	KV 버전 2 시크릿 엔진의 경로입니다.
`secret_store.ca_cert_file` `CMA_SECRET_STORE__CA_CERT_FILE`	없음	Vault 인증서에 서명한 인증 기관이 포함된 PEM 파일의 경로입니다.
`secret_store.token_file` `CMA_SECRET_STORE__TOKEN_FILE`	없음	Vault Agent와 같은 다른 프로세스가 최신 상태로 유지하는 Vault 토큰이 담긴 파일의 경로입니다.
`secret_store.kubernetes.role` `CMA_SECRET_STORE__KUBERNETES__ROLE`	없음	`kubernetes`에서 필수. 서버가 로그인할 때 사용하는 Vault 역할입니다. 이 역할을 서버의 서비스 계정에 바인딩하세요.
`secret_store.kubernetes.mount_path` `CMA_SECRET_STORE__KUBERNETES__MOUNT_PATH`	`kubernetes`	Vault가 Kubernetes 로그인 방법을 마운트하는 위치입니다.
`secret_store.kubernetes.service_account_token_file` `CMA_SECRET_STORE__KUBERNETES__SERVICE_ACCOUNT_TOKEN_FILE`	`/var/run/secrets/kubernetes.io/serviceaccount/token`	서버가 로그인할 때마다 제시하는 서비스 계정 토큰의 경로입니다.
`secret_store.approle.role_id` `CMA_SECRET_STORE__APPROLE__ROLE_ID`	없음	`approle`에서 필수. 서버가 로그인할 때 사용하는 AppRole 역할의 ID입니다.
`secret_store.approle.secret_id_file` `CMA_SECRET_STORE__APPROLE__SECRET_ID_FILE`	없음	`approle`에서 필수. 역할의 `secret_id`가 담긴 파일의 경로입니다.
`secret_store.approle.mount_path` `CMA_SECRET_STORE__APPROLE__MOUNT_PATH`	`approle`	Vault가 AppRole 로그인 방법을 마운트하는 위치입니다.

에이전트 ID

에이전트 토큰을 설정하려면 에이전트 ID를 참조하세요. 이 표의 설정 중 하나라도 설정하면 이 기능이 켜집니다. 그러면 서버에는 agent_identity.issuer와 서명 키를 위한 정확히 하나의 위치(key_file, key_secret, kms_key 중 하나)가 필요합니다.

설정 환경 변수	기본값	설명
`agent_identity.issuer` `CMA_AGENT_IDENTITY__ISSUER`	없음	에이전트 토큰이 `iss` 클레임으로 가지는 `https://` URL입니다.
`agent_identity.key_file` `CMA_AGENT_IDENTITY__KEY_FILE`	없음	토큰에 서명하는 PEM 개인 키의 경로입니다.
`agent_identity.key_secret` `CMA_AGENT_IDENTITY__KEY_SECRET`	없음	시크릿 매니저에서 PEM 개인 키를 보관하는 시크릿의 이름으로, `secret_store.prefix`를 제외한 이름입니다.
`agent_identity.kms_key.provider` `CMA_AGENT_IDENTITY__KMS_KEY__PROVIDER`	없음	서명 키를 보관하는 키 관리 서비스로, `aws_kms` 또는 `gcp_kms`입니다.
`agent_identity.kms_key.key` `CMA_AGENT_IDENTITY__KMS_KEY__KEY`	없음	`kms_key.provider`와 함께 사용할 때 필수. `aws_kms`의 경우 키의 ARN이고, `gcp_kms`의 경우 하나의 키 버전에 대한 리소스 이름입니다.
`agent_identity.published_key_files` `CMA_AGENT_IDENTITY__PUBLISHED_KEY_FILES`	없음	키 세트에 추가할 PEM 공개 키의 경로입니다. 서버는 이 키를 게시하지만 이 키로 서명하지는 않습니다. 서명 키를 교체할 때 이 설정을 사용하세요.
`agent_identity.token_lifetime` `CMA_AGENT_IDENTITY__TOKEN_LIFETIME`	`5m`	토큰의 `iat` 클레임부터 `exp` 클레임까지의 시간입니다. 이미 전송된 토큰은 `exp`까지 유효합니다. 최솟값은 `limits.mcp_call_timeout`에 `1m`을 더한 값이고, 최댓값은 `15m`입니다.
`agent_identity.jwks_uri` `CMA_AGENT_IDENTITY__JWKS_URI`	`<issuer>/.well-known/jwks.json`	발급자의 디스커버리 문서가 키 세트에 대해 제공하는 URL입니다. 키 세트를 발급자 URL 아래가 아닌 다른 곳에 호스팅하는 경우에만 설정하세요.
`agent_identity.direct.audiences` 파일 전용	없음	토큰을 받을 수 있는 수신자입니다. 각 항목에는 `audience` URL과, 해당 수신자의 MCP 서버 URL 접두사인 `urls`가 있습니다.
`agent_identity.actor.enabled` `CMA_AGENT_IDENTITY__ACTOR__ENABLED`	`true`	서버가 도구 호출의 토큰에 `actor_sub` 및 `actor_iss` 클레임을 추가할지 여부입니다. `actor_sub`는 세션을 생성한 호출자의 주체(subject)입니다. `actor_iss`는 호출자가 로그인할 때 사용한 `auth.issuers` 항목의 `issuer_url`입니다. 어느 클레임도 호출자가 해당 호출을 승인했음을 의미하지 않습니다.

이그레스 게이트웨이

게이트웨이를 설정하려면 환경 변수 자격 증명을 참조하세요. 이 표의 다른 설정은 egress.gateway_enabled: true에서만 설정하세요. 이 설정이 없으면 다른 설정 중 하나라도 지정된 경우 서버가 시작되지 않습니다.

설정 환경 변수	기본값	설명
`egress.gateway_enabled` `CMA_EGRESS__GATEWAY_ENABLED`	`false`	서버가 이그레스 게이트웨이와 연동하고 `environment_variable` 볼트 자격 증명을 수락할지 여부입니다.
`egress.allowed_hostnames` `CMA_EGRESS__ALLOWED_HOSTNAMES`	없음	샌드박스가 게이트웨이를 통해 접근할 수 있는 정확한 공개 호스트 이름입니다. `api.example.com`과 같이 포트가 없는 항목은 `https` URL에 대해 포트 443, `http` URL에 대해 포트 80을 허용합니다. `api.example.com:8443`과 같이 포트가 있는 항목은 해당 포트만 허용합니다.
`egress.swap_header_names` `CMA_EGRESS__SWAP_HEADER_NAMES`	`Authorization`	게이트웨이가 자격 증명 값을 넣을 수 있는 요청 헤더입니다. 직접 지정한 목록은 기본값을 대체하므로, 목록에 `Authorization`을 포함하세요.
`egress.gateway_listen` `CMA_EGRESS__GATEWAY_LISTEN`	`:8410`	게이트웨이만 서비스하는 서버의 두 번째 리스너 주소입니다. 기본값은 모든 인터페이스에서 수신 대기합니다.
`egress.gateway_key_file` `CMA_EGRESS__GATEWAY_KEY_FILE`	없음	필수. 게이트웨이가 서버에 제시하는 키가 담긴 파일의 경로입니다.
`egress.ca_cert_file` `CMA_EGRESS__CA_CERT_FILE`	없음	필수. 게이트웨이 인증 기관의 PEM 인증서 경로입니다.
`egress.gateway_proxy_address` `CMA_EGRESS__GATEWAY_PROXY_ADDRESS`	없음	필수. 샌드박스가 게이트웨이의 프록시 포트에 접근하는 `host:port`입니다.

MCP 서버

MCP 서버에는 허용 목록 항목이 필요합니다를 참조하세요.

설정 환경 변수	기본값	설명
`mcp.allowed_hostnames` `CMA_MCP__ALLOWED_HOSTNAMES`	없음	서버가 연결할 수 있는 MCP 서버의 정확한 호스트 이름입니다. 이 설정이 없으면 서버는 어디에도 연결하지 않습니다.
`mcp.private_hostnames` 파일 전용	없음	`mcp.allowed_hostnames`의 호스트 이름 중 사설 주소로 확인될 수 있는 호스트 이름입니다.
`mcp.max_result_bytes` `CMA_MCP__MAX_RESULT_BYTES`	`102400` (100 KiB)	모델이 보는 단일 MCP 도구 결과의 최대 바이트 수입니다. 최솟값은 `1024`입니다.

Git 저장소

Git 저장소에는 허용 목록 항목이 필요합니다를 참조하세요.

설정 환경 변수	기본값	설명
`git.allowed_hostnames` `CMA_GIT__ALLOWED_HOSTNAMES`	없음	세션의 저장소가 위치할 수 있는 Git 호스트입니다. 호스트 이름은 와일드카드 없이 정확히 일치해야 하며, 항목은 하위 도메인을 포함하지 않습니다. 항목은 포트 443 또는 `git.example.com:8443`과 같이 항목에 지정된 하나의 포트를 허용합니다. 이 설정이 없으면 서버는 어떤 저장소도 수락하지 않습니다.
`git.private_hostnames` 파일 전용	없음	`git.allowed_hostnames`의 호스트 이름 중 사설 주소로 확인되는 호스트 이름으로, 포트 없이 작성합니다. 그 외의 호스트 이름에 대해서는 서버가 해당 호스트 이름의 공개 주소에만 연결합니다.
`git.allowed_push_refs` `CMA_GIT__ALLOWED_PUSH_REFS`	없음	에이전트가 푸시할 수 있는 브랜치로, 각각 `refs/heads/` 아래에 있습니다. `/`로 끝나는 항목은 그 아래의 모든 브랜치를 허용합니다. 그 외의 항목은 해당 브랜치 하나를 허용합니다. 이 설정이 없으면 에이전트는 푸시할 수 없습니다.
`git.commit_author_name` `CMA_GIT__COMMIT_AUTHOR_NAME`	`Claude`	에이전트 커밋의 작성자 이름입니다. `git.commit_author_email`과 함께 설정하세요.
`git.commit_author_email` `CMA_GIT__COMMIT_AUTHOR_EMAIL`	`noreply@anthropic.com`	에이전트 커밋의 작성자 이메일 주소입니다. `git.commit_author_name`과 함께 설정하세요.
`git.max_concurrent_transfers` `CMA_GIT__MAX_CONCURRENT_TRANSFERS`	`32`	한 서버가 동시에 처리하는 최대 Git 요청 수입니다. 최솟값은 `1`입니다.
`git.max_session_transfer_bytes` `CMA_GIT__MAX_SESSION_TRANSFER_BYTES`	`8589934592` (8 GiB)	한 서버가 하나의 세션에 대해 전달하는 최대 Git 트래픽(바이트 단위)으로, 업로드와 다운로드를 합산합니다. 샌드박스가 세션을 가져올 때마다 집계는 0부터 다시 시작됩니다. 한도에 도달하면 서버는 해당 세션의 다음 Git 요청을 `403`으로 거부합니다. `0`은 제한 없음을 의미합니다. 그 외의 경우 최솟값은 `1048576`입니다.
`git.max_push_bytes` `CMA_GIT__MAX_PUSH_BYTES`	`2147483648` (2 GiB)	한 번의 푸시로 보낼 수 있는 최대 바이트 수입니다. 최솟값은 `1048576`입니다.

Git 저장소에는 다음 제한이 적용됩니다:

프로토콜: 서버는 SSH 또는 Git LFS를 지원하지 않으며, 이름이 변경된 저장소에 대한 리디렉션과 같은 리디렉션을 거부합니다.
토큰: Git 호스트는 사용자 이름 x-access-token으로 HTTP Basic 인증의 비밀번호로서 토큰을 수락해야 합니다.
URL: 저장소 URL에는 하나의 소유자와 하나의 저장소 이름이 있으므로, GitLab 하위 그룹의 저장소는 사용할 수 없습니다.
호스트: git.allowed_hostnames에 나열되지 않은 호스트에 있는 URL에 대해 서버는 400을 반환합니다. 다른 호스트를 나열하더라도 오류 메시지에는 URL이 github.com에 있어야 한다고 표시됩니다.
푸시: 서버는 브랜치를 삭제하거나, 태그와 같이 브랜치 이외의 것을 변경하는 푸시를 항상 거부합니다.

웹 도구 및 스킬

웹 도구에는 서버 설정이 필요합니다를 참조하세요.

설정 환경 변수	기본값	설명
`web_tools.enabled` `CMA_WEB_TOOLS__ENABLED`	`false`	에이전트가 `web_search` 및 `web_fetch` 도구를 사용할 수 있는지 여부입니다. 다른 `web_tools` 설정을 지정하면 기본값은 `true`입니다.
`web_tools.allowed_domains` `CMA_WEB_TOOLS__ALLOWED_DOMAINS`	없음	에이전트가 웹 도구를 통해 읽을 수 있는 유일한 도메인입니다. 항목은 해당 하위 도메인도 포함합니다.
`web_tools.blocked_domains` `CMA_WEB_TOOLS__BLOCKED_DOMAINS`	없음	어떤 에이전트도 웹 도구를 통해 읽을 수 없는 도메인입니다. 이 설정 또는 `web_tools.allowed_domains` 중 하나만 설정하세요.
`web_tools.max_content_tokens` `CMA_WEB_TOOLS__MAX_CONTENT_TOKENS`	없음	`web_fetch`가 모델에 반환하는, 가져온 단일 페이지의 최대 토큰 수입니다.
`skills.max_name_chars` `CMA_SKILLS__MAX_NAME_CHARS`	`64`	`SKILL.md` 파일이 가질 수 있는 `name`의 최대 길이입니다. 최댓값은 `255`입니다.
`skills.max_description_chars` `CMA_SKILLS__MAX_DESCRIPTION_CHARS`	`1024`	`SKILL.md` 파일이 가질 수 있는 `description`의 최대 길이입니다.

제한, 타임아웃 및 스케줄링

설정 환경 변수	기본값	설명
`limits.max_active_sessions` `CMA_LIMITS__MAX_ACTIVE_SESSIONS`	`64`	`store.backend: memory` 전용. 동시에 턴을 실행하는 최대 세션 수입니다. `0`은 제한 없음을 의미합니다.
`limits.max_live_subagent_threads` `CMA_LIMITS__MAX_LIVE_SUBAGENT_THREADS`	`25`	한 세션이 동시에 보유할 수 있는 최대 서브에이전트 스레드 수입니다. 스레드는 보관되거나 종료될 때까지 집계되므로, 유휴 스레드도 집계됩니다. 한도에 도달하면 에이전트는 다른 서브에이전트를 시작할 수 없습니다. 최솟값은 `1`이고, 최댓값은 `4000`입니다.
`scheduler.max_concurrent_turns` `CMA_SCHEDULER__MAX_CONCURRENT_TURNS`	`64`	`store.backend: postgres` 전용. 한 서버가 동시에 실행하는 최대 턴 수입니다. 최솟값은 `1`입니다. 서버는 서브에이전트 턴 전용의 추가 슬롯을 둡니다. 그 수는 이 값의 4분의 1이며, 최소 `4`입니다. 기본값에서는 한 서버가 64개의 턴과 16개의 서브에이전트 턴을 실행할 수 있습니다.
`scheduler.claim_poll_interval` `CMA_SCHEDULER__CLAIM_POLL_INTERVAL`	`1s`	`store.backend: postgres` 전용. 빈 턴 슬롯이 있는 서버가 데이터베이스에서 대기 중인 작업을 확인하는 주기입니다. 최솟값은 `50ms`입니다.
`scheduler.sandbox_claim` `CMA_SCHEDULER__SANDBOX_CLAIM`	`immediate`	워커가 세션의 샌드박스를 시작할 수 있는 시점입니다. `immediate`는 세션이 생성되는 즉시를 의미하므로, 첫 번째 도구 호출의 대기 시간이 가장 짧습니다. `tool_call`은 샌드박스가 필요한 세션의 첫 번째 도구 호출 시점을 의미하므로, 그러한 도구 호출을 하지 않는 세션은 샌드박스를 사용하지 않습니다.
`limits.model_call_timeout` `CMA_LIMITS__MODEL_CALL_TIMEOUT`	`20m`	서버가 취소하기 전까지 재시도를 포함하여 하나의 모델 호출이 실행될 수 있는 시간입니다.
`limits.stream_idle_timeout` `CMA_LIMITS__STREAM_IDLE_TIMEOUT`	`5m`	서버가 해당 시도를 포기하기 전까지 모델 호출의 응답이 아무것도 전달하지 않을 수 있는 시간입니다.
`limits.mcp_call_timeout` `CMA_LIMITS__MCP_CALL_TIMEOUT`	`4m`	서버가 포기하기 전까지 하나의 MCP 도구 호출이 실행될 수 있는 시간입니다.

모델 및 컴팩션

설정 환경 변수	기본값	설명
`models.settings` 파일 전용	없음	모델 ID를 키로 하는, 서버의 기본 제공 모델 카탈로그에 대한 변경 사항입니다. 모델 항목을 참조하세요.
`compaction.triggers` 파일 전용	각 모델 컨텍스트 윈도우의 약 90%	모델 ID를 키로 하는, 해당 모델에서 턴이 기록을 컴팩션하는 컨텍스트 크기(토큰 단위)입니다. 최솟값은 `50000`입니다. 각 모델은 컴팩션을 지원해야 합니다.

모델 항목

models.settings의 각 항목은 카탈로그의 모델을 변경하거나 모델을 추가합니다. 카탈로그에 있는 모델의 경우, 생략한 필드는 기본 제공 값을 유지합니다.

필드	설명
`fast_supported`	모델이 `speed: "fast"`를 수락하는지 여부입니다. 추가하는 모델에는 필수입니다.
`inference_geo_supported`	모델이 `inference_geo`를 수락하는지 여부입니다.
`forced_tool_choice_supported`	모델이 하나의 도구를 호출하도록 강제하는 요청을 수락하는지 여부입니다. 서버는 승인된 `web_search` 또는 `web_fetch` 호출을 실행할 때만 이러한 요청을 보냅니다. `false`이면 서버는 이 모델에서 도구를 강제하지 않습니다.
`effort_supported`	모델이 effort 수준을 수락하는지 여부입니다.
`effort_levels`	모델이 수락하는 effort 수준으로, `low`, `medium`, `high`, `xhigh`, `max` 중에서 선택합니다. 기본 제공 수준이 없는 모델에서 `effort_supported: true`와 함께 사용할 때 필수입니다.
`effort_default`	에이전트가 effort 수준을 지정하지 않은 세션의 effort 수준입니다. `effort_levels` 중 하나여야 합니다. 기본 제공 기본값이 없는 모델에서 `effort_supported: true`와 함께 사용할 때 필수입니다.
`thinking`	서버가 요청하는 사고 모드로, `enabled` 또는 `adaptive`입니다.
`thinking_budget`	서버가 `thinking: enabled`와 함께 보내는 사고 예산(토큰 단위)입니다.
`max_tokens`	각 모델 호출의 `max_tokens` 값입니다.

서버의 콘솔

설정 환경 변수	기본값	설명
`console.serve` `CMA_CONSOLE__SERVE`	`true`	서버의 콘솔을 제공할지 여부입니다.

설정 위치

Compose 스택에 자격 증명 전달하기

표 읽는 방법

서버 및 로깅

데이터베이스

추론 프로바이더

클라우드 프로바이더

모델 게이트웨이

단기 게이트웨이 토큰

싱글 사인온

발급자 항목

시크릿 매니저

HashiCorp Vault

에이전트 ID

이그레스 게이트웨이

MCP 서버

Git 저장소

웹 도구 및 스킬

제한, 타임아웃 및 스케줄링

모델 및 컴팩션

모델 항목

서버의 콘솔