Desenvolva com clareza.

Onde estamos

A API está pronta e testada. Até a primeira rota de modelo abrir, as solicitações de chat retornam 503 inference_not_configured. O estado em tempo real está sempre em https://undergrove.vercel.app/api/status.

Ela segue o formato da API da OpenAI, então os SDKs existentes funcionam trocando a URL base: chat com imagens, chamada de funções e saídas estruturadas, além de embeddings, transcrição e fala. Para que as solicitações fiquem ilegíveis até para o nosso gateway, use o modo criptografado, como o espaço de trabalho faz.

Início rápido

URL base: https://undergrove.vercel.app/v1. Liste os modelos com GET /v1/models e depois transmita uma resposta em 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

Envie uma solicitação de chat desta página com a sua própria chave e veja a resposta, o uso e a resposta bruta, com a mesma solicitação em curl. Ela vai do seu navegador para o /v1 deste site, como qualquer outra chamada de API, e gasta a sua cota ou o seu crédito como de costume.

Escolha Criptografado para enviá-la do jeito que o modo criptografado dos SDKs faz: o SDK da Tinfoil verifica o enclave nesta página e depois sela a solicitação para ele. O playground mostra os bytes que de fato saíram da página, o que voltou e o comprovante do enclave para o qual ela foi selada.

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": "Me ajuda a explorar uma ideia."
      }
    ],
    "stream": true
  }'

Autenticação

Envie uma chave de API do Undergrove como token Bearer. As chaves começam com ugk_ e são emitidas por convite durante o alfa. Onde as chaves de autoatendimento estiverem ativadas, os membros do alfa criam até cinco nas configurações do espaço de trabalho, e cada uma gasta a cota e o crédito da conta dela. Guardamos apenas um hash unidirecional de cada chave, então uma chave perdida não pode ser recuperada, apenas substituída.

Cada chave de autoatendimento pode ter os próprios limites, definidos ao criá-la ou depois nas configurações: um limite de gasto diário, depois do qual as solicitações dela são recusadas até a meia-noite UTC, e uma lista dos modelos que ela pode usar. Uma chave com limite continua contando para a cota da conta. As chaves criadas antes de os limites existirem não têm nenhum e continuam funcionando como antes.

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

Endpoints

As respostas usam o formato padrão chat.completion. Os streams enviam eventos chat.completion.chunk e terminam com data: [DONE]. Os modelos de raciocínio transmitem o raciocínio separadamente em delta.reasoning_content, e o último chunk informa o uso de tokens. Se um stream for interrompido, o evento final é um objeto de erro em vez de [DONE], então uma resposta parcial nunca é confundida com uma 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 criptografado

A API padrão é lida pelo nosso gateway na memória para verificar cada solicitação. Para que as solicitações fiquem ilegíveis também para o Undergrove, use o SDK da Tinfoil com a sua chave. Ele verifica a atestação de hardware do enclave e depois criptografa cada solicitação para que só aquele enclave possa lê-la. O nosso retransmissor verifica a sua chave e a sua cota e repassa o 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);

O mesmo cliente acessa embeddings, audio/transcriptions e audio/speech. Como o retransmissor não consegue ler essas solicitações, os modelos são indicados pelo id enclave_model de /v1/models, as respostas voltam no formato da Tinfoil e o uso é estimado a partir do tamanho dos dados criptografados. As cotas e o crédito se aplicam como de costume.

Servidor MCP

O Undergrove também é um servidor Model Context Protocol, em https://undergrove.vercel.app/mcp. Cada modelo real é uma ferramenta, como ask_<model>, que clientes MCP como Claude Code, Cursor e Claude Desktop podem chamar com a sua chave de API. Uma ferramenta recebe um prompt e, opcionalmente, system, max_tokens e, para modelos que pesquisam, web_search, e retorna a resposta do modelo como texto.

Uma chamada de ferramenta é uma solicitação de API como qualquer outra: o gateway a lê na memória, envia pela rota publicada do modelo, não guarda cópia e a desconta dos limites, da cota e do crédito da sua chave. O servidor usa HTTP com streaming, responde em JSON e não mantém sessões. Ele fala as versões de protocolo 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"}'

Depois, chame a ferramenta de um 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."}
    }
  }'

No sentido inverso, o espaço de trabalho pode usar ferramentas de servidores MCP que você conecta nas Configurações. Essas chamadas passam pelo servidor do Undergrove até o servidor que você conectou, em texto simples, então use servidores em que você confia com o que as ferramentas recebem.

Erros e limites

Os erros usam o formato da OpenAI: {"error": {"message", "type", "code"}}.

Durante o alfa, cada chave ou conta tem uma cota por minuto, de solicitações diárias e de gasto diário. Os valores atuais são publicados em /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"
  }
}

Saiba para onde vão os seus dados

O gateway verifica a sua chave, aplica os limites e encaminha à rota do modelo apenas os campos acima. Ele não guarda cópia de prompts ou respostas e não os registra. Os registros dele contêm apenas nomes de rotas, códigos de status e tempos. Os contadores de limite de taxa usam um hash unidirecional da sua chave ou conta e expiram em até dois dias.

O operador, a localização e a retenção de cada rota de modelo são publicados no registro de modelos em /api/status e na página de privacidade. As solicitações nunca passam para outra rota como alternativa. A Vercel, nossa hospedagem, guarda os metadados de solicitação habituais, como endereços IP.

Nas rotas de computação confidencial, o gateway da API verifica a atestação de hardware do enclave antes de se conectar e criptografa cada solicitação para que só aquele enclave possa lê-la. O próprio gateway ainda lê as solicitações de API na memória para verificá-las.

Dados do espaço de trabalho

A sincronização, os links compartilhados e os projetos compartilhados guardam apenas texto cifrado criado pelo navegador. Cada diagrama mostra, passo a passo, quem tem a chave.

O que a verificação comprova

Antes de enviar qualquer coisa, o espaço de trabalho executa no seu navegador o verificador de código aberto da Tinfoil. Ele confere o relatório de atestação de hardware do enclave com as chaves de assinatura da AMD ou da Intel, confere se o código medido no enclave corresponde a uma versão que a Tinfoil publicou e assinou no GitHub e confere se a chave de criptografia que ele usa pertence àquele enclave. Selecione Verificado no espaço de trabalho para ver cada verificação, a versão e a medição.

Isso comprova que as suas mensagens só podem ser descriptografadas por aquele hardware rodando aquele código publicado. Não comprova que o código publicado esteja livre de falhas, não protege contra fraquezas dos próprios processadores e não cobre o que você faz com as respostas depois que elas chegam ao seu navegador. O código do espaço de trabalho é servido pelo Undergrove, então você está confiando que servimos o verificador tal como foi publicado; Verificar esta página compara o código que o seu navegador carregou com o manifesto da build, e npm run verify:site compara o site com a sua própria build do mesmo commit. Está prevista uma avaliação independente.

Cada resposta de um enclave tem um botão Comprovante. Ele mostra o enclave, a versão e as medições verificadas antes do envio daquela solicitação e a chave para a qual ela foi criptografada, e os baixa como JSON. Até a aba ser fechada, o download inclui o relatório de atestação, para que você possa rodar o verificador nele de novo depois; a partir daí, ele contém o hash do relatório e onde buscar o relatório atual do enclave. O comprovante é o registro do seu navegador, não uma declaração assinada, e o enclave que ele indica é o roteador de modelos da Tinfoil; o roteador repassa as solicitações ao enclave do próprio modelo. O comprovante indica também esse enclave, e o seu navegador tenta verificá-lo do mesmo jeito. A maioria dos enclaves de modelos roda em Intel TDX, que o verificador do navegador ainda não consegue verificar; nesses casos, o comprovante informa isso, e a verificação fica a cargo do roteador, cujo código publicado verifica cada enclave de modelo antes de usá-lo.

# 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

Próximos passos