Reference / Providers & Models

Providers & Models

Heddle supports a broad family of models: OpenAI, Anthropic, local Ollama, local OpenAI-compatible servers, self-hosted vLLM, and hosted gateways such as Hugging Face, OpenRouter, Together AI, and Groq. Configure one provider, then choose models with CLI flags, terminal slash commands, or browser controls.

For the provider-family compatibility matrix, see Model Providers.

Provider access

OpenAI account sign-in

heddle auth login openai

Experimental, user-selected ChatGPT/Codex account transport. Not official OpenAI support.

OpenAI Platform API key

export OPENAI_API_KEY=your_key_here

Stable API-key path and required for hosted web search and drift embeddings.

Anthropic API key

export ANTHROPIC_API_KEY=your_key_here

Use this for Claude models. Heddle does not support Anthropic consumer subscription OAuth.

Local Ollama

ollama list
heddle --model ollama/llama3.2:latest ask "Reply with exactly: ok"

Runs through Ollama's local OpenAI-compatible endpoint. No hosted provider API key required.

Local OpenAI-compatible servers

heddle --model lmstudio/local-model ask "Reply with exactly: ok"
heddle --model vllm/meta-llama/Llama-3.3-70B-Instruct ask "Reply with exactly: ok"

Use LM Studio, LiteLLM, or vLLM through provider prefixes such as lmstudio/, litellm/, and vllm/.

Hosted OpenAI-compatible gateways

export OPENROUTER_API_KEY=your_key_here
heddle --model openrouter/meta-llama/llama-3.3-70b-instruct ask "Reply with exactly: ok"

Use Hugging Face, OpenRouter, Together AI, or Groq with their provider API keys and prefixes.

Credential commands

heddle auth status
heddle auth login openai
heddle auth login openai --no-browser
heddle auth logout openai

The same auth surface is available inside terminal chat with /auth, /auth status, /auth login openai, and /auth logout openai.

Default models

OpenAI default

gpt-5.1-codex

Anthropic default

claude-sonnet-4-6

OpenAI-compatible defaults

No hardcoded default. Pick a provider-prefixed model such as ollama/<model>, lmstudio/<model>, openrouter/<model>, together/<model>, or groq/<model>.

Choosing a model

heddle --model gpt-5.4-mini
heddle chat --model claude-3-5-haiku-latest
heddle --model ollama/llama3.2:latest ask "Summarize this repository"
heddle --model lmstudio/local-model ask "Summarize this repository"
heddle --model openrouter/meta-llama/llama-3.3-70b-instruct ask "Summarize this repository"

/model
/model list
/model set <query>
/model <name>
/model ollama/llama3.2:latest
/model lmstudio/local-model
/model openrouter/meta-llama/llama-3.3-70b-instruct

When a profiled provider is reachable, /model set and the browser model selector include discovered models from that provider. Ollama uses the local Ollama API; other OpenAI-compatible profiles use /models. The chat footer and browser composer footer show the active auth source for the selected model.

Model quality caveats

Model quality depends on the family, parameter size, quantization, provider routing, and the hardware or service running the model. Some smaller, older, local, or aggressively routed models are useful for experiments but are not reliable at coding-agent tool use.

They may miss tool calls or produce malformed tool calls.
They may call tools correctly but ignore the tool result.
They may give confident but wrong repository summaries.
They may run slowly enough to hit host request timeouts.

For important code edits, keep approval prompts enabled, review traces and diffs carefully, and prefer a stronger local or hosted model when tool-calling quality matters.

OpenAI account sign-in support

OpenAI account sign-in is limited to models Heddle has explicitly allowed for the ChatGPT/Codex transport path. Use OPENAI_API_KEY for other OpenAI Platform models or features that require API-key mode.

gpt-5.1-codex
gpt-5.1-codex-max
gpt-5.1-codex-mini
gpt-5.2
gpt-5.2-codex
gpt-5.3-codex
gpt-5.3-codex-spark
gpt-5.4
gpt-5.4-mini
gpt-5.5

Important notes

If both OpenAI OAuth and an API key are available, Heddle prefers OAuth by default.
Use --prefer-api-key to force Platform API-key mode for a run, ask command, or daemon session.
Hosted web search and drift embeddings require OpenAI Platform API-key mode today.
Use provider prefixes including ollama/, lmstudio/, litellm/, vllm/, huggingface/ or hf/, openrouter/, together/, and groq/.
Use OLLAMA_OPENAI_BASE_URL, LMSTUDIO_OPENAI_BASE_URL, LITELLM_OPENAI_BASE_URL, or VLLM_OPENAI_BASE_URL when a local server is not on the default endpoint.
Hosted gateways use API keys such as HF_TOKEN, OPENROUTER_API_KEY, TOGETHER_API_KEY, and GROQ_API_KEY.
Gemini model names are recognized by provider inference, but a Google adapter is not wired yet.