Configure models, credentials, and fallbacks

Choose a working provider connection before selecting the model for an agent. For route identities and fallback behavior, see Models and providers.

Before you start

Access to the Holon installation you intend to configure.
A provider account or a local inference server.
Permission to change shared configuration. Global defaults and credentials can affect several agents.

Run these commands in your operator terminal. Do not paste credentials into agent prompts, screenshots, logs, or issue reports.

Steps

Inspect registered providers and configuration health:
```
holon config providers list
holon config doctor
```
For interactive setup, including supported OAuth/device-login providers:
```
holon onboard
```
Follow the wizard for your provider. If using an API key instead, store it through standard input and connect the profile to the provider. This example uses the built-in deepseek provider:
```
holon config credentials set --kind api_key --stdin deepseek
```
Enter the key and finish input with Ctrl+D before running the next commands:
```
holon config set providers.deepseek.auth.source credential_profile
holon config set providers.deepseek.auth.profile deepseek
holon config set providers.deepseek.auth.kind api_key
```
A profile name is a label, not an automatic provider assignment. Alternatively, use the provider's documented environment variable in the daemon's environment. Exporting it in a separate client shell does not update a running daemon. Never use --material for a real secret in a shared command history.
List models after authentication:
```
holon config models list
```
Select an available agent-turn route from the output. Canonical routes use provider@endpoint/model, for example deepseek@default/deepseek-v4-pro. Availability still depends on your account, endpoint, and installed configuration.
Set a global default using your chosen route:
```
holon config set model.default "deepseek@default/deepseek-v4-pro"
holon config get model.default
```
To select a different route for one existing agent:
```
holon agent model set "anthropic@default/claude-sonnet-4-6" reviewer
holon agent model get reviewer
```
Use a route available to your installation; these two examples require different provider connections. holon agent model clear reviewer removes the override so the agent uses the global default again.
Choose a fallback policy:
```
# Automatic: one preferred route per authenticated provider.
holon config set model.fallbacks '["auto"]'

# Or an explicit ordered list of routes you have authenticated.
holon config set model.fallbacks '["anthropic@default/claude-sonnet-4-6"]'
```
Run only the policy you intend to use. An agent override replaces the primary route; the global default is not implicitly added as a fallback. Empty or unset fallback lists use automatic fallback. To require a single provider route instead, set:
```
holon config set runtime.disable_provider_fallback true
```
This is global. Set it back to false when you want fallback restored. Review where prompts may be sent before enabling additional providers.
Read any config set notes on stderr. A persisted change may still require a daemon restart to take effect. If requested, wait for active work to settle and use your installation's normal daemon restart procedure. Then test one agent:
```
holon config doctor
holon run --agent reviewer "Reply with a one-sentence greeting. Do not use tools or change files."
holon agent get reviewer --detail full
holon transcript --agent reviewer --limit 20
```

Confirm it worked

The model list and doctor report show an available primary route. The test returns a brief. In agent detail, inspect model.requested_model, model.active_model, and model.fallback_active when present, and compare them with the transcript's provider metadata. These distinguish the configured preference from the route used after fallback. Do not rely on the model identifying itself in prose.

Local or custom endpoints

For a local Ollama server, pull a model in Ollama first, then select its available route, such as ollama@default/<installed-model>. No API key is required for the built-in localhost provider.

For a custom provider, use the declared management command:

holon config providers set my-proxy \
  --transport openai_chat_completions \
  --base-url "https://my-proxy.example.com/v1" \
  --credential-source env \
  --credential-env MY_PROXY_API_KEY \
  --credential-kind api_key

Replace the endpoint and configure its credential in the daemon environment. Inspect holon config models list before selecting it. Endpoint, plan, and model-metadata fields are in the Configuration reference.

Configure image tools separately

Choose routes that support the operation and whose credentials are available to the daemon. For example, with the corresponding providers configured:

holon config set vision.default "anthropic@default/claude-sonnet-4-6"
holon config set image_generation.default "openai@default/gpt-image-2"
holon config get vision.default
holon config get image_generation.default

These settings leave the conversation model unchanged. Follow any restart notice, then test image inspection with a harmless local image, or image generation with a small request. Check the tool's actual result and provider selection, not just the stored configuration. Generation may incur provider charges.

Without explicit routes, the tools use their documented discovery rules. See vision selection and image routing for capability and transport requirements. A working text conversation does not verify either image tool.

Troubleshooting

Missing or expired credentials: rerun holon onboard for OAuth, or update the intended credential profile through stdin. Check the provider's configured credential source.
Unknown or unavailable route: copy a route from the model list and check endpoint/model access. Metadata declarations do not give an account access to a model.
Unexpected provider: inspect the agent override, fallback policy, and actual execution metadata; then decide whether fallback should be disabled.
Stored value differs from running behavior: inspect stderr for the applied-via result or restart note. Do not repeatedly rewrite the same key.
Custom catalog edit: models.catalog is an object value. Preserve existing entries when adding overrides instead of replacing the whole map with a one-entry example.

For advisory-only model routing, use Configure advisory decisions.