Anthropic이 에이전트 루프를 관리하고 샌드박스에서 도구를 실행하는 인테그레이션은 Claude Managed Agents를 참조하세요.
사전 요구 사항
시작하기 전에 다음이 필요합니다.SANDBOX_USER액션이 부여된 CoreWeave API 액세스 토큰- 터미널 인터페이스를 사용하려면 Claude 계정 또는 Claude Code에서 지원하는 API 사용자 인증 정보가 필요합니다. Remote Control을 사용하려면 Claude Pro, Max, Team 또는 Enterprise 구독이 필요합니다. API 키와
claude setup-token토큰으로는 Remote Control을 인증할 수 없습니다. - 샌드박스에서 복제할 수 있는 저장소 URL. 예시에서는 공개 저장소를 사용합니다. 비공개 저장소를 사용하려면 샌드박스 내부에 Git 사용자 인증 정보가 있어야 합니다.
cws-agent에서는 --lifetime 24h를 사용하세요. 소프트웨어 개발 키트(SDK) 예시에서는 Python의 max_lifetime_seconds 또는 TypeScript의 maxLifetimeSeconds를 24 * 3600으로 설정하세요.
cws-agent 빠른 시작
cws-agent로 샌드박스를 생성하려면 이 설정 방법을 선택하세요. 클라이언트 라이브러리로 직접 생성하려면 Sandboxes SDK로 설정으로 건너뛰세요. 두 방법 모두 어느 인터페이스든 사용할 수 있습니다.
cws-agent 설치 안내를 따르세요. 이 도구는 파일 시스템 스냅샷으로 워크스페이스를 저장하고 복원할 수 있도록 스냅샷 볼륨을 설정합니다.
Claude가 열리기 전에 cws-agent가 임포트할 로컬 스킬과 Model Context Protocol(MCP) 서버의 미리 보기를 표시할 수 있습니다. 이 가이드에서는 임포트 프롬프트에서 Enter를 눌러 건너뛰세요. 임포트는 나중에 에이전트 도구 가이드를 참고하여 설정할 수 있습니다.
다음 인터페이스 중 하나를 선택하세요. [SANDBOX-NAME]을 cws-agent 세션 이름으로, [REPOSITORY-URL]을 공개 저장소 URL로 바꾸세요. 세션 이름은 소문자, 숫자 또는 하이픈으로 구성된 1~40자로 지정하고, 문자 또는 숫자로 시작해야 합니다.
터미널 인터페이스 사용
Anthropic API 키를 사용하려면 샌드박스를 시작하거나 복원하기 전에 로컬 터미널에서ANTHROPIC_API_KEY에 키를 설정하세요. cws-agent는 이 변수를 샌드박스에 전달합니다. API 키 인증에는 브라우저 로그인이 필요하지 않습니다. Claude Code 인증을 참조하세요.
Claude Code를 시작하고 로컬 터미널을 연결하세요:
cws-agent login [SANDBOX-NAME]을 실행한 다음, 해당 환경에서 /login을 완료하세요.
--permission-mode native 옵션은 Claude 자체 승인 설정을 사용합니다. 이 옵션이 없으면 cws-agent는 기본적으로 해당 승인 메시지를 건너뜁니다. 권한 모드를 참조하세요.
API 키가 설정되어 있는데도 Claude가 Not logged in을 표시하고 키 승인 메시지를 표시하지 않는 경우, /exit로 종료한 다음 온보딩을 활성화하여 다시 연결하세요:
Remote Control 사용
분리된 샌드박스를 생성한 다음, 터미널을 연결하여 구독 계정으로 로그인하세요.IS_DEMO 설정을 해제합니다. Claude Code 환경 변수를 참조하세요.
Claude에서 Claude 구독 계정으로 /login을 완료하고 프로젝트 신뢰 프롬프트를 수락하세요. /remote-control을 실행하고 최초 사용 확인을 수락한 다음 /exit로 Claude를 종료하세요. 분리된 서버를 시작하기 전에 확인 질문에 응답해야 하므로 이 단계는 대화형으로 진행하세요.
로컬 터미널에서 Claude 자체 승인 설정을 사용해 Remote Control을 시작하세요.
tmux 세션으로 서버를 다시 시작하세요. cws-agent rc 명령어는 출력을 로그로 리디렉션하므로, 기존 세션에 연결해도 프롬프트가 표시되지 않습니다.
로컬 터미널에서 대기 중인 서버를 중지하고 새 세션을 여세요.
tmux 안에서 Remote Control을 시작해 세션이 프로젝트 디렉터리를 사용하도록 하세요:
tmux에 출력을 표시합니다. 세션으로 다시 돌아가려면 cws-agent connect [SANDBOX-NAME] --cmd 'tmux attach -t cws-remote-control'을 실행하세요.
Sandboxes SDK로 설정
Sandboxes SDK로 샌드박스를 생성하는 대체 방법으로, 두 인터페이스 모두에 사용할 수 있습니다. 이 방법은cws-agent에 의존하지 않으며 스냅샷을 설정하지 않습니다.
이 가이드에서 생성한 가상 환경에서 Python 코드 조각을 실행하세요. TypeScript 코드 조각은 클라이언트를 설치한 프로젝트에 .mts 파일로 저장한 다음, npx tsx [FILENAME].mts로 실행하세요.
샌드박스 생성
클라이언트를 선택하고 로컬에 설치하세요.- Python
- TypeScript
Python 3.11 이상과
uv를 사용하세요.tmux를 설치한 다음, 명령줄 인수로 전달한 저장소를 복제합니다.
두 스크립트 모두 apt-get으로 패키지를 설치하고 /root/.local/bin/claude를 사용하므로 컨테이너가 root로 실행되어야 합니다. 러너의 정책에서 이 사용자를 허용해야 합니다.
- Python
- TypeScript
create_claude_sandbox.py
[REPOSITORY-URL]을 공개 저장소 URL로 바꾸세요.
- Python
- TypeScript
Session 또는 컨텍스트 관리자로 래핑하면 이러한 정리 작업 동작이 달라집니다.
터미널 연결하기
SDK를 사용하여 동일한 CoreWeave 사용자 인증 정보로 로컬 터미널을 연결하세요. 이 스크립트는 키 입력을 샌드박스 셸로 전달하고, 셸이 종료되면 터미널을 원래 상태로 복원합니다.- Python
- TypeScript
macOS 또는 Linux에서 다음 내용을
attach_sandbox.py로 저장하세요.attach_sandbox.py
[SANDBOX-ID]를 출력된 ID로 바꾼 다음 실행하세요.
- Python
- TypeScript
cwsandbox sh [SANDBOX-ID] 단축 명령을 선택적으로 사용할 수 있습니다. cli extra를 설치하고, CWSANDBOX_API_KEY에는 해당 샌드박스에 사용한 CoreWeave API 액세스 토큰을 계속 설정해 두세요.
이제 터미널이 샌드박스 내부의 셸에 연결되었습니다. 다음 인터페이스 중 하나를 선택하여 Claude Code를 시작하세요.
터미널 인터페이스 시작
API 키 인증을 사용하는 경우 Claude를 시작하기 전에 샌드박스의 Bash 셸에서 키를 입력하세요. 입력 내용은 화면에 표시되지 않으며 명령 이력에도 남지 않습니다.Remote Control 시작
이 인터페이스에서는 Claude 구독 계정으로 로그인하세요. 이전에 이 샌드박스에서 API 키를 사용했다면 로그인하기 전에 셸과 모든 Claude 설정에서 해당 키를 제거하세요:tmux 세션을 여세요.
tmux에서 Claude를 실행하세요.
/exit로 Claude를 종료한 후 같은 디렉터리에서 Remote Control 서버를 시작하세요.
--spawn same-dir 옵션을 지정하면 원격 세션에서 프로젝트 디렉터리를 사용합니다. 확인 메시지가 표시되면 최초 사용 확인을 수락하세요. 표시된 Claude Code URL을 같은 Claude 계정으로 로그인한 브라우저에서 여세요.
연결이 확인되면 Ctrl-b를 누른 다음 d를 눌러 tmux에서 분리하고 샌드박스 셸을 종료하세요. 서버는 tmux 세션에서 계속 실행됩니다. 다시 접속하려면 연결 스크립트를 다시 실행한 다음 tmux attach -t claude-remote를 실행하세요.
세션 확인
터미널 인터페이스를 사용하는 경우 연결된 Claude Code TUI에서 프롬프트를 보내세요. Remote Control을 사용하는 경우 동일한 계정으로 브라우저에서 claude.ai/code 에 접속하거나 Claude 모바일 앱 또는 Desktop 앱에서 세션을 여세요. 다른 값과 겹치지 않으면서 민감하지 않은 테스트 값을 정한 다음, 다음 프롬프트의[PROOF-VALUE]를 해당 값으로 바꾸세요.
/exit로 Claude를 종료하고, SDK 설정을 사용한 경우 exit로 샌드박스 셸도 종료하세요. 그런 다음 로컬 터미널에서 사용 중인 설정에 맞는 명령어로 결과를 확인하세요.
- cws-agent
- Sandboxes SDK
실행 중인 샌드박스로 돌아가기
Claude를 종료하거나 터미널을 닫아도 샌드박스는 계속 실행됩니다. 다른 터미널이나 머신에서 다시 접속하려면 동일한 클라이언트를 설치한 후, 해당 샌드박스에 액세스할 수 있는 사용자 인증 정보로 인증하세요.cws-agent를 사용하는 경우 이름으로 세션을 찾은 다음 새 Claude 터미널을 여세요.
connect 명령어는 기존 샌드박스와 파일을 그대로 사용하지만, 이전 대화를 재개하지는 않습니다. 저장된 대화를 이어서 진행하려면 먼저 해당 대화를 실행한 원본 Claude 프로세스를 종료하세요. 그런 다음 이력 목록을 확인하고 [CONVERSATION-ID]를 재개할 ID로 바꾸세요:
tmux 또는 cws-agent 워크트리 세션을 사용하세요.
재연결해도 샌드박스의 수명은 재설정되지 않습니다. 샌드박스가 이미 중단되었다면 저장된 워크스페이스를 복원하세요.
결과 보존 및 중지
수명이 거의 끝날 때까지 기다리지 말고, 긴 세션 중간중간 진행 상황을 저장하세요.cws-agent를 사용하는 경우 Claude가 쓰기를 마칠 때까지 기다리고 워크스페이스에 쓰는 다른 프로세스를 일시 중지한 다음, 샌드박스를 중지하지 않은 상태로 /workspace 디렉터리를 캡처하세요.
READY 상태의 스냅샷이 표시될 때까지 기다리세요. 스냅샷은 생성 시점의 파일을 캡처합니다. 이후에 편집한 내용을 보존하려면 스냅샷을 다시 생성해야 합니다. 캡처 동작과 저장된 사용자 인증 정보에 대한 자세한 내용은 스냅샷 가이드를 참조하세요. 수명 만료 시 최신 변경 사항이 자동으로 저장된다고 가정하지 마세요.
로컬 터미널에서 검증된 텍스트 결과를 로컬 컴퓨터로 복사하세요.
down 명령어는 샌드박스를 중지하기 전에 스냅샷이 생성되었는지 확인합니다. 스냅샷 생성에 실패하면 샌드박스는 계속 실행 상태로 유지됩니다. cws-agent status [SANDBOX-NAME]을 확인하고 실패 원인을 해결한 후 다시 시도하세요. 현재 변경 사항을 저장하지 않고 중지하려면 cws-agent down [SANDBOX-NAME] --no-snapshot을 사용하세요.
SDK를 직접 사용하는 경우 이 예제에는 영구 마운트가 없습니다. 복원 가능한 워크스페이스가 필요하면 샌드박스를 생성할 때 파일 시스템 스냅샷을 설정하세요. 파일 작업으로 결과를 외부로 복사한 다음 샌드박스를 중지하세요.
- Python
- TypeScript
cws-agent로 저장한 워크스페이스로 돌아가려면 새 샌드박스에 복원하세요. 스킬/MCP 임포트 프롬프트가 나타나면 Enter를 눌러 건너뛰세요.
/exit로 복원된 Claude TUI를 종료한 다음, cws-agent connect부터 로그인 및 서버 시작 단계를 다시 진행하세요. 복원 과정에서 이미 샌드박스가 생성되었으므로 실행 명령어는 건너뛰세요. 저장된 대화와 병렬 워크트리에 대한 자세한 내용은 cws-agent 세션 가이드를 참조하세요.
문제 해결
다음 항목을 확인하여 일반적인 문제를 해결하세요.- 샌드박스 생성에 실패하면 CoreWeave API 액세스 토큰과 인증 설정을 확인하세요.
- 설치, 복제 또는 모델 요청이 실패하면 아웃바운드 연결 상태와 해당 공급자의 사용자 인증 정보를 확인하세요. CoreWeave Kubernetes Service (CKS) 배치를 사용하는 경우 러너의 정책에서 해당 대상을 허용해야 합니다.
- 터미널 연결이 끊어지면 샌드박스가 실행 중일 때 다시 연결하세요. 터미널 연결이 끊어져도 프로세스가 유지되게 하려면
tmux같은 터미널 멀티플렉서에서 프로세스를 실행하세요. - Remote Control에서 인증이 거부되면 Claude 구독 계정으로 로그인하세요. 원격 환경이나 Claude 설정에 충돌하는 API 키 사용자 인증 정보가 있다면 제거하세요.
- Remote Control을 사용할 수 없으면 Anthropic의 문제 해결 가이드에서 조직 설정, 맞춤형 API 엔드포인트, 필수 기능 확인을 비활성화하는 환경 변수 관련 내용을 확인하세요.
- 샌드박스가 만료되면 새로 만드세요. 수명은 생성 후에 연장할 수 없으며, 이 SDK 예시는 파일 시스템을 자동으로 저장하지 않습니다.
데이터 처리
명령어는 샌드박스에서 실행되고, 모델 요청은 설정한 공급자로 전송됩니다. Remote Control은 프롬프트, 도구 활동, 대화 내용을 Anthropic으로 전송하며, 연결된 기기 간 동기화를 위해 전사본을 저장합니다. 자세한 내용은 Remote Control 보안 및 Claude Code 데이터 사용을 참조하세요.다음 단계
자세한 내용은 다음 가이드를 참조하세요:- 대화형 셸 및 TTY에서는 SDK에서 터미널 액세스를 다룹니다.
- 샌드박스 라이프사이클에서는 대기, 재연결, 중지를 다룹니다.
- Claude Code 문서에서는 에이전트 설정 및 인증을 다룹니다.