Configure Mecatl

Configure the process that runs the agent. A mecatui client connected to a remote server cannot change that server's providers, permissions, storage, or other operator settings.

Mecatl separates shared agent policy, credentials, daemon topology, command-line overrides, and terminal UI preferences. Keep each setting in its own configuration file or deployment input.

Configuration at a glance

Configuration	Practical location or input	Owner	What it configures
Operator settings	$XDG_CONFIG_HOME/mecatl/settings.yaml (usually ~/.config/mecatl/settings.yaml)	Server operator	Providers and models, permissions, posture, MCP profiles, and other shared agent policy.
Provider credentials	$XDG_CONFIG_HOME/mecatl/auth.yaml (usually ~/.config/mecatl/auth.yaml), or --api-key-file	Server operator	Provider API keys and the experimental Codex credential snapshot.
Daemon topology	A chosen daemon.yaml, passed to mecated serve --config PATH	mecated operator	Listener addresses, TLS material, and rate limits. It is not automatically loaded and never contains the API bearer token.
CLI flags and environment	Invocation flags and documented environment variables	Process launcher	Deployment-specific overrides such as workspace, provider, model, store, or transport.
mecatui client settings	$XDG_CONFIG_HOME/mecatui/settings.yaml (usually ~/.config/mecatui/settings.yaml)	Local terminal user	Keybindings and status-line presentation only.

Use mecated config init to create settings.yaml, and use mecated config validate to check it without starting the server. The generated configuration reference lists the complete schema, defaults, and allowed configuration tiers.

Which settings apply?

Deployment option	Operator settings.yaml and auth.yaml	daemon.yaml	Agent/server flags	Client-only mecatui settings	Effective defaults
mecated serve	Read at startup.	Available through mecated serve --config PATH.	Configure the daemon; applicable explicit flags override file values.	Used only by a separate client.	Daemon defaults, then operator settings, then applicable explicit flags.
Bare mecatui	Read by the embedded server at startup.	Not used.	Configure the embedded server.	Read locally.	Embedded-server defaults, operator settings, then applicable explicit flags.
mecatui connect ADDRESS	Read by the remote server.	Owned by the remote operator.	Only connection and client flags apply.	Read locally.	The remote server controls agent behavior; local settings control only the client and connection.
mecatequi	Read at startup.	Not used.	Configure the single run.	Not used.	Headless defaults, operator settings, then applicable explicit flags.
mecak8s	Mount settings.yaml from a ConfigMap and auth.yaml from a read-only Secret. You can also project provider and MCP credentials as documented environment variables.	Not used; Helm and Kubernetes own topology.	Helm values supply arguments and environment variables.	Not used.	Headless auto posture, no-filesystem placement, pod listeners, Redis state when configured, and Kubernetes Lease coordination.

For the daemon and Kubernetes operating details, see Run mecated standalone and Cloud-native k8s with mecak8s. For one-shot CI ownership, see Single-shot CI with mecatequi.

Ownership and precedence

settings.yaml is the user-global operator file. Put provider keys in auth.yaml, and use --api-key-file to select a non-default credentials file. The process reads both files at startup, so restart it after changing either file.

A trusted project can contribute project-tier settings from .mecatl/settings.yaml or .mecatl/settings.local.yaml. Operator-only settings remain user-global. Permission sources have their own ordered scopes, including explicit --permission-config files. See Permissions and posture for the trust and precedence rules.

An applicable explicit CLI value overrides the corresponding file setting. Flags and environment variables are command-specific, so check the command's --help-all output before reusing an option with another executable or mode.

daemon.yaml uses its own precedence: defaults, then the daemon file, then an explicit mecated serve flag. It controls listener topology, TLS, and rate limits. Supply the daemon API bearer through --auth-token or MECATL_AUTH_TOKEN.

Select harness context sources

Use harness_context in operator settings to choose instruction, command, rule, skill, and agent-definition sources independently of execution placement. For example, this policy keeps the configured local sources but disables agent definitions:

harness_context:
  enabled_sources: [local]
  kinds:
    instructions: { sources: [local], mode: combine }
    commands: { sources: [local], mode: combine }
    rules: { sources: [local], mode: combine }
    skills: { sources: [local], mode: combine }
    agent_defs: { sources: [], mode: combine }

Include all five kind mappings and set each mode to combine or replace. An empty sources list disables that kind. Sources appear in highest-precedence order. combine concatenates instructions and combines named entries, keeping the first entry for each name. replace selects the complete contribution of the first nonempty source after exclusions.

The built-in compatibility IDs are:

ID	Kinds	Availability
local	All five	The configured startup project and existing local customization settings, subject to their existing enablement and project-trust checks.
skills	Commands	The command view of the skills selected by this policy.
driver	Commands, skills, agent definitions	Only for each kind with a configured content-source driver. There is no built-in instruction or rule driver registration.
mcp	Commands	When MCP prompts are enabled.

Other IDs, such as deployment, organization, or repository, require a trusted composition root to register the corresponding typed sources before calling app.Build. A deployment can register a project-provenance source that reads the selected session's execution files. Mecatl authorizes that source against the session's exact placement and gives it a read-only view; the source cannot choose a root or environment reference. This capability is part of the deployment registration, not the settings schema.

IDs are registration names, not paths or transport names; a settings file does not create adapters. Ask your deployment owner which additional IDs and kinds are available. Every enabled ID must appear in at least one kind. Unknown, disabled, duplicate, unused, or kind-incompatible references fail startup without falling back to execution files.

A project harness_context block is ignored in full with a warning that omits its values, even in a trusted project. Source selection cannot grant tool permissions or bypass project trust. A selected source that requires execution files fails for a no-filesystem session; there is no silent fallback. Use an independent registered source for that profile, or disable the execution-file source in operator policy. A no-filesystem session can still use separately configured file-backed or service-backed logical sources; reading those sources does not authorize execution-file edits.

Restart the process after changing source policy. Existing sessions and schedules use the current policy and current source authorization when they rebind. Commands remain live between calls; instructions refresh per run; rules, skills, and agent definitions keep their source-binding snapshots. With no harness_context block, existing source settings and precedence apply, bound to the configured startup source rather than each session's execution placement.

See the configuration reference for the strict schema. Named overrides replace only their listed candidates when the declared winner is present; an earlier non-replaced source still wins. Exclusions and overrides never merge entry bodies.

Configure the command runner

Use command_runner.shell to choose the interpreter for built-in local Shell runners. An explicit --shell value overrides this setting, including --shell "" to disable Shell. --no-shell always disables Shell.

The built-in main runner removes credential-shaped environment variables by default. To make a specific external CLI credential available to main-session Shell commands, list its environment variable name without its value:

command_runner:
  shell: /bin/sh
  environment:
    inherit:
      - GH_TOKEN

The variable must already be present in the Mecatl process environment. The setting grants ambient access to every permitted main-session Shell command, so use a credential limited to the intended service. Shell commands must not inspect, print, copy, write, or commit credential values.

Mecatl never restores its own provider, web-search, server, driver, MCP, or other configured credential references. Read-only Subagents, Team members, Parallel branches, and internal Git operations retain fully scrubbed environments. A direct-write Subagent uses the main runner and receives the same deliberate grants. Independent attenuation for direct-write children requires a future same-workspace child runner; direct-write mode is not a child credential-isolation boundary.

The setting applies to mecated, mecak8s, mecatequi, and the server embedded by bare mecatui. A custom placement provider owns its complete execution environment and is unchanged. Project command_runner blocks are ignored with a value-free warning. See the configuration reference for the complete schema.

Configure provider credentials

Model provider setup is covered in Choose models and providers. For a service, keep credential custody with its operator: supply credentials to the process or an operator-owned credential file, and restrict file access to the service account. Configure providers and storage explains daemon-specific paths, precedence, and reload behavior. Kubernetes and CI deployments own their Secret and workflow-secret handling in their guides.

Embedded and connected mecatui

Bare mecatui embeds a private server. Its local operator settings, credentials, and embedded-server flags control provider availability, workspace policy, storage, and permissions.

mecatui connect ADDRESS connects to an existing server whose operator controls those choices. Local connection credentials authenticate the client; they do not configure the remote server.

The terminal client reads $XDG_CONFIG_HOME/mecatui/settings.yaml in both modes. These UI settings do not alter server behavior. For keymaps, the client file has the lowest priority and mecatui --keymap has the highest priority. See Keybindings, Customize mecatui, and Connect to a server for client and transport details.

Next steps

• Choose models and providers.
• Configure permissions and posture.
• Configure MCP connections.

Related information

• Configuration reference lists every settings key, type, default, and allowed tier.
• Connect to a server covers client transport and authentication.
• Keybindings covers client-owned overrides.