> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-run-filter-ui-updates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 샌드박스 라이프사이클

> 상태, 상태 변경을 기다리는 방법, 샌드박스를 중지하는 방법을 포함하여 Serverless 샌드박스의 라이프사이클에 대해 알아보세요.

<Warning>
  Serverless Sandboxes는 공개 프리뷰입니다.
</Warning>

Serverless 샌드박스는 라이프사이클 동안 여러 상태를 거칩니다. 샌드박스의 상태에 따라 사용 가능한 오퍼레이션이 결정됩니다.

대부분의 경우 샌드박스는 `PENDING` 상태에서 시작하고, container가 프로비저닝되는 동안 `CREATING` 상태로 이동한 다음, 사용할 준비가 되면 `RUNNING` 상태가 됩니다.

메인 명령과 함께 샌드박스를 시작하면 해당 명령이 샌드박스의 메인 프로세스가 됩니다. 메인 프로세스가 종료되면 샌드박스는 `COMPLETED`(종료 코드 `0`) 또는 `FAILED`(시작 또는 실행 중 오류)와 같은 종료 상태로 들어갑니다. 샌드박스는 외부에서 중지되거나 최대 수명을 초과한 경우 `TERMINATED` 상태가 될 수도 있습니다.

```text theme={null}
PENDING -> CREATING -> RUNNING -> COMPLETED
                               -> FAILED
                               -> TERMINATED
```

다음 섹션에서는 샌드박스 상태, 준비 완료 또는 완료될 때까지 기다리는 방법, 그리고 샌드박스를 중지하는 방법을 설명합니다. 샌드박스를 생성하고 명령을 실행하는 방법에 대한 자세한 내용은 [샌드박스 만들기](/ko/sandboxes/create-sandbox) 및 [명령 실행](/ko/sandboxes/run-commands)을 참조하세요.

<div id="sandbox-states">
  ## 샌드박스 상태
</div>

다음 표는 샌드박스의 상태를 요약합니다:

| State      | Description                              |
| ---------- | ---------------------------------------- |
| PENDING    | 샌드박스 요청이 접수되었으며 스케줄링을 기다리고 있습니다.         |
| CREATING   | container를 프로비저닝하는 중입니다.                 |
| RUNNING    | 샌드박스가 오퍼레이션을 수행할 준비가 되었습니다.              |
| COMPLETED  | 메인 프로세스가 종료 코드 0으로 성공적으로 종료되었습니다.        |
| FAILED     | 샌드박스 또는 메인 프로세스에서 시작 또는 실행 중 오류가 발생했습니다. |
| TERMINATED | 샌드박스가 외부에서 중지되었거나 최대 수명을 초과하여 종료되었습니다.   |

대부분의 오퍼레이션을 수행하려면 샌드박스가 RUNNING 상태여야 합니다. 하지만 많은 오퍼레이션은 계속 진행하기 전에 샌드박스가 준비될 때까지 자동으로 대기합니다.

샌드박스가 종료 상태에 들어가면 추가 작업에 더 이상 사용할 수 없습니다.

<div id="wait-for-readiness-or-completion">
  ## 준비 완료 또는 완료 시점까지 기다리기
</div>

필요에 따라 서로 다른 대기 방법을 사용하세요:

* `Sandbox.wait()`를 사용하여 [샌드박스를 사용할 수 있을 때까지 기다리세요](/ko/sandboxes/lifecycle#wait-for-a-sandbox-to-start).
* `Sandbox.wait_until_complete()`를 사용하여 [샌드박스의 메인 프로세스가 끝날 때까지 기다리세요](/ko/sandboxes/lifecycle#wait-for-a-sandbox-to-complete).

<div id="wait-for-a-sandbox-to-start">
  ### 샌드박스가 시작될 때까지 기다리기
</div>

`Sandbox.wait()`를 사용하면 샌드박스가 RUNNING 상태에 도달할 때까지 명시적으로 기다릴 수 있습니다. 이 방법은 시작 문제를 디버깅하거나, 시작 실패와 이후 명령에서 발생하는 오류를 구분하려는 경우에 유용합니다.

예를 들어, 다음 코드는 샌드박스를 생성하고, 준비될 때까지 기다린 다음 명령을 실행합니다.

```python theme={null}
import wandb
from wandb.sandbox import Sandbox

with Sandbox.run() as sandbox:
    sandbox.wait()  # 샌드박스가 실행될 때까지 대기
    result = sandbox.exec(["python", "-c", "print('hello from sandbox')"]).result()
    print(result.stdout)
```

<div id="wait-for-a-sandbox-to-complete">
  ### 샌드박스 완료까지 기다리기
</div>

샌드박스의 메인 프로세스가 전체 워크로드를 담당하고 해당 작업이 완료될 때까지 기다리려는 경우 [`Sandbox.wait_until_complete()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#wait_until_complete)를 사용하세요.

```python theme={null}
from wandb.sandbox import Sandbox

sandbox = Sandbox.run("python", "train.py")
sandbox.wait_until_complete(timeout=3600.0).result()  # 메인 프로세스가 종료되거나 타임아웃에 도달할 때까지 블로킹
print(f"Exit code: {sandbox.returncode}")
```

이 패턴은 `Sandbox.run("python", "train.py")`와 같은 메인 명령로 샌드박스를 시작하고, 샌드박스의 라이프사이클이 해당 명령의 실행에 맞춰지도록 하려는 경우에 유용합니다.

메인 프로세스가 종료되면 샌드박스는 종료 상태에 들어갑니다. 성공적인 run은 일반적으로 COMPLETED로 끝납니다. 프로세스가 실패하면 샌드박스는 FAILED 상태에 들어갈 수 있습니다.

대신 명령을 대화형으로 실행해야 하는 경우 `Sandbox.exec()`와 함께 컨텍스트 관리자를 사용하세요:

```python theme={null}
from wandb.sandbox import Sandbox

with Sandbox.run() as sandbox:
    result = sandbox.exec(["python", "train.py"]).result()
    print(result.stdout)
# 종료 시 샌드박스 자동 중지
```

<div id="explicit-lifecycle-control">
  ## 명시적 라이프사이클 제어
</div>

샌드박스의 라이프사이클을 명시적으로 제어해야 할 때는 `Sandbox.wait()` 및 `Sandbox.stop()`과 같은 방법을 사용하세요.

대부분의 경우 이러한 방법을 직접 호출할 필요는 없습니다. `Sandbox.exec()`, `Sandbox.read_file()`, `Sandbox.write_file()`와 같은 오퍼레이션은 준비될 때까지 자동으로 기다리며, 컨텍스트 관리자(`with Sandbox.run() as sandbox:`)는 블록을 벗어날 때 샌드박스를 자동으로 중지합니다.

<div id="stop-a-sandbox">
  ### 샌드박스 중지
</div>

샌드박스가 더 이상 필요 없거나, 오래 실행 중인 프로세스를 종료하려거나, 샌드박스가 최대 수명에 도달하기 전에 리소스를 정리해야 할 때는 [`Sandbox.stop()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#stop)를 사용하세요.

```python theme={null}
from wandb.sandbox import Sandbox

sandbox = Sandbox.run("sleep", "infinity")

# ... 샌드박스를 사용합니다 ...

sandbox.stop().result()
```

추가 옵션으로 종료 방식을 제어할 수도 있습니다:

```python theme={null}
from wandb.sandbox import Sandbox

with Sandbox.run("sleep", "infinity") as sandbox:
    sandbox.stop(
        graceful_shutdown_seconds=30.0,  # 샌드박스를 강제 종료하기 전에 대기합니다.
        missing_ok=True,                 # 이미 중지된 경우 오류를 발생시키지 않습니다.
    ).result()
```