> ## 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. # Sandboxes에서 에이전트 실행하기 > CoreWeave에서 장시간 세션, 병렬 작업, 도구를 활용해 대화형 에이전트와 자율 에이전트를 실행하세요. 에이전트가 CoreWeave에서 코드를 편집하고, 테스트를 실행하고, 결과를 저장할 수 있는 작업 공간을 제공하세요. 이 개요는 인테그레이션을 선택하고 장시간 세션, 서브에이전트, 도구 실행을 위한 환경을 설정하는 데 도움이 됩니다. 스크린샷, 마우스 입력, 키보드 입력으로 그래픽 데스크톱을 조작하는 에이전트는 [샌드박스에서 컴퓨터 사용 에이전트 실행하기](/ko/products/sandboxes/tutorials/computer-use)를 참조하세요. 벤치마크 기반 에이전트 평가는 [CoreWeave 샌드박스에서 평가 실행하기](/ko/products/sandboxes/evals)를 참조하세요. [Claude Code 클라우드 세션](/ko/products/sandboxes/agents/claude-code-cloud) 예시에서는 claude.ai/code 에서 세션을 시작할 때마다 샌드박스에 호스팅된 오케스트레이터가 워커 샌드박스를 온디맨드로 프로비저닝합니다. 워커는 릴리스되면 중지됩니다.

대화형 coding agent와 autonomous agent

대화형 coding agent를 사용하면 에이전트와 함께 작업합니다: 터미널, 브라우저 또는 모바일 앱을 통해 질문을 하고, 편집 내용을 검토하며, 액션을 승인합니다. 예를 들어, Claude Code를 사용하여 실패한 테스트를 조사하면서 변경 사항을 안내할 수 있습니다. autonomous agent를 사용하면 작업을 위임하고 나중에 결과를 수집합니다. 예를 들어, 저장소 마이그레이션을 할당하고, 에이전트가 테스트를 실행하고 변경 사항을 수정하게 한 다음 결과를 검토합니다. 작업을 시작하기 전에 권한, 자격 증명 및 중지 조건을 설정하세요. 필요할 때 입력을 위해 일시 중지할 수도 있습니다. 이것들은 작업 방식일 뿐이며, 별도의 샌드박스 유형이 아닙니다. coding harness는 둘 다 지원할 수 있습니다. harness는 에이전트 루프, 모델 컨텍스트, 도구 선택 및 위임을 관리합니다. CoreWeave는 도구가 실행되는 컴퓨트와 파일 시스템을 제공합니다. 더 긴 샌드박스 lifetime은 에이전트에게 더 많은 실행 시간을 제공하지만, 대화 압축 및 작업 복구는 harness에 따라 달라집니다.

인테그레이션 선택

다음 인테그레이션은 CoreWeave 샌드박스에서 명령어를 실행합니다. 에이전트 루프가 실행되는 위치와 사용하는 인터페이스는 인테그레이션마다 다릅니다. | 가이드 | 에이전트 루프 실행 위치 | 상호작용 방식 | 용도 | | - | - | - | - | | [Claude Code](/ko/products/sandboxes/agents/claude-code) | 샌드박스 | 연결된 터미널, Claude 모바일 또는 Desktop 앱, 또는 claude.ai/code | 터미널에서 저장소 작업을 하거나 다른 기기에서 Remote Control을 사용합니다. | | [Cursor](/ko/products/sandboxes/agents/cursor) | 샌드박스 | 연결된 터미널 또는 스크립트 | 저장소를 대화형으로 편집하거나 무인 코딩 작업을 실행합니다. | | [OpenCode CLI](/ko/products/sandboxes/agents/opencode) | 샌드박스 | 연결된 터미널 또는 명령어 | Serverless Inference 또는 다른 모델 공급자를 사용해 코딩 작업을 실행합니다. | | [Muse Code](/ko/products/sandboxes/agents/muse-code) | 샌드박스 | Sandboxes SDK | 저장소에서 CLI 작업을 실행하고 결과를 조회합니다. | | [Pi](/ko/products/sandboxes/agents/pi) | 샌드박스 | 연결된 터미널 | Serverless Inference를 포함해 원하는 모델 공급자를 사용해 저장소 작업을 합니다. | | [Claude Managed Agents](/ko/products/sandboxes/agents/claude-managed-agents) | Anthropic의 관리형 서비스 | Managed Agents API | 자체 호스팅 워커를 관리형 에이전트 세션에 연결합니다. | | [Codex](/ko/products/sandboxes/agents/codex) | 샌드박스 | 샌드박스 내 Codex CLI, Codex App Server에 연결된 로컬 CLI, 또는 데스크톱 앱 및 페어링된 모바일 앱 | Codex로 원격 저장소 작업을 합니다. | | [Devin Outposts](/ko/products/sandboxes/agents/devin-outposts) | Devin Cloud | Devin Cloud | 아웃포스트 워커를 통해 샌드박스에서 Devin의 명령어를 실행합니다. | | [OpenAI Agents API](/ko/products/sandboxes/agents/openai-agents-api) | OpenAI의 관리형 서비스 | Agents API를 사용하는 사용자 애플리케이션 | 자체 호스팅 샌드박스에서 에이전트 도구와 서브에이전트 분석을 실행합니다. | Claude Code 및 Pi 예시는 사용자가 관리하는 작업 공간에서 대화형 에이전트를 시작합니다. Cursor 예시는 대화형 작업과 무인 작업을 모두 지원합니다. Muse Code 예시는 대화형 터미널 없이 작업을 실행합니다. Managed Agents 및 Devin Outposts 예시는 대기열에 있는 여러 세션에 걸쳐 샌드박스를 재사용하는 워커를 시작합니다. 공급자 세션 하나를 종료해도 해당 워커 샌드박스는 중지되지 않습니다. 모델 추론은 여전히 에이전트에 설정된 공급자에서 수행됩니다. 도구를 샌드박스에서 실행하더라도 에이전트는 프롬프트, 파일 내용, 도구 출력을 해당 공급자에 계속 전송할 수 있습니다. 작업 공간을 연결하기 전에 공급자의 데이터 처리 요구 사항을 검토하세요.

나만의 인테그레이션 구축

[Sandboxes SDK](/ko/products/sandboxes/client)를 사용하여 환경을 생성하고, 도구 Call을 실행하며, 결과를 수집하고, 자체 하니스에서 컴퓨팅을 중지하세요. [command 실행](/ko/products/sandboxes/client/guides/execution), [file operations](/ko/products/sandboxes/client/guides/file-operations), [cleanup patterns](/ko/products/sandboxes/client/guides/cleanup-patterns)부터 시작하세요.

cws-agent 시작하기

[`cws-agent`](https://github.com/coreweave/cws-agent)는 샌드박스 생성, 에이전트 설치, 작업 공간 관리를 자동화합니다. 대부분의 인테그레이션 가이드에는 이 도구를 사용하는 빠른 시작 방법이 포함되어 있습니다. 일부 가이드에서는 Sandboxes SDK로 샌드박스를 직접 설정합니다. 두 방법을 모두 다루는 가이드에서는 원하는 방법을 골라 따로 진행할 수 있습니다. [설치 안내](https://github.com/coreweave/cws-agent#install)에 따라 설치한 다음 인테그레이션 가이드를 선택하세요. 일반적인 `cws-agent` 예시에서는 CoreWeave API 액세스 토큰을 사용해 샌드박스에 액세스합니다. 에이전트 공급자 인증은 별도로 진행하세요. ```bash theme={"system"} export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]" ``` 토큰에는 **Sandbox User** 역할이 필요합니다. [사용자 인증 정보 선택 및 조회](/ko/products/sandboxes/placement#choose-and-get-credentials)를 참조하세요. SDK 예시는 지원되는 경우 Forge 사용자 인증 정보를 명시적으로 전달하므로, 각 가이드의 사용자 인증 정보 설정 방법을 따르세요. 레거시 환경 변수가 필요한 통합 가이드에서는 Forge API 키를 해당 변수에 어떻게 매핑해야 하는지 설명합니다. 설정 임포트, 병렬 세션, 작업 공간 저장 및 복원에 대해서는 [`cws-agent` 문서](https://github.com/coreweave/cws-agent#more)를 참조하세요. 하니스를 직접 통합할 때는 `cws-agent`가 필요하지 않습니다.

샌드박스가 실행될 위치 선택

[Serverless 배치](/ko/products/sandboxes/get-started#run-a-sandbox-on-serverless-capacity)는 CoreWeave가 운영하는 용량을 사용합니다. 이 가이드의 시작점입니다. [CoreWeave Kubernetes Service (CKS) 배치](/ko/products/sandboxes/get-started-cks)를 사용하세요. 자체 클러스터 배치와 샌드박스 정책이 필요할 때 사용합니다. 관리자가 러너를 배포하고 네트워크 및 리소스 제약을 구성합니다. 에이전트는 공급자와 사용하는 패키지 또는 소스 호스트에 대한 아웃바운드 액세스가 필요합니다.

더 긴 세션 실행

수명은 시작 시간을 포함한 실제 경과 시간 제한이며, 생성 후에는 연장할 수 없습니다. 에이전트가 작업을 완료하거나 중단 후 복구하는 것을 보장하지는 않습니다. Serverless Sandboxes는 `max_lifetime_seconds`를 생략하면 기본 수명이 10분으로 설정됩니다. CKS 러너는 다른 정책 기본값을 제공할 수 있습니다. 설정과 작업에 필요한 시간을 고려하여 생성 시 수명을 명시적으로 설정하세요.

serverless 샌드박스 수명 설정

[SDK 설치 및 인증](/ko/products/sandboxes/get-started#run-your-first-sandbox)을 완료한 후, 24시간 수명의 샌드박스를 위한 생성 요청을 사용하세요. 예시에서는 `FORGE_API_KEY`를 읽어 client에 명시적으로 전달합니다: ```python theme={"system"} import os from cwsandbox import AuthHeaders, Sandbox forge_auth = AuthHeaders( headers={"x-wandb-api-key": os.environ["FORGE_API_KEY"]}, strategy="wandb_api_key", ) sandbox = Sandbox.run( auth=forge_auth, placement_mode="serverless", container_image="python:3.12-slim", resources={"cpu": "4", "memory": "8Gi"}, max_lifetime_seconds=24 * 60 * 60, ) print(f"Sandbox ID: {sandbox.sandbox_id}") ``` ```typescript theme={"system"} import { createSandboxClient } from "@coreweave/cwsandbox/wandb"; const client = createSandboxClient({ apiKey: process.env.FORGE_API_KEY, }); const sandbox = await client.create({ containerImage: "python:3.12-slim", resources: { cpu: "4", memory: "8Gi" }, maxLifetimeSeconds: 24 * 60 * 60, waitUntilRunning: false, }); console.log(`Sandbox ID: ${sandbox.sandboxId}`); ``` 인쇄된 ID를 저장하여 [SDK로 재연결](/ko/products/sandboxes/client/guides/sandbox-lifecycle#reconnection)하세요. ID는 생성이 수락되었음을 확인할 뿐, 시작이 완료되었음을 의미하지 않습니다. readiness를 기다리고, 설치한 후 에이전트를 시작하거나, 도구가 이미 설치된 이미지를 제공하려면 인테그레이션 guide를 따르세요. 두 standalone 생성 호출 모두 스크립트가 종료된 후에도 샌드박스를 실행 상태로 둡니다. TypeScript의 `withSandbox()`는 콜백이 완료되면 중지합니다. `with Sandbox.run(...)` 블록은 블록이 종료되면 중지합니다. SDK `Session`을 통해 생성된 샌드박스는 해당 세션이 닫힐 때(프로세스 종료 정리 중 포함) 중지됩니다. `cws-agent`가 설치 및 인증된 상태에서 Claude Code를 실행할 때 동일한 수명을 설정하세요. `[SANDBOX-NAME]`을 작업 공간용 `cws-agent` 세션 이름으로 교체하세요. 소문자, 숫자 또는 하이픈 1\~40자를 사용하며, 문자 또는 숫자로 시작해야 합니다: ```bash theme={"system"} cws-agent launch [SANDBOX-NAME] --lifetime 24h --cpu 4 --memory 8Gi --permission-mode native ``` 터미널을 닫을 때 대화형 에이전트가 계속 실행되도록 하려면, 터미널 멀티플렉서 내부에서 실행하세요. 분리 및 재연결 지침은 [`tmux` 가이드](https://github.com/tmux/tmux/wiki/Getting-Started)를 참조하세요. 분리된 세션은 여전히 승인이나 로그인을 기다릴 수 있습니다.

CKS 배치 및 정책 설정

CKS 배치에는 `SANDBOX_USER` IAM 액션이 있는 CoreWeave API 액세스 토큰이 필요합니다. [자체 컴퓨팅 사용](/ko/products/sandboxes/get-started-cks)을 따르세요. Python에서는 `auth=AuthStrategy.COREWEAVE_API_KEY`를 설정하고, `max_lifetime_seconds`를 유지한 채 `placement_mode="cks"`와 `runner_ids=["[RUNNER-ID]"]`를 설정하세요. `[RUNNER-ID]`를 클러스터의 러너 ID로 교체하세요. TypeScript에서는 `@coreweave/cwsandbox/node` entry point를 사용하고, `maxLifetimeSeconds`를 유지한 채 CKS를 선택하려면 `runnerIds: ["[RUNNER-ID]"]`를 설정하세요. 러너에는 설정된 정책이 있어야 합니다. 리소스 상한은 생성 요청을 수용할 수 있어야 합니다. 기존 워크로드에 필요한 다른 제약 조건과 더 높은 상한을 유지하세요. 정책 쓰기는 전체 문서를 대체하며, 변경 사항은 새로 생성된 샌드박스에 적용됩니다. 수명을 생략한 요청의 기본값을 24시간으로 설정하려면, Admin이 [CoreWeave Intelligent CLI](/ko/products/sandboxes/profiles/configure#update-a-policy)를 사용하여 기존 정책을 편집하게 하세요: ```bash theme={"system"} cwic sandbox runner policy edit [RUNNER-ID] ``` 이 필드들을 기존 `constraints` 객체에 병합하세요. 이는 완전한 대체 문서가 아니라 정책 조각입니다: ```json theme={"system"} { "constraints": { "lifecycle": { "defaultLifetimeSeconds": 86400 }, "resources": { "maxCpu": "4", "maxMemory": "8Gi" } } } ``` 명시적 요청 수명은 `defaultLifetimeSeconds`보다 우선합니다. 플랫폼 최대값은 30일입니다. 정책에는 이를 높일 `maxLifetimeSeconds` 필드가 없습니다. 공급자 연결을 허용하려면 [network egress](/ko/products/sandboxes/profiles/configure#constrain-network-access)도 설정하세요: `allowedEgress`는 요청된 대상을 허용하고, `defaultEgress`는 요청이 이그레스 규칙을 생략할 때 액세스를 제공합니다. 허용만으로는 액세스 권한이 부여되지 않습니다.

실행 시간과 대화 상태를 분리하세요

도구 명령의 `timeout_seconds`는 샌드박스 lifetime과 별개입니다. 긴 빌드와 테스트에 적절한 명령 timeout을 부여하세요. 무인 작업의 경우, 하니스가 지원하는 백그라운드 실행 및 복구 기능을 사용하고 중간 결과를 저장하세요. [명령 timeout](/ko/products/sandboxes/client/guides/execution#set-a-timeout) 및 [샌드박스 라이프사이클](/ko/products/sandboxes/client/guides/sandbox-lifecycle)을 참조하세요.

서브에이전트에 작업 위임

하니스에서 서브에이전트를 설정하세요. 샌드박스 생성 플래그가 없으면 서브에이전트가 활성화됩니다. 예를 들어, Claude Code에는 내장 서브에이전트가 포함되어 있습니다. 대화형 세션에서 독립적인 조사를 분할하도록 요청하세요: ```text theme={"system"} Use separate subagents to inspect the API and its tests in parallel. Have each report relevant files and findings without editing anything. Combine their findings into an implementation plan. ``` 재사용 가능한 전문가를 정의하려면, Claude Code를 시작하기 전에 샌드박스의 프로젝트에 이 파일을 생성하세요: ```markdown title=".claude/agents/test-reader.md" theme={"system"} --- name: test-reader description: Inspect tests and report coverage gaps without editing files. tools: Read, Grep, Glob --- Find tests relevant to the requested change. Summarize coverage gaps and cite the test files. Do not modify files. ``` Claude에게 특정 작업에 `test-reader`를 사용하도록 요청하세요. 위임은 기본적으로 사용 가능합니다. 상위 에이전트의 `Agent` 도구에 대한 `permissions.deny` 규칙은 위임을 차단합니다. 도구 권한 및 기타 옵션에 대해서는 [Claude Code 서브에이전트 구성](https://code.claude.com/docs/en/sub-agents)을 참조하세요. 하나의 샌드박스를 사용하는 서브에이전트는 해당 샌드박스의 컴퓨트와 파일 시스템을 공유합니다. 동시 도구를 위해 CPU와 메모리를 적절히 크기 조정하고, 동일 파일에 대한 동시 편집을 피하세요. 작업자가 독립적인 인증 정보 또는 격리가 필요할 때는 별도의 샌드박스를 사용하세요. 별도의 코딩 작업의 경우, [`cws-agent` 병렬 세션](https://github.com/coreweave/cws-agent/blob/main/docs/sessions.md)은 하나의 샌드박스 내에서 별도의 Git 작업 트리를 제공합니다. 이들은 독립적인 세션이며, 하니스 관리 서브에이전트나 별도의 보안 경계가 아닙니다.

도구를 효율적으로 사용하기

에이전트가 작업에 시간을 쓸 수 있도록 환경을 준비하세요: * **반복적으로 사용하는 의존성을 이미지에 설치하세요.** 생성 시 준비된 `container_image`를 전달하면 세션마다 동일한 테스트 도구와 런타임을 설치하지 않아도 됩니다. [샌드박스 설정](/ko/products/sandboxes/client/guides/sandbox-configuration)을 참조하세요. * **작업에 필요한 도구를 선택하세요.** 하니스에서 스킬과 Model Context Protocol(MCP) 서버를 설정하세요. `cws-agent`로 관리하는 CLI 세션에서는 로컬 설정을 미리 보고 선택한 항목을 해당 샌드박스로 임포트하세요: ```bash theme={"system"} cws-agent config preview [SANDBOX-NAME] --verbose cws-agent config sync [SANDBOX-NAME] ``` Claude Managed Agents 워커에서는 설정 임포트를 사용할 수 없습니다. `sync` 명령어는 항목 선택과 확인을 요청합니다. 변경 사항을 불러오려면 에이전트를 다시 시작하세요. 필요한 실행 파일을 샌드박스에 설치하고 노트북 컴퓨터에서만 유효한 경로를 바꾸세요. [스킬 및 MCP 임포트](https://github.com/coreweave/cws-agent/blob/main/docs/config-import.md)를 참조하세요. * **핵심 결과를 반환하세요.** 도구가 데이터를 모델에 반환하기 전에 샌드박스에서 필터링하거나 요약하도록 하세요. 예를 들어 전체 테스트 출력을 파일에 저장하고 실패한 테스트 이름과 간략한 실패 요약을 반환하세요. 후속 검토를 위해 파일을 계속 사용할 수 있도록 유지하세요. * **독립적인 오퍼레이션을 병렬로 실행하세요.** 리소스가 허용하는 경우 독립적인 검사를 동시에 실행하세요. 의존성이 있는 단계는 사전 요구 사항이 충족될 때까지 기다리세요. [SDK 실행 가이드](/ko/products/sandboxes/client/guides/execution#sequential-compared-with-parallel-execution)에서 명령어를 시작하고 결과를 수집하는 방법을 설명합니다. 도구 검색, 컨텍스트 압축, 호출할 도구 결정은 하니스의 기능입니다. CoreWeave는 명령어를 실행하고 해당 파일을 저장합니다.

결과 보존 및 컴퓨팅 중지

에이전트를 종료하거나 공급자 세션을 끝내더라도 샌드박스가 반드시 중지되는 것은 아닙니다. 인테그레이션 가이드의 정리 단계를 따르고, 컴퓨팅 리소스를 생성할 때 수명을 설정하세요. 중지하기 전에 결과를 복사해 두거나, 변경 사항을 저장소에 푸시하거나, [파일 시스템 스냅샷](/ko/products/sandboxes/file-system-snapshots)을 사용하도록 스냅샷 볼륨을 설정하세요. 스냅샷은 파일을 보존하지만 실행 중인 프로세스는 보존하지 않습니다. 공급자의 대화 이력에는 별도의 라이프사이클이 있습니다.