---
title: 자체 호스팅 워커 배포
url: https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers
description: 자체 호스팅 샌드박스 워커가 작업을 가져오는 방식과 세션이 실행되는 위치를 선택한 다음, 상시 실행 워커를 실행하거나 웹훅에서 워커를 트리거하세요.
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#quickstart)은 지속적으로 폴링하며 모든 세션을 하나의 프로세스에서 실행하는 `ant` CLI 워커 하나를 실행합니다. 이 페이지는 배포 패턴을 선택하는 데 도움을 준 다음, 상시 실행 워커와 웹훅 트리거 워커를 다룹니다.

## 배포 패턴 선택

워커를 배포할 때는 두 가지를 선택해야 합니다. 워커가 작업을 가져오는 방식과 각 세션이 실행되는 위치입니다.

**워커가 작업을 가져오는 방식:**

* **상시 실행(Always-on):** 장기 실행 프로세스가 큐를 지속적으로 폴링합니다. 이 프로세스는 아웃바운드 HTTPS 요청만 보내므로 Anthropic에 엔드포인트를 노출하지 않아도 됩니다.
* **웹훅 트리거(Webhook-triggered):** 핸들러가 `session.status_run_started`에서 깨어나 폴링을 시작합니다. 유휴 폴러를 피할 수 있지만, Anthropic이 접근할 수 있는 [웹훅](https://platform.claude.com/docs/ko/managed-agents/webhooks) 엔드포인트가 필요합니다.

**각 세션이 실행되는 위치:**

* **프로세스 내(In process):** 세션을 가져온 워커가 하나의 공유 작업 디렉터리에서 해당 세션의 도구 호출도 실행합니다.
* **세션당 샌드박스(Sandbox per session):** 폴러가 가져온 각 세션마다 새 샌드박스를 시작합니다. 새로운 파일 시스템, 리소스 제한 또는 세션별 네트워크 제어 등 더 강력한 격리가 필요할 때 이 방식을 선택하세요. [세션당 하나의 샌드박스 실행](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session)을 참조하세요. 이 페이지에서는 Kubernetes용 Helm 차트도 다룹니다.

CLI 워커와 SDK 워커는 서로 다른 조합을 지원합니다:

| 기능 | `ant` CLI | SDK (Python, TypeScript, Go) |
| ----- | ----- | ----- |
| 상시 폴링 | 예 | 예 |
| 웹훅 트리거 | 아니요 | 예 |
| [세션당 샌드박스](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session) | 예 | 예 |
| [메모리 스토어](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) | 아니요 | 예 |

모든 CLI 플래그와 SDK 옵션은 [자체 호스팅 워커 참조](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference)를 참조하세요.

더 세밀하게 제어하려면 [환경 작업 엔드포인트](https://platform.claude.com/docs/ko/api/beta/environments/work)를 직접 호출하여 자체 워커를 구현하세요. 그러면 사용자의 워커가 SDK 워커가 하는 일을 수행합니다. 예를 들어 각 작업 항목을 확인(acknowledge)하고, 하트비트를 보내고, 에이전트의 스킬을 다운로드합니다. 세션의 [권한 정책(permission policy)](https://platform.claude.com/docs/ko/managed-agents/permission-policies#see-how-each-call-was-evaluated)이 허용하는 도구 호출만 실행합니다. 각 결과를 `user.tool_result` 또는 `user.custom_tool_result` 이벤트로 반환합니다. 마지막으로 항목을 중지합니다. [Python SDK](https://github.com/anthropics/anthropic-sdk-python/tree/main/src/anthropic/lib/environments), [TypeScript SDK](https://github.com/anthropics/anthropic-sdk-typescript/tree/main/src/lib/environments) 또는 [Go SDK](https://github.com/anthropics/anthropic-sdk-go/tree/main/lib/environments)에 있는 워커 소스를 참고 자료로 사용하세요.

## 상시 실행 워커 실행

이 샘플은 `/workspace`를 워커의 작업 디렉터리로 사용합니다. 이 디렉터리는 워커가 시작되기 전에 존재해야 합니다. 새 호스트에서는 [첫 번째 세션 실행하기](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes#run-your-first-session)의 "워커 시작하기" 단계에서처럼 디렉터리를 만들고 워커의 사용자에게 쓰기 권한을 부여하세요.

macOS에서는 루트 볼륨이 읽기 전용이므로 `mkdir`로 `/workspace`를 만들 수 없습니다. 해당 단계에 나와 있는 것처럼 대신 `~/workspace`를 만드세요. SDK는 `~`를 확장하지 않으므로 `/workspace` 대신 `echo ~/workspace`가 출력하는 전체 경로를 사용하세요.

큐를 지속적으로 폴링하는 워커를 시작합니다. 워커는 빠른 시작에서 받은 [환경 키](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes#run-your-first-session)로 인증합니다:

<CodeGroup exclude="shell:cURL, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    워커는 단일 HTTP 요청이 아니라 장기 실행 프로세스입니다. 대신 `ant` CLI 워커를 실행하세요: `ant beta:worker poll --workdir /workspace`.
  </CodeGroupItem>

  ```bash CLI
  ant beta:worker poll --workdir /workspace
  ```

  ```python Python
  import asyncio
  import contextlib
  import os
  import signal
  from anthropic import AsyncAnthropic
  from anthropic.lib.environments import EnvironmentWorker


  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:
          worker = EnvironmentWorker(
              client,
              environment_id=environment_id,
              environment_key=environment_key,
              workdir="/workspace",
          )
          task = asyncio.create_task(worker.run())
          # 프로세스를 강제 종료하는 대신 태스크를 취소하면 워커가 종료 전에
          # 진행 중인 작업 항목을 중지하고 변경된 메모리 파일을 업로드할 수 있습니다.
          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 environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
  const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
  const client = new Anthropic({ authToken: environmentKey });
  const controller = new AbortController();
  // 두 신호 중 하나로 중단하면 프로세스가 종료되기 전에 워커가 변경된 메모리 파일을 업로드하고
  // 스토어 디렉터리를 제거할 수 있습니다.
  process.once("SIGINT", () => controller.abort());
  process.once("SIGTERM", () => controller.abort());

  await new EnvironmentWorker({
    client,
    environmentId,
    environmentKey,
    workdir: "/workspace",
    signal: controller.signal
  }).run();
  ```

  <CodeGroupItem language="C#">
    C# SDK에는 `EnvironmentWorker`가 없습니다. 대신 `ant` CLI 워커를 실행하세요: `ant beta:worker poll --workdir /workspace`.
  </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() {
  	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
  	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

  	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  	defer stop()

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

  	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
  		EnvironmentID:  environmentID,
  		EnvironmentKey: environmentKey,
  		Workdir:        "/workspace",
  	})
  	if err := worker.Run(ctx); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Java SDK에는 `EnvironmentWorker`가 없습니다. 대신 `ant` CLI 워커를 실행하세요: `ant beta:worker poll --workdir /workspace`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    PHP SDK에는 `EnvironmentWorker`가 없습니다. 대신 `ant` CLI 워커를 실행하세요: `ant beta:worker poll --workdir /workspace`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Ruby SDK에는 `EnvironmentWorker`가 없습니다. 대신 `ant` CLI 워커를 실행하세요: `ant beta:worker poll --workdir /workspace`.
  </CodeGroupItem>
</CodeGroup>

## 웹훅으로 워커 트리거

<Steps>
  <Step title="세션 웹훅 구독">
    [Claude Console](https://platform.claude.com/settings/workspaces/default/webhooks)에서 `session.status_run_started` 이벤트를 수신하는 webhook 엔드포인트를 정의하세요. 자세한 내용은 [웹훅 구독하기](https://platform.claude.com/docs/ko/managed-agents/webhooks)를 참조하세요.
  </Step>

  <Step title="웹훅 서명 키 내보내기">
    [첫 번째 세션 실행하기](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes#run-your-first-session)의 환경 ID 및 키와 함께, 핸들러 호스트에서 webhook 서명 키를 내보내세요. 핸들러는 이 키를 사용하여 수신되는 페이로드를 검증합니다.

    ```bash
    export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."
    ```
  </Step>

  <Step title="웹훅 핸들러 구현">
    `session.status_run_started`가 발생하면 워커를 시작하세요. 핸들러는 큐를 비우면서 가져온 각 작업 항목을 (Python, TypeScript 및 Go SDK의) `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`)에 전달합니다. 이 메서드는 스킬을 다운로드하고, 도구 호출을 실행하고, 결과를 다시 게시한 후 반환합니다.

    샘플은 `/workspace`를 작업 디렉터리로 사용합니다. 핸들러를 시작하기 전에 핸들러 호스트에 해당 디렉터리를 만드세요. [첫 번째 세션 실행하기](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes#run-your-first-session)의 "워커 시작하기" 단계에서처럼 핸들러의 사용자가 이 디렉터리에 쓸 수 있는지 확인하세요.

    <CodeGroup exclude="shell, csharp, java, php, ruby">
      <CodeGroupItem language="cURL">
        이 핸들러에는 단일 셸 명령보다 더 많은 로직이 필요합니다. 실행하려면 Python, TypeScript 또는 Go SDK를 사용하세요.
      </CodeGroupItem>

      <CodeGroupItem language="CLI">
        이 핸들러에는 단일 셸 명령보다 더 많은 로직이 필요합니다. 실행하려면 Python, TypeScript 또는 Go SDK를 사용하세요.
      </CodeGroupItem>

      <CodeGroupItem>
        웹훅 서명을 검증하려면 webhooks extra를 설치하세요: `pip install "anthropic[webhooks]"`.

        ```python Python
        import asyncio
        import os
        import anthropic
        import standardwebhooks  # installed by the anthropic[webhooks] extra

        environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
        environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
        client = anthropic.AsyncAnthropic(
            auth_token=environment_key,
        )
        # shutdown()에 의해 취소되므로, 진행 중인 작업 항목이 변경된 메모리 파일을 업로드하고
        # 프로세스 종료 전에 스토어 디렉터리를 제거할 수 있습니다.
        inflight: set[asyncio.Task[None]] = set()


        # 호스트의 종료 훅에서 이를 await하세요. 예: ASGI lifespan 종료(FastAPI lifespan의
        # `yield` 이후 코드)는 uvicorn이 SIGTERM 시 실행합니다. uvicorn은 열린 요청이
        # 끝난 뒤 해당 훅을 실행하므로 --timeout-graceful-shutdown으로 대기 시간을 제한하세요.
        async def shutdown() -> None:
            for task in inflight:
                task.cancel()
            await asyncio.gather(*inflight, return_exceptions=True)


        async def handle(raw: bytes, headers: dict[str, str]) -> tuple[dict[str, str], int]:
            try:
                event = client.beta.webhooks.unwrap(raw.decode(), headers=headers)
            except standardwebhooks.WebhookVerificationError:
                return {"error": "signature verification failed"}, 401
            if event.data.type != "session.status_run_started":
                return {"status": "ignored"}, 200
            task = asyncio.create_task(run_queued_work())
            inflight.add(task)
            task.add_done_callback(inflight.discard)
            try:
                # 보호됨: 전달이 끊기거나 시간 초과되어도 항목을 취소하면 안 되며, 취소는 shutdown()이 합니다.
                await asyncio.shield(task)
            except asyncio.CancelledError:
                return {"status": "shutting down"}, 503
            return {"status": "ok"}, 200


        async def run_queued_work() -> None:
            async for work in client.beta.environments.work.poller(
                environment_id=environment_id,
                environment_key=environment_key,
                block_ms=None,
                reclaim_older_than_ms=2000,
                drain=True,
                auto_stop=False,
            ):
                await client.beta.environments.work.worker(workdir="/workspace").handle_item(
                    work_id=work.id,
                    environment_id=environment_id,
                    session_id=work.data.id,
                    environment_key=environment_key,
                    # 세션별 시크릿을 통해 워커가 세션의 메모리 스토어를 마운트할 수 있습니다.
                    work_secret=work.secret,
                )
        ```
      </CodeGroupItem>

      ```typescript TypeScript
      import Anthropic from "@anthropic-ai/sdk";

      const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
      const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
      const client = new Anthropic({
        authToken: environmentKey
      });
      // 호스트의 SIGTERM/SIGINT 핸들러에서 서버를 닫는 것과 함께 shutdown.abort()를 호출하고,
      // 종료 전에 진행 중인 handle() 호출을 기다리세요: abort는 실행 중인 작업 항목이 먼저
      // 변경된 메모리 파일을 업로드하고 스토어 디렉터리를 제거할 수 있게 합니다.
      export const shutdown = new AbortController();

      export async function handle(req: Request): Promise<Response> {
        // 여기서 실행되지 않을 작업의 전달은 절대 확인 응답하지 마세요; 503은 발신자가 재시도하게 합니다.
        if (shutdown.signal.aborted) {
          return Response.json({ status: "shutting down" }, { status: 503 });
        }
        const body = await req.text();
        let event;
        try {
          event = client.beta.webhooks.unwrap(body, { headers: Object.fromEntries(req.headers) });
        } catch {
          return new Response("signature verification failed", { status: 401 });
        }
        if (event.data.type !== "session.status_run_started") {
          return Response.json({ status: "ignored" });
        }

        for await (const work of client.beta.environments.work.poller({
          environmentId,
          environmentKey,
          blockMs: null,
          reclaimOlderThanMs: 2000,
          drain: true,
          autoStop: false,
          signal: shutdown.signal
        })) {
          await client.beta.environments.work.worker({ workdir: "/workspace" }).handleItem({
            workId: work.id,
            environmentId,
            sessionId: work.data.id,
            environmentKey,
            // 세션별 시크릿은 워커가 세션의 메모리 스토어를 마운트할 수 있게 해 줍니다.
            workSecret: work.secret ?? undefined,
            signal: shutdown.signal
          });
        }
        // 폴러와 handleItem은 abort 시 조용히 반환하므로, 중단된 드레인은 여기에 도달합니다.
        if (shutdown.signal.aborted) {
          return Response.json({ status: "shutting down" }, { status: 503 });
        }
        return Response.json({ status: "ok" });
      }
      ```

      <CodeGroupItem language="C#">
        C# SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 작업 항목을 처리하려면 [배포 패턴 선택](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern)에 설명된 대로 자체 워커를 구현하세요.
      </CodeGroupItem>

      ```go Go
      package main

      import (
      	"context"
      	"encoding/json"
      	"errors"
      	"io"
      	"log/slog"
      	"net/http"
      	"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"
      	"github.com/anthropics/anthropic-sdk-go/v2/packages/param"
      )

      var (
      	environmentKey = os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
      	environmentID  = os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
      	client         = anthropic.NewClient(
      		option.WithAuthToken(environmentKey),
      		option.WithWebhookKey(os.Getenv("ANTHROPIC_WEBHOOK_SIGNING_KEY")),
      	)
      	worker = environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
      		Workdir: "/workspace",
      	})
      	// SIGINT 또는 SIGTERM 시 취소됩니다(main에서 설정). 따라서 진행 중인 작업 항목은
      	// 종료 전에 변경된 메모리 파일을 업로드하고 스토어 디렉터리를 제거할 수 있습니다.
      	shutdown context.Context
      )

      func handle(w http.ResponseWriter, r *http.Request) {
      	body, err := io.ReadAll(r.Body)
      	if err != nil {
      		http.Error(w, "bad request", http.StatusBadRequest)
      		return
      	}
      	event, err := client.Beta.Webhooks.Unwrap(body, r.Header)
      	if err != nil {
      		http.Error(w, "signature verification failed", http.StatusUnauthorized)
      		return
      	}
      	if event.Data.Type != "session.status_run_started" {
      		json.NewEncoder(w).Encode(map[string]string{"status": "ignored"})
      		return
      	}

      	// Go SDK는 RunOne 편의 함수를 제공하지 않습니다. 대기 중인 항목을
      	// WorkPoller로 모두 가져와 각각 HandleItem으로 실행하세요.
      	// r.Context()에서 분리합니다. 세션이 웹훅 전달 타임아웃보다 오래 지속될 수 있기 때문입니다.
      	// 프로세스 전역 종료 컨텍스트는 SIGTERM 시에도 항목을 깔끔하게 종료합니다.
      	ctx := shutdown
      	poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{
      		EnvironmentID:      environmentID,
      		EnvironmentKey:     environmentKey,
      		BlockMs:            param.Null[int64](),
      		ReclaimOlderThanMs: param.NewOpt[int64](2000),
      		Drain:              true,
      		AutoStop:           param.NewOpt(false),
      	})
      	defer poller.Close()
      	for poller.Next() {
      		item := poller.Current()
      		if err := worker.HandleItem(ctx, environments.HandleItemOptions{
      			WorkID:         item.ID,
      			EnvironmentID:  item.EnvironmentID,
      			SessionID:      item.Data.ID,
      			EnvironmentKey: environmentKey,
      			// 세션별 시크릿이 있어야 워커가 세션의 메모리 스토어를 마운트할 수 있습니다.
      			WorkSecret: item.Secret,
      		}); err != nil {
      			slog.Error("handle work item", "work_id", item.ID, "err", err)
      			http.Error(w, "internal error", http.StatusInternalServerError)
      			return
      		}
      	}
      	if err := poller.Err(); err != nil {
      		slog.Error("poll work queue", "err", err)
      		http.Error(w, "internal error", http.StatusInternalServerError)
      		return
      	}
      	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
      }

      func main() {
      	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
      	defer stop()
      	shutdown = ctx

      	server := &http.Server{Addr: ":8080"}
      	http.HandleFunc("POST /webhook", handle)
      	go func() {
      		if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
      			slog.Error("http server", "err", err)
      			os.Exit(1)
      		}
      	}()
      	// 시그널을 받으면 전달 수신을 중단하고, 진행 중인 핸들러와
      	// 그에 따른 작업 항목의 메모리 정리가 완료된 후에만 반환합니다.
      	<-ctx.Done()
      	if err := server.Shutdown(context.Background()); err != nil {
      		slog.Error("http shutdown", "err", err)
      	}
      }
      ```

      <CodeGroupItem language="Java">
        Java SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 작업 항목을 처리하려면 [배포 패턴 선택](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern)에 설명된 대로 자체 워커를 구현하세요.
      </CodeGroupItem>

      <CodeGroupItem language="PHP">
        PHP SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 작업 항목을 처리하려면 [배포 패턴 선택](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern)에 설명된 대로 자체 워커를 구현하세요.
      </CodeGroupItem>

      <CodeGroupItem language="Ruby">
        Ruby SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 작업 항목을 처리하려면 [배포 패턴 선택](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern)에 설명된 대로 자체 워커를 구현하세요.
      </CodeGroupItem>
    </CodeGroup>

    Python, TypeScript 및 Go SDK에서 `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`)은 메모리 스토어를 마운트하기 위해 작업 항목의 시크릿이 필요합니다. `run()` (go: `Run()`)으로 폴링하는 워커는 이미 시크릿을 가지고 있습니다. 이 핸들러는 각 항목을 직접 가져오므로 `work_secret` (typescript: `workSecret`; go: `WorkSecret`) 인수로 시크릿을 전달합니다. [작업 항목의 시크릿 전달](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#forward-the-work-items-secret)을 참조하세요.
  </Step>
</Steps>

이 핸들러는 가져온 모든 항목을 하나의 프로세스에서 실행하며, 서로 다른 웹훅 전달에서 온 항목을 동시에 실행합니다. 이러한 세션들은 `/workspace` 및 `/mnt/memory`를 포함한 하나의 파일 시스템을 공유합니다. 세션들이 동일한 메모리 스토어를 연결하는 경우 [스토어를 공유하는 세션 격리하기](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory#isolate-sessions-that-share-a-store)를 참조하세요.

## 다음 단계

<CardGroup cols={2}>
  <Card title="세션당 하나의 샌드박스 실행" icon="cube" href="https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session">
    Kubernetes의 Helm 차트, 스폰 스크립트 또는 SDK 폴러로 샌드박스를 시작하세요.
  </Card>

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

  <Card title="보안 모델" icon="lock" href="https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-security">
    자체 호스팅 샌드박스 환경을 위한 공동 책임 모델입니다.
  </Card>
</CardGroup>

## 제공 여부

사전 구축된 자체 호스팅 워커은(는) 모든 모델에서 베타 상태입니다.

### API 지원

#### [Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)

* 제공 여부: 사용 가능

| 상태 | 클라우드 플랫폼 |
| ----- | ----- |
| 베타 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws) |

### 필수 베타 헤더

[베타 헤더 개요](https://platform.claude.com/docs/ko/api/beta-headers)

베타 헤더를 사용하면 실험적 기능과 새로운 모델 기능이 표준 API에 포함되기 전에 액세스할 수 있습니다.

* `managed-agents-2026-04-01`

### 데이터 처리

[데이터 처리 개요](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#feature-eligibility)

| 항목 | 제로 데이터 보존 | HIPAA |
| ----- | ----- | ----- |
| 상태 | 적격 아님 | 적격 아님 |
| 세부 정보 | 자체 호스팅 Managed Agents를 제외하고 ZDR 적격 대상이 아닙니다. 세션은 상태를 유지하는 리소스이며, 트랜스크립트는 삭제할 때까지 유지됩니다. [자세히 알아보기](https://platform.claude.com/docs/ko/managed-agents/self-hosted-data-and-access#how-long-data-is-kept) | HIPAA 적격 대상이 아닙니다. 모든 Managed Agents 하위 기능에 적용됩니다. |

적용 엔드포인트:

* `/v1/agents`
* `/v1/sessions`
* `/v1/environments`
