> ## Documentation Index > Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt > Use this file to discover all available pages before exploring further. # Claude Managed Agents와 함께 샌드박스 사용하기 > 자체 호스팅 샌드박스 워커를 Claude Managed Agents에 연결하고 CoreWeave에서 도구 실행을 확인하세요. [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)를 CoreWeave 샌드박스에서 실행 중인 워커에 연결하세요. Anthropic이 에이전트 루프와 대화를 관리하고, 워커는 도구를 실행한 뒤 그 결과를 Anthropic에 반환합니다. 이 인테그레이션은 자체 호스팅 환경을 사용하며, Claude Code CLI 및 Remote Control과는 별개입니다. Claude Managed Agents도 베타 단계입니다. 해당 API를 사용하려면 `managed-agents-2026-04-01` 베타 헤더가 필요합니다. 이 가이드에서 사용하는 Anthropic SDK는 이 헤더를 자동으로 추가합니다. [Anthropic 베타 액세스](https://platform.claude.com/docs/en/managed-agents/overview#beta-access)를 참조하세요.

사전 요구 사항

시작하기 전에 다음이 필요합니다. * `SANDBOX_USER` 액션이 있는 [CoreWeave API 액세스 토큰](/ko/products/sandboxes/placement#choose-and-get-credentials). * Anthropic 워크스페이스의 Claude Managed Agents 액세스 권한과 세션을 생성하는 클라이언트용 Console API 키. * `agent_toolset_20260401`로 설정된 기존 에이전트. Anthropic의 [Managed Agents 퀵스타트](https://platform.claude.com/docs/en/managed-agents/quickstart)에 따라 에이전트를 생성하고 해당 ID를 기록하세요. * SDK 예시의 경우 [`uv`](https://docs.astral.sh/uv/)가 포함된 Python 3.11 이상 또는 Node.js 22 이상. 이 가이드를 실행하는 터미널에서 CoreWeave API 액세스 토큰을 내보내세요. ```bash theme={"system"} export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]" ```

환경 만들기

[Claude Console](https://platform.claude.com/environments)에서 **Self-hosted** 환경을 만드세요. 환경을 열고 환경 키를 생성하세요. 환경 ID를 기록하고 키를 안전하게 보관하세요. Anthropic의 [환경 설정](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#create-a-self-hosted-environment)을 참고하세요. 환경 키는 이 환경에 대한 워커 인증에 사용됩니다. Console API 키는 클라이언트에서 세션을 생성하는 데 사용됩니다. 두 사용자 인증 정보를 별도로 관리하세요. 확인 작업에는 이 가이드에서 만든 워커만 있는 환경을 사용하세요. 이렇게 하면 다른 워커가 테스트 세션을 가져가는 것을 방지할 수 있습니다. 환경이 준비되면 `cws-agent` 또는 Sandboxes SDK를 선택하여 워커를 시작한 다음 확인 작업을 실행하세요.

cws-agent로 빠르게 시작하기

[`cws-agent` 설치 지침](https://github.com/coreweave/cws-agent#install)을 따르세요. 이 도구는 [파일 시스템 스냅샷](/ko/products/sandboxes/file-system-snapshots#start-a-sandbox-with-a-snapshot-mount)으로 작업 공간을 저장하고 복원할 수 있도록 스냅샷 볼륨을 설정합니다. `[ENVIRONMENT-KEY]`, `[ENVIRONMENT-ID]`, `[SANDBOX-NAME]`을 각각 환경 키, 환경 ID, 샌드박스에 사용할 `cws-agent` 세션 이름으로 바꾸세요. 세션 이름은 소문자, 숫자, 하이픈을 사용해 1\~40자로 지정하며, 소문자 또는 숫자로 시작해야 합니다. ```bash theme={"system"} export ANTHROPIC_ENVIRONMENT_KEY="[ENVIRONMENT-KEY]" cws-agent launch [SANDBOX-NAME] --claude-env [ENVIRONMENT-ID] ``` Launch는 `/workspace/claude/0`에서 워커 하나를 시작한 후 셸로 돌아옵니다. 이 도구는 환경 키를 샌드박스에 전달합니다. 워커의 터미널을 보려면 다음을 실행하세요: ```bash theme={"system"} cws-agent connect [SANDBOX-NAME] --cmd 'tmux attach -t claude-0' ``` **Ctrl-b**를 누른 다음 **d**를 눌러 세션에서 분리하세요. [작업 실행 및 확인](#run-and-verify-a-task)으로 이동하세요. 작업은 Managed Agents API를 통해 전송하세요. `cws-agent run` 명령은 Managed Agents 대화를 처리하지 않습니다.

Sandboxes SDK로 설정하기

이 대안은 Anthropic의 `ant` 워커를 샌드박스의 메인 프로세스로 시작합니다. `cws-agent`가 필요하지 않으며 스냅샷을 설정하지 않습니다. Python 코드 스니펫은 이 가이드에서 생성한 가상 환경에서 실행하세요. TypeScript 코드 스니펫은 클라이언트를 설치한 프로젝트에 `.mts` 파일로 저장한 다음 `npx tsx [FILENAME].mts`로 실행하세요.

사용자 인증 정보 설정 및 클라이언트 설치

스크립트를 실행할 터미널에서 Console의 환경 키와 ID를 내보내세요. ```bash theme={"system"} export ANTHROPIC_ENVIRONMENT_KEY="[ENVIRONMENT-KEY]" export ANTHROPIC_ENVIRONMENT_ID="[ENVIRONMENT-ID]" ``` Python 3.11 이상과 `uv`를 사용하세요: ```bash theme={"system"} uv venv --python 3.11 source .venv/bin/activate uv pip install 'cwsandbox>=1.14.2' ``` Node.js 22 이상을 사용하세요. 프로젝트에 클라이언트와 TypeScript 러너를 설치하세요: ```bash theme={"system"} npm install @coreweave/cwsandbox@0.5.0-beta.0 tsx ```

워커 시작하기

사용하는 언어에 맞는 스크립트를 표시된 파일 이름으로 저장하세요. 이 스크립트는 Bash가 포함된 Linux 이미지에 `ant` CLI를 설치하고, 워커 하나를 시작한 다음 샌드박스 ID를 출력합니다. 클라이언트는 로컬 환경에서 `ANTHROPIC_ENVIRONMENT_KEY`를 읽고, 그 값을 샌드박스 요청에 전달하여 워커의 환경 변수를 설정합니다. ```python title="start_claude_worker.py" theme={"system"} import os from cwsandbox import Sandbox worker = """ set -o pipefail case "$(uname -m)" in x86_64) arch=amd64 ;; aarch64) arch=arm64 ;; *) echo "Unsupported architecture" >&2; exit 1 ;; esac version=1.33.0 curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${version}/ant_${version}_linux_${arch}.tar.gz" \ | tar -xz -C /usr/local/bin ant mkdir -p /workspace exec ant beta:worker poll --workdir /workspace """ sandbox = Sandbox.run( "bash", "-ec", worker, container_image="python:3.12-bookworm", environment_variables={ "ANTHROPIC_ENVIRONMENT_KEY": os.environ["ANTHROPIC_ENVIRONMENT_KEY"], "ANTHROPIC_ENVIRONMENT_ID": os.environ["ANTHROPIC_ENVIRONMENT_ID"], }, resources={"cpu": "2", "memory": "4Gi"}, max_lifetime_seconds=8 * 3600, tags=["claude-managed-agents-worker"], ) try: sandbox.wait() except BaseException: sandbox.stop().result() raise print(f"Worker sandbox ID: {sandbox.sandbox_id}") ``` ```typescript title="start_claude_worker.mts" theme={"system"} import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node"; const token = process.env.ANTHROPIC_ENVIRONMENT_KEY; if (!token) throw new Error("Set ANTHROPIC_ENVIRONMENT_KEY."); const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID; if (!environmentId) throw new Error("Set ANTHROPIC_ENVIRONMENT_ID."); const worker = ` set -o pipefail case "$(uname -m)" in x86_64) arch=amd64 ;; aarch64) arch=arm64 ;; *) echo "Unsupported architecture" >&2; exit 1 ;; esac version=1.33.0 curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v\${version}/ant_\${version}_linux_\${arch}.tar.gz" \\ | tar -xz -C /usr/local/bin ant mkdir -p /workspace exec ant beta:worker poll --workdir /workspace `; const client = createSandboxClientFromEnv(); const sandbox = await client.run(["bash", "-ec", worker], { containerImage: "python:3.12-bookworm", environmentVariables: { ANTHROPIC_ENVIRONMENT_KEY: token, ANTHROPIC_ENVIRONMENT_ID: environmentId, }, resources: { cpu: "2", memory: "4Gi" }, maxLifetimeSeconds: 8 * 3600, waitUntilRunning: false, tags: ["claude-managed-agents-worker"], }); try { await sandbox.wait(); } catch (error) { await sandbox.stop(); throw error; } console.log(`Worker sandbox ID: ${sandbox.sandboxId}`); ``` 스크립트를 실행하세요: ```bash theme={"system"} python start_claude_worker.py ``` ```bash theme={"system"} npx tsx start_claude_worker.mts ``` 스크립트는 시작이 완료될 때까지 기다립니다. Python에서는 메인 프로세스가 이미 완료된 경우에도 `wait()`가 반환될 수 있습니다. 샌드박스 ID가 출력되었다고 해서 워커가 인증되었거나 폴링 중이라는 의미는 아닙니다. 작업을 시작하기 전에 워커의 상태와 최근 로그를 확인하세요. `[SANDBOX-ID]`를 출력된 ID로 바꾸세요: ```python theme={"system"} from cwsandbox import Sandbox sandbox = Sandbox.from_id("[SANDBOX-ID]").result() print("Sandbox status:", sandbox.get_status()) for container in sandbox.container_statuses: print(container.name, container.state, container.exit_code, container.restart_count) for line in sandbox.stream_logs(tail_lines=100): print(line, end="") ``` ```typescript theme={"system"} import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node"; const client = createSandboxClientFromEnv(); const sandbox = await client.fromId("[SANDBOX-ID]"); console.log("Sandbox status:", sandbox.status, "Exit code:", sandbox.exitCode); for (const line of await sandbox.logs.read({ tailLines: 100 })) { process.stdout.write(line); } ``` Python 클라이언트는 컨테이너별 상태, 종료 코드, 재시작 횟수도 보고합니다. TypeScript 클라이언트는 아직 이러한 세부 정보를 제공하지 않습니다. 최신 로그를 가져오려면 이 확인 작업을 다시 실행하세요. 이 워커는 아웃바운드 HTTPS를 통해 폴링합니다. 인바운드 서비스는 필요하지 않습니다. 각 세션은 동일한 샌드박스 파일 시스템을 사용하므로, 이 예제는 세션마다 새 샌드박스를 제공하지 않습니다. 이러한 아키텍처는 Anthropic의 [자체 호스팅 샌드박스 인테그레이션 가이드](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes)를 참조하세요.

선택: 시크릿 저장소 사용

환경 키 값 대신 [Forge 시크릿 참조](/ko/products/sandboxes/secrets)를 전달할 수 있습니다. 이 옵션을 사용하려면 Forge 인증과 서버리스 배치가 필요합니다. 환경 키를 담당 Forge 팀의 Secret Manager에 저장한 다음, 해당 팀의 사용자 인증 정보를 내보내세요. ```bash theme={"system"} export FORGE_API_KEY="[FORGE-API-KEY]" export FORGE_TEAM="[FORGE-TEAM]" ``` 이 사용자 인증 정보로 SDK를 명시적으로 설정하세요. `FORGE_API_KEY`와 `FORGE_TEAM`은 예시로 든 환경 변수이므로 SDK가 자동으로 감지하지 않습니다. 샌드박스를 생성하기 전에 `AuthHeaders`를 임포트하고 `auth`를 정의하세요. ```python theme={"system"} import os from cwsandbox import AuthHeaders auth = AuthHeaders( headers={ "x-wandb-api-key": os.environ["FORGE_API_KEY"], "x-entity-id": os.environ["FORGE_TEAM"], }, strategy="wandb_api_key", ) ``` `Sandbox.run()`에 `auth=auth`를 전달하세요. 이후의 Python 예시에서도 이 설정을 포함하고, 모든 `Sandbox.from_id()` 호출에도 `auth=auth`를 전달하세요. 클라이언트 임포트 및 초기화 코드를 다음으로 바꾸세요. 이후의 TypeScript 예시에서도 이 클라이언트 설정을 사용하세요. ```typescript theme={"system"} import { createSandboxClient } from "@coreweave/cwsandbox/wandb"; const client = createSandboxClient({ apiKey: process.env.FORGE_API_KEY, entity: process.env.FORGE_TEAM, }); ``` `[SECRET-NAME]`을 팀 시크릿의 이름으로 바꾸세요. `cwsandbox`에서 `Secret`을 임포트하고, `environment_variables`에서 `ANTHROPIC_ENVIRONMENT_KEY`를 제거한 다음, `Sandbox.run()`에 `secrets=[Secret(store="wandb", name="[SECRET-NAME]", env_var="ANTHROPIC_ENVIRONMENT_KEY")]`를 추가하세요. `const token` 선언과 `if (!token)` 검사를 제거하세요. `environmentVariables`에서 `ANTHROPIC_ENVIRONMENT_KEY`를 제거하고, `client.run()`에 전달하는 options에 `secrets: [{ store: "wandb", name: "[SECRET-NAME]", envVar: "ANTHROPIC_ENVIRONMENT_KEY" }]`를 추가하세요. 플랫폼이 참조를 해석하여 워커의 환경 변수를 설정합니다.

작업 실행 및 확인

두 설정 방식 모두 사용자의 컴퓨터에서 세션 클라이언트를 실행하세요. 사용하는 언어에 맞는 Anthropic SDK를 설치하세요: ```bash theme={"system"} uv venv --python 3.11 .claude-client source .claude-client/bin/activate uv pip install 'anthropic>=1.6.0' ``` ```bash theme={"system"} npm install @anthropic-ai/sdk@0.126.0 tsx ``` `[ANTHROPIC-API-KEY]`를 Console API 키로, `[AGENT-ID]`를 기존 에이전트 ID로, `[ENVIRONMENT-ID]`를 워커에 연결된 환경으로 바꾸세요: ```bash theme={"system"} export ANTHROPIC_API_KEY="[ANTHROPIC-API-KEY]" export ANTHROPIC_AGENT_ID="[AGENT-ID]" export ANTHROPIC_ENVIRONMENT_ID="[ENVIRONMENT-ID]" ``` 사용하는 언어의 확인 스크립트를 표시된 파일 이름으로 저장하세요. 이 스크립트는 에이전트에게 작업 디렉터리에 시크릿이 아닌 고유한 값을 기록하도록 요청합니다. 자체 호스팅 도구 실행은 워커가 허용된 Call을 처리하는 동안 일시적인 유휴 이벤트를 생성합니다. 스크립트는 이러한 이벤트가 발생하는 동안 대기하다가 대화 턴이 끝나거나 다른 액션이 필요해지면 중지됩니다. 파일을 가져오기 전에 출력된 중지 사유를 확인하세요. ```python title="verify_claude_worker.py" theme={"system"} import os import uuid from anthropic import Anthropic client = Anthropic() proof = uuid.uuid4().hex session = client.beta.sessions.create( agent=os.environ["ANTHROPIC_AGENT_ID"], environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"], title="CoreWeave worker verification", ) print(f"Session ID: {session.id}") print(f"Expected file contents: {proof}") events_by_id = {} with client.beta.sessions.events.stream(session.id) as events: client.beta.sessions.events.send( session.id, events=[{ "type": "user.message", "content": [{ "type": "text", "text": f"Write exactly {proof} to managed-agent-proof.txt in your working directory and read it back.", }], }], ) for event in events: print(event.model_dump_json()) events_by_id[event.id] = event if event.type == "session.status_idle": reason = event.stop_reason if reason and reason.type == "requires_action": pending = [events_by_id.get(event_id) for event_id in reason.event_ids] if pending and all( getattr(tool, "evaluated_permission", None) == "allow" for tool in pending ): continue break ``` ```typescript title="verify_claude_worker.mts" theme={"system"} import { randomUUID } from "node:crypto"; import Anthropic from "@anthropic-ai/sdk"; const agent = process.env.ANTHROPIC_AGENT_ID; const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID; if (!agent || !environmentId) { throw new Error("Set ANTHROPIC_AGENT_ID and ANTHROPIC_ENVIRONMENT_ID."); } const client = new Anthropic(); const proof = randomUUID().replaceAll("-", ""); const session = await client.beta.sessions.create({ agent, environment_id: environmentId, title: "CoreWeave worker verification", }); console.log(`Session ID: ${session.id}`); console.log(`Expected file contents: ${proof}`); const allowedEvents = new Map(); await client.beta.sessions.events.send(session.id, { events: [{ type: "user.message", content: [{ type: "text", text: `Write exactly ${proof} to managed-agent-proof.txt in your working directory and read it back.`, }], }], }); const events = await client.beta.sessions.events.stream(session.id); try { for await (const event of events) { console.log(JSON.stringify(event)); if ("id" in event) { allowedEvents.set(event.id, "evaluated_permission" in event && event.evaluated_permission === "allow"); } if (event.type === "session.status_idle") { const reason = event.stop_reason; if (reason?.type === "requires_action" && reason.event_ids.length > 0 && reason.event_ids.every((id) => allowedEvents.get(id) === true)) { continue; } break; } } } finally { events.controller.abort(); } ``` 실행하고 이벤트를 확인하세요: ```bash theme={"system"} python verify_claude_worker.py ``` ```bash theme={"system"} npx tsx verify_claude_worker.mts ``` 스크립트가 `requires_action` 상태로 중지되면 참조된 도구 이벤트를 확인하세요. `evaluated_permission: "ask"`가 설정된 Call은 Anthropic의 [도구 확인 워크플로](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#tool-confirmation)가 필요합니다. 허용된 Call은 워커가 처리합니다. Call이 멈춘 경우 워커의 로그를 확인하세요. 새 세션을 만들지 말고 세션 ID를 보관해 두었다가 해당 세션을 이어서 사용하세요. 작업이 완료되면 사용 중인 설정에 맞는 명령어로 샌드박스에서 파일을 읽으세요. `[SANDBOX-NAME]` 또는 `[SANDBOX-ID]`를 작업 공간 이름 또는 출력된 샌드박스 ID로 바꾸세요: ```bash theme={"system"} cws-agent exec [SANDBOX-NAME] 'cat /workspace/claude/0/managed-agent-proof.txt' ``` ```python theme={"system"} from cwsandbox import Sandbox sandbox = Sandbox.from_id("[SANDBOX-ID]").result() result = sandbox.exec(["cat", "/workspace/managed-agent-proof.txt"], check=True).result() print(result.stdout, end="") ``` ```typescript theme={"system"} import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node"; const client = createSandboxClientFromEnv(); const sandbox = await client.fromId("[SANDBOX-ID]"); const result = await sandbox.commands.run(["cat", "/workspace/managed-agent-proof.txt"], { check: true }); process.stdout.write(result.stdout); ``` Python의 경우 필요하면 `cwsandbox`를 설치한 가상 환경을 다시 활성화하세요. TypeScript의 경우 SDK 코드 스니펫을 `.mts` 파일로 저장한 후 `npx tsx`로 실행하세요. 파일 내용은 클라이언트가 출력한 값과 일치해야 합니다. 이를 통해 에이전트의 도구 실행이 특정 CoreWeave 샌드박스와 연결되었음을 확인할 수 있습니다.

결과 보존 및 중지

진행 중인 작업이 완료될 때까지 기다린 후 필요한 결과를 샌드박스 밖으로 복사하세요. 그런 다음 설정에 맞는 명령으로 샌드박스를 중지하세요: ```bash theme={"system"} cws-agent down [SANDBOX-NAME] ``` `down`은 중지하기 전에 작업 공간의 스냅샷을 생성합니다. 캡처에 실패하면 `cws-agent status [SANDBOX-NAME]`을 확인하고 실패 원인을 해결한 후 다시 시도하세요. 저장하지 않은 변경 사항을 삭제해도 된다면 `down --no-snapshot`을 사용하세요. ```python theme={"system"} from cwsandbox import Sandbox sandbox = Sandbox.from_id("[SANDBOX-ID]").result() sandbox.stop().result() ``` ```typescript theme={"system"} import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node"; const client = createSandboxClientFromEnv(); const sandbox = await client.fromId("[SANDBOX-ID]"); await sandbox.stop(); ``` 이 예제에서는 영구 저장소를 설정하지 않습니다. 중지하기 전에 파일을 외부로 복사하세요. 샌드박스의 최대 실행 시간이 만료되면 진행 중인 작업이 종료될 수 있습니다. Managed Agents 세션을 종료해도 이 상시 실행 워커는 중지되지 않습니다. 샌드박스를 중지하거나 복원해도 Anthropic의 대화 이력은 삭제되거나 복원되지 않습니다.

문제 해결

다음 항목을 확인하여 일반적인 문제를 해결하세요: * 세션이 워커를 기다리는 경우 환경 ID, 워커 로그, 다른 작업이 이미 워커를 점유하고 있는지 확인하세요. * 워커가 인증할 수 없는 경우 환경 키를 확인하세요. 세션 클라이언트에서 사용하는 Console API 키는 별도의 자격 증명입니다. * 도구가 없는 경우 의존성을 포함한 이미지를 구축하세요. 예시에서는 Python 이미지를 사용하며 프로젝트별 도구 모음은 설치하지 않습니다. 실행은 CoreWeave에서 이루어지지만 도구의 입력과 출력은 Anthropic으로 전송됩니다. Managed Agents에는 Zero Data Retention 또는 HIPAA 비즈니스 제휴 계약이 적용되지 않습니다. [Anthropic의 데이터 보관 적용 자격](https://platform.claude.com/docs/en/managed-agents/overview#beta-access)을 참고하세요. 데이터 처리 및 워커 권한에 대해서는 [자체 호스팅 환경 보안 모델](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-security)을 검토하세요.