Providers

A backend is what actually executes a step. The runner registers seven, and a recipe can define more.

mentu-recipes adapters

shell	shell	plain_text	ignored	available	explicit
openai	llm-http	openai_sse	native	unavailable	auto
openai-chat	llm-http	openai_sse	native	unavailable	auto
deepseek	llm-http	openai_sse	native	unavailable	auto
ollama	llm-http	openai_sse	native	available	auto
claude	agent-cli	claude_json	native	available	auto
codex	agent-cli	codex_json	folded_into_prompt	available	auto

The columns are name, execution kind, stream format, how system context is passed, availability, and whether the backend can be auto-detected. The availability column depends on what is installed and exported on your machine, so your rows may differ from these.

Details are on Cloud APIs, CLI agents, and Local models. Credentials are on Credentials.

Selection order

For each step the runner takes the first of:

1. the step's backend
2. --backend on the command line
3. the recipe's backend
4. auto-detection

A name is matched after trimming, lowercasing, and turning underscores into hyphens. openai-responses and chatgpt are aliases for openai. A name declared under the recipe's providers block wins over a built-in of the same name.

Auto-detection walks a fixed list and takes the first backend that reports available: openai, claude, codex, deepseek, ollama. openai-chat is never auto-detected, even though the table marks it auto. Select it by name.

shell is never auto-detected either. A step gets a shell only by asking for one by name, which is why the last column marks it explicit.

ollama always reports available and sits last in that list, so it is what a step falls back to when nothing earlier is configured. See Local models.

The model follows the same shape: the step's model, then --model on the command line, then the recipe's model, then the backend's default.

Why a backend shows as unavailable

Availability is a non-blocking check. The HTTP backends look for their environment variable, the CLI backends look for their executable on PATH, and shell checks that /bin/sh exists. The check deliberately does not open the macOS Keychain, so a backend whose key lives only in the vault reports unavailable and still runs when a step selects it by name.

mentu-recipes adapters checks the process environment you run it from. During a run the recipe's env block is merged in first, with ${vault-key} references resolved, so a key referenced that way does make its backend auto-detectable for that run.

ollama is the exception in the other direction. It needs no credential, so it reports available whether or not a server is running.

Capabilities

Every backend reports machine-readable capabilities: execution kind, stream format, completion policy, system context handling, whether it is local, whether it needs network or a credential, tool allow-list and deny-list support, reasoning, thinking, output token limits, token reporting, structured completion, and whether it can run offline.

mentu-recipes adapters --explain shell

shell
  execution: shell
  stream: plain_text
  completion: shell_exit_code
  local: true
  network: false
  credential: false
  tools: false
  structured completion: false

mentu-recipes adapters --explain openai

openai
  execution: llm-http
  stream: openai_sse
  completion: provider_complete_event
  local: false
  network: true
  credential: true
  tools: false
  structured completion: true

--explain accepts the seven built-in names only. --json prints the full capability record for every built-in backend. doctor reads these capabilities rather than hardcoding provider assumptions, which is how it knows to warn when a step sets allowed_tools, disallowed_tools, or thinking on a backend that does not support it.

Completion policy

The capability that matters most when authoring is completion. A shell step completes on exit code zero. A provider step completes on the provider's own completion event: the final SSE event for an HTTP backend, the result record for a CLI agent.

Adding completion_keyword to any step changes the check. The step then completes when the process exit code is zero and the keyword appears in stdout or stderr. The provider completion event is no longer consulted. A step that also declares verify or expected_changes must pass those checks too.