Claude Managed Agents 셀프 호스트 샌드박스 입문 — 자사 인프라에서 도구 실행

Anthropic은 2026년 5월 19일(Code with Claude London), Claude Managed Agents에 **셀프 호스트 샌드박스 (self-hosted sandboxes)**를 추가했다고 발표했습니다. 현재는 퍼블릭 베타 (public beta)로 제공되고 있습니다.

이 기사에서는 셀프 호스트 샌드박스란 무엇인지, 어떤 아키텍처로 작동하는지, 그리고 실제로 어떻게 구축하는지를 공식 문서를 바탕으로 해설합니다.

• 셀프 호스트 샌드박스의 메커니즘과 클라우드 실행과의 차이점

• environment worker (워크 큐 방식)의 동작 모델

• ant CLI / SDK를 사용한 워커 기동 절차 - 대응하는 매니지드 프로바이더 (Cloudflare / Daytona / Modal / Vercel)의 특징

• Claude의 에이전트 기능을 업무에 사용하고 싶은 엔지니어

• 기밀 데이터나 프라이빗 네트워크 제약으로 인해 클라우드 실행이 어려운 분

• 에이전트의 실행 환경을 자사의 컴플라이언스 및 감사 하에 두고 싶은 분

• 셀프 호스트 샌드박스는, 에이전트 루프 (agent loop)는 Anthropic 측에 남겨둔 채, 도구 실행(tool execution)만을 자사 인프라로 옮기는 메커니즘입니다. 파일 시스템, 프로세스, 네트워크 egress는 자사의 관리 하에 놓입니다.

• 자사에서 구동하는 environment worker가 Anthropic의 워크 큐 (work queue)로부터 세션을 클레임 (claim)하여 실행합니다.

• ant CLI / SDK (Python, TypeScript, Go)에 내장 워커가 동봉되어 있으며, Cloudflare, Daytona, Modal, Vercel의 매니지드 프로바이더에도 대응합니다.

Managed Agents는 기본적으로 Anthropic이 관리하는 클라우드 샌드박스 내에서 도구(tool)나 코드를 실행합니다. 셀프 호스트 샌드박스는 오케스트레이션 (orchestration)을 Anthropic 측에 남겨두면서, 도구 실행을 자사가 관리하는 인프라로 옮깁니다. 에이전트의 코드, 파일 시스템, 네트워크 egress가 자사 환경 밖으로 나가지 않는다는 점이 특징입니다.

구분	클라우드 환경	셀프 호스트 샌드박스
도구 실행 장소	Anthropic 관리 샌드박스	자사 인프라
...

단, 주의할 점으로 도구의 입력과 출력은 계속해서 Anthropic의 컨트롤 플레인 (control plane)으로 흐릅니다. Claude가 모델로서 결과를 보고 다음 행동을 판단하기 때문입니다. "코드가 실행되는 장소"는 자사 내에 닫히지만, "모델이 결과를 읽는" 플로우는 Anthropic 측에 남습니다.

셀프 호스트가 적합한 경우는 다음과 같습니다.

• 네트워크 경계 밖으로 내보낼 수 없는 데이터를 에이전트가 다뤄야 할 필요가 있는 경우
• 공개 라우팅되지 않은 사내 서비스에 도달하고 싶은 경우
• 자사의 컴플라이언스 및 감사 통제 하에서 에이전트를 구동하고 싶은 경우

셀프 호스트의 핵심은 environment worker입니다. 이는 자사 인프라 상에서 구동되는 프로세스로, Anthropic으로부터 도구 실행 요청을 받아 로컬에서 실행합니다.

self_hosted 환경은 **워크 큐 (work queue)**로서 기능합니다. 세션이 해당 환경에 할당되면, Anthropic은 세션을 워크 아이템 (work item)으로서 큐에 쌓습니다. 워커는 다음 흐름으로 처리합니다.

• 큐에서 워크 아이템을 클레임 (claim)한다
• 세션별 실행 컨텍스트 (execution context)를 생성한다
• 에이전트의 스킬 (skill) (파일 기반의 재사용 가능한 리소스)을 다운로드한다
• 도구 호출 (tool call)을 실행한다
• 결과를 Anthropic에 반환한다

워크 아이템의 클레임 방식은 두 가지가 있습니다.

• always-on worker: 상시 폴링 (polling)을 지속함
• webhook-triggered handler: session.status_run_started 이벤트로 깨어나서 폴링을 시작함

CLI (ant)는 always-on 방식만 지원하며, SDK는 always-on과 webhook 방식을 모두 지원합니다.

• <workdir>/skills/<name>/: 도구 실행과 스킬 다운로드의 기본 작업 디렉토리. 스킬은 /workspace에 위치합니다.

에 전개되는 -
: 최종 결과물의 출력 경로. 샌드박스 (Sandbox) 모드에서는 이 경로에 호스트 디렉토리를 마운트(mount)하면, 세션 종료 후 결과물을 꺼낼 수 있는 /mnt/session/outputs

• 기존의 에이전트 (없다면 Quickstart에서 생성하고 agent ID를 기록해 둘 것)

• /bin/bash를 정확히 해당 경로에 가진 Linux 호스트

• TypeScript SDK는 추가로 unzip, tar, Node.js 22 이상이 필요 - Python SDK는 표준 라이브러리로 완결되어 추가 바이너리가 필요 없음

• TypeScript SDK는 추가로 ant CLI 또는 Anthropic SDK (Python / TypeScript / Go) - 2개의 자격 증명(credential): 워커 인증을 위한 **환경 키 (Environment Key)**와, 세션 생성 및 통계 취득을 위한 Claude API 키

Console에서 Workspace > Environments > New > Self-hosted를 통해 생성할 수 있습니다. API로도 생성 가능합니다.

import anthropic
client = anthropic.Anthropic()
environment = client.beta.environments.create(
...

Console에서 대상 환경을 열고 「Generate environment key」를 클릭합니다. 키 생성은 (API로 환경을 만든 경우라도) Console 전용입니다. 생성한 키와 환경 ID를 워커 호스트에 설정합니다.

export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
export ANTHROPIC_ENVIRONMENT_ID="env_..."

가장 심플한 것은 always-on 방식입니다. ant CLI를 사용하면 명령어 한 줄로 기동할 수 있습니다.

ant beta:worker poll --workdir "/workspace"

SDK를 사용하는 경우에는 EnvironmentWorker 헬퍼(helper)를 사용합니다.

import asyncio
import os
from anthropic import AsyncAnthropic
...

워커(worker)는 SIGTERM / SIGINT를 받으면, 실행 중인 도구 호출을 드레인(drain)한 후 깔끔하게 종료됩니다.

다른 셸에서 (환경 키가 아니라) Claude API 키로 통계를 확인하여, workers_polling이 1 이상인지 확인합니다.

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

workers_polling이 0인 상태라면, 워커가 큐(queue)에 도달하지 못한 것입니다. 워커 호스트에서 ANTHROPIC_ENVIRONMENT_KEY와 ANTHROPIC_ENVIRONMENT_ID가 설정되어 있는지 확인하십시오.

SDK는 제어 수준이 다른 세 가지 헬퍼를 제공합니다. 대부분의 케이스는 EnvironmentWorker로 충분하며, 더 세밀한 제어가 필요할 때 하위 헬퍼로 내려가는 설계입니다.

• : 폴링(polling), 설정, 실행까지 일괄적으로 처리하는 표준 워커. EnvironmentWorker.run()은 상주하며, .handle_item()은 단 하나의 세션만 처리하고 종료합니다. - : 워크 큐를 폴링하고, 클레임(claim)한 세션을 하나씩 전달합니다. 세션마다 샌드박스를 기동하는 등 직접 처리 방식을 결정하고 싶을 때 사용합니다. work.poller()`
• : 단일 세션의 도구 호출만을 실행합니다. 이미 워크를 클레임했으며 실행 레이어만 필요할 때 사용합니다. client.beta.sessions.events.tool_runner()`

자사 인프라에서 직접 구동하는 것 외에도, 계산 자원과 분리하여 매니지드 프로바이더(managed provider)에 맡길 수도 있습니다. 각각 전용 가이드가 준비되어 있습니다.

프로바이더	특징
Cloudflare	microVM 기반 격리, zero-trust 비밀 정보 (secret) 주입, 커스터마이징 가능한 egress 프록시
Daytona	완전 구성 가능한 컴퓨터. 장시간 상태 유지 (stateful), SSH/인증이 포함된 프리뷰 URL, pause/restore 지원
Modal	AI 워크로드용 클라우드. 1초 미만의 실행 (sub-second startup), 수십만 개의 동시 샌드박스로 확장 가능
Vercel	VM 레벨의 보안 + VPC peering. 밀리초 단위 실행, 방화벽을 통한 자격 증명 (credential) 주입

셀프 호스트 샌드박스에서는

Memory 기능은 현재 지원되지 않습니다. 또한, Anthropic은 파일이나 GitHub 리포지토리를 셀프 호스트 샌드박스에 마운트하지 않습니다. 세션 고유의 파일을 전달하려면 S3 경로 나 커밋 SHA(commit SHA) 등의 참조를 세션의 metadata에 넣고, 워커(worker) 측에서 스테이징(staging)해야 합니다.

모니터링은 work.stats에서 수행할 수 있습니다. 주요 반환 필드는 다음과 같습니다.

• depth: 대기 중인 아이템 수 (백로그 알림 및 스케일링 판단에 사용)
• pending: 워커가 가져가서 처리 중인 아이템 수
• workers_polling: 최근 30초 동안 폴링(polling)한 워커 수 (생존 확인/health check에 사용)

참고로, 이러한 모니터링 관련 엔드포인트는 환경 키(environment key)가 아닌 조직의 API 키로 인증하며, 워커 호스트 외부에서 호출합니다. 워커 호스트에 ANTHROPIC_API_KEY를 두면, 조직 범위(organization scope)의 자격 증명이 에이전트의 도구 호출(tool call)에 노출될 수 있으므로 피해야 합니다.

• 셀프 호스트 샌드박스는 에이전트 루프(agent loop)를 Anthropic 측에 남겨두면서 도구 실행을 자사 경계 내로 폐쇄하는 메커니즘
• 핵심은 자사에서 구동하는 environment worker와 Anthropic 측의 워크 큐(work queue)
• ant CLI / SDK에 내장 워커가 포함되어 있으며, always-on 및 webhook 방식 모두 지원
• Cloudflare, Daytona, Modal, Vercel의 매니지드 프로바이더(managed provider)를 통해 격리 및 계산 자원을 위임 가능
• Memory 미지원, 파일은 metadata를 통해 전달해야 하는 등의 운영상 제약 주의

기밀 데이터나 프라이빗 네트워크 제약으로 인해 클라우드 실행을 보류했던 환경에서도, Claude 에이전트를 자사의 컴플라이언스(compliance) 하에서 구동할 수 있는 길이 열렸습니다. 프라이빗 MCP 서버에 접근하고 싶다면 MCP tunnels (research preview)와의 병용도 검토할 수 있습니다.

• New in Claude Managed Agents: self-hosted sandboxes and MCP tunnels (공식 블로그) — 발표 내용 및 프로바이더 개요
• Self-hosted sandboxes (공식 문서) — 아키텍처, 구축 절차, SDK 헬퍼
• Claude Managed Agents overview (공식 문서) — Managed Agents 전체 개요