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

The provider chain is the primary model (agent override, or model.default when no override is set) followed by model.fallbacks. model.default never joins the chain as an implicit fallback; when you want it as a safety net, list it in model.fallbacks explicitly or rely on the auto default.

# 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"]'

# Use the auto default (one preferred route per authenticated provider)
holon config set model.fallbacks '["auto"]'

# 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.

Model Catalog Overrides (models.catalog)

models.catalog accepts a JSON object mapping logical model refs (provider/model) to override objects. Common override fields include:

# Register a custom model with decision capability and protocol
holon config set models.catalog '{"cloudflare/clef-flash":{"decision_protocol":"cloudflare_clef","capabilities":{"decision":true}}}'

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.

Authentication & Session Settings

Holon supports session-based authentication for browser and Web UI clients alongside bearer token authentication.

For a step-by-step guide covering IdP setup and session audits, see Configure OIDC authentication.

Session Lifetime Rules:

• When configured, auth.session.absolute_ttl_seconds must be greater than or equal to auth.session.idle_ttl_seconds.
• Setting auth.session.absolute_ttl_seconds to null (or omitting it) disables the absolute cutoff. For backwards compatibility, setting 0 normalizes to null.
• Production deployments require HTTPS for both issuer_url and callback endpoints. HTTP is only permitted when the callback host is localhost.
• Daemon restart is required when changing auth.mode or OIDC parameters.

# Configure session timeouts
holon config set auth.session.idle_ttl_seconds 43200

# Enable OIDC authentication
holon config set auth.mode "oidc"
holon config set auth.oidc.issuer_url "https://auth.example.com/realms/holon"
holon config set auth.oidc.client_id "holon-client"
holon config set auth.oidc.client_secret_env "HOLON_OIDC_CLIENT_SECRET"

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.

Cookie-authenticated unsafe requests

Cookie Origin protection is disabled by default. This keeps browser sessions working through Tailscale Serve, HTTPS termination, reverse proxies, custom domains, and standalone Vite proxies without deployment-specific configuration. To opt into strict protection, set one or more exact origins:

holon config set api.csrf.trusted_origins '["https://admin.example:8443"]'

When the list is non-empty, unsafe requests (POST, PUT, PATCH, and DELETE) authenticated by the browser's holon_session cookie must carry an allowed browser source. Holon accepts an Origin matching the request Host by scheme, host, and port, or an exact configured origin. If Origin is absent, Sec-Fetch-Site: same-origin and same-origin Referer are accepted as fallbacks; otherwise the request is rejected with HTTP 403. The guard is independent of CORS and also covers /apps plus browser session exchange/pairing redemption. Bearer requests, Unix-socket trusted-local requests, and native credential endpoints remain compatible. Trusted origins must be explicit http:// or https:// origins with an optional port; wildcard *, paths, queries, and forwarded proxy headers are not accepted.

Prompt Attachments

The prompt HTTP request body limit is derived as max(32 MiB, 2 × api.prompt.attachment_max_bytes) (128 MiB by default), allowing room for Base64 and JSON. Runtime reload applies changes to new requests; each in-flight request keeps one snapshot for both limits.

Projection Gate

Scheduler

The canonical scheduler is always enabled. runtime.scheduler is no longer a configurable key. For one minor release, an existing persisted runtime.scheduler=canonical value or HOLON_SCHEDULER=canonical environment value is accepted with a deprecation warning. legacy and all other values fail startup. Remove the obsolete selector from deployment configuration.

Migration 40 marked the rollout tables as retired compatibility data. The follow-up cleanup migration removes them after recovery reaches a fixed point. They do not decide authority during startup, ordinary scheduler transactions, or typed repair.

The follow-up cleanup migration fails closed while any canonical execution is open, any execution work item is in flight, or any queue entry is dequeued. The error lists the affected agent IDs. Stop Holon and run holon debug scheduler-recovery --agent <agent> to report, apply the typed recovery, and report again. This command can open the immediately preceding schema without triggering cleanup; other current-binary commands cannot.

Holon v0.31.1 is the rollback release for deployments that still require the legacy scheduler. Use it only with a pre-migration database backup; a database migrated by the follow-up schema cleanup is not downgrade-compatible.

Decision Subsystem Settings

# Enable the Decision subsystem and advisory tool
holon config set decision.enabled true
holon config set decision.tools.enabled true

# Route decisions to a dedicated provider model
holon config set decision.model "typesafe@default/typesafe-ai/jev"

# Or enable the zero-egress local ONNX provider
holon config set decision.local_onnx.enabled true
holon config set decision.local_onnx.preset "jev-selector-q4f16"

# Set safety guardrails
holon config set decision.tools.max_calls_per_turn 3
holon config set decision.tools.min_confidence 0.65

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.

Ollama (local)

Holon includes a built-in ollama provider for running models locally with Ollama. It requires no API key and targets a local Ollama server at http://127.0.0.1:11434 over the Anthropic Messages transport.

1. Install and start Ollama, then pull a model, for example ollama pull qwen3.8:latest.
2. Select Ollama during holon onboard, or set it directly:

holon config set model.default "ollama/qwen3.8:latest"

The Web GUI discovers locally running Ollama models without any credential configuration, and ViewImage automatically discovers Ollama vision models for image analysis.

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:

Runtime Observability

OTLP trace export is optional and disabled by default. OpenMetrics is exposed through the protected /api/control/runtime/metrics endpoint whenever the control API is running.

OTLP settings take effect when the daemon starts. See the runtime observability guide for Collector, Prometheus, Grafana, alerting, and troubleshooting examples.

Web Fetch/Search Settings

Runtime Database Retention

Configure automatic retention cleanup for SQLite runtime events, transcripts, and tool executions:

Command Task Output Safety

Configure on-disk output limits, execution quotas, and filesystem free-space waterlines for background command tasks:

Environment Variables

Each command task setting can also be overridden via environment variables:

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.

Decision Subsystem

The Decision subsystem provides non-authoritative advisory second opinions to agents facing high-ambiguity choices. It is isolated from the primary conversation loop:

• Advisory by design: Results from AdvisoryDecision provide structured evidence (ranked options, choice, confidence, reasoning). They never grant permissions, bypass execution gates, or alter lifecycle state.
• Provider options: Holon supports three Decision provider kinds:
  • Local ONNX: Embedded zero-egress inference using the local-onnx feature, pre-packaged presets (such as jev-selector-q4f16), and question-tail encoding.
  • Native Jev: Direct HTTP integration with TypeSafe Jev endpoints.
  • OpenAI-compatible: Standard remote model endpoints advertising Decision capability.
• Route isolation: Decision models require explicit capability advertisement and dedicated routes, preventing decision traffic from competing with primary agent context.
• Defensive guardrails: Configure decision.tools.max_calls_per_turn to cap per-turn invocations and decision.tools.min_confidence to force explicit abstentions when confidence is low.

Supervised Subagent Maintenance

The daemon's existing deletion coordinator also observes retained private subagents. Parent agents can call DeleteAgent directly; creating a child needs no retention duration. GetAgent on the current parent includes a bounded subagent_cleanup responsibility list without activating any child.

Reminders are enabled by default; idle retirement is opt-in. Both actions use runtime config reload. Stopped or budget-exhausted parents are deferred. Missing supervision and repeatedly failed parent cleanup produce deduplicated operator attention without an extra model call. Disabling an action stops new admissions; accepted deletion jobs continue. Idle retirement rejects active work, waits, timers and pending wake obligations. The durable default callback endpoint survives and reloads the agent through host ingress. Validate residency and reload latency on the deployment before enabling automatic retirement.

Authentication and API Security

Holon enforces session lifetimes and optional CSRF protection for HTTP endpoints:

Session Inactivity Policy

Authenticated Web GUI and native client sessions expire after 7 days of inactivity by default. Any valid request refreshes the idle timer up to the optional auth.session.absolute_ttl_seconds ceiling.

Cookie Origin Guard

When your deployment serves cookie-authenticated sessions across origins, populate api.csrf.trusted_origins with exact trusted origins (e.g. ["https://app.example.com"]). Unsafe mutating requests (POST, PUT, DELETE, PATCH) with session cookies must present an exact matching Origin header. Requests without an Origin or with an unlisted origin fail closed with HTTP 403.

See Also

• CLI Reference — Complete CLI command reference
• Getting Started — Step-by-step setup tutorial
• Agent Templates — Catalog of built-in agent roles