ابنِ بوضوح.

أين وصلنا

بُنيت واجهة 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. ينتقل الطلب من متصفحك إلى /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. تبدأ المفاتيح بـ 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 كأي طلب آخر: تقرؤه البوابة في الذاكرة، وترسله عبر المسار المنشور للنموذج، ولا تحتفظ بأي نسخة، وتحتسبه ضمن حدود مفتاحك وحصته ورصيده. يستخدم الخادم 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 شيفرة مساحة العمل، لذا فأنت تثق بأننا نقدّم المُحقِّق كما هو منشور؛ وتقارن تحقّق من هذه الصفحة الشيفرة التي حمّلها متصفحك ببيان البناء، ويقارن 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

ما التالي