Configure a model provider

This guide helps you connect Harn to a model provider. It covers the checks you can run before you put a provider in a program.

1. Check the local installation#

Run the doctor command first:

harn doctor
harn doctor --check-providers

The first command reports the local Harn setup. The second also checks the configured provider paths. It does not print secret values.

2. Find a provider and model#

List the models that Harn knows about:

harn models list
harn models list --provider anthropic

Inspect one model before you use it:

harn models info claude-sonnet-5
harn provider dispatch-explain anthropic claude-sonnet-5

The catalog is the source of truth for current aliases and capabilities. Do not copy an old model name from an example when the catalog gives you a newer one.

3. Set the provider credential#

Each provider reads its key from an environment variable. Set the one for the provider you picked:

export ANTHROPIC_API_KEY="sk-ant-..."

Harn names these providers first, because most people already have an account with one of them:

Harn supports dozens more, and some accept more than one variable. For every provider and the variables it reads, see credential variables; for the endpoint and header details behind them, see the provider reference. To see which variables are already set on this machine, run harn doctor.

Keep the key out of your shell#

A variable can hold a secret reference instead of the key itself:

export ANTHROPIC_API_KEY="harn-secret://work/anthropic"

Harn resolves the reference when it makes the call, so the key never lands in your shell history or a config file. See secrets for how to store one.

After you set the variable, confirm the provider resolves:

harn doctor --check-providers

That command reports which providers have a working credential path. It never prints a secret value.

4. Test the connection#

Use the model test command for a small smoke test:

harn models test claude-sonnet-5 --provider anthropic

The command sends a test request. It can use provider credits. Use a model that is available to your account.

5. Use the provider in a program#

Keep the provider and model in the call options:

fn main(harness: Harness) {
  const response = harness.llm.call(
    "Reply with one short greeting.",
    nil,
    { provider: "anthropic", model: "claude-sonnet-5", max_tokens: 64 }
  )
  harness.stdio.println(response.text)
}

For a single project, put stable defaults in harn.toml when the provider reference says the setting is supported. Keep credentials out of that file.

Local providers#

Start your local server first, then use the provider's name and model from the catalog:

harn models list --provider ollama
harn provider ready ollama --model <model>

For an OpenAI-compatible server, check the endpoint and model settings in the provider reference.

Use the mock provider in tests#

The mock provider needs no credentials and returns deterministic responses. Use it for syntax checks, unit tests, and examples. A mock run proves that the program reaches Harn's model-call boundary; it does not prove that a cloud provider is configured or that a model produces useful answers.

See mock LLM responses for queued responses and error cases.