わかりやすく、作る。

現在の状況

APIは構築とテストが完了しています。最初のモデルのルートが公開されるまで、チャットのリクエストは 503 inference_not_configured を返します。最新の状態は常に https://undergrove.vercel.app/api/status にあります。

OpenAI の API 形式に従っているため、既存の SDK はベースURLを変えるだけで使えます。画像付きのチャット、関数呼び出し、構造化出力に加え、埋め込み、文字起こし、音声合成に対応しています。リクエストをゲートウェイからも読めないようにするには、ワークスペースと同じく暗号化モードを使ってください。

クイックスタート

ベースURL：https://undergrove.vercel.app/v1。GET /v1/models でモデルを一覧し、回答をストリーミングします：

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

プレイグラウンド

このページから自分のキーでチャットのリクエストを送り、回答、利用量、生のレスポンスを、同じリクエストの curl とともに確認できます。ほかのAPI呼び出しと同じく、ブラウザからこのサイトの /v1 に送られ、通常どおり利用枠またはクレジットを消費します。

「暗号化」を選ぶと、SDK の暗号化モードと同じ方法で送信します。Tinfoil の SDK がこのページでエンクレーブを検証し、そのエンクレーブ宛てにリクエストを封印します。プレイグラウンドには、実際にページから出ていったバイト、戻ってきたもの、封印先のエンクレーブのレシートが表示されます。

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": "アイデアを広げるのを手伝って。"
      }
    ],
    "stream": true
  }'

認証

Undergrove の API キーを Bearer トークンとして送ります。キーは ugk_ で始まり、アルファ期間中は招待制で発行します。セルフサービスのキーが有効な場合、アルファのメンバーはワークスペースの設定で5つまで作成でき、各キーはそのアカウントの利用枠とクレジットを消費します。保存するのは各キーの一方向ハッシュだけなので、紛失したキーは復元できず、作り直すことになります。

セルフサービスのキーには、作成時またはあとから設定で、個別の上限を付けられます。1日の支出上限（超えると UTC の午前0時までリクエストを拒否）と、使えるモデルの一覧です。上限付きのキーも、アカウントの利用枠に計上されます。上限の機能ができる前に作ったキーには上限がなく、これまでどおり使えます。

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

エンドポイント

レスポンスは標準の chat.completion の形式です。ストリームは chat.completion.chunk イベントを送り、data: [DONE] で終わります。推論モデルは推論を delta.reasoning_content で別にストリーミングし、最後のチャンクでトークンの利用量を報告します。ストリームが途中で切れた場合、最後のイベントは [DONE] ではなくエラーオブジェクトになるため、途中までの回答を完全な回答と取り違えることはありません。

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

パラメーター

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

暗号化モード

標準の API では、ゲートウェイが各リクエストを確認するためにメモリ上で読みます。Undergrove からもリクエストを読めないようにするには、キーとともに Tinfoil の SDK を使ってください。SDK はエンクレーブのハードウェアアテステーションを検証し、そのエンクレーブだけが読めるように各リクエストを暗号化します。リレーはキーと利用枠を確認し、暗号文を中継します。

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

同じクライアントで embeddings、audio/transcriptions、audio/speech にも届きます。リレーはこれらのリクエストを読めないため、モデルは /v1/models の enclave_model の id で指定し、回答は Tinfoil の形式で返り、利用量は暗号化データのサイズから見積もります。利用枠とクレジットは通常どおり適用されます。

MCP サーバー

Undergrove は Model Context Protocol のサーバーでもあり、https://undergrove.vercel.app/mcp で提供しています。各ライブモデルは ask_<model> のようなツールで、Claude Code、Cursor、Claude Desktop などの MCP クライアントから API キーで呼び出せます。ツールは prompt と、任意で system、max_tokens、検索できるモデルでは web_search を受け取り、モデルの回答をテキストで返します。

ツールの呼び出しは、ほかのAPIリクエストと同じです。ゲートウェイはメモリ上でそれを読み、モデルの公開ルートで送り、コピーは保持せず、キーの上限、利用枠、クレジットから差し引きます。サーバーは Streamable HTTP を使い、JSON で応答し、セッションは保持しません。プロトコルのバージョン 2025-11-25、2025-06-18、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"}'

次に、モデルのツールを呼び出します：

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

逆に、ワークスペースは設定で接続した MCP サーバーのツールを使えます。その呼び出しは Undergrove のサーバーを経由して、接続したサーバーに平文で届きます。ツールに渡す内容を任せられるサーバーを使ってください。

エラーと上限

エラーは OpenAI の形式です：{"error": {"message", "type", "code"}}。

アルファ期間中、各キーまたはアカウントには、1分あたり、1日のリクエスト数、1日の支出の利用枠があります。現在の値は /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"
  }
}

データの行き先を知る

ゲートウェイはキーを確認し、上限を適用して、上記のフィールドだけをモデルのルートに転送します。プロンプトや回答のコピーは保持せず、記録もしません。ログに残るのは、ルート名、ステータスコード、所要時間だけです。レート制限のカウンターはキーまたはアカウントの一方向ハッシュを使い、2日以内に失効します。

各モデルのルートの運営者、所在地、保持期間は、/api/status のモデルレジストリとプライバシーのページで公開しています。リクエストが別のルートに切り替わることはありません。ホスティング先の Vercel は、IPアドレスなどの一般的なリクエストのメタデータを保持します。

コンフィデンシャルコンピューティングのルートでは、APIゲートウェイが接続前にエンクレーブのハードウェアアテステーションを検証し、そのエンクレーブだけが読めるように各リクエストを暗号化します。ただし、ゲートウェイ自身は確認のためにAPIリクエストをメモリ上で読みます。

ワークスペースのデータ

同期、共有リンク、共有プロジェクトが保存するのは、ブラウザが作った暗号文だけです。各図で、誰が鍵を持っているかを一歩ずつ示します。

検証が証明すること

何かを送る前に、ワークスペースは Tinfoil のオープンソースの検証機能をブラウザで実行します。エンクレーブのハードウェアアテステーションレポートを AMD または Intel の署名鍵で確認し、エンクレーブで測定されたコードが Tinfoil が GitHub で公開・署名したリリースと一致すること、使用する暗号鍵がそのエンクレーブのものであることを確かめます。ワークスペースで検証済みを選ぶと、各チェック、リリース、測定値を確認できます。

メッセージを復号できるのは、その公開コードを実行するそのハードウェアだけであることを証明します。公開コードに欠陥がないこと、プロセッサ自体の弱点への対策、回答がブラウザに届いたあとの扱いまでは証明しません。ワークスペースのコードは Undergrove が配信しているため、検証機能を公開どおりに配信していることについては私たちを信頼していただく必要があります。このページを検証 はブラウザが読み込んだコードをビルドマニフェストと比較し、npm run verify:site はサイトを同じコミットからのあなた自身のビルドと比較します。独立した評価を予定しています。

エンクレーブからの各回答にはレシートボタンがあります。そのリクエストを送る前に検証したエンクレーブ、リリース、測定値と、暗号化に使った鍵を表示し、JSON としてダウンロードできます。タブを閉じるまでは、ダウンロードにアテステーションレポートが含まれるため、あとで検証機能を再実行できます。その後は、レポートのハッシュと、エンクレーブの最新のレポートの取得先が含まれます。レシートはブラウザの記録で、署名された証明ではありません。示されるエンクレーブは Tinfoil のモデルルーターで、ルーターがリクエストをモデル自身のエンクレーブに渡します。レシートにはそのエンクレーブも記され、ブラウザは同じ方法で検証を試みます。ほとんどのモデルのエンクレーブは Intel TDX で動いており、ブラウザの検証機能はまだそれを確認できません。その場合はレシートにそう記され、確認は、各モデルのエンクレーブを使う前に検証する公開コードを持つルーターに依存します。

# 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

今後の予定