클라우드 환경 설정

"Environment"(환경)는 에이전트가 실행되는 샌드박스 구성을 정의합니다. 환경을 한 번 생성한 다음, 세션을 시작할 때마다 해당 ID를 참조합니다. 여러 세션이 동일한 환경을 공유할 수 있지만, 각 세션은 자체적으로 격리된 샌드박스(새로운 Linux 컨테이너)를 갖습니다.

이 페이지에서는 type: cloud 환경을 다룹니다. 자체 인프라에서 샌드박스를 실행하려면 자체 호스팅 샌드박스를 참조하세요.

환경 생성

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: python-dev
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

환경을 서로 구분할 수 있도록 고유하고 설명적인 name을 사용하세요.

세션에서 환경 사용

세션을 생성할 때 환경 ID를 문자열로 전달하세요.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

구성 옵션

패키지

packages 필드는 에이전트가 시작되기 전에 샌드박스에 패키지를 사전 설치합니다. 패키지는 각각의 패키지 관리자에 의해 설치되며, 동일한 환경을 공유하는 세션 간에 캐시됩니다. 여러 패키지 관리자가 지정된 경우 알파벳 순서(apt, cargo, gem, go, npm, pip)로 실행됩니다. 선택적으로 특정 버전을 고정할 수 있습니다. 고정되지 않은 패키지는 최신 버전이 설치됩니다. 환경이 limited 네트워킹을 사용하는 경우 networking.allow_package_managers도 true로 설정하세요. 그렇지 않으면 요청이 400 오류와 함께 거부됩니다.

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted

지원되는 패키지 관리자:

네트워킹

networking 필드는 샌드박스의 아웃바운드 네트워크 액세스를 제어합니다. 이 필드는 Anthropic 서버에서 실행되는 web_search 또는 web_fetch 도구에는 영향을 주지 않습니다. 해당 도구가 접근할 수 있는 사이트를 제한하려면 에이전트 도구 세트의 해당 도구 항목에 allowed_domains 또는 blocked_domains를 설정하세요. 웹 검색 및 웹 가져오기 도메인 제한을 참조하세요.

다음 예시는 limited 네트워킹으로 환경을 생성합니다:

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true

limited 네트워킹을 사용하는 경우:

• allowed_hosts는 샌드박스가 접근할 수 있는 도메인을 지정합니다. 순수 호스트 이름 또는 와일드카드 패턴(예: *.example.com)을 지정하세요. URL 스킴, 포트 또는 경로는 포함하지 마세요.
• allow_mcp_servers는 allowed_hosts 배열에 나열된 것 외에도 에이전트에 구성된 MCP 서버 엔드포인트에 대한 아웃바운드 액세스를 허용합니다. 기본값은 false입니다.
• allow_package_managers는 allowed_hosts 배열에 나열된 것 외에도 일련의 공개 패키지 레지스트리 및 코드 호스트에 대한 아웃바운드 액세스를 허용합니다. 목록은 패키지 관리자 호스트를 참조하세요. 기본값은 false입니다. 환경에서 packages를 지정하는 경우에는 항상 true로 설정하세요. 그렇지 않으면 레지스트리 호스트가 allowed_hosts에 나열되어 있더라도 요청이 400 오류와 함께 거부됩니다.

패키지 관리자 호스트

allow_package_managers가 true인 경우, 샌드박스는 allowed_hosts에 있는 호스트 외에도 다음 호스트에 접근할 수 있습니다. 이 목록은 Anthropic이 관리하며 변경될 수 있습니다.

환경 수명 주기

• 환경은 명시적으로 보관되거나 삭제될 때까지 유지됩니다.
• 여러 세션이 동일한 환경을 참조하더라도 각 세션은 자체 샌드박스 인스턴스를 갖습니다. 세션은 파일 시스템 상태를 공유하지 않습니다.
• 환경은 버전 관리되지 않습니다. 환경을 자주 업데이트하는 경우, 각 세션이 어떤 구성을 사용했는지 알 수 있도록 변경 사항을 직접 기록해 두세요.

환경 관리

# List environments
environments = client.beta.environments.list()

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(environment.id)

사전 설치된 런타임

클라우드 샌드박스에는 일반적인 언어 런타임, 데이터베이스 및 명령줄 도구가 기본으로 포함되어 있습니다. 전체 목록은 클라우드 샌드박스 참조를 참조하세요.

다음 단계