Claude Platform Docs
Managed Agents자체 호스팅 샌드박스

세션당 하나의 샌드박스 실행

Kubernetes의 Helm 차트, 스폰 스크립트 또는 SDK 폴러를 사용하여 각 세션에 자체 호스팅 샌드박스를 제공합니다.

세션당 샌드박스 패턴에서는 각 세션이 새로운 샌드박스에서 실행되며, 각 샌드박스는 자체 파일 시스템, 리소스 제한 및 네트워크 제어를 가질 수 있습니다. 다른 패턴과 비교하려면 배포 패턴 선택을 참조하세요.

세 가지 방법으로 설정할 수 있습니다:

  • Kubernetes의 Helm 차트: Anthropic의 디스패처가 작업을 가져오고 클러스터에서 각 세션마다 파드를 시작합니다.
  • 스폰 스크립트: ant CLI가 작업을 가져오고 스크립트를 호출하며, 스크립트가 모든 플랫폼에서 샌드박스를 시작합니다.
  • SDK 폴러: 사용자의 코드가 작업을 가져오고 샌드박스를 시작합니다.

Kubernetes에서 샌드박스 실행 이후의 섹션은 스폰 스크립트와 SDK 폴러에 적용됩니다.

Kubernetes에서 샌드박스 실행

Anthropic은 Helm 차트인 cma-sandboxes와 해당 이미지를 게시합니다. 이 차트는 사용자의 Kubernetes 클러스터에서 세션당 하나의 샌드박스를 실행합니다. 차트의 디스패처는 환경의 작업 큐를 폴링하고 각 세션에 전용 파드를 제공합니다:

  • 격리: 각 파드는 차트의 네트워크 정책 뒤에서 gVisor 하에 실행됩니다. 각 파드는 자체 파일 시스템과 리소스 제한을 가집니다. 환경 키는 디스패처만 보유합니다.
  • 세션 어피니티: 세션의 모든 메시지는 해당 세션의 샌드박스로 전달됩니다. 세션이 30분 동안 유휴 상태이면(차트의 sandbox.idleTimeout 설정 기본값) 해당 파드가 중지됩니다. /workspace 볼륨은 세션이 종료될 때까지 유지됩니다. 다음 메시지가 오면 동일한 볼륨에서 파드가 시작됩니다.
  • 웜 풀: Google Kubernetes Engine(GKE)을 제외하고, 차트는 새 세션을 위해 두 개의 파드를 준비 상태로 유지합니다(차트의 sandbox.warmPoolSize 설정 기본값).

샌드박스 파드는 ant CLI 워커를 실행합니다. 기본 동기화 설정으로 메모리 스토어를 지원하며, 사용자 정의 도구는 지원하지 않습니다.

차트 설치

차트는 GKE, Amazon EKS 및 기타 클러스터에서 실행됩니다. 설치하기 전에 다음을 설정하세요:

  • 클러스터 내: Agent Sandbox 컨트롤러(GKE에서는 Agent Sandbox 애드온), gVisor를 실행하는 노드, NetworkPolicy를 적용하는 네트워크 플러그인.
  • 사용자 자신의 네임스페이스 내: Restricted Pod Security Standard 레이블, 환경 ID와 환경 키가 포함된 Secret, 디스패처의 TLS 인증서.

GitHub의 설치 가이드에 각 클러스터 유형별 설정 단계가 있습니다. 업그레이드와 키 교체도 다룹니다.

설정을 cma-values.yaml로 저장하세요. 이 파일에 있는 세 가지 설정이 없으면 설치가 실패합니다:

cma-values.yaml
platform: gke             # or eks, or generic for any other cluster
egress:
  # The chart already blocks the private ranges. List your other addresses
  # that sandboxes must not reach.
  clusterCIDRs:
    - 203.0.113.10/32     # your cluster's Kubernetes API endpoint
  cmaServer:
    public: true          # the Claude API has a public address

설치 가이드에는 GKE Autopilot의 gke.dns처럼 클러스터에 따라 달라지는 설정이 나열되어 있습니다. 또한 egress.clusterIsPrivate: true가 egress.clusterCIDRs를 대신하는 경우도 설명합니다.

그런 다음 차트를 설치하세요:

helm install cma \
  oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
  --version 0.1.0 \
  --namespace cma \
  -f cma-values.yaml \
  --wait

설치 후에는 설치 가이드에 설명된 사전 점검을 실행하세요.

샌드박스 이미지에 도구 추가

게시된 샌드박스 이미지는 bash, curl, jq 및 ant CLI가 포함된 Alpine Linux입니다. 차트는 읽기 전용 루트 파일 시스템과 루트가 아닌 사용자로 이미지를 실행하므로, 에이전트는 세션 중에 패키지를 설치할 수 없습니다.

Python이나 Git 같은 도구를 에이전트에 더 제공하려면 릴리스 태그 기준으로 저장소에서 두 이미지를 모두 빌드하세요. 명령은 설치 가이드의 Install 섹션에 있습니다. 이미지를 차트 버전을 태그로 하여 cma-dispatcher 및 cma-sandbox로 레지스트리에 푸시하세요. 그런 다음 image.registry를 해당 레지스트리로 설정하세요. 이미지 다이제스트를 고정하는 경우 자체 이미지의 다이제스트를 사용하세요.

네트워크 이그레스 제한

기본적으로 차트의 네트워크 정책은 샌드박스가 공용 IPv4 인터넷에 접근하도록 허용합니다. 사설 주소 범위, 클라우드 메타데이터 서버, egress.clusterCIDRs에 있는 주소는 차단합니다. 프롬프트 인젝션을 당한 에이전트는 자신이 읽은 내용을 샌드박스가 접근할 수 있는 모든 주소로 보낼 수 있습니다. 자세한 내용은 설치 가이드의 Network egress를 참조하세요.

  • Dataplane V2를 사용하는 GKE: egress.mode: fqdnGke를 설정하면 egress.fqdnGke.hosts에 있는 호스트의 443 포트로만 연결을 제한할 수 있습니다. 이 목록에 api.anthropic.com을 유지하고, 에이전트의 명령에 필요한 모든 호스트를 추가하세요. 기본 모드와 달리 이 모드에는 차단된 범위 목록이 없습니다. 나열된 호스트의 이름이 해석되는 모든 주소를 허용하므로, DNS를 신뢰할 수 있는 호스트만 나열하세요. 샌드박스는 여전히 DNS 조회 내부에 데이터를 담아 외부로 보낼 수 있습니다.
  • 기타 클러스터 및 Dataplane V2를 사용하지 않는 GKE: 기본 모드가 유일한 모드입니다.
  • 모든 클러스터: 네트워크 정책은 클러스터 자체 노드가 수신 대기하는 포트를 다루지 않습니다. 설치 가이드의 Node isolation you own을 참조하세요.

스폰 스크립트로 샌드박스 시작

호스트의 폴러가 작업을 가져오고 각 작업 항목마다 스크립트를 한 번씩 호출합니다. 스크립트는 해당 세션 하나를 위한 샌드박스를 시작합니다.

  1. 샌드박스 이미지 빌드

    ant를 설치하고 ant beta:worker run을 엔트리포인트로 설정하세요. 샌드박스가 시작되면 환경 변수에서 세션 세부 정보를 읽고, 해당 세션을 처리한 후 종료합니다. 베이스 이미지는 /bin/bash를 제공해야 하며, 빌드에서는 ant를 다운로드하는 데에만 curl을 사용합니다.

    Dockerfile
    FROM your-base-image
    ARG ANT_VERSION=2.11.0
    ARG TARGETARCH
    RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \
        curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \
          | tar -xz -C /usr/local/bin ant
    WORKDIR /workspace
    VOLUME /workspace
    ENTRYPOINT ["ant", "beta:worker", "run"]
  2. 스폰 스크립트 작성

    스크립트는 세션 세부 정보를 새 샌드박스로 전달합니다. 폴러 호스트에 jq가 필요합니다.

    spawn.sh
    #!/bin/bash
    # spawn.sh: 가져온 작업 항목마다 한 번씩 호출됩니다
    # 가져온 작업 항목은 stdin을 통해 JSON으로 전달됩니다.
    ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
    export ANTHROPIC_WORK_SECRET
    mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
    exec docker run --rm \
      -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
      -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
      -e ANTHROPIC_WORK_SECRET \
      -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
      your-image

    폴러는 ANTHROPIC_WORK_ID, ANTHROPIC_ENVIRONMENT_ID, ANTHROPIC_SESSION_ID, ANTHROPIC_ENVIRONMENT_KEY를 설정합니다. ANTHROPIC_BASE_URL은 사용자가 폴러 호스트에 설정한 경우에만 스크립트에 전달됩니다. 스크립트는 표준 입력으로 들어오는 작업 항목의 JSON에서 ANTHROPIC_WORK_SECRET을 읽습니다. 환경 변수를 참조하세요.

    /host/outputs는 사용자가 선택하는 호스트 디렉터리입니다. 이를 /workspace에 마운트하면 샌드박스가 종료된 후 세션의 결과물을 가져올 수 있습니다. 이 마운트에는 다운로드된 skills/ 트리와 모든 중간 파일도 함께 저장됩니다.

  3. 폴러 시작

    ant beta:worker poll --on-work ./spawn.sh

작업 항목의 시크릿 전달

가져온 각 작업 항목에는 Anthropic이 해당 세션에 대해 발급하는 secret이 포함될 수 있습니다. 세션을 실행하는 워커는 메모리 스토어를 마운트하기 위해 이 시크릿이 필요합니다.

하나의 프로세스에서 세션을 가져오고 실행하는 워커는 시크릿을 직접 전달합니다. run()을 사용하는 EnvironmentWorker가 이러한 워커 중 하나이며, --on-work 없이 실행하는 ant beta:worker poll도 마찬가지입니다. 사용자의 코드가 작업 가져오기와 워커 사이에 있는 경우에는 사용자가 시크릿을 전달해야 합니다:

작업을 가져오는 방법시크릿이 도착하는 위치워커에 전달하는 방법
ant beta:worker poll --on-work스크립트의 표준 입력으로 들어오는 작업 항목 JSON의 secret 필드샌드박스 환경의 ANTHROPIC_WORK_SECRET
Python, TypeScript 또는 Go SDK의 work.poller()가져온 각 작업 항목의 secret 필드샌드박스 환경의 ANTHROPIC_WORK_SECRET 또는 handle_item()의 work_secret 인수

시크릿은 해당 세션을 처리하는 샌드박스에만 전달하고 절대 로그에 기록하지 마세요. 시크릿이 환경 키와 어떤 관계인지는 보안 모델을 참조하세요.

SDK 폴러에서 샌드박스 시작

ant beta:worker poll --on-work 대신 자체 코드에서 작업을 가져오려면 Python, TypeScript 또는 Go SDK의 폴러를 사용하세요: work.poller(). 폴러는 큐를 폴링하여 가져온 각 세션을 제공하며, 사용자는 샌드박스를 시작합니다:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)


async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # `docker run`을 자체 샌드박스 실행기로 바꾸세요. 환경
    # 키(API 키는 절대 전달하지 마세요)와 작업 항목의 세션별 시크릿을 전달하세요. 내부 워커는
    # 세션의 메모리 스토어를 마운트하는 데 이 시크릿이 필요합니다.
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-image", env=env
    )
    await launcher.wait()


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

샌드박스 내부에서 SDK 워커 실행

샌드박스가 사용자 정의 도구를 제공하거나 기본값이 아닌 메모리 동기화 설정을 사용해야 하는 경우 ant beta:worker run 엔트리포인트를 SDK 엔트리포인트로 교체하세요. 이 엔트리포인트는 EnvironmentWorker를 생성하고 handle_item()을 호출하며, 이 메서드는 스폰 스크립트가 전달하는 것과 동일한 ANTHROPIC_* 변수를 읽습니다.

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    async with AsyncAnthropic(
        auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    ) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # 인수 없이 호출하면 handle_item()은 스폰
        # 스크립트가 전달한 ANTHROPIC_* 변수(ANTHROPIC_WORK_SECRET 포함)를 읽습니다.
        task = asyncio.create_task(worker.handle_item())
        # 컨테이너가 중지될 때 작업을 취소하면 워커가 종료 전에
        # 변경된 메모리 파일을 업로드하고 스토어 디렉터리를 제거할 수 있습니다.
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task


asyncio.run(main())

세션용 파일 준비

Anthropic은 자체 호스팅 샌드박스에 파일이나 GitHub 저장소를 마운트하지 않습니다. 세션별 파일을 사용할 수 있도록 하려면:

  1. S3 경로나 커밋 SHA 같은 파일 참조를 세션의 metadata 필드에 전달하세요.
  2. 스폰 스크립트 또는 --on-work 핸들러에서 세션을 조회(GET /v1/sessions/{session_id})하고 metadata를 읽으세요. 가져온 작업 항목에는 세션 ID가 포함되지만 메타데이터는 포함되지 않습니다.
  3. 도구가 실행되기 전에 파일을 작업 디렉터리에 준비하세요.

cURL 샘플은 ANTHROPIC_AUTH_TOKEN에서 액세스 토큰을 읽습니다. 토큰을 얻으려면 페더레이션 설정에 설명된 대로 기본 workspace:developer 범위로 Workload Identity Federation을 설정하세요. 그런 다음 워크로드에서 인증에 나와 있는 대로 워크로드의 ID 토큰을 액세스 토큰으로 교환하세요. ANTHROPIC_AUTH_TOKEN은 페더레이션 설정보다 우선하므로 cURL 샘플을 실행하는 셸에서만 설정하세요. 인증에는 빠른 시작의 API 키와 같이 API가 허용하는 다른 자격 증명이 나열되어 있습니다.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

다음 단계

큐 깊이를 확인하고, 세션과 워커를 깔끔하게 중지하고, 일반적인 오류를 해결합니다.

이 페이지가 도움이 되었나요?