---
title: Model provider
description: Point harness sessions at any OpenAI-compatible server, map venom's model aliases to real models, and understand the provider's errors and model discovery.
section: harness
order: 50
audience: [builder, agent]
sources: [packages/harness/src/provider/index.ts, packages/harness/src/extensions/provider.ts, packages/harness/AGENTS.md]
features: [harness.provider]
---

Sessions talk to one OpenAI-compatible chat-completions server through venom's provider. That can be the venom orchestrator, Venom Cloud, vLLM, SGLang, llama.cpp, Ollama, LM Studio, or a hosted provider's OpenAI endpoint. `@venom/harness/provider` holds the pure parts (options, discovery, prices, error text); the root entry wires them into sessions.

## Configure it {#configure}

```ts
import { createHarness, provider } from "@venom/harness";

// From an environment map you choose to pass:
const fromEnv = provider.providerOptionsFromEnv(process.env);

// Or explicitly:
const harness = createHarness({
  provider: {
    baseUrl: "https://cloud.usevenom.dev/v1",
    apiKey: process.env.MYAPP_VENOM_KEY,    // a vck_… key; never log it
    defaultModel: "venom-default",
  },
});
```

| Option | Env var (`providerOptionsFromEnv`) | Default | Meaning |
|---|---|---|---|
| `baseUrl` | `VENOM_BASE_URL` | `http://localhost:8787/v1` | the server, including `/v1` |
| `apiKey` | `VENOM_API_KEY` | none (no `Authorization` header) | bearer key |
| `defaultModel` | `VENOM_MODEL` | `venom-default` | model when a session names none |
| `aliasMap` | `VENOM_ALIAS_MAP` (`venom-default=gpt-5.4-mini,venom-fast=…`) | automatic, see below | rewrite venom aliases to the server's model ids |
| `contextWindow` | `VENOM_CONTEXT_WINDOW` | the server's report, else 131072 | a cap: each model gets `min(server window, contextWindow)` |
| `maxTokensField` | `VENOM_MAX_TOKENS_FIELD` | `max_completion_tokens` | which request field carries the output limit |
| `adminToken` | `VENOM_ADMIN_TOKEN` | none | the orchestrator's admin token: `/cost` reads the orchestrator's figures for the session |
| `visionModel` | `VENOM_VISION_MODEL` | `venom-vision` | describes images for a text-only model |
| `maxTokens` | | 16384 | max output tokens |
| `discover` | | `true` | fetch `GET /v1/models` in the background |
| `discoveryTimeoutMs` | | 2500 | discovery timeout |
| `cachePath` | | under `venomHome` | where discovered model ids are cached |
| `preflightTimeoutMs` | | 3000 | the reachability check before a session's first request |
| `notice` | | stderr | where one-line notices go without a UI |
| `fetch` | | global `fetch` | inject a transport (tests, a proxy) |

Pass `provider: false` to register no venom provider at all (when your app brings its own pi provider).

## Model aliases {#aliases}

Venom names models by role: `venom-default` (the session), `venom-fast` (cheap reads, summaries, the explorer subagent), `venom-smart` (hard problems), `venom-vision`, `venom-decide`. The orchestrator and Venom Cloud serve these aliases. Against a server that does not:

- `aliasMap` always wins: `{ "venom-default": "qwen3:8b", "venom-fast": "qwen3:4b" }`. The request's `model` field is rewritten; the session still shows the alias.
- Without one, a server that lists no `venom-*` id gets an automatic mapping: api.openai.com maps to its current small, nano and large models; a server with one model maps all three to it; otherwise models are ranked by the parameter count in their ids. With more than 12 models or nothing to rank by, nothing is mapped and a notice asks for `VENOM_ALIAS_MAP`.

## Model discovery {#discovery}

The provider lists `GET /v1/models` once (cached), drops non-chat models (embeddings, TTS, transcription, moderation, image generation, rerankers), and records per model whether it accepts images and its context window. `provider.fetchModels`, `fetchModelIds`, `supportsImages` and `isChatModelId` expose the same logic; `modelCostFor` and `pricedModelFor` give the bundled list price used for cost estimates.

## Headers venom sends {#headers}

| Header | From | Purpose |
|---|---|---|
| `Authorization: Bearer …` | `apiKey` | auth |
| `x-venom-profile` | `HarnessOptions.routeProfile` | an orchestrator route profile |
| `x-venom-gear` | `HarnessOptions.gear` | a Venom Cloud gear, so spend counts toward its budget |
| `x-venom-experiment` | `HarnessOptions.experiment` | a gear experiment arm (`<id>; arm=a`) |

Subagents inherit all three. None of them enters the prompt.

## Errors {#errors}

The provider rewrites the common failures into one message that names the setting to fix:

| Situation | What the session reports |
|---|---|
| Server unreachable before the first request | fails at once, naming `VENOM_BASE_URL` and `venom doctor` (no retry storm) |
| A transport failure later | re-checks the server: still down, the same message; back up, pi retries |
| 401 or 403 | a line naming `VENOM_API_KEY`; a 403 `model_not_allowed` says the key is valid but restricted |
| 404 naming a model | the list of models the server does serve |
| 429 with a reset time | a long task waits for the reset and continues ([long tasks](/docs/harness/entry-points.md#longtask)) |
| 429 `spend_limit_reached` from Venom Cloud | not retried; names the gear whose budget ran out |

`provider.classifyFetchError`, `httpErrorMessages` and `isPermanentLimit` give the same classification to your own code.

## Related {#related}

- [Sessions, events and cost](/docs/harness/sessions.md)
- [Subagents and model tiers](/docs/harness/subagents.md#tiers)
- [Orchestrator section](/docs/orchestrator.md) and [Venom Cloud section](/docs/cloud.md), for the servers that serve the aliases
