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

# Direct sandbox connections

> Route exec, log, and file operations over a direct mTLS connection instead of the gateway.

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

직접 샌드박스 연결은 클라이언트에서 샌드박스로 exec, 로깅, 파일 오퍼레이션을 mutual TLS(mTLS)를 통해 직접 전달하며, CoreWeave Sandboxes 게이트웨이를 거치지 않습니다. 게이트웨이 홉을 제거하면 샌드박스 안팎으로 대량의 데이터를 주고받는 워크로드의 지연 시간이 줄고 처리량이 늘어납니다.

샌드박스 시작, 샌드박스 목록 조회, 중지와 같은 라이프사이클 및 관리 오퍼레이션은 항상 CoreWeave Sandboxes API를 사용합니다. 직접 연결은 이미 실행 중인 샌드박스의 데이터 오퍼레이션에만 적용됩니다.

이 페이지는 `cwsandbox` Python SDK를 사용하여 샌드박스를 시작하고 관리하는 개발자를 위한 내용입니다. 데이터 오퍼레이션에 대한 전송 정책 선택 방법, SDK가 직접 연결을 설정하는 방식, 그리고 오퍼레이션이 어떤 전송 방식을 사용했는지 확인하는 방법을 설명합니다.

<h2 id="overview">
  개요
</h2>

`DataPlaneMode` 열거형은 데이터 오퍼레이션의 전송 정책을 설정합니다. SDK는 달리 선택하지 않는 한 `AUTO`를 사용하므로 대부분의 호출자는 코드를 변경하지 않고도 직접 연결을 얻을 수 있습니다.

| Mode | Behavior | When to use it |
| - | - | - |
| `AUTO` | 직접 mTLS 연결을 선호하며 직접 액세스를 사용할 수 없을 때 게이트웨이로 투명하게 대체합니다. | 기본값입니다. 특정 전송을 고정해야 하는 경우가 아니면 사용하세요. |
| `DIRECT` | 직접 mTLS 연결을 요구하며 설정할 수 없을 때 예외를 발생시킵니다. | 환경에서 직접 연결이 작동하는지 검증할 때 사용합니다. |
| `GATEWAY` | 항상 데이터 오퍼레이션을 게이트웨이를 통해 라우팅합니다. | 직접 전송을 배제해야 할 때 결정론적 롤백 경로입니다. |

<h2 id="set-the-transport-policy">
  전송 정책 설정
</h2>

단일 샌드박스의 전송 정책을 설정하려면 `Sandbox.run()`에 `data_plane_mode`를 전달하세요. 샌드박스 그룹의 전송 정책을 설정하려면 `SandboxDefaults`에 `data_plane_mode`를 전달하세요.

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

# AUTO가 기본값입니다. 직접 연결을 우선 사용하고, 불가능하면 게이트웨이로 전환합니다.
with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
    print(result.stdout)

# 직접 연결 경로를 필수로 사용합니다. 연결 상태를 검증할 때 유용합니다.
with Sandbox.run(data_plane_mode=DataPlaneMode.DIRECT) as sandbox:
    print(sandbox.read_file("/etc/hostname").result().decode())

# 이 기본 설정을 사용하는 모든 샌드박스에 게이트웨이 경로를 강제합니다.
defaults = SandboxDefaults(data_plane_mode=DataPlaneMode.GATEWAY)
with Sandbox.run(defaults=defaults) as sandbox:
    print(sandbox.exec(["echo", "gateway"]).result().stdout)
```

<h2 id="how-a-direct-connection-is-established">
  직접 연결이 설정되는 방식
</h2>

샌드박스가 실행 중인 상태에서 첫 번째 데이터 오퍼레이션을 수행하면, SDK는 메모리에 P-256 개인 키를 생성하고 CoreWeave Sandboxes API에 인증서 서명 요청만 전송합니다. API는 해당 샌드박스에서만 사용할 수 있는 인증서를 반환하며, SDK는 이를 사용하여 샌드박스 자체에 mTLS 연결을 설정합니다.

자격 증명을 이해할 때 이 교환 과정에서 중요한 점은 다음 두 가지입니다.

* 개인 키는 클라이언트 프로세스 외부로 절대 전달되지 않습니다. SDK는 키가 아닌 인증서 서명 요청을 전송합니다.
* API Bearer 토큰은 샌드박스 데이터 엔드포인트로 절대 전송되지 않습니다. 샌드박스는 인증서만으로 클라이언트를 인증합니다.

SDK는 자격 증명이 필요할 때만 생성하므로, 라이프사이클 호출만 수행하는 샌드박스는 자격 증명을 요청하지 않습니다. SDK는 자체적으로 더 짧은 세션 유효 기간을 적용하지 않고, 서버가 발급한 인증서의 만료 시간을 사용합니다.

<h2 id="timing-and-fallback">
  대기 시간 및 폴백
</h2>

`AUTO`와 `DIRECT`는 대기 시간과 설정이 제한 시간 내에 완료되지 않았을 때의 동작이 다릅니다.

* `AUTO`에서는 자격 증명 발급과 채널 준비에 총 1초의 제한 시간이 적용됩니다. 이 시간이 지나면 오퍼레이션은 게이트웨이를 통해 진행되며 SDK는 30초를 기다린 후 다시 직접 연결을 시도합니다. 폴백은 사용자 개입 없이 이루어지며 오퍼레이션은 정상적으로 성공합니다.
* `DIRECT`에서는 연결 설정에 최대 10초가 주어지며 폴백은 지원되지 않습니다. 설정이 완료되지 않으면 오퍼레이션에서 오류가 발생합니다.

<h2 id="connection-reuse">
  연결 재사용
</h2>

SDK는 프로세스 전체에서 공유하는 유휴 직접 채널 풀을 유지하며, 최대 64개로 제한합니다. 풀 크기를 제한하면 비활성 샌드박스 객체로 이루어진 대규모 컬렉션을 보유한 프로그램이 샌드박스마다 소켓을 하나씩 유지하지 않습니다.

활성 스트림은 시작 시 사용한 채널을 계속 사용합니다. 채널이 오래된 것으로 표시되면 기존 스트림은 해당 채널에서 처리를 마무리하고, 새로운 Call은 대체 채널을 생성합니다.

<h2 id="verify-which-transport-an-operation-used">
  오퍼레이션이 사용한 전송 방식 확인
</h2>

환경에서 직접 연결이 작동하는지 확인하려면 `DIRECT` 모드에서 오퍼레이션을 실행하세요. 이 모드는 대체 경로로 전환하지 않으므로 성공적으로 반환된 오퍼레이션은 직접 전송 방식을 사용한 것입니다. 연결을 설정할 수 없는 오퍼레이션은 게이트웨이를 자동으로 사용하는 대신 오류를 발생시킵니다.

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

with Sandbox.run(data_plane_mode=DataPlaneMode.DIRECT) as sandbox:
    result = sandbox.exec(["echo", "direct"]).result()
    print(result.stdout)
```

이 작업이 예외를 발생시키는 동안 `GATEWAY` 아래의 동일한 call이 성공한다면, 샌드박스 데이터 endpoint가 네트워크에서 도달할 수 없는 것입니다. 호출자를 `AUTO`에 유지하여 게이트웨이를 통해 계속 작동하게 하고, 클라이언트와 샌드박스 사이의 egress 제한을 확인하세요.

<h2 id="see-also">
  참고 항목
</h2>

* [샌드박스 아키텍처](/ko/products/sandboxes/architecture): 제어 영역, 게이트웨이, 러너가 함께 작동하는 방식.

* [실행](/ko/products/sandboxes/client/guides/execution): 샌드박스에서 명령어 실행.

* [파일 오퍼레이션](/ko/products/sandboxes/client/guides/file-operations): 샌드박스에서 파일 읽기 및 쓰기.

* [샌드박스 설정](/ko/products/sandboxes/client/guides/sandbox-configuration): `SandboxDefaults`와 `Sandbox.run()`을 통해 설정할 수 있는 기타 옵션.