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

# Utiliser les secrets Forge

> Injectez les secrets de l’équipe Forge dans des bacs à sable exécutés sur une capacité sans serveur, avec Python ou TypeScript.

Utilisez Forge Secret Manager pour rendre les jetons API et autres identifiants d’authentification disponibles dans une sandbox exécutée sur une capacité sans serveur. Votre application transmet les noms des secrets à l’API Sandboxes. Lors de la création de la sandbox, l’API résout leurs valeurs depuis votre équipe Forge et les injecte sous forme de variables d’environnement.

<h2 id="before-you-begin">
  Avant de commencer
</h2>

L’injection de secrets Forge nécessite un sandbox authentifié avec une clé API Forge. Elle est disponible pour les bacs à sable sans serveur, mais pas pour les bacs à sable exécutés sur votre propre cluster CoreWeave Kubernetes Service (CKS). Le placement CKS repose sur un jeton d’accès à l’API CoreWeave. Il n’est pas possible de combiner ce jeton avec une clé API Forge distincte pour résoudre les secrets d’un sandbox CKS.

| Placement du sandbox | Identifiant d’authentification du sandbox | Injection de secrets Forge |
| - | - | - |
| Sans serveur | Clé API Forge | Pris en charge. Utilisez le magasin `wandb`. |
| Sans serveur | Jeton d’accès à l’API CoreWeave | Non pris en charge. |
| Votre cluster CKS | Jeton d’accès à l’API CoreWeave | Non pris en charge. L’ajout de `FORGE_API_KEY` ne permet pas de l’activer. |

Pour suivre les exemples, vous devez disposer des éléments suivants :

* Un compte Forge SaaS (logiciel en tant que service) avec un [accès aux bacs à sable sans serveur](/fr/products/sandboxes/get-started).
* Un secret nommé `HF_TOKEN` dans le Secret Manager de votre équipe Forge. Si ce secret n’existe pas, demandez à un administrateur Forge de l’[ajouter](/fr/products/wandb/platform/secrets#add-a-secret).
* Une clé API Forge ayant accès à cette équipe.

Définissez `FORGE_API_KEY` dans l’environnement du processus qui crée le sandbox. Remplacez `[FORGE-API-KEY]` par votre clé API Forge :

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

Les exemples utilisent l'équipe par défaut de la clé API, sauf si vous définissez `FORGE_TEAM`. Si le secret appartient à une autre équipe, définissez `FORGE_TEAM` sur cette équipe. Remplacez `[FORGE-TEAM]` par le nom de l'équipe :

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

Les exemples transmettent explicitement ces variables au client ; le SDK ne détecte pas automatiquement `FORGE_API_KEY` ni `FORGE_TEAM`.

Installez le client correspondant à votre langage :

<Tabs>
  <Tab title="Python">
    Utilisez Python 3.11 ou une version ultérieure et, si nécessaire, [installez `uv`](https://docs.astral.sh/uv/getting-started/installation/). Dans votre environnement Python, installez le client :

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

  <Tab title="TypeScript">
    Utilisez Node.js 22 ou une version ultérieure. Installez le client TypeScript ainsi que `tsx` pour exécuter les exemples :

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

    Enregistrez l’exemple TypeScript à exécuter sous le nom `secrets.mts`, puis lancez `npx tsx secrets.mts`.
  </Tab>
</Tabs>

<h2 id="inject-a-secret">
  Injecter un secret
</h2>

Utilisez `store="wandb"` en Python ou `store: "wandb"` en TypeScript. Ce magasin résout les secrets pour l’équipe Forge authentifiée. Avec ce flux de travail, il n’est pas nécessaire d’enregistrer un magasin de secrets d’organisation.

Les exemples suivants injectent `HF_TOKEN` et vérifient sa présence sans afficher sa valeur. Dans la sandbox, la variable d’environnement porte par défaut le nom du secret.

<Tabs>
  <Tab title="Python">
    Transmettez la clé API Forge et, si besoin, l’équipe via `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">
    Importez le client depuis le point d’entrée Forge. Si vous omettez `runnerIds`, le client utilise le placement sans serveur :

    ```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>

Les deux exemples affichent `Secret is available` et arrêtent la sandbox une fois l’opération terminée. Le code exécuté dans la sandbox peut lire la valeur dans `HF_TOKEN`.

Dans `secrets`, transmettez le nom du secret, et non sa valeur : c’est le serveur qui résout la valeur. Ne l’affichez pas et ne l’écrivez pas dans les journaux.

<h2 id="secret-reference-fields">
  Champs de référence de secret
</h2>

Utilisez ces champs dans un `Secret` Python ou dans une entrée `secrets` TypeScript :

| Champ Python | Champ TypeScript | Requis | Description |
| - | - | - | - |
| `store` | `store` | Oui | Nom du magasin de secrets. Utilisez `wandb` pour Forge Secret Manager. |
| `name` | `name` | Oui | Nom du secret dans le Secret Manager de l’équipe Forge sélectionnée. |
| `field` | `field` | Non | Clé de premier niveau à sélectionner dans un secret dont la valeur est un objet JSON. Omettez ce champ pour injecter l’intégralité de la valeur du secret. |
| `env_var` | `envVar` | Non | Variable d’environnement qui reçoit la valeur. Par défaut : `name`. |

<h2 id="use-a-custom-environment-variable-name">
  Utiliser un nom de variable d’environnement personnalisé
</h2>

Pour choisir la variable d’environnement qui reçoit le secret, définissez `env_var` en Python ou `envVar` en TypeScript. Les exemples suivants exposent le secret `HF_TOKEN` sous le nom `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>

Les deux exemples vérifient la présence de `HUGGINGFACE_TOKEN`, puis affichent `Secret is available`.

<h2 id="select-a-field-from-a-structured-secret">
  Sélectionner un champ d’un secret structuré
</h2>

Pour injecter une seule valeur d’un objet JSON, définissez `field` sur sa clé de premier niveau. Les chemins imbriqués ne sont pas pris en charge. S’il s’agit d’une chaîne JSON, la valeur est injectée sans les guillemets JSON qui l’entourent.

Pour cet exemple, ajoutez un secret d’équipe nommé `DB_CREDENTIALS` dont la valeur est un objet JSON tel que `{"password":"[DB-PASSWORD]"}`. Remplacez `[DB-PASSWORD]` par le mot de passe avant d’enregistrer le secret. Les exemples injectent son champ `password` dans `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>

Les deux exemples affichent `Secret is available` sans révéler le mot de passe. La sélection d’un champ échoue si le secret n’est pas un objet JSON, si la clé n’existe pas ou si sa valeur est `null`.

<h2 id="reuse-secret-references">
  Réutiliser les références de secret
</h2>

Pour les sessions Python, placez les références de secret partagées dans `SandboxDefaults`. En TypeScript, réutilisez un même tableau `secrets` lorsque vous créez des bacs à sable :

<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)
    ```

    Le client Python fusionne les valeurs par défaut de la session avec les `secrets` propres à chaque sandbox et ignore les doublons exacts. Si plusieurs références différentes ciblent la même variable d’environnement, le client lève une `ValueError` avant de créer la sandbox. Pour la signature de type Python, consultez la [référence Secret](/fr/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">
  Résoudre les problèmes d’injection de secrets
</h2>

Si la sandbox ne démarre pas avec une référence de secret, consultez le texte de l’erreur pour vérifier l’authentification, l’équipe sélectionnée et le placement :

| Texte de l’erreur | Éléments à vérifier |
| - | - |
| `secret store "wandb" not found` | Vérifiez si le client a sélectionné l’authentification CoreWeave. Pour un placement sans serveur, transmettez les identifiants d’authentification Forge via `AuthHeaders` en Python ou via `createSandboxClient` depuis `@coreweave/cwsandbox/wandb` en TypeScript, comme indiqué dans les exemples. Définir uniquement `FORGE_API_KEY` ne suffit pas à faire basculer vers Forge un client authentifié auprès de CoreWeave. Il n’est pas nécessaire d’enregistrer un magasin. |
| `one or more W&B secrets not found` | Vérifiez le nom du secret et l’équipe Forge sélectionnée. Définissez `FORGE_TEAM` si le secret appartient à une équipe autre que l’entity par défaut de la clé API, et vérifiez que votre compte Forge peut y accéder. |
| `entity not found` | Vérifiez que `FORGE_TEAM` ne contient pas de faute de frappe, que l’équipe existe et que votre compte Forge peut y accéder. |
| `no eligible runner is available on this replica right now; retry shortly` | Si vous avez sélectionné un exécuteur CKS avec l’authentification Forge, cette combinaison n’est pas prise en charge, et une nouvelle tentative n’y changera rien. Pour l’injection de secrets, utilisez l’authentification Forge avec un placement sans serveur. Pour une requête sans serveur, cette erreur peut signaler une indisponibilité temporaire de l’exécuteur. |

L’injection de secrets Forge n’est pas disponible pour le placement CKS, y compris lorsque vous définissez à la fois un jeton d’accès à l’API CoreWeave et une clé API Forge.