---
title: Profiles, side requests and gears
description: Re-target aliases per request with route profiles, give side requests their own body defaults, and publish gears that clients list.
section: orchestrator
order: 30
audience: [operator, builder, agent]
sources: [services/go-orchestrator/internal/config/config.go, services/go-orchestrator/internal/config/gears.go, docs/architecture.md, services/go-orchestrator/AGENTS.md, config/orchestrator.yaml]
features: [orchestrator.config-profiles, orchestrator.config-side-requests, orchestrator.config-gears, orchestrator.config-gears-locked, orchestrator.config-gears-source, orchestrator.api-gears]
---

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}

```yaml
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
```

```bash
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 {#side-requests}

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:

```yaml
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](/docs/orchestrator/configuration.md#response-cache)).

## Gears {#gears}

```yaml
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
```

```bash
curl -s http://127.0.0.1:8787/v1/gears -H "Authorization: Bearer $VENOM_API_KEY"
```

```json
{"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](/docs/configuration.md).

## Errors {#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](/docs/orchestrator/routing.md), [Keys, budgets and limits](/docs/orchestrator/keys-and-budgets.md) (a key's default profile), [Batches, files and service tiers](/docs/orchestrator/batches-and-files.md#service-tiers).
