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

# Sessions

> Group and manage multiple sandboxes with sessions.

이 예시에서는 `CWSANDBOX_API_KEY`에 설정한 CoreWeave API 액세스 토큰을 사용합니다. Forge API 키 인증은 [시작하기](/ko/products/sandboxes/get-started)를 참조하세요. CKS 요구 사항은 [배치 모드](/ko/products/sandboxes/placement)를 참조하세요.

이 가이드에서는 `Session`을 사용하여 공유 설정을 사용하는 여러 샌드박스를 관리하는 방법을 설명합니다. 샌드박스 그룹을 조율하고, 공통 기본값을 적용하며, 워크로드 전체에서 일관된 정리를 보장해야 하는 클라이언트 개발자를 위한 가이드입니다.

<h2 id="session-overview">
  세션 개요
</h2>

`Session`은 다음을 제공합니다:

* 모든 샌드박스에 대한 공유 기본 설정.
* 세션이 닫힐 때 자동 정리.
* `@session.function()` 데코레이터를 위한 범위.

<h2 id="basic-usage">
  기본 사용
</h2>

```python theme={"system"}
import cwsandbox
from cwsandbox import SandboxDefaults

# 공유 설정을 정의합니다
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("project-alpha",),
)

# 컨텍스트 관리자로 세션을 생성합니다
with cwsandbox.Session(defaults=defaults) as session:
    # 세션을 통해 샌드박스를 생성합니다
    sb1 = session.sandbox()
    sb2 = session.sandbox()

    # 샌드박스를 사용합니다
    result1 = sb1.exec(["echo", "sandbox 1"]).result()
    result2 = sb2.exec(["echo", "sandbox 2"]).result()

# 컨텍스트를 벗어나면 모든 샌드박스가 자동으로 중단됩니다
```

<h2 id="create-sandboxes">
  샌드박스 만들기
</h2>

다음 섹션에서는 세션을 통해 샌드박스를 만들고 세션 기본값을 재정의하는 방법을 설명합니다.

<h3 id="sessionsandbox">
  session.sandbox()
</h3>

세션 기본값으로 샌드박스를 생성합니다. 샌드박스는 처음 사용할 때까지 시작되지 않습니다:

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    # sandbox()는 아직 시작되지 않은 샌드박스를 반환합니다
    sandbox = session.sandbox()

    # 오퍼레이션을 처음 사용하면 샌드박스가 자동으로 시작됩니다
    result = sandbox.exec(["echo", "hello"]).result()
```

시작 RPC가 호출되는 시점을 명시적으로 제어하려면:

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    sandbox = session.sandbox()
    sandbox.start().result()  # 명시적으로 시작
    sandbox.wait()            # RUNNING 상태가 될 때까지 대기
    result = sandbox.exec(["echo", "hello"]).result()
```

<h3 id="override-defaults">
  기본값 재정의
</h3>

추가 인수를 전달하여 세션 기본값을 재정의하세요:

```python theme={"system"}
from cwsandbox import ResourceOptions

# 기본 설정을 사용하는 세션
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project",),
)

with cwsandbox.Session(defaults=defaults) as session:
    # 이 샌드박스의 이미지와 리소스 재정의
    gpu_sandbox = session.sandbox(
        command="sleep",
        args=["infinity"],
        container_image="pytorch/pytorch:latest",
        resources=ResourceOptions(
            requests={"cpu": "4", "memory": "16Gi"},
            limits={"cpu": "8", "memory": "32Gi"},
            gpu={"count": 1},
        ),
        tags=["gpu-workload"],  # 세션 태그와 병합됨
    )
```

사용 가능한 모든 옵션은 [샌드박스 설정 가이드](/ko/products/sandboxes/client/guides/sandbox-configuration)를 참조하세요.

<h2 id="multiple-sandbox-management">
  여러 샌드박스 관리
</h2>

세션은 샌드박스 풀을 관리하는 데 잘 맞습니다:

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    # 샌드박스 풀 생성
    sandboxes = [
        session.sandbox()
        for _ in range(5)
    ]

    # 풀 전체에 작업 분배
    processes = [
        sb.exec(["python", "-c", f"print({i})"])
        for i, sb in enumerate(sandboxes)
    ]

    # 결과 수집
    results = [p.result() for p in processes]

# 샌드박스 5개 모두 자동으로 정리됨
```

요청이 들어오기 전에 샌드박스를 미리 준비하려면
[웜 풀 구현](/ko/products/sandboxes/warm-pools)을 참조하세요.
이 레시피는 준비 완료 상태의 샌드박스를 버퍼에 확보해 두고, 각 워크로드에 별도의
샌드박스를 할당하며, 워크로드가 샌드박스를 클레임할 때마다 버퍼를 다시 채웁니다.

<h2 id="session-lifecycle">
  세션 라이프사이클
</h2>

다음 섹션에서는 세션을 닫는 방법, `close()`의 동작, 오류 처리 방법을 설명합니다.

<h3 id="manual-close">
  수동 종료
</h3>

컨텍스트 관리자를 사용하지 않는 경우 세션을 명시적으로 종료하세요:

```python theme={"system"}
session = cwsandbox.Session(defaults=defaults)

sandbox = session.sandbox()
result = sandbox.exec(["echo", "hello"]).result()

# 세션을 닫습니다(모든 샌드박스 중지)
session.close().result()
```

<h3 id="what-close-does">
  close()가 수행하는 작업
</h3>

`close()`를 호출하면 다음 작업을 수행합니다:

1. 세션을 통해 생성되었거나 세션 관리에 편입된 모든 샌드박스를 중지합니다.
2. 정리 작업이 완료될 때까지 기다립니다.
3. `OperationRef[None]` 반환값.

<h3 id="error-handling">
  오류 처리
</h3>

예외가 발생해도 세션은 정리됩니다:

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    sandbox = session.sandbox()
    raise RuntimeError("Something went wrong!")
# 샌드박스는 예외가 발생해도 정리됩니다
```

<h2 id="adopt-external-sandboxes">
  외부 샌드박스를 세션 관리에 포함하기
</h2>

세션 외부에서 생성된 샌드박스를 세션 관리에 포함하세요:

```python theme={"system"}
import cwsandbox
from cwsandbox import Sandbox

with cwsandbox.Session(defaults=defaults) as session:
    # 기존 샌드박스 찾기
    existing = Sandbox.list(tags=["orphaned-work"]).result()

    # 정리할 수 있도록 세션 관리에 편입
    for sandbox in existing:
        session.adopt(sandbox)

    # 이제 session.close()가 이 샌드박스도 정리합니다
```

<h2 id="session-properties">
  세션 속성
</h2>

`sandbox_count`와 같은 기본 제공 속성으로 세션 상태를 확인하세요:

```python theme={"system"}
session = cwsandbox.Session(defaults=defaults)

# 추적 중인 샌드박스 수
print(session.sandbox_count)  # 0

sandbox = session.sandbox()
print(session.sandbox_count)  # 1
```

<h2 id="when-to-use-sessions">
  세션을 사용해야 하는 경우
</h2>

| 사용 사례 | 권장 방식 |
| - | - |
| 단일 샌드박스, 단순한 작업 | 컨텍스트 관리자와 함께 `Sandbox.run()` 사용 |
| 여러 샌드박스, 공유 설정 | 세션 |
| 함수 데코레이터 API | 세션 필수 |
| 워커 풀 | 세션 |
| 일회성 명령 | `Sandbox.run()` 직접 사용 |

<h2 id="without-sessions">
  세션 없이 사용하기
</h2>

단일 샌드박스에는 세션이 필요하지 않습니다:

```python theme={"system"}
from cwsandbox import Sandbox

# 세션 없이 직접 사용
with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
# 컨텍스트 관리자가 정리 작업 처리
```