CLI로 샌드박스 관리하기

cwsandbox 명령줄 인터페이스(CLI)를 사용하면 터미널에서 기존 CoreWeave 샌드박스를 관리할 수 있습니다. CLI로 샌드박스 검사, 명령어 실행, 로그 조회, 파일 전송, 파일 시스템 스냅샷 관리, 리소스 정리 등의 작업을 수행할 수 있습니다. CLI는 샌드박스 Python 클라이언트의 선택적 추가 기능(extra)으로 설치합니다. CLI를 사용하기 전에 먼저 SDK로 샌드박스를 생성하세요. 서버리스 퀵스타트 또는 자체 컴퓨팅 사용하기를 참고하여 샌드박스를 생성할 수 있습니다.

사전 요구 사항

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

uv가 설치된 활성화된 Python 3.11 이상 가상 환경
샌드박스를 소유한 계정의 사용자 인증 정보. 사용자 인증 정보 설정 방법과 필요한 역할은 사용자 인증 정보 선택 및 가져오기를 참조하세요.
명령어 실행, 대화형 셸, 로그 조회, 파일 작업, 스냅샷 생성에 사용할 실행 중인 샌드박스

설치 및 인증

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

Forge API 키
CoreWeave API 액세스 토큰

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

uv pip install --upgrade 'cwsandbox[cli,wandb]'
export WANDB_API_KEY="WANDB_API_KEY_VALUE"
export CWSANDBOX_AUTH="wandb"
cwsandbox --help

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

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 의존성과 사용자 인증 정보가 설정되어 있다면 다음과 같습니다.

cwsandbox --auth wandb ls

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

cwsandbox exec --help
cwsandbox files read --help
cwsandbox snapshots create --help

샌드박스 찾기

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

cwsandbox ls

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

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로 바꾼 다음, 터미널에서 다음과 같이 설정하세요.

export SANDBOX_ID="SANDBOX_ID_VALUE"
cwsandbox get "$SANDBOX_ID"
cwsandbox get "$SANDBOX_ID" --output json

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

명령 실행

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

cwsandbox exec "$SANDBOX_ID" echo hello
cwsandbox exec "$SANDBOX_ID" python -c "print('hello')"

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

cwsandbox exec "$SANDBOX_ID" --cwd "REMOTE_DIRECTORY" pwd

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

대화형 셸 열기

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

cwsandbox sh "$SANDBOX_ID"

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

cwsandbox sh "$SANDBOX_ID" --cmd /bin/sh
cwsandbox sh "$SANDBOX_ID" --cmd "python -i"

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

로그 보기

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

cwsandbox logs "$SANDBOX_ID" --tail 100
cwsandbox logs "$SANDBOX_ID" --tail 100 --timestamps

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

cwsandbox logs "$SANDBOX_ID" --follow

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

cwsandbox logs "$SANDBOX_ID" --since "2026-09-10 09:00:00"

로그에는 메인 프로세스, 즉 샌드박스를 만들 때 사용한 명령어의 표준 출력과 표준 오류가 포함됩니다. cwsandbox exec의 출력은 포함되지 않습니다. 기본 keep-alive 명령어로 만든 샌드박스는 로그를 출력하지 않습니다. 로그는 샌드박스가 실행 중일 때만 조회할 수 있으므로 샌드박스를 중지하기 전에 조회하세요. 자세한 내용은 샌드박스 로깅을 참조하세요.

파일 읽기 및 쓰기

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

cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH"

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

cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH" --output "LOCAL_PATH"

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

cwsandbox files write "$SANDBOX_ID" "REMOTE_PATH" "LOCAL_PATH"

파일 시스템 스냅샷 관리

스냅샷을 생성하려면 파일 시스템 스냅샷 마운트가 설정된 샌드박스가 실행 중이어야 합니다. 또한 조직에 파일 시스템 스냅샷 기능이 활성화되어 있어야 합니다. 스냅샷 생성:

cwsandbox snapshots create "$SANDBOX_ID"

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

cwsandbox snapshots create "$SANDBOX_ID" --no-wait --output json

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

cwsandbox snapshots list
cwsandbox snapshots list --source-sandbox-id "$SANDBOX_ID" --status ready

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

export SNAPSHOT_ID="SNAPSHOT_ID_VALUE"
cwsandbox snapshots get "$SNAPSHOT_ID"
cwsandbox snapshots get "$SNAPSHOT_ID" --output json

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

cwsandbox snapshots delete "$SNAPSHOT_ID"

스냅샷 요구 사항, 지원되는 저장소, SDK로 샌드박스를 복원하는 방법은 파일 시스템 스냅샷을 참조하세요.

샌드박스 중지 또는 삭제

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

cwsandbox stop "$SANDBOX_ID"

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

cwsandbox stop "$SANDBOX_ID" --graceful-shutdown-seconds 30

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

cwsandbox stop "$SANDBOX_ID" --snapshot-on-stop

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

cwsandbox delete "$SANDBOX_ID"

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

cwsandbox delete "$SANDBOX_ID" --missing-ok

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

CLI로 샌드박스 관리하기

사전 요구 사항

설치 및 인증

샌드박스 찾기

샌드박스 검사하기

명령 실행

대화형 셸 열기

로그 보기

파일 읽기 및 쓰기

파일 시스템 스냅샷 관리

샌드박스 중지 또는 삭제

​사전 요구 사항

​설치 및 인증

​샌드박스 찾기

​샌드박스 검사하기

​명령 실행

​대화형 셸 열기

​로그 보기

​파일 읽기 및 쓰기

​파일 시스템 스냅샷 관리

​샌드박스 중지 또는 삭제

사전 요구 사항

설치 및 인증

샌드박스 찾기

샌드박스 검사하기

명령 실행

대화형 셸 열기

로그 보기

파일 읽기 및 쓰기

파일 시스템 스냅샷 관리

샌드박스 중지 또는 삭제