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

# CLI로 샌드박스 관리하기

> 샌드박스 CLI를 설치하여 샌드박스를 검사하고, 명령어를 실행하고, 파일을 전송하고, 스냅샷을 관리하세요.

`cwsandbox` 명령줄 인터페이스(CLI)를 사용하면 터미널에서 기존 CoreWeave 샌드박스를 관리할 수 있습니다. CLI로 샌드박스 검사, 명령어 실행, 로그 조회, 파일 전송, 파일 시스템 스냅샷 관리, 리소스 정리 등의 작업을 수행할 수 있습니다. CLI는 [샌드박스 Python 클라이언트](https://docs.coreweave.com/ko/products/sandboxes/client.md)의 선택적 추가 기능(extra)으로 설치합니다.

CLI를 사용하기 전에 먼저 SDK로 샌드박스를 생성하세요. [서버리스 퀵스타트](https://docs.coreweave.com/ko/products/sandboxes/get-started.md) 또는 [자체 컴퓨팅 사용하기](https://docs.coreweave.com/ko/products/sandboxes/get-started-cks.md)를 참고하여 샌드박스를 생성할 수 있습니다.

## 사전 요구 사항

시작하기 전에 다음을 준비하세요.

* `uv`가 설치된 [활성화된 Python 3.11 이상 가상 환경](https://docs.coreweave.com/ko/products/sandboxes/client.md#prepare-your-python-environment)
* 샌드박스를 소유한 계정의 사용자 인증 정보. 사용자 인증 정보 설정 방법과 필요한 역할은 [사용자 인증 정보 선택 및 가져오기](https://docs.coreweave.com/ko/products/sandboxes/placement.md#choose-and-get-credentials)를 참조하세요.
* 명령어 실행, 대화형 셸, 로그 조회, 파일 작업, 스냅샷 생성에 사용할 실행 중인 샌드박스

## 설치 및 인증

샌드박스를 생성할 때 사용한 사용자 인증 정보를 선택하세요. 활성화된 가상 환경에서 탭 중 하나의 명령어를 실행하고, 사용자 인증 정보 플레이스홀더는 실제 키 또는 토큰으로 바꾸세요.

**Forge API 키**

`cli` 및 `wandb` extra를 설치한 다음, Forge API 키에 사용할 W\&B 인증 전략을 선택하세요.

```bash theme={"system"}
uv pip install --upgrade 'cwsandbox[cli,wandb]'
export WANDB_API_KEY="WANDB_API_KEY_VALUE"
export CWSANDBOX_AUTH="wandb"
cwsandbox --help
```

**CoreWeave API 액세스 토큰**

`cli` extra를 설치하고 CoreWeave 인증을 선택하세요.

```bash theme={"system"}
uv pip install --upgrade 'cwsandbox[cli]'
export CWSANDBOX_API_KEY="API_ACCESS_TOKEN"
export CWSANDBOX_AUTH="coreweave_api_key"
cwsandbox --help
```

도움말 출력에 사용 가능한 명령어 목록이 표시됩니다. 이후 예시를 실행할 터미널에서는 인증 변수가 설정된 상태를 유지하세요.

`CWSANDBOX_AUTH`는 사용자 인증 정보 전략을 지정합니다. 최상위 `--auth` 옵션을 사용하면 한 번의 호출에 한해 이 값을 재정의할 수 있습니다. 예를 들어 Forge 의존성과 사용자 인증 정보가 설정되어 있다면 다음과 같습니다.

```bash theme={"system"}
cwsandbox --auth wandb ls
```

명령어나 하위 명령어의 옵션을 확인하려면 `--help`를 사용하세요.

```bash theme={"system"}
cwsandbox exec --help
cwsandbox files read --help
cwsandbox snapshots create --help
```

## 샌드박스 찾기

사용자 인증 정보로 조회할 수 있는 샌드박스 목록을 확인하세요.

```bash theme={"system"}
cwsandbox ls
```

상태로 필터링하거나 상태와 태그를 조합해 필터링하세요. `TAG`는 샌드박스에 연결된 태그로 바꾸세요.

```bash theme={"system"}
cwsandbox ls --status running
cwsandbox ls --status running --tag "TAG" --output json
```

기본 table에는 샌드박스 ID, 상태, 러너, 시작 시간이 표시됩니다. `--output json`을 사용하면 구조화된 출력이 반환됩니다. 필터 값을 여러 개 지정하려면 `--tag` 또는 `--runner-id`를 반복해서 사용하세요.

## 샌드박스 검사하기

`SANDBOX_ID_VALUE`를 `cwsandbox ls`에서 확인한 ID로 바꾼 다음, 터미널에서 다음과 같이 설정하세요.

```bash theme={"system"}
export SANDBOX_ID="SANDBOX_ID_VALUE"
cwsandbox get "$SANDBOX_ID"
cwsandbox get "$SANDBOX_ID" --output json
```

다음 예시에서는 이 변수를 사용합니다. 세부 정보에는 샌드박스 상태, 러너 정보, 시작 시간, 반환 코드(제공되는 경우)가 포함됩니다.

## 명령 실행

실행 중인 샌드박스에서 명령어를 실행합니다. 실행할 명령어는 샌드박스 이미지에 포함되어 있어야 합니다.

```bash theme={"system"}
cwsandbox exec "$SANDBOX_ID" echo hello
cwsandbox exec "$SANDBOX_ID" python -c "print('hello')"
```

원격 작업 디렉터리를 설정하려면 원격 명령어 앞에 `--cwd`를 지정하세요. `REMOTE_DIRECTORY`는 샌드박스에 이미 있는 디렉터리로 바꾸세요.

```bash theme={"system"}
cwsandbox exec "$SANDBOX_ID" --cwd "REMOTE_DIRECTORY" pwd
```

CLI는 표준 출력과 표준 오류를 로컬 터미널로 스트리밍합니다. 원격 명령어가 정상적으로 완료되면 CLI는 해당 명령어의 종료 코드를 반환하며 종료됩니다.

## 대화형 셸 열기

macOS 또는 Linux의 로컬 터미널에서 다음 명령을 실행하여 대화형 셸을 여세요.

```bash theme={"system"}
cwsandbox sh "$SANDBOX_ID"
```

기본 셸은 `/bin/bash`입니다. 다른 셸이나 샌드박스에 설치된 대화형 프로그램을 선택하려면 `--cmd`를 사용하세요.

```bash theme={"system"}
cwsandbox sh "$SANDBOX_ID" --cmd /bin/sh
cwsandbox sh "$SANDBOX_ID" --cmd "python -i"
```

대화형 셸을 사용하려면 표준 입력과 표준 출력이 모두 터미널이어야 하며, Windows에서는 지원되지 않습니다. 셸 세션을 종료하려면 `exit`를 입력하거나 `Ctrl+D`를 누르세요. `Ctrl+C`는 원격 프로세스로 전달됩니다.

## 로그 보기

샌드박스의 메인 프로세스에서 로그를 조회하세요.

```bash theme={"system"}
cwsandbox logs "$SANDBOX_ID" --tail 100
cwsandbox logs "$SANDBOX_ID" --tail 100 --timestamps
```

새 로그 출력을 스트리밍하려면 `--follow`를 사용하세요. 스트리밍을 중지하려면 `Ctrl+C`를 누르세요.

```bash theme={"system"}
cwsandbox logs "$SANDBOX_ID" --follow
```

타임스탬프를 기준으로 로그를 필터링하려면 `--since`를 사용하세요. `2026-09-10 09:00:00`을 원하는 시작 시간으로 바꾸세요. CLI는 시간대가 지정되지 않은 타임스탬프를 UTC로 해석합니다:

```bash theme={"system"}
cwsandbox logs "$SANDBOX_ID" --since "2026-09-10 09:00:00"
```

로그에는 메인 프로세스, 즉 샌드박스를 만들 때 사용한 명령어의 표준 출력과 표준 오류가 포함됩니다. `cwsandbox exec`의 출력은 포함되지 않습니다. 기본 keep-alive 명령어로 만든 샌드박스는 로그를 출력하지 않습니다.

로그는 샌드박스가 실행 중일 때만 조회할 수 있으므로 샌드박스를 중지하기 전에 조회하세요. 자세한 내용은 [샌드박스 로깅](https://docs.coreweave.com/ko/products/sandboxes/client/guides/logging.md)을 참조하세요.

## 파일 읽기 및 쓰기

파일 작업을 하려면 샌드박스가 실행 중이어야 합니다. 원격 파일의 내용을 표준 출력으로 출력하려면 `REMOTE_PATH`를 샌드박스 내부의 파일 경로로 바꾸세요.

```bash theme={"system"}
cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH"
```

파일을 다운로드하려면 `--output` 옵션에 로컬 저장 경로를 지정하세요. `LOCAL_PATH`를 파일을 저장할 경로로 바꾸세요.

```bash theme={"system"}
cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH" --output "LOCAL_PATH"
```

파일을 업로드하려면 원격 대상을 첫 번째 인수로, 기존 로컬 소스 파일을 두 번째 인수로 지정하세요.

```bash theme={"system"}
cwsandbox files write "$SANDBOX_ID" "REMOTE_PATH" "LOCAL_PATH"
```

## 파일 시스템 스냅샷 관리

스냅샷을 생성하려면 [파일 시스템 스냅샷 마운트](https://docs.coreweave.com/ko/products/sandboxes/file-system-snapshots.md#start-a-sandbox-with-a-snapshot-mount)가 설정된 샌드박스가 실행 중이어야 합니다. 또한 조직에 파일 시스템 스냅샷 기능이 활성화되어 있어야 합니다.

스냅샷 생성:

```bash theme={"system"}
cwsandbox snapshots create "$SANDBOX_ID"
```

이 명령어는 스냅샷이 준비 완료 상태가 될 때까지 기다린 후 스냅샷 ID를 출력합니다. 준비 상태를 기다리지 않고 바로 반환하면서 ID를 JSON 형식으로 출력하려면 다음 명령어를 사용하세요.

```bash theme={"system"}
cwsandbox snapshots create "$SANDBOX_ID" --no-wait --output json
```

스냅샷 목록을 조회하거나, 특정 샌드박스에서 생성된 스냅샷 중 준비 완료 상태인 스냅샷만 필터링하세요.

```bash theme={"system"}
cwsandbox snapshots list
cwsandbox snapshots list --source-sandbox-id "$SANDBOX_ID" --status ready
```

스냅샷을 조회하려면 `SNAPSHOT_ID_VALUE`를 해당 스냅샷의 ID로 바꾸세요:

```bash theme={"system"}
export SNAPSHOT_ID="SNAPSHOT_ID_VALUE"
cwsandbox snapshots get "$SNAPSHOT_ID"
cwsandbox snapshots get "$SNAPSHOT_ID" --output json
```

더 이상 필요하지 않은 스냅샷을 삭제하려면 다음 명령을 실행하세요.

```bash theme={"system"}
cwsandbox snapshots delete "$SNAPSHOT_ID"
```

스냅샷 요구 사항, 지원되는 저장소, SDK로 샌드박스를 복원하는 방법은 [파일 시스템 스냅샷](https://docs.coreweave.com/ko/products/sandboxes/file-system-snapshots.md)을 참조하세요.

## 샌드박스 중지 또는 삭제

샌드박스를 다 사용했으면 중지하세요.

```bash theme={"system"}
cwsandbox stop "$SANDBOX_ID"
```

정상 종료에 최대 30초를 허용하려면 다음 방법을 대신 사용하세요:

```bash theme={"system"}
cwsandbox stop "$SANDBOX_ID" --graceful-shutdown-seconds 30
```

파일 시스템 스냅샷 마운트가 설정된 샌드박스라면, 다음과 같은 대체 방법으로 중지하기 전에 스냅샷을 캡처하세요.

```bash theme={"system"}
cwsandbox stop "$SANDBOX_ID" --snapshot-on-stop
```

샌드박스를 삭제하려면 다음 명령을 실행하세요.

```bash theme={"system"}
cwsandbox delete "$SANDBOX_ID"
```

정리 스크립트에서는 `--missing-ok`를 사용해 이미 삭제된 샌드박스 때문에 오류가 발생하지 않도록 하세요:

```bash theme={"system"}
cwsandbox delete "$SANDBOX_ID" --missing-ok
```