Skip to main content
CoreWeave 샌드박스에서 Claude Code를 실행하고 상호작용 방식을 선택하세요. 터미널 사용자 인터페이스(TUI)를 사용하면 로컬 터미널에서 샌드박스 내부의 Claude Code를 제어할 수 있습니다. Remote Control을 사용하면 Claude 모바일 앱, Claude Desktop 또는 claude.ai/code에서 상호작용할 수 있습니다. 어느 방식이든 에이전트 프로세스, 도구, 워크스페이스는 모두 샌드박스에서 실행되며, 모델 요청은 설정한 모델 공급자로 전송됩니다. 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 사용자 인증 정보가 있어야 합니다.
이 가이드를 진행할 터미널에서 CoreWeave API 액세스 토큰을 내보내세요.
Remote Control을 사용하려면 Team 및 Enterprise 계정에서는 Owner가 이 기능을 활성화해야 합니다. 또한 조직에서 이 기능의 전사본 저장을 허용해야 합니다. Zero Data Retention 요구 사항이 적용되는 조직에서는 이 기능을 활성화할 수 없습니다. Anthropic의 Remote Control 요구 사항을 확인하세요. 연결에는 아웃바운드 HTTPS가 사용되므로 공개 샌드박스 엔드포인트나 인바운드 포트가 필요하지 않습니다. 두 설정 방식 모두 하루 근무 시간에 맞춰 샌드박스 수명을 8시간으로 설정합니다. 수명은 생성 시점부터 계산되며 설정 시간과 유휴 시간도 포함되고, 연장할 수 없습니다. 수명이 만료되면 Claude가 작업 중이더라도 샌드박스가 중지되고 세션이 종료됩니다. 작업을 마치면 수명이 만료되기 전에 결과를 저장하고 샌드박스를 중지하세요. 밤새 작업하려면 생성 시 24시간을 선택하세요. 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를 시작하고 로컬 터미널을 연결하세요:
Claude Code가 샌드박스의 프로젝트 디렉터리에서 열립니다. 워크스페이스 신뢰 프롬프트가 표시되면 안내를 따르세요. API 키 인증을 사용하는 경우 메시지가 표시되면 키를 승인하세요. 계정 인증이 필요한 경우 Claude를 종료하고 cws-agent login [SANDBOX-NAME]을 실행한 다음, 해당 환경에서 /login을 완료하세요. --permission-mode native 옵션은 Claude 자체 승인 설정을 사용합니다. 이 옵션이 없으면 cws-agent는 기본적으로 해당 승인 메시지를 건너뜁니다. 권한 모드를 참조하세요. API 키가 설정되어 있는데도 Claude가 Not logged in을 표시하고 키 승인 메시지를 표시하지 않는 경우, /exit로 종료한 다음 온보딩을 활성화하여 다시 연결하세요:
이 명령은 Claude 자체 승인 설정을 사용합니다. 계속하기 전에 워크스페이스 신뢰 및 API 키 확인 요청을 수락하세요. 세션 확인으로 이동하여 프롬프트를 보내고 결과를 확인하세요.

Remote Control 사용

분리된 샌드박스를 생성한 다음, 터미널을 연결하여 구독 계정으로 로그인하세요.
연결 명령어는 구독 로그인이나 Remote Control 기능 확인을 방해할 수 있는 설정을 지웁니다. 또한 온보딩을 활성화하기 위해 IS_DEMO 설정을 해제합니다. Claude Code 환경 변수를 참조하세요. Claude에서 Claude 구독 계정으로 /login을 완료하고 프로젝트 신뢰 프롬프트를 수락하세요. /remote-control을 실행하고 최초 사용 확인을 수락한 다음 /exit로 Claude를 종료하세요. 분리된 서버를 시작하기 전에 확인 질문에 응답해야 하므로 이 단계는 대화형으로 진행하세요. 로컬 터미널에서 Claude 자체 승인 설정을 사용해 Remote Control을 시작하세요.
세션 URL이 표시되면 해당 URL을 여세요. 프로세스가 시작되었다는 메시지만으로는 연결되었다고 판단할 수 없습니다. 웹, 모바일 또는 데스크톱 클라이언트에서 프롬프트를 보낸 후 세션 확인에 설명된 방법으로 결과를 확인하세요. URL이 표시되지 않으면 원격 로그를 살펴보세요.
재시도하기 전에 로그인 또는 자격 요건 오류를 먼저 해결하세요. 서버가 대화형 프롬프트 입력을 기다리고 있다면, 같은 샌드박스에서 연결된(attached) tmux 세션으로 서버를 다시 시작하세요. cws-agent rc 명령어는 출력을 로그로 리디렉션하므로, 기존 세션에 연결해도 프롬프트가 표시되지 않습니다. 로컬 터미널에서 대기 중인 서버를 중지하고 새 세션을 여세요.
tmux 안에서 Remote Control을 시작해 세션이 프로젝트 디렉터리를 사용하도록 하세요:
표시되는 프롬프트에 응답한 뒤 화면에 나타난 Claude Code URL을 여세요. 연결이 정상적으로 작동하면 Ctrl-b를 누른 다음 d를 눌러 세션에서 분리하세요. 그러면 서버는 계속 실행됩니다. 대체 세션은 로그를 업데이트하지 않고 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 3.11 이상과 uv를 사용하세요.
사용하는 언어에 맞는 스크립트를 표시된 파일 이름으로 저장하세요. 이 스크립트는 Claude Code와 tmux를 설치한 다음, 명령줄 인수로 전달한 저장소를 복제합니다. 두 스크립트 모두 apt-get으로 패키지를 설치하고 /root/.local/bin/claude를 사용하므로 컨테이너가 root로 실행되어야 합니다. 러너의 정책에서 이 사용자를 허용해야 합니다.
create_claude_sandbox.py
[REPOSITORY-URL]을 공개 저장소 URL로 바꾸세요.
출력된 샌드박스 ID를 기록해 두세요. 이 독립 실행형 예시에서는 스크립트가 종료된 후에도 샌드박스가 계속 실행됩니다. 샌드박스는 직접 중지하거나 8시간 수명이 만료될 때까지 실행됩니다. Python에서는 샌드박스를 Session 또는 컨텍스트 관리자로 래핑하면 이러한 정리 작업 동작이 달라집니다.

터미널 연결하기

SDK를 사용하여 동일한 CoreWeave 사용자 인증 정보로 로컬 터미널을 연결하세요. 이 스크립트는 키 입력을 샌드박스 셸로 전달하고, 셸이 종료되면 터미널을 원래 상태로 복원합니다.
macOS 또는 Linux에서 다음 내용을 attach_sandbox.py로 저장하세요.
attach_sandbox.py
[SANDBOX-ID]를 출력된 ID로 바꾼 다음 실행하세요.
cwsandbox sh [SANDBOX-ID] 단축 명령을 선택적으로 사용할 수 있습니다. cli extra를 설치하고, CWSANDBOX_API_KEY에는 해당 샌드박스에 사용한 CoreWeave API 액세스 토큰을 계속 설정해 두세요. 이제 터미널이 샌드박스 내부의 셸에 연결되었습니다. 다음 인터페이스 중 하나를 선택하여 Claude Code를 시작하세요.

터미널 인터페이스 시작

API 키 인증을 사용하는 경우 Claude를 시작하기 전에 샌드박스의 Bash 셸에서 키를 입력하세요. 입력 내용은 화면에 표시되지 않으며 명령 이력에도 남지 않습니다.
샌드박스 내에서 복제한 저장소에서 Claude를 시작하세요:
API 키를 사용하는 경우, 이를 승인하세요. 그렇지 않으면 계정 로그인을 완료하세요. 그런 다음 워크스페이스 신뢰 프롬프트를 수락하고 세션 확인으로 이동하세요.

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로 샌드박스 셸도 종료하세요. 그런 다음 로컬 터미널에서 사용 중인 설정에 맞는 명령어로 결과를 확인하세요.
값이 일치하면 직접 생성한 샌드박스에 Claude가 파일을 썼음을 확인할 수 있습니다.

실행 중인 샌드박스로 돌아가기

Claude를 종료하거나 터미널을 닫아도 샌드박스는 계속 실행됩니다. 다른 터미널이나 머신에서 다시 접속하려면 동일한 클라이언트를 설치한 후, 해당 샌드박스에 액세스할 수 있는 사용자 인증 정보로 인증하세요. cws-agent를 사용하는 경우 이름으로 세션을 찾은 다음 새 Claude 터미널을 여세요.
connect 명령어는 기존 샌드박스와 파일을 그대로 사용하지만, 이전 대화를 재개하지는 않습니다. 저장된 대화를 이어서 진행하려면 먼저 해당 대화를 실행한 원본 Claude 프로세스를 종료하세요. 그런 다음 이력 목록을 확인하고 [CONVERSATION-ID]를 재개할 ID로 바꾸세요:
SDK 방식을 사용하는 경우 동일한 샌드박스 ID로 터미널 연결 스크립트를 다시 실행한 다음 Claude를 다시 시작하세요. 샌드박스의 수명이 더 길더라도 SDK 셸 세션 하나는 24시간이 지나면 종료됩니다. 샌드박스는 계속 실행 중이므로 스크립트를 다시 실행하면 재연결할 수 있습니다. Remote Control을 사용하는 경우 해당 서버가 실행 중인 동안 세션 URL을 다시 여세요. 샌드박스 연결과 에이전트 프로세스의 수명은 서로 별개입니다. 연결을 끊은 후에도 터미널 에이전트가 계속 작업해야 한다면 tmux 또는 cws-agent 워크트리 세션을 사용하세요. 재연결해도 샌드박스의 수명은 재설정되지 않습니다. 샌드박스가 이미 중단되었다면 저장된 워크스페이스를 복원하세요.

결과 보존 및 중지

수명이 거의 끝날 때까지 기다리지 말고, 긴 세션 중간중간 진행 상황을 저장하세요. cws-agent를 사용하는 경우 Claude가 쓰기를 마칠 때까지 기다리고 워크스페이스에 쓰는 다른 프로세스를 일시 중지한 다음, 샌드박스를 중지하지 않은 상태로 /workspace 디렉터리를 캡처하세요.
명령어 출력에 READY 상태의 스냅샷이 표시될 때까지 기다리세요. 스냅샷은 생성 시점의 파일을 캡처합니다. 이후에 편집한 내용을 보존하려면 스냅샷을 다시 생성해야 합니다. 캡처 동작과 저장된 사용자 인증 정보에 대한 자세한 내용은 스냅샷 가이드를 참조하세요. 수명 만료 시 최신 변경 사항이 자동으로 저장된다고 가정하지 마세요. 로컬 터미널에서 검증된 텍스트 결과를 로컬 컴퓨터로 복사하세요.
코드 변경 사항은 변경 사항 가져오기를 참조하세요. 스냅샷은 원격 워크스페이스를 보존할 뿐, 파일을 로컬 머신으로 복사하지는 않습니다. 작업을 마쳤다면 진행 중인 작업과 워크스페이스 쓰기가 모두 완료될 때까지 기다린 다음, 워크스페이스를 저장하고 컴퓨팅을 중지하세요.
down 명령어는 샌드박스를 중지하기 전에 스냅샷이 생성되었는지 확인합니다. 스냅샷 생성에 실패하면 샌드박스는 계속 실행 상태로 유지됩니다. cws-agent status [SANDBOX-NAME]을 확인하고 실패 원인을 해결한 후 다시 시도하세요. 현재 변경 사항을 저장하지 않고 중지하려면 cws-agent down [SANDBOX-NAME] --no-snapshot을 사용하세요. SDK를 직접 사용하는 경우 이 예제에는 영구 마운트가 없습니다. 복원 가능한 워크스페이스가 필요하면 샌드박스를 생성할 때 파일 시스템 스냅샷을 설정하세요. 파일 작업으로 결과를 외부로 복사한 다음 샌드박스를 중지하세요.
Claude만 종료해서는 샌드박스가 중지되지 않습니다. 샌드박스를 중지하면 Remote Control을 포함한 에이전트 프로세스가 모두 종료됩니다. 스냅샷에서 파일을 복원해도 이 프로세스는 복원되지 않으므로, 필요하면 로그인한 후 Remote Control을 다시 시작하세요. cws-agent로 저장한 워크스페이스로 돌아가려면 새 샌드박스에 복원하세요. 스킬/MCP 임포트 프롬프트가 나타나면 Enter를 눌러 건너뛰세요.
Remote Control을 사용하는 경우 /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 데이터 사용을 참조하세요.

다음 단계

자세한 내용은 다음 가이드를 참조하세요: claude.ai/code 에서 새 클라우드 세션을 시작할 때마다 워커 샌드박스를 프로비저닝하려면 Claude Code 클라우드 세션을 참조하세요.
마지막 수정일 2026년 10월 15일