---
title: Configuration
summary: Holon configuration files, keys, credentials, environment variables, and diagnostics.
order: 15
---
# Configuration Reference
Holon stores runtime configuration in JSON files under `~/.holon/`:
| `~/.holon/config.json` | Providers, model defaults, TUI, web, and runtime settings |
| `~/.holon/credentials.json` | Permission-protected credential storage (managed via `config credentials`) |
## Configuration Keys
Use `holon config get/set/unset/list` to read and write keys. Use `holon config schema` to see every available key with its type, default, and description.
### Model & Provider Settings
| `model.default` | model_ref | Default provider/model, e.g. `"anthropic/claude-sonnet-4-6"` |
| `model.fallbacks` | model_ref_list | Ordered fallback models when the default is unavailable |
| `runtime.disable_provider_fallback` | boolean | Disable provider/model fallback; require deterministic single-provider execution |
```bash
# Set the default model
holon config set model.default "deepseek-anthropic/deepseek-v4-pro"
# Add fallback models (JSON array)
holon config set model.fallbacks '["anthropic/claude-sonnet-4-6","minimax/MiniMax-M2.7"]'
# Read current default
holon config get model.default
# See all current config
holon config list
# Remove a config key (reverts to default)
holon config unset model.fallbacks
```
### Per-Model Policy
The `models.catalog` key lets you override runtime metadata for specific provider/model refs. Keys under `model.unknown_fallback.*` control policy for models without built-in metadata.
## Credential Management
Credentials are stored securely in `~/.holon/credentials.json`. Use `config credentials` subcommands — **never edit this file directly**.
### Setting Credentials
```bash
# Preferred: use --stdin to avoid shell history leakage
holon config credentials set --kind api_key --stdin deepseek
# Paste your API key and press Enter (Ctrl+D to finish)
# Alternative: --material (visible in shell history — not recommended)
holon config credentials set --kind api_key --material "sk-..." deepseek
```
The `<PROFILE>` argument is a label you choose (e.g. `deepseek`, `bigmodel`, `openai`).
### Listing & Removing
```bash
holon config credentials list
holon config credentials remove deepseek
```
### Environment Variables
As an alternative to the credential store, Holon reads API keys from environment variables:
| Anthropic | `ANTHROPIC_AUTH_TOKEN` |
| DeepSeek | `DEEPSEEK_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| BigModel (Zhipu) | `BIGMODEL_API_KEY` |
| MiniMax | `MINIMAX_API_KEY` |
| Xiaomi MiMo | `XIAOMI_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Fireworks | `FIREWORKS_API_KEY` |
| Together | `TOGETHER_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |
| xAI | `XAI_API_KEY` |
| Moonshot | `MOONSHOT_API_KEY` |
| NEAR AI Cloud (TEE inference) | `NEARAI_API_KEY` |
| Volcengine | `VOLCENGINE_API_KEY` or `ARK_API_KEY` |
| StepFun | `STEPFUN_API_KEY` |
| Qwen | `QWEN_API_KEY` or `DASHSCOPE_API_KEY` |
| HuggingFace | `HUGGINGFACE_API_KEY` or `HF_TOKEN` |
| Venice | `VENICE_API_KEY` |
| Chutes | `CHUTES_API_KEY` |
| NVIDIA | `NVIDIA_API_KEY` |
For a complete, up-to-date list, run `holon config providers list`.
## Provider Configuration
Holon ships with built-in provider definitions for 40+ providers. You can add or override providers in `config.json`.
### Listing Registered Providers
```bash
holon config providers list
```
Each provider entry shows its transport protocol (`anthropic_messages`, `openai_chat_completions`, etc.), base URL, and credential requirement.
### Adding a Custom Provider
```bash
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
```
Options:
- `--transport`: Protocol — `anthropic_messages`, `openai_chat_completions`, or `openai_responses`
- `--base-url`: API endpoint base URL
- `--credential-source`: `none`, `env`, `credential_profile`, or `external_cli`
- `--credential-kind`: `none`, `api_key`, or `session_token`
- `--credential-env`: Environment variable name (when source is `env`)
- `--credential-profile`: Credential store profile (when source is `credential_profile`)
### Removing a Provider
```bash
holon config providers remove my-proxy
```
## Listing Available Models
```bash
holon config models list
```
This shows each model's availability, credential status, provider, transport, and policy (context window, max output tokens, capabilities).
## Agent-Level Model Overrides
Each agent can override the default model:
```bash
holon agent model set "anthropic/claude-sonnet-4-6" reviewer
```
The override is stored in the agent's own configuration, not the global `model.default`.
## Diagnostics
```bash
# Full system health check including model availability
holon config doctor
# List all configuration keys with types and defaults
holon config schema
```
`config doctor` reports: default model, fallback models, per-model availability, provider settings, and retry policy.
## Configuration File Location
Holon resolves its configuration directory as follows:
1. `$HOLON_HOME/config.json` (if `HOLON_HOME` is set)
2. `~/.holon/config.json` (fallback)
Credentials follow the same pattern with `credentials.json`.
## TUI Settings
| `tui.alternate_screen` | `auto`, `always`, `never` | `auto` | Alternate screen buffer behavior |
TUI debug instrumentation is controlled by environment variables:
| `HOLON_TUI_PRESENTATION_LOG` | `1`, `true`, `yes`, `on`, `debug` | unset | Enable `<HOLON_HOME>/logs/tui/presentation.jsonl` debug logging for stream-driven presentation decisions |
| `HOLON_TUI_PRESENTATION_LOG_MAX_BYTES` | positive integer bytes | `5242880` | Rotate the presentation debug log when it reaches this size |
## Web Fetch/Search Settings
| `web.fetch.enabled` | boolean | `true` | Enable WebFetch tool |
| `web.fetch.max_chars` | integer | `20000` | Max characters returned to model |
| `web.fetch.max_response_bytes` | integer | `750000` | Max response bytes before truncation |
| `web.fetch.timeout_seconds` | integer | `20` | Per-request timeout |
| `web.fetch.max_redirects` | integer | `5` | Max redirect hops |
| `web.fetch.allowed_hosts` | string_list | `[]` | Hosts allowed (empty = all) |
| `web.fetch.denied_hosts` | string_list | `[]` | Hosts blocked |
| `web.search.enabled` | boolean | `true` | Enable WebSearch tool |
| `web.search.provider` | string | `"auto"` | Default search provider or `auto` |
| `web.search.mode` | enum | `"fallback"` | Routing mode: `single`, `fallback`, or `aggregate` |
| `web.search.providers` | string_list | `[]` | Explicit auto-mode provider attempt order |
| `web.search.max_results` | integer | `5` | Max results returned |
| `web.search.max_provider_attempts` | integer | `3` | Max providers attempted by fallback/aggregate routing |
| `web.providers.<name>.kind` | string | required | Provider kind: `duck_duck_go`, `searxng`, `brave`, `tavily`, `exa`, `perplexity`, `firecrawl`, `open_ai_native`, `anthropic_native`, or `gemini_native` |
| `web.providers.<name>.base_url` | string | unset | Custom provider endpoint |
| `web.providers.<name>.credential_profile` | string | unset | Credential profile for API-backed providers |
| `web.providers.<name>.capabilities` | json_object | derived | Read-only capability metadata surfaced by `holon config get` and routing diagnostics |
## See Also
- [CLI Reference](/reference/cli.md) — Complete CLI command reference
- [Getting Started](/getting-started/first-agent.md) — Step-by-step setup tutorial