--- title: 자체 호스팅 워커 참조 url: https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference description: "자체 호스팅 샌드박스 워커에 대한 참조: ant CLI 플래그, 환경 변수, 호스트 요구 사항, 파일 시스템 경로 및 SDK 헬퍼 옵션." featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 이 페이지는 `self_hosted` 환경을 처리하는 사전 빌드된 워커를 설명합니다. 작업 중심 가이드는 [자체 호스팅 샌드박스](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes)와 [자체 호스팅 워커 배포](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers)부터 시작하세요. ## CLI 명령 및 플래그 | 명령 | 설명 | | ---------------------- | -------------------------------------------------------------------------------------------------- | | `ant beta:worker poll` | 환경의 큐에서 작업 항목을 가져와(claim) 각 세션을 프로세스 내에서 실행합니다. `--on-work`를 사용하면 대신 각 작업 항목에 대해 사용자의 스크립트를 호출합니다. | | `ant beta:worker run` | 가져온 세션 하나를 처리한 후 종료합니다. 세션별 샌드박스의 진입점으로 사용하세요. | | 플래그 | 설명 | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `--environment-id` | 작업을 폴링할 환경입니다. `ANTHROPIC_ENVIRONMENT_ID`에서도 읽습니다. | | `--environment-key` | 이 환경에 대해 워커를 인증합니다. `ANTHROPIC_ENVIRONMENT_KEY`에서도 읽습니다. | | `--workdir` | 스킬이 다운로드되고 도구가 파일을 읽고 쓰는 디렉터리입니다. 기본값은 `.`(현재 디렉터리)입니다. | | `--on-work` | 도구를 프로세스 내에서 실행하는 대신 가져온 각 작업 항목에 대해 호출할 스크립트입니다. 세션 세부 정보를 환경 변수로, 작업 항목을 표준 입력의 JSON으로 받습니다. | | `--max-idle` | 세션이 `end_turn` [중지 이유](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons)로 유휴 상태가 된 후 종료하기 전까지 대기하는 시간입니다. 기본값은 `60s`입니다. | | `--log-format` | 로그 출력 형식입니다. 구조화된 로그 수집에는 `json`을 사용하세요. 기본값은 `text`입니다. | ## 환경 변수 | 변수 | 설명 | 설정 주체 | | ------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ANTHROPIC_ENVIRONMENT_ID` | 워커가 처리하는 큐가 속한 환경입니다. | 사용자가 워커 호스트에서 설정합니다. 폴러가 이를 `--on-work` 스크립트에 전달합니다. | | `ANTHROPIC_ENVIRONMENT_KEY` | 워커를 해당 큐에 인증합니다. | 사용자가 워커 호스트에서 설정합니다. 폴러가 이를 `--on-work` 스크립트에 전달합니다. | | `ANTHROPIC_SESSION_ID` | 가져온 작업 항목이 나타내는 세션입니다. | 폴러가 `--on-work` 스크립트를 위해 설정합니다. | | `ANTHROPIC_WORK_ID` | 가져온 작업 항목입니다. | 폴러가 `--on-work` 스크립트를 위해 설정합니다. | | `ANTHROPIC_WORK_SECRET` | 작업 항목의 세션별 시크릿입니다. | 사용자가 설정합니다. 폴러는 이를 설정하지 않습니다. [작업 항목의 시크릿 전달](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret)을 참조하세요. | | `ANTHROPIC_BASE_URL` | 기본 API 엔드포인트를 재정의합니다. 선택 사항입니다. | 사용자가 워커 호스트에서 설정합니다. | | `ANTHROPIC_WEBHOOK_SIGNING_KEY` | 수신되는 웹훅 페이로드를 검증합니다. | 사용자가 웹훅 핸들러 호스트에서 설정합니다. | ## 호스트 요구 사항 | 워커 | 요구 사항 | | --------------- | ------------------------------------------------------------------------------- | | 모든 워커 | 정확히 해당 경로에 `/bin/bash`가 있는 Linux 호스트. 워커의 bash 도구는 `PATH`를 참조하지 않고 이를 직접 호출합니다. | | TypeScript SDK | `PATH`에 있는 `unzip` 및 `tar`, 그리고 Node.js 22 이상. | | Python 및 Go SDK | 추가 바이너리가 필요하지 않습니다. 이 SDK들은 아카이브 추출에 표준 라이브러리를 사용합니다. | [메모리 스토어](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory#requirements)에는 자체 요구 사항이 추가됩니다. ## 샌드박스 파일 시스템 | 경로 | 내용 | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/workspace` | 도구 실행 및 스킬 다운로드를 위한 시스템 기본 작업 디렉터리입니다. 다른 작업 디렉터리를 사용하는 경우 Claude가 스킬 파일을 찾을 수 있도록 에이전트의 시스템 프롬프트를 업데이트하세요. | | `/skills//` | 에이전트의 다운로드된 스킬입니다. | | `/mnt/memory//` | 연결된 메모리 스토어마다 하나의 디렉터리로, 스토어의 `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`)에 위치합니다(예: `/mnt/memory/user-preferences/`). 워커는 세션을 가져올 때 이 디렉터리를 생성하고 세션이 끝나면 제거합니다. | 자체 호스팅 환경에서는 세션의 시스템 프롬프트에 Anthropic 관리형 샌드박스에서 사용되는 `/mnt/session/outputs` 지침이 포함되지 않습니다. 최종 결과물은 에이전트가 샌드박스 파일 시스템에 기록하는 위치에 저장되며, 일반적으로 작업 디렉터리 아래에 있습니다. 스킬에는 에이전트가 직접 실행할 수 있는 실행 파일이 포함될 수 있습니다. CLI 및 SDK 워커는 스킬 번들을 추출할 때 번들에 기록된 실행 권한을 유지합니다. 스킬 다운로드를 수동으로 구현하는 경우 실행 권한 설정은 사용자의 책임입니다. ## SDK 헬퍼 Python, TypeScript 및 Go SDK는 서로 다른 제어 수준의 세 가지 헬퍼를 제공합니다: | 헬퍼 | 기능 | 사용 시점 | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------- | | [`EnvironmentWorker`](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#environment-worker) | 폴링, 설정 및 실행을 처음부터 끝까지 처리합니다. | 대부분의 경우. | | [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#work-poller) | 작업 큐를 폴링하고 가져온 각 세션을 제공합니다. | 각 세션에서 일어날 일을 직접 결정하는 경우. 예를 들어 도구를 프로세스 내에서 실행하는 대신 샌드박스를 시작하는 경우. | | [`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) | 세션 ID와 도구 목록이 주어지면 단일 세션에 대한 도구 호출을 실행합니다. | 이미 작업을 가져왔고 실행 계층만 필요한 경우. | ### EnvironmentWorker | 메서드 | 설명 | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `run()` (go: `Run()`) | 무기한 실행되며 세션이 도착하는 대로 가져옵니다. | | `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | 가져온 단일 작업 항목을 처리하고 반환합니다. 작업, 세션 및 환경 식별자와 `work_secret` (typescript: `workSecret`; go: `WorkSecret`)을 명시적으로 전달하거나, [`ANTHROPIC_*` 변수](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#environment-variables)를 읽도록 하세요. | | 옵션 | 설명 | | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` (go: `ToolsFunc`) | 세션의 `AgentToolContext`를 받아 도구 목록을 반환하는 팩토리입니다. 기본값은 표준 에이전트 도구 세트입니다. | | `memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | 세션이 실행되는 동안 연결된 메모리 스토어가 서버와 조정되는 빈도입니다. [동기화 간격](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory#sync-interval)을 참조하세요. | | `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | 에이전트가 로컬에서 삭제한 파일을 스토어에서도 삭제할지 여부입니다. [삭제](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory#deletions)를 참조하세요. | `EnvironmentWorker`는 `AgentToolContext`와 도구 세트를 자동으로 관리합니다. 도구 목록을 사용자 지정하려면 `tools` (go: `ToolsFunc`) 팩토리를 전달하세요: ```python Python EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool]) ``` ```typescript TypeScript new EnvironmentWorker({ client, environmentId, environmentKey, tools: (ctx) => [betaBashTool(ctx), myCustomTool] }); ``` C# SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 사용자 정의 도구 호출에 응답하려면 [커스텀 도구 결과 반환하기](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#return-a-custom-tool-result)에서와 같이 각 결과를 세션의 이벤트 스트림으로 전송하세요. ```go Go worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool { return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), myCustomTool} }, }) ``` Java SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 사용자 정의 도구 호출에 응답하려면 [커스텀 도구 결과 반환하기](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#return-a-custom-tool-result)에서와 같이 각 결과를 세션의 이벤트 스트림으로 전송하세요. PHP SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 사용자 정의 도구 호출에 응답하려면 [커스텀 도구 결과 반환하기](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#return-a-custom-tool-result)에서와 같이 각 결과를 세션의 이벤트 스트림으로 전송하세요. Ruby SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 사용자 정의 도구 호출에 응답하려면 [커스텀 도구 결과 반환하기](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#return-a-custom-tool-result)에서와 같이 각 결과를 세션의 이벤트 스트림으로 전송하세요. ### 작업 폴러 | 옵션 | 설명 | | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `drain` (go: `Drain`) | 새 작업을 기다리지 않고 큐가 비면 폴링을 중지할지 여부입니다. | | `block_ms` (typescript: `blockMs`; go: `BlockMs`) | 각 폴링이 반환하기 전에 작업이 도착하기를 기다리는 시간(밀리초)입니다. 1에서 999 사이여야 하며, 헬퍼가 자동으로 다시 폴링합니다. 비차단 확인을 하려면 `null` (python: `None`; go: `param.Null[int64]()`)을 전달하세요. 기본값은 999ms 롱 폴링입니다. | | `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | 가져왔지만 이 밀리초 내에 확인(acknowledge)되지 않은 작업 항목을 다시 가져옵니다. | | `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | 루프 본문이 각 작업 항목 처리를 마치면 해당 작업 항목에 대한 중지 신호를 게시할지 여부입니다. 작업 항목을 실행하는 주체가 직접 중지를 게시하는 경우 `false` (python: `False`; go: `param.NewOpt(false)`)로 설정하세요. `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`)이 그렇게 하며, 사용자가 시작한 샌드박스가 중지 호출을 담당하는 경우도 마찬가지입니다. | 전체 예제는 [SDK 폴러에서 샌드박스 시작](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers#launch-sandboxes-from-the-sdk-poller)을 참조하세요. ### 세션 도구 러너 `client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)는 도구 목록을 `tools` (go: `Tools`)로 받습니다. 해당 목록을 만들려면 `AgentToolContext`를 직접 설정하고 `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`)를 호출하세요: ```python Python 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: # /workspace/skills//에 다운로드된 스킬 tools = beta_agent_toolset_20260401(env) ``` ```typescript TypeScript import { setupSkills, betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node"; const ctx = { workdir: "/workspace", client, sessionId: work.data.id }; await setupSkills(ctx); const tools = betaAgentToolset20260401(ctx); ``` C# SDK에는 `AgentToolContext`가 없습니다. ```go Go env := &agenttoolset.AgentToolContext{Workdir: "/workspace"} if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil { panic(err) } // /workspace/skills//에 다운로드된 스킬 tools := agenttoolset.BetaAgentToolset20260401(env) ``` Java SDK에는 `AgentToolContext`가 없습니다. PHP SDK에는 `AgentToolContext`가 없습니다. Ruby SDK에는 `AgentToolContext`가 없습니다. ### AgentToolContext 및 에이전트 도구 세트 `AgentToolContext`는 도구 호출을 위한 실행 컨텍스트입니다. 작업 디렉터리와 경로 정책을 정의하며, 세션의 스킬을 다운로드할 수 있습니다. | 옵션 | 설명 | | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`) | 작업 디렉터리 외에 파일 도구(`read`, `write`, `edit`, `glob`, `grep`)가 접근할 수 있는 디렉터리입니다. | | `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | `write` 및 `edit`가 경로를 거부하는 디렉터리입니다. | `EnvironmentWorker`는 세션의 메모리 스토어 디렉터리를 `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`)에 직접 추가하고, `access: "read_only"`로 연결된 스토어의 디렉터리를 `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`)에 추가합니다. 이 제한은 파일 도구에만 적용되는 보호 장치이며 샌드박스가 아닙니다. `bash`는 제한하지 않습니다. `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`)는 `AgentToolContext`를 받아 표준 도구 구현(`bash`, `read`, `write`, `edit`, `glob`, `grep`)을 반환합니다.