자체 호스팅 샌드박스

기본적으로 Managed Agents는 Anthropic 관리형 클라우드 샌드박스 내에서 도구와 코드를 실행합니다. 자체 호스팅 샌드박스는 오케스트레이션은 Anthropic 측에 유지하면서 도구 실행을 사용자가 제어하는 인프라로 이동시키므로, 에이전트의 코드, 파일 시스템, 네트워크 송신이 사용자 환경을 벗어나지 않습니다.

도구 실행은 사용자 호스트에 머무릅니다. 에이전트가 읽고 쓰는 파일 시스템, 생성하는 프로세스, 접근할 수 있는 네트워크가 모두 사용자의 제어 하에 있습니다. 도구 입력과 출력은 여전히 Anthropic의 컨트롤 플레인(Claude가 실행되는 곳)으로 전달되어 모델이 결과를 확인하고 다음 작업을 결정할 수 있습니다. 전체 데이터 흐름 경계는 보안 모델을 참조하세요.

클라우드 환경과의 차이점

자체 호스팅은 에이전트가 네트워크 경계를 벗어날 수 없는 데이터를 다루어야 하거나, 공개적으로 라우팅할 수 없는 내부 서비스에 접근해야 하거나, 조직 자체의 규정 준수 및 감사 제어 하에서 실행되어야 하는 경우에 적합합니다.

Zero Data Retention 및 HIPAA BAA 적격성에 대해서는 API 및 데이터 보존을 참조하세요.

MCP 터널과 함께 사용하는 경우

자체 호스팅은 에이전트의 코드가 실행되는 위치를 제어합니다. MCP 터널은 Anthropic이 사용자 네트워크 내의 MCP 서버에 도달하는 방법을 제어합니다. 이 둘은 독립적입니다. Anthropic의 클라우드 샌드박스에서 실행되는 세션도 터널을 통해 프라이빗 MCP 서버에 접근할 수 있으며, 자체 호스팅 세션은 터널링된 MCP 서버나 공개 MCP 서버 중 어느 것이든 사용할 수 있습니다. 실행과 도구 접근을 모두 사용자 경계 내에 유지하려면 두 가지를 함께 사용하세요.

환경 워커

환경 워커는 사용자가 자체 인프라에서 실행하는 프로세스입니다. Anthropic으로부터 도구 실행 요청을 받아 로컬에서 실행합니다. self_hosted 환경은 작업 큐 역할을 합니다. 세션이 이 환경에 할당되면 Anthropic은 해당 세션을 작업 항목으로 큐에 추가합니다. 워커는 해당 큐에서 작업 항목을 가져와 각 항목에 대한 실행 컨텍스트를 생성하고, 에이전트의 스킬(에이전트에게 도메인별 전문성을 제공하는 재사용 가능한 파일 시스템 기반 리소스)을 다운로드하고, 도구 호출을 실행한 후 결과를 다시 게시합니다.

작업 항목은 환경의 큐를 폴링하여 가져옵니다. 지속적으로 폴링하는 상시 실행 워커 또는 session.status_run_started 이벤트에 의해 깨어나 폴링을 시작하는 웹훅 트리거 핸들러 중 하나를 사용할 수 있습니다.

CLI와 SDK 모두 사전 구축된 워커를 제공합니다. ant CLI는 상시 실행 패턴만 지원하며, SDK는 상시 실행과 웹훅 트리거 방식을 모두 지원합니다. 둘 다 구성 가능합니다. CLI 플래그는 레퍼런스의 자체 호스팅 워커를, SDK 옵션은 이 페이지의 SDK 헬퍼를 참조하세요. 더 세밀한 제어가 필요하면 Environments Work 엔드포인트를 직접 호출하여 자체 워커를 구현하세요. Claude Platform on AWS에서는 GET /v1/environments/{id}/work 목록 엔드포인트와 해당 SDK 기능이 현재 제공되지 않습니다. 다른 work 엔드포인트(poll, ack, heartbeat, stop, post results, 항목별 get, stats)는 정상적으로 작동합니다.

샌드박스 파일 시스템

• /workspace: 도구 실행 및 스킬 다운로드를 위한 시스템 기본 작업 디렉터리입니다. CLI의 --workdir 플래그는 기본적으로 현재 디렉터리를 사용합니다. 시스템 기본값과 일치시키려면 --workdir /workspace를 전달하세요. 스킬은 <workdir>/skills/<name>/에 다운로드됩니다. 다른 작업 디렉터리를 사용하는 경우 Claude가 스킬 파일을 찾을 수 있도록 에이전트의 시스템 프롬프트를 업데이트하세요.
• /mnt/session/outputs: 워커 하네스는 Claude에게 최종 산출물을 이 경로에 작성하도록 지시합니다. 샌드박스 모드에서는 세션 종료 후 출력을 가져올 수 있도록 호스트 디렉터리를 이 경로에 마운트하세요. 인프로세스 모드에서는 워커의 파일 도구가 작업 디렉터리 아래에 쓰기 때문에 이 경로가 적용되지 않습니다.

시작하기 전에

다음이 필요합니다.

• 기존 에이전트. 없는 경우 먼저 빠른 시작을 완료하고 에이전트 ID를 기록해 두세요.
• /bin/bash가 정확히 해당 경로에 있는 Linux 호스트. TypeScript SDK는 추가로 unzip, tar, Node.js 22 이상이 필요합니다. Python SDK는 아카이브 추출에 표준 라이브러리를 사용하므로 추가 바이너리 요구 사항이 없습니다. 이러한 종속성은 고정된 경로에서 확인되며 PATH 재정의를 따르지 않습니다.
• 워커 호스트에 설치된 ant CLI 또는 Anthropic SDK(Python, TypeScript 또는 Go).
• 두 가지 자격 증명: 환경 키(다음 단계에서 생성)는 워커를 해당 큐에 인증합니다. Claude API 키는 워커 호스트 외부에서 세션을 생성하고 큐 통계를 읽는 데 사용됩니다.

워커 실행

가장 간단한 설정을 원하면 상시 실행을 선택하세요. 장기 실행 프로세스가 큐를 지속적으로 폴링하며 아웃바운드 HTTPS만 필요합니다. 유휴 폴러 실행을 피하려면 웹훅 트리거를 선택하세요. 이 방식은 Anthropic이 접근할 수 있는 웹훅 엔드포인트가 필요합니다(엔드포인트 설정 및 서명 검증은 웹훅 참조).

SDK 헬퍼

SDK는 서로 다른 수준의 제어를 제공하는 세 가지 헬퍼를 제공합니다. EnvironmentWorker가 대부분의 사용 사례를 다룹니다. 세션별 프로세스를 직접 시작하거나 이미 가져온 세션에 대해 도구를 실행해야 하는 경우 하위 수준 헬퍼를 사용하세요.

• EnvironmentWorker: 즉시 사용 가능한 워커입니다. 폴링, 설정, 실행을 처음부터 끝까지 처리합니다.
  • .run(): 무기한 실행되며 세션이 도착하는 대로 처리합니다. SIGTERM 시 정상 종료됩니다.
  • .handle_item(): 대기 중인 세션 하나를 가져와 처리한 후 종료합니다.
• work.poller(): 사용자를 대신하여 작업 큐를 폴링하고 가져온 각 세션을 제공합니다. 각 세션에 대해 수행할 작업을 직접 결정하려는 경우(예: 인프로세스로 도구를 실행하는 대신 샌드박스를 시작하는 경우)에 사용하세요.
  • drain: 새 작업을 기다리지 않고 큐가 비면 폴링을 중지할지 여부입니다.
  • block_ms: 작업이 도착할 때까지 대기할 시간(밀리초)입니다. 1에서 999 사이여야 합니다(폴링당 대기 시간이며, 헬퍼가 자동으로 다시 폴링합니다). 논블로킹 확인을 위해서는 null(Python에서는 None, Go에서는 param.Null[int64]())을 전달하세요. 매개변수를 생략하면 기본값인 999ms 롱 폴링이 사용됩니다.
  • reclaim_older_than_ms: 응답을 중단한 워커에 임대된 작업 항목을 다시 가져옵니다.
  • auto_stop: 이터레이터가 종료된 후 작업 항목에 중지 신호를 게시할지 여부입니다. Go 폴러는 옵트아웃이 없으며 항상 중지 신호를 게시하므로, 분리하지 말고 세션이 완료될 때까지 루프 본문에서 블로킹하세요.
• client.beta.sessions.events.tool_runner(): 세션 ID와 도구 목록이 주어지면 단일 세션에 대한 도구 호출을 실행합니다. 이미 작업을 가져왔고 실행 계층만 필요한 경우에 사용하세요.

세션별 프로세스를 직접 시작하려는 경우(예: 가져온 각 세션에 대해 샌드박스를 생성하는 경우) work 폴러를 직접 사용하세요.

import asyncio
import os

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


async def launch_container(work: BetaSelfHostedWork) -> None:
    # 자체 세션별 샌드박스 런처로 교체하세요.
    # 실행된 샌드박스에는 API 키가 아니라
    # ANTHROPIC_ENVIRONMENT_KEY를 전달하세요.
    print(f"claimed session {work.data.id}")


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())

**AgentToolContext**는 도구 호출을 위한 실행 컨텍스트입니다. 작업 디렉터리와 경로 정책을 정의하며, 컨텍스트 매니저로 사용될 때 선택적으로 세션의 스킬을 다운로드합니다. **beta_agent_toolset_20260401(env)**는 AgentToolContext를 받아 표준 도구 구현(bash, read, write, edit, glob, grep)을 반환합니다.

EnvironmentWorker 사용 시: 둘 다 자동으로 관리됩니다. 도구 목록을 사용자 정의하려면 tools 팩토리를 전달하세요.

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

work.poller() 및 tool_runner() 사용 시: client.beta.sessions.events.tool_runner()에 tools로 도구 목록을 전달하세요. 해당 목록을 구성하려면 AgentToolContext를 직접 설정하고 beta_agent_toolset_20260401(env)를 호출하세요.

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

워커 연결 확인

별도의 셸에서 환경 키가 아닌 Claude API 키를 사용하여 workers_polling이 1 이상인지 확인하세요.

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

workers_polling이 0으로 유지되면 워커가 큐에 도달하지 못하고 있는 것입니다. 워커 호스트에 ANTHROPIC_ENVIRONMENT_KEY와 ANTHROPIC_ENVIRONMENT_ID가 설정되어 있는지 확인하세요. 전체 통계 응답 및 다른 언어 예제는 큐 깊이 읽기를 참조하세요.

세션 시작

워커가 실행되면 해당 환경을 대상으로 하는 세션을 생성하세요. 세션은 환경의 작업 큐에 들어가 워커가 가져갈 때까지 대기합니다. 연결된 워커가 없으면 세션은 실패하지 않고 큐에 대기 상태로 남습니다.

Anthropic은 자체 호스팅 샌드박스에 파일이나 GitHub 저장소를 마운트하지 않습니다. 세션별 파일을 사용할 수 있게 하려면 세션 metadata 필드에 파일 참조(예: S3 경로 또는 커밋 SHA)를 전달하세요. spawn 스크립트 또는 --on-work 핸들러가 가져온 작업 항목에서 해당 메타데이터를 읽고(Environments Work 엔드포인트를 통해) 도구 실행이 시작되기 전에 파일을 작업 디렉터리에 준비합니다.

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

CLI 플래그의 전체 목록은 레퍼런스의 자체 호스팅 워커를, SDK 헬퍼 옵션은 SDK 헬퍼를 참조하세요.

모니터링 및 운영

이러한 호출은 Claude API 키로 인증된 모니터링 또는 운영 도구에서 실행되어 워커 플릿을 관찰하고 관리합니다. 가져오기 및 keep-alive 루프는 워커 헬퍼 내부에서 처리되므로 해당 엔드포인트를 직접 호출할 필요가 없습니다.

큐 깊이 읽기

work.stats는 환경의 큐 상태를 반환합니다.

• depth는 가져가기를 기다리는 항목 수입니다. 이 값을 기준으로 워커 플릿을 확장하거나 백로그에 대한 알림을 설정하세요.
• pending은 워커가 가져가서 현재 처리 중인 항목 수입니다.
• oldest_queued_at은 큐에서 가장 오래된 항목의 타임스탬프이며, 큐가 비어 있으면 null입니다.
• workers_polling은 지난 30초 동안 폴링한 워커 수입니다. 활성 상태 알림에 사용하세요.

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

세션 정상 중지

work.stop을 사용하여 특정 세션을 처리 중인 워커에게 정상적으로 종료하도록 요청하세요. 워커는 진행 중인 도구 호출을 완료하고 최종 상태를 게시한 후 세션을 해제합니다. 현재 도구 호출이 완료될 때까지 기다리지 않고 즉시 중단하려면 요청 본문에 force: true를 전달하세요.

이러한 호출은 워커 호스트가 아닌 운영 도구에서 실행되므로 ANTHROPIC_WORK_ID가 자동으로 설정되지 않습니다. 다음 예제를 실행하기 전에 대상 작업 항목의 ID로 설정하세요.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

다음 단계