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)
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:
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>\
Realm config inheritance
A realm config doc may declare aparent, 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.
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:- Built-in defaults
- A configured
globalroot and explicit ancestors, folded root-first - The head realm’s own
config.toml - Per-request runtime parameters (for example model, system prompt, or tool toggles on create/resume calls)
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:configgenerationrealm_idinstance_idbackend
resolved_paths in diagnostic/admin contexts. Treat that field as optional rather than universal across all public config envelopes.
Writes support optimistic concurrency:
config/setandconfig/patchaccept optionalexpected_generation- stale writes return generation conflict
Merge semantics
Meerkat uses three update models:- Layered config loading (
defaults -> file -> runtime) uses section-specific merge rules:
- optional settings such as
max_tokensoverride when present; many non-optional scalars override only when nondefault shell,store,comms,compaction, andrest: a nondefault incoming section replaces the whole section, including its omitted fields’ defaults- hook entries append; hook scalar settings override only when nondefault
- 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_sessionswhile inheriting other caps) shell,store,comms,compaction, andrest: retain nondefault whole-section replacement, not per-field inheritance- filesystem-backed docs additionally use raw TOML presence for
tools,retry, andskillsoverrides, 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, whileenabled = falseexplicitly replaces and disablesgovernance: a present section, even an empty one, replaces the inherited one as a whole; a document without it inherits itconfinement: 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_profileonly within its own section (the owning realm)
- Runtime patch APIs (
config/patch,PATCH /config) use RFC 7396 JSON merge-patch semantics.
config/set when replacing the whole config intentionally, and config/patch for surgical updates.
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
Setagent.max_turns to bound the model-loop iterations in one agent run:
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:--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, theenv 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 inrealm_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:
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: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. TheConfig schema accepts a default
template and optional custom templates:
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:
--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: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 = truewith an empty chain on a document that did not already have that shape is rejected, and so is any unknown fallback key, including the removeduse_catalog_default_chainand unsupported scope/expiry/revert options. A patch that restatesenabled = truewith 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.rkatprints 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) ortool_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) orr3(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 forr3and refused forr2. The weakest approver authentication the consent accepts:device_trusted(a declared local-operator posture, such as the operator of a stdio connection) orperson_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.
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.
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 thewritesubtrees, reads thereadsubtrees, gets thecommand_runtime_v1platform baseline, and opens IP sockets only withnetwork = "unrestricted". The workspace root is the CLI’s project root and a server’s--context-root; a server started without--context-rootrefuses 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.
. 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_hostincluded, 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/credentialsunder 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.tomlfiles, 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 withuntrusted_configuration_sourcebefore 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, andrkat 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 arefused-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 untrustedmcp.tomlthat 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: aHookSourceTrustinstalled withAgentFactory::with_hook_source_trustis 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, whichConfig::loadfills 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 theresolve_layered_hooks_confighelper 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.
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.
