---
title: 세션당 하나의 샌드박스 실행
url: https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session
description: Kubernetes의 Helm 차트, 스폰 스크립트 또는 SDK 폴러를 사용하여 각 세션에 자체 호스팅 샌드박스를 제공합니다.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: 자체 호스팅 Managed Agents를 제외하고 ZDR 적격 대상이 아닙니다. 세션은 상태를 유지하는 리소스이며, 트랜스크립트는 삭제할 때까지 유지됩니다.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
---

세션당 샌드박스 패턴에서는 각 세션이 새로운 샌드박스에서 실행되며, 각 샌드박스는 자체 파일 시스템, 리소스 제한 및 네트워크 제어를 가질 수 있습니다. 다른 패턴과 비교하려면 [배포 패턴 선택](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern)을 참조하세요.

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

* **[Kubernetes의 Helm 차트](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes):** Anthropic의 디스패처가 작업을 가져오고 클러스터에서 각 세션마다 파드를 시작합니다.
* **[스폰 스크립트](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script):** `ant` CLI가 작업을 가져오고 스크립트를 호출하며, 스크립트가 모든 플랫폼에서 샌드박스를 시작합니다.
* **[SDK 폴러](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-from-the-sdk-poller):** 사용자의 코드가 작업을 가져오고 샌드박스를 시작합니다.

[Kubernetes에서 샌드박스 실행](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes) 이후의 섹션은 스폰 스크립트와 SDK 폴러에 적용됩니다.

## Kubernetes에서 샌드박스 실행

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

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

샌드박스 파드는 `ant` CLI 워커를 실행합니다. 기본 동기화 설정으로 [메모리 스토어](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory)를 지원하며, [사용자 정의 도구](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-custom-tools)는 지원하지 않습니다.

### 차트 설치

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

* **클러스터 내:** [Agent Sandbox](https://github.com/kubernetes-sigs/agent-sandbox) 컨트롤러(GKE에서는 Agent Sandbox 애드온), gVisor를 실행하는 노드, NetworkPolicy를 적용하는 네트워크 플러그인.
* **사용자 자신의 네임스페이스 내:** Restricted Pod Security Standard 레이블, 환경 ID와 [환경 키](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes#run-your-first-session)가 포함된 Secret, 디스패처의 TLS 인증서.

[GitHub의 설치 가이드](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md)에 각 클러스터 유형별 설정 단계가 있습니다. 업그레이드와 키 교체도 다룹니다.

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

<File filename="cma-values.yaml">
  ```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
  ```
</File>

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

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

```bash
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
```

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

<Warning>
  `helm uninstall`만으로 차트를 제거하지 마세요. 이 명령은 네트워크 정책을 삭제하고 세션의 샌드박스를 정책 없이 실행 중인 상태로 남깁니다. [설치 가이드의 Removal 섹션](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#removal)에 제시된 순서대로 먼저 디스패처를 중지하고 샌드박스를 삭제하세요.
</Warning>

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

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

Python이나 Git 같은 도구를 에이전트에 더 제공하려면 릴리스 태그 기준으로 저장소에서 두 이미지를 모두 빌드하세요. 명령은 [설치 가이드의 Install 섹션](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#install)에 있습니다. 이미지를 차트 버전을 태그로 하여 `cma-dispatcher` 및 `cma-sandbox`로 레지스트리에 푸시하세요. 그런 다음 `image.registry`를 해당 레지스트리로 설정하세요. 이미지 다이제스트를 고정하는 경우 자체 이미지의 다이제스트를 사용하세요.

### 네트워크 이그레스 제한

기본적으로 차트의 네트워크 정책은 샌드박스가 공용 IPv4 인터넷에 접근하도록 허용합니다. 사설 주소 범위, 클라우드 메타데이터 서버, `egress.clusterCIDRs`에 있는 주소는 차단합니다. 프롬프트 인젝션을 당한 에이전트는 자신이 읽은 내용을 샌드박스가 접근할 수 있는 모든 주소로 보낼 수 있습니다. 자세한 내용은 설치 가이드의 [Network egress](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#network-egress)를 참조하세요.

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

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

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

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

    <File filename="Dockerfile">
      ```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"]
      ```
    </File>
  </Step>

  <Step title="스폰 스크립트 작성">
    스크립트는 세션 세부 정보를 새 샌드박스로 전달합니다. 폴러 호스트에 `jq`가 필요합니다.

    <File filename="spawn.sh">
      ```bash
      #!/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
      ```
    </File>

    폴러는 `ANTHROPIC_WORK_ID`, `ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_SESSION_ID`, `ANTHROPIC_ENVIRONMENT_KEY`를 설정합니다. `ANTHROPIC_BASE_URL`은 사용자가 폴러 호스트에 설정한 경우에만 스크립트에 전달됩니다. 스크립트는 표준 입력으로 들어오는 작업 항목의 JSON에서 `ANTHROPIC_WORK_SECRET`을 읽습니다. [환경 변수](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#environment-variables)를 참조하세요.

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

  <Step title="폴러 시작">
    ```bash
    ant beta:worker poll --on-work ./spawn.sh
    ```
  </Step>
</Steps>

## 작업 항목의 시크릿 전달

가져온 각 작업 항목에는 Anthropic이 해당 세션에 대해 발급하는 `secret` (csharp, go: `Secret`)이 포함될 수 있습니다. 세션을 실행하는 워커는 [메모리 스토어](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory)를 마운트하기 위해 이 시크릿이 필요합니다.

하나의 프로세스에서 세션을 가져오고 실행하는 워커는 시크릿을 직접 전달합니다. `run()` (go: `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()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`) | 가져온 각 작업 항목의 `secret` (go: `Secret`) 필드    | 샌드박스 환경의 `ANTHROPIC_WORK_SECRET` 또는 `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`)의 `work_secret` (typescript: `workSecret`; go: `WorkSecret`) 인수 |

시크릿은 해당 세션을 처리하는 샌드박스에만 전달하고 절대 로그에 기록하지 마세요. 시크릿이 환경 키와 어떤 관계인지는 [보안 모델](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-security)을 참조하세요.

## SDK 폴러에서 샌드박스 시작

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

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    루프에서 작업을 가져오고 각 세션마다 샌드박스를 시작하려면 단일 셸 명령보다 많은 로직이 필요합니다. 셸에서는 [스폰 스크립트로 샌드박스 시작](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script)에서처럼 스폰 스크립트와 함께 `ant beta:worker poll --on-work`를 실행하세요.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    셸에서 작업을 가져오고 각 세션마다 샌드박스를 시작하려면 스폰 스크립트와 함께 `ant beta:worker poll --on-work`를 실행하세요. [스폰 스크립트로 샌드박스 시작](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script)을 참조하세요.
  </CodeGroupItem>

  ```python Python
  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())
  ```

  ```typescript TypeScript
  import { spawn } from "node:child_process";
  import { once } from "node:events";
  import Anthropic from "@anthropic-ai/sdk";
  import { WorkPoller } from "@anthropic-ai/sdk/helpers/beta/environments";
  import type { BetaSelfHostedWork } from "@anthropic-ai/sdk/resources/beta/environments";

  const 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
  ];

  const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
  const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
  const client = new Anthropic({ authToken: environmentKey });

  async function launchContainer(work: BetaSelfHostedWork): Promise<void> {
    console.log(`claimed session ${work.data.id}`);
    // `docker run`을 자체 샌드박스 실행기로 바꾸세요. 환경
    // 키(API 키는 절대 전달하지 마세요)와 작업 항목의 세션별 시크릿을 전달하세요. 내부의 워커는
    // 세션의 메모리 스토어를 마운트하려면 이 시크릿이 필요합니다.
    const env = {
      ...process.env,
      ANTHROPIC_WORK_ID: work.id,
      ANTHROPIC_SESSION_ID: work.data.id,
      ANTHROPIC_WORK_SECRET: work.secret ?? ""
    };
    const forward = SANDBOX_ENV.flatMap((name) => ["-e", name]);
    const launcher = spawn("docker", ["run", "--rm", "--detach", ...forward, "your-image"], {
      env,
      stdio: "inherit"
    });
    await once(launcher, "close");
  }

  const poller = new WorkPoller({
    client,
    environmentId,
    environmentKey,
    autoStop: false // the launched sandbox owns the stop call
  });

  for await (const work of poller) {
    await launchContainer(work);
  }
  ```

  <CodeGroupItem language="C#">
    C# SDK에는 작업을 폴링하는 헬퍼가 없습니다. 자체 코드에서 작업을 가져오려면 [환경 작업 엔드포인트](https://platform.claude.com/docs/ko/api/beta/environments/work)를 호출하여 항목을 폴링하고 확인(acknowledge)하세요.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"fmt"
  	"log"
  	"os"
  	"os/exec"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  	"github.com/anthropics/anthropic-sdk-go/v2/packages/param"
  )

  var sandboxEnv = []string{
  	"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
  }

  func launchContainer(ctx context.Context, work *anthropic.BetaSelfHostedWork) error {
  	fmt.Printf("claimed session %s\n", work.Data.ID)
  	// `docker run`을 자체 샌드박스 실행기로 바꾸세요. 환경 키(API 키는 절대 전달하지 마세요)와
  	// 작업 항목의 세션별 시크릿을 전달하세요. 내부의 워커는
  	// 세션의 메모리 스토어를 마운트하기 위해 이 시크릿이 필요합니다.
  	args := []string{"run", "--rm", "--detach"}
  	for _, name := range sandboxEnv {
  		args = append(args, "-e", name)
  	}
  	launcher := exec.CommandContext(ctx, "docker", append(args, "your-image")...)
  	launcher.Env = append(os.Environ(),
  		"ANTHROPIC_WORK_ID="+work.ID,
  		"ANTHROPIC_SESSION_ID="+work.Data.ID,
  		"ANTHROPIC_WORK_SECRET="+work.Secret,
  	)
  	launcher.Stdout, launcher.Stderr = os.Stdout, os.Stderr
  	return launcher.Run()
  }

  func main() {
  	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
  	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")

  	client := anthropic.NewClient(option.WithAuthToken(environmentKey))

  	ctx := context.Background()

  	poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{
  		EnvironmentID:  environmentID,
  		EnvironmentKey: environmentKey,
  		AutoStop:       param.NewOpt(false), // the launched sandbox owns the stop call
  	})
  	defer poller.Close()

  	for work, err := range poller.All() {
  		if err != nil {
  			log.Fatal(err)
  		}
  		if err := launchContainer(ctx, work); err != nil {
  			log.Fatal(err)
  		}
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Java SDK에는 작업을 폴링하는 헬퍼가 없습니다. 자체 코드에서 작업을 가져오려면 [환경 작업 엔드포인트](https://platform.claude.com/docs/ko/api/beta/environments/work)를 호출하여 항목을 폴링하고 확인(acknowledge)하세요.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    PHP SDK에는 작업을 폴링하는 헬퍼가 없습니다. 자체 코드에서 작업을 가져오려면 [환경 작업 엔드포인트](https://platform.claude.com/docs/ko/api/beta/environments/work)를 호출하여 항목을 폴링하고 확인(acknowledge)하세요.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Ruby SDK에는 작업을 폴링하는 헬퍼가 없습니다. 자체 코드에서 작업을 가져오려면 [환경 작업 엔드포인트](https://platform.claude.com/docs/ko/api/beta/environments/work)를 호출하여 항목을 폴링하고 확인(acknowledge)하세요.
  </CodeGroupItem>
</CodeGroup>

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

샌드박스가 [사용자 정의 도구를 제공](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-custom-tools)하거나 [기본값이 아닌 메모리 동기화 설정](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory#configure-sync)을 사용해야 하는 경우 `ant beta:worker run` 엔트리포인트를 SDK 엔트리포인트로 교체하세요. 이 엔트리포인트는 `EnvironmentWorker`를 생성하고 `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`)을 호출하며, 이 메서드는 스폰 스크립트가 전달하는 것과 동일한 `ANTHROPIC_*` 변수를 읽습니다.

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    워커는 단일 HTTP 요청이 아니라 장기 실행 프로세스입니다. 사용자 정의 도구를 제공하거나 메모리 동기화 설정을 변경하려면 Python, TypeScript 또는 Go SDK의 `EnvironmentWorker`를 사용하세요.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    `ant` CLI 워커(`ant beta:worker run`)는 사용자 정의 도구를 제공하거나 메모리 동기화 설정을 변경할 수 없습니다. 둘 중 하나를 하려면 Python, TypeScript 또는 Go SDK의 `EnvironmentWorker`를 사용하세요.
  </CodeGroupItem>

  ```python Python
  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())
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";
  import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

  const client = new Anthropic({ authToken: process.env.ANTHROPIC_ENVIRONMENT_KEY });
  const controller = new AbortController();
  // 컨테이너가 중지될 때 중단하면 워커가 종료 전에 변경된 메모리
  // 파일을 업로드하고 스토어 디렉터리를 제거할 수 있습니다.
  process.once("SIGTERM", () => controller.abort());
  process.once("SIGINT", () => controller.abort());

  // 인수 없이 호출하면 handleItem()은 스폰 스크립트가 전달한
  // ANTHROPIC_* 변수(ANTHROPIC_WORK_SECRET 포함)를 읽습니다.
  await new EnvironmentWorker({
    client,
    workdir: "/workspace",
    signal: controller.signal
  }).handleItem();
  ```

  <CodeGroupItem language="C#">
    C# SDK에는 `EnvironmentWorker`가 없습니다.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"log"
  	"os"
  	"os/signal"
  	"syscall"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  )

  func main() {
  	// 컨테이너가 중지될 때 컨텍스트를 취소하면 워커가 종료 전에
  	// 변경된 메모리 파일을 업로드하고 스토어 디렉터리를 제거할 수 있습니다.
  	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  	defer stop()

  	client := anthropic.NewClient(option.WithAuthToken(os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")))
  	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
  		Workdir: "/workspace",
  	})
  	// 옵션이 제로 값이면 HandleItem은 스폰 스크립트가 전달한 ANTHROPIC_* 변수를 읽으며,
  	// 여기에는 ANTHROPIC_WORK_SECRET도 포함됩니다.
  	if err := worker.HandleItem(ctx, environments.HandleItemOptions{}); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Java SDK에는 `EnvironmentWorker`가 없습니다.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    PHP SDK에는 `EnvironmentWorker`가 없습니다.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Ruby SDK에는 `EnvironmentWorker`가 없습니다.
  </CodeGroupItem>
</CodeGroup>

## 세션용 파일 준비

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

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

cURL 샘플은 `ANTHROPIC_AUTH_TOKEN`에서 액세스 토큰을 읽습니다. 토큰을 얻으려면 [페더레이션 설정](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation#set-up-federation)에 설명된 대로 기본 `workspace:developer` 범위로 Workload Identity Federation을 설정하세요. 그런 다음 [워크로드에서 인증](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation#authenticate-from-your-workload)에 나와 있는 대로 워크로드의 ID 토큰을 액세스 토큰으로 교환하세요. `ANTHROPIC_AUTH_TOKEN`은 페더레이션 설정보다 우선하므로 cURL 샘플을 실행하는 셸에서만 설정하세요. [인증](https://platform.claude.com/docs/ko/manage-claude/authentication)에는 빠른 시작의 API 키와 같이 API가 허용하는 다른 자격 증명이 나열되어 있습니다.

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "environment_id": "env_01595EKxaaTTGwwY3kyXdtbs",
      "metadata": {"input_file": "s3://my-bucket/data.csv"}
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent agent_011CYm1BLqPXpQRk5khsSXrs \
    --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
    --metadata '{"input_file": "s3://my-bucket/data.csv"}'
  ```

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

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

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Metadata = new Dictionary<string, string> { ["input_file"] = "s3://my-bucket/data.csv" },
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
  	EnvironmentID: environment.ID,
  	Metadata: map[string]string{
  		"input_file": "s3://my-bucket/data.csv",
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .metadata(SessionCreateParams.Metadata.builder()
          .putAdditionalProperty("input_file", JsonValue.from("s3://my-bucket/data.csv"))
          .build())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      metadata: ['input_file' => 's3://my-bucket/data.csv'],
  );
  ```

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

## 다음 단계

<CardGroup cols={2}>
  <Card title="자체 호스팅 워커 모니터링 및 문제 해결" icon="lightning" href="https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-operations">
    큐 깊이를 확인하고, 세션과 워커를 깔끔하게 중지하고, 일반적인 오류를 해결합니다.
  </Card>
</CardGroup>
