Utiliser les secrets Forge

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.

Avant de commencer

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

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 :

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 :

Python
TypeScript

Utilisez Python 3.11 ou une version ultérieure et, si nécessaire, installez uv. Dans votre environnement Python, installez le client :

uv pip install 'cwsandbox>=1.14.2'

Utilisez Node.js 22 ou une version ultérieure. Installez le client TypeScript ainsi que tsx pour exécuter les exemples :

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.

Injecter un secret

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.

Python
TypeScript

Transmettez la clé API Forge et, si besoin, l’équipe via AuthHeaders :

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)

Importez le client depuis le point d’entrée Forge. Si vous omettez runnerIds, le client utilise le placement sans serveur :

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

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.

Champs de référence de secret

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

Utiliser un nom de variable d’environnement personnalisé

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 :

Python
TypeScript

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)

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

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

Sélectionner un champ d’un secret structuré

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 :

Python
TypeScript

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)

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

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.

Réutiliser les références de secret

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 :

Python
TypeScript

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.

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

Résoudre les problèmes d’injection de secrets

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.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Utiliser les secrets Forge

Avant de commencer

Injecter un secret

Champs de référence de secret

Utiliser un nom de variable d’environnement personnalisé

Sélectionner un champ d’un secret structuré

Réutiliser les références de secret

Résoudre les problèmes d’injection de secrets

​Avant de commencer

​Injecter un secret

​Champs de référence de secret

​Utiliser un nom de variable d’environnement personnalisé

​Sélectionner un champ d’un secret structuré

​Réutiliser les références de secret

​Résoudre les problèmes d’injection de secrets

Avant de commencer

Injecter un secret

Champs de référence de secret

Utiliser un nom de variable d’environnement personnalisé

Sélectionner un champ d’un secret structuré

Réutiliser les références de secret

Résoudre les problèmes d’injection de secrets