명확하게 개발하세요.

현재 상황

API는 구축과 테스트를 마쳤습니다. 첫 모델 경로가 열릴 때까지 채팅 요청은 503 inference_not_configured를 반환합니다. 실시간 상태는 언제나 https://undergrove.vercel.app/api/status에서 확인할 수 있습니다.

OpenAI API 형식을 따르므로 기본 URL만 바꾸면 기존 SDK가 작동합니다. 이미지가 포함된 채팅, 함수 호출, 구조화된 출력과 함께 임베딩, 음성 텍스트 변환, 음성 합성을 지원합니다. 게이트웨이조차 요청을 읽을 수 없게 하려면 워크스페이스처럼 암호화 모드를 사용하세요.

빠른 시작

기본 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개까지 만들 수 있으며, 각 키는 계정의 일일 한도와 크레딧을 사용합니다. 저희는 각 키의 단방향 해시만 저장하므로, 잃어버린 키는 복구할 수 없고 교체만 할 수 있습니다.

각 셀프 서비스 키에는 만들 때나 나중에 설정에서 별도의 한도를 지정할 수 있습니다. 일일 지출 상한에 도달하면 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도 요청을 읽을 수 없게 하려면 내 키로 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는 https://undergrove.vercel.app/mcp에 있는 Model Context Protocol 서버이기도 합니다. 각 실시간 모델은 ask_<model> 같은 도구이며, Claude Code, Cursor, Claude Desktop 같은 MCP 클라이언트가 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

다음 계획