Skip to main content
Realms are Meerkat’s state boundary. A realm owns sessions, runtime config, auth bindings, schedules, blobs, mob state, and the pinned persistence backend. There are two separate choices:
  1. Realm identity: which logical realm id is active.
  2. Realm state root: where realm directories are stored on disk.
The CLI’s default is workspace-friendly identity with project-local storage:
That derives a stable ws-... realm id from the workspace/context root, then stores the realm under <context-root>/.rkat/realms/.

​
See The Active Realm

Use verbose mode when behavior is surprising:
The startup log includes:
  • realm is the logical sharing key.
  • context root is the path used to derive a workspace realm when --realm is omitted.
  • realm root is the physical realm directory that contains config.toml, realm_manifest.json, sessions, blobs, and other realm state.

​
Default CLI Behavior

When --realm is omitted, CLI run/session commands use a stable workspace realm:
By default, the context root is the current directory. The CLI derives the workspace realm id from that path and creates .rkat/realms/<realm>/ there on first use. This means a subdirectory is a different default realm from its parent. Pass --context-root <parent> or --realm <id> when you want a subdirectory command to share the parent project’s state.

​
Where State Lives

By default, CLI realm state is project-local:
Each realm gets a subdirectory:
Project-local .rkat/ also contains project-scoped files such as .rkat/mcp.toml, .rkat/skills/, and compatibility configuration workflows. Project-local is where the CLI creates fresh realms. An existing realm is found where it lies: resolution probes both the project-local root and the user-global data root for the realm id first, so an explicit --realm reaches its data no matter which surface materialized it. See Realms for the full resolution rules.

​
Choose An Explicit Shared Realm

Use --realm when multiple surfaces or folders should intentionally share state:
The same explicit realm id means the same sessions, config, auth bindings, schedules, blobs, and mob state.

​
Isolate A Run

Use --isolated when a command should not reuse workspace state:
This creates a fresh opaque realm-... id.

​
Change The Workspace Root

Use --context-root when you want workspace-derived identity, but from a specific path:
This changes both the derived ws-... realm id and, unless --state-root is also supplied, the default project-local state root.

​
Override The State Root

Use --state-root when you want realm files somewhere other than <context-root>/.rkat/realms:
--state-root changes the parent directory that contains realm directories. It does not change the realm id. Combine it with --context-root or --realm when you need both custom storage and predictable identity:

​
Backend Pinning

The first open of a realm writes realm_manifest.json and pins the backend.
After the manifest exists, a conflicting --realm-backend fails with a backend-mismatch error (a matching value is a no-op). The stored manifest wins so every surface opens the same backend.

​
Common Surprises

For normal local development, use the CLI defaults and inspect with --verbose when needed. For team or daemon workflows, use explicit names:
For a fully explicit project-local setup, set both axes: