Skip to content
Docs menu

Profiles, side requests and gears

Re-target aliases per request with route profiles, give side requests their own body defaults, and publish gears that clients list.

View .md

Three config sections shape requests without changing the routes themselves:

  • profiles: are named re-targetings of aliases, picked per request with the x-venom-profile header or per client key. Use one for a data-residency rule ("Chinese-developed models only"), a provider preference or a cheaper evaluation lane.
  • side_requests: set body defaults (output cap, effort) for a client's side calls, recognised by the suffix of x-venom-session.
  • gears: are presets of models, thinking level and profile that the orchestrator only validates and serves at GET /v1/gears; the venom CLI lists them next to its own.

Route profiles

profiles:
  qwen-first:
    description: Qwen first on every venom-* alias, then the usual fallbacks
    routes:
      venom-default: [qwen/qwen3.8-max, qwen/qwen3.7-plus, "*"]
      venom-fast:    [qwen/qwen3.8-flash, "*"]
  china:
    allow: [qwen/qwen*, qwen/deepseek*, qwen/kimi*, qwen/glm*, zai/glm*, ollama/qwen*, vllm/Qwen/*]
    routes:
      venom-decide: []        # not served under this profile
  eval:
    defaults: {service_tier: flex}
    flex_timeout: 10m
curl -s http://127.0.0.1:8787/v1/chat/completions -H "Authorization: Bearer $VENOM_API_KEY" \
  -H "x-venom-profile: china" -H "Content-Type: application/json" \
  -d '{"model":"venom-default","messages":[{"role":"user","content":"hi"}]}'
Key Type Default What it does
profiles.<name> map The name must match [a-z0-9][a-z0-9._-]{0,63}. An empty profile is an error.
description string none Shown by admin views.
routes.<alias> list the alias's own targets Replaces the alias's targets, in order. Entries are upstream/model, or "*" once for the alias's own targets not already listed. [] means the alias is not served under the profile (404 model_not_found). Strategy, ttft_timeout and images stay the alias's own; an experiment alias can't be re-targeted.
allow list of globs none (everything) Patterns over upstream/model (* matches any characters, / included). Every candidate a request could reach (targets, "*" expansions, the images route, direct and bare ids) must match one; when none is left the answer is 403 profile_forbidden.
defaults map none Body defaults for every request under the profile, same keys as side_requests below; a side kind's own value wins.
flex_timeout duration 0 (usual deadlines) Time to first byte allowed an attempt sent with service_tier: flex; replaces the route's ttft_timeout and, when longer, the upstream's timeout.

Selection: the x-venom-profile header wins; without it, the client key's default profile (set with POST /admin/v1/keys or PATCH /admin/v1/keys/{id}). An unknown name is 400 unknown_profile, listing the configured ones; a request is never routed without the profile it asked for. Answers carry x-venom-profile, the request log records it, and GET /v1/models lists the configured profile names in a top-level profiles array so a client can check before it sends one.

The shipped china profile reaches only Qwen, GLM, Kimi and DeepSeek on Model Studio or Z.ai, or a Qwen model on your own Ollama or vLLM; venom-decide is not served under it. qwen-first puts Qwen first on every venom-* alias.

Side requests and request defaults

A client marks a side call by suffixing its session header: x-venom-session: <session>:<kind>. The venom CLI does this for its auto-mode classifier, prompt hooks, vision descriptions and decisions. Each kind listed under side_requests: gets these fields set when the request carries none, and only where the target model takes them:

side_requests:
  auto-classifier: {max_completion_tokens: 512, reasoning_effort: minimal, verbosity: low}
  hook:            {max_completion_tokens: 2048, reasoning_effort: low, verbosity: low}
  decide:          {max_completion_tokens: 4096, reasoning_effort: low}
  vision:          {max_completion_tokens: 2048, reasoning_effort: low}
Key Values What it does
max_completion_tokens int ≥ 0 Output cap when the request names none (sent as max_tokens where the kind needs it; max_output_tokens on /v1/responses).
reasoning_effort auto, none, minimal, low, medium, high, xhigh, max The effort asked of a model that reasons by default at a higher one; never raised above the model's default. auto picks one per request from its last turns (a failed tool result high, a trivial edit low), between effort_min and effort_max.
effort_min, effort_max none … max Bounds for auto (default low..high); they need reasoning_effort: auto.
verbosity low, medium, high For OpenAI's GPT-5 family only.
service_tier auto, default, flex, priority For OpenAI models that take it; a flex 429 is retried at once on the default tier.

Kind names must match the header suffix pattern; main-session turns never get side defaults, so the main prompt cache is untouched. Side kinds at temperature 0, or listed in response_cache.kinds, can be answered from the response cache (Configuration reference).

Gears

gears_locked: false
gears_source: orchestrator
gears:
  - name: eco
    key: 1
    description: the cheap model, no thinking
    model: [venom-fast, openai/gpt-5.4-nano]
    thinking: "off"
    workers: {model: venom-fast}
    roles:
      smart:   {model: [venom-default, venom-fast]}
      vision:  {model: venom-vision}
      summary: {model: venom-fast, service_tier: flex}
  - name: china
    key: 4
    model: venom-default
    profile: china          # every request of the session sends x-venom-profile: china
curl -s http://127.0.0.1:8787/v1/gears -H "Authorization: Bearer $VENOM_API_KEY"
{"object": "list", "source": "orchestrator", "locked": false,
 "gears": [{"name": "eco", "key": 1, "description": "the cheap model, no thinking",
            "model": ["venom-fast", "openai/gpt-5.4-nano"], "thinking": "off",
            "workers": {"model": "venom-fast"},
            "roles": {"smart": {"model": ["venom-default", "venom-fast"]},
                      "vision": {"model": "venom-vision"},
                      "summary": {"model": "venom-fast", "service_tier": "flex"}}}]}
Key Type Default What it does
gears list [] The presets GET /v1/gears serves (same auth as /v1/models; always 200).
gears[].name string required 1–64 of a-z 0-9 . _ -, unique.
gears[].key 1–9 none The number key a client binds it to; unique.
gears[].description string none One line for the client's list.
gears[].model string or list required A route alias, a models: id or upstream/model on a configured upstream (a trailing * matches by prefix in the client). In a list the first one served wins.
gears[].thinking off, minimal, low, medium, high, xhigh none The thinking level for the main model.
gears[].profile profile name or null none A configured route profile, sent as x-venom-profile on every request the session makes; null means explicitly none.
gears[].service_tier auto, default, flex, priority, batch none What the main row's requests ask for: sent as x-venom-service-tier, or x-venom-urgency: batch for batch.
gears[].workers role none The model (and profile, thinking, service_tier) for subagents.
gears[].roles map none Per-role settings for smart, vision, browser, classifier, summary and reflex, each with model, profile, thinking, service_tier. A role does not inherit the main row's tier.
gears_locked bool false Tells clients to offer only these gears.
gears_source string orchestrator The source field of the response (Venom Cloud serves the same shape with its own source).

The orchestrator validates gears at load and reload (every model must resolve, every profile must exist, keys must be unique) and never applies them; the client does. A field absent in the config is absent in the response, and model keeps the form it was written in. The CLI's own gears and its gear wizard are in the Configuration section.

Errors

Status Code Cause
400 unknown_profile the header (or a key's default, after a reload removed it) names no profile
403 profile_forbidden nothing the request could reach passes the profile's allow list
404 model_not_found the alias is [] under the profile

Config errors name the profile, alias, gear or field: an alias that isn't configured, an entry that is neither upstream/model nor "*", "*" twice, a gear model that resolves to nothing, a duplicate gear key.