agents schema (151-217)

Canonical generated docsThis section is generated from caco config schema --json. The table below preserves the runtime field path, type, required/default markers, and canonical description for every value in this slice.

Agent presets, retry policy, and managed runtime defaults. Model availability is defined canonically under providers.*.models plus model_discovery; legacy agents.{claude,codex,pi}.models is removed.

Field path	Type	Required	Default	Canonical description
└ `agents.pi_daemon.web.port`	`u16`	optional		Dashboard listener port; required when enabled and distinct from the API port.
└ `agents.pi_daemon.web.public_origin`	`string`	optional		Exact plaintext HTTP browser origin override, without credentials, path, query, or fragment.
└ `agents.pi_daemon.web.allow_insecure_http`	`bool`	optional		Optional upstream plaintext HTTP setting.
└ `agents.pi_daemon.ahp`	`map`	optional		pi-daemon 1.0 AHP endpoint; when set, agent messages are delivered as AHP turns instead of socket wakes.
└ `agents.pi_daemon.ahp.url`	`string`	required		ws:// or wss:// URL of the AHP host's /ahp endpoint (for example pi-daemon 1.0).
└ `agents.pi_daemon.ahp.token_file`	`string`	required		Owner-private bearer-token file reference; bearer bytes are forbidden in config.
└ `agents.pi_daemon.ahp.profile`	`string`	optional	cacophony	Host profile (AHP provider) agent sessions are created with.
└ `agents.pi_daemon.ahp.client_id`	`string`	optional	cacophony	Stable AHP client id; a resent message keeps its request id only while this is unchanged.
└ `agents.pi_daemon.ahp.request_timeout_secs`	`u64`	optional	30	Connection and request timeout in seconds.
└ `agents.pi_daemon.ahp.turn_follow_secs`	`u64`	optional	3600	How long Cacophony follows a turn for its end state; only an explicit delivery deadline cancels a turn.
└ `agents.pi_daemon.ahp.identity`	`enum[session_env_file, none]`	optional	session_env_file	How the host learns the agent's identity: session_env_file writes the agent's session.env beside its checkout for the host profile to load.
└ `agents.pi_daemon.ahp.kind`	`enum[ahp, pi-daemon]`	optional	ahp	What the host is: pi-daemon hosts also serve /chord and are attached with pi-client; the pi-daemon host defaults to pi-daemon.
└ `agents.pi_daemon.ahp.chord_url`	`string`	optional		ws:// or wss:// URL of a pi-daemon host's /chord endpoint; defaults to url with its trailing /ahp replaced by /chord.
└ `agents.pi_daemon.ahp.apply_to_pi`	`bool`	optional	false	Opt pi and pi-on-demand TUI agents into /chord delivery through this pi-daemon host's node bridge, falling back to their native pane when the bridge has not accepted a message.
└ `agents.pi_daemon.ahp.adaptor_extension`	`string`	optional		pi-durable-adaptor extension (absolute or ~/ path) that managed pi and pi-on-demand workspaces load with apply_to_pi, so the node's pi-daemon bridge serves their /chord session; unset loads nothing.
└ `agents.pi_daemon.security`	`map`	optional		Owner-trusted host posture for a pi-daemon instance the operator owns.
└ `agents.pi_daemon.security.allow_authority_root_overlap`	`bool`	optional	false	Permit workloads rooted above pi-daemon state/credentials.
└ `agents.pi_daemon.security.trusted_host`	`bool`	optional	false	Accept owner-declared session resources without the host's symlink/foreign-owner/foreign-writer authority gate.
└ `agents.pi_daemon.security.resource_load_policy`	`enum`	optional	strict	strict refuses a session when a declared resource fails to load; lenient records diagnostics like pi does.
└ `agents.pi_daemon.paratenic_connector`	`map`	optional		Cacophony-owned Paratenic connector whose endpoint and credential reference are derived from this exact Pi-Daemon service.
└ `agents.pi_daemon.paratenic_connector.enabled`	`bool`	required		Make Cacophony supervise one Paratenic connector for this exact Pi-Daemon service.
└ `agents.pi_daemon.paratenic_connector.provider_id`	`string`	optional	pi-daemon-cacophony	Stable AHP provider namespace, distinct from pi and the standalone pi-daemon provider; must match a configured launch descriptor.
└ `agents.pi_daemon.paratenic_connector.binary`	`string`	optional	paratenic	Reviewed Paratenic executable path/name.
└ `agents.pi_daemon.paratenic_connector.poll_interval_ms`	`u64`	optional	30000	Pi-Daemon inventory polling interval in milliseconds.
└ `agents.pi_daemon.paratenic_connector.request_timeout_ms`	`u64`	optional	30000	Pi-Daemon API and RPC setup timeout in milliseconds.
└ `agents.pi_daemon.paratenic_connector.launch_presets`	`string`	optional		Owner-private reviewed managed-launch preset descriptor.
└ `agents.pi_daemon.session_environment`	`map[string, string]`	optional		Non-secret environment defaults enforced on every configured logical Pi session.
└ `agents.ahp_hosts.<name>`	`map`	optional		Named AHP hosts that ahp agents' sessions live on; node-local entries win per name; the name pi-daemon falls back to agents.pi_daemon.ahp.
└ `agents.ahp_hosts.<name>.url`	`string`	required		ws:// or wss:// URL of the AHP host's /ahp endpoint (for example pi-daemon 1.0).
└ `agents.ahp_hosts.<name>.token_file`	`string`	required		Owner-private bearer-token file reference; bearer bytes are forbidden in config.
└ `agents.ahp_hosts.<name>.profile`	`string`	optional	cacophony	Host profile (AHP provider) agent sessions are created with.
└ `agents.ahp_hosts.<name>.client_id`	`string`	optional	cacophony	Stable AHP client id; a resent message keeps its request id only while this is unchanged.
└ `agents.ahp_hosts.<name>.request_timeout_secs`	`u64`	optional	30	Connection and request timeout in seconds.
└ `agents.ahp_hosts.<name>.turn_follow_secs`	`u64`	optional	3600	How long Cacophony follows a turn for its end state; only an explicit delivery deadline cancels a turn.
└ `agents.ahp_hosts.<name>.identity`	`enum[session_env_file, none]`	optional	session_env_file	How the host learns the agent's identity: session_env_file writes the agent's session.env beside its checkout for the host profile to load.
└ `agents.ahp_hosts.<name>.kind`	`enum[ahp, pi-daemon]`	optional	ahp	What the host is: pi-daemon hosts also serve /chord and are attached with pi-client; the pi-daemon host defaults to pi-daemon.
└ `agents.ahp_hosts.<name>.chord_url`	`string`	optional		ws:// or wss:// URL of a pi-daemon host's /chord endpoint; defaults to url with its trailing /ahp replaced by /chord.
└ `agents.ahp_hosts.<name>.apply_to_pi`	`bool`	optional	false	Opt pi and pi-on-demand TUI agents into /chord delivery through this pi-daemon host's node bridge, falling back to their native pane when the bridge has not accepted a message.
└ `agents.ahp_hosts.<name>.adaptor_extension`	`string`	optional		pi-durable-adaptor extension (absolute or ~/ path) that managed pi and pi-on-demand workspaces load with apply_to_pi, so the node's pi-daemon bridge serves their /chord session; unset loads nothing.
└ `agents.pi_client_bin`	`string`	optional	pi-client	pi-client binary that attaches to agents on kind: pi-daemon AHP hosts over /chord; a bare name is looked up on PATH.
└ `agents.groups`	`map[string, list[string]]`	optional		Cluster-scoped named agent groups keyed by group name; values are ordered agent IDs or persistent declaration names..
└ `agents.retry`	`map`	optional		Retry policy for managed worker failures.
└ `agents.retry.max_retries`	`u32`	optional	10	Maximum automatic retry attempts.
└ `agents.retry.initial_backoff_secs`	`u64`	optional	5	Initial backoff delay in seconds.
└ `agents.retry.max_backoff_secs`	`u64`	optional	300	Maximum backoff delay cap.
└ `agents.retry.backoff_multiplier`	`f64`	optional	2.0	Multiplier applied after each retry.
└ `agents.stall_timeout_secs`	`i64`	optional	300	Seconds before a running agent with no tool activity is marked Stalled.
└ `agents.stall_escalation_timeout_secs`	`i64`	optional	600	Seconds a Stalled agent is allowed before its tmux is killed.
└ `agents.agent_cleanup_grace_secs`	`u64`	optional	300	Seconds after completion before auto-discarding a completed agent. 0 disables.
└ `agents.agent_directory_warn_age_secs`	`u64`	optional	604800	Doctor warning threshold for old managed-agent runtime directories; diagnostic only, not a pruning policy.
└ `agents.stale_socket_threshold_secs`	`u64`	optional	86400	Seconds before stale orphan tmux sockets are pruned.
└ `agents.runtime`	`map`	optional		Global managed shell/runtime defaults.
└ `agents.runtime.multiplexer`	`string`	optional	herdr	Persistent terminal host for new shell agents: herdr or tmux. Existing agents retain their backend.
└ `agents.runtime.herdr`	`map`	optional		Herdr terminal host settings.
└ `agents.runtime.herdr.session`	`string`	optional	caco	Named Herdr session shared by Caco agents; default selects the user's main Herdr session.
└ `agents.runtime.herdr.binary`	`string`	optional	herdr	Herdr executable on the owning node.
└ `agents.runtime.shell`	`map`	optional		Shell/interpreter configuration.
└ `agents.runtime.shell.program`	`string`	optional	bash	Shell binary path or name.
└ `agents.runtime.shell.init`	`string`	optional	minimal	Init mode: minimal (default), user, or file.
└ `agents.runtime.shell.init_file`	`string`	optional		Custom init file path (when init is 'file').
└ `agents.runtime.shell.args`	`list[string]`	optional		Extra arguments passed to the shell.
└ `agents.runtime.shell.shell_rc`	`string`	optional		Inline shell init content sourced into every agent shell (concatenated across layers).
└ `agents.runtime.path`	`map`	optional		Ordered PATH additions.
└ `agents.runtime.path.prepend`	`list[string]`	optional		Directories prepended to PATH.
└ `agents.runtime.environment`	`map[string, string]`	optional		Non-secret environment defaults.
└ `agents.pi_extra_config_dirs`	`list[string]`	optional		Global extra config directories merged into every managed Pi workspace.
└ `agents.override_pi_agent_dir`	`string`	optional		Global read-only Pi agent directory override passed directly to managed Pi launches.