Sviluppa con chiarezza.

A che punto siamo

L’API è pronta e testata. Finché non si apre il primo percorso di modello, le richieste di chat restituiscono 503 inference_not_configured. Lo stato in tempo reale è sempre su https://undergrove.vercel.app/api/status.

Segue il formato dell’API di OpenAI, quindi gli SDK esistenti funzionano cambiando l’URL di base: chat con immagini, function calling e output strutturati, oltre a embedding, trascrizione e sintesi vocale. Per rendere le richieste illeggibili persino per il nostro gateway, usa la modalità cifrata, come fa lo spazio di lavoro.

Guida rapida

URL di base: https://undergrove.vercel.app/v1. Elenca i modelli con GET /v1/models, poi ricevi una risposta in 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

Invia una richiesta di chat da questa pagina con la tua chiave e guarda la risposta, il suo utilizzo e la risposta grezza, insieme alla stessa richiesta in curl. Va dal tuo browser al /v1 di questo sito, come qualsiasi altra chiamata API, e consuma la tua quota o il tuo credito come di consueto.

Scegli Cifrata per inviarla come fa la modalità cifrata degli SDK: l’SDK di Tinfoil verifica l’enclave in questa pagina, poi sigilla la richiesta per essa. Il playground mostra i byte che hanno effettivamente lasciato la pagina, cosa è tornato indietro e la ricevuta dell’enclave per cui è stata sigillata.

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": "Aiutami a esplorare un’idea."
      }
    ],
    "stream": true
  }'

Autenticazione

Invia una chiave API di Undergrove come token Bearer. Le chiavi iniziano con ugk_ e durante l’alpha vengono rilasciate su invito. Dove le chiavi self-service sono attive, i membri dell’alpha ne creano fino a cinque nelle impostazioni dello spazio di lavoro, e ognuna consuma la quota e il credito del proprio account. Conserviamo solo un hash unidirezionale di ogni chiave, quindi una chiave persa non si può recuperare, solo sostituire.

Ogni chiave self-service può avere i propri limiti, impostati alla creazione o in seguito nelle impostazioni: un tetto di spesa giornaliero, superato il quale le sue richieste vengono rifiutate fino alla mezzanotte UTC, e un elenco dei modelli che può usare. Una chiave con tetto continua a essere conteggiata nella quota del suo account. Le chiavi create prima che esistessero i limiti non ne hanno e continuano a funzionare come prima.

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

Endpoint

Le risposte usano la forma standard chat.completion. Gli stream inviano eventi chat.completion.chunk e terminano con data: [DONE]. I modelli di ragionamento trasmettono il ragionamento a parte in delta.reasoning_content, e l’ultimo chunk riporta l’utilizzo dei token. Se uno stream si interrompe, l’evento finale è un oggetto di errore invece di [DONE], così una risposta parziale non viene mai scambiata per una completa.

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"]
  }'

Parametri

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"]
        }
      }
    }]
  }'

Modalità cifrata

L’API standard viene letta in memoria dal nostro gateway per controllare ogni richiesta. Per rendere le richieste illeggibili anche per Undergrove, usa l’SDK di Tinfoil con la tua chiave. Verifica l’attestazione hardware dell’enclave, poi cifra ogni richiesta in modo che solo quell’enclave possa leggerla. Il nostro relay controlla la tua chiave e la tua quota e inoltra il testo cifrato.

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

Lo stesso client raggiunge embeddings, audio/transcriptions e audio/speech. Poiché il relay non può leggere queste richieste, i modelli si indicano con il loro id enclave_model da /v1/models, le risposte tornano nel formato di Tinfoil e l’utilizzo viene stimato dalla dimensione dei dati cifrati. Quote e credito si applicano come di consueto.

Server MCP

Undergrove è anche un server Model Context Protocol, all’indirizzo https://undergrove.vercel.app/mcp. Ogni modello live è uno strumento, come ask_<model>, che i client MCP come Claude Code, Cursor e Claude Desktop possono chiamare con la tua chiave API. Uno strumento accetta un prompt e, facoltativamente, system, max_tokens e, per i modelli che cercano, web_search, e restituisce la risposta del modello come testo.

Una chiamata a uno strumento è una richiesta API come le altre: il gateway la legge in memoria, la invia sul percorso pubblicato del modello, non ne conserva copia e la conteggia nei limiti, nella quota e nel credito della tua chiave. Il server usa HTTP in streaming, risponde in JSON e non mantiene sessioni. Supporta le versioni del protocollo 2025-11-25, 2025-06-18 e 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"}'

Poi chiama lo strumento di un modello:

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."}
    }
  }'

Nella direzione opposta, lo spazio di lavoro può usare strumenti dei server MCP che colleghi nelle Impostazioni. Quelle chiamate passano dal server di Undergrove al server che hai collegato, in chiaro, quindi usa server a cui affideresti ciò che ricevono gli strumenti.

Errori e limiti

Gli errori usano il formato di OpenAI: {"error": {"message", "type", "code"}}.

Durante l’alpha, ogni chiave o account ha una quota al minuto, una di richieste giornaliere e una di spesa giornaliera. I valori attuali sono pubblicati su /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"
  }
}

Sappi dove vanno i tuoi dati

Il gateway controlla la tua chiave, applica i limiti e inoltra al percorso del modello solo i campi indicati sopra. Non conserva copie di prompt o risposte e non li registra. I suoi log registrano solo nomi dei percorsi, codici di stato e tempi. I contatori dei limiti di frequenza usano un hash unidirezionale della tua chiave o del tuo account e scadono entro due giorni.

L’operatore, la posizione e la conservazione dei dati di ogni percorso di modello sono pubblicati nel registro dei modelli su /api/status e nella pagina sulla privacy. Le richieste non passano mai a un percorso diverso come ripiego. Vercel, il nostro hosting, conserva i metadati standard delle richieste, come gli indirizzi IP.

Sui percorsi di confidential computing, il gateway dell’API verifica l’attestazione hardware dell’enclave prima di connettersi e cifra ogni richiesta in modo che solo quell’enclave possa leggerla. Il gateway stesso continua però a leggere in memoria le richieste API per controllarle.

Dati dell’area di lavoro

Sincronizzazione, link condivisi e progetti condivisi conservano solo testo cifrato creato dal browser. Ogni diagramma mostra, passo per passo, chi ha la chiave.

Cosa dimostra la verifica

Prima di inviare qualsiasi cosa, lo spazio di lavoro esegue nel tuo browser il verificatore open source di Tinfoil. Controlla il report di attestazione hardware dell’enclave con le chiavi di firma di AMD o di Intel, controlla che il codice misurato nell’enclave corrisponda a una release che Tinfoil ha pubblicato e firmato su GitHub, e controlla che la chiave di cifratura che usa appartenga a quell’enclave. Seleziona Verificato nello spazio di lavoro per vedere ogni controllo, la release e la misurazione.

Dimostra che i tuoi messaggi possono essere decifrati solo da quell’hardware mentre esegue quel codice pubblicato. Non dimostra che il codice pubblicato sia privo di difetti, non protegge da debolezze dei processori stessi e non copre ciò che fai con le risposte dopo che raggiungono il tuo browser. Il codice dello spazio di lavoro è servito da Undergrove, quindi ti fidi che serviamo il verificatore così come è stato pubblicato; Verifica questa pagina confronta il codice caricato dal tuo browser con il manifest della build, e npm run verify:site confronta il sito con una tua build dello stesso commit. È prevista una valutazione indipendente.

Ogni risposta di un’enclave ha un pulsante Ricevuta. Mostra l’enclave, la release e le misurazioni verificate prima dell’invio di quella richiesta e la chiave per cui è stata cifrata, e li scarica come JSON. Finché la scheda resta aperta, il download include il report di attestazione, così puoi eseguire di nuovo il verificatore in seguito; dopo, contiene l’hash del report e dove recuperare quello attuale dell’enclave. La ricevuta è un registro del tuo browser, non una dichiarazione firmata, e l’enclave che indica è il router dei modelli di Tinfoil; il router passa le richieste all’enclave del modello. La ricevuta indica anche quell’enclave, e il tuo browser prova a verificarla allo stesso modo. La maggior parte delle enclave dei modelli funziona su Intel TDX, che il verificatore nel browser non può ancora controllare; in quei casi la ricevuta lo dice, e il controllo si basa sul router, il cui codice pubblicato verifica ogni enclave di modello prima di usarla.

# 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

Prossimi passi