Skip to main content
Realms are Meerkat’s state boundary. Most surprises come from confusing two independent choices:
  1. Realm identity - which logical realm_id is active.
  2. Realm state root - which storage provider or directory contains it.
The CLI defaults to workspace-derived identity and project-local storage. Server surfaces default to a fresh isolated realm in user-global storage.

​
Inspect The Active Realm

Verbose startup logs include the logical realm, exact context root, and resolved realm root. Inspect a known realm with:
Use rkat storage doctor when candidate roots, manifests, database versions, or a possible split need a read-only diagnosis.

​
Understand The CLI Default

With no --realm, the CLI canonicalizes the current directory and hashes that path into a stable ws-... realm ID. It hashes the raw path only when canonicalization fails, so ordinary symlink aliases converge. Storage discovery has a separate rule. Starting at the exact directory, Meerkat walks upward to the nearest existing .rkat entry and uses that project root’s .rkat/realms as the local candidate. If no ancestor is already a project, the current directory becomes the fresh local candidate. For example:
The nested directory gets its own default ws-... identity, but its physical realm directory lives beneath the ancestor project. This preserves exact workspace identity while avoiding a new .rkat tree in every subdirectory. MCP discovery intentionally uses the exact invocation context and does not walk upward. Treat storage discovery and MCP trust discovery as separate boundaries.

​
Share State Deliberately

Use an explicit name for daemons, teams, or commands from several folders:
An existing realm is found where it lies because resolution probes the project-local and user-global candidates by realm ID before applying the surface’s creation default. The same realm ID shares state only when the processes resolve the same physical root/provider. If you explicitly point two hosts at different local directories, their equal strings do not make those disks shared. Multi-host deployments should use a shared external RealmStorageProvider.

​
Share A Workspace-Derived Realm From Subdirectories

Set one common context root:
--context-root changes the exact input to the ws-... ID. It does not disable project-root walk-up for the local storage candidate. If you want both axes explicit:

​
Isolate A Run

This creates a fresh opaque realm-... identity. Use it for throwaway work; use a named realm when later processes must find the state.

​
Override The State Root

--state-root is the parent directory containing realm directories. It does not change the realm ID. It wins immediately and disables dual-root probing, which is useful for an intentional operator choice but can also select a different physical copy. Inspect first when you are resolving a split.

​
Backend Pinning

Choose a backend on first creation:
The first open writes realm_manifest.json. A later conflicting --realm-backend fails; a matching hint is a no-op. Use a new realm or the documented storage migration path rather than editing the manifest by hand. The realm directory contains the manifest and realm config plus backend- and feature-owned stores. Typical durable profiles include a session store, runtime authority store, jobs, blobs, artifacts, schedules, WorkGraph, and derived projections. Do not rely on one fixed list of filenames across backends.

​
Diagnose Split Roots

If the same realm exists in both local and user-global candidates, Meerkat refuses to choose:
Storage verbs use their exact invocation context and do not walk upward. From a nested directory, either change to the detected project root first or pass each candidate explicitly with repeated --root as described in Storage operations. The migration command is a dry run by default. After reviewing the report, an operator can adopt one root:
The unchosen registered copy is archived read-only. The command does not merge divergent domains or discard the backup.

​
Common Surprises

  • Local interactive work: use the CLI workspace default.
  • Daemons and cross-surface applications: use an explicit stable realm.
  • One-off experiments: use --isolated.
  • Operators and multi-host deployments: set explicit storage and verify its provider/manifest before starting every surface.

​
See Also