사전 요구 사항
시작하기 전에 다음 항목이 필요합니다.- 샌드박스 액세스용
SANDBOX_USER액션이 포함된 CoreWeave API 액세스 토큰 - Serverless Inference 또는 다른 OpenCode 공급자를 통한 모델 액세스 권한. 공급자 액세스와 결제는 샌드박스 액세스와 별도로 관리됩니다.
- 공개 저장소 URL. 비공개 저장소를 사용하려면 샌드박스 내부에 Git 사용자 인증 정보가 필요합니다.
- 설치 안내에 따라
설치한
cws-agent
[API-ACCESS-TOKEN]을 CoreWeave API 액세스 토큰으로 바꾸세요.
cws-agent로 OpenCode 실행하기
cws-agent를 사용하여 샌드박스에 OpenCode를 설치하고, 저장소를
/workspace/project 디렉터리에 복제한 다음,
파일 시스템 스냅샷에 사용할 스냅샷 마운트를 설정하세요.
다음 공급자 옵션 중 하나를 선택하세요. [SANDBOX-NAME]은 소문자, 숫자 또는
하이픈으로 구성된 1~40자의 세션 이름으로 바꾸세요. 이름은 영문자 또는 숫자로
시작해야 합니다. [REPOSITORY-URL]은 공개 저장소 URL로 바꾸세요.
Serverless Inference 사용(권장)
이 가이드에서는 Serverless Inference를 공급자로 사용하는 것을 권장합니다. Serverless Inference를 사용하면 호스팅된 오픈 모델에 액세스할 수 있습니다. OpenCode에서 지원하는 다른 모델과 공급자를 사용할 수도 있으며, 이 경우 다른 모델 공급자 사용을 참고하세요. Forge 프로젝트 생성을 포함한 Serverless Inference 사전 요구 사항을 완료하고, 사용 가능한 추론 크레딧을 확인하세요. 추론에 사용할 Forge API 키를 설정하세요. 이 예제에서는 GLM 5.2를 명시적으로 지정합니다.--wandb 사전 설정은 Forge의 추론 엔드포인트를 설정하고 OpenCode가 해당 공급자만 사용하도록 제한합니다. 이 CLI 사전 설정에는 WANDB_API_KEY라는 환경 변수 이름이 필요하므로, 명령어에서 FORGE_API_KEY를 이 이름에 매핑한 후 샌드박스로 전달합니다. 샌드박스 액세스에는 CWSANDBOX_API_KEY를 사용합니다. 다른
Forge 모델을 선택하려면 zai-org/GLM-5.2를
사용 가능한 모델 목록에 있는 ID로 바꾸세요.
다른 모델 공급자 사용
다른 공급자를 사용하려면 샌드박스를 생성할 때--wandb와 --wandb-model을
생략하세요. 그런 다음 해당 공급자의 API 키를 로컬 환경 변수로 내보내세요. 예를 들어
다음 중 하나를 선택하고 키 플레이스홀더를 실제 값으로 바꾸세요.
- Anthropic
- OpenAI
[PROVIDER-ID]/[MODEL-ID]를 OpenCode 모델 식별자로 바꾸세요. 이때
공급자에 맞게 anthropic/ 또는 openai/ 접두사를 붙이세요.
small_model 필드는 제목 생성과 같은 가벼운 작업에 사용할 모델을 지정합니다.
자세한 내용은 OpenCode models를 참조하세요.
ANTHROPIC_API_KEY와 OPENAI_API_KEY가 설정되어 있으면 cws-agent가 이를 전달합니다.
키가 자동으로 전달되지 않는 공급자는 해당
OpenCode 공급자 설정을 따르고, 추가 환경 변수는
--env-passthrough [VARIABLE-NAME]으로 전달하세요.
두 실행 옵션 모두 설정이 끝나면 session ready.를 출력합니다. --detach를 사용하면 터미널
인터페이스를 열지 않고 로컬 스킬과 Model Context Protocol(MCP) 설정도 임포트하지 않은 채
샌드박스를 계속 실행해 둡니다. 2시간 수명은 설정 시간을 포함한 실제 경과 시간
기준입니다. 작업을 마치면 컴퓨팅을 중지하세요.
작업 실행 및 결과 확인
로컬 터미널에서 OpenCode에 파일을 작성하고 읽어 달라고 요청하세요.--permission-mode native를 지정하면
OpenCode에 설정된 권한이 그대로 유지됩니다. 이 옵션을 지정하지 않으면 cws-agent는 기본적으로
승인 요청을 수락합니다. OpenCode 정책상 해당 작업에 승인이 필요하다면
대화형 세션에서 승인하세요. 자세한 내용은
OpenCode permissions를 참조하세요.
에이전트의 응답과 별개로 실제 파일을 직접 확인하세요:
Hello from CoreWeave가 출력되어야 합니다. 컴퓨팅을 중지하기 전에 로컬 사본을
조회하세요.
선택 사항: 대화형으로 작업하기
macOS 또는 Linux의 대화형 터미널에서 같은 워크스페이스로 OpenCode를 실행하세요.--no-config-sync 플래그를 사용하면 로컬 스킬과 MCP 임포트를 건너뜁니다. OpenCode에서 프롬프트를 보내고
작업을 승인한 다음, /exit로 로컬 터미널로 돌아가세요.
OpenCode를 종료해도 샌드박스는 계속 실행됩니다. OpenCode를 다시 열려면 연결
명령어를 다시 실행하세요. 이전 대화는 자동으로 선택되지 않습니다.
대화 이력 및 재개 명령어는
cws-agent 세션을 참조하세요.
저장, 중지 및 복원
에이전트 작업이 끝나면 워크스페이스의 스냅샷을 만들고 컴퓨팅을 중지하세요.down은 샌드박스를 중지하기 전에 /workspace 디렉터리를 저장합니다. 스냅샷에 실패하면
샌드박스는 계속 실행 상태로 유지됩니다. 오류를 확인하고 해결한 후 다시 시도하세요.
명시적인 스냅샷을 기다리지 않고 중지하려면 다음을 실행하세요.
FORGE_API_KEY가
아직 export되어 있는지 확인한 후 다음 명령어를 실행하세요.
--wandb-model 값을 사용하세요. --wandb를 사용하면서 이 값을 생략하면
복원 시 사전 설정의 기본 모델이 선택됩니다.
다른 공급자를 사용하는 경우 해당 공급자의 키와 OPENCODE_CONFIG_CONTENT를 다시 export한 후 다음 명령을 실행하세요.
sandbox-proof.txt 파일이 그대로 남아 있는지 확인하세요.
cws-agent run 또는 대화형 연결 명령어로 작업을 이어서 진행하세요. 작업을 마치면
cws-agent down으로 복원된 샌드박스를 중지하세요.
문제 해결
설정이나 작업이 실패하면 다음 사항을 확인하세요.- 샌드박스 인증 실패: CoreWeave API 액세스 토큰과 샌드박스 액세스 권한을 확인하세요.
- Forge 모델 요청 실패: 추론 액세스 권한, 크레딧, 모델 ID를 확인하세요. 샌드박스 액세스 권한이 있다고 해서 추론 액세스 권한까지 주어지지는 않습니다.
- 다른 공급자를 사용할 수 없음:
--wandb없이 새 세션을 시작하세요. Forge 사전 설정은 워크스페이스에 저장되므로 복원할 때--wandb를 생략해도 사전 설정은 그대로 남아 있습니다. 기존 워크스페이스라면 Forge 사전 설정 구성을 참조하세요. - 헤드리스 작업에 승인이 필요함: 대화형으로 연결하고 OpenCode의 승인 프롬프트에서 승인한 후 계속 진행하세요.
다음 단계
자세한 내용은 다음 가이드를 참조하세요.- CoreWeave 샌드박스에서 에이전트 실행하기에서는 에이전트 실행 모델과 워크스페이스 수명을 설명합니다.
- OpenCode 설정에서는 모델, 공급자, 프로젝트 설정을 다룹니다.
- Sandboxes SDK 사용하기에서는 애플리케이션에서 명령어 실행을 직접 관리하는 방법을 설명합니다.