Skip to main content

​
Global runtime scope flags

The top-level CLI parser exposes these realm scope and config flags:
  • --realm <id>
  • --isolated
  • --instance <id>
  • --realm-backend <sqlite|jsonl|memory> (creation hint only)
  • --state-root <path>
  • --context-root <path>
  • --user-config-root <path>
  • --default-model <model>
The scope flags decide which realm config and state are used. --user-config-root overrides the user-level convention root. --default-model validates and persists the model in the scope-resolved config, then continues with the command or exits when no command was given. Storage maintenance verbs reject --isolated and --default-model because they dispatch before runtime-scope resolution. rkat mob host also rejects --isolated; a member host must use a stable workspace or explicit realm.

​
Default realm behavior

If you want CLI + RPC to share the same state, pass both the same explicit --realm and the same --state-root, resolving to the same physical store and provider. A matching server --context-root assists project-local candidate discovery; it does not select the CLI’s realm identity or guarantee the same root. Without --realm, RPC still creates an isolated realm. For CLI commands, the default invocation context is the current directory. The project-local state root is <project-root>/.rkat/realms, where the project root is the nearest ancestor containing a .rkat entry. If none exists, the context root is used. --context-root changes the ancestor-search starting point; --state-root bypasses discovery. Use --verbose on rkat run to print the active realm, context root, and physical realm root. See the realm guide for the full identity-vs-storage model.

​
Environment variables

For direct environment-backed provider auth, set at least one key pair below. Realm auth bindings and their configured credential stores can supply provider credentials instead, so these variables are not universally required. See providers for full key precedence (RKAT_* variants included).

​
Config files

The active realm document is the head of the runtime config chain. Under the default project-local state root it is <project-root>/.rkat/realms/<realm>/config.toml. Compatibility files still exist: These remain convention inputs for templates and compatibility workflows. CLI, RPC, REST, and MCP all resolve the same realm chain. Realm config supports explicit inheritance:
Resolution starts at the selected realm, follows each explicit parent, and appends the reserved global realm only when it is configured. Child values add to or override parent values. State never inherits: sessions, jobs, schedules, WorkGraph data, blobs, artifacts, and runtime rows remain owned by the selected realm. Credential reads inherit. HostAuthService and RPC/REST credential writes enforce strict ownership: a child-addressed inherited write is rejected with the owner identity. Current CLI logout exception: when the loaded config resolves child:<binding> to an inherited owner, rkat auth logout child:<binding> can clear that owner’s stored credential, including a shared credential account used by other routes. Explicitly address the true owner instead. A bare logout binding means global; --realm does not retarget it. This does not change the raw-head read/write split of config get / set / patch. Inherited MCP servers, hook entries, and skill sources have no removal tombstones, so an empty child collection does not delete inherited entries. Common tool gates:
default_timeout accepts humantime strings; per-tool timeout values use Serde’s duration representation with secs and nanos. tools.mcp_servers is also accepted in runtime config, although the CLI’s user/project MCP convention files are managed separately as described below. Streaming retries have a 300-second inactivity watchdog by default. Override it with a humantime value, or disable only this watchdog explicitly:

​
Custom model registry entries

Uncatalogued models served by a first-party API provider are declared once under [models.<id>], next to the per-provider default model strings. One definition feeds provider inference, compaction scaling, capability gates, and call timeouts:
provider parses into the closed provider vocabulary and fails closed on unknown names. Self-hosted models belong under [self_hosted.models] (below), not [models]. The same [models.<id>] table shape is accepted inside a mob definition (mob.toml) for mob-scoped models.

​
Self-hosted model config

Self-hosted models are defined directly in realm config:
vision = true covers image input. With api_style = "chat_completions", image_tool_results must remain false; that result shape is available only through a validated responses endpoint. transport is currently openai_compatible only. api_style chooses the upstream API shape:
  • chat_completions is the safest default for Ollama, LM Studio, and vLLM in current Meerkat docs and examples
  • responses should be treated as an advanced/server-specific path you validate explicitly before depending on it
For Gemma 4, prefer chat_completions unless you have verified a server-specific responses workflow you want to use. supports_thinking and supports_reasoning describe the behavior you intend Meerkat to expose through that configured transport. Gemma 4 models themselves are reasoning-capable, but some servers expose those capabilities with provider-specific conventions. Server entries carry connection facts only — the legacy bearer_token / bearer_token_env server fields are rejected at config parse. Credentials and the connection itself are owned by a realm binding for provider = "self_hosted" (auth_method of none, api_key, or static_bearer); a self-hosted server with no realm binding fails closed at run time. See Self-hosting models for the realm binding shape.

​
Model fallback config

Model fallback is disabled by default. Enable an explicit non-empty backup chain to permit migration at a recoverable, pre-output LLM boundary:
There is no catalog chain. enabled = true with no targets is invalid; enabled = false overrides an inherited enabled table. Unknown fallback keys (including the removed use_catalog_default_chain) reject. Fallback targets include the auth binding identity. Use auth_binding on an explicit target to retry the same model/provider through a different configured credential. Cross-provider targets are skipped unless policy explicitly allows them. Defaults migrate only on capacity/provider unavailability after three failures, not transport or empty output. See the policy and resume contract. Fallback admission preserves the requested output reserve and, by default, required tools. Smaller targets that cannot fit the actual context are skipped even when the primary failure was capacity rather than context overflow. The agent receives a hidden system notice when a switch commits. Fallback is only attempted before user-visible stream output has been emitted. Structured-output extraction retries keep their schema and provider-native web search remains disabled after a fallback switch.

​
Session storage layout

CLI realm storage resolves by realm identity across the configured candidate roots. By default, a fresh workspace realm is created under the nearest ancestor containing .rkat, falling back to the context root:
Pass --state-root <path> to use a different parent directory. An explicit state root wins. Otherwise, an existing unique realm copy is reused across project-local and user-global candidates. If the same realm is materialized under multiple candidates, normal opens fail closed as typed split-brain. Use rkat storage doctor to inspect it and the fenced rkat storage migrate --apply --adopt-root <path> path to choose the copy to keep. Important files:
  • realm_manifest.json (backend pinning)
  • config.toml (realm config)
  • config_state.json (config generation CAS state)
  • sessions.sqlite3 (when backend is sqlite)
  • sessions_jsonl/ (when backend is jsonl)
  • runtime.sqlite3 (JSONL runtime companion)
  • jobs.sqlite3 (durable detached jobs)
  • workgraph.sqlite3 (WorkGraph state)
  • <projection_root>/.rkat/events/ (optional derived event audit/replay log)
  • <projection_root>/.rkat/sessions/<session_id>/ (rebuildable materialized session views)
  • blobs/ (realm blob objects)
  • artifacts/ (stable artifact records)
  • <store_path>/approvals.json (RPC approval-record sidecar when the persistence bundle exposes a store path)
  • mobs/ (per-mob <mob_id>.db SQLite storage plus realm_profiles.db)
<store_path>/approvals.json is not an eighth RealmStorageProvider durability domain. The current storage doctor and storage migrate commands do not inventory or migrate this RPC-owned sidecar. For built-in SQLite and named memory realms, store_path is the realm root; for the JSONL backend, it is the sessions_jsonl/ directory. The optional event audit log and its .rkat/sessions/ materialized views belong to session/event projection, not additional RealmStorageProvider domains. Both are asynchronous derived state; the RuntimeStore/backend carrier remains authority. Per-session files may be regenerated when the audit log is healthy. --realm-backend is a creation hint. After first realm creation, backend selection is pinned by realm_manifest.json. This applies to both session storage and rkat mob command behavior in that realm. Manifest format 2 also records an optional external storage provider and explicit ephemeral_domains. Every storage provider must declare exactly one durability resolution for each of the seven domains: sessions, runtime, schedule, workgraph, jobs, blobs, and artifacts. A durable domain may not silently fall back to memory. When SQLite support is compiled in, new persistent realms default to sqlite.

​
MCP configuration

MCP servers are configured separately from realm runtime state: Project servers override user servers with the same name.

​
Exit codes

Codes 45-48 are used only by mob-family commands that carry the matching typed multi-host error. Code 2 alone does not establish budget exhaustion, and not every budget/deadline stop necessarily maps to 2. Inspect the diagnostic or an available typed error payload rather than classifying the failure solely by its numeric code; not every CLI error has structured JSON. In particular, session persistence/compaction disabled conditions are informational at the CLI transport layer and do not map to dedicated non-zero exit codes.

​
See also