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.
Three config sections shape requests without changing the routes themselves:
profiles:are named re-targetings of aliases, picked per request with thex-venom-profileheader 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 ofx-venom-session.gears:are presets of models, thinking level and profile that the orchestrator only validates and serves atGET /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: 10mcurl -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: chinacurl -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.
Related
- Routes and strategies, Keys, budgets and limits (a key's default profile), Batches, files and service tiers.