realm_id.
Sharing requires both the same logical realm and the same physical storage
provider/root. Supplying the same ID with two deliberately different explicit
state roots selects two different stores.
For task-oriented commands and troubleshooting, see the
realm guide.
Identity Rules
Explicit user-facing realm IDs:- are 1-64 characters;
- start with an ASCII alphanumeric character;
- contain only ASCII alphanumerics,
_, and-; - cannot contain whitespace or
:; and - cannot use a UUID-like opaque value.
team-alpha, prod, or audit_2026.
Meerkat-generated workspace and isolated IDs use separate typed construction
paths.
Surface Defaults
The CLI is workspace-friendly by default. Server processes are isolated by
default so unrelated launches do not collide.
Context Root And Project Root
Meerkat keeps two path facts distinct:- Invocation context is the supplied current directory or
--context-root. Its canonicalized path determines the workspace-derived realm ID (raw path only if canonicalization fails), while the supplied path remains the no-walk-up boundary for MCP config/trust discovery. - Project root is found by walking upward from the invocation context to the
nearest existing
.rkatentry. Its.rkat/realmsdirectory is the project-local realm-storage candidate. Outside any existing project, the exact invocation context is used for a fresh local candidate.
ws-... realm while storing that realm under the ancestor project’s
.rkat/realms. Use an explicit --realm or a common --context-root when
the nested command should share the parent’s logical realm.
Realm-ID-First Root Resolution
Meerkat resolves identity first, then looks for that realm under candidate roots:--state-rootselects one explicit root and disables candidate probing.- Otherwise, the resolver probes the project-local candidate and user-global platform data root for the resolved realm ID.
- If the realm exists under exactly one candidate, Meerkat opens it where it already lives.
- If it exists under both, startup refuses with a typed split-brain error rather than choosing silently.
- If it exists nowhere, the surface creates it under its default root: local for CLI and user-global for servers.
--state-root or matching server --context-root when
cross-surface first-start convergence matters.
Use these operator commands when layout is unclear:
rkat storage migrate is a report-only dry run unless --apply is
supplied. Adopting one root archives the other registered copy; it does not
merge divergent state automatically.
Explicit Sharing
RealmStorageProvider rather than assuming equal realm IDs make local disks
shared.
Backend And Provider Pinning
The first open writesrealm_manifest.json. It pins the built-in backend or
external storage provider, so later surfaces cannot reinterpret the realm:
sqlite is the normal durable same-realm multi-process profile. jsonl
keeps inspectable session files and a durable runtime.sqlite3 companion for
runtime authority. memory is explicitly ephemeral and process-local.
Multi-process hosting
Several processes may serve one durable realm at once, for example tworkat-rpc servers. Declare it in realm config:
single_process, overrides its parent’s.
With multiprocess:
- Each session is hosted by exactly one runtime at a time. The host holds the session’s hosting claim, an OS file lock released by the kernel when the process exits. Two runtimes inside one process are distinct hosts too.
- Another process (or runtime) neither attaches the session nor writes its
durable state: those calls fail with the typed
SESSION_SERVED_ELSEWHEREerror (the session-busy code withdata.kind = "session_served_elsewhere"). - Each job-delivery recipient is applied by the process hosting the recipient’s session. Recipients of sessions no process hosts are applied by one elected cold-delivery owner per realm, which takes the session’s claim first.
- A process learns of deliveries committed by another process from changes to the realm’s database files, plus a bounded sweep (5 seconds by default) that also notices a released claim or cold-delivery lock after a process exits. These are wake hints only: who may host or write a session is decided by the claims, never by the watch.
- The sweep is the cross-process wake; file notifications only shorten it.
Since 0.9.4 a watch whose notifications cannot be registered (at an inotify
watch or instance limit, or with the process at its thread limit) runs on
its sweep alone and logs “sqlite change watch notifications are unavailable;
the watch runs on its sweep alone”, so cross-process wakes take up to one
sweep. Registration also no longer delays startup: on macOS, FSEvents
registration held the first mob storage open for over 30 seconds in 0.9.3 and
earlier. At most 64 registrations run at once in a process; a watch started
beyond that runs on its sweep alone. To restore notifications on Linux, raise
fs.inotify.max_user_watchesorfs.inotify.max_user_instancesand restart the process.
single_process does not require
multi-process-capable storage. On stores that provide OS-locked hosting claims,
session exclusivity still applies in both modes: another runtime cannot
continue a session while its current host holds the claim. The claim is
released when its last holder is dropped or the host process exits.
On a store with OS-locked claims, in either mode, a session whose claim cannot
be taken for a reason other than another holder (its lock file cannot be
created or locked, for example after the hosting/ directory became
unwritable) is refused with a typed “hosting claim unavailable” error
(SESSION_HOSTING_UNAVAILABLE, carried under the runtime-unavailable code).
It is never served without its claim. Likewise a process that cannot take the
cold-delivery lock applies no cold deliveries until it can.
A host that takes over a session whose earlier process ended without
unregistering it (a crash or a power cut) can settle the runtime work that
process left before it registers the session, without serving it:
PersistentSessionService::settle_cold_predecessor_before (for a mob’s
session service,
MobSessionService::settle_cold_predecessor_with_mob_lifecycle_authority_before),
under the host’s own claim of the session (grant_session_hosting). It needs
OS-locked claims and a HeadCanonical runtime store. It commits the durable
tail the earlier process left, ends every input that never ended as
stopped and answers its requester, finalizes every terminal receipt and
publication still owed, and answers an input that a recovered boundary
consumed without a receipt as outcome unknown
(CompletionOutcome::OutcomeUnknown; its requester gets interaction_failed
with reason kind outcome_unknown): what its run did for it is not known, so
it must not be resubmitted. Keep the claim until the session’s next
registration has published: that registration joins the claim’s lineage and
does not settle the lost owner’s consents again. Ok is a complete census of
the session’s input rows; a refusal, a deadline or a cancelled call certifies
nothing, and repeating the call converges. A host that governs consents
registers the session only when the census reports the owner-loss outcome
Completed or NotOwed. NoConsentOwner means the runtime has no issuing
consent owner installed, a composition defect: install it, then repeat the
call. Directed work needs the service’s event store: without one, publishing
a directed input’s terminal refuses after the input ended, and the terminal
stays owed until a service with an event store repeats the call.
The claims and delivery coordination live under the realm root in hosting/
and delivery/. They are derived runtime files, reported by
rkat storage doctor as inventory, and never removed while the realm is
online.
Manifest format 2 can also record operator-declared ephemeral domains. A storage provider
must declare exactly one durability result for each required domain:
sessions, runtime, schedule, workgraph, jobs, blobs, and
artifacts. A durable domain resolving to undeclared non-persistent storage
refuses startup unless the manifest explicitly declares that domain ephemeral.
A provider can instead return the typed DeclaredEphemeral resolution itself,
as the JSONL backend does for its disabled schedule store; that typed provider
declaration does not require a duplicate manifest entry.
Readers reject a manifest format newer than they support and reject a provider
or backend mismatch. Existing realms remain pinned when defaults change.
Config And State
The realm’s own config document is<state-root>/<realm>/config.toml, except
for the reserved global realm, whose config is home-rooted at
~/.rkat/config.toml.
Config can inherit from parent realms, but state never does. A child can inherit
models, bindings, MCP servers, hooks, skills, and limits while keeping its
sessions and every durable state domain local.
