> ## 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.

# 샌드박스에서 OpenCode 실행하기

> Serverless Inference 또는 다른 모델 공급자를 사용해 샌드박스에서 OpenCode를 실행합니다.

CoreWeave 샌드박스에서 저장소를 대상으로 OpenCode를 실행하세요. 터미널에서 작업을 전송하고,
생성된 파일을 확인한 다음, 나중에 다시 사용할 수 있도록 워크스페이스를 저장하세요. 에이전트
프로세스, 워크스페이스, 명령어는 모두 샌드박스에서 실행되며, 모델 요청은 설정한
공급자로 전송됩니다.

<h2 id="prerequisites">
  사전 요구 사항
</h2>

시작하기 전에 다음 항목이 필요합니다.

* 샌드박스 액세스용 `SANDBOX_USER` 액션이 포함된 [CoreWeave API 액세스 토큰](/ko/products/sandboxes/placement#choose-and-get-credentials)
* Serverless Inference 또는 다른
  OpenCode 공급자를 통한 모델 액세스 권한. 공급자 액세스와
  결제는 샌드박스 액세스와 별도로 관리됩니다.
* 공개 저장소 URL. 비공개 저장소를 사용하려면 샌드박스 내부에
  Git 사용자 인증 정보가 필요합니다.
* [설치 안내](https://github.com/coreweave/cws-agent#install)에 따라
  설치한 `cws-agent`

로컬 터미널에서 `[API-ACCESS-TOKEN]`을 CoreWeave API 액세스 토큰으로 바꾸세요.

```bash theme={"system"}
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
```

<h2 id="launch-opencode-with-cws-agent">
  cws-agent로 OpenCode 실행하기
</h2>

`cws-agent`를 사용하여 샌드박스에 OpenCode를 설치하고, 저장소를
`/workspace/project` 디렉터리에 복제한 다음,
[파일 시스템 스냅샷](/ko/products/sandboxes/file-system-snapshots)에 사용할 스냅샷 마운트를 설정하세요.

다음 공급자 옵션 중 하나를 선택하세요. `[SANDBOX-NAME]`은 소문자, 숫자 또는
하이픈으로 구성된 1\~40자의 세션 이름으로 바꾸세요. 이름은 영문자 또는 숫자로
시작해야 합니다. `[REPOSITORY-URL]`은 공개 저장소 URL로 바꾸세요.

<h3 id="use-wb-serverless-inference-recommended">
  Serverless Inference 사용(권장)
</h3>

이 가이드에서는 Serverless Inference를 공급자로 사용하는 것을 권장합니다. Serverless Inference를
사용하면 호스팅된 오픈 모델에 액세스할 수 있습니다. OpenCode에서 지원하는 다른 모델과 공급자를
사용할 수도 있으며, 이 경우
[다른 모델 공급자 사용](#use-another-model-provider)을 참고하세요.

Forge 프로젝트 생성을 포함한 [Serverless Inference 사전 요구 사항](/ko/products/inference/serverless/api-reference#prerequisites)을 완료하고,
사용 가능한
[추론 크레딧](/ko/products/inference/serverless/usage-limits)을 확인하세요.
추론에 사용할 Forge API 키를 설정하세요. 이 예제에서는 GLM 5.2를 명시적으로 지정합니다.

```bash theme={"system"}
export FORGE_API_KEY="[FORGE-API-KEY]"
WANDB_API_KEY="$FORGE_API_KEY" cws-agent launch [SANDBOX-NAME] --agent opencode \
  --repo-url [REPOSITORY-URL] --lifetime 2h \
  --wandb --wandb-model zai-org/GLM-5.2 \
  --permission-mode native --detach
```

`--wandb` 사전 설정은 Forge의 추론 엔드포인트를 설정하고 OpenCode가 해당 공급자만 사용하도록 제한합니다. 이 CLI 사전 설정에는 `WANDB_API_KEY`라는 환경 변수 이름이 필요하므로, 명령어에서 `FORGE_API_KEY`를 이 이름에 매핑한 후 샌드박스로 전달합니다. 샌드박스 액세스에는 `CWSANDBOX_API_KEY`를 사용합니다. 다른
Forge 모델을 선택하려면 `zai-org/GLM-5.2`를
[사용 가능한 모델](/ko/products/inference/serverless/models) 목록에 있는 ID로 바꾸세요.

<h3 id="use-another-model-provider">
  다른 모델 공급자 사용
</h3>

다른 공급자를 사용하려면 샌드박스를 생성할 때 `--wandb`와 `--wandb-model`을
생략하세요. 그런 다음 해당 공급자의 API 키를 로컬 환경 변수로 내보내세요. 예를 들어
다음 중 하나를 선택하고 키 플레이스홀더를 실제 값으로 바꾸세요.

<Tabs>
  <Tab title="Anthropic">
    ```bash theme={"system"}
    export ANTHROPIC_API_KEY="[ANTHROPIC-API-KEY]"
    ```
  </Tab>

  <Tab title="OpenAI">
    ```bash theme={"system"}
    export OPENAI_API_KEY="[OPENAI-API-KEY]"
    ```
  </Tab>
</Tabs>

두 필드의 `[PROVIDER-ID]/[MODEL-ID]`를 OpenCode 모델 식별자로 바꾸세요. 이때
공급자에 맞게 `anthropic/` 또는 `openai/` 접두사를 붙이세요.
`small_model` 필드는 제목 생성과 같은 가벼운 작업에 사용할 모델을 지정합니다.
자세한 내용은 [OpenCode models](https://opencode.ai/docs/models/)를 참조하세요.

```bash theme={"system"}
export OPENCODE_CONFIG_CONTENT='{"model":"[PROVIDER-ID]/[MODEL-ID]","small_model":"[PROVIDER-ID]/[MODEL-ID]"}'
cws-agent launch [SANDBOX-NAME] --agent opencode \
  --repo-url [REPOSITORY-URL] --lifetime 2h \
  --env-passthrough OPENCODE_CONFIG_CONTENT \
  --permission-mode native --detach
```

`ANTHROPIC_API_KEY`와 `OPENAI_API_KEY`가 설정되어 있으면 `cws-agent`가 이를 전달합니다.
키가 자동으로 전달되지 않는 공급자는 해당
[OpenCode 공급자 설정](https://opencode.ai/docs/providers/)을 따르고, 추가 환경 변수는
`--env-passthrough [VARIABLE-NAME]`으로 전달하세요.

두 실행 옵션 모두 설정이 끝나면 `session ready.`를 출력합니다. `--detach`를 사용하면 터미널
인터페이스를 열지 않고 로컬 스킬과 Model Context Protocol(MCP) 설정도 임포트하지 않은 채
샌드박스를 계속 실행해 둡니다. 2시간 수명은 설정 시간을 포함한 실제 경과 시간
기준입니다. 작업을 마치면 컴퓨팅을 중지하세요.

<h2 id="run-a-task-and-check-the-result">
  작업 실행 및 결과 확인
</h2>

로컬 터미널에서 OpenCode에 파일을 작성하고 읽어 달라고 요청하세요.

```bash theme={"system"}
cws-agent run [SANDBOX-NAME] \
  'Create sandbox-proof.txt in the current directory containing exactly Hello from CoreWeave followed by a newline, then read it back. Do not commit or push anything.' \
  --permission-mode native
```

이 명령은 대화형 터미널 없이 OpenCode를 실행합니다. `--permission-mode native`를 지정하면
OpenCode에 설정된 권한이 그대로 유지됩니다. 이 옵션을 지정하지 않으면 `cws-agent`는 기본적으로
승인 요청을 수락합니다. OpenCode 정책상 해당 작업에 승인이 필요하다면
대화형 세션에서 승인하세요. 자세한 내용은
[OpenCode permissions](https://opencode.ai/docs/permissions/)를 참조하세요.

에이전트의 응답과 별개로 실제 파일을 직접 확인하세요:

```bash theme={"system"}
cws-agent exec [SANDBOX-NAME] 'cat /workspace/project/sandbox-proof.txt'
```

`Hello from CoreWeave`가 출력되어야 합니다. 컴퓨팅을 중지하기 전에 로컬 사본을
조회하세요.

```bash theme={"system"}
cws-agent exec [SANDBOX-NAME] 'cat /workspace/project/sandbox-proof.txt' > sandbox-proof.txt
```

<h3 id="optional-work-interactively">
  선택 사항: 대화형으로 작업하기
</h3>

macOS 또는 Linux의 대화형 터미널에서 같은
워크스페이스로 OpenCode를 실행하세요.

```bash theme={"system"}
cws-agent connect [SANDBOX-NAME] --permission-mode native --no-config-sync
```

`--no-config-sync` 플래그를 사용하면 로컬 스킬과 MCP 임포트를 건너뜁니다. OpenCode에서 프롬프트를 보내고
작업을 승인한 다음, `/exit`로 로컬 터미널로 돌아가세요.
OpenCode를 종료해도 샌드박스는 계속 실행됩니다. OpenCode를 다시 열려면 연결
명령어를 다시 실행하세요. 이전 대화는 자동으로 선택되지 않습니다.
대화 이력 및 재개 명령어는
[`cws-agent` 세션](https://github.com/coreweave/cws-agent/blob/main/docs/sessions.md)을 참조하세요.

<h2 id="save-stop-and-restore">
  저장, 중지 및 복원
</h2>

에이전트 작업이 끝나면 워크스페이스의 스냅샷을 만들고 컴퓨팅을 중지하세요.

```bash theme={"system"}
cws-agent down [SANDBOX-NAME]
```

`down`은 샌드박스를 중지하기 전에 `/workspace` 디렉터리를 저장합니다. 스냅샷에 실패하면
샌드박스는 계속 실행 상태로 유지됩니다. 오류를 확인하고 해결한 후 다시 시도하세요.
명시적인 스냅샷을 기다리지 않고 중지하려면 다음을 실행하세요.

```bash theme={"system"}
cws-agent down [SANDBOX-NAME] --no-snapshot
```

이 명령어만으로는 변경 사항이 저장되지 않을 수 있습니다. 중지하기 전에 결과를 다른 곳에 복사하거나
스냅샷이 완료되었는지 확인하세요. 복원하려면 완료된 스냅샷이 있어야 합니다.

Forge 추론으로 저장된 워크스페이스로 돌아가려면 로컬 터미널에서 `FORGE_API_KEY`가
아직 export되어 있는지 확인한 후 다음 명령어를 실행하세요.

```bash theme={"system"}
WANDB_API_KEY="$FORGE_API_KEY" cws-agent restore [SANDBOX-NAME] --wandb --wandb-model zai-org/GLM-5.2 --lifetime 2h --no-config-sync
```

실행할 때 사용한 것과 동일한 `--wandb-model` 값을 사용하세요. `--wandb`를 사용하면서 이 값을 생략하면
복원 시 사전 설정의 기본 모델이 선택됩니다.

다른 공급자를 사용하는 경우 해당 공급자의 키와 `OPENCODE_CONFIG_CONTENT`를 다시 export한 후 다음 명령을 실행하세요.

```bash theme={"system"}
cws-agent restore [SANDBOX-NAME] --env-passthrough OPENCODE_CONFIG_CONTENT --lifetime 2h --no-config-sync
```

복원하면 저장된 워크스페이스에서 새 샌드박스가 생성됩니다. 환경 변수로만 제공되는
사용자 인증 정보는 다시 입력하세요. 스냅샷에는 저장된 OpenCode 로그인 정보와
대화 데이터가 포함될 수 있지만, 실행 중인 프로세스는 보존되지 않습니다.

파일 확인을 다시 실행하여 `sandbox-proof.txt` 파일이 그대로 남아 있는지 확인하세요.
`cws-agent run` 또는 대화형 연결 명령어로 작업을 이어서 진행하세요. 작업을 마치면
`cws-agent down`으로 복원된 샌드박스를 중지하세요.

<h2 id="troubleshoot">
  문제 해결
</h2>

설정이나 작업이 실패하면 다음 사항을 확인하세요.

* 샌드박스 인증 실패: CoreWeave API 액세스 토큰과
  샌드박스 액세스 권한을 확인하세요.
* Forge 모델 요청 실패: 추론 액세스 권한, 크레딧, 모델
  ID를 확인하세요. 샌드박스 액세스 권한이 있다고 해서 추론 액세스 권한까지 주어지지는 않습니다.
* 다른 공급자를 사용할 수 없음: `--wandb` 없이 새 세션을 시작하세요.
  Forge 사전 설정은 워크스페이스에 저장되므로 복원할 때 `--wandb`를 생략해도
  사전 설정은 그대로 남아 있습니다. 기존 워크스페이스라면
  [Forge 사전 설정 구성](https://github.com/coreweave/cws-agent/blob/main/docs/opencode.md#resume-and-restore)을 참조하세요.
* 헤드리스 작업에 승인이 필요함: 대화형으로 연결하고 OpenCode의
  승인 프롬프트에서 승인한 후 계속 진행하세요.

<h2 id="next-steps">
  다음 단계
</h2>

자세한 내용은 다음 가이드를 참조하세요.

* [CoreWeave 샌드박스에서 에이전트 실행하기](/ko/products/sandboxes/agents)에서는 에이전트
  실행 모델과 워크스페이스 수명을 설명합니다.
* [OpenCode 설정](https://opencode.ai/docs/config/)에서는 모델,
  공급자, 프로젝트 설정을 다룹니다.
* [Sandboxes SDK 사용하기](/ko/products/sandboxes/client/guides/execution)에서는
  애플리케이션에서 명령어 실행을 직접 관리하는 방법을 설명합니다.