Configuration schema and consequences

Which configuration are you reading?

aii -dir DIRECTORY -config FILE starts the application; it is not a configuration-inspection command. Normal startup can create a missing configuration and proceed toward firstboot. Prefer Settings for supported operator changes; do not paste private configuration into chat or an issue.

Diagram — four configuration layers, narrowest last.

An absent field can inherit a value; explicit zero is not universally omission. ReadConfig rejects unknown fields in most typed sections and trailing content (custom map/unmarshal sections can differ) and validates selected values; it does not rerun every default after decoding.

Examples: the template dashboard port is 8180; applyDefaults has a 8080 zero fallback, not a promise that every explicit saved zero becomes 8080. Identity path blanks in the template become data/ledger.jsonl, data/aii.db, data/identity.sec. Default LLM/probe timeouts are 120/45 seconds, recent turns 20, shell timeout 120 seconds. A blank dashboard host is ruled to loopback 127.0.0.1; non-loopback forces TLS even if saved tls is false. TLS is not permission to expose a dashboard safely without reviewing authentication and routing.

All 19 top-level areas

Keys below are relative to the named area. Seconds, milliseconds, bytes, token and character counts are different units; changing a limit does not guarantee capacity, permission or cost control.

Use the direct-link summary to locate each area; the recognized settings and consequences follow.

identity

ledger_path, db_path, key_path locate the record, database and private signing key. db_format accepts empty, sqlite, zstd; db_optimize_levels, db_learn_dictionary concern database compression optimization. These are not reset controls: changing a path is not migrating an identity. Never share the key.

llm

provider, model choose inference routing; api_key_env names a credential environment variable (default name OPENAI_API_KEY, not a supplied credential). timeout_seconds, probe_timeout_seconds, stream, retries, retry_backoff_ms govern request handling. Provider settings can add destinations and charges; retries are not free or an undo.

dashboard

host, port, tls, origin control serving/routing; require_token, access_token, skip_signin_with_valid_token control access/sign-in behaviour. operator_ascii, expert, notices_off_dashboard affect presentation; stop_drain_seconds bounds shutdown drain. auth_token_sha256 is legacy migration input, not a current token. Tokens are secrets. Settings HOST/PORT/HTTPS changes require restart; saving them does not rebind the current listener. See deployment and access for the different live-token and configuration-reload boundaries.

speech

stt has provider, model, language, api_key_env, timeout_seconds, monthly_minutes; tts has provider, model, voice, api_key_env, timeout_seconds, monthly_characters. speakers has mode, uids, unidentified, revision; operator_speakers links operator speaker UUIDs; voice mode has listen, speak, revision. Audio transmission, playback and who counts as operator are consequential: names alone are not speaker authentication. Revisions are control state, not arbitrary labels.

tools

cwd, extra_roots establish working/filesystem reach; local_hosts widens permitted local-network destinations; disabled switches named builtins or plugin operations off. shell_timeout_seconds, webfetch_timeout_seconds bound tool execution. Additional roots are grants of reach, not invitations to read everything. Legacy bash_timeout_seconds maps to shell timeout and disabled bash maps to shell.

plugins

autoload chooses trust-tier loading policy (none, T0–T3 recognized); certifier_root, reviewer_root, platform_root, catalog_dir, catalog_url locate trust/catalogue inputs; worker_binary selects a worker. grants, auth_profiles, runtime, resources, settings, dev_section are detailed below. Verification is not authorization for every effect.

projects

root locates project work. It does not bypass filesystem restrictions.

prompt

max_tokens (zero derives from model window), max_tool_result_chars, pulse_interval_seconds, recent_turns, ring3_max_chars, surfacing_max_chars, self_model_max_tokens, dream_conversation_max_chars, tensions_max_chars govern bounded supplied context and prompts. Reducing context is not deleting stored history.

agency

max_tool_rounds, max_subagent_depth, max_parallel_subagents, subagent_wall_seconds, subagent_wall_seconds_local, subagent_max_mints, subagent_max_tool_rounds, subagent_max_tool_calls, subagent_max_legs, subagent_continuation, spawn_queue, rhythm_seconds, outcome_window, queue_workers, harvest_wake, yield_answer, turn_continuation, turn_token_budget bound or coordinate ongoing work. roles maps role names to provider/model; prefer_local_for_roles expresses routing preference, not authority or proof of local-only processing. More parallel work can increase resource use and charges.

timezone

Timezone selection, separate from record durability or scheduling guarantees.

witness_server

url, interval_events, platform_pubkey_path, tls_spki_sha256 configure witness destination, cadence and trust pins. Witnessing is not a replacement for retaining backups.

certificate

server_url, tls_spki_sha256, acme_directory, contact, route_mode, relay_endpoint, direct_addresses configure public-name/certificate routing. Empty server URL defaults to https://certificate.aiii.id; none disables that server selection. Default ACME directory is Let's Encrypt production. Review network disclosure and public reach before enabling a route.

genesis

server_url, firewall_url, bootstrap_url select founding services; shipped template uses the corresponding *.aiii.id HTTPS services. A local model is not offline founding.

updates

automatic, repo configure software updates. Template sets automatic true. Update/recovery procedures belong in Operations, not manual edits to installed program files.

machine

dir selects a machine-service directory; empty uses the account arrangement. A development service needs explicit matching configuration. Shared service/store effects can cross identity boundaries within the account.

logs

dir, max_backups, compress_days, max_days control retention/storage; level, detail, taps, group control diagnostic detail/capture/grouping. Tap entries contain until. Template uses log, nine backups, seven compression days. Raw captures can contain sensitive payloads; CLI overlays can differ from saved config.

maintenance

enabled, backup_keep, on_demand_spacing_seconds configure continuity maintenance; template enables it and keeps eight. Loader accepts spacing zero (default 600 seconds) or 1–86400. Encryption/recovery state is not established by enabling maintenance: see Operations.

memory

salience supplies weights/thresholds; meaning_source chooses meaning input. backfill_seconds, backfill_rows, backfill_local_seconds, embed_cue_seconds, embed_memory_seconds, source_check_retry_seconds, reply_hold_seconds, conversation_vector_window bound embedding/backfill/retrieval work. Provider-backed meaning may disclose text to that provider; persistence does not establish perfect recall.

contacts

Entries have name, channel, address, wake, operator. This is destination/authority configuration: use synthetic examples, never publicize real addresses. Operator designation is consequential, not an address-book decoration.

Plugin subareas and salience

Plugin runtime and per-plugin resources

plugins.runtime: max_installed_bytes, max_files, max_file_bytes, max_compressed_bytes, max_depth, roots_kept, max_startup_ms, admission_memory_reserve_bytes, slow_storage_call_ms, admission_memory_budget_bytes, max_concurrent_starts govern package/admission/storage resources. Former fixed byte defaults are treated as unset; free disk can decide component capacity. resources[plugin]: memory_max_bytes, startup_timeout_ms, stream_max_bytes, files_max_bytes impose per-plugin bounds. settings[plugin] is plugin-defined JSON; dev_section has id, path.

Plugin grants

grants[plugin]: voice, kv, hosts, local, plaintext_credentials, auto_confirm, read_only, credential_handles, embeddings, memory, interactions, files, tools. Grant only intended capabilities; plaintext credentials, auto-confirmation, local destinations and record access deserve special scrutiny. Retired roots grants nothing; use supported Sandbox controls.

Plugin authentication profiles

auth_profiles[name]: secret_env, secret_file, host, port, scheme, provider, client_id, client_secret_file, client_secret_env, hosts, scopes, token_file, authorize_url, token_url, device_url, revoke_url, redirect_uri describe credential sources and OAuth destinations. They are not safe example material from a live account.

Memory salience

memory.salience: impact, novelty, recurrence, tension_delta, provenance_trust, persistence_hint, emotional_salience, cost_to_store, cost_to_query, downstream_use, belief_at, value_at, version configure scoring/classification, not evidence that a belief is true.

Retired agency coaching keys heuristic_nudges, breadth_nudge, plan_nudge, planning_brief are accepted but dropped, not active controls.

Provider registry is separate

providers.json beside the selected configuration holds model_catalogue_url, oauth, providers, model_capabilities, dialect_effort_floor. Provider entries group endpoint/dialect (name, api_type, url, local), credentials (api_key, api_key_env, credential, oauth, credential options), model lists/defaults/windows, generation/thinking/cache controls, embeddings and speech. A registry API key is a stored secret; an environment-variable name is not that secret. Discovery/catalogue facts, configured limits and a model actually available at the endpoint can differ. This reference inventories application configuration, not every provider dialect, OAuth profile or plugin-specific settings schema. Do not infer hot reload for every setting from a successful save.

Back to section overview · Documentation home