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.
--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
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 schedules started in parallel per scheduler tick. Applies only when
scheduling is enabled. (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 disables reviews.
--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
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-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-profile string
Operator-configured execution provider profile
--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
--permissions-conventional
Discover project and user permission settings for each session (default true)
--posture string
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 schedules started concurrently in one scheduler tick (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 disables the reviewer
--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; equivalent to --posture=trusted
--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.