לבנות בבהירות.

איפה אנחנו עומדים

ה־API בנוי ונבדק. עד שייפתח מסלול המודל הראשון, בקשות צ׳אט מחזירות 503 inference_not_configured. המצב העדכני תמיד זמין ב־https://undergrove.vercel.app/api/status.

הוא עוקב אחרי הפורמט של OpenAI API, כך שערכות SDK קיימות עובדות אחרי שינוי כתובת הבסיס: צ׳אט עם תמונות, קריאה לפונקציות ופלטים מובנים, וגם embeddings, תמלול ודיבור. כדי שהבקשות יישארו בלתי קריאות אפילו לשער שלנו, השתמשו במצב מוצפן, כמו שסביבת העבודה עושה.

התחלה מהירה

כתובת בסיס: 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. היא עוברת מהדפדפן שלכם אל /v1 של האתר הזה, כמו כל קריאת API אחרת, ומנצלת את המכסה או הקרדיט שלכם כרגיל.

בחרו מוצפן כדי לשלוח אותה כמו שהמצב המוצפן של ערכות ה־SDK עושה: ה־SDK של Tinfoil מאמת את המובלעת בדף הזה, ואז אוטם אליה את הבקשה. סביבת הניסויים מציגה את הבייטים שבאמת יצאו מהדף, את מה שחזר, ואת הקבלה של המובלעת שאליה הבקשה נאטמה.

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

אימות זהות

שלחו מפתח API של Undergrove כ־Bearer token. מפתחות מתחילים ב־ugk_ וניתנים בהזמנה בתקופת האלפא. כשמפתחות בשירות עצמי מופעלים, חברי האלפא יוצרים עד חמישה מפתחות בהגדרות של סביבת העבודה, וכל אחד מהם מנצל את המכסה והקרדיט של החשבון שלו. אנחנו שומרים רק גיבוב חד־כיווני של כל מפתח, ולכן אי אפשר לשחזר מפתח שאבד, רק להחליף אותו.

לכל מפתח בשירות עצמי יכולות להיות מגבלות משלו, שנקבעות כשהוא נוצר או אחר כך בהגדרות: תקרת הוצאה יומית, שאחריה הבקשות שלו נדחות עד חצות UTC, ורשימה של המודלים שמותר לו להשתמש בהם. מפתח עם תקרה עדיין נספר במכסה של החשבון שלו. למפתחות שנוצרו לפני שהיו מגבלות אין מגבלות, והם ממשיכים לעבוד כמו קודם.

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, השתמשו ב־SDK של Tinfoil עם המפתח שלכם. הוא מאמת את אטסטציית החומרה של המובלעת, ואז מצפין כל בקשה כך שרק המובלעת הזו יכולה לקרוא אותה. הממסר שלנו בודק את המפתח ואת המכסה שלכם ומעביר הלאה את הטקסט המוצפן.

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. מכיוון שהממסר לא יכול לקרוא את הבקשות האלה, המודלים נקראים לפי מזהה ה־enclave_model שלהם מ־/v1/models, התשובות חוזרות בפורמט של Tinfoil, והשימוש מוערך לפי גודל הנתונים המוצפנים. המכסות והקרדיט חלים כרגיל.

שרת MCP

Undergrove הוא גם שרת Model Context Protocol, בכתובת https://undergrove.vercel.app/mcp. כל מודל חי הוא כלי, כמו ask_<model>, שלקוחות MCP כמו Claude Code, Cursor ו־Claude Desktop יכולים לקרוא לו עם מפתח ה־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"}}.

בתקופת האלפא, לכל מפתח או חשבון יש מכסת בקשות לדקה, מכסת בקשות יומית ומכסת הוצאה יומית. הערכים הנוכחיים מפורסמים ב־/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"
  }
}

לדעת לאן הנתונים שלכם הולכים

השער בודק את המפתח שלכם, מחיל מגבלות, ומעביר למסלול המודל רק את השדות שלמעלה. הוא לא שומר עותק של פרומפטים או תשובות ולא רושם אותם ביומן. היומנים שלו מתעדים רק שמות מסלולים, קודי סטטוס ותזמונים. מוני מגבלת הקצב משתמשים בגיבוב חד־כיווני של המפתח או החשבון שלכם ופגים תוך יומיים.

המפעיל, המיקום ומדיניות השמירה של כל מסלול מודל מפורסמים במרשם המודלים ב־/api/status ובדף הפרטיות. בקשות אף פעם לא עוברות למסלול אחר כגיבוי. Vercel, המארחת שלנו, שומרת מטא־נתונים רגילים של בקשות, כמו כתובות IP.

במסלולי מחשוב חסוי, שער ה־API מאמת את אטסטציית החומרה של המובלעת לפני ההתחברות ומצפין כל בקשה כך שרק המובלעת הזו יכולה לקרוא אותה. השער עצמו עדיין קורא בקשות API בזיכרון כדי לבדוק אותן.

נתוני סביבת העבודה

סנכרון, קישורים משותפים ופרויקטים משותפים שומרים רק טקסט מוצפן שהדפדפן יצר. כל תרשים מראה, צעד אחר צעד, למי יש את המפתח.

מה האימות מוכיח

לפני שהיא שולחת משהו, סביבת העבודה מריצה בדפדפן שלכם את המאמת בקוד פתוח של Tinfoil. הוא בודק את דוח אטסטציית החומרה של המובלעת מול מפתחות החתימה של AMD או של Intel, בודק שהקוד שנמדד במובלעת תואם לגרסה ש־Tinfoil פרסמה וחתמה ב־GitHub, ובודק שמפתח ההצפנה שהוא משתמש בו שייך למובלעת הזו. בחרו מאומת בסביבת העבודה כדי לראות כל בדיקה, את הגרסה ואת המדידה.

זה מוכיח שההודעות שלכם יכולות להיות מפוענחות רק על ידי החומרה הזו כשהיא מריצה את הקוד שפורסם. זה לא מוכיח שהקוד שפורסם נקי מפגמים, לא מגן מפני חולשות במעבדים עצמם, ולא מכסה את מה שאתם עושים בתשובות אחרי שהן מגיעות לדפדפן שלכם. הקוד של סביבת העבודה מוגש על ידי Undergrove, כך שאתם סומכים עלינו שנגיש את המאמת כפי שפורסם; אימות הדף הזה משווה את הקוד שהדפדפן שלכם טען למניפסט של ה־build, ו־npm run verify:site משווה את האתר ל־build שאתם בונים בעצמכם מאותו commit. מתוכננת הערכה עצמאית.

לכל תשובה ממובלעת יש לחצן קבלה. הוא מציג את המובלעת, הגרסה והמדידות שאומתו לפני שהבקשה נשלחה ואת המפתח שאליו היא הוצפנה, ומוריד אותם כ־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

מה הלאה