Boons

A boon is an ability the gateway adds to a model: seeing images, answering in a JSON schema, calling tools, drawing, searching the web, quoting your documents. The gateway does the extra work around the model's own call, so clients send ordinary requests and need no changes.

The boons

Guardrails run on the same engine but are set per tenant, not per model.

Turn a boon on

A boon runs only when it is on for the gateway and the model asks for it. Nothing is granted by default.

1. 1

   Turn it on for the gateway

   Open Settings › Boons. Each boon is a row with its switch, what it is set to, and the models asking for it. A row reads "1 asks, off" when a model has the boon but the switch is off. Open a row to pick its helper model and limits, then save with the save bar. The gateway picks up the change within 15 seconds, with no restart.

   Knowledge is the exception: its row links to the Knowledge page, where retrieval is switched on.

2. 2

   Grant it to a model

   Open the model's page and go to Boons. Switch the boon on and save. A boon that is off in Settings, or has no helper model picked, can't be newly granted; the page says what is missing.

   The tool loop is granted by ticking MCP servers under the model's Tool servers instead. Attaching a knowledge collection to a model grants it Knowledge.

3. 3

   Check it ran

   Send a request and read the x-obleth-boons response header, which lists the boons that acted on it. Settings › Needs you also lists any boon a model asks for while it is off, or is on with no helper model picked.

The same two switches from the Management API:

curl -X PUT http://localhost:9180/api/v1/settings/boons \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "vision_enabled": true, "vision_fallback_model": "glm-4-5v" }'

curl -X PUT http://localhost:9180/api/v1/models/$MODEL_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "upstream_model": "Qwen/Qwen3-8B",
    "api_base": "http://inference.example.internal:8000/v1",
    "boons": ["vision", "structured_output"]
  }'

An omitted settings field keeps its stored value. A model update needs upstream_model and api_base, and leaves other omitted fields unchanged. A model's boons list is trimmed and lowercased, and unknown values are dropped.

Boons compose per request

A model can hold several boons. For each chat request the gateway applies them in a fixed order, and each one runs only if the request calls for it:

1. Vision describes any images.
2. Knowledge captures the retrieval query from the user's own words.
3. Compression compacts JSON and code.
4. The tool loop, image generation and web search add their tools.
5. Compression's dedup, log and lossy passes run.
6. Structured output arms its schema.
7. The tenant's input guardrails scan the request.
8. Knowledge injects the retrieved passages.
9. Speculation decides whether to draft.

Speculation is the only boon that steps aside for others: structured output, output guardrails and a tool loop with real MCP tools all need the model's own answer.

Helper calls and billing

Boons that call another model (the vision describer, the structured-output fixer, tool-loop turns, the speculation drafter and verifier, the image model) or a search tool record that call as its own usage row against the calling tenant and key. Each row has admission = boon, a request_type naming the boon, and the id of the request it served as parent_request_id, so the request's panel in Request logs lists it under Helper calls:

Helper spend counts toward the tenant's and key's term budgets, so a tenant at its cap can't keep spending through boons. Playground and benchmark tenants have their helper rows labelled benchmark, like their other requests. Knowledge's query embeddings and compression are not billed.

Fail-open

A boon never fails a request. No helper model, an upstream error, a timeout or a reply that can't be parsed leaves the request or response as it was, and the model answers on its own. When something was skipped that the client might care about, the response carries x-obleth-boons-warning, for example structured_output_validation_failed.

What callers see

A model's entry on GET /v1/models/{id} and /model/info lists its boons in boon_details, next to its own supports_* flags: whether each boon runs, and which helper model does the work. A text-only model with Vision reports supports_vision: false and names its describer, so a result can be traced to both models. See Model discovery.

The x-obleth-boons header

On a response, the header lists what acted on the request: vision, knowledge, compression, tool_loop, image_generation, web_search, structured_output, guardrails_input, speculation.

On a request, it takes comma-separated tokens:

• off turns every boon off for that request. The tenant's guardrails still run.
• lossy turns compression's lossy pass on for that request. See Compression.