Construire en toute clarté.

Où nous en sommes

L’API est construite et testée. Tant que la première route de modèle n’est pas ouverte, les requêtes de chat renvoient 503 inference_not_configured. L’état en direct se trouve toujours sur https://undergrove.vercel.app/api/status.

Elle suit le format de l’API d’OpenAI : les SDK existants fonctionnent en changeant l’URL de base, pour le chat avec images, l’appel de fonctions et les sorties structurées, ainsi que les embeddings, la transcription et la synthèse vocale. Pour que les requêtes restent illisibles même pour notre passerelle, utilisez le mode chiffré, comme le fait l’espace de travail.

Démarrage rapide

URL de base : https://undergrove.vercel.app/v1. Listez les modèles avec GET /v1/models, puis diffusez une réponse en streaming :

curl https://undergrove.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "stream": true,
    "messages": [{"role": "user", "content": "Help me explore an idea."}]
  }'

Playground

Envoyez une requête de chat depuis cette page avec votre propre clé, et voyez la réponse, son utilisation et la réponse brute, avec la même requête en curl. Elle part de votre navigateur vers le /v1 de ce site, comme tout autre appel d’API, et consomme votre quota ou votre crédit comme d’habitude.

Choisissez Chiffré pour l’envoyer comme le fait le mode chiffré des SDK : le SDK de Tinfoil vérifie l’enclave dans cette page, puis scelle la requête pour elle. Le playground montre les octets qui ont réellement quitté la page, ce qui est revenu et le reçu de l’enclave pour laquelle elle a été scellée.

curl --no-buffer https://undergrove.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [
      {
        "role": "user",
        "content": "Aide-moi à explorer une idée."
      }
    ],
    "stream": true
  }'

Authentification

Envoyez une clé d’API Undergrove comme jeton Bearer. Les clés commencent par ugk_ et sont délivrées sur invitation pendant l’alpha. Là où les clés en libre-service sont activées, les membres de l’alpha en créent jusqu’à cinq dans les réglages de l’espace de travail, et chacune consomme le quota et le crédit de son compte. Nous ne stockons qu’un hachage à sens unique de chaque clé : une clé perdue ne peut donc pas être récupérée, seulement remplacée.

Chaque clé en libre-service peut avoir ses propres limites, définies à sa création ou plus tard dans les réglages : un plafond de dépense quotidien, au-delà duquel ses requêtes sont refusées jusqu’à minuit UTC, et une liste des modèles qu’elle peut utiliser. Une clé plafonnée compte toujours dans le quota de son compte. Les clés créées avant l’existence des limites n’en ont aucune et fonctionnent comme avant.

curl https://undergrove.vercel.app/v1/models \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY"

Points de terminaison

Les réponses ont la forme standard chat.completion. Les flux envoient des événements chat.completion.chunk et se terminent par data: [DONE]. Les modèles de raisonnement diffusent leur raisonnement à part dans delta.reasoning_content, et le dernier fragment indique l’utilisation des jetons. Si un flux est interrompu, l’événement final est un objet d’erreur au lieu de [DONE] : une réponse partielle n’est donc jamais prise pour une réponse complète.

curl https://undergrove.vercel.app/v1/embeddings \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "undergrove/nomic-embed-text",
    "input": ["Where is the signed contract?", "Payment terms"]
  }'

Paramètres

curl https://undergrove.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "max_tokens": 500,
    "messages": [{"role": "user", "content": "Is it raining in Lisbon?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }]
  }'

Mode chiffré

L’API standard est lue en mémoire par notre passerelle pour vérifier chaque requête. Pour que les requêtes soient aussi illisibles pour Undergrove, utilisez le SDK de Tinfoil avec votre clé. Il vérifie l’attestation matérielle de l’enclave, puis chiffre chaque requête pour que seule cette enclave puisse la lire. Notre relais vérifie votre clé et votre quota, et transmet le texte chiffré.

import { SecureClient } from "tinfoil"; // npm install tinfoil

const RELAY = "https://undergrove.vercel.app/api/enclave";
const client = new SecureClient({
  baseURL: `${RELAY}/v1/`,
  attestationBundleURL: RELAY,
});
await client.ready(); // verifies the enclave; throws if it can't

const response = await client.fetch("chat/completions", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.UNDERGROVE_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "gemma4-31b", // enclave_model in /v1/models
    max_tokens: 1000,
    messages: [{ role: "user", content: "Summarise this contract." }],
  }),
});
console.log((await response.json()).choices[0].message.content);

Le même client accède à embeddings, audio/transcriptions et audio/speech. Comme le relais ne peut pas lire ces requêtes, les modèles sont désignés par leur id enclave_model de /v1/models, les réponses reviennent au format de Tinfoil et l’usage est estimé à partir de la taille des données chiffrées. Les quotas et le crédit s’appliquent comme d’habitude.

Serveur MCP

Undergrove est aussi un serveur Model Context Protocol, à l’adresse https://undergrove.vercel.app/mcp. Chaque modèle en direct est un outil, comme ask_<model>, que des clients MCP tels que Claude Code, Cursor et Claude Desktop peuvent appeler avec votre clé d’API. Un outil prend un prompt, et en option system, max_tokens et, pour les modèles qui cherchent, web_search, puis renvoie la réponse du modèle sous forme de texte.

Un appel d’outil est une requête d’API comme une autre : la passerelle la lit en mémoire, l’envoie sur la route publiée du modèle, n’en garde aucune copie et la décompte des limites, du quota et du crédit de votre clé. Le serveur utilise HTTP en streaming, répond en JSON et ne conserve aucune session. Il parle les versions de protocole 2025-11-25, 2025-06-18 et 2025-03-26.

claude mcp add --transport http undergrove https://undergrove.vercel.app/mcp \
  --header "Authorization: Bearer ugk_your_key"

{
  "mcpServers": {
    "undergrove": {
      "url": "https://undergrove.vercel.app/mcp",
      "headers": {
        "Authorization": "Bearer ugk_your_key"
      }
    }
  }
}

{
  "mcpServers": {
    "undergrove": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://undergrove.vercel.app/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ugk_your_key"
      }
    }
  }
}

curl https://undergrove.vercel.app/mcp \
  -H "Authorization: Bearer ugk_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Appelez ensuite l’outil d’un modèle :

curl https://undergrove.vercel.app/mcp \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "ask_<model>",
      "arguments": {"prompt": "Name three uses for a sealed envelope."}
    }
  }'

Dans l’autre sens, l’espace de travail peut utiliser les outils des serveurs MCP que vous connectez dans les Réglages. Ces appels passent par le serveur d’Undergrove jusqu’au serveur connecté, en clair : utilisez des serveurs à qui vous confiez ce que reçoivent les outils.

Erreurs et limites

Les erreurs suivent le format d’OpenAI : {"error": {"message", "type", "code"}}.

Pendant l’alpha, chaque clé ou compte a un quota par minute, de requêtes quotidiennes et de dépense quotidienne. Les valeurs actuelles sont publiées sur /api/status.

HTTP/2 429
retry-after: 41

{
  "error": {
    "message": "You’re sending messages quickly. Please wait a moment.",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

Savoir où vont vos données

La passerelle vérifie votre clé, applique les limites et ne transmet à la route du modèle que les champs ci-dessus. Elle ne garde aucune copie des prompts ni des réponses et ne les journalise pas. Ses journaux n’enregistrent que des noms de routes, des codes d’état et des durées. Les compteurs de limites de débit utilisent un hachage à sens unique de votre clé ou de votre compte et expirent sous deux jours.

L’opérateur, l’emplacement et la conservation de chaque route de modèle sont publiés dans le registre des modèles sur /api/status et sur la page de confidentialité. Les requêtes ne basculent jamais sur une autre route. Vercel, notre hébergeur, conserve les métadonnées de requête habituelles, comme les adresses IP.

Sur les routes d’informatique confidentielle, la passerelle de l’API vérifie l’attestation matérielle de l’enclave avant de se connecter et chiffre chaque requête pour que seule cette enclave puisse la lire. La passerelle elle-même lit toujours les requêtes d’API en mémoire pour les vérifier.

Données de l’espace de travail

La synchronisation, les liens partagés et les projets partagés ne stockent que du texte chiffré produit par le navigateur. Chaque schéma montre, étape par étape, qui détient la clé.

Ce que prouve la vérification

Avant tout envoi, l’espace de travail exécute dans votre navigateur le vérificateur open source de Tinfoil. Il vérifie le rapport d’attestation matérielle de l’enclave avec les clés de signature d’AMD ou d’Intel, vérifie que le code mesuré dans l’enclave correspond à une version publiée et signée par Tinfoil sur GitHub, et vérifie que la clé de chiffrement utilisée appartient à cette enclave. Sélectionnez Vérifié dans l’espace de travail pour voir chaque vérification, la version et la mesure.

Elle prouve que vos messages ne peuvent être déchiffrés que par ce matériel exécutant ce code publié. Elle ne prouve pas que le code publié est exempt de failles, ne protège pas contre les faiblesses des processeurs eux-mêmes et ne couvre pas ce que vous faites des réponses une fois arrivées dans votre navigateur. Le code de l’espace de travail est servi par Undergrove : vous nous faites donc confiance pour servir le vérificateur tel qu’il est publié ; Vérifier cette page compare le code chargé par votre navigateur avec le manifeste de build, et npm run verify:site compare le site avec votre propre build du même commit. Une évaluation indépendante est prévue.

Chaque réponse d’une enclave a un bouton Reçu. Il montre l’enclave, la version et les mesures vérifiées avant l’envoi de cette requête ainsi que la clé pour laquelle elle a été chiffrée, et les télécharge en JSON. Jusqu’à la fermeture de l’onglet, le téléchargement inclut le rapport d’attestation, pour que vous puissiez réexécuter le vérificateur dessus plus tard ; ensuite, il contient l’empreinte du rapport et l’endroit où récupérer le rapport actuel de l’enclave. Le reçu est le relevé de votre navigateur, pas une déclaration signée, et l’enclave qu’il nomme est le routeur de modèles de Tinfoil ; le routeur transmet les requêtes à l’enclave propre au modèle. Le reçu nomme aussi cette enclave, et votre navigateur tente de la vérifier de la même façon. La plupart des enclaves de modèles s’exécutent sur Intel TDX, que le vérificateur du navigateur ne sait pas encore vérifier ; dans ce cas, le reçu l’indique, et la vérification repose sur le routeur, dont le code publié vérifie chaque enclave de modèle avant de l’utiliser.

# The attestation bundle the gateway verified, what it checked
# in it, and the steps to check it again yourself
curl https://undergrove.vercel.app/v1/attestation

La suite