Skip to main content
Configuration is realm-scoped. The active realm_id determines which raw config document is read and written.

Realm-scoped config

An ordinary non-global realm keeps these files in its resolved realm directory:
  • config.toml (user settings)
  • config_state.json (generation counter for CAS)
  • realm_manifest.json (pinned backend + metadata)
The reserved global config document and its config-generation sidecar are the exception: they are home-rooted at ~/.rkat/config.toml and ~/.rkat/config_state.json. Global config can be inherited, but a global realm’s runtime state is never inherited. For CLI commands, the normal non-global location is project-local:
Here project-root is the nearest ancestor containing .rkat. Outside an existing project, it falls back to the exact invocation context. The invocation context itself is never walked up for workspace realm identity or MCP trust discovery, so identity and the local storage candidate are intentionally separate facts. An explicit --state-root bypasses candidate probing. For daemon/API surfaces that do not receive a --state-root, the default state root is the platform data directory:
  • macOS: ~/Library/Application Support/meerkat/realms/<realm>/
  • Linux: ~/.local/share/meerkat/realms/<realm>/
  • Windows: %APPDATA%\meerkat\realms\<realm>\
Use realms to choose whether state is shared or isolated.

Realm config inheritance

A realm config doc may declare a parent, and resolution walks a single chain head -> parent -> ... -> global. A terminal non-global realm appends global when a global section is configured. The chain can also end before global when no global config has been materialized.
  • Config inherits along the chain: models, MCP servers, hooks, skills, limits, and auth bindings are composed parent-first with child-wins.
  • State never inherits: sessions, session stores, event stores, and the .rkat/ projection stay realm-local to the consuming (head) realm.
The global realm’s config document is home-rooted at ~/.rkat/config.toml (a single well-known location, not a per-workspace file), which is why a single interactive rkat auth login is inherited by every workspace realm via the chain tail. See Realm inheritance for the full model, including credential read-inherit / write-strict-owner and the add/override-but-not-remove rules for MCP servers and hooks.

Effective precedence

For an agent build in a given realm, effective precedence is:
  1. Built-in defaults
  2. A configured global root and explicit ancestors, folded root-first
  3. The head realm’s own config.toml
  4. Per-request runtime parameters (for example model, system prompt, or tool toggles on create/resume calls)
The agent build path on every surface (CLI, REST, RPC, MCP server) composes this effective config over the head realm, so model/MCP/hook/skill/limit inheritance applies on every build, not just the auth path. config get / config set operate on the raw head doc (a read/write split): an inherited entry is read through composition and never copied into the child’s own doc. This does not make a config get then config set round trip safe in a child realm: config get returns the head doc as a typed config with every default filled in, and config set writes all of it back as the child’s own values. Use config patch for partial edits. This shared configuration path does not install native permission owners. Native governance requires explicit trusted-host composition. The stock hosts select OS process confinement from the [confinement] section and their --confinement flags (see OS process confinement); a Rust embedding installs it on its own factory. See authorization integration for the supported profiles and native governed embedding for setup. Environment variables still matter, but they are primarily part of runtime credential resolution, not a general config layer that mutates the loaded realm config. In practice:
  • realm config remains the canonical persisted settings surface
  • provider credentials can still come from RKAT_* or provider-native env vars at resolve time
  • bindings and auth profiles decide how those credentials are used at runtime

Config APIs and CAS

RPC, REST, and MCP all expose the same config envelope:
  • config
  • generation
  • realm_id
  • instance_id
  • backend
Some surfaces also expose resolved_paths in diagnostic/admin contexts. Treat that field as optional rather than universal across all public config envelopes. Writes support optimistic concurrency:
  • config/set and config/patch accept optional expected_generation
  • stale writes return generation conflict
This gives deterministic behavior when multiple clients or processes update config concurrently.

Merge semantics

Meerkat uses three update models:
  1. Layered config loading (defaults -> file -> runtime) uses section-specific merge rules:
  • optional settings such as max_tokens override when present; many non-optional scalars override only when nondefault
  • shell, store, comms, compaction, and rest: a nondefault incoming section replaces the whole section, including its omitted fields’ defaults
  • hook entries append; hook scalar settings override only when nondefault
  1. Realm-chain composition reuses those rules, folding each realm doc parent-first:
  • per-provider model defaults: union, child-wins per provider (a child overrides its anthropic default while inheriting the parent’s openai default)
  • MCP servers: map-key union, child-wins per name (add or override, never remove)
  • hook entries and skill sources: append parent-first (child cannot remove inherited entries); hook scalars retain the nondefault-value rule
  • limits: per-field optional child-wins (a child can tighten max_sessions while inheriting other caps)
  • shell, store, comms, compaction, and rest: retain nondefault whole-section replacement, not per-field inheritance
  • filesystem-backed docs additionally use raw TOML presence for tools, retry, and skills overrides, so explicitly setting a supported field to its default can override a parent; this is not a universal rule for all scalar fields or non-filesystem sources
  • model_fallback: a nondefault table replaces the inherited table as a whole; an empty/default-valued table inherits, while enabled = false explicitly replaces and disables
  • governance: a present section, even an empty one, replaces the inherited one as a whole; a document without it inherits it
  • confinement: per launch kind, a requirement only holds or is added; a less trusted document cannot replace or remove it (see composition)
  • the binding/backend/auth maps are not merged across realms: each realm’s binding resolves its backend_profile / auth_profile only within its own section (the owning realm)
  1. Runtime patch APIs (config/patch, PATCH /config) use RFC 7396 JSON merge-patch semantics.
Use config/set when replacing the whole config intentionally, and config/patch for surgical updates.
config/set (and rkat config set, including any partial --toml, --json or FILE payload) writes a full typed config: every key the request leaves out is written with its default. The MCP server’s meerkat_config set refuses a partial payload, but a complete one has the same effect. In a child realm each of those keys becomes the child’s own override, so the realm stops inheriting it, and capabilities the parent disabled whose defaults are on (tools.schedule_enabled, provider web search, Gemini Google search, skills.enabled) are enabled again. A config get then config set round trip has the same effect. config/patch writes only the keys it names and keeps the rest of the document as written; a null value removes a key so the realm inherits it again.

Presence-based override (Option fields)

Config.max_tokens and agent.max_tokens_per_turn are optional. None means “inherit / use the template default” and is resolved at point-of-use (resolved_max_tokens / resolved_max_tokens_per_turn). Merge for these fields is presence-based (an explicit value wins, regardless of whether it equals the default), so a child realm can override a non-default parent value back down to the default - something a != default heuristic could not express.

Agent turn limits

Set agent.max_turns to bound the model-loop iterations in one agent run:
An omitted value inherits from the parent realm. If the entire chain omits it, agent construction uses the default of 100. An explicit value always overrides the parent, including 100 and 0. max_turns = 0 terminates immediately with the TurnLimitReached cause, before the first model request; zero does not mean unlimited. The counter resets for each run, so this is not a limit on the number of user messages in a session. Direct Rust callers can set the same limit with AgentBuilder::max_turns(u32).

CLI behavior

CLI config commands operate on the selected realm:
Without --realm, CLI derives a stable workspace realm (ws-...) from the current directory, or from --context-root when supplied.

What About ~/.rkat/config.toml And .rkat/config.toml?

~/.rkat/config.toml is the home-rooted config document for the reserved global realm. Interactive rkat auth login writes the [realm.global] binding section here; once configured, it is the implicit chain tail for workspace realms. The project-root .rkat/config.toml still exists for rkat init, legacy single-file loading, and explicitly layered hook discovery. Do not confuse it with the active non-global realm document at <state-root>/<realm>/config.toml, which is the canonical raw head store used by CLI/RPC/REST/MCP runtime composition.

File permissions

A config document can hold credential material: an auth profile’s inline secret, the env values of a command credential source, and the literal args, env and headers of an MCP server. On Unix the engine therefore writes every config document, the config_state.json beside it and mcp.toml readable by their owner only (mode 0600), whatever the process umask. The file has that mode from its creation, before any byte is written, and a write replaces the document with it, so a document an earlier release left readable by others becomes private at its next write. A write never adds a permission the file lacked: a document its owner made 0400 stays 0400. The one exception is a directory shared through its group on purpose. When a document’s directory has the setgid bit, the documents written there are 0640: readable by the directory’s group, which the directory gives them, never writable by it and never readable by others. Set the bit once on a directory that several accounts read (chmod g+s <dir>), such as the .rkat directory of a shared project or a realm directory a helper under another account reads. A document that is already 0600 there stays 0600 until its owner runs chmod g+r on it. Where the bit cannot be set, grant the read after each write, with chmod g+r or an ACL on the document: a write replaces the file, so a grant on the file before it does not carry over, and a default ACL on the directory does not reach a file that is created 0600. The engine changes the mode of no directory: a directory it creates takes the umask’s mode, and an existing one keeps its own. A document written before this rule keeps its mode until the engine writes it again; chmod 600 tightens it at once. The admission fence file follows its own rule (see Realm Admission Fences), and the credential store keeps its files 0600 in 0700 directories.

Backend and storage settings

Session backend is pinned per realm in realm_manifest.json (sqlite, jsonl, or memory). --realm-backend only matters on first creation of a realm. [storage] hosting declares how many processes may serve the realm at once:
It is layered like every realm option (a child realm’s explicit value, including single_process, wins). With multiprocess, every surface refuses to start when the realm’s stores cannot provide trusted cross-process hosting or the runtime store’s watch cannot start its sweep. Since 0.9.4 it does not refuse because file notifications cannot be registered (an inotify limit, for example): the sweep, every 5 seconds by default, is then the cross-process wake. See Realms: multi-process hosting.

Compaction settings

Compaction runtime policy is configurable in realm config:
When session-compaction is enabled, AgentFactory maps these values into the runtime CompactionConfig. If auto_compact_threshold is omitted, cataloged models scale the token trigger to 80 percent of the smaller of their context window and separate input ceiling, when one is declared. For gpt-6-astra, the 922,000-token input ceiling gives a 737,600-token default trigger; its shared input-plus-output context window remains 1,050,000 tokens. When the selected account states a smaller prompt limit for the model (a GitHub Copilot account model’s max_prompt_tokens, or its context window less the session’s output budget, max_tokens), the trigger is 80 percent of that limit instead. An explicit auto_compact_threshold, or a per-build override, above the account’s prompt limit is lowered to the limit, with a warning: the account refuses a longer prompt whatever the threshold. Built-in provider clients also attach the current provider’s approximate request-byte cap to each lowered request; the byte trigger fires at 80 percent of that cap. max_request_bytes is an optional operator override, especially useful for a self-hosted gateway whose limit is not in the catalog. Compaction is checked against both token and serialized-request pressure. Inline media can exhaust a provider byte limit long before the token estimate reaches its threshold. history_retained_rewrites bounds the transcript history a session document keeps. Each compaction is a recorded transcript rewrite, and the session’s rewrite graph holds the history needed to reconstruct earlier revisions. After each compaction, only the most recent history_retained_rewrites rewrites keep that history. Older rewrites keep their commit records and digests, and their message bodies are dropped. Without the bound, a session document kept every message it ever produced, however often it compacted. A fork, rewind, restore or revision read that targets a revision older than the window fails with a typed error naming the oldest retained revision. The SQLite store applies the same bound to its rows: each compaction’s write deletes the stored history below the window in the same transaction.

Retry and stream watchdog settings

LLM retry policy (RetryPolicy) is configurable in realm config:
call_timeout is a tri-state override for the hard per-LLM-call deadline: omitted inherits the profile-derived default, "disabled" turns it off, and a duration sets it explicitly. stream_inactivity_timeout is the per-provider-stream inactivity watchdog. It is on by default with a 300-second window: an LLM call whose stream reports no events for the window is aborted with the retryable StreamStalled failure and flows through normal retry handling. Each received stream event re-arms the window, so long-but-alive responses are unaffected. Set stream_inactivity_timeout = "disabled" to opt out, or a duration ("120s") for an explicit window for every model. Like call_timeout, an omitted value inherits from the model profile: a model whose provider documents responses that can stay silent for minutes has its own catalog window (gemini-4-carbon, gemini-4-argon and, from 0.9.15, gemini-4-hydrogen: 900 s, gpt-5.5-pro: 7200 s), a self-hosted model can declare one with stream_inactivity_timeout_secs (at least 60 seconds; config validation refuses a shorter one), and every other model uses the built-in 300 s. The window is resolved for each LLM call, so a model change or fallback uses the new model’s window. The watchdog covers all built-in provider clients; a custom AgentLlmClient that does not report stream liveness fails open (no watchdog; only the hard call timeout applies). An explicit stream_inactivity_timeout must be greater than zero: config validation refuses "0s", which would stall every call; use "disabled" to turn the watchdog off. Keep an explicit window at 60 seconds or more. The OpenAI-compatible client waits up to 30 seconds after the model’s final event for its usage trailer, and the watchdog keeps running through that wait, so a shorter window can abort and retry a stream whose answer already arrived. Unknown provider failures also enter the machine-authorized bounded retry path. Explicit terminal classes such as invalid requests, authentication failures, exhausted quota or credit (OpenAI insufficient_quota, Anthropic spend caps, Gemini daily quota), missing models, content filtering, context overflow, and oversized requests remain non-retryable. With the default max_retries = 3, a persistently unknown failure can make four provider attempts before returning retry_exhausted. The turn’s typed error then names what failed: the provider, the typed reason of the last attempt and retryable: true (see the JSON-RPC turn error).

Turn and agent-lifetime bounds

The timeouts above bound one segment of a turn: a single LLM call, a single provider stream, a single tool call. Their sum is a separate fact with a separate owner:
max_turn_duration is the aggregate bound. Its clock is re-armed at every run entry, so it measures one turn end-to-end no matter how many LLM calls, retries, and tool batches that turn contains. Exceeding it takes the existing time terminal, TurnTerminalOutcome::TimeBudgetExceeded, which surfaces as AgentError::TerminalFailure { outcome: TimeBudgetExceeded, .. }. Note the asymmetry with the other budget dimensions, which is deliberate: an exhausted token or tool-call budget is an orderly stop that still answers the caller, while an exhausted deadline is a hard failure. A turn past its deadline can no longer promise what it did or when it will answer, so it fails closed rather than reporting a warning and continuing. max_duration is not a per-turn deadline. Its clock starts when the session’s agent is built and is never re-armed, so it measures the agent’s whole lifetime including idle time between turns. Setting it low to bound a turn will terminalize a later turn that did no work. Both are unset by default: turns are unbounded in aggregate unless a deployment declares a ceiling. The bound is enforced at segment boundaries, so it never tears down a tool call that is already running; the effective ceiling is max_turn_duration plus the longest segment already in flight (at most one per-tool-call timeout, since calls in a batch run their clocks together). Before a limit stops a run, the agent warns once: when tokens, tool calls, or a time horizon reach [agent] budget_warning_threshold of their limit (0.8 by default), it emits a budget_warning event whose percent is the fraction used. The per-turn horizon warns again each turn. The value takes effect when it is greater than 0 and at most 1; 1.0 keeps only the budget_warning emitted when a limit is reached. A config with a value outside that range still loads, with a warning, and keeps the inherited threshold (the default if no parent realm sets one).
limits.max_sessions controls active-session admission; persisted history does not consume the limit. RPC, REST, and MCP snapshot this value when their session service builds its admission semaphore. Changing config does not resize an already-running service; rebuild or restart it to apply the new limit.

HTML Presentation Defaults

HTML rendering is surface-requested. The Config schema accepts a default template and optional custom templates:
This is accepted configuration syntax, but the ordinary CLI realm-composition path currently does not propagate presentation. On that path, neither a configured default nor these named custom templates reaches the HTML resolver. This limitation does not describe direct Rust consumers of a parsed Config. HTML output itself still works. Select the builtin explicitly or read a custom template file directly:
Configuration does not turn ordinary runs into HTML; request --html, --output html, or --browser.

Model fallback settings

Model fallback is disabled by default. Enabling it requires a non-empty, explicit ordered chain. There is no implicit catalog fallback:
A fallback target is identified by model, provider, self-hosted server, and auth_binding. The same model/provider with a different credential binding is a valid target. Cross-provider candidates are skipped before credential lookup unless cross_provider = true (default false). Use enabled = false to disable an inherited policy. A nondefault child fallback table replaces the inherited table as a whole. Omitted tables and empty/default-valued tables inherit; explicit enabled = false is nondefault and therefore replaces the parent. A chain alone never enables fallback. Writes and loads treat two legacy shapes differently:
  • Writes are strict. A config set or patch (CLI, REST, RPC, MCP, SDK stores) that introduces enabled = true with an empty chain on a document that did not already have that shape is rejected, and so is any unknown fallback key, including the removed use_catalog_default_chain and unsupported scope/expiry/revert options. A patch that restates enabled = true with an empty chain on a document that already has it is not rejected: it is normalized like a load (see below) and reports the warning.
  • Loads of persisted documents are lenient for the two shapes that config files written by rkat 0.8.36 and earlier can contain. The document still loads, the legacy setting is ignored, and the surface reports a typed warning (ConfigWarning) naming the file. rkat prints it once per file on stderr without changing the exit status; servers log it once per file.
A legacy table loads as if it were absent. That matches 0.8.36, where a child realm’s enabled = true table with no chain equalled the default and inherited its parent’s policy, so a reviewed chain on a parent realm keeps applying to children written by 0.8.36. Fallback only ever uses explicit [[model_fallback.chain]] entries; the removed catalog chain is never used. A load never rewrites the file. The next write to that document drops the legacy setting (the enabled key of the first shape, and use_catalog_default_chain). A patch merges onto the document as persisted, so a patch that adds a [[model_fallback.chain]] target to an enabled = true document keeps enabled = true and turns fallback on; any other patch drops the legacy setting and reports the warning. To silence a warning, delete the [model_fallback] table, or add an explicit [[model_fallback.chain]]. Only realms on the resolved inheritance chain are reported when a config is composed, so ~/.rkat/config.toml is reported there only when it is on that chain. Operations on the global document itself report it too: rkat auth login, rkat config get --realm global, and the rkat credential setup that rewrites it. Explicit brain_swap requests are independent of automatic fallback settings. Target discovery uses the effective model catalog, configured realm routes, account affinity, and installed provider runtimes; it does not resolve foreign credentials or prebuild foreign clients. The active route remains eligible, including an environment-backed active route, but an unconfigured foreign environment-only route is not advertised. Credential and client admission still occur through the canonical runtime realization before the next turn; a staged request is not a committed switch. Separately enabled image generation may resolve its own provider credentials; disabling automatic model fallback does not disable image features. An explicit image-generation disable skips that feature’s automatic executor discovery. Mob definitions also accept [runtime.model_fallback] and [profiles.<name>.model_fallback]. A present profile table wins over mob runtime, which wins over host config; explicit false is preserved through materialization and portable profile revival. Realm-profile references cannot add a fallback override beside realm_profile; put it on the referenced profile or in the mob runtime table instead. Fallback activation is still runtime-governed: the generated recovery authority must classify the LLM failure as recoverable, and the core run loop must decide the retry is pre-stream safe. Defaults consider capacity and provider unavailability only after three failed attempts. Transport and empty-output failures never migrate by default; ordinary bounded retries remain separate. Migration is suppressed after visible text or reasoning. Admission uses the actual hydrated, compacted request, output reserve, target context limits, required tools/modalities, structured output, and credential authority. From 0.9.15, a session’s reasoning_effort level is carried to each target and checked against the target’s own route: a target that does not accept it is skipped (reasoning_effort_unsupported), never switched to with another effort, and the session keeps the level on the target it commits to. Also from 0.9.15, a turn that changes the level of a live session (sets another level or clears it) leaves that live session without its model fallback chain until its next build (a resume or a restart builds it with the chain again), and a turn that names the level the session already holds changes nothing. Unsafe candidates produce typed model_fallback_skipped events, even if every candidate is rejected. Staging is not commitment; only model_fallback_committed confirms the canonical sticky route changed. New fallback commits persist target-bound provenance in the same canonical control transaction. An unsafe fallback-origin resume requires explicit model reconfiguration; explicit identity overrides obsolete that provenance. There is no automatic restoration or migration of pre-0.8.37 sticky routes: historical notice text and brain-swap history are not fallback authority. Scoped overlays, expiry, timed reversion, and doctor/migration redesign remain unsupported.

Governance settings

A stock governed realm can require review above R1 for exact operation targets. Each rule names one target, by the name its owner registers it under (never a model-facing display name), and the tier it requires:
  • target: mcp_server (every operation of one configured MCP server), mcp_operation (one raw operation of one server) or tool_bundle_operation (one operation of a registered tool bundle). Each target appears once.
  • tier: r2 (the configured reviewer model reviews the exact operation before it runs) or r3 (a human consents to it). A rule only raises a tier: it never allows an operation the stock rules refuse, and where several rules match, the strictest applies.
  • consent_assurance: required for r3 and refused for r2. The weakest approver authentication the consent accepts: device_trusted (a declared local-operator posture, such as the operator of a stdio connection) or person_authenticated. A person satisfies either; a delegated service credential satisfies neither.
  • [governance.review.reviewer]: the explicit model that reviews R2 operations. There is no default model; without it an R2 operation is refused, never run at R1.
The review and the consent happen where rkat-rpc serves the realm as a governed pipe. rkat in a governed realm reads the same rules and installs no reviewer and no human route: it refuses an operation that a rule puts above R1, an r2 operation even when a reviewer is configured and an r3 operation always, and the run goes on. A reviewed MCP or tool-bundle operation shows its reviewer and consenting human the account it acts with, as its own owner states it: the MCP server’s connector binding, its oauth_account, or its host’s account = "none" declaration (see the account an operation acts with), or the account a host declared when it registered the bundle. An operation whose owner states none is refused, never reviewed without it. rkat and rkat-rpc, the stock hosts that open a governed realm, each read the rules from the realm’s effective configuration when the realm opens. A section that cannot be read or is malformed refuses the governed work: rkat-rpc refuses the pipe, and rkat fails the command before the realm opens (Error: Failed to load config: ... or Error: Invalid runtime config: ..., exit code 1). rkat-rest and rkat-mcp refuse to start on a governed realm. Unknown or misspelled fields are refused, including inside the reviewer’s identity. [governance.decisions] names the approver ids the operator of an rkat-rpc stdio connection acts for when the connection presents and decides durable decisions:
  • operator_approver_ids: each entry an approver id (non-empty, at most 256 bytes, no whitespace or control characters). Without the key the operator acts for ["operator"]; an explicit empty list makes it act for none, so the connection presents nothing and refuses every decide.
A plain stdio connection reads the list from the realm’s effective configuration each time it presents or decides, so a change applies to the next presentation (a decision that opens, or a decision/list) and the next decision/decide; a decision already presented is refused once its approver id is no longer listed. The stock governed pipe reads its host’s configuration as the pipe started, so a change reaches it at its next start. Governance is administered by the realm’s trusted host in the realm’s own config document. An ordinary config write (config/set, config/patch, PUT/PATCH /config, the MCP config tool or the CLI) cannot change, remove or restate the section, including a full replace that omits it, and is refused with governance_administration_required. The section stays readable through the ordinary config reads. A realm composes its ancestors’ governance through its realm sections, so those are covered too: a write that changes them in a way that would change the governance the realm composes is refused with governance_administration_required (see confinement administration for the rule both sections share).

OS process confinement

[confinement] selects the OS process confinement a stock host (rkat, rkat-rpc, rkat-rest and rkat-mcp) applies to the processes its agents launch: shell tool calls, background jobs and monitors (shell), command hooks (command_hooks), and local MCP stdio servers and stdio skill sources (mcp_stdio). Without the section, every launch runs as the trusted host, as before.
  • trusted_host: no OS confinement, the default.
  • workspace: the launched process reads and writes the host’s workspace root and the write subtrees, reads the read subtrees, gets the command_runtime_v1 platform baseline, and opens IP sockets only with network = "unrestricted". The workspace root is the CLI’s project root and a server’s --context-root; a server started without --context-root refuses to start with this mode instead of confining nothing. Command hooks and MCP stdio servers start in the workspace root; the shell keeps its own working directory.
  • custom: an explicit requirement in the confinement wire shape (see native governed embedding), and the absolute working directory of the command hooks and MCP stdio servers it confines.
Every path is absolute, without . or .. components. Unknown keys, modes and fields are refused, not ignored. A launch the platform’s backend cannot confine as required is refused at that launch with typed confinement_refused feedback; it never runs unconfined, and the rest of the run continues. At startup a host reports each launch kind’s requested and effective confinement (the backend that enforces it, or that every launch of the kind is refused, with any host setting the backend can tell it lacks, such as vm.memfd_noexec), what keeps the host’s own inputs from its confined processes, and each convention source it does not trust. macOS uses Seatbelt. Linux uses namespaces and seccomp: it needs unprivileged user namespaces (with pid and cgroup namespaces in them, and network namespaces for a launch without IP access) and memory files it may execute (vm.memfd_noexec below 2), and it refuses deny lists, Unix socket grants, nested grants, a grant of / or of /proc, /sys, /dev or anything in them, and granted paths that do not exist or pass through a symbolic link. One link is accepted on Linux: the last component of a read-only literal file grant in a custom requirement, such as { kind = "literal", path = "/etc/resolv.conf" } on a systemd-resolved host for name resolution with unrestricted network, when the link’s own text alone names its regular file (a link to a link is refused), that file is not in /proc, /sys or /dev, and only root or the host’s user can replace the link or a directory above it. These checks trust the owners and modes the filesystem reports, so for a link on a FUSE or network filesystem they trust that filesystem’s server. That file is bound read-only at the link’s path. A file replaced under its name (a new file renamed into place, as systemd-resolved does when its DNS settings change) is checked again by the same rules at the next launch, which binds it. A link replaced with other text refuses the launch, even when it names the same file, and so does a file replaced by anything the same rules refuse. macOS refuses such a grant. Other platforms refuse every confined launch. A confined process finds its program, libraries and data only inside its granted subtrees and the platform baseline; grant anything else it needs with read. A confined command hook, MCP stdio server or stdio skill source names its program by absolute path and receives only its configured environment, never the host’s; a relative program name or a loader variable such as LD_PRELOAD refuses that launch. A confined stdio skill source starts in the kind’s working directory, as an MCP stdio server does; its own cwd does not apply. On Linux each confined launch runs in a pid namespace of its own. Its first process, the one the host holds (the launch’s PID and the leader of its process group), runs the setup, starts the command as pid 2 of the namespace and then runs a small init that the backend executes from a sealed memory file: it holds none of the host’s memory, and the command cannot inspect it. When the command ends, the init reports the command’s exit status (an exit code, or the signal that ended it), which is the launch’s, and every other process of the launch ends with it; killing the launch’s PID ends them all at once. A signal to the launch’s process group reaches the command and every process it started; any signal other than SIGKILL or SIGSTOP sent to the launch’s PID alone reaches only the init, which ignores it. Inside, $$ and getpid() are 2, never the PID the host records. Each confined launch therefore counts as two processes toward a pids limit. The launch sees a read-only /proc of its own pid namespace with process entries only: /proc/self/exe resolves, which Rust toolchains need, while /proc/sys, /proc/net and other host-wide entries are absent, and only the launch’s own processes are listed. A launch without IP access also gets a network namespace of its own, so /proc/self/net shows only its own loopback interface. With network = "unrestricted" the launch shares the host’s network namespace, and /proc/self/net lists its connections and Unix socket names. Each launch also gets a cgroup namespace of its own, so /proc/self/cgroup shows the launch’s cgroup as /, never the host’s cgroup path, while /proc/self/mountinfo still names the source device, filesystem type and mount options of each path bound into the launch. A host that refuses the backend this mount, such as a container runtime that masks or overmounts /proc, or a kernel before 5.8, still runs confined launches, without /proc. With IP access, a confined process may create Unix stream and seqpacket socket pairs, which the Rust standard library uses to start processes; a datagram pair stays refused, since it can be addressed to another socket. A pair socket cannot connect to or serve anything outside the launch, but it can bind an abstract socket name in the shared network namespace, taking that name from other processes, and pass descriptors between processes of the launch.

Composition

A requirement only ever holds or is added across the documents a realm composes, from the most trusted: the user document (~/.rkat/config.toml, which applies even when no document declares [realm.global]), then the realm chain from its root to the head. A document’s statement for a launch kind is its own kind table, else its own all.
  • The most trusted document that requires confinement for a kind decides it.
  • A less trusted document may restate that requirement exactly or state nothing for the kind. Any other statement, trusted_host included, refuses the composition with an error naming both realms.
  • A less trusted document can still add confinement for a kind that no more trusted document confines.

The host’s own inputs

A host that confines every launch kind keeps the inputs it reads its own administration from out of its confined processes’ reach:
  • The realm state (every realm config document and the head realm’s stores under the state root), the user config document and the file credential store (the tokens, keys and secrets of the host’s providers, MCP servers, connectors and comms identity; by default meerkat/credentials under the user’s config directory). A start in which a confined process could change one, by writing it, creating it where it is missing, or replacing a directory on the way to it, is refused, naming the input and the launch kind. Keep the state root, the user config root and the user’s config directory outside every write grant (--state-root, --user-config-root).
  • The convention sources: the project and user mcp.toml files, the hooks of the project .rkat/config.toml, and the skills directories (the project .rkat/skills, filesystem skill repositories and the Git skill cache). A source a confined process can write is not trusted. Each of its MCP servers is refused with untrusted_configuration_source before it is expanded, authorized, connected or spawned, each of its hooks keeps its place and is refused at every invocation, so a mandatory guardrail withholds what it gates, and its skills are not loaded. A definition that a trusted source states identically is used from that source. An MCP auth request (login, completion, cancel, status or logout over JSON-RPC or REST, and rkat mcp login) that names a server only such a file defines is refused as not configured (mcp_server_not_configured) before anything is discovered, registered or stored for it. The model sees a refused server under its name when that is a plain server name, else under a refused-mcp-server-<n> placeholder (never the name of another server of the session), and a refused definition does not fail the rest of the session’s setup. An untrusted mcp.toml that does not parse, or that states an invalid access policy, still fails the setup, as a trusted one does. An embedding host can also judge the hook files by their content: a HookSourceTrust installed with AgentFactory::with_hook_source_trust is asked once per build about each convention hook file the build read (the project and user .rkat/config.toml), with the SHA-256 of the exact bytes it parsed, so a file rewritten after the host checked it is judged as rewritten, and every hook of a file it refuses is refused the same way. It judges those bytes only: not the program or script a command hook names (read when the hook runs), not a run’s hook overrides (the caller’s own input), and not the hooks of the config the host passes to the build, which Config::load fills from the project .rkat/config.toml (or else the user’s). A build handed its own hook engine (AgentBuildConfig::hook_engine_override) reads neither file, so the trust is not asked, and the resolve_layered_hooks_config helper layers both with no decision.
  • Links: an input or a skills directory is judged with the symbolic links in it. A start whose realm state or credential store links to a path a confined process could change (a target that does not exist yet included) is refused like a writable input, and a skill linked out of a trusted skills directory to such a path is not loaded.
Each launch kind is judged on its own grants and protections: one kind’s protection does not cover another kind that writes the same place. On macOS the workspace preset protects <root>/.rkat (the CLI’s default realm state and the project’s convention files). The Linux backend has no deny lists, so there the host’s realm state must live outside the workspace. A write grant outside the root takes the macOS protection away: a kind that can write the root and a place outside it is judged able to move the root away, so the host treats <root>/.rkat as changeable by that kind. A host that runs any launch kind as the trusted host claims none of this: its startup report says that a process the agent drives can still change the host’s own inputs. --confinement trusted-host turns confinement off for the whole process, with no such guarantee. All of the above is about the processes an agent launches. The in-process file tools (apply_patch, blob_save_file) are not processes and are bound by a rule of their own, in every confinement mode and without confinement: they never write a .rkat directory at or below the project root, or any of the inputs and convention sources listed above that lie inside the project root. See paths the file tools never write.

Administration

Like governance, the section is administered by the host in the document itself. An ordinary config write (config/set, config/patch, PUT/PATCH /config, the MCP config tool or the CLI) cannot add, change or remove it, including a full replace that omits it, and is refused with confinement_administration_required. Restating it unchanged is allowed. The section stays readable through the ordinary config reads. A realm composes its ancestors’ [confinement] and [governance] through the realm sections of its own document: its [realm.<id>].parent edge, and a [realm.global] section that puts the user document on its chain. These are covered too: a write that changes them is refused with confinement_administration_required (or governance_administration_required) when the realm would compose a different [confinement] (or [governance]) afterwards, adding or dropping a requirement alike, and sections whose chain does not resolve are refused as invalid. A change that composes the same sections, such as a parent stating the same requirement, is ordinary config. Re-parent a confined or governed realm by editing its document as its host. A credential command (an auth profile’s source = { kind = "command" }) runs as the host, outside confinement, so it is administered the same way, and so is where its token goes. A config write that adds one, changes its program, arguments, environment or working directory, or changes where its token is sent is refused with confinement_administration_required, naming the auth profile, on every config write surface. Where the token is sent is the profile’s provider and auth_method and each binding of the same realm section that names the profile as its auth_profile: adding such a binding, re-pointing one at the profile, moving one to another backend or changing its default_model, and changing the backend it names (its provider, kind, base_url, options or server) or the [self_hosted.servers] entry that backend names are all refused. Its timeout and caching, removing it, and removing a binding are ordinary config. Three more rules keep the token where its document sends it. A self-hosted backend’s endpoint is otherwise the server that serves a request’s model, so a binding that uses a credential command on a self-hosted backend must name that backend’s server (server = "<id>"): a realm with one that does not is refused when it composes, naming the binding and the backend. A host that builds its config without composing it still never sends such a binding’s token to a server it does not declare: the binding is never chosen for another server, by its default_model or as the one unconstrained self-hosted binding, and naming it explicitly for one is refused. A request may override a binding’s auth profile (auth_binding.profile), but not with a credential command profile other than the binding’s own: that is refused before anything resolves (credential_command_profile_override). And a realm section composes whole from one document, but [self_hosted.servers] entries compose field by field across the documents on a realm’s chain, so a composition in which a credential command binding’s server entry differs from the one the command’s own document states is refused, naming the binding, the profile and the server; state the whole entry in the command’s document and nowhere else on the chain. Credentials that do not come from a command (the managed store, credential accounts, environment variables, platform defaults, external resolvers, file descriptors) are outside these rules: where they are sent stays ordinary config. The user document decides for other realms too: its [realm.global] section puts global, and with it the user document’s [governance], on the chain of every realm whose own documents state none, and a realm with no document of its own takes the section the user document states for it. A write to the user document is also refused when such a realm would compose a different section afterwards. Several state roots can share one user document, so a realm the user document states a section for is checked both with its own document from the writing host’s state root and as if it had none, as on a state root that holds no document for it. Each refusal names the change and the realm, for example removing [realm.global] would change the [governance] section a realm whose own document states no parent and no [realm.global] composes, and says what to do instead. The user document a host creates from its template states [realm.global]. One that states [governance] but no [realm.global] cannot gain the section through a config write, nor through a sign-in that provisions credentials under it: add [realm.global] to it by hand. A section the user document states for a realm whose chain does not resolve where the realm has no document of its own (say, an edge to a realm with no document there) cannot be removed or changed by a config write either. Hosts on such state roots refuse to compose the realm, and a write that would have them compose it from the user document alone, possibly with weaker requirements than intended, is refused, naming the realm on a state root without its own document. Edit the user document by hand as its host. Only a store that declares the realm’s chain enforces this, as the stock hosts’ stores do (FileConfigStore::with_realm_chain, SdkConfigStore::with_realm_document). A store built with FileConfigStore::new or SdkConfigStore::with_path alone, and an in-memory store, keep the document’s own [confinement] and [governance] sections but not the realm sections that compose an ancestor’s. Such writes over one state root take turns: each store holds an exclusive advisory lock on <state_root>/.realm-config.lock from before it reads its own document, through its composition check, to after its write, in one process and across processes, so no check reads a document another writer is about to replace. A RealmConfigSource names the file with composition_lock_path; one that names none (the default) leaves such writes unserialized. Hosts on different state roots take different locks; the user document’s own check composes each realm it states as if that realm had no document, so it depends on no document only another state root holds. The lock orders the stores that take it, nothing else. rkat realm create, delete and prune do not take it. Creating a realm writes no config document. Deleting or pruning one checks that no realm’s own document names it as a parent and then removes its document, so a write that makes a document name it in between leaves that realm with a missing parent: its chain does not resolve, and it composes nothing (each use is refused) until its document names another parent. The lock is an advisory file lock (flock on Unix), so on a network filesystem it holds only as far as the filesystem carries it: an NFS client emulates it with a byte-range lock that other machines see only when the mount’s locking reaches the server (not with nolock or local_lock=flock). Hosts on different machines that share one state root over such a mount may not take turns; give each machine its own state root. A realm composes only from the documents on its chain, each from its own: an ancestor whose own document is missing fails the composition (a missing parent) instead of composing as if it required nothing, and rkat realm delete and rkat realm prune keep a realm another realm’s document names as its parent.

Launches outside confinement

Every process a stock host starts runs under its launch kind’s confinement except these, which the host runs as itself (HostLaunchExemption, one constructor per program): Under a host that confines any launch kind, each of these runs, with every program it starts by name (an interpreter named through env, ssh or git-lfs under Git, the programs a browser opener tries), from a PATH without relative directories or the directories a confined process could change, so none of them is a program a confined process put on the PATH. A host that confines only some launch kinds still cleans them: the judgement reports no writer for an unconfined kind, so a launch gets the deny list and the relative-PATH drop and loses only the paths a confined kind could change. Each also runs there without the variables that make a program load code or startup options from elsewhere (LD_*, DYLD_*, PYTHON*, NODE_OPTIONS, NODE_PATH, PERL5LIB, PERL5OPT, RUBYLIB, RUBYOPT, BASH_ENV, ENV, GIT_DIR, GIT_WORK_TREE, GIT_EXEC_PATH and the like), and with the paths a confined process could change taken out of every other variable: a list of directories keeps the trusted ones, and a variable that names one such path is not passed on. A credential command’s own env is passed on with the same paths taken out. A host that confines no launch kind has no confined process to plant anything, and runs them with its own environment as it is. A test of the source enumerates every process launch in shipped code and fails on one that is neither confined nor in this list. Clippy enforces it too: the workspace clippy.toml disallows every API that starts a process (Command::new, exec, fork, posix_spawn, system, popen and the like), and shipped code allows that lint only at the launch sites the test lists, so a launch the text scan cannot see, such as one through an aliased import, still fails the build’s lint.

Operator flags

Each stock binary accepts --confinement <trusted-host|workspace>, with --confinement-network <denied|unrestricted> and the repeatable --confinement-read <path> and --confinement-write <path> for the workspace preset. The flags replace the composed section for every launch kind of that process, after composition: --confinement trusted-host is the operator’s explicit opt-out. They are never persisted, and no session, turn or API parameter can carry them. Relative flag paths resolve against the working directory; a server reads its working directory only for such a path.

See also