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. When a local daemon is running, these commands prefer the daemon runtime config API; when no daemon is reachable, they fall back to the offline config store. set and unset print applied_via=daemon_api or applied_via=offline_store on stderr, while stdout remains the script-facing JSON value/status. Unsupported daemon updates fail with the daemon-provided rejection reason. Accepted daemon updates are persisted to config.json; the running daemon may continue using its current effective config until restart/reload support is available, and the CLI surfaces that daemon note on stderr. 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@default/deepseek-v4-pro"

# Add fallback models (JSON array)
holon config set model.fallbacks '["anthropic@default/claude-sonnet-4-6","minimax@default/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.

Model metadata and executable selection use distinct identities:

• provider/model is a logical model ref used by models.catalog.
• provider@endpoint/model is a model route ref used by defaults, fallbacks, vision/image generation selections, and agent overrides.

Legacy provider/model selection values remain accepted, but all new writes include the endpoint. Inspect or explicitly rewrite existing config and agent state with:

holon config migrate-model-routes          # dry-run
holon config migrate-model-routes --write  # validated canonical rewrite

The write creates a one-time config backup and updates all agent state in a SQLite transaction. Invalid or ambiguous refs prevent partial writes.

HTTP API CORS

CORS is enabled by default for localhost/loopback browser origins on any port: http://localhost:<port>, https://localhost:<port>, http://127.0.0.1:<port>, and http://[::1]:<port>. This lets local Web UIs call a local or remote Holon HTTP/control API when they provide the required Authorization: Bearer <token> header.

Configure api.cors.allowed_origins to add non-local browser origins such as a LAN-hosted Web UI. These origins are added to the built-in localhost/loopback allowlist. For LAN access, the API must also bind to a reachable address such as 0.0.0.0:7878 or a specific LAN IP; a 127.0.0.1 bind is not reachable from other devices. Set api.cors.enabled=false to disable CORS entirely.

holon config set api.cors.allowed_origins '["http://192.168.1.10:5173"]'
holon config set api.cors.allowed_methods '["GET","POST","PATCH","DELETE","OPTIONS"]'
holon config set api.cors.allowed_headers '["content-type","authorization"]'
holon config set api.cors.allow_credentials false
holon config set api.cors.max_age_seconds 600

Do not combine api.cors.allow_credentials=true with api.cors.allowed_origins=["*"]; Holon rejects that unsafe combination.

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.

Credential sources

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)

Provider Endpoints and Plans

Provider configuration separates a provider account from its concrete endpoints. The legacy provider keys still configure the default endpoint:

holon config set providers.openai.transport openai_responses
holon config set providers.openai.base_url "https://api.openai.com/v1"

These are shortcuts for providers.openai.endpoints.default.transport and providers.openai.endpoints.default.base_url. Use endpoint keys when the same provider account needs another transport, base URL, or credential policy:

holon config set providers.volcengine.endpoints.image-openai.transport openai_chat_completions
holon config set providers.volcengine.endpoints.image-openai.base_url "https://ark.cn-beijing.volces.com/api/plan/v3"
holon config set providers.volcengine.plans.image-openai.endpoint image-openai

A plan maps a stable provider alias such as volcengine-image-openai onto a named endpoint. Canonical selections persist that route explicitly, for example volcengine@image-openai/model-id. Existing built-in aliases and older provider/model references continue to work as compatible inputs.

Removing a Provider

holon config providers remove my-proxy

Provider OAuth and login flows

Some providers use OAuth or browser-based login instead of static API keys. Holon supports two OAuth-style flows:

OpenAI Codex OAuth

Codex supports two OAuth flows:

• Device OAuth (recommended) — Holon requests a device code, prints a verification URL and user code. Open the URL in any browser, enter the code, and the daemon automatically polls for completion. The entire flow runs as a background job (see Web GUI Job Monitoring).
• Browser OAuth — The codex CLI opens a browser for OAuth login and stores the credential locally. Holon reads it via external_cli.

The provider uses credential_source: external_cli and credential_kind: oauth for browser OAuth, or device OAuth via the onboarding wizard.

If your credential expires, run holon onboard again — the wizard detects the expiry and guides you through re-authentication.

Vercel AI Gateway OIDC

Vercel AI Gateway uses OpenID Connect (OIDC) for authentication. The onboarding wizard supports this flow when Vercel is selected as the provider.

For both OAuth and OIDC flows, the recommended setup path is:

holon onboard

The wizard handles the entire OAuth flow and stores the credential securely. You should not attempt to configure OAuth providers manually in config.json unless you are scripting a headless deployment.

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@default/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

Agent Template Remote Sources

Configure remote Git repositories that Holon syncs to populate the agent template catalog:

The daemon runs a sync job at startup to fetch remote source templates into the local template library (~/.agents/agent_templates). Re-syncs reuse recorded install mappings and refuse to overwrite locally-edited templates.

HTTP Addressing

Holon separates the listen address from the advertised address:

advertise_url is the URL remote clients (CLI, Web GUI) use to reach the daemon. Set it when the daemon is behind a reverse proxy, tunnel, or on a different network interface than the default localhost address.

callback_base_url is always derived from the listen port as http://127.0.0.1:<port> unless overridden via the HOLON_CALLBACK_BASE_URL environment variable. This keeps same-host webhook callbacks working even when advertise_url is set to a remote address.

See Also

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