Configuration reference
This reference lists the operator settings.yaml keys, types,
defaults, and allowed configuration tiers. It is generated from the same
permconfig schema (internal/adapter/permconfig/schema.go) that
parses the file at startup.
For configuration workflows and examples, see Configure Mecatl.
To scaffold a complete commented file, run
mecated config init (or mecated config init --print to print it).
Validate the conventional file with mecated config validate, or select
one with mecated config validate --file PATH; validation is offline,
read-only, and never prints settings values.
The settings file lives at <XDG_CONFIG_HOME>/mecatl/settings.yaml
(default ~/.config/mecatl/settings.yaml). The tier column records
which configuration tier accepts a subtree: operator-tier subtrees are
accepted only from this user-global file and CLI (a project .mecatl/settings.yaml
copy is ignored with a warning);
operator + project subtrees may also be set per-project (within the
operator's limits and trust requirements).
The Default column describes the settings.yaml schema/resolver fallback when
an applicable key is absent ((empty) for an unset string, (absent) for an unset
map/list/sub-block). It is not a universal process-runtime default: command roots
and modes can supply their own defaults, disable a feature, or reject a setting.
The example values in the config init skeleton illustrate configuration choices rather than defaults.
For the configuration planes and intentional per-mode differences, see
Configure Mecatl.
permissions
Tier: operator + project
Allow/ask/deny rule-spec lists. Each entry is "Tool(pattern)" or a bare "Tool". Deny is deny-dominant and binds children too; allow/ask bind the main engine; the subagent block binds child engines. A project allow is trust-gated.
| Key | Type | Default | Description |
|---|---|---|---|
permissions.allow | []string | (absent) | Allow lists rule specs that GRANT a tool call (effect Allow) on the MAIN engine. Under an untrusted project these are DROPPED by the trust gate (see Resolver). |
permissions.ask | []string | (absent) | Ask lists rule specs that REQUIRE approval (effect Ask) on the MAIN engine. Always honoured. |
permissions.deny | []string | (absent) | Deny lists rule specs that BLOCK a tool call (effect Deny) EVERYWHERE — main engine and subagents (a deny only tightens). Always honoured. |
permissions.subagent | subagentpermissions | (absent) | Subagent holds the child-scoped rule-spec lists (issue #32): rules that bind ONLY subagent/member/branch engines, resolved through the child-ask model (a subagent allow can clear a substitution-floored ask; a subagent ask surfaces to the human or auto-denies; a subagent deny blocks). |
permissions.subagent.allow | []string | (absent) | Allow lists child-scoped rule specs with effect Allow (trust-gated for project tiers). |
permissions.subagent.ask | []string | (absent) | Ask lists child-scoped rule specs with effect Ask (always honoured). A configured subagent Ask is NEVER auto-approved by the isolation carve-out — it surfaces to a human or auto-denies. |
permissions.subagent.deny | []string | (absent) | Deny lists child-scoped rule specs with effect Deny (always honoured). |
guardrails
Tier: operator
OPERATOR-TIER LLM content-checker (issue #27). Parsed strictly. A project-tier guardrails: block is IGNORED with a WARN (a project cannot weaken a security checker).
Enable: Configuring
model:ENABLES guardrails;disabled: trueis the kill-switch (the CLI --guardrails=off also sets it).
| Key | Type | Default | Description |
|---|---|---|---|
guardrails.model | string | (empty) | Model is the checker model id / alias. Empty leaves the CLI --guardrails-model to supply it; a value here is overridden by the CLI flag when both are set. Enable: Setting a model here ENABLES contextual guardrails. A configured model with no rules runs the default BLOCK set across Shell, local file mutations and results, web, MCP, and delegation, with the same applicable rules on workers; downgrade via defaultMode: advisory. Leave empty (and pass no --guardrails-model) to keep guardrails OFF. |
guardrails.disabled | bool | false | Disabled is the YAML-level kill switch (the CLI --guardrails=off also sets it). |
guardrails.onCheckerDown | string | (empty) | OnCheckerDown sets the global posture when the checker model is unavailable (error/timeout): "fail" (default, fail-closed) or explicit "warn" (continue with an operational warning). Per-rule failClosed overrides: failClosed:true tightens under warn; explicit false loosens under fail. Empty = fail. |
guardrails.defaultMode | string | (empty) | DefaultMode sets the enforcement mode for the built-in default rules when no explicit rules are configured: "block" (default) or "advisory". An explicit rules list replaces the defaults entirely (this key is ignored). |
guardrails.taskWindow | int | 1 | TaskWindow selects the last K explicitly authenticated root prompts (default 1, clamped 1..3). |
guardrails.escape | bool | false | Escape is the guardrail escape knob: when true AND a checker model is configured, an out-of-root FS escape at posture auto routes through the guardrail checker (an unsafe verdict denies; a checker error fails closed to the write-escape Ask). Default false = the un-routed posture table. |
guardrails.rules | []guardrailrulespec | (absent) | Rules is the guardrail rule list. |
guardrails.rules[].match | string | (empty) | Match is the tool-name matcher (exact / "prefix*" / "*"). |
guardrails.rules[].phases | []string | (absent) | Phases lists "pre"/"post"; empty = both. |
guardrails.rules[].mode | string | (empty) | Mode is "block"/"advisory"; empty defaults to block. |
guardrails.rules[].prompt | string | (empty) | Prompt adds operator task-risk context beneath the fixed harness safety, provenance, evidence, and structured-output rubric; it cannot replace it. |
guardrails.rules[].failClosed | bool | false | FailClosed optionally overrides the fail-closed global default for this rule. |
posture
Tier: operator
OPERATOR-TIER posture-ladder scalar: strict < trusted < auto < yolo (the graduated trust/automation tier). A project-tier posture: is IGNORED with a WARN (a project cannot raise the automation posture). Empty = keep the CLI/default.
| Value | Type | Default | Description |
|---|---|---|---|
posture | string | (empty) | Posture is the OPERATOR-TIER posture-ladder scalar (the graduated trust/ automation tier: strict/trusted/auto/yolo). Like Guardrails it is honoured ONLY from the user-global + CLI tiers; a project-tier file's posture: key is IGNORED with a WARN (a project repo RAISING the automation posture — e.g. posture: yolo — is a security DOWNGRADE the tighten-only project gate forbids, the fail-closed core of this feature). Empty = absent (the resolver returns "" and composition keeps the CLI/default). The composition layer parses the string; permconfig only reads the scalar. |
reasoning-effort
Tier: operator
OPERATOR-TIER reasoning-effort scalar: "" / "auto" (unset — the provider default) / "low" / "medium" / "high" / "xhigh" / "max". OpenAI clamps xhigh/max down to high; Anthropic maps all five. A per-session CreateSession.reasoning_effort out-ranks this default. A project-tier reasoning-effort: is IGNORED with a WARN (a project cannot raise the model's reasoning spend). Empty = keep the CLI/default (provider default).
| Value | Type | Default | Description |
|---|---|---|---|
reasoning-effort | string | (empty) | ReasoningEffort is the OPERATOR-TIER reasoning-effort scalar (the neutral vocabulary "" / "auto" / "low" / "medium" / "high" / "xhigh" / "max"). Like Posture it is honoured ONLY from the user-global + CLI tiers; a project-tier file's reasoning-effort: key is IGNORED with a WARN (operator-tier only, for consistency — a project cannot raise the model's reasoning spend). Empty = absent (the resolver returns "" and composition uses the provider default). The composition layer interprets + clamps the token; permconfig only reads the scalar. |
plan-mode-auto-approve
Tier: operator
OPERATOR-TIER plan-mode auto-approve flag (issue #206): when true, a plan-mode session that parks awaiting a plan-approval ask is auto-approved (flip to default mode and execute) WITHOUT a human reviewing the plan. DEFAULT OFF. A project-tier plan-mode-auto-approve: is IGNORED with a WARN (a project cannot grant an autonomous approval capability).
| Value | Type | Default | Description |
|---|---|---|---|
plan-mode-auto-approve | bool | false | PlanModeAutoApprove is the OPERATOR-TIER plan-mode-auto-approve flag (issue #206). Like Posture/ReasoningEffort it is honoured ONLY from the user-global + CLI tiers; a project-tier file's plan-mode-auto-approve: key is IGNORED with a WARN (operator-tier only — a project repo enabling autonomous plan approval is a security DOWNGRADE). false = absent (the resolver returns false and composition keeps the default OFF). The composition layer interprets the bool; permconfig only reads the scalar. |
providers
Tier: operator
Strict operator-defined LLM providers. Project-tier definitions are ignored. Provider URLs must be HTTPS without userinfo, query, or fragment; credentials belong only in auth.yaml or the shared OIDC credential store.
| Key | Type | Default | Description |
|---|---|---|---|
providers.team-gateway | providerdefinition | (absent) | |
providers.team-gateway.base_url | string | (required) | |
providers.team-gateway.default_model | string | (required) | |
providers.team-gateway.api_flavor | string | (required) | |
providers.team-gateway.auth | providerauth | (required) | |
providers.team-gateway.auth.method | string | (required) | |
providers.team-gateway.auth.oidc | provideroidc | (required only for oidc) | |
providers.team-gateway.auth.oidc.issuer | string | (required) | |
providers.team-gateway.auth.oidc.client_id | string | (required) | |
providers.team-gateway.auth.oidc.scopes | []string | (required) | |
providers.team-gateway.auth.oidc.resource_audience | string | (optional) | Optional OAuth audience parameter and access-token audience binding. Empty omits both. |
providers.team-gateway.auth.oidc.issuer_trust | nativetrust | (required) | |
providers.team-gateway.auth.oidc.issuer_trust.policy | string | (required) | |
providers.team-gateway.auth.oidc.issuer_trust.ca_bundle | string | (forbidden for public) | |
providers.team-gateway.auth.oidc.gateway_trust | nativetrust | (required) | |
providers.team-gateway.auth.oidc.gateway_trust.policy | string | (required) | |
providers.team-gateway.auth.oidc.gateway_trust.ca_bundle | string | (forbidden for public) |
credential_store
Tier: operator
API-key file input and shared protected credential home for OIDC providers. OIDC records always remain encrypted; changing key custody does not automatically migrate them or fall back to another source.
| Key | Type | Default | Description |
|---|---|---|---|
credential_store.api_key | apikeycredentialstore | (absent) | |
credential_store.api_key.file | string | $XDG_CONFIG_HOME/mecatl/auth.yaml | |
credential_store.oidc | oidccredentialstore | (absent) | |
credential_store.oidc.home | string | (required) | Shared protected home for all OIDC provider credentials. |
credential_store.oidc.key | nativecredentialkey | (optional; default keyring) | Shared encryption-key source for the OIDC credential home; omission uses the OS-keyring default, and changing it does not migrate existing records. |
credential_store.oidc.key.source | string | (required) | Closed choice: keyring or environment. Omitting the whole key mapping uses the OS-keyring default. |
credential_store.oidc.key.key_env | string | (required for environment; forbidden for keyring) | MECATL_* environment reference containing canonical padded base64 that decodes to exactly 32 bytes. Only the reference belongs in settings, never the key value. |
provider_overrides
Tier: operator
Strict endpoint overrides for built-in openai, openrouter, anthropic, and opencode only. Codex and ToolHive policies cannot be overridden here.
| Key | Type | Default | Description |
|---|---|---|---|
provider_overrides.openai | provideroverride | (absent) | |
provider_overrides.openai.base_url | string | (required) |
harness_context
Tier: operator
Selects trusted deployment-registered instruction and customization source IDs independently from execution placement. Unknown configured IDs fail startup; registration support is deployment-specific.
| Key | Type | Default | Description |
|---|---|---|---|
harness_context.enabled_sources | []string | (absent) | EnabledSources is the unique allowlist of registered IDs. Each ID must be used by at least one kind; unknown, unused, or unsupported references fail startup. |
harness_context.kinds | harnesscontextkinds | (absent) | Kinds must include all five content kinds, each with an explicit mode. |
harness_context.kinds.instructions | HarnessContextKind | (absent) | |
harness_context.kinds.instructions.sources | []string | (absent) | Sources lists enabled, kind-compatible IDs in highest-precedence order. Empty disables this kind without changing execution capabilities. |
harness_context.kinds.instructions.mode | string | (empty) | Mode is required: combine concatenates instructions or unions named entries; replace takes the complete first nonempty post-exclusion source contribution. |
harness_context.kinds.instructions.exclude | []harnesscontextexclude | (absent) | Exclude removes exact source/name candidates before resolution. Instructions have no names and use source-only exclusions. |
harness_context.kinds.instructions.exclude[].source | string | (empty) | Source must occur in this kind's sources list. |
harness_context.kinds.instructions.exclude[].name | string | (empty) | Name is an exact, case-sensitive logical name. Required for named kinds; forbidden for instructions. |
harness_context.kinds.instructions.overrides | []harnesscontextoverride | (absent) | Overrides changes exact-name collisions in combine mode only. Forbidden for instructions and replace mode. Duplicate or structurally no-op declarations fail startup. |
harness_context.kinds.instructions.overrides[].name | string | (empty) | Name is the exact, case-sensitive collision name. |
harness_context.kinds.instructions.overrides[].winner | string | (empty) | Winner is a configured source ID. If it has no post-exclusion candidate, normal ordered resolution applies without removing any replaced candidates. |
harness_context.kinds.instructions.overrides[].replaces | []string | (absent) | Replaces is a nonempty unique list of configured source IDs, excluding Winner. When Winner is present, remove these candidates, then choose the first remaining candidate in original source order. An earlier non-replaced source still wins. |
harness_context.kinds.commands | HarnessContextKind | (absent) | |
harness_context.kinds.commands.sources | []string | (absent) | Sources lists enabled, kind-compatible IDs in highest-precedence order. Empty disables this kind without changing execution capabilities. |
harness_context.kinds.commands.mode | string | (empty) | Mode is required: combine concatenates instructions or unions named entries; replace takes the complete first nonempty post-exclusion source contribution. |
harness_context.kinds.commands.exclude | []harnesscontextexclude | (absent) | Exclude removes exact source/name candidates before resolution. Instructions have no names and use source-only exclusions. |
harness_context.kinds.commands.exclude[].source | string | (empty) | Source must occur in this kind's sources list. |
harness_context.kinds.commands.exclude[].name | string | (empty) | Name is an exact, case-sensitive logical name. Required for named kinds; forbidden for instructions. |
harness_context.kinds.commands.overrides | []harnesscontextoverride | (absent) | Overrides changes exact-name collisions in combine mode only. Forbidden for instructions and replace mode. Duplicate or structurally no-op declarations fail startup. |
harness_context.kinds.commands.overrides[].name | string | (empty) | Name is the exact, case-sensitive collision name. |
harness_context.kinds.commands.overrides[].winner | string | (empty) | Winner is a configured source ID. If it has no post-exclusion candidate, normal ordered resolution applies without removing any replaced candidates. |
harness_context.kinds.commands.overrides[].replaces | []string | (absent) | Replaces is a nonempty unique list of configured source IDs, excluding Winner. When Winner is present, remove these candidates, then choose the first remaining candidate in original source order. An earlier non-replaced source still wins. |
harness_context.kinds.rules | HarnessContextKind | (absent) | |
harness_context.kinds.rules.sources | []string | (absent) | Sources lists enabled, kind-compatible IDs in highest-precedence order. Empty disables this kind without changing execution capabilities. |
harness_context.kinds.rules.mode | string | (empty) | Mode is required: combine concatenates instructions or unions named entries; replace takes the complete first nonempty post-exclusion source contribution. |
harness_context.kinds.rules.exclude | []harnesscontextexclude | (absent) | Exclude removes exact source/name candidates before resolution. Instructions have no names and use source-only exclusions. |
harness_context.kinds.rules.exclude[].source | string | (empty) | Source must occur in this kind's sources list. |
harness_context.kinds.rules.exclude[].name | string | (empty) | Name is an exact, case-sensitive logical name. Required for named kinds; forbidden for instructions. |
harness_context.kinds.rules.overrides | []harnesscontextoverride | (absent) | Overrides changes exact-name collisions in combine mode only. Forbidden for instructions and replace mode. Duplicate or structurally no-op declarations fail startup. |
harness_context.kinds.rules.overrides[].name | string | (empty) | Name is the exact, case-sensitive collision name. |
harness_context.kinds.rules.overrides[].winner | string | (empty) | Winner is a configured source ID. If it has no post-exclusion candidate, normal ordered resolution applies without removing any replaced candidates. |
harness_context.kinds.rules.overrides[].replaces | []string | (absent) | Replaces is a nonempty unique list of configured source IDs, excluding Winner. When Winner is present, remove these candidates, then choose the first remaining candidate in original source order. An earlier non-replaced source still wins. |
harness_context.kinds.skills | HarnessContextKind | (absent) | |
harness_context.kinds.skills.sources | []string | (absent) | Sources lists enabled, kind-compatible IDs in highest-precedence order. Empty disables this kind without changing execution capabilities. |
harness_context.kinds.skills.mode | string | (empty) | Mode is required: combine concatenates instructions or unions named entries; replace takes the complete first nonempty post-exclusion source contribution. |
harness_context.kinds.skills.exclude | []harnesscontextexclude | (absent) | Exclude removes exact source/name candidates before resolution. Instructions have no names and use source-only exclusions. |
harness_context.kinds.skills.exclude[].source | string | (empty) | Source must occur in this kind's sources list. |
harness_context.kinds.skills.exclude[].name | string | (empty) | Name is an exact, case-sensitive logical name. Required for named kinds; forbidden for instructions. |
harness_context.kinds.skills.overrides | []harnesscontextoverride | (absent) | Overrides changes exact-name collisions in combine mode only. Forbidden for instructions and replace mode. Duplicate or structurally no-op declarations fail startup. |
harness_context.kinds.skills.overrides[].name | string | (empty) | Name is the exact, case-sensitive collision name. |
harness_context.kinds.skills.overrides[].winner | string | (empty) | Winner is a configured source ID. If it has no post-exclusion candidate, normal ordered resolution applies without removing any replaced candidates. |
harness_context.kinds.skills.overrides[].replaces | []string | (absent) | Replaces is a nonempty unique list of configured source IDs, excluding Winner. When Winner is present, remove these candidates, then choose the first remaining candidate in original source order. An earlier non-replaced source still wins. |
harness_context.kinds.agent_defs | HarnessContextKind | (absent) | |
harness_context.kinds.agent_defs.sources | []string | (absent) | Sources lists enabled, kind-compatible IDs in highest-precedence order. Empty disables this kind without changing execution capabilities. |
harness_context.kinds.agent_defs.mode | string | (empty) | Mode is required: combine concatenates instructions or unions named entries; replace takes the complete first nonempty post-exclusion source contribution. |
harness_context.kinds.agent_defs.exclude | []harnesscontextexclude | (absent) | Exclude removes exact source/name candidates before resolution. Instructions have no names and use source-only exclusions. |
harness_context.kinds.agent_defs.exclude[].source | string | (empty) | Source must occur in this kind's sources list. |
harness_context.kinds.agent_defs.exclude[].name | string | (empty) | Name is an exact, case-sensitive logical name. Required for named kinds; forbidden for instructions. |
harness_context.kinds.agent_defs.overrides | []harnesscontextoverride | (absent) | Overrides changes exact-name collisions in combine mode only. Forbidden for instructions and replace mode. Duplicate or structurally no-op declarations fail startup. |
harness_context.kinds.agent_defs.overrides[].name | string | (empty) | Name is the exact, case-sensitive collision name. |
harness_context.kinds.agent_defs.overrides[].winner | string | (empty) | Winner is a configured source ID. If it has no post-exclusion candidate, normal ordered resolution applies without removing any replaced candidates. |
harness_context.kinds.agent_defs.overrides[].replaces | []string | (absent) | Replaces is a nonempty unique list of configured source IDs, excluding Winner. When Winner is present, remove these candidates, then choose the first remaining candidate in original source order. An earlier non-replaced source still wins. |
harness_context.project_instruction_max_bytes | int | (absent) | ProjectInstructionMaxBytes bounds retained project instruction content in bytes across selected sources; omitted uses 65536. A separate equal-sized budget bounds discovered directory and scope metadata. Must be positive when set. |
learning
Tier: operator + project
Optional completed-trajectory observation policy. Off means no automatic completed-trajectory reflection or review; project settings may only tighten the operator ceiling off < review < auto. Separately configured consolidation schedules are independent.
| Key | Type | Default | Description |
|---|---|---|---|
learning.mode | string | off | Mode controls automatic completed-trajectory observation: off (default; no automatic reflection), review (signal-gated reflection stages durable proposals without memory writes), or auto (stage first, then conservatively promote only eligible non-conflicting facts). Operator settings establish the ceiling; project settings may only tighten it under off < review < auto and never raise autonomy. It does not override separately configured maintenance schedules such as --user-model-consolidate-interval. |
learning.admission_interval | int | 1 | AdmissionInterval admits every Nth eligible automatic reflection process-wide. Nil uses the default of 1; zero and one both admit every eligible reflection. This field is operator-owned; project values do not change admission cadence. |
learning.sensitivity | string | balanced | Sensitivity controls weighted automatic admission. Empty means balanced. |
learning.skills | learningskillssection | (absent) | Skills controls learned-skill lifecycle policy. |
learning.skills.activation | string | validated when mode is explicitly auto; evaluated otherwise | Activation is validated (default for Auto) or evaluated. Project settings may only tighten validated to evaluated. |
learning.automatic | learningautomaticsection | (absent) | Automatic is operator-only admission policy. Standard non-off composition applies it through a durable ledger, making count/token windows, cooldown, and deduplication deployment-wide across cooperating processes. |
learning.automatic.cooldown | duration | 10m | Cooldown is the per-principal weighted-admission cooldown; zero disables it. |
learning.automatic.window | duration | 1h | Window is the sliding count/token window, strictly 1m..24h. |
learning.automatic.max_reflections | int | 8 | MaxReflections is the global count cap; zero disables automatic reflection. |
learning.automatic.max_tokens | int | 100000 | MaxTokens is the global reserved-token cap; zero disables automatic reflection. |
learning.automatic.max_reflections_per_principal | int | 4 | MaxReflectionsPerPrincipal is the per-principal count cap; zero disables automatic reflection. |
learning.automatic.max_tokens_per_principal | int | 50000 | MaxTokensPerPrincipal is the per-principal reserved-token cap; zero disables automatic reflection. |
retention
Tier: operator
Versioned automatic session cleanup policy. Operator-tier only; project values are ignored. Zero disables each limit. Explicit compatibility flags outrank these values.
| Key | Type | Default | Description |
|---|---|---|---|
retention.version | int | 1 | Version is the required schema version; the only supported value is 1. |
retention.main | retentionlimitsection | (absent) | Main controls top-level operator/service sessions. |
retention.main.max_age | string | (empty) | MaxAge deletes eligible rows older than this Go duration; 0 disables the age limit. |
retention.main.max_count | int | 0 | MaxCount keeps the newest eligible rows up to this count; 0 disables the count limit. |
retention.child | retentionlimitsection | (absent) | Child controls subagent, parallel-branch, and team-member sessions. |
retention.child.max_age | string | (empty) | MaxAge deletes eligible rows older than this Go duration; 0 disables the age limit. |
retention.child.max_count | int | 0 | MaxCount keeps the newest eligible rows up to this count; 0 disables the count limit. |
retention.scheduled | retentionlimitsection | (absent) | Scheduled controls scheduled-fire sessions. |
retention.scheduled.max_age | string | (empty) | MaxAge deletes eligible rows older than this Go duration; 0 disables the age limit. |
retention.scheduled.max_count | int | 0 | MaxCount keeps the newest eligible rows up to this count; 0 disables the count limit. |
retention.sweep_cadence | duration | 1h | SweepCadence is the repeat interval; 0 disables repeats while retaining the compatibility startup sweep. |
retention.acknowledge_main_deletion | bool | false | AcknowledgeMainDeletion explicitly consents to destructive main-session cleanup. |
system_prompt
Tier: operator
Strict standard prompt policy. Operator-tier only; project values are ignored.
| Key | Type | Default | Description |
|---|---|---|---|
system_prompt.commit_coauthor | bool | true | CommitCoauthor controls the standard commit co-author guidance. Nil preserves the default enabled behavior; false opts out. |
command_runner
Tier: operator
Built-in command interpreter and main-runner environment policy. Operator-tier only; project values are ignored. Explicit --shell overrides shell, and --no-shell disables Shell.
| Key | Type | Default | Description |
|---|---|---|---|
command_runner.shell | string | /bin/sh (command default) | Shell is the command interpreter path. An explicitly empty value disables Shell. |
command_runner.environment | commandrunnerenvironment | (absent) | Environment controls named ambient environment inheritance for built-in main runners. |
command_runner.environment.inherit | []string | [] | Inherit lists portable environment names to retain for built-in main runners. |
temporary_storage
Tier: operator
Managed command temporary-storage policy. Read only from user-global settings.yaml; project and explicit CLI config values are ignored. Managed mode is Linux-only; system preserves inherited temporary-directory behavior.
| Key | Type | Default | Description |
|---|---|---|---|
temporary_storage.mode | string | managed | |
temporary_storage.managed_root | string | mecatl | |
temporary_storage.system_temp_dir | string | inherited | |
temporary_storage.command_reap_after | duration | 1h | |
temporary_storage.reap_interval | duration | 1h | |
temporary_storage.reap_timeout | duration | 5m | |
temporary_storage.shutdown_reap_timeout | duration | 1m |
storage_management
Tier: operator
Exact verified OIDC issuer/subject pairs authorized for process-wide storage health and cleanup. Empty grants nobody; project values are ignored.
| Key | Type | Default | Description |
|---|---|---|---|
storage_management.version | int | 1 | Version is the required schema version; the only supported value is 1. |
storage_management.principals | []storagemanagementprincipal | (absent) | Principals lists exact verified OIDC issuer/subject pairs. Empty grants nobody. |
storage_management.principals[].issuer | string | (empty) | Issuer must equal the verified token issuer byte-for-byte. |
storage_management.principals[].subject | string | (empty) | Subject must equal the verified token subject byte-for-byte. |
execution
Tier: operator
Server-owned execution placement and MicroVM guest-egress policy. Operator-tier only; project values are ignored. Bare mecatui and mecated resolve the same settings.
| Key | Type | Default | Description |
|---|---|---|---|
execution.default_placement | string | host-local | The default_placement setting selects the server-owned default placement backend. |
execution.microvm | executionmicrovmsection | (absent) | The microvm block configures local MicroVM execution without creating a public profile. |
execution.microvm.guest_egress | executionguestegresssection | (absent) | The guest_egress block controls network destinations reachable from the guest. |
execution.microvm.guest_egress.mode | string | permissive | mode accepts permissive, deny-all, or allowlist. Permissive is the default. |
execution.microvm.guest_egress.allow | []string | (absent) | allow lists HOST:PORT/tcp|udp destinations and is valid only in allowlist mode. |
steer
Tier: operator
OPERATOR-TIER mid-run steer knob (steer-while-running, issue #512): when true (the DEFAULT), a client may inject an operator instruction into an in-flight run, drained at the next turn boundary. Set false to disable the steer inbox (the capability echo then reads false and a steer frame reports too_late). A project-tier steer: is IGNORED with a WARN (the harness's operator surface is not a project repo's to flip). Omit = keep the CLI/default (steer ON).
| Value | Type | Default | Description |
|---|---|---|---|
steer | bool | true | Steer is the OPERATOR-TIER mid-run steer knob (steer-while-running, issue #512): enable (default) or disable the mid-run steer inbox. Like Posture/ReasoningEffort it is honoured ONLY from the user-global + CLI tiers; a project-tier file's steer: key is IGNORED with a WARN (operator-tier only — the harness's operator surface is not a project repo's to flip, in either direction). It is a *bool so ABSENT is distinguishable from an explicit false: nil = absent (the resolver reports not-present and composition keeps the DEFAULT-ON); a non-nil value is honoured (composition maps steer: false onto the opt-OUT DisableSteer). |
models
Tier: operator
Provider/model aliases, slots, defaults, and delegated router taxonomy. Every effective binding is operator-owned. A project-tier models block is ignored in full with one warning, regardless of trust. The legacy operator allowlist key remains parseable but has no effect and warns.
| Key | Type | Default | Description |
|---|---|---|---|
models.slots | map[string]modelslotvalue | (absent) | Slots binds a slot name to a model selector. Call slots include "compaction", "ask-reviewer", and "guardrail"; tier slots include "cheap", "fast", and "reasoning". The "plan" slot selects the session model while the session is in plan mode. In default or accept-edits mode, the session uses its default model. When "plan" is unset, it falls through to the "reasoning" tier when configured. The guardrail slot alone also accepts an operator-only explicit provider route. |
models.aliases | map[string]modelaliastarget | (absent) | Aliases binds a short name to either a scalar model ID (bound to the effective configured default provider when present, otherwise contextual) or a strict provider/model object. CLI --model-alias replaces the whole lower-tier target with a contextual scalar; --model-alias-provider supplies its optional provider. |
models.default | string | (empty) | Default is the operator-tier session-default model selector (alias or concrete id). A provider-aware alias selects the whole provider/model default; a separately configured default_provider applies only to scalar selectors. Empty = absent. |
models.subagent | string | (empty) | Subagent sets the default model for unpinned Subagent, Parallel, and Team members. --subagent-model takes precedence. Invalid targets fail startup. |
models.default_provider | string | (empty) | DefaultProvider sets the provider for scalar defaults, aliases, slots, and delegation routes. A provider-aware default alias selects its own provider for the main session; the configured default provider must still be available for scalar bindings. Unknown or unavailable providers fail startup. |
models.allowlist | []string | (absent) | Allowlist is retained for compatibility, has no effect, and emits a warning when configured. |
models.router | routersection | (absent) | Router selects models for unpinned delegated work by category. A non-empty category list enables routing unless disabled here or by CLI. Project-tier models blocks are ignored, including router settings. Enable: A non-empty categories list ENABLES the router (taxonomy-presence enable — NOT a CLI enable-flag); disabled: true (or --subagent-model-router=false) is the kill-switch. Operator-tier only. |
models.router.backend | string | llm | Backend selects llm or jev. Empty input defaults to llm. |
models.router.jev | jevroutersection | (absent) | Jev configures the explicitly selected Typesafe Jev backend. The block is rejected with an active llm backend and ignored for active checks while routing is disabled or has no categories. |
models.router.jev.model | string | jev-1.13.0 | Model is the Typesafe service model. Empty input defaults to jev-1.13.0. |
models.router.jev.base-url | string | (empty) | BaseURL optionally overrides the Typesafe endpoint. Active routing accepts HTTPS or loopback HTTP; omission uses the pinned SDK endpoint. |
models.router.jev.minimum-confidence | float64 | 0 | MinimumConfidence makes a valid lower-confidence answer an ordinary routing miss. Zero disables filtering; values must be finite and in [0,1]. |
models.router.jev.maximum-input-bytes | int | 16384 | MaximumInputBytes bounds the complete rendered textual request before SDK marshalling. Omission defaults to 16384; explicit values must be integers in [1,65536]. |
models.router.classifier-slot | string | (empty) | ClassifierSlot names the model slot the CLASSIFIER itself runs on (the tiny, cheap one-turn classification call). Empty falls through to the router slot's default tier (cheap) — the classifier is housekeeping, not the routed work. |
models.router.categories | []routercategory | (absent) | Categories are the routing choices. Each carries a Name (the classifier's verdict key), a Description (the classifier's only signal — make them distinct), and a Model selector (an alias / slot / concrete id, resolved through the operator- merged alias map; operator taxonomy targets are UNCAPPED). |
models.router.categories[].name | string | (empty) | Name is the routing key the classifier echoes back as its verdict and the key composition maps to Model. |
models.router.categories[].description | string | (empty) | Description is the one-line summary the classifier reads to choose this category. |
models.router.categories[].model | string | (empty) | Model is the model selector (alias / slot / concrete id) a task classified into this category is minted on, resolved through the operator-merged alias map. A scalar target uses the configured default provider when present. |
models.router.default-category | string | (empty) | DefaultCategory is the category the classifier is told to choose when none clearly fits (advisory to the classifier; the real safety net is the fail-soft inherit). |
models.router.disabled | bool | false | Disabled is the YAML-level kill switch (mirroring GuardrailsSection.Disabled): a non-empty taxonomy ENABLES the router, so disabled: true is the "taxonomy defined but temporarily off" override. The CLI kill-switch --subagent-model-router=false also sets it (the two OR together). Default false ⇒ the router is enabled whenever categories are present. |
models.context_windows | map[string]map[string]int | (absent) | ContextWindows is the OPERATOR-TIER exact provider ID → exact final model ID → total context token override map. It is intentionally not a selector map: aliases and slots are resolved before this lookup, and project values are ignored. |
openrouter
Tier: operator
OPERATOR-TIER OpenRouter downstream-provider routing (issue #480): a per-model preferred DOWNSTREAM provider order, sent as OpenRouter's provider request-body object. Setting an order disables OpenRouter's default price load-balancing; allow_fallbacks: false pins hard to the order. A project-tier openrouter: block is IGNORED with a WARN (a project cannot pick the downstream provider).
| Key | Type | Default | Description |
|---|---|---|---|
openrouter.models | map[string]openroutermodelroute | (absent) | Models maps a model id (or alias, resolved in composition) to its downstream-provider routing preference. |
openrouter.models.<key>.order | []string | (absent) | Order lists downstream provider slugs (lowercase-kebab, e.g. "anthropic", "google-vertex", "deepinfra/turbo") tried in order. Setting it disables OpenRouter's default price load-balancing. Base-slug matching applies: "google-vertex" matches all its regions/variants (service tiers excepted). |
openrouter.models.<key>.allow_fallbacks | bool | (absent) | AllowFallbacks, when explicitly false, pins the request to Order with no fallback to other downstreams. Omit the key to keep OpenRouter's default (true); set it to false to disable fallback. |
telemetry
Tier: operator
OPERATOR-TIER opt-out product/adoption metrics (telemetry.productMetrics). Honoured ONLY from the user-global + CLI tiers; a project-tier telemetry: block is IGNORED with a WARN (a project repo cannot flip a user's own telemetry choice in either direction). Omit entirely to fall through to the DO_NOT_TRACK env var and finally the enabled-by-default posture.
| Key | Type | Default | Description |
|---|---|---|---|
telemetry.productMetrics | productmetricssection | (absent) | ProductMetrics is the opt-out product/adoption metrics config. |
telemetry.productMetrics.enabled | bool | (absent) | Enabled is a *bool so ABSENT (nil) is distinguishable from an explicit false: nil = absent (composition falls through to DO_NOT_TRACK then the enabled-by-default posture); a non-nil value is honoured exactly. |
mcp
Tier: operator
Strict OPERATOR-TIER Streamable HTTP MCP authority configuration. Mode selects one mutually exclusive global or session-broker authority; broker mode carries its callback configuration and neutral route declarations. Authentication is a closed none/static_bearer/oauth union. Broker OAuth may use trusted explicit OAuth2 endpoints; preregistered clients take the client secret from secret_file (an absolute path) or secret_env (a MECATL_* environment variable name), in either mode; never put secret values in YAML. Keep secret files outside the workspace (mode 0400 recommended): agent shell commands run as the same user and can read a known file path. Other secret-shaped values are MECATL_* environment references. Project mcp blocks are ignored with a value-free warning.
| Key | Type | Default | Description |
|---|---|---|---|
mcp.mode | string | (empty) | Mode selects global or broker authority. Empty uses the command-root default. |
mcp.broker | mcpbrokerprofile | (absent) | Broker contains options meaningful only in broker mode. |
mcp.broker.callback_url | string | (empty) | CallbackURL is required exactly when broker mode contains an OAuth route. It must be an absolute HTTPS URL without userinfo, query, or fragment; an omitted path or / is normalized to /. |
mcp.servers | []mcpserverprofile | (absent) | Servers is the ordered list of neutral Streamable HTTP route declarations. |
mcp.servers[].name | string | (empty) | Name is an ASCII [A-Za-z0-9_]+ identifier, unique case-insensitively. |
mcp.servers[].url | string | (empty) | URL is an absolute HTTP(S) endpoint without userinfo or a fragment. |
mcp.servers[].auth | mcpauthprofile | (absent) | Auth selects exactly one of none, static_bearer, or oauth. |
mcp.servers[].auth.mode | string | (empty) | Mode is exactly none, static_bearer, or oauth. |
mcp.servers[].auth.static_bearer | mcpstaticbearerprofile | (absent) | StaticBearer names the bearer-token environment reference. |
mcp.servers[].auth.static_bearer.token_env | string | (empty) | TokenEnv is a MECATL_* environment variable name containing the opaque token. |
mcp.servers[].auth.oauth | mcpoauthprofile | (absent) | OAuth declares the OAuth identity, client, credentials, scopes, and network policy. |
mcp.servers[].auth.oauth.profile | string | (empty) | Profile is the required global-mode credential identity profile and is forbidden in broker mode. |
mcp.servers[].auth.oauth.principal | string | (empty) | Principal is the required global-mode credential identity principal and is forbidden in broker mode. |
mcp.servers[].auth.oauth.issuer | string | (empty) | Issuer is the canonical exact origin used by OIDC discovery. It is forbidden when Upstream explicitly selects generic OAuth2. |
mcp.servers[].auth.oauth.upstream | mcpoauthupstreamprofile | (absent) | Upstream optionally selects OIDC discovery or explicit generic OAuth2. Omitted defaults to OIDC. |
mcp.servers[].auth.oauth.upstream.mode | string | (empty) | |
mcp.servers[].auth.oauth.upstream.oauth2 | mcpoauth2upstreamprofile | (absent) | |
mcp.servers[].auth.oauth.upstream.oauth2.authorization_endpoint | string | (empty) | |
mcp.servers[].auth.oauth.upstream.oauth2.token_endpoint | string | (empty) | TokenEndpoint is a canonical HTTPS URL with no query string or fragment: the hardened runtime token client pins the exact origin and controls the request query itself. |
mcp.servers[].auth.oauth.client | mcpoauthclientprofile | (absent) | Client selects exactly one preregistered, CIMD, or DCR client declaration. |
mcp.servers[].auth.oauth.client.mode | string | (empty) | Mode is exactly preregistered, cimd, or dcr. |
mcp.servers[].auth.oauth.client.preregistered | mcppreregisteredclientprofile | (absent) | Preregistered declares a confidential client registered with the issuer. |
mcp.servers[].auth.oauth.client.preregistered.id | string | (empty) | ID is the required preregistered OAuth client identifier. |
mcp.servers[].auth.oauth.client.preregistered.secret_env | string | (empty) | SecretEnv is a MECATL_* environment variable name containing the client secret; mutually exclusive with SecretFile. |
mcp.servers[].auth.oauth.client.preregistered.secret_file | string | (empty) | SecretFile is an absolute path to a regular file containing the client secret; mutually exclusive with SecretEnv. |
mcp.servers[].auth.oauth.client.cimd | mcpcimdclientprofile | (absent) | CIMD declares an HTTPS client-id metadata document URL. |
mcp.servers[].auth.oauth.client.cimd.document_url | string | (empty) | DocumentURL is the required HTTPS metadata-document URL. |
mcp.servers[].auth.oauth.client.dcr | mcpdcrclientprofile | (absent) | DCR selects dynamic registration: direct/global profiles require an empty payload, discover from issuer, and use omitted scopes as openid; broker profiles require discovery_url and nonempty scopes. Ready direct-DCR identity drift is reset-required and uses --reset-dcr-registration; pending identity drift is pending-identity-mismatch and cannot reset or retry until the matching profile, principal, canonical resource, and exact issuer are restored. Corrupt direct-DCR state is not resettable: preserve its records and configuration without editing, deleting, or renaming them, then contact the deployment operator or support team with only the server name and redacted command error—never credential contents, OAuth URLs, client IDs, tokens, keys, or a raw response. |
mcp.servers[].auth.oauth.client.dcr.discovery_url | string | (empty) | DiscoveryURL is required for broker DCR and forbidden for direct/global DCR, which discovers from issuer instead. |
mcp.servers[].auth.oauth.scopes | []string | (absent) | Scopes is the non-empty OAuth scope allowlist, except direct/global DCR may omit it and uses exactly openid. |
mcp.servers[].auth.oauth.request_refresh_token | bool | false | RequestRefreshToken asks the authorization server for refresh capability; direct/global DCR defaults false and rejects true. |
mcp.servers[].auth.oauth.credentials | mcpoauthcredentialprofile | (absent) | Credentials selects one global-mode local or environment credential source and is forbidden in broker mode. |
mcp.servers[].auth.oauth.credentials.mode | string | (empty) | Mode is exactly local or environment. |
mcp.servers[].auth.oauth.credentials.local | mcplocalcredentialprofile | (absent) | Local declares encrypted mutable credentials rooted at an absolute path. |
mcp.servers[].auth.oauth.credentials.local.root | string | (empty) | Root is the required absolute credential-store root. |
mcp.servers[].auth.oauth.credentials.local.key_env | string | (empty) | KeyEnv is the legacy MECATL_* environment variable containing the key. |
mcp.servers[].auth.oauth.credentials.local.key | mcpnativecredentialkey | (absent) | Key selects root-pinned native custody for newly onboarded profiles. |
mcp.servers[].auth.oauth.credentials.environment | mcpenvironmentcredentialprofile | (absent) | Environment declares one externally provisioned read-only credential record. |
mcp.servers[].auth.oauth.credentials.environment.credential_env | string | (empty) | CredentialEnv is a MECATL_* environment variable containing the opaque credential record. |
mcp.servers[].auth.oauth.credentials.environment.allow_process_local_refresh | bool | false | AllowProcessLocalRefresh permits refreshed credentials to live only in this process. |
mcp.servers[].auth.oauth.network | mcpoauthnetworkprofile | (absent) | Network is required. Global profiles enforce its exact-origin egress policy; broker OAuth accepts only an explicit empty mapping until ToolHive can enforce it equivalently. |
mcp.servers[].auth.oauth.network.additional_origins | []string | (absent) | AdditionalOrigins lists canonical exact origins additionally allowed for OAuth traffic. |
mcp.servers[].auth.oauth.network.private_origins | []string | (absent) | PrivateOrigins lists allowed origins that may resolve only to RFC1918 IPv4 or ULA IPv6 addresses. Loopback, link-local, metadata, unspecified, multicast, mapped, public, and other special addresses remain denied. |
mcp.servers[].auth.oauth.network.max_redirects | int | 0 | MaxRedirects is the redirect bound, from zero through five. |
mcp.servers[].auth.oauth.tools | []mcpstatictoolprofile | (absent) | Tools optionally declares this protected backend's tool catalogue statically. Declarations are visible before connection; the first call starts ToolHive's aggregate authorization for every protected backend. The granted bundle unlocks the declared surface only. Omitted, the backend remains discoverable only through pre-prompt workspace enrollment. |
mcp.servers[].auth.oauth.tools[].name | string | (empty) | |
mcp.servers[].auth.oauth.tools[].description | string | (empty) | |
mcp.servers[].auth.oauth.tools[].input_schema | []uint8 | (absent) | |
mcp.servers[].auth.oauth.tools[].read_only | bool | false |
websearch
Tier: operator
HTTP web-search adapter settings. Operator-tier only; project values are ignored.
| Key | Type | Default | Description |
|---|---|---|---|
websearch.enabled | bool | (absent) | Enabled controls whether web search is available. Nil leaves the runtime default unchanged. |
websearch.url | string | (empty) | URL is the generic JSON search endpoint. |
websearch.auth_header | string | (empty) | AuthHeader is the optional request header that carries the search credential. |
websearch.query_param | string | (empty) | QueryParam is the query-string parameter that carries the search text. |
websearch.searxng | websearchsearxngsection | (absent) | Searxng configures the optional SearXNG backend. |
websearch.searxng.url | string | (empty) | URL is the SearXNG search endpoint. |
Flag- / file-configured features (NOT in settings.yaml)
By design, settings.yaml covers the subtrees above. Several other
operator features are configured through CLI flags (and, for some, their own
files) rather than this YAML. See Run mecated standalone
for the full flag tables. The pointers below are the starting points:
| Feature | How it is configured | See |
|---|---|---|
| Soul (operator persona) | --soul-file / --no-soul (+ its own soul.md file) | Skills, commands, and soul |
| User-model learning | --user-model-dir / --user-model-review | Memory and user model |
| Memory | --memory-dir / --memory-store-url | Memory and user model |
| Slash commands | --commands-dir (+ the command .md files) | Skills, commands, and soul |
| Session leasing | --session-lease-* | Run mecated standalone |
The model slots / aliases above also have CLI twins (--model-slot /
--model-alias); the guardrails checker model has --guardrails-model; the
router kill-switch has --subagent-model-router=false. The CLI flag and the
YAML key are two surfaces for the same setting. See Configure Mecatl
for precedence.