Configuration reference#

Vellum reads one file at startup: vellum.config.json at the project root. Its shape is fully described by a JSON Schema at src/shared/site-schema.json — modern editors will autocomplete and validate the config when you keep the "$schema": "./src/shared/site-schema.json" line at the top.

The schema is generated from src/shared/types.ts by bun run gen:schema; edit the types if you add new fields.

Top-level shape#

{
  "$schema": "./src/shared/site-schema.json",
  "site": {
    /* SiteConfig */
  },
  "repos": [
    /* RepoConfig, ... */
  ],
  "nav": [
    /* NavItem, ... */
  ]
}

site and repos are required; nav is optional and is the site-level top navigation (each repo can override it with vellum.json#nav).

SiteConfig#

AI providers (global pool)#

All three AI features (AI Summary, Ask AI, Machine translation) draw from a single pool of upstream providers declared at site.aiProviders. Each entry is a fully-specified endpoint with its own provider kind, model, base URL, and API key env var. Features either consume the whole pool or narrow it via their own providers whitelist.

Order matters: the worker tries entries left-to-right and falls over to the next on a retryable error (HTTP 401/402/403/429/5xx or network failure). See Failover behaviour below.

"site": {
  "aiProviders": [
    {
      "id": "openrouter",
      "provider": "openai-compatible",
      "baseUrl": "https://openrouter.ai/api/v1",
      "model": "openai/gpt-4o-mini",
      "apiKeyEnv": "VELLUM_AI_API_KEY"     // optional; this is the default
    },
    {
      "id": "openrouter-backup",
      "provider": "openai-compatible",
      "baseUrl": "https://openrouter.ai/api/v1",
      "model": "openai/gpt-4o-mini",
      "apiKeyEnv": "VELLUM_AI_API_KEY_BACKUP"
    },
    {
      "id": "anthropic",
      "provider": "anthropic",
      "model": "claude-haiku-4-5",
      "apiKeyEnv": "VELLUM_AI_API_KEY_ANTHROPIC"
    },
    {
      "id": "workers-ai",
      "provider": "workers-ai",
      "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
    }
  ]
}

Credentials live in worker env vars, not the config file:

• VELLUM_AI_API_KEY — bearer / x-api-key for openai-compatible and anthropic providers. workers-ai doesn’t need one. Override per entry with apiKeyEnv to stage multiple keys.

• VELLUM_AI_BASE_URL — legacy global override. Wins over every provider entry’s baseUrl when set; useful when one config ships to multiple environments that all share a single gateway.

• VELLUM_TURNSTILE_SECRET — paired with feature-level turnstileSiteKey. Set both or neither; half-configured Turnstile fails closed.

For workers-ai, the AI binding is declared in wrangler.jsonc ("ai": { "binding": "AI" }).

Multiple keys per provider#

When a provider has multiple keys that each carry independent quotas (common for OpenRouter / Together / Groq free tiers), Vellum supports two ways to stage them. Both expand into separate failover attempts.

Option A — array of env var names. Each name expands into its own attempt, sharing everything else.

{
  "id": "openrouter",
  "provider": "openai-compatible",
  "baseUrl": "https://openrouter.ai/api/v1",
  "model": "openai/gpt-4o-mini",
  "apiKeyEnv": [
    "VELLUM_AI_API_KEY",
    "VELLUM_AI_API_KEY_BACKUP",
    "VELLUM_AI_API_KEY_THIRD"
  ]
}

Option B — one env var, one key per line. Easier to operate when you don’t want to juggle N secrets. The env var’s value is split on newlines (LF / CRLF / CR all work); each non-empty line becomes a separate attempt labelled ${envName}#1, #2, … in log lines.

{
  "id": "openrouter",
  "provider": "openai-compatible",
  "baseUrl": "https://openrouter.ai/api/v1",
  "model": "openai/gpt-4o-mini",
  "apiKeyEnv": "VELLUM_AI_API_KEYS"
}

wrangler secret put VELLUM_AI_API_KEYS
# paste at the prompt:
# sk-or-v1-abc...
# sk-or-v1-def...
# sk-or-v1-ghi...

The two options stack: apiKeyEnv: ["FOO", "BAR"] with FOO holding two newline-separated keys and BAR holding one runs four attempts in order (FOO#1, FOO#2, BAR). At resolve time the worker walks the resulting list left-to-right, falling over to the next key on any retryable error.

Provider body extensions#

Some provider features aren’t exposed by Vellum’s first-class fields: DeepSeek’s thinking mode, Anthropic’s extended thinking, extra sampling params, custom headers via OpenRouter routing, etc. The extraBody field on an AiProvider entry is merged verbatim into the provider’s request body before the worker’s required fields:

[
  // DeepSeek thinking mode via vLLM-flavoured kwargs.
  {
    "id": "deepseek-reasoning",
    "provider": "openai-compatible",
    "baseUrl": "https://api.deepseek.com",
    "model": "deepseek-chat",
    "apiKeyEnv": "VELLUM_AI_API_KEY_DEEPSEEK",
    "extraBody": {
      "chat_template_kwargs": { "enable_thinking": true }
    }
  },
  // Anthropic extended thinking — passed through verbatim to /v1/messages.
  {
    "id": "claude-thinking",
    "provider": "anthropic",
    "model": "claude-opus-4-7",
    "apiKeyEnv": "VELLUM_AI_API_KEY_ANTHROPIC",
    "extraBody": {
      "thinking": { "type": "enabled", "budget_tokens": 4000 }
    }
  },
  // Extra sampling tuning that the worker doesn't expose directly.
  {
    "id": "openrouter-creative",
    "provider": "openai-compatible",
    "baseUrl": "https://openrouter.ai/api/v1",
    "model": "openai/gpt-4o",
    "apiKeyEnv": "VELLUM_AI_API_KEY",
    "extraBody": {
      "top_p": 0.95,
      "presence_penalty": 0.1
    }
  }
]

extraBody merges with lower precedence than the worker’s structural fields. That means model, messages, stream, system, and tools always win — so a stray extraBody.model can’t accidentally break the streaming setup. Tunable params (temperature, max_tokens, top_p, …) live at higher precedence than the runner’s defaults, so extraBody.temperature does override the worker’s translate-time temperature of 0.

For workers-ai entries the same object is merged into the env.AI.run input — same precedence rules apply.

AI Summary#

Mirrors Microsoft Learn’s “AI Summary” button. When site.aiSummary is set, every doc page shows a small pill button below the title; clicking it streams a 2–4 paragraph summary into an expandable card.

"site": {
  "aiSummary": {
    "turnstileSiteKey": "0x4AAA...",
    "cacheTtlSeconds": 604800
  }
}

Ask AI#

A chat drawer triggered from the NavBar. The visitor types a question; the AI runs an agent loop with docs tools and streams the answer back. Configure with site.aiChat:

"site": {
  "aiChat": {
    "turnstileSiteKey": "0x4AAA...",
    "maxIterations": 6
  }
}

The AI has these tools and uses them on its own:

• search_docs(query, repo?, locale?) — full-text search; up to 10 hits.

• fetch_page(repo, page, locale?) — read a specific page as plain text.

• list_repos() — enumerate the repos on this site.

• list_pages(repo, locale?) — list every page in a repo.

Credentials reuse the env vars declared in AI providers. One extra secret unique to chat:

• VELLUM_SESSION_SECRET — HMAC key (32+ bytes) used to sign the chat session tokens issued by /api/ai/session. Set with wrangler secret put in production; rotate to invalidate every active session.

MCP server#

The same docs tools are exposed at /api/mcp as a JSON-RPC 2.0 endpoint speaking the Model Context Protocol. External MCP clients (Claude Desktop, ChatGPT Connectors, mcp-inspector, custom agents) can connect to this URL and call the tools directly — no API key required, since a docs site is already public.

To wire it into Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "vellum-docs": {
      "url": "https://docs.example.com/api/mcp"
    }
  }
}

The endpoint is read-only: it implements initialize, tools/list, tools/call, and ping. There are no resources, prompts, or sampling calls.

Machine translation#

site.translate enables machine translation of page bodies, sidebars, repo nav, frontmatter, the UI dictionary, and vellum.config.json strings. Translations are cached in a D1 database, refreshed on webhook push, and pruned on an hourly cron tick when older than refreshDays.

"site": {
  "translate": {
    "targets": ["zh-CN", "zh-TW", "ja", "ko", "es", "pt-BR"],
    "refreshDays": 5
  }
}

Credentials reuse the env vars declared in AI providers. The new piece is the D1 database that backs the cache:

• VELLUM_TRANSLATION_DB — D1 binding declared in wrangler.jsonc. Create with wrangler d1 create vellum-translations, paste the returned UUID into the binding, then wrangler d1 migrations apply vellum-translations --remote.

The binding is optional at runtime — without it the translation layer no-ops and MT-target locales fall back to the default-locale source.

See Internationalisation → Machine translation for the full story: what’s translated, how the prompt preserves markdown syntax, refresh behaviour, and cost shape.

Failover behaviour#

Every AI feature shares the same failover loop. The worker walks site.aiProviders (or the feature’s filtered subset) left-to-right, trying each provider until one succeeds. Common setups:

• Same provider, multiple keys. Add the same provider + baseUrl twice with different apiKeyEnv values to stage two OpenRouter keys with independent quotas.

• Mixed providers as last resort. Put a free-tier OpenRouter entry first, an Anthropic entry second, and Workers AI last — readers always get something, even when the upstream goes down.

What triggers a failover#

The worker classifies these upstream conditions as “used up” and tries the next endpoint:

Other 4xx codes (400 bad request, 404 model missing) propagate without retry — they’re content / config problems and re-issuing the same payload elsewhere just burns the fallback budget for the same outcome.

Streaming-safe semantics#

For aiSummary and aiChat, the SSE stream begins after the upstream returns 2xx. Failover only fires before any bytes are written to the client — once the worker has emitted a token event, it’s committed to the current endpoint. Mid-stream errors propagate to the client as a single error event; no duplicate tokens.

For translate, the call is single-shot (no streaming to client), so every retry is a clean POST.

Compatibility with aiChat#

aiChat runs a tool-calling agent loop with provider-specific request / response shapes. The loop locks to a single API shape based on the first provider in the pool that the feature would use:

• OpenAI-compatible / Workers AI: the OpenAI chat-completions shape. Failover skips past any anthropic entries.

• Anthropic: the Messages-API shape. Failover skips past openai-compatible and workers-ai entries.

To explicitly pin chat to one shape regardless of pool order, set aiChat.providers to just the ids you want.

Env vars and logging#

Each endpoint’s apiKeyEnv names the env var the worker reads its key from. Stage them with wrangler secret put:

wrangler secret put VELLUM_AI_API_KEY               # primary
wrangler secret put VELLUM_AI_API_KEY_BACKUP        # fallback #1
wrangler secret put VELLUM_AI_API_KEY_ANTHROPIC     # fallback #2

Every failover decision logs to wrangler tail / wrangler dev under the per-feature tag:

[vellum][summarize] endpoint #1 (openai-compatible, key=VELLUM_AI_API_KEY) failed (Upstream 429: rate limit exceeded); trying #2
[vellum][summarize] failover ok: succeeded on endpoint #2 (openai-compatible)

A line that mentions “all N endpoints exhausted” means every entry in the chain returned a retryable error — usually a sign that a provider- wide outage is in progress and you should add more diverse fallbacks.

RepoConfig#

A repo is a slice of documentation — one section in the URL space (/<slug>/...), one sidebar, one search index. You’ll typically have one RepoConfig per actual GitHub repo you’re documenting, plus optional local sources for your handbook and landing page.

¹ Conditionally required: the JSON schema enforces owner / repo / branch when source is "github" (or omitted).

{
  "slug": "prism",
  "owner": "siiway",
  "repo": "prism",
  "branch": "main",
  "docsRoot": "docs",
  "displayName": "Prism",
  "description": "Self-hosted OAuth 2.0 / OpenID Connect on Cloudflare Workers.",
  "logo": "https://icons.siiway.org/prism/icon.svg",
  "editLinkPattern": "https://github.com/siiway/prism/edit/main/docs/:path",
  "versions": [
    { "label": "main", "branch": "main", "default": true },
    { "label": "v1", "branch": "v1" }
  ]
}

NavItem#

The site-level top nav. Per-repo navs (from vellum.json#nav or VitePress themeConfig.nav) take precedence when a reader is inside that repo.

² Exactly one of link / items must be set (enforced by the JSON schema’s oneOf).

Environment variables#

Set these in wrangler.jsonc#vars (or wrangler secret put for secrets):

KV is bound separately in wrangler.jsonc#kv_namespaces. Without it, the worker falls back to the per-edge Cache API alone.

Bindings#

Beyond env vars, the worker has these Cloudflare bindings:

Cron triggers are declared under wrangler.jsonc#triggers.crons. The default is "0 * * * *" (top of every hour) — used by the translation refresher to prune stale rows.

Regenerating the schema#

When you edit src/shared/types.ts:

bun run gen:schema

This re-derives src/shared/site-schema.json from the TypeScript types, preserving the curated descriptions, regex patterns, and conditional requireds defined in scripts/gen-site-schema.ts.