Providers

The built-in model providers, how each one signs in, and how to add your own.

Hob talks to LLM providers over their HTTP APIs. Models are split into three tiers: weak (cheap and fast), medium (balanced), and strong (highest capability, highest cost). There is also a compaction tier for choosing a dedicated model to summarize context when the conversation grows long.

Open the model picker with /model and press !, @, #, or $ on any row to assign it to strong, medium, weak, or compaction. Press the same key again to remove the assignment. Your overrides are saved to ~/.local/state/hob/model-tiers and apply across sessions.

Auth Reloading

Hob re-reads auth from storage and environment variables each time a new agent spawns (/new, retry, session load). If you run hob auth login in another terminal or change an env var, the next session picks it up without a restart.

You can set multiple API keys in one env var (ANTHROPIC_API_KEY=sk-1,sk-2,sk-3). On a rate-limit or auth error, hob switches to the next key right away, with no delay and without spending a retry. Each request walks the pool once before falling back to normal backoff. A plan quota error does not rotate keys, since the quota is per account and the others are just as spent.

Base URL Overrides

Every provider honors a <SLUG>_BASE_URL env var (anthropic -> ANTHROPIC_BASE_URL, llama-cpp -> LLAMA_CPP_BASE_URL). Set it to the origin of a proxy or a compatible endpoint and Hob appends the API paths itself:

Terminal
ANTHROPIC_BASE_URL=https://my-proxy.internal hob

Built-in, plugin and providers.toml providers all read it. When several origins are set, the first one wins:

  1. An origin the provider’s auth hook returns, such as the endpoint a login flow was given.
  2. <SLUG>_BASE_URL.
  3. base_url in providers.toml.
  4. The provider’s own default base_url.

ANTHROPIC_BASE_URL and OPENAI_BASE_URL are the same names the official SDKs use, so an existing proxy setup carries over as is. Two exceptions: OPENAI_BASE_URL only redirects the platform API, never the ChatGPT Coding Plan backend; XAI_BASE_URL only redirects the public API-key endpoint, never the OAuth CLI proxy.

You can also set base_url for a built-in provider in ~/.config/hob/providers.toml. It overrides the built-in default and loses to the env var above:

toml
[openai]
base_url = "http://xxxx:1234/v1"

The built-in provider still owns the slug, so api_key_env, discover_models, models and protocol are ignored with a warning. Use a custom slug if you need those. ollama and llama-cpp read protocol values openai and openai-responses to pick the chat or Responses API.

Built-in Providers

deepseek, mistral, openrouter, regolo, requesty, synthetic and tensorx ship as bundled plugins and are listed last. Turn one off with plugins = { tensorx = { enabled = false } } in hob.setup.

Anthropic

  • Env var: ANTHROPIC_API_KEY
  • API: https://api.anthropic.com/v1/messages
  • Features: Prompt caching, thinking mode (adaptive/budgeted), advanced tool use
Tier Models Pricing (in/out per 1M tokens) Context
Weak claude-haiku-4-5 (default) $1.00 / $5.00 200K ctx / 64K out
Medium claude-sonnet-4-5 $3.00 / $15.00 200K ctx / 64K out
Medium claude-sonnet-4-6 $3.00 / $15.00 200K ctx / 64K out
Medium claude-sonnet-5 (default) $2.00 / $10.00 200K ctx / 128K out
Medium claude-sonnet-4 $3.00 / $15.00 200K ctx / 64K out
Strong claude-opus-4-5 $5.00 / $25.00 200K ctx / 64K out
Strong claude-opus-4-6 $5.00 / $25.00 200K ctx / 128K out
Strong claude-opus-4-7 $5.00 / $25.00 200K ctx / 128K out
Strong claude-opus-4-8 $5.00 / $25.00 200K ctx / 128K out
Strong claude-opus-5 (default) $5.00 / $25.00 200K ctx / 128K out
Strong claude-fable-5 $10.00 / $50.00 200K ctx / 128K out
Strong claude-opus-4-0, claude-opus-4-1, claude-opus-4-20250514 $15.00 / $75.00 200K ctx / 32K out

Defaults: claude-haiku-4-5 (weak), claude-sonnet-5 (medium), claude-opus-5 (strong)

Add -1m to any Claude model, like claude-sonnet-4-6-1m, to use the 1M token context window.

Amazon Bedrock

If you already use Claude through AWS Bedrock, you can point Hob at it instead of the direct Anthropic API. Set CLAUDE_CODE_USE_BEDROCK=1 and Hob will route all Anthropic requests through Bedrock. The same models, the same features, just a different door.

The region comes from AWS_REGION, then AWS_DEFAULT_REGION, then your AWS profile, and falls back to us-east-1. Auth uses the first of these that is set:

Method Env vars
Bearer token AWS_BEARER_TOKEN_BEDROCK
Gateway proxy CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 + ANTHROPIC_BEDROCK_BASE_URL (skips signing, useful behind a proxy that handles auth)
AWS credentials The AWS SDK’s default chain: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, AWS_PROFILE (static keys, SSO, credential_process, assumed roles, aws login), web identity, container and instance credentials

Temporary AWS credentials are refreshed 5 minutes before they expire. After aws sso login, the next request picks up the new session.

You can override the model with ANTHROPIC_MODEL and the endpoint with ANTHROPIC_BEDROCK_BASE_URL. These env var names match Claude Code, so if you were already using Bedrock there, the same setup works here.

OpenAI

  • Env var: OPENAI_API_KEY (also supports OAuth via hob auth login openai)
  • API: https://api.openai.com/v1
Tier Models Pricing (in/out per 1M tokens) Context
Weak gpt-5.6-luna (default) $1.00 / $6.00 372K ctx / 128K out
Weak gpt-6-luna $0.10 / $0.50 1050K ctx / 128K out
Weak gpt-5.4-nano $0.20 / $1.25 400K ctx / 128K out
Weak gpt-5.4-mini $0.75 / $4.50 400K ctx / 128K out
Weak gpt-4.1-nano $0.10 / $0.40 1047K ctx / 32K out
Medium gpt-5.6-terra (default) $2.50 / $15.00 372K ctx / 128K out
Medium gpt-6-sol $2.00 / $10.00 1050K ctx / 128K out
Medium gpt-6.1-sol $2.00 / $10.00 1050K ctx / 128K out
Medium gpt-6.2-sol $2.00 / $10.00 1050K ctx / 128K out
Medium gpt-4.1-mini $0.40 / $1.60 1047K ctx / 32K out
Medium gpt-4.1 $2.00 / $8.00 1047K ctx / 32K out
Medium o4-mini $1.10 / $4.40 200K ctx / 100K out
Medium gpt-5.1-codex-mini $0.25 / $2.00 400K ctx / 128K out
Strong gpt-5.6-sol (default) $5.00 / $30.00 372K ctx / 128K out
Strong gpt-6-astra $10.00 / $50.00 1050K ctx / 128K out
Strong gpt-6.2-astra $8.00 / $40.00 1050K ctx / 128K out
Strong gpt-5.5 $5.00 / $30.00 1050K ctx / 128K out
Strong gpt-5.4 $2.50 / $15.00 1050K ctx / 128K out
Strong o3 $2.00 / $8.00 200K ctx / 100K out
Strong gpt-5.3-codex $1.75 / $14.00 400K ctx / 128K out
Strong gpt-5.2-codex $1.75 / $14.00 400K ctx / 128K out
Strong gpt-5.1-codex-max $1.25 / $10.00 400K ctx / 128K out
Strong gpt-5.1-codex $1.25 / $10.00 400K ctx / 128K out

Defaults: gpt-5.6-luna (weak), gpt-5.6-terra (medium), gpt-5.6-sol (strong)

hob auth login openai offers browser login (PKCE, callback on localhost:1455) and device code login. Browser is the desktop default; device code is recommended over SSH or in a container. Tokens refresh automatically.

Hob keeps several OpenAI accounts side by side, subscription logins and saved API keys alike, and /account picks one per session. See Accounts.

With an API key, Hob discovers models from the platform’s /models endpoint using that key. With ChatGPT OAuth the model list comes from the Codex backend’s own /models endpoint, so a model your plan gains shows up without a Hob update, with the context window and reasoning levels the backend declares for it. The table above is the offline fallback. The endpoint hides models newer than the Codex CLI version Hob reports, so a brand new release can lag until that version is bumped.

/usage shows subscription quotas, available banked resets, and their expiry dates. If OpenAI changes its usage endpoint paths, override them in providers.toml:

toml
[openai.endpoints]
usage = "/backend-api/wham/usage"
reset_credits = "/backend-api/wham/rate-limit-reset-credits"

Both settings are optional, apply only to the native openai provider (other providers ignore them), and are read on the next usage refresh. Paths must start with a single /; full URLs, backslashes, whitespace, control characters, query strings, fragments, and percent escapes are rejected. Requests stay on https://chatgpt.com, regardless of inference base_url overrides, and never redeem reset credits. API-key accounts do not use these endpoints. If providers.toml cannot be read or parsed during a usage refresh, Hob logs a warning and uses the built-in paths instead. Usage requests reload configured headers into a separate usage snapshot when configuration is valid, with configured values taking precedence for unselected logins. Inference keeps its existing routing, configured headers, and sampling parameters until the normal provider reload applies them together. If configuration cannot be loaded, usage requests retain their last resolved headers. Token rotation updates provider-owned credentials while retaining inference’s configured headers and routing. Selected accounts continue to reject configured credential headers. The optional reset-credit details request has a two-second total deadline and does not trigger token refresh on a 401; the primary quota request retains normal OAuth recovery.

The response contract is implemented by the native parser, not downloaded at runtime. For upstream references, see Codex’s usage and reset-credit types and endpoint implementation. Additional response fields are ignored and missing optional reset metadata does not hide quota data; renamed fields or changed semantics may still require a Hob update.

Google

  • Env var: GEMINI_API_KEY
  • API: https://generativelanguage.googleapis.com/v1beta
  • Features: Native Gemini API with thinking support
Tier Models Pricing (in/out per 1M tokens) Context
Weak gemini-2.0-flash-lite (default) $0.07 / $0.30 1048K ctx / 65K out
Medium gemini-2.5-flash (default) $0.15 / $0.60 1048K ctx / 65K out
Strong gemini-2.5-pro (default) $1.25 / $5.00 1048K ctx / 65K out

Defaults: gemini-2.5-pro (strong), gemini-2.5-flash (medium), gemini-2.0-flash-lite (weak)

Copilot

  • Env var: GH_COPILOT_TOKEN (or run hob auth login copilot to import a token from gh CLI, the Copilot client, or the system keyring)
  • API: https://api.githubcopilot.com (or GraphQL-discovered Copilot API endpoint)
  • Features: Native Copilot Chat HTTP API with model endpoint discovery
Tier Models Pricing (in/out per 1M tokens) Context
Weak gpt-5-mini $0.25 / $2.00 200K ctx / 100K out
Weak gpt-5.4-mini $0.75 / $4.50 200K ctx / 100K out
Weak gpt-5.4-nano $0.20 / $1.25 200K ctx / 100K out
Weak claude-haiku-4.5 $1.00 / $5.00 200K ctx / 64K out
Weak gemini-3.5-flash $1.50 / $9.00 200K ctx / 65K out
Weak mai-code-1-flash-picker $0.75 / $4.50 200K ctx / 100K out
Weak gpt-5.6-luna (default) $0.20 / $1.20 200K ctx / 100K out
Medium gemini-3.6-flash $0.75 / $3.75 200K ctx / 65K out
Medium gemini-3.7-flash $0.75 / $3.75 200K ctx / 65K out
Medium claude-sonnet-4.5, claude-sonnet-4.6 $3.00 / $15.00 200K ctx / 64K out
Medium claude-sonnet-5 $2.00 / $10.00 200K ctx / 100K out
Medium kimi-k2.7-code $0.95 / $4.00 200K ctx / 100K out
Medium gemini-3.1-pro-preview $2.00 / $12.00 200K ctx / 65K out
Medium gpt-5.6-terra (default) $2.00 / $12.00 200K ctx / 100K out
Medium grok-4.5 $2.00 / $6.00 200K ctx / 100K out
Medium grok-4.6 $2.00 / $6.00 200K ctx / 100K out
Strong gpt-5.5 $5.00 / $30.00 200K ctx / 100K out
Strong kimi-k3 $3.00 / $15.00 200K ctx / 100K out
Strong gpt-5.4 $2.50 / $15.00 200K ctx / 100K out
Strong gpt-5.6-sol $5.00 / $30.00 200K ctx / 100K out
Strong gpt-5.3-codex $1.75 / $14.00 200K ctx / 100K out
Strong claude-opus-5, claude-opus-4.8, claude-opus-4.7, claude-opus-4.6, claude-opus-4.5 (default) $5.00 / $25.00 200K ctx / 64K out
Strong claude-opus-4.8-fast, claude-fable-5 $10.00 / $50.00 200K ctx / 100K out

Defaults: gpt-5.6-luna (weak), gpt-5.6-terra (medium), claude-opus-5 (strong)

Ollama

  • Env var: OLLAMA_HOST for local/remote (e.g. http://localhost:11434), OLLAMA_API_KEY for auth
  • API: http://localhost:11434/v1
  • Features: Local or remote inference via OLLAMA_HOST, cloud fallback via OLLAMA_API_KEY

This provider talks the OpenAI-compatible /v1 API, so it also works with llama.cpp’s server, LocalAI, or anything else that speaks the same protocol. Just point OLLAMA_HOST to the right address (e.g. http://localhost:8080 for llama.cpp).

Context window

Ollama picks the context window when it loads a model, from available VRAM unless a Modelfile num_ctx or OLLAMA_CONTEXT_LENGTH sets it. That is often less than the model supports. Before every request hob reads the window from /api/ps and compacts to fit, so Ollama does not cut the start of a long chat. A model that is not loaded yet starts from its Modelfile num_ctx, or from the trained length without one.

For more room, raise the window on the server, where the memory is: OLLAMA_CONTEXT_LENGTH or a Modelfile num_ctx. hob does not set it per request, because a larger window reloads the model and can run out of VRAM mid-session.

Thinking

hob reads from /api/show whether each model thinks and which levels it takes. /thinking lists every level, and a level the model does not take is dimmed and names the level it sends instead: the closest one below, or else the lowest. A model that can only turn thinking on or off shows medium, the level Ollama reads any request as. adaptive sends medium, snapped the same way, and off sends none to a model that can turn thinking off.

LlamaCpp

  • Env var: LLAMA_CPP_API_KEY
  • API: http://localhost:8080/v1
  • Features: Local or remote inference via LLAMA_CPP_HOST, set optional key via LLAMA_CPP_API_KEY

Connects to any OpenAI-compatible /v1 endpoint. Point LLAMA_CPP_HOST to your server address (defaults to http://localhost:8080).

Z.AI

  • Env var: ZHIPU_API_KEY (shared across both endpoints)
  • API endpoints:
    • https://api.z.ai/api/paas/v4
    • https://api.z.ai/api/coding/paas/v4
Tier Models Pricing (in/out per 1M tokens) Context
Weak glm-5.3-flash $0.15 / $0.50 1000K ctx / 131K out
Weak glm-4.7-flash (default) $0.00 / $0.00 200K ctx / 131K out
Weak glm-4.5-flash $0.00 / $0.00 131K ctx / 98K out
Weak glm-4.5-air $0.20 / $1.10 131K ctx / 98K out
Medium glm-4.7, glm-4.6 (default) $0.60 / $2.20 200K ctx / 131K out
Medium glm-4.5 $0.60 / $2.20 131K ctx / 98K out
Strong glm-5-code (default) $1.20 / $5.00 200K ctx / 131K out
Strong glm-5.3 $1.40 / $4.40 1000K ctx / 131K out
Strong glm-5.2 $1.40 / $4.40 1000K ctx / 131K out
Strong glm-5.1 $1.40 / $4.40 200K ctx / 131K out
Strong glm-5 $1.00 / $3.20 200K ctx / 131K out

Defaults: glm-5-code (strong), glm-4.7-flash (weak), glm-4.7 (medium)

Opencode Zen

  • Env var: OPENCODE_API_KEY
  • API: https://opencode.ai/zen/v1
  • Features: Dynamically discovered models via models.dev + all the models provided by Opencode Zen API

No hardcoded model catalog. Use any model ID supported by this provider.

By default Hob hides free models from the Opencode catalog. To list free models (they use a public fallback, no API key needed), add this to ~/.config/hob/providers.toml:

toml
[opencode]
enable_free_models = true

The default is false.

xAI

  • Env var: XAI_API_KEY (also supports OAuth via hob auth login xai)
  • API endpoints:
    • https://api.x.ai/v1
    • https://cli-chat-proxy.grok.com/v1
  • Features: OAuth login, account-specific model catalog, Grok reasoning (low/medium/high/xhigh)
Tier Models Pricing (in/out per 1M tokens) Context
Medium grok-4.3 (default) $1.25 / $2.50 1000K ctx / 131K out
Strong grok-4.6 (default) $2.00 / $6.00 500K ctx / 131K out
Strong grok-4.5 $2.00 / $6.00 500K ctx / 131K out

Defaults: grok-4.6 (strong), grok-4.3 (medium)

OAuth uses the same first-party xAI client as the official Grok CLI (hob auth login xai). Browser login (PKCE) is the desktop default; device code is recommended over SSH or in a container. Tokens refresh automatically. After login, Hob fetches your account catalog from GET /v1/models-v2 on the Grok CLI proxy and caches it for 15 minutes. XAI_BASE_URL only redirects the public API-key endpoint, never the OAuth proxy.

If ~/.grok/auth.json already exists, login offers to reuse it without writing that file.

Aperture

  • Env var: APERTURE_HOST (e.g. https://your-host.tailnet.ts.net)
  • API: Aperture gateway (set APERTURE_HOST)
  • Features: Tailscale Aperture LLM gateway; set APERTURE_HOST or configure in providers.toml

Aperture discovers models from your gateway. Set APERTURE_HOST to your Tailscale Aperture endpoint (e.g. https://your-host.tailnet.ts.net). No API key needed, Tailscale handles auth.

Opencode Go

  • Env var: OPENCODE_API_KEY
  • API: https://opencode.ai/zen/go/v1
  • Features: Dynamically discovered models via models.dev + all the models provided by Opencode Go API

No hardcoded model catalog. Use any model ID supported by this provider. An API key is required.

DeepSeek

  • Env var: DEEPSEEK_API_KEY
  • API: https://api.deepseek.com
  • Features: Thinking on or off, open-weight models
  • Peak pricing: 2x during 01:00-04:00, 06:00-10:00 UTC, Mon-Fri. The prices below are off-peak, and each turn pays the rate in effect when it runs
Tier Models Pricing (in/out per 1M tokens) Context
Medium deepseek-flash, deepseek-v4-flash (default) $0.15 / $0.60 1000K ctx / 384K out
Strong deepseek-v4-pro (default) $0.66 / $1.98 1000K ctx / 384K out

Defaults: deepseek-flash (medium), deepseek-v4-pro (strong)

Mistral

  • Env var: MISTRAL_API_KEY
  • API: https://api.mistral.ai/v1
Tier Models Pricing (in/out per 1M tokens) Context
Weak zai-glm-5-3-flash (default) $0.15 / $0.50 1000K ctx / 131K out
Weak ministral-14b-latest, ministral-14b-2512 $0.20 / $0.20 262K ctx
Medium mistral-small-latest, mistral-small-2603 (default) $0.15 / $0.60 262K ctx
Medium deepseek-v4-1-flash-1017 $0.30 / $1.20 1000K ctx / 131K out
Strong mistral-large-4, mistral-large-4-0 (default) $0.70 / $2.10 1000K ctx
Strong mistral-medium-latest, mistral-medium-3.5, mistral-medium-3-5, mistral-medium-2604 $1.50 / $7.50 262K ctx
Strong zai-glm-latest, zai-glm-5-3, zai-glm-5 $1.40 / $4.40 1000K ctx / 131K out

Defaults: mistral-large-4 (strong), mistral-small-latest (medium), zai-glm-5-3-flash (weak)

OpenRouter

  • Env var: OPENROUTER_API_KEY
  • API: https://openrouter.ai/api/v1
  • Features: 300+ models behind one key, prompt caching, provider routing

Use any model id from openrouter.ai/models, e.g. openrouter/anthropic/claude-sonnet-4.

Regolo

  • Env var: REGOLO_API_KEY
  • API: https://api.regolo.ai/v1
  • Features: EU-hosted open-weight models, live catalog and prices
Tier Models Pricing (in/out per 1M tokens) Context
Weak qwen3.5-9b (default) $0.07 / $0.35 80K ctx / 80K out
Medium qwen3-coder-next (default) $0.50 / $2.00 120K ctx / 120K out
Strong qwen3.5-122b (default) $1.00 / $4.20 120K ctx / 120K out

Defaults: qwen3.5-122b (strong), qwen3-coder-next (medium), qwen3.5-9b (weak)

Requesty

  • Env var: REQUESTY_API_KEY
  • API: https://router.requesty.ai/v1
  • Features: 700+ models behind one key, managed routing policies, EU region

Models are listed live from the API. Managed policies come first, with short ids such as requesty/claude-sonnet-4-5, and their @eu variants use only EU providers. The full <vendor>/<model> catalog follows, e.g. requesty/openai/gpt-4o-mini. Get a key at app.requesty.ai/api-keys. Set REQUESTY_BASE_URL=https://router.eu.requesty.ai/v1 to keep all traffic in the EU.

Synthetic

  • Env var: SYNTHETIC_API_KEY
  • API: https://api.synthetic.new/openai/v1
  • Features: Reasoning effort (low, medium, high), open-weight models
Tier Models Pricing (in/out per 1M tokens) Context
Weak hf:zai-org/GLM-4.7-Flash (default) $0.10 / $0.50 200K ctx / 131K out
Medium hf:deepseek-ai/DeepSeek-V3.2 (default) $0.56 / $1.68 200K ctx / 131K out
Strong hf:moonshotai/Kimi-K2.5 (default) $0.45 / $3.40 200K ctx / 131K out

Defaults: hf:moonshotai/Kimi-K2.5 (strong), hf:deepseek-ai/DeepSeek-V3.2 (medium), hf:zai-org/GLM-4.7-Flash (weak)

TensorX

  • Env var: TENSORX_API_KEY
  • API: https://api.tensorx.ai/v1
  • Features: Open-weight models, zero data retention, prompt caching

No hardcoded model catalog. Use any model ID supported by this provider.

Model Identifiers

Models are referenced as provider/model_id:

anthropic/claude-sonnet-4-6
openai/gpt-4.1
xai/grok-4.6
zai/glm-4.7

If the model name is unique across providers, the prefix can be omitted.

Models newer than your Hob version

The tables above list the models Hob curates. Any other id a provider accepts works too: type it into /model or pass it to --model. The picker also lists what the provider’s own model endpoint reports, so same-day releases are selectable there.

For an id no table covers, rates, context window, vision and thinking support come from models.dev, refreshed daily (hob models --refresh forces it). Hob reads each field on its own, so a row that lists a price but no context window still leaves the window to the sources below.

Sources rank by how sure they are to describe the exact model you asked for:

  1. What the provider’s own model endpoint reported this session.
  2. A curated row for that id, including its dated snapshots. claude-sonnet-4-5-20250929 reads the claude-sonnet-4-5 row.
  3. models.dev.
  4. A curated row for a close relative, reached by shared prefix. glm-5.4 falls back to glm-5 here, and takes its family and tier from it either way.
  5. The provider’s defaults, with no cost estimate.

A curated row is checked against the provider’s own pricing page, so it wins for the id it names. For a relative it loses to models.dev, because a rate nobody checked against the id you typed is only a guess.

New models start at the medium tier until you assign one in the picker.

providers.toml

providers.toml lives in the config directory (~/.config/hob/providers.toml on Linux/macOS, %APPDATA%\hob\providers.toml on Windows). Use it to:

  1. Tweak a built-in (pick a plan, change its base URL, set enable_free_models for Opencode).
  2. Declare a custom provider that speaks OpenAI, Anthropic, or Google wire format.
toml
# Point a built-in at a proxy. Env vars still win over this file.
[anthropic]
base_url = "https://my-proxy.internal"

# Full custom provider. Slug becomes the `provider/` prefix in model specs.
[my-proxy]
display_name = "My Proxy"
protocol = "openai"            # openai | openai-responses | anthropic | google
base_url = "https://llm.example.com/v1"
api_key_env = "MY_PROXY_API_KEY"
default_model = "my-proxy/fast-v1"
discover_models = true         # also list models via the provider's /models endpoint

[[my-proxy.models]]
id = "fast-v1"
tier = "weak"
context_window = 128000
max_output_tokens = 16384
pricing_input = 0.5
pricing_output = 1.5

[[my-proxy.models]]
id = "smart-v1"
tier = "strong"
context_window = 200000
max_output_tokens = 32000
supports_thinking = true
supports_vision = false

Provider fields

Field Type Notes
display_name string Shown in pickers and auth status
protocol string openai, openai-responses, anthropic, or google. Required for custom slugs
base_url string Origin of the API. Hob appends the protocol paths
plan string Built-in plan key (see Plans below). Sets base URL and default model
api_key_env string Env var that holds the key. Defaults to <SLUG>_API_KEY
api_key string Inline key (prefer the env var or hob auth login)
headers table Extra HTTP headers sent on every request to this provider. Values expand ${VAR} from the environment; an unset or empty variable fails the provider instead of sending a half-filled header. A same-name header (case-insensitive) replaces the built-in auth header and survives key rotation
default_model string Used after login when no model is saved yet. On a custom entry it is also the startup fallback when no built-in or plugin provider is available. Without it, startup picks a declared strong or medium model
top_p f64 Nucleus sampling probability, sent as top_p in the request body for OpenAI-compatible, Anthropic, Bedrock and Google providers. Claude and GPT models reject it while thinking is on, and Claude Opus 4.7, Claude 5 and later always do, so it is dropped there. Never sent to Copilot or over the OpenAI responses path. Only sent when set, so the provider’s own default applies otherwise. Must be in (0, 1]
discover_models bool When true, also probe the provider’s model list endpoint (default false)
enable_free_models bool Opencode only. Show free catalog models (default false)
allow_paid_account_fallback bool OpenAI only. Allow saved-account fallback to metered or unverified billing when leaving a subscription or unknown billing route (default false). Does not permit environment, model, or cross-provider fallback
subsidised_by string Name of the flat subscription prepaying this provider (e.g. "Max"). Models bill $0 and show the published list price beside it as a reference. The list-price fallback needs protocol = "anthropic"
supports_deferred_tools bool The endpoint can load a deferred MCP tool without rewriting the cached tools prefix (see MCP). True for Anthropic direct and Bedrock. A custom protocol = "anthropic" provider, or a built-in pointed at another base_url, defaults to false and opts in here
models array Declared models for custom providers (see below)
overrides table Aperture only. Per-upstream model overrides (see below)

Model fields

Field Type Default Notes
id string required Model id. Spec becomes {slug}/{id}
tier string medium weak, medium, strong, or compaction
context_window u32 protocol default Tokens of context
max_output_tokens u32 protocol default Max completion tokens
supports_tool_examples bool protocol default
supports_thinking bool protocol default
requires_thinking bool false For APIs that reject requests with thinking disabled. Implies supports_thinking and raises thinking to minimal effort when off (including compaction). On generic openai entries without thinking_fields its only wire effect is that the disabled block is never sent
thinking_fields table unset How this model spells each thinking mode on the wire. The only thinking control on generic openai entries, and it implies supports_thinking
supports_vision bool protocol default When false, image input and view_image are off
pricing_input / pricing_output f64 0 USD per 1M tokens
pricing_cache_write / pricing_cache_read f64 0 USD per 1M tokens
pricing_fast_input / pricing_fast_output f64 unset Fast-mode pricing when the provider supports it

Custom slugs must not reuse a built-in provider name. Hob exits with code 2 at startup if providers.toml does not parse or contains an unknown key, so a typo like api_key_evn fails there rather than being silently ignored.

Custom openai-protocol models control thinking with thinking_fields. Each key is a thinking mode, and its JSON fragment merges into the request body. An effort level without a key uses the closest declared level below it, or the lowest declared level if none is below. off and adaptive need their own keys and never fall back:

toml
[[my-ollama.models]]
id = "qwen3.8-coder-27b-mlx:latest"
supports_thinking = true

[my-ollama.models.thinking_fields]
off = { reasoning_effort = "none" }
adaptive = { reasoning_effort = "medium" }
low = { reasoning_effort = "low" }
medium = { reasoning_effort = "medium" }
high = { reasoning_effort = "xhigh" }
max = { reasoning_effort = "xhigh" }

A mode you left out sends nothing. The built-in ollama slug needs no thinking keys, because it asks Ollama which levels each model takes (see Ollama). To override that for a model, set [ollama].base_url (or OLLAMA_HOST) and give [[ollama.models]] the thinking keys. Only supports_thinking, requires_thinking and thinking_fields overlay onto a built-in slug. The rest of the entry stays ignored, and startup names the keys it dropped.

Without thinking_fields, hob sends "thinking": {"type": "disabled"} when thinking is off and nothing when it is on. GLM and Kimi gateways need this block to stop reasoning. Declaring thinking_fields replaces it, so add an off key if your gateway needs one. Some gateways, such as LiteLLM in front of Azure, reject the block. Hob then retries without it, and if the retry works, leaves the block out for that model until restart.

You can also create a custom provider interactively with hob auth login and choosing the custom option. That writes a starter entry to this file.

Aperture overrides

Aperture proxies upstream providers, exposing each model as aperture/<upstream>/<model>. Overrides keyed by upstream provider id live under [aperture.overrides]:

toml
[aperture.overrides.llmserver]
base = "llama-cpp"
context_window = 131072
max_output_tokens = 16384

[aperture.overrides.llmserver.models."qwen-3.6"]
context_window = 262144
supports_vision = true

Provider-level fields apply to every model from that upstream; per-model entries under models win field by field. Fields: context_window, max_output_tokens, supports_thinking, supports_vision, base (remaps an opaque vendor to a native provider; e.g. llama-cpp, google, anthropic), and path_prefix. Model ids containing dots must be quoted ("qwen3.6") since TOML treats a bare dotted key as a nested table.

Hob sends /v1 (or /v1beta for Gemini routes, nothing for Anthropic and Z.AI), and Aperture appends that path to the upstream’s base url. If an upstream base url already carries its own path, set path_prefix = "" for it to avoid a doubled path. Z.AI defaults to no prefix since its API path has no /v1 segment; point the upstream base url at the full API root (e.g. https://api.z.ai/api/paas/v4).

Plans

Some built-ins ship multiple plans (different base URLs or default models). hob auth login <provider> asks which plan to use when more than one exists. You can also set it in TOML:

toml
[mistral]
plan = "coding"

[zai]
plan = "coding"

Current plans:

Provider Plan What it does
Mistral standard Standard at https://api.mistral.ai/v1, default mistral/mistral-large-4
Mistral coding Vibe / Coding at https://api.mistral.ai/v1, default mistral/mistral-vibe-cli-latest
Z.AI standard Pay-as-you-go at https://api.z.ai/api/paas/v4, default zai/glm-5.1
Z.AI coding Coding plan at https://api.z.ai/api/coding/paas/v4, default zai/glm-5-code

Env <SLUG>_BASE_URL still wins over both the plan and a base_url in this file.

Plugin Providers

A Lua plugin can add a provider. Call hob.provider.register at the top level of the plugin file, and its models become {slug}/{model_id} (e.g. acme/acme-large) in /model and the picker. They get the same retries, pricing and usage accounting as a built-in provider.

lua
hob.provider.register({
  slug = "acme",
  display_name = "Acme",
  codec = "openai",
  base_url = "https://api.acme.com/v1",
  api_key_env = "ACME_API_KEY",
  models = {
    { prefixes = { "acme-large" }, tier = "strong", context_window = 200000 },
  },
})

The plugin’s plugin.toml must grant net, list the provider’s hosts in net_hosts, and list the slug under providers when models.dev serves that name. api_key_env also needs env:

toml
providers = ["acme"]

[permissions]
net = true
env = true
net_hosts = ["api.acme.com"]

Hob sends the provider’s credentials only to those hosts, plus any origin you set yourself with <SLUG>_BASE_URL or providers.toml. The base_url must be https, or http on loopback. See plugin egress for the pattern syntax.

The Lua API lists every field. This section explains the choices.

Granted slugs

A third-party plugin that registers a slug models.dev serves has to be granted it: the manifest lists the slug at the top level of its plugin.toml, and the install approval covers it. The install approval prompt shows that the package will receive your saved key for each name models.dev serves.

toml
providers = ["acme"]

[permissions]
net = true
net_hosts = ["api.acme.com"]

Hob checks the list against the names models.dev serves today. A load that registers such a slug the manifest does not list, or the approval never covered, is refused. List every slug the package registers, so a name the catalog adds later is already approved and the generic catalog client can never take over a working package’s slug and receive the key you saved for it.

Names Hob ships, built in or as a bundled plugin, stay reserved regardless of this list.

An approval recorded before this list existed covers no slug. The startup approval check asks again, so update or reinstall the package and answer the prompt to grant the names.

This replaces the plugin = "..." selection field an older release had in providers.toml. Hob still reads it: while it is set, the slug stays owned by the named package so the catalog client cannot take it over, and a warning tells you to list the slug under providers in the package’s plugin.toml and remove the plugin = line.

codec or base

Set exactly one of the two. codec picks the wire format the API speaks:

codec Wire format
openai OpenAI chat completions
openai-responses OpenAI responses API
anthropic Anthropic messages
google Gemini generateContent

base borrows a built-in provider’s whole adapter, quirks included, such as Ollama’s thinking field or Copilot’s endpoint routing. Use it when porting a provider script that set base, or when no codec fits. A base changes whenever that provider does, so prefer a codec. Valid values: anthropic, openai, google, copilot, ollama, llama-cpp, zai, opencode, xai, aperture.

With any base, endpoint overrides belong to the plugin slug. The native slug’s <SLUG>_BASE_URL, base_url and selected plan do not apply. Base-specific settings such as aperture.overrides and a native local provider’s protocol still apply. See Base URL Overrides for precedence.

A base rejects a static base_url in the declaration or its plans. Use codec for those fields.

Without a list_models hook, the provider lists what its codec or base lists, such as GET /models for codec = "openai". A base also lends its model rows, so a model your models table leaves out keeps the base’s price, limits and tier.

family, accepts_arbitrary_models, max_output_tokens and context_window apply to models without a row, and default to the provider behind the codec or base. codec = "openai" defaults to the gpt family, so set family = "generic" unless the API serves GPT models. Rows that leave out a limit take the provider’s.

Model rows

models is read once at registration. Rows describe models, and the picker lists them next to the runtime list. To change how the runtime list is fetched, use the list_models hook.

A row matches every model id that starts with one of its prefixes, and the longest match wins: acme-large-2504 uses an acme-large row over an acme row. prefixes[1] is the canonical id, shown in the picker and used in {slug}/{model_id}.

Field Type Default Notes
prefixes list of strings required The first is the canonical id
tier string medium weak, medium, strong, or compaction
context_window number provider’s Tokens of context
max_output_tokens number provider’s Max completion tokens
supports_thinking bool unset
requires_thinking bool false For APIs that reject a request with thinking off. Implies supports_thinking and raises thinking to minimal effort when off
supports_vision bool unset When false, image input and view_image are off for this model
supports_tool_examples bool unset
pricing table unset input, output, cache_write, cache_read, in dollars per 1M tokens
thinking_fields table unset How this model spells each thinking mode on the wire
family string provider’s generic, claude, gpt, gemini, glm or synthetic
default bool first row of its tier The tier’s default model. At most one per tier

An unset supports_* flag uses the codec or base provider’s answer, and false turns the feature off for that model.

thinking_fields works as in providers.toml. Keys are off, adaptive and the effort levels minimal, low, medium, high, xhigh, max, each mapped to a JSON fragment merged into the request body. A mode you leave out sends nothing with a codec, and falls back to the built-in mapping with base = "llama-cpp" or base = "ollama".

Hooks

Every hook is optional. Without any, the provider reads its key from api_key_env.

Hook Runs
auth(ctx, purpose) "resolve" before the first request, "refresh" after a 401 on the newest credentials (then retries), "reload" to re-read stored credentials after a login or another hob process changed them
list_models(ctx) When the picker or hob models lists models
build_body(ctx, body, model, opts) On every request, with the final body
map_error(ctx, status, message) On an API error, before it reaches the UI
fetch_usage(ctx) When the usage display asks for quota
login(ctx) hob auth login <slug>
logout(ctx) hob auth logout <slug>

Each hook gets a ctx table first, with the slug, the current origin and headers, and a ctx.get_json helper. Build URLs from ctx.base_url so side calls follow a user who points the slug at a gateway. To fail, return nil, err with an error from ctx.get_json or hob.provider.http_error, and Hob retries as it would for a built-in provider.

Credentials resolve on the first request. A provider with missing or expired credentials stays in the picker and fails when you send a message, like a built-in provider with no API key.

hob auth login lists a provider that defines login or api_key_env. With login, it runs the hook. Otherwise it asks for one of the plans if there are any, opens login_url, and saves the key you paste.

map_error can change the status and message of an API error, for example to turn an opaque vendor error into advice. Retries follow the new status, and retry-after still comes from the server.

build_body needs the openai or openai-responses codec, and the google codec refuses system_prefix. Both mistakes fail at registration.

Credentials

hob.provider.auth stores credentials for the plugin’s own slugs:

lua
hob.provider.auth.set("acme", { access_token = token, expires_at = when })
local creds = hob.provider.auth.get("acme")
hob.provider.auth.clear("acme")

The value is any JSON object. Each slug gets its own file at ~/.local/state/hob/auth/plugins/<slug>.json, with mode 0600, atomic writes and a lock against other Hob processes. An auth hook can call set to save a refreshed token.

Slug rules

  • Starts with a letter or digit, then only letters, digits, _ and -
  • Not a slug Hob ships, built in or as a bundled plugin, even one you turned off. Your plugin would otherwise get the API key saved for that provider
  • Listed under providers in the package’s plugin.toml and covered by its install approval when models.dev serves the slug. List every slug the package registers, so a name models.dev adds later cannot break a working package
  • Not a custom provider from providers.toml or a slug another plugin registered

Migrating from provider scripts

Hob no longer runs executable scripts from the config providers/ directory. At startup it names every script that no plugin has replaced yet. To port them, run:

Terminal
hob migrate providers

It lists those scripts and prints a prompt that asks a coding agent to port them to Lua plugins. The prompt names your files and directories, maps each part of the script protocol to the Lua API, and ends with checks the agent runs before it reports back. It goes to stdout, so you can start hob with it or copy it into another agent:

Terminal
hob "$(hob migrate providers)"
hob migrate providers | pbcopy

If a script was your only way to reach a model, the new hob has no model to run the prompt with. Use the binary that hob update replaced, which it keeps in the state directory. Releases before 0.5.8 still run scripts, and when the backup is one of them, hob migrate providers shows the command:

Terminal
~/.local/state/hob/hob_backup "$(hob migrate providers)"

With the old binary, the agent also checks that each plugin lists the same models the script did. The next hob update overwrites the backup, so port your scripts before you update again. Without a backup, paste the prompt into another agent.

Each plugin keeps its script’s file name as the slug, so saved models and hob auth login <slug> keep working. The warning for a script stops once a plugin registers its slug. The prompt tells the agent to leave the scripts and their credential files in place, and to tell you which ones you can delete once every check passes.

To port a script by hand, map each subcommand to part of the registration:

Script subcommand Lua
info The same fields on the registration table, minus has_auth. Defining login replaces it
models The models table. id = "acme" becomes prefixes = { "acme" } and matches the same ids. Rows no longer bound the list, so if the API has no model list, add list_models = function() return {} end to list only the rows
resolve, refresh, reload auth = function(ctx, purpose), with purpose naming the subcommand
login login = function(ctx), using ctx.print, ctx.prompt and ctx.open_url
logout logout = function(ctx)

A script whose base was mistral, deepseek, openrouter, requesty, synthetic, regolo or tensorx uses codec = "openai" now, with that provider’s origin as base_url. Those providers are Lua plugins themselves, so they cannot be a base.

A static base_url only works with codec. A script that kept its base and returned a base_url from resolve returns it from the auth hook now.

A script that kept credentials in its own file can import them on first use, so nobody has to log in again. Call this from a hook, since hob.provider.auth.set only works inside one:

lua
local function credentials()
  local stored = hob.provider.auth.get("acme")
  if stored then
    return stored
  end
  local text = hob.fs.read(hob.fs.normalize("~/.local/state/hob/auth/acme.json"))
  if not text then
    return nil
  end
  local imported = hob.json.decode(text)
  hob.provider.auth.set("acme", imported)
  return imported
end

Worked example

Hob’s tests load this plugin, so it matches the current API. It uses codec = "openai" and every hook.

plugin.toml:

toml
providers = ["acmelua"]

[permissions]
net = true
net_hosts = ["api.acme.example"]

init.lua:

lua
-- An OpenAI-compatible provider that uses every `hob.provider.register` hook
-- once. The provider docs quote this file as their worked example.

local ANONYMOUS = "anonymous"
local REFRESH = "refresh"
local MODELS_PATH = "/models"

local function stored_token(slug)
  local stored = hob.provider.auth.get(slug)
  return (stored and stored.token) or ANONYMOUS
end

local function bearer(token)
  return { headers = { authorization = "Bearer " .. token } }
end

hob.provider.register({
  slug = "acmelua",
  display_name = "Acme (Lua)",
  codec = "openai",
  base_url = "https://api.acme.example/v1",
  -- Prepended to hob's system prompt.
  system_prefix = "Acme house rules: answer in full sentences.",
  models = {
    {
      prefixes = { "acme-1", "acme" },
      tier = "strong",
      context_window = 200000,
      max_output_tokens = 8192,
      supports_thinking = true,
      -- The only levels Acme accepts. Hob snaps any other level onto them.
      thinking_fields = {
        low = { reasoning_effort = "low" },
        high = { reasoning_effort = "high" },
      },
    },
  },

  -- `purpose` is "resolve" before the first request, "reload" after a login
  -- in another process changed the store, and "refresh" after a 401. An Acme
  -- token is single use, so a refresh mints and stores the next one here.
  auth = function(ctx, purpose)
    if purpose ~= REFRESH then
      return bearer(stored_token(ctx.slug))
    end
    local renewed = stored_token(ctx.slug) .. "-renewed"
    hob.provider.auth.set(ctx.slug, { token = renewed })
    return bearer(renewed)
  end,

  -- The catalogue changes faster than this file, so the picker asks the API.
  -- `ctx.get_json` uses the chat requests' origin and headers.
  list_models = function(ctx)
    local body, err = ctx.get_json(MODELS_PATH)
    if err then
      return nil, err
    end
    local models = {}
    for _, m in ipairs(body.data or {}) do
      table.insert(models, { id = m.id, context_window = m.context_length, tier = "strong" })
    end
    return models
  end,

  -- Gets the final body, thinking level included. Acme wants the effort under
  -- its own key. `opts.thinking` is nil when thinking is off.
  build_body = function(_, body, model, opts)
    body.acme_reasoning = { model = model, effort = body.reasoning_effort, asked_for = opts.thinking }
    body.reasoning_effort = nil
    return body
  end,

  -- Acme answers 429 for a spent monthly allowance, which no retry can fix,
  -- so a 400 stops the retries.
  map_error = function(_, status, message)
    if status == 429 and message:find("allowance") then
      return { status = 400, message = "Acme allowance is spent until the next cycle" }
    end
  end,

  fetch_usage = function()
    return { plan = "team", limits = { { label = "Monthly allowance", percentage = 42 } } }
  end,

  -- Defining `login` lists the provider in `hob auth login`.
  login = function(ctx)
    local key = ctx.prompt({ label = "Acme API key: ", secret = true })
    if not key or key == "" then
      ctx.print("No key entered, nothing was stored.")
      return
    end
    hob.provider.auth.set(ctx.slug, { token = key })
    ctx.print("Stored your Acme key.")
  end,

  logout = function(ctx)
    hob.provider.auth.clear(ctx.slug)
    ctx.print("Forgot your Acme key.")
  end,
})

Keyboard shortcuts

Go to

On this page

  • jkNext or previous section
  • 12…The section with that number
  • cCopy the install command
  • iDownload
  • dDocs
  • []Previous or next page

Anywhere

  • ?Show or hide this list
  • EscClose, or stop a "g"