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

# 환경 변수

> CoreWeave가 모든 샌드박스 내부에 설정하는 환경 변수와 이를 재정의하는 방법.

<Note>
  `auth`를 생략한 예시는 `CWSANDBOX_API_KEY`에 지정된 CoreWeave API 액세스 토큰을 사용합니다. Forge API 키로 인증하려면 [시작하기](/ko/products/sandboxes/get-started#forge-api-key)의 안내에 따라 생성한 `AuthHeaders`를 오퍼레이션에 전달하세요.
</Note>

이 페이지에서는 CoreWeave가 모든 샌드박스 내부에 설정하는 환경 변수와 샌드박스에서 실행되는 코드에서 이를 조회하는 방법을 설명합니다. 플랫폼은 사용자가 직접 지정한 변수와 함께 이러한 변수를 생성 시점에 설정하므로, 코드에서 자신의 런타임을 파악할 수 있습니다.

직접 변수를 설정하려면 [사용자 환경 변수 설정](/ko/products/sandboxes/client/guides/environment-variables)을 참조하세요.

<h2 id="variables">
  변수
</h2>

플랫폼은 모든 샌드박스에 다음 변수를 설정합니다:

| 변수 | 값 | 설명 |
| - | - | - |
| `CW_SANDBOX_ID` | UUID | 샌드박스 자체의 ID입니다. 샌드박스 생성 시 반환되는 ID 및 샌드박스에 작업을 수행하는 API와 SDK Call에 사용하는 ID와 동일합니다. |

플랫폼은 사용하는 SDK 또는 API 버전에 관계없이 이 변수를 설정합니다.

<Note>
  샌드박스 ID를 획득하기 위해 호스트 이름을 파싱하지 마세요. 샌드박스의 호스트 이름은 샌드박스 ID로 시작하지만, 기반 파드가 다시 시작되면 변경되는 자동 생성 접미사가 붙습니다. 대신 `CW_SANDBOX_ID`를 사용하세요.
</Note>

<h2 id="read-a-variable">
  변수 조회
</h2>

플랫폼 변수는 각 컨테이너의 메인 프로세스, 해당 프로세스가 시작하는 모든 프로세스, `exec` 및 스트리밍 실행으로 시작된 프로세스에서 사용할 수 있습니다. 단, 자식 프로세스를 시작하기 전에 환경을 비우는 프로그램은 예외입니다.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    import os

    sandbox_id = os.environ["CW_SANDBOX_ID"]
    print(f"running in sandbox {sandbox_id}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"system"}
    const sandboxId = process.env.CW_SANDBOX_ID;

    console.log(`running in sandbox ${sandboxId}`);
    ```
  </Tab>

  <Tab title="셸">
    ```bash theme={"system"}
    echo "$CW_SANDBOX_ID"
    ```
  </Tab>
</Tabs>

일반적인 활용 사례는 샌드박스 내부에서 생성되는 로그나 메트릭에 태그를 지정하여, 나중에 기록을 해당 기록을 생성한 샌드박스와 연결할 수 있도록 하는 것입니다.

<h2 id="override-a-variable">
  변수 재정의
</h2>

플랫폼 변수는 기본값이며, 예약된 이름이 아닙니다. 샌드박스에 같은 이름의 변수를 설정하면 샌드박스는 사용자가 지정한 값을 사용하고 플랫폼은 기본값을 적용하지 않습니다.

`[YOUR-VALUE]`를 샌드박스가 보고하도록 할 값으로 바꾸세요:

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    from cwsandbox import Sandbox

    sandbox = Sandbox.run(
        container_image="ubuntu:22.04",
        environment_variables={"CW_SANDBOX_ID": "[YOUR-VALUE]"},
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"system"}
    import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

    const client = createSandboxClientFromEnv();

    const sandbox = await client.create({
      containerImage: "ubuntu:22.04",
      environmentVariables: { CW_SANDBOX_ID: "[YOUR-VALUE]" },
    });
    ```
  </Tab>
</Tabs>

재정의에는 다음 규칙이 적용됩니다:

* **빈 문자열을 포함한 모든 값이 유효합니다.** `CW_SANDBOX_ID`를 `""`로 설정하면 존재하지만 값이 비어 있는 변수가 생성됩니다. 플랫폼은 빈 값을 미설정 상태로 간주하지 않으며 이를 대체하지 않습니다.

* **정책은 플랫폼 변수를 재정의할 수 없습니다.** 이 이름은 운영자의 설정에서 사용할 수 없도록 예약되어 있으므로, 클러스터의 [정책](/ko/products/sandboxes/profiles/configure)이 사용자가 설정한 값을 알리지 않고 대체할 수 없습니다.

* **시크릿도 재정의로 간주됩니다.** 같은 변수 이름에 매핑된 [시크릿](/ko/products/sandboxes/secrets)은 값을 직접 지정한 경우와 동일하게 플랫폼 기본값이 적용되지 않도록 합니다.

<h2 id="metadata-only-not-identity">
  ID가 아닌 메타데이터일 뿐입니다
</h2>

`CW_SANDBOX_ID`는 참고용 메타데이터입니다. 이 값은 재정의될 수 있으므로 샌드박스 내부의 코드가 임의의 값을 보고할 수 있습니다.

<Warning>
  `CW_SANDBOX_ID`를 인증, 권한 부여 또는 감사 귀속에 사용하지 마세요. 샌드박스를 생성할 때 사용자의 시스템에 샌드박스 ID가 이미 기록되어 있습니다. 샌드박스 내부에서 보고된 값이 아니라 이 ID를 신뢰할 수 있는 기준으로 삼으세요.
</Warning>

<h2 id="sandboxes-with-more-than-one-container">
  컨테이너가 두 개 이상인 샌드박스
</h2>

각 컨테이너는 `CW_SANDBOX_ID`를 직접 설정하지 않는 한 샌드박스의 첫 번째 컨테이너에 설정된 값을 받습니다. 값을 명시적으로 설정한 컨테이너에서는 해당 값이 우선 적용됩니다.

이에 따라 다음 두 가지 결과가 발생합니다:

* 첫 번째 컨테이너에서 변수를 재정의하면, 아무 값도 설정하지 않은 다른 모든 컨테이너는 재정의된 값을 받습니다.
* 첫 번째 컨테이너에서 변수를 빈 문자열로 재정의하면, 다른 컨테이너는 해당 변수를 아예 받지 않습니다.

<h2 id="behavior-across-the-sandbox-lifecycle">
  샌드박스 라이프사이클 전반의 동작
</h2>

`CW_SANDBOX_ID`는 샌드박스의 수명 동안 다음과 같이 동작합니다:

* **값은 샌드박스의 수명 동안 고정됩니다.** 플랫폼이 생성 시 값을 부여하며, 기반 파드가 다시 시작되어도 값은 변경되지 않습니다.
* **복원된 샌드박스는 새로운 샌드박스입니다.** 파일 시스템 스냅샷에서 복원하면 새 ID를 가진 샌드박스가 생성되며, `CW_SANDBOX_ID`에는 이 새 값이 들어갑니다. 애플리케이션이 스냅샷 볼륨에 기록한 이전 ID는 사용자 데이터로 유지되며 업데이트되지 않습니다.