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

# Protobuf

> CoreWeave Sandboxes Protobuf 정의, 각 서비스를 제공하는 호스트, 생성된 SDK를 확인하세요.

CoreWeave Sandboxes API의 Protobuf 정의는 Buf 모듈 [`buf.build/coreweave/sandbox`](https://buf.build/coreweave/sandbox)에서 확인할 수 있습니다. CoreWeave 공식 클라이언트가 없는 언어로 통합하거나, [Python 클라이언트](/ko/products/sandboxes/client) 또는 TypeScript 클라이언트(`@coreweave/cwsandbox`)에서 제공하지 않는 RPC가 필요할 때 이 정의를 사용하세요.

[모듈 페이지](https://buf.build/coreweave/sandbox)는 API 자체에 대한 레퍼런스로, 모든 서비스와 필드, JSON 인코딩 규칙, 오류 규약을 설명합니다. 새로 통합할 때는 `coreweave.sandbox.v1`을 사용하세요. 이전 버전인 `coreweave.sandbox.v1beta2` 패키지는 기존 클라이언트를 위해 계속 제공되며, 프로필 템플릿과 러너 등록 기능도 포함되어 있습니다.

<h2 id="endpoints">
  엔드포인트
</h2>

모든 RPC는 [Connect 프로토콜](https://connectrpc.com/)로 제공되며, 동일한 엔드포인트에서 gRPC 및 gRPC-Web 클라이언트 요청도 처리합니다. `v1` 서비스는 두 호스트에 나뉘어 제공되며, 직접 연결을 위한 샌드박스별 엔드포인트가 별도로 있습니다.

| 호스트 | 제공 서비스 |
| - | - |
| `https://api.cwsandbox.com` | `SandboxService`, `DiscoveryService`, `VolumeService`, `NetworkService`, `SettingsService`. |
| `https://api.coreweave.com` | `RunnerManagementService` 및 `SandboxTemplateService`. `PlacementOrgConfigService`도 이 호스트에서 제공되지만 플랫폼 Operator 전용입니다. [API 개요](/ko/products/sandboxes/reference/control-plane-api)를 참조하세요. |
| 샌드박스별 데이터 영역 엔드포인트 | `SandboxDataPlaneService`. `SandboxService.ConnectSandbox`는 엔드포인트 URI, 단기 클라이언트 인증서, 신뢰 번들을 반환합니다. [샌드박스 직접 연결](/ko/products/sandboxes/client/guides/direct-connections)을 참조하세요. |

`NetworkService`는 아직 사용할 수 없으며, 모든 RPC가 `UNIMPLEMENTED`를 반환합니다. 또한 모든 RPC가 모든 조직이나 [배치 모드](/ko/products/sandboxes/placement#compare-placement-modes)에서 활성화되어 있지는 않습니다. 사용할 수 없는 호출은 사유 `CWSANDBOX_NOT_IMPLEMENTED`와 함께 `UNIMPLEMENTED`를 반환합니다.

요청은 CoreWeave API 액세스 토큰으로 인증합니다. 토큰을 생성하고 `SANDBOX_USER` 또는 `SANDBOX_ADMIN` IAM 액션을 부여하는 방법은 [인증](/ko/products/sandboxes/reference/control-plane-api#authentication)을 참조하세요.

<h2 id="install-a-generated-sdk">
  생성된 SDK 설치
</h2>

Buf Schema Registry는 요청 시 해당 모듈의 SDK를 빌드합니다. 다음 명령어를 사용하면 자주 쓰이는 언어 및 플러그인 조합을 설치할 수 있습니다.

```bash title="Install a generated SDK" theme={"system"}
# Go: Connect 클라이언트 및 메시지 유형
go get buf.build/gen/go/coreweave/sandbox/connectrpc/go@latest
go get buf.build/gen/go/coreweave/sandbox/protocolbuffers/go@latest

# Python: 메시지 유형 및 gRPC 스텁
pip install coreweave-sandbox-protocolbuffers-python coreweave-sandbox-grpc-python \
  --extra-index-url https://buf.build/gen/python

# TypeScript: 메시지 유형(@connectrpc/connect와 함께 사용)
npm config set @buf:registry https://buf.build/gen/npm/v1/
npm install @buf/coreweave_sandbox.bufbuild_es
```

그 밖의 언어 및 플러그인 조합은 모듈 페이지의 [SDKs 탭](https://buf.build/coreweave/sandbox/sdks)을 참조하세요. 코드를 로컬에서 직접 생성하려면 `buf generate`에 모듈을 지정하세요: `buf generate buf.build/coreweave/sandbox`.

<h2 id="see-also">
  참조
</h2>

* [샌드박스 아키텍처](/ko/products/sandboxes/architecture): 게이트웨이가 런타임 요청을 중개하는 방식과 컨트롤 플레인 및 데이터 영역의 분리 구조를 설명합니다.
* [API 개요](/ko/products/sandboxes/reference/control-plane-api): 컨트롤 플레인의 인증, 페이지 매김, 필드 마스크, 오류 처리를 설명합니다.
* [샌드박스 Python 클라이언트](/ko/products/sandboxes/client): 이 API를 기반으로 구축된 상위 수준 클라이언트인 `cwsandbox`를 소개합니다.
* [샌드박스 직접 연결](/ko/products/sandboxes/client/guides/direct-connections): 클라이언트가 상호 TLS(mTLS)를 통해 `SandboxDataPlaneService`에 연결하는 방법을 설명합니다.