Configuration Reference

Holon stores runtime configuration in JSON files under ~/.holon/:

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

# 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

# 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

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:

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

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

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

holon config providers remove my-proxy

Listing Available Models

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:

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

# 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 debug instrumentation is controlled by environment variables:

Web Fetch/Search Settings

See Also

• CLI Reference — Complete CLI command reference
• Getting Started — Step-by-step setup tutorial