> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Realm guide

> How rkat chooses a realm, where realm state lives, and how to share or isolate state deliberately.

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:

```bash theme={null}
rkat "summarize this repo"
```

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:

```bash theme={null}
rkat "hello" --verbose
```

The startup log includes:

```text theme={null}
Using realm: ws-..., context root: /path/to/workspace, realm root: /path/to/workspace/.rkat/realms/ws-...
```

* `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:

```bash theme={null}
rkat run "fix the failing test"
rkat session list
```

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:

```text theme={null}
<context-root>/.rkat/realms/
```

Each realm gets a subdirectory:

```text theme={null}
<state-root>/<realm-id>/
  config.toml
  realm_manifest.json
  sessions.sqlite3
  sessions_jsonl/
```

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](/concepts/realms#realm-id-first-root-resolution) for the full
resolution rules.

## Choose An Explicit Shared Realm

Use `--realm` when multiple surfaces or folders should intentionally share
state:

```bash theme={null}
rkat --realm team-alpha run "draft release notes"
rkat --realm team-alpha session list
rkat-rpc --realm team-alpha
rkat-rest --realm team-alpha
rkat-mcp --realm team-alpha
```

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:

```bash theme={null}
rkat --isolated run "try this without touching my project realm"
```

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:

```bash theme={null}
rkat --context-root "$PWD" run "use this folder as the workspace identity"
```

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`:

```bash theme={null}
rkat --state-root "$HOME/.local/share/meerkat/realms" run "store this realm globally"
```

`--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:

```bash theme={null}
rkat \
  --context-root "$PWD" \
  --state-root "$HOME/.local/share/meerkat/realms" \
  run "use project identity and global storage"
```

## Backend Pinning

The first open of a realm writes `realm_manifest.json` and pins the backend.

```bash theme={null}
rkat --realm audit --realm-backend sqlite run "start audit"
```

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

| Symptom                                                                  | Cause                                                                                       | Fix                                                                                                                                                  |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| A subdirectory does not see parent sessions                              | CLI defaults `context_root` to the current directory                                        | Pass `--context-root <parent>` or an explicit shared `--realm`                                                                                       |
| A command creates a new `.rkat/realms` directory                         | No state root was supplied, so CLI used `<context-root>/.rkat/realms`                       | Pass `--state-root <path>`                                                                                                                           |
| CLI and RPC do not share state                                           | RPC defaults to an isolated opaque realm                                                    | Pass the same `--realm` to both                                                                                                                      |
| `--realm-backend` errors on an existing realm                            | Backend is pinned in `realm_manifest.json`; a conflicting hint is rejected                  | Create a new realm or migrate state intentionally                                                                                                    |
| A run refuses with `realm '...' exists under both candidate state roots` | The realm was materialized under both the project-local and user-global roots (split-brain) | Inspect with `rkat storage doctor`, reconcile with `rkat storage migrate --apply --adopt-root <path>`, or pass `--state-root` to pick one explicitly |

## Recommended Defaults

For normal local development, use the CLI defaults and inspect with
`--verbose` when needed.

For team or daemon workflows, use explicit names:

```bash theme={null}
rkat --realm prod run "check deploy readiness"
rkat-rpc --realm prod
```

For a fully explicit project-local setup, set both axes:

```bash theme={null}
rkat \
  --context-root "$PWD" \
  --state-root "$PWD/.rkat/realms" \
  --realm project \
  run "work only in this project-local realm"
```