Server CLI reference
These inventories come from the flag help registered by each binary. Defaults
are shown where the CLI prints them; empty values are generally omitted.
Operator environment overrides are excluded from generation. Environment-backed
defaults therefore show their unset form; <WORKSPACE>, <HOME>, and
<XDG_ROOT> stand for deployment-specific paths when present.
Use mecated or mecak8s for deployment workflows. Configuration-file precedence is described in operator settings.
mecated serve
Usage: mecated serve [flags]
Flags:
--acknowledge-main-retention
acknowledge automatic deletion of main sessions. Required when main age- or
count-based retention is enabled.
--agent-source-url string
host and port of a remote agent-definition driver. It replaces --agents-dir and
conventional discovery. Agent-definition hooks run shell commands without
permission prompts, so use only a trusted driver. Startup fails if it is
unavailable.
--agents-conventional
discover agent definitions from conventional project and user directories.
Enabled by default. Agent definitions can steer the model, so use only trusted
locations. (default true)
--agents-dir value
directory of named agent definitions arranged as <name>.md with YAML front
matter. Repeatable; these directories have highest precedence. Agent
definitions can steer the model, so use only trusted directories.
--anthropic-base-url string
override the native Anthropic API base URL (compatible/proxy endpoints; key
from ANTHROPIC_API_KEY)
--anthropic-cache-ttl string
Anthropic ephemeral prompt-cache TTL: "5m" or "1h". Default empty uses 1h on
Anthropic, OpenRouter's Anthropic endpoint and the ToolHive gateway, and the
API default of 5m elsewhere; set 5m for cheaper cache writes. Other values are
ignored with a warning.
--api-key-file string
provider credentials YAML path (default: $XDG_CONFIG_HOME/mecatl/auth.yaml);
environment credentials take precedence
--approve-soul
record the current soul content hash as its baseline. Later hash changes
produce a warning.
--auth-token string
bearer token required on every gRPC/HTTP request (or MECATL_AUTH_TOKEN; empty
disables auth)
--authority-evaluator string
authority evaluator: local (default), noop, or cedar; cedar requires --cedar-
authority-policy (default "local")
--block-profile-rate int
runtime.SetBlockProfileRate in nanoseconds: sample one blocking event per N ns
blocked for /debug/pprof/block. 0 (default) disables it. Adds per-block-event
overhead; enable only when investigating blocking
--cedar-authority-policy string
path to the static operator Cedar authority policy; read once at startup when -
-authority-evaluator=cedar
--child-gc-interval duration
how often the session retention GC re-sweeps after the startup sweep; 0
disables periodic cadence (startup sweep remains for compatibility). Operator
settings: retention.sweep_cadence (default 1h0m0s)
--child-retention duration
retain persisted child sessions for this duration before deleting them. Main
sessions are unaffected. Requires a durable store; 0 disables age-based
cleanup. (default 168h0m0s)
--child-retention-max-per-family int
maximum persisted child sessions per subagent, parallel, or team family. Older
sessions are deleted, excluding active runs. Requires a durable store; 0
disables the limit. (default 500)
--client-ca string
PEM client-CA bundle; enables mutual TLS (require + verify client certs)
--command-source-url string
host and port of a remote slash-command driver. Local commands with the same
name take precedence. Command bodies become user prompts, so use only a trusted
driver. Startup fails if it is unavailable.
--commands-dir string
directory of slash-command templates (<name>.md); setting it enables command
expansion. Empty + --enable-commands uses the defaults (.mecatl/commands,
.claude/commands)
--compaction string
compaction strategy: "heuristic" (default, single-summary) or "cascade" (tiered
snip→strip→collapse→summarize) (default "heuristic")
--config string
path to a daemon config YAML file (v1 schema: grpc_addr, http_addr,
metrics_addr, tls_cert, tls_key, client_ca, rate_limit, rate_burst). Explicit
CLI flags override file values; auth TOKEN is not accepted in YAML
--context-window-override int
override the model context window in tokens for compaction and the client
context meter. Default 0 uses the configured, reported, cataloged, or 128k
value.
--cors-origins value
allow this exact browser origin, scheme://host[:port], to call the HTTP API.
Repeatable. Wildcards, suffixes, subdomains, and "null" are refused because
requests use credentials. Default empty disables CORS.
--default-model string
default model identifier for the default provider. Client defaults override it.
Startup fails if the model is unavailable for that provider.
--default-placement string
override execution.default_placement for this mecated serve: host-local or
microvm-local (omitted: operator settings, then host-local)
--default-provider string
default provider identifier for sessions without a client selector. Client
selectors override it. Startup fails if the provider is unavailable.
--deployment-id string
optional opaque deployment label returned by GetCompatibilityInfo. Mecatl never
derives it from host or environment values. Printable single-line text only, up
to 128 bytes.
--driver-auth-token string
bearer token sent on every store-driver RPC (or MECATL_DRIVER_AUTH_TOKEN; empty
disables driver auth). Refused over cleartext to a non-loopback driver — pair
with --driver-tls
--driver-tls
enable transport TLS on the store-driver connections (--session-store-url/--
memory-store-url)
--driver-tls-ca string
PEM CA bundle to verify the store driver's server certificate (with --driver-
tls; empty uses the system roots)
--driver-tls-cert string
PEM client certificate for mutual TLS to the store driver (with --driver-tls
and --driver-tls-key)
--driver-tls-key string
PEM client private key (paired with --driver-tls-cert)
--enable-commands
enable slash-command expansion using the default directories (.mecatl/commands,
.claude/commands) when --commands-dir is empty
--enable-parallel
register the Parallel fan-out tool (parallel isolated child branches) (default
true)
--enable-teams
enable the agent team capability. Enabled by default. (default true)
--event-log-url string
host and port of a remote gRPC event log for the durable per-session timeline.
It is independent of the session store. Empty uses the configured local log or
an in-memory log. Uses the same driver authentication and TLS settings as --
session-store-url.
--flight-recorder
retain recent execution traces in a bounded memory buffer for
/debug/flightrecorder. Enabled by default. (default true)
--fork-preserved-cap int
maximum preserved winner forks kept on disk. Older forks are deleted and no
longer inspectable. (default 8)
--goroutine-warn-interval duration
how often the goroutine-leak watchdog samples runtime.NumGoroutine(). Only
consulted when --goroutine-warn-threshold > 0 (default 30s)
--goroutine-warn-threshold int
log a warning when the goroutine count exceeds this value. Default 0 disables
the warning; /metrics still reports the count.
--grpc-addr string
gRPC listen address (defaults to loopback; set --auth-token and/or --tls-cert
before binding non-loopback) (default "127.0.0.1:8080")
--grpc-unix-socket string
absolute path of a UNIX-domain socket for gRPC instead of a TCP port. It is
mutually exclusive with an explicitly configured --grpc-addr. Mecatl creates an
owner-only socket and parent directory, removes stale sockets, and refuses a
socket used by a running process.
--guardrails string
set to "off" to disable configured guardrails. Any other value prevents startup.
--guardrails-model string
model identifier or --model-alias for checking tool-call arguments and results
against operator guardrail rules. Setting a model enables guardrails unless --
guardrails=off. A project cannot configure or weaken this checker.
--headless
run without interactive permission approval. Child subagent, team-member, and
branch permission requests are denied unless --subagent-ask-reviewer allows
them. Configured deny and ask rules still take precedence. Disabled by default.
--help-all
show the exhaustive flag reference (every registered flag) and exit
--http-addr string
HTTP/SSE listen address. Defaults to loopback; configure --auth-token or --tls-
cert before binding a non-loopback address. An empty value disables the
HTTP/SSE and metrics listeners. (default "127.0.0.1:8081")
--import-claude-permissions
also load supported Claude Code permission settings when --permissions-
conventional is enabled. Unsupported or invalid rules are ignored with a log
entry.
--learning-admission-interval int
process-wide automatic-learning debounce: admit every Nth eligible reflection
(0 or 1 admits every eligible reflection) (default 1)
--learning-store-url string
host and port of a remote gRPC learning store. The server must provide attempt,
proposal, and skill repositories. Uses the same driver authentication and TLS
settings as --session-store-url.
--lifetime-pipe-fd int
file descriptor for an inherited pipe read end or connected UNIX-domain socket.
EOF means the parent exited, then Mecatl shuts down gracefully. Default 0
disables this; file descriptors 1 and 2 are rejected.
--lifetime-stdin
use piped standard input as the parent-liveness channel. EOF shuts down the
daemon gracefully. Intended for supervisors that cannot assign a child file
descriptor. Mutually exclusive with --lifetime-pipe-fd.
--llm-breaker-cooldown duration
how long the LLM circuit breaker stays open before half-opening (default 30s)
--llm-breaker-threshold int
consecutive LLM failures that open the circuit breaker (0 disables) (default 5)
--llm-max-attempts int
maximum attempts for one precommit model step (initial request included)
(default 60)
--llm-per-attempt-timeout duration
timeout for connecting to an LLM stream and receiving its first chunk. It does
not interrupt an active stream. Set 0 to disable. (default 5m0s)
--llm-recovery-budget duration
maximum time spent recovering a model step before semantic output (default
30m0s)
--llm-stream-idle-timeout duration
max idle gap between LLM stream chunks after the first chunk; the watchdog
bounds each gap, so precommit timeouts may recover while visible stalls are
terminal (0 disables) (default 3m0s)
--log-level string
minimum log level: debug, info (default), warn, or error (default "info")
--main-retention duration
retain persisted main sessions for this duration before deleting them. Child
sessions use --child-retention. Requires a durable store; default 0 disables
cleanup.
--main-retention-max-total int
maximum persisted main sessions in the store. Older sessions are deleted,
excluding active runs. Requires a durable store; default 0 disables the limit.
--max-run-tokens int
maximum cumulative input and output tokens per run. Child agents inherit the
limit. Default 0 allows unlimited tokens.
--max-team-tokens int
maximum cumulative input and output tokens across a team run; checked between
rounds. A per-call team limit can only lower it. Default 0 allows unlimited
tokens.
--mcp-prompts
expand /mcp__<server>__<prompt> inputs using connected-server prompts. Prompt
content steers the model, so use only trusted servers. (default true)
--mcp-resource-tools
register MCP resource tools when a connected server exposes resources. Resource
contents enter the model context, so use only trusted servers. (default true)
--mcp-server value
remote MCP server as name=URL (repeatable); auth token read from
MCP_<NAME>_TOKEN. The name must match [A-Za-z0-9_]+ and be case-insensitively
unique across entries (it derives the token env var); a token-bearing URL must
use HTTPS, or HTTP to a loopback host. --mcp-server-insecure-http is the
explicit per-server opt-out.
--mcp-server-insecure-http value
name of an MCP server entry allowed to send its MCP_<NAME>_TOKEN bearer token
over plain HTTP to a non-loopback host. The token travels in cleartext on the
network path. The flag can appear before or after the matching server entry.
The name must identify an HTTP non-loopback server entry.
--memory-consolidate-interval duration
interval for background memory consolidation (dream); 0 disables. Only
meaningful with --memory-dir
--memory-dir string
per-project memory store directory (empty disables the Remember/Recall tools)
--memory-store-url string
host and port of a remote gRPC memory store. Replaces --memory-dir and enables
the Remember and Recall tools. Uses the same driver authentication and TLS
settings as --session-store-url.
--metrics-addr string
Prometheus /metrics listen address (empty disables the metrics endpoint)
(default "127.0.0.1:9090")
--microvm-guest-allow value
allow one microvm-local guest destination as HOST:PORT/tcp|udp (repeatable;
requires --microvm-guest-egress=allowlist; hostnames only, no IP literals or
wildcards)
--microvm-guest-egress value
override execution.microvm.guest_egress.mode: permissive, deny-all, or
allowlist; omitted: operator settings, then permissive
--mock
use a canned offline mock provider. It does not make network requests.
--mock-script string
path to a JSON mockllm script (offline; implies --mock and supports text, tool-
call, and delayed turns)
--model string
model identifier sent to the provider (empty: use the provider-appropriate
default)
--model-alias model
model alias mapping as name=model-id. Repeatable; for example, --model-alias
fast=gpt-4o-mini. Agent definitions can use these aliases in their model field.
--model-alias-provider value
provider for a same-tier --model-alias as name=provider-id. Repeatable; an
entry without a matching --model-alias is invalid.
--model-slot compaction
model binding as slot=selector. Repeatable; for example, --model-slot
compaction=cheap. Slots compaction, `ask-reviewer`, and `guardrail` select
models for those operations. The selector is a --model-alias or model
identifier. An invalid selector uses the session model. `ask-reviewer` and
`guardrail` slots do not enable those features.
--mutex-profile-fraction int
runtime.SetMutexProfileFraction: report 1/N mutex contention events for
/debug/pprof/mutex. 0 (default) disables it. Adds per-contention sampling
overhead; enable only when investigating lock contention
--no-prompt-cache
disable provider-side prompt caching. Caching is enabled by default.
--no-scheduler
disable scheduling for a schedule-capable durable store. Create, list, and
manual fire operations remain available.
--no-shell
disable the Shell tool entirely (shell-less mode); overrides --shell
--no-soul
disable the user persona. Otherwise Mecatl reads it from the conventional
location and ignores an unavailable file.
--no-steer
disable client steering while a run is in progress. Steering is enabled by
default.
--no-user-model
disable the user-model entirely (explicit tools and live operator profile)
--oidc-allow-private-https-issuer
allow an HTTPS issuer or JWKS URL to resolve to a private, loopback, or link-
local address. Requires --oidc-ca-cert-file; TLS, CA, hostname, redirect, and
DNS-pinned-dial checks remain enabled.
--oidc-audience aud
accepted OIDC audience (aud). Required with --oidc-issuer to reject tokens for
other services.
--oidc-ca-cert-file string
PEM CA bundle for --oidc-allow-private-https-issuer; required when private
HTTPS issuer admission is enabled
--oidc-client-id value
public mecatui OAuth client-registration identifier
--oidc-insecure-allow-private-issuer
deprecated insecure compatibility option. Allows HTTP issuer and JWKS URLs and
private, loopback, and link-local addresses. This disables cloud-metadata SSRF
protection. Use --oidc-allow-private-https-issuer with --oidc-ca-cert-file for
private HTTPS issuers.
--oidc-issuer string
OIDC issuer URL whose tokens identify callers. Each request must present a
valid bearer token, and the verified issuer and subject become the session
owner. Requires --oidc-audience. Empty disables caller identity.
--oidc-jwks-uri string
static JWKS endpoint for --oidc-issuer. Empty uses the issuer discovery
document.
--oidc-max-jwks-staleness duration
maximum age of cached JWKS signing keys when refresh cannot reach the IdP;
stale, unrefreshable keys yield 503 instead of validating tokens. 0 disables
the upper bound; negative values are rejected (default 1h0m0s)
--oidc-resource value
canonical external HTTPS URL of the OAuth protected resource
--oidc-scopes value
optional comma-separated OAuth scopes to advertise in protected-resource
metadata
--openai
use the OpenAI Responses provider (key from OPENAI_API_KEY)
--openai-base-url string
override the OpenAI API base URL (compatible endpoints)
--opencode-base-url string
override the OpenCode Go API base URL (default https://opencode.ai/zen/go/v1;
key from OPENCODE_API_KEY)
--openrouter-base-url string
override the OpenRouter API base URL (default https://openrouter.ai/api/v1; key
from OPENROUTER_API_KEY)
--otlp-endpoint string
OTLP trace collector endpoint, e.g. localhost:4317 (empty disables tracing)
--otlp-insecure
skip TLS when dialing the OTLP collector (development only)
--otlp-protocol string
OTLP transport: "grpc" (default) or "http" (default "grpc")
--perf-mcp
serve read-only runtime and profile data over MCP at /mcp on the loopback
metrics listener. Disabled by default. Requires a loopback --metrics-addr
because the endpoint does not require authentication.
--permission-config value
path to a repeatable YAML permission configuration. CLI rules have highest
precedence; configured deny and ask rules always override allows.
--permission-mode string
permission mode, one of: plan, default, accept-edits, auto, yolo. Sets two
things: the process-wide posture, fixed at startup (strict for plan, default,
and accept-edits; auto; yolo), and the session mode new sessions start in,
which each session may change. Default: default. auto and yolo allow tools
without asking, so they need a guardrails checker (--guardrails-model) or an
explicit --guardrails off, and are refused for root unless MECATL_SANDBOX=1 or
IS_SANDBOX=1. Deny rules and configured ask rules still apply. Replaces the
deprecated --posture and --yolo; --trust-project still combines with it.
--permissions-conventional
load project and user permission settings for each session. Enabled by default.
Project allow rules require --trust-project; project deny and ask rules always
apply. (default true)
--plan-mode-auto-approve
approve plan-mode results automatically in headless mode. Interactive sessions
and non-plan requests are unaffected. Disabled by default.
--posture string
DEPRECATED: use --permission-mode. Permission posture: strict prompts
mutations; trusted applies project allow rules; auto allows tools and relaxes
main shell substitutions; yolo also runs child command substitutions. Deny
rules and configured ask rules still apply. strict is the default. --trust-
project and --yolo select trusted and yolo. auto and yolo are refused for root
outside MECATL_SANDBOX.
--product-metrics
send anonymous product-adoption metrics to Stacklok: version, OS and
architecture, enabled features, and coarse session, run, and tool-call counts.
Prompts, file paths, tool names, and model identifiers are excluded. Enabled by
default; disable with --product-metrics=false, MECATL_PRODUCT_METRICS=false,
DO_NOT_TRACK=1, or telemetry.productMetrics.enabled: false. (default true)
--product-metrics-dry-run
print product-metrics observations to standard error instead of sending them.
--rate-burst int
rate-limit token-bucket burst size (0 derives a sane default from --rate-limit)
--rate-limit float
sustained per-client request rate in req/s (0 disables rate limiting)
--ready-file string
absolute path for a JSON readiness document written atomically after every
listener starts. It contains the process ID, transport, bound gRPC and HTTP
addresses, and compatibility metadata. Empty writes nothing.
--reasoning-effort string
default reasoning effort: auto, low, medium, high, xhigh, or max. Empty lets
provider or operator settings select the value. Per-session selection overrides
it. Unsupported or unknown values are ignored with a warning.
--schedule-fire-retention duration
retain persisted scheduled-run sessions for this duration before deleting them.
Active runs are not deleted. Requires a durable store; unset uses 7d when
scheduling is available, while explicit 0 disables cleanup.
--schedule-fire-retention-max-total int
maximum persisted scheduled-run sessions in the store. Older sessions are
deleted, excluding active runs. Requires a durable store; default 0 disables
the limit.
--schedule-store-url string
host and port of a remote schedule-store driver. It replaces the schedule store
from the configured session store. Empty uses the configured store's schedule
capability, if any. Uses the same driver authentication and TLS settings as --
session-store-url.
--scheduler-max-concurrent-fires int
maximum admitted scheduled fires, including manual fires and teardown. (default
4)
--scheduler-min-interval duration
minimum allowed scheduled cadence. Default 1m. Set 0 to allow any cadence.
(default 1m0s)
--scheduler-tick-interval duration
interval for polling due schedules. Default 30s; 0 also uses 30s. Applies only
when scheduling is enabled. (default 30s)
--session-lease-dir string
directory for local flock-based session leases between processes on one host.
flock releases leases after a crash. Use --session-lease-k8s-namespace or --
session-lease-url across hosts. Empty disables leasing.
--session-lease-k8s-namespace string
Kubernetes namespace for coordination.k8s.io Lease-backed session leasing (the
in-cluster multi-replica path). Uses in-cluster config (or the default
kubeconfig out-of-cluster); the ServiceAccount needs get,create,update,delete
on leases in coordination.k8s.io for this namespace (never list/watch — see
https://mecatl.dev/docs/operating/mecated). Empty = no leasing
--session-lease-renew-interval duration
how often the per-session renewer refreshes a held lease; 0 = --session-lease-
ttl / 3. Keep it well below the TTL so a slow store does not lose the lease and
cancel the run. Only meaningful when a lease backend is selected
--session-lease-ttl duration
session-lease lifetime: a crashed/killed holder's lease becomes claimable after
this long. Only meaningful when a lease backend is selected (default 30s)
--session-lease-url string
host and port of a remote session-lease driver for cross-process single-writer
enforcement. Empty disables leasing. Mutually exclusive with --session-lease-
dir and --session-lease-k8s-namespace.
--session-store-url string
host and port of a remote gRPC session store. Replaces --store-dir. For a non-
loopback server, configure --driver-tls and, when required, --driver-auth-
token.
--shell string
shell used to execute Shell-tool commands; empty disables Shell (shell-less
mode) (default "/bin/sh")
--skill-source-url string
host and port of a remote skill source. It replaces --skills-dir and
conventional discovery. Skill instructions steer the model, so use only a
trusted source. Startup fails if the source is unavailable.
--skills-conventional
discover skills from conventional project and user directories. Disabled by
default. Skill files can steer the model, so use only trusted locations.
--skills-dir value
directory of skills arranged as <name>/SKILL.md. Repeatable; these directories
have highest precedence. An SKILL.md can steer the model, so use only trusted
directories.
--skills-draft-dir mecated skills promote
enable SkillDraft and set the directory for candidate skills. The directory
must be outside the workspace and must not overlap a --skills-dir. Candidates
remain quarantined until promoted with mecated skills promote.
--skills-draft-similarity-threshold float
2-gram Jaccard similarity above which a SkillDraft warns of a near-duplicate
existing skill (warn-only, does not block) (default 0.5)
--soul-file string
path to a read-only user persona file for initial agent context. Default is the
conventional XDG location. Missing, empty, oversized, or unsafe files are
ignored.
--soul-source-url string
host and port of a remote gRPC source for the user persona. Replaces --soul-
file; --no-soul still disables the persona. Startup fails if the source is
unavailable. Uses the same driver authentication and TLS settings as --session-
store-url.
--soul-strict
omit a soul whose content hash differs from its recorded baseline. Use --
approve-soul to record a new baseline.
--store-dir string
directory for the JSONL session store (empty -> in-memory store)
--subagent-ask-reviewer string
model identifier or --model-alias for reviewing child permission requests in
headless mode. An allow applies only to that request; denied or failed reviews
deny it. Empty leaves reviews off, except that a headless auto or yolo
permission mode turns them on by default (ask-reviewer model slot, else the
session model); off disables reviews explicitly.
--subagent-ask-reviewer-max-denies int
maximum consecutive denied, failed, or timed-out child-permission reviews
before later requests are automatically denied. An allowed review resets the
count. Values at or below 0 use the default of 3. (default 3)
--subagent-ask-reviewer-policy string
path to a trusted policy file that replaces the built-in child-permission
review rubric. Startup fails if the file is unreadable.
--subagent-model string
default model for child subagents, parallel branches, and team members. Accepts
a model identifier or --model-alias. Empty inherits --model; an unresolved
value prevents startup.
--subagent-model-router
set explicitly to false to disable the configured subagent model router. The
router selects a model for eligible plain subagent delegations; failures use
the default model.
--tls-cert string
PEM server certificate; with --tls-key enables TLS on the gRPC + HTTP servers
--tls-key string
PEM server private key (paired with --tls-cert)
--tokenizer string
token counter for the compaction trigger: "heuristic" (default, dependency-
free) or "tiktoken" (offline tiktoken vocab) (default "heuristic")
--toolhive
discover MCP servers from running ToolHive workloads. Mecatl does not start
workloads. Discovered tools enter the model context, so use only trusted
workloads. (default true)
--toolhive-group string
ToolHive group to discover workloads from (empty -> the "default" group). Only
consulted when --toolhive is set
--toolhive-llm
auto-detect a locally-running ToolHive LLM proxy by reading ToolHive's config
and probing 127.0.0.1, and register it as a model provider (id "toolhive", no
API key needed); unrelated to --toolhive (MCP workload discovery). Set =false
on shared hosts (default true)
--toolhive-llm-base-url string
explicit ToolHive LLM proxy base URL (must resolve to loopback); skips the
config-file auto-detect but keeps the startup probe
--toolhive-llm-mode string
ToolHive LLM routing mode: "auto" (default; direct when the OIDC trio is
configured, else the loopback proxy), "proxy" (force the loopback reverse
proxy), or "direct" (talk to the real gateway_url with an in-process OIDC
token; fails when OIDC is not configured). The explicit --toolhive-llm-base-url
override is always proxy mode (default "auto")
--trust-project
apply allow rules from a discovered project permission configuration. Project
deny and ask rules always apply. Disabled by default because project allow
rules can approve tool calls.
--user-model-consolidate-interval duration
independent process-wide interval for background consolidation (dream) of the
cross-project user-model store's user/ namespace; 0 disables. Requires the
user-model store and provider; learning.mode (including a project off ceiling)
does not gate this explicit maintenance schedule
--user-model-dir string
directory for user-scoped facts shared across projects. Default is the
conventional XDG location. It supplies user-memory tools and a bounded operator
profile; agent behavior comes from the soul and system rules.
--websearch string
set to "off" to disable web search and outbound search requests. Web search is
enabled by default.
--websearch-auth-header string
HTTP header for WEBSEARCH_API_KEY. Default "Authorization" sends a Bearer
token; for example, "X-API-Key" sends the key directly.
--websearch-query-param string
query parameter name for the search string. Default "q".
--websearch-url string
base URL of an HTTP JSON search endpoint. Overrides configured environment-
based search providers. The API key is read from WEBSEARCH_API_KEY.
--workspace string
default session workspace root (default
"<WORKSPACE>")
--yolo
DEPRECATED: use --permission-mode yolo. Alias for --posture=yolo. Allows tools
server-wide and lets child command substitutions run automatically. Deny rules
and configured ask rules still apply. Intended only for isolated, ephemeral,
single-tenant environments. Refused for root unless MECATL_SANDBOX=1 or
IS_SANDBOX=1.
mecak8s
Usage: mecak8s [flags]
--acknowledge-main-retention
Acknowledge automatic deletion of main sessions when main retention is
configured
--agents-conventional
Also search conventional agent-definition directories (default true)
--agents-dir value
Directory to search for agent definitions. Repeatable and highest precedence;
agent instructions affect model behavior, so use only trusted directories
--anthropic-base-url string
override the native Anthropic API base URL (compatible/proxy endpoints; key
from ANTHROPIC_API_KEY)
--anthropic-cache-ttl string
Anthropic prompt-cache TTL: 5m or 1h. Empty uses 1h on Anthropic, OpenRouter's
Anthropic endpoint and the ToolHive gateway, the API default elsewhere; other
values are ignored
--api-key-file string
provider credentials YAML path (API-key providers only; Codex OAuth is
unsupported)
--auth-token string
Bearer token for RPC/API requests. Empty disables static bearer authentication;
OIDC or mTLS may still apply. Reads MECATL_AUTH_TOKEN when unset
--child-gc-interval duration
Interval for session-retention cleanup after the startup sweep. Zero runs only
the startup sweep (default 1h0m0s)
--child-retention duration
Retention period for persisted child-session snapshots. Older snapshots are
deleted; zero disables age-based cleanup (default 168h0m0s)
--child-retention-max-per-family int
Maximum persisted child-session snapshots per delegation family. Older
snapshots are deleted; zero disables the limit (default 500)
--client-ca string
PEM client CA bundle. Requires and verifies client certificates
--close-timeout value
Maximum time for final application cleanup (default 5s)
--default-model string
Deployment-wide default model ID for the default provider. Invalid values
prevent startup
--default-provider string
Deployment-wide default provider ID, such as openai, openrouter, or anthropic.
Invalid values prevent startup
--drain-addr string
Unauthenticated HTTP address for GET /drain, typically used by a kubelet
preStop hook (default "0.0.0.0:8082")
--drain-timeout value
Maximum time to cancel, join, and persist runs during shutdown (default 15s)
--driver-auth-token string
Bearer token for store-driver RPCs. Reads MECATL_DRIVER_AUTH_TOKEN when empty;
cleartext remote connections are refused
--driver-tls
Use TLS for store-driver connections
--driver-tls-ca string
PEM CA bundle for the store-driver server certificate. Requires --driver-tls;
empty uses system roots
--driver-tls-cert string
PEM client certificate for store-driver mutual TLS. Pair with the matching
private-key flag and enable TLS
--driver-tls-key string
PEM client private key for --driver-tls-cert
--enable-parallel
Enable the Parallel tool for isolated child branches
--enable-teams
Enable the experimental agent-team capability
--execution-allowed-subjects string
Comma-separated OIDC subject allowlist for execution template inventory and
binding; empty denies all
--execution-enabled
Use an independently deployed Kubernetes execution provider for default sessions
--execution-endpoint string
Host:port endpoint of the mTLS gRPC execution provider. Requires --execution-
enabled
--execution-template-id string
Operator-configured default execution template ID
--execution-template-revision string
Exact versioned default execution template revision
--execution-tls-ca string
Mounted CA bundle used only by the execution client
--execution-tls-cert string
Mounted execution-provider mTLS client certificate
--execution-tls-key string
Mounted execution-provider mTLS client private key
--grpc-addr string
gRPC listen address. Pods bind 0.0.0.0; configure caller authentication outside
a service mesh (default "0.0.0.0:8080")
--grpc-stop-timeout value
Maximum time for graceful gRPC shutdown before a hard stop (default 10s)
--guardrails string
Set to off to disable guardrails regardless of other configuration
--guardrails-model string
Model ID or alias for checking outbound arguments and inbound results. A
configured model or guardrail model slot enables checks
--headless
Run without an interactive permission approver. Child permission requests are
denied unless --subagent-ask-reviewer handles them (default true)
--http-addr string
HTTP/SSE listen address. Health and readiness endpoints do not require
authentication (default "0.0.0.0:8081")
--http-shutdown-timeout value
Maximum time for graceful HTTP and metrics shutdown (default 5s)
--import-claude-permissions
Import compatible Claude Code permission settings
--learning-store-url string
Host:port of a distributed learning gRPC driver. It must provide attempt,
proposal, and skill repositories or startup fails
--llm-breaker-cooldown duration
How long the LLM circuit breaker remains open before retrying (default 30s)
--llm-breaker-threshold int
Consecutive LLM failures that open the circuit breaker. Zero disables it
(default 5)
--llm-max-attempts int
maximum attempts for one precommit model step (initial request included)
(default 60)
--llm-per-attempt-timeout duration
Timeout for connecting to an LLM stream and receiving its first chunk. Does not
stop an active stream; zero disables the timeout (default 5m0s)
--llm-recovery-budget duration
Maximum time spent recovering a model step before semantic output (default
30m0s)
--llm-stream-idle-timeout duration
Maximum idle gap between LLM stream chunks. The watchdog bounds each chunk gap;
before semantic output a timed-out attempt may recover, while visible stalls
are terminal. Zero disables the timeout (default 3m0s)
--log-level string
minimum log level: debug, info (default), warn, or error (default "info")
--main-retention duration
Retention period for persisted main-session snapshots. Older snapshots are
deleted; requires --acknowledge-main-retention. Zero disables age-based cleanup
--main-retention-max-total int
Maximum persisted main-session snapshots. Older snapshots are deleted; requires
--acknowledge-main-retention. Zero disables the limit
--max-run-tokens int
Maximum cumulative input and output tokens per agent run. Runs exceeding it end
with stop=budget; zero is unlimited
--max-team-tokens int
Maximum cumulative input and output tokens per team run. Zero is unlimited
--mcp-server value
remote MCP server as name=URL (repeatable); auth token read from
MCP_<NAME>_TOKEN. The name must match [A-Za-z0-9_]+ and be case-insensitively
unique across entries (it derives the token env var); a token-bearing URL must
use HTTPS, or HTTP to a loopback host. --mcp-server-insecure-http is the
explicit per-server opt-out.
--mcp-server-insecure-http value
name of an MCP server entry allowed to send its MCP_<NAME>_TOKEN bearer token
over plain HTTP to a non-loopback host. The token travels in cleartext on the
network path. The flag can appear before or after the matching server entry.
The name must identify an HTTP non-loopback server entry.
--metrics-addr string
Loopback listen address for Prometheus metrics. Empty disables metrics; non-
loopback addresses are rejected because output can contain sensitive data
--mock
Use an offline mock provider without network access or an API key
--mock-script string
Path to an offline JSON mock script. Implies --mock
--model string
Model identifier sent to the provider. Empty uses the provider default
--model-alias model
model alias mapping as name=model-id. Repeatable; for example, --model-alias
fast=gpt-4o-mini. Agent definitions can use these aliases in their model field.
--model-alias-provider value
provider for a same-tier --model-alias as name=provider-id. Repeatable; an
entry without a matching --model-alias is invalid.
--model-slot compaction
model binding as slot=selector. Repeatable; for example, --model-slot
compaction=cheap. Slots compaction, `ask-reviewer`, and `guardrail` select
models for those operations. The selector is a --model-alias or model
identifier. An invalid selector uses the session model. `ask-reviewer` and
`guardrail` slots do not enable those features.
--no-prompt-cache
Disable provider-side prompt caching
--no-scheduler
Disable scheduled-task execution. Schedule management APIs remain available;
one replica runs the scheduler when leasing is enabled
--no-shell
Disable the Shell tool. Overrides --shell
--no-soul
Disable the persona fragment
--no-user-model
Disable the user model
--oidc-allow-private-https-issuer
allow an HTTPS issuer or JWKS URL to resolve to a private, loopback, or link-
local address. Requires --oidc-ca-cert-file; TLS, CA, hostname, redirect, and
DNS-pinned-dial checks remain enabled.
--oidc-audience aud
accepted OIDC audience (aud). Required with --oidc-issuer to reject tokens for
other services.
--oidc-ca-cert-file string
PEM CA bundle for --oidc-allow-private-https-issuer; required when private
HTTPS issuer admission is enabled
--oidc-client-id value
public mecatui OAuth client-registration identifier
--oidc-insecure-allow-private-issuer
deprecated insecure compatibility option. Allows HTTP issuer and JWKS URLs and
private, loopback, and link-local addresses. This disables cloud-metadata SSRF
protection. Use --oidc-allow-private-https-issuer with --oidc-ca-cert-file for
private HTTPS issuers.
--oidc-issuer string
OIDC issuer URL whose tokens identify callers. Each request must present a
valid bearer token, and the verified issuer and subject become the session
owner. Requires --oidc-audience. Empty disables caller identity.
--oidc-jwks-uri string
static JWKS endpoint for --oidc-issuer. Empty uses the issuer discovery
document.
--oidc-max-jwks-staleness duration
maximum age of cached JWKS signing keys when refresh cannot reach the IdP;
stale, unrefreshable keys yield 503 instead of validating tokens. 0 disables
the upper bound; negative values are rejected (default 1h0m0s)
--oidc-resource value
canonical external HTTPS URL of the OAuth protected resource
--oidc-scopes value
optional comma-separated OAuth scopes to advertise in protected-resource
metadata
--openai
Use the OpenAI Responses provider. Reads OPENAI_API_KEY or --openai-bearer-
token-file
--openai-base-url string
override the OpenAI API base URL (compatible endpoints)
--openai-bearer-token-file string
Path to a rotating OpenAI bearer token. Requires --openai-base-url and excludes
OPENAI_API_KEY
--opencode-base-url string
override the OpenCode Go API base URL (default https://opencode.ai/zen/go/v1;
key from OPENCODE_API_KEY)
--openrouter-base-url string
override the OpenRouter API base URL (default https://openrouter.ai/api/v1; key
from OPENROUTER_API_KEY)
--otlp-endpoint string
OTLP trace collector endpoint. Empty disables trace export
--otlp-insecure
Skip TLS for the OTLP collector. For development only
--otlp-metrics-endpoint string
OTLP metrics collector endpoint. Empty disables metrics export
--otlp-metrics-protocol string
OTLP transport for metrics: grpc or http (default "grpc")
--otlp-protocol string
OTLP transport for traces: grpc or http (default "grpc")
--otlp-shutdown-timeout duration
Maximum time to flush telemetry on shutdown. Zero disables the limit (default
5s)
--permission-config value
Trusted permission YAML file. Repeatable
--permission-mode string
Permission mode, one of: plan, default, accept-edits, auto, yolo. Sets two
things: the process-wide posture, fixed at startup (strict for plan, default,
and accept-edits; auto; yolo), and the session mode new sessions start in,
which each session may change. Default: auto (posture auto, auto session mode).
auto and yolo allow tools without asking, so they need a guardrails checker (--
guardrails-model or the guardrail model slot) or an explicit --guardrails off,
and require MECATL_SANDBOX when running as root. Deny rules and configured ask
rules still apply. Replaces the deprecated --posture; --trust-project still
combines with it
--permissions-conventional
Discover project and user permission settings for each session (default true)
--posture string
DEPRECATED: use --permission-mode. Permission posture: strict prompts for
mutations; trusted honors project allow rules; auto allows tools by default and
relaxes main shell substitutions while child injection defenses remain enabled;
yolo also runs child command substitutions automatically. Deny rules and
configured ask rules still apply. auto and yolo require MECATL_SANDBOX when
running as root (default "auto")
--product-metrics
Report anonymous product-adoption metrics to Stacklok. Reports version,
OS/architecture, enabled features, and aggregate counts, never prompts, file
paths, tool names, or model IDs; disable with --product-metrics=false,
MECATL_PRODUCT_METRICS=false, DO_NOT_TRACK=1, or
telemetry.productMetrics.enabled=false (default true)
--product-metrics-dry-run
Print product-metrics observations to stderr instead of sending them
--reasoning-effort string
Default reasoning effort: auto, low, medium, high, xhigh, or max. Empty or auto
uses configured or provider defaults; unsupported or invalid values fall back
to a supported default
--redis-allow-plaintext
Allow unauthenticated plaintext Redis for a disposable local or Kind fixture.
Production Redis requires CA-verified TLS
--redis-filesystem
Use a principal-scoped, persistent, shell-less Redis workspace. Excludes --
workspace
--redis-follow-pool-size int
Maximum Redis connections reserved for blocking event followers (default 32)
--redis-max-followers int
Maximum event followers admitted by this process (default 32)
--redis-password-file string
Path to an optional Redis password in a mounted Secret. Requires verified TLS;
do not pass the password as an argument
--redis-read-ledger
Store each session's read-before-write ledger in Redis
--redis-tls
Verify Redis TLS with the system trust store. Use --redis-tls-ca for a private
CA
--redis-tls-ca string
Path to a PEM CA bundle in a mounted Secret for Redis TLS verification.
Replaces the system trust store; required with ACL credentials unless --redis-
tls is set
--redis-url string
Redis host:port for the session store and durable event log
--redis-username-file string
Path to an optional Redis ACL username in a mounted Secret. Requires a password
and verified TLS
--schedule-fire-retention duration
Delete scheduled-run snapshots older than this age; running and awaiting are
protected. Zero disables age cleanup; default is 168h.
--schedule-fire-retention-max-total int
Keep at most this many scheduled-run snapshots; delete the oldest non-active
snapshots above the limit. Zero disables count cleanup
--scheduler-max-concurrent-fires int
Maximum admitted scheduled fires, including manual fires and teardown (default
4)
--scheduler-min-interval duration
Minimum accepted schedule interval. Shorter intervals are rejected; zero
disables the limit (default 1m0s)
--scheduler-tick-interval duration
Interval for polling due schedules. Zero uses the default interval; inactive
when scheduling is unavailable or disabled (default 30s)
--session-lease-k8s-namespace string
Kubernetes namespace for session leases. The ServiceAccount needs get, create,
update, and delete permissions on coordination.k8s.io leases; empty disables
leasing (default "mecatl")
--session-lease-renew-interval duration
Interval for renewing held session leases. Zero uses one third of --session-
lease-ttl
--session-lease-ttl duration
Session lease lifetime. Another replica can claim a lease after this period
when its holder stops (default 30s)
--shell string
Shell for Shell tool commands. An empty value disables the tool (default
"/bin/sh")
--skills-conventional
Also search conventional skill directories, after --skills-dir
--skills-dir value
Directory to search for skills. Repeatable and highest precedence; skill
instructions affect model behavior, so use only trusted directories
--soul-file string
Path to a user persona file. Empty uses the conventional location
--subagent-ask-reviewer string
Model ID or alias for reviewing child permission requests in headless mode.
Empty leaves the reviewer off, except that the auto and yolo permission modes
turn it on by default (ask-reviewer model slot, else the session model); off
disables it explicitly
--subagent-ask-reviewer-max-denies int
Consecutive non-allow outcomes that disable the reviewer for the run. Values
less than or equal to zero use the default (default 3)
--subagent-ask-reviewer-policy string
Path to a trusted policy rubric for --subagent-ask-reviewer. Replaces the
built-in rubric; an unreadable file prevents startup
--subagent-model string
Default model for child agents without their own model. Empty inherits --model
--subagent-model-router
Disable operator-configured subagent model routing; this flag cannot enable
routing
--telemetry-installation-id string
Stable UUID for the optional mecatl.installation.id OpenTelemetry resource
attribute. Empty omits it
--tls-cert string
PEM server certificate. Enables TLS for gRPC and HTTP with --tls-key
--tls-key string
PEM server private key for --tls-cert
--toolhive-llm
auto-detect a locally-running ToolHive LLM proxy by reading ToolHive's config
and probing 127.0.0.1, and register it as a model provider (id "toolhive", no
API key needed); unrelated to --toolhive (MCP workload discovery). Set =false
on shared hosts (default true)
--toolhive-llm-base-url string
explicit ToolHive LLM proxy base URL (must resolve to loopback); skips the
config-file auto-detect but keeps the startup probe
--toolhive-llm-mode string
ToolHive LLM routing mode: "auto" (default; direct when the OIDC trio is
configured, else the loopback proxy), "proxy" (force the loopback reverse
proxy), or "direct" (talk to the real gateway_url with an in-process OIDC
token; fails when OIDC is not configured). The explicit --toolhive-llm-base-url
override is always proxy mode (default "auto")
--trust-project
Honor a discovered project's allow rules. Deny and ask rules are always
honored; raises the posture to at least trusted and combines with --permission-
mode
--user-model-dir string
Directory for the user model. Empty uses the conventional location
--workspace string
Shared agent workspace root, such as a mounted PVC. Empty gives every session a
shell-less, file-less workspace; clients cannot choose another root
Version: mecak8s --version prints the build version and exits.