Construye con claridad.

Dónde estamos

La API está construida y probada. Hasta que se abra la primera ruta de modelo, las solicitudes de chat devuelven 503 inference_not_configured. El estado en vivo está siempre en https://undergrove.vercel.app/api/status.

Sigue el formato de la API de OpenAI, así que los SDK existentes funcionan cambiando la URL base: chat con imágenes, llamadas a funciones y salidas estructuradas, además de embeddings, transcripción y voz. Para que las solicitudes sean ilegibles incluso para nuestra pasarela, usa el modo cifrado, como hace el espacio de trabajo.

Inicio rápido

URL base: https://undergrove.vercel.app/v1. Lista los modelos con GET /v1/models y luego transmite una respuesta:

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

Envía una solicitud de chat desde esta página con tu propia clave y mira la respuesta, su uso y la respuesta sin procesar, con la misma solicitud en curl. Va de tu navegador al /v1 de este sitio, como cualquier otra llamada a la API, y gasta tu asignación o tu crédito como siempre.

Elige Cifrado para enviarla como lo hace el modo cifrado de los SDK: el SDK de Tinfoil verifica el enclave en esta página y luego sella la solicitud para él. El playground muestra los bytes que salieron realmente de la página, lo que volvió y el comprobante del enclave para el que se selló.

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": "Ayúdame a explorar una idea."
      }
    ],
    "stream": true
  }'

Autenticación

Envía una clave de API de Undergrove como token Bearer. Las claves empiezan por ugk_ y se emiten por invitación durante la alfa. Donde las claves de autoservicio están activadas, los miembros de la alfa crean hasta cinco en los ajustes del espacio de trabajo, y cada una gasta la asignación y el crédito de su cuenta. Solo guardamos un hash unidireccional de cada clave, así que una clave perdida no se puede recuperar, solo sustituir.

Cada clave de autoservicio puede tener sus propios límites, fijados al crearla o más tarde en los ajustes: un límite de gasto diario, tras el cual sus solicitudes se rechazan hasta medianoche UTC, y una lista de los modelos que puede usar. Una clave con límite sigue contando contra la asignación de su cuenta. Las claves creadas antes de que existieran los límites no tienen ninguno y siguen funcionando como antes.

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

Endpoints

Las respuestas usan la forma estándar chat.completion. Los streams envían eventos chat.completion.chunk y terminan con data: [DONE]. Los modelos de razonamiento transmiten su razonamiento aparte en delta.reasoning_content, y el último fragmento informa del uso de tokens. Si un stream se interrumpe, el evento final es un objeto de error en lugar de [DONE], así que una respuesta parcial nunca se confunde con 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"]
  }'

Parámetros

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

Modo cifrado

La API estándar la lee nuestra pasarela en memoria para comprobar cada solicitud. Para que las solicitudes también sean ilegibles para Undergrove, usa el SDK de Tinfoil con tu clave. Verifica la atestación de hardware del enclave y luego cifra cada solicitud para que solo ese enclave pueda leerla. Nuestro retransmisor comprueba tu clave y tu asignación y reenvía el texto cifrado.

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

El mismo cliente llega a embeddings, audio/transcriptions y audio/speech. Como el retransmisor no puede leer estas solicitudes, los modelos se nombran por su id enclave_model de /v1/models, las respuestas vuelven en el formato de Tinfoil y el uso se estima a partir del tamaño de los datos cifrados. Las asignaciones y el crédito se aplican como siempre.

Servidor MCP

Undergrove también es un servidor Model Context Protocol, en https://undergrove.vercel.app/mcp. Cada modelo en vivo es una herramienta, como ask_<model>, que clientes MCP como Claude Code, Cursor y Claude Desktop pueden llamar con tu clave de API. Una herramienta recibe un prompt, y opcionalmente system, max_tokens y, para los modelos que buscan, web_search, y devuelve la respuesta del modelo como texto.

Una llamada a una herramienta es una solicitud a la API como cualquier otra: la pasarela la lee en memoria, la envía por la ruta publicada del modelo, no guarda ninguna copia y la cuenta contra los límites, la asignación y el crédito de tu clave. El servidor usa HTTP en streaming, responde en JSON y no mantiene sesiones. Habla las versiones del protocolo 2025-11-25, 2025-06-18 y 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"}'

Después, llama a la herramienta de un modelo:

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

En sentido inverso, el espacio de trabajo puede usar herramientas de servidores MCP que conectes en los Ajustes. Esas llamadas pasan por el servidor de Undergrove hasta el servidor que conectaste, en texto plano, así que usa servidores en los que confíes con lo que reciben las herramientas.

Errores y límites

Los errores usan el formato de OpenAI: {"error": {"message", "type", "code"}}.

Durante la alfa, cada clave o cuenta tiene una asignación por minuto, de solicitudes diarias y de gasto diario. Los valores actuales se publican en /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"
  }
}

Sabe adónde van tus datos

La pasarela comprueba tu clave, aplica los límites y reenvía solo los campos de arriba a la ruta del modelo. No guarda ninguna copia de los prompts ni de las respuestas y no los registra. Sus registros recogen solo nombres de rutas, códigos de estado y tiempos. Los contadores de límites de frecuencia usan un hash unidireccional de tu clave o cuenta y caducan en un plazo de dos días.

El operador, la ubicación y la conservación de cada ruta de modelo se publican en el registro de modelos en /api/status y en la página de privacidad. Las solicitudes nunca pasan a otra ruta como alternativa. Vercel, nuestro proveedor de alojamiento, guarda los metadatos habituales de las solicitudes, como las direcciones IP.

En las rutas de computación confidencial, la pasarela de la API verifica la atestación de hardware del enclave antes de conectarse y cifra cada solicitud para que solo ese enclave pueda leerla. La propia pasarela sigue leyendo las solicitudes a la API en memoria para comprobarlas.

Datos del espacio de trabajo

La sincronización, los enlaces compartidos y los proyectos compartidos solo guardan texto cifrado creado por el navegador. Cada diagrama muestra, paso a paso, quién tiene la clave.

Lo que demuestra la verificación

Antes de enviar nada, el espacio de trabajo ejecuta en tu navegador el verificador de código abierto de Tinfoil. Comprueba el informe de atestación de hardware del enclave frente a las claves de firma de AMD o Intel, comprueba que el código medido en el enclave coincide con una versión que Tinfoil publicó y firmó en GitHub, y comprueba que la clave de cifrado que usa pertenece a ese enclave. Selecciona Verificado en el espacio de trabajo para ver cada comprobación, la versión y la medición.

Demuestra que tus mensajes solo pueden descifrarse en ese hardware ejecutando ese código publicado. No demuestra que el código publicado esté libre de fallos, no protege frente a debilidades de los propios procesadores ni cubre lo que hagas con las respuestas cuando llegan a tu navegador. El código del espacio de trabajo lo sirve Undergrove, así que confías en que sirvamos el verificador tal como se publicó; Verificar esta página compara el código que cargó tu navegador con el manifiesto de la compilación, y npm run verify:site compara el sitio con tu propia compilación del mismo commit. Está prevista una evaluación independiente.

Cada respuesta de un enclave tiene un botón Comprobante. Muestra el enclave, la versión y las mediciones verificadas antes de enviar esa solicitud y la clave para la que se cifró, y los descarga como JSON. Hasta que se cierra la pestaña, la descarga incluye el informe de atestación, para que puedas volver a ejecutar el verificador sobre él más tarde; después, contiene el hash del informe y dónde descargar el actual del enclave. El comprobante es el registro de tu navegador, no una declaración firmada, y el enclave que indica es el enrutador de modelos de Tinfoil; el enrutador pasa las solicitudes al enclave propio del modelo. El comprobante también indica ese enclave, y tu navegador intenta verificarlo del mismo modo. La mayoría de los enclaves de modelos se ejecutan en Intel TDX, que el verificador del navegador aún no puede comprobar; en esos casos el comprobante lo dice, y la comprobación descansa en el enrutador, cuyo código publicado verifica cada enclave de modelo antes de usarlo.

# 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

Lo siguiente