Skip to main content

​
Global runtime scope flags

All CLI commands accept realm scope flags:
  • --realm <id>
  • --isolated
  • --instance <id>
  • --realm-backend <sqlite|jsonl|memory> (creation hint only)
  • --state-root <path>
  • --context-root <path>
These flags decide which realm config/session state is used.

​
Default realm behavior

Command surfaceDefault when --realm is omitted
rkat run, rkat run --resume, rkat session ...Workspace-derived stable realm (ws-...)
rkat mob ...Workspace-derived stable realm (ws-...)
rkat-rpcNew opaque realm (realm-...)
If you want CLI + RPC to share the same state, pass the same explicit --realm to both. For CLI commands, the default context root is the current directory. The default state root is <context-root>/.rkat/realms. 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

Required API keys (at least one):
VariableProvider
ANTHROPIC_API_KEYAnthropic Claude
OPENAI_API_KEYOpenAI GPT
AZURE_OPENAI_API_KEY plus AZURE_OPENAI_ENDPOINTAzure OpenAI
GOOGLE_API_KEY / GEMINI_API_KEYGoogle Gemini
See providers for full key precedence (RKAT_* variants included).

​
Config files

Canonical runtime config for CLI commands is realm-scoped (<context-root>/.rkat/realms/<realm>/config.toml by default). Compatibility files still exist:
ScopePath
User~/.rkat/config.toml
Project.rkat/config.toml
These are useful for templates (rkat init) and compatibility workflows, but realm config is the runtime source of truth for CLI/RPC/REST/MCP surfaces. Common tool gates: 
[tools]
builtins_enabled = false
shell_enabled = false
schedule_enabled = true
workgraph_enabled = false

​
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: 
[models]
anthropic = "claude-opus-4-8"

[models.claude-internal-preview]
provider = "anthropic"          # required: anthropic | openai | gemini
display_name = "Claude Internal Preview"
context_window = 500000          # drives compaction scaling
max_output_tokens = 16384
vision = true                    # capability flags default to false
web_search = false
call_timeout_secs = 900
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: 
[self_hosted.servers.local]
transport = "openai_compatible"
base_url = "http://127.0.0.1:11434"
api_style = "chat_completions"

[self_hosted.models.gemma-4-31b]
server = "local"
remote_model = "gemma4:31b"
display_name = "Gemma 4 31B"
family = "gemma-4"
tier = "supported"
context_window = 256000
max_output_tokens = 8192
vision = true
image_tool_results = true
inline_video = false
supports_temperature = true
supports_thinking = true
supports_reasoning = true
call_timeout_secs = 600
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 enabled by default for factory-built agents. If the active model fails at a recoverable LLM boundary, Meerkat can move through an ordered backup chain and retry with the next viable model: 
[model_fallback]
enabled = true

[[model_fallback.chain]]
model = "claude-opus-4-8"
provider = "anthropic"

[[model_fallback.chain]]
model = "gpt-5.5"
provider = "openai"
auth_binding = { realm = "dev", binding = "openai_oauth" }
Omit chain to use the catalog default chain. Set enabled = false to fail closed on the original model error. Set use_catalog_default_chain = true in a higher-precedence config layer when you need to undo an inherited disabled or custom policy. 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. The catalog default chain only uses provider bindings available in the selected non-env realm. Fallback can change the effective model surface. Smaller backup models can reduce max output tokens, hide tools gated by model capabilities, and be skipped for context overflow if their context window is too small. The agent receives a hidden system notice when a switch happens, including the reason and any hidden tools. 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 lives under the active state root. By default, that is project-local: 
<context-root>/.rkat/realms/<realm>/
Pass --state-root <path> to use a different parent directory. 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)
  • mobs/ (per-mob <mob_id>.db SQLite storage plus realm_profiles.db)
--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. When SQLite support is compiled in, new persistent realms default to sqlite.

​
MCP configuration

MCP servers are configured separately from realm runtime state:
ScopePath
User~/.rkat/mcp.toml
Project.rkat/mcp.toml
Project servers override user servers with the same name.

​
Exit codes

CodeMeaning
0Success
1Internal error
2Budget exhausted
Most richer session/provider/runtime failures are reported through structured error payloads and stderr text rather than a large exit-code taxonomy. 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