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

# Forge シークレットを使用する

> Python または TypeScript を使用して、サーバーレスキャパシティ上のサンドボックスに Forge チームシークレットを注入します。

Forge Secret Manager を使用すると、サーバーレスキャパシティ上のサンドボックス内で API トークンなどの認証情報を利用できるようになります。アプリケーションからシークレット名を Sandboxes API に渡すと、API はサンドボックスの作成時に Forge チームから値を取得し、環境変数として注入します。

<h2 id="before-you-begin">
  始める前に
</h2>

Forge のシークレット注入を使用するには、Forge APIキーで認証されたサンドボックスが必要です。この機能はサーバーレスのサンドボックスで利用できますが、お客様自身の CoreWeave Kubernetes Service (CKS) クラスター上のサンドボックスでは利用できません。CKS への配置では CoreWeave API アクセストークンを使用します。このトークンと別途用意した Forge APIキーを組み合わせて、CKS サンドボックスのシークレットを解決することはできません。

| サンドボックスの配置 | サンドボックスの認証情報 | Forge のシークレット注入 |
| - | - | - |
| サーバーレス | Forge APIキー | サポートされています。`wandb` ストアを使用します。 |
| サーバーレス | CoreWeave API アクセストークン | サポートされていません。 |
| お客様の CKS クラスター | CoreWeave API アクセストークン | サポートされていません。`FORGE_API_KEY` を追加しても有効にはなりません。 |

例を実行するには、以下が必要です。

* [サーバーレスサンドボックスへのアクセス](/ja/products/sandboxes/get-started)権を持つ Forge の SaaS (Software as a Service) アカウント。
* Forge チームの Secret Manager に登録された `HF_TOKEN` という名前のシークレット。このシークレットが存在しない場合は、Forge の管理者に[シークレットの追加](/ja/products/wandb/platform/secrets#add-a-secret)を依頼してください。
* そのチームへのアクセス権を持つ Forge APIキー。

サンドボックスを作成するプロセスの環境で `FORGE_API_KEY` を設定します。`[FORGE-API-KEY]` はお使いの Forge APIキーに置き換えてください。

```bash theme={"system"}
export FORGE_API_KEY="[FORGE-API-KEY]"
```

`FORGE_TEAM` を設定しない場合、各例では APIキーのデフォルトのチームが使用されます。シークレットが別のチームに属している場合は、`FORGE_TEAM` にそのチームを設定してください。`[FORGE-TEAM]` はチーム名に置き換えてください。

```bash theme={"system"}
export FORGE_TEAM="[FORGE-TEAM]"
```

例では、これらの変数をクライアントに明示的に渡しています。SDK は `FORGE_API_KEY` や `FORGE_TEAM` を自動的には検出しません。

使用する言語に対応したクライアントをインストールします。

<Tabs>
  <Tab title="Python">
    Python 3.11 以降を使用し、必要に応じて [`uv` をインストール](https://docs.astral.sh/uv/getting-started/installation/)します。Python 環境にクライアントをインストールします。

    ```bash theme={"system"}
    uv pip install 'cwsandbox>=1.14.2'
    ```
  </Tab>

  <Tab title="TypeScript">
    Node.js 22 以降を使用します。TypeScript クライアントと、例の実行に使用する `tsx` をインストールします。

    ```bash theme={"system"}
    npm install @coreweave/cwsandbox
    npm install --save-dev tsx
    ```

    実行する TypeScript の例を `secrets.mts` として保存し、`npx tsx secrets.mts` を実行します。
  </Tab>
</Tabs>

<h2 id="inject-a-secret">
  シークレットを注入する
</h2>

Python では `store="wandb"`、TypeScript では `store: "wandb"` を使用します。このストアは、認証済みの Forge チームのシークレットを解決します。この手順では、組織のシークレットストアを登録する必要はありません。

以下のサンプルでは、`HF_TOKEN` を注入し、値を出力せずに存在を確認します。サンドボックス内では、環境変数名はデフォルトでシークレット名になります。

<Tabs>
  <Tab title="Python">
    Forge のAPIキーと、必要に応じてチームを `AuthHeaders` で渡します。

    ```python theme={"system"}
    import os
    from cwsandbox import AuthHeaders, Sandbox, Secret

    forge_auth = AuthHeaders(
        headers={
            "x-wandb-api-key": os.environ["FORGE_API_KEY"],
            **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
        },
        strategy="wandb_api_key",
    )

    with Sandbox.run(
      auth=forge_auth,
      placement_mode="serverless",
      container_image="python:3.11",
      resources={"cpu": "1", "memory": "1Gi"},
      secrets=[Secret(store="wandb", name="HF_TOKEN")],
    ) as sandbox:
      result = sandbox.exec([
        "python", "-c",
        "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
      ]).result()
      print(result.stdout)
    ```
  </Tab>

  <Tab title="TypeScript">
    Forge エントリポイントからクライアントをインポートします。`runnerIds` を省略すると、クライアントはサーバーレスの配置を使用します。

    ```typescript theme={"system"}
    import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

    const client = createSandboxClient({
      apiKey: process.env.FORGE_API_KEY,
      entity: process.env.FORGE_TEAM,
    });

    const result = await client.withSandbox(
      async (sandbox) => sandbox.commands.run([
        "python", "-c",
        "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
      ]),
      {
        containerImage: "python:3.11",
        resources: { cpu: "1", memory: "1Gi" },
        secrets: [{ store: "wandb", name: "HF_TOKEN" }],
      },
    );

    console.log(result.stdout);
    ```
  </Tab>
</Tabs>

どちらのサンプルも `Secret is available` を出力し、操作が完了するとサンドボックスを停止します。サンドボックス内で実行されるコードは、`HF_TOKEN` から値を読み取れます。

`secrets` には、シークレットの値ではなく名を渡してください。サーバーが値を解決します。値を出力したり、ログに書き込んだりしないでください。

<h2 id="secret-reference-fields">
  シークレット参照フィールド
</h2>

Python の `Secret` または TypeScript の `secrets` エントリで、次のフィールドを使用します:

| Python フィールド | TypeScript フィールド | 必須 | 説明 |
| - | - | - | - |
| `store` | `store` | はい | シークレットストア名。Forge Secret Manager には `wandb` を使用します。 |
| `name` | `name` | はい | 選択した Forge チームの Secret Manager にあるシークレットの名。 |
| `field` | `field` | いいえ | 値が JSON オブジェクトであるシークレットから選択するトップレベルキー。シークレットの値全体を注入するには省略します。 |
| `env_var` | `envVar` | いいえ | 値を受け取る環境変数。デフォルトは `name` です。 |

<h2 id="use-a-custom-environment-variable-name">
  カスタム環境変数名を使用する
</h2>

シークレットを受け取る環境変数を指定するには、Python では `env_var`、TypeScript では `envVar` を設定します。次の例では、`HF_TOKEN` シークレットを `HUGGINGFACE_TOKEN` として公開します。

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

    forge_auth = AuthHeaders(
        headers={
            "x-wandb-api-key": os.environ["FORGE_API_KEY"],
            **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
        },
        strategy="wandb_api_key",
    )

    with Sandbox.run(
      auth=forge_auth,
      placement_mode="serverless",
      container_image="python:3.11",
      secrets=[Secret(
        store="wandb",
        name="HF_TOKEN",
        env_var="HUGGINGFACE_TOKEN",
      )],
    ) as sandbox:
      result = sandbox.exec([
        "python", "-c",
        "import os; assert os.environ.get('HUGGINGFACE_TOKEN'); print('Secret is available')",
      ]).result()
      print(result.stdout)
    ```
  </Tab>

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

    const client = createSandboxClient({
      apiKey: process.env.FORGE_API_KEY,
      entity: process.env.FORGE_TEAM,
    });

    const result = await client.withSandbox(
      async (sandbox) => sandbox.commands.run([
        "python", "-c",
        "import os; assert os.environ.get('HUGGINGFACE_TOKEN'); print('Secret is available')",
      ]),
      {
        containerImage: "python:3.11",
        secrets: [{
          store: "wandb",
          name: "HF_TOKEN",
          envVar: "HUGGINGFACE_TOKEN",
        }],
      },
    );

    console.log(result.stdout);
    ```
  </Tab>
</Tabs>

どちらの例も、`HUGGINGFACE_TOKEN` が存在することを確認してから `Secret is available` を出力します。

<h2 id="select-a-field-from-a-structured-secret">
  構造化されたシークレットからフィールドを選択する
</h2>

JSON オブジェクトから値を 1 つ注入するには、`field` にそのトップレベルキーを設定します。ネストされたパスはサポートされません。JSON string の場合、注入される値には JSON の引用符は付きません。

この例では、`{"password":"[DB-PASSWORD]"}` のような JSON オブジェクトを値とする、`DB_CREDENTIALS` という名のチームシークレットを追加します。シークレットを保存する前に、`[DB-PASSWORD]` をパスワードに置き換えてください。以下のサンプルでは、その `password` フィールドを `DB_PASSWORD` に注入します。

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

    forge_auth = AuthHeaders(
        headers={
            "x-wandb-api-key": os.environ["FORGE_API_KEY"],
            **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
        },
        strategy="wandb_api_key",
    )

    with Sandbox.run(
      auth=forge_auth,
      placement_mode="serverless",
      container_image="python:3.11",
      secrets=[Secret(
        store="wandb",
        name="DB_CREDENTIALS",
        field="password",
        env_var="DB_PASSWORD",
      )],
    ) as sandbox:
      result = sandbox.exec([
        "python", "-c",
        "import os; assert os.environ.get('DB_PASSWORD'); print('Secret is available')",
      ]).result()
      print(result.stdout)
    ```
  </Tab>

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

    const client = createSandboxClient({
      apiKey: process.env.FORGE_API_KEY,
      entity: process.env.FORGE_TEAM,
    });

    const result = await client.withSandbox(
      async (sandbox) => sandbox.commands.run([
        "python", "-c",
        "import os; assert os.environ.get('DB_PASSWORD'); print('Secret is available')",
      ]),
      {
        containerImage: "python:3.11",
        secrets: [{
          store: "wandb",
          name: "DB_CREDENTIALS",
          field: "password",
          envVar: "DB_PASSWORD",
        }],
      },
    );

    console.log(result.stdout);
    ```
  </Tab>
</Tabs>

どちらのサンプルも、パスワードを出力せずに `Secret is available` を出力します。シークレットが JSON オブジェクトでない場合、キーが存在しない場合、またはその値が `null` の場合、フィールドの選択は失敗します。

<h2 id="reuse-secret-references">
  シークレット参照の再利用
</h2>

Python セッションの場合、共有シークレット参照を `SandboxDefaults` に配置します。TypeScript の場合は、サンドボックスを作成するときに `secrets` 配列を再利用します:

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    import os
    from cwsandbox import AuthHeaders, SandboxDefaults, Secret, Session

    forge_auth = AuthHeaders(
        headers={
            "x-wandb-api-key": os.environ["FORGE_API_KEY"],
            **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
        },
        strategy="wandb_api_key",
    )

    defaults = SandboxDefaults(
      auth=forge_auth,
      placement_mode="serverless",
      secrets=(Secret(store="wandb", name="HF_TOKEN"),),
    )

    with Session(defaults) as session:
      sandbox = session.sandbox()
      result = sandbox.exec([
        "python", "-c",
        "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
      ]).result()
      print(result.stdout)
    ```

    Python クライアントは、セッションのデフォルトをサンドボックスごとの `secrets` とマージし、完全に同一のものは無視します。異なる参照が同じ環境変数をターゲットにする場合、クライアントはサンドボックスを作成する前に `ValueError` を送出します。Python のタイプシグネチャについては、[Secret reference](/ja/products/sandboxes/client/ref/configuration/secret) を参照してください。
  </Tab>

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

    const client = createSandboxClient({
      apiKey: process.env.FORGE_API_KEY,
      entity: process.env.FORGE_TEAM,
    });
    const secrets = [{ store: "wandb", name: "HF_TOKEN" }];

    const result = await client.withSandbox(
      async (sandbox) => sandbox.commands.run([
        "python", "-c",
        "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
      ]),
      { containerImage: "python:3.11", secrets },
    );

    console.log(result.stdout);
    ```
  </Tab>
</Tabs>

<h2 id="troubleshoot-secret-injection">
  シークレット注入のトラブルシューティング
</h2>

シークレット参照を指定したサンドボックスが起動しない場合は、エラーテキストに基づいて認証、選択したチーム、配置を確認します。

| エラーテキスト | 確認事項 |
| - | - |
| `secret store "wandb" not found` | クライアントが CoreWeave 認証を選択しているか確認します。サーバーレス配置の場合は、例に示すように、Python では `AuthHeaders`、TypeScript では `@coreweave/cwsandbox/wandb` の `createSandboxClient` を使用して Forge の認証情報を渡します。`FORGE_API_KEY` を設定するだけでは、CoreWeave 認証を使用するクライアントは Forge 認証に切り替わりません。ストアを登録する必要はありません。 |
| `one or more W&B secrets not found` | シークレット名と選択した Forge チームを確認します。シークレットが APIキーのデフォルトの entity とは異なるチームに属する場合は、`FORGE_TEAM` を設定し、Forge アカウントからアクセスできることを確認します。 |
| `entity not found` | `FORGE_TEAM` に入力ミスがないか確認し、チームが存在することと、Forge アカウントからアクセスできることを確認します。 |
| `no eligible runner is available on this replica right now; retry shortly` | Forge 認証で CKS ランナーを選択した場合、この組み合わせはサポートされていません。再試行しても有効にはなりません。シークレット注入には、Forge 認証とサーバーレス配置を使用してください。サーバーレスのリクエストでは、このエラーはランナーが一時的に利用できないことを示している場合があります。 |

CoreWeave API アクセストークンと Forge APIキーの両方を設定した場合も含め、CKS 配置では Forge シークレット注入を利用できません。