Configuration

​

MetaConfig

MetaConfig {
    modules: Vec<ModuleConfig>,
    discovery: DiscoverySpec,
    pre_spawn: Vec<PreSpawnData>,
}

​

ModuleConfig

ModuleConfig {
    id: String,
    command: String,
    args: Vec<String>,
    restart_policy: RestartPolicy,
}

​

RestartPolicy

enum RestartPolicy {
    Never,
    OnFailure,
    Always,
}

​

DiscoverySpec

DiscoverySpec {
    namespace: String,
    modules: Vec<String>,
}

​

PreSpawnData

PreSpawnData {
    module_id: String,
    env: Vec<(String, String)>,
}

​

SDK and Gateway runtime options

​

Implicit delegate idle retirement

​

Model fallback

[runtime.model_fallback]
enabled = true
chain = [{ model = "gpt-5.5", provider = "openai" }]

[runtime.model_fallback.policy]
cross_provider = false
min_context_headroom = 0.10
require_tool_parity = true
trigger_after_attempts = 3
triggers = ["provider_unavailable", "capacity"]

# A profile can explicitly disable an inherited policy.
[profiles.coordinator.model_fallback]
enabled = false

​

One-shot mob definition update

runtime = await (
    Meta.builder()
    .mob("config/mob.toml")  # complete replacement definition
    .persistent_state("/var/lib/example")
    .declare_spec_update(expected_revision=1)
    .gateway("/path/to/rpc_gateway")
    .build()
)

const runtime = await Meta.builder()
  .mob("config/mob.toml") // complete replacement definition
  .persistentState("/var/lib/meta-app")
  .declareSpecUpdate(1)
  .gateway("/path/to/rpc_gateway")
  .build();

{
  "runtime_options": {
    "mob_composition": {"authority": "authoritative"},
    "declare_spec_update": {"expected_revision": 1}
  }
}

​

Self-hosted models and the Meerkat host config

[profiles.worker]
model = "gemma-4-31b"
provider = "self_hosted"
self_hosted_server_id = "local"

[self_hosted]
default_model = "gemma-4-31b"

[self_hosted.servers.local]
transport = "openai_compatible"
base_url = "http://127.0.0.1:11434"
api_style = "chat_completions"

[self_hosted.models.gemma-4-31b]
server = "local"
remote_model = "gemma4:31b"

[realm.global]
default_binding = "local"

[realm.global.backend.local]
provider = "self_hosted"
backend_kind = "self_hosted"
server = "local"

[realm.global.auth.local_auth]
provider = "self_hosted"
auth_method = "none"
source = { kind = "platform_default" }

[realm.global.binding.local]
backend_profile = "local"
auth_profile = "local_auth"

mob.toml declares a top-level [self_hosted] table, which is meerkat host configuration
that the mob definition parser ignores; move it into the meerkat config.toml and point the
gateway at that file: runtime_options.meerkat_config_path on rpc_gateway, or the
meerkat_config_path init param (default <workspace>/.rkat/config.toml) on meta_gateway

​

How the host config reaches each surface

​

The init model check

​

Provider credentials

​

GitHub Copilot with a service-account token

​

Native realm and member auth binding

{
  "runtime_options": {
    "native_realm": {
      "realm_id": "team",
      "context_root": "/home/user/projects/app",
      "state_root": "/home/user/.rkat/realms",
      "user_config_root": "/home/user"
    },
    "member_auth_binding": { "realm": "team", "binding": "work", "profile": "default" },
    "provider_credentials_root": "/srv/app/users/u1/credentials"
  }
}

• a definition whose [spawn_policy] creates members automatically: Meerkat builds those members without the gateway’s spawn customizers;
• an enabled model fallback chain with a target that names no auth_binding (Meerkat would select a default binding for it) or another binding, in the members’ configuration, the definition’s [runtime.model_fallback], an inline profile’s model_fallback or a realm-referenced profile’s. Name the launch’s binding on every target, or disable the fallback;
• image generation (tools.image_generation = true in an inline or a realm-referenced profile): Meerkat builds an image generation executor for each image provider other than the member’s own by default binding selection. A spawn whose profile override enables it, or that explicitly enables image generation, is refused too;
• the agent memory engines (agent_memory.distiller, agent_memory.steward enabled): they build their model clients from the default configuration with no binding;
• the same in a child mob an agent creates: mob_create with an automatic spawn policy, a fallback target off the binding or image generation, in an inline profile or a realm profile one references, and a tooling profile, inline or a realm profile, that would make such calls; an agent’s realm profile write (mob_profile_create, mob_profile_update) of such a profile is refused too;
• identity declarations an earlier launch adopted, which the launch’s mob storage holds: Meerkat materializes a declared identity from its sealed declaration without the gateway’s spawn customizers, so init refuses declarations sealed with no binding or another binding, naming them;
• a durable child mob an agent created before the launch named the binding: a restore rebuilds it with the definition it was created with, so init reads every stored child definition and refuses one with an automatic spawn policy, a fallback target off the binding or image generation, naming it. A child whose destroy is pending is skipped (Meerkat only finishes destroying it); a child Meerkat keeps from running for another reason (its owning session archived or not observable) is still refused, fail closed, and one launch without the binding settles it;
• every member build that would still run off the binding or make such calls, checked where the gateway’s session services build a member, and again after an SDK session builder’s callback/build_agent answer is applied (a resume_session_id answer seats the build on another stored session; the resume itself is not refused). Refused are: a member build on another binding or none (none is Meerkat’s default binding selection: a fork seated before the launch, above); Meerkat’s fallback web search, enabled by the build or, on a member rebuilt on its session, by the tooling that session recorded, where the provider’s own web search does not serve it (a model without native search, judged as Meerkat’s factory judges it on the model the build runs on and the [models] of the member’s own mob definition; a copilot backend; or tool governance that disables the provider’s native tools: a dispatch admission, an application tool policy, a restricted tool access policy, or a host’s member registration hook, for whose decision Meerkat prepares every member the hook registers, governed whatever its application tool policy); image generation; and a fallback target off the binding. The provider’s own web search runs on the member’s binding and is not refused. The build is refused, and a member Meerkat builds that way reads broken with the reason, at ready or at its first wake (below);
• mob/adopt_member_identity_declaration and mob/apply_member_tool_declaration, on the stdio gateway and on POST /console/rpc: Meerkat materializes a declared identity from its sealed declaration without the gateway’s spawn customizers, so a launch with member_auth_binding refuses both (-32602, member_auth_binding_uncarried) before anything is written;
• meta/attach_existing_session, or meta/ensure_member with a resume_session_id, of a session that already has a live actor in the gateway’s process, on the stdio gateway and on POST /console/rpc: Meerkat reuses that actor as it is, with the binding it runs, so unless the session records the launch’s binding, in either form, the attach is refused (-32602, member_auth_binding_conflict, with session_id) before the spawn. A session whose binding cannot be read is refused too, with retryable: true in data: the same call can succeed once the read does. A session without a live actor is rebuilt with the launch’s binding.

• Meerkat’s auxiliary tool executors (image generation, the fallback web search) resolve their credentials by default selection, never with the member’s binding, so whatever would enable them under a member auth binding is refused (member_auth_binding_uncarried): image generation at init, at the spawn and the agent tool, and at the member’s build; the fallback web search at the member’s build, where the provider’s own web search, which runs on the member’s binding, passes.
• Meerkat rebuilds a durable fork from its own records, with the binding its session recorded, so a durable fork seated before a launch named its member auth binding is refused at its rebuild under that launch (member_auth_binding_uncarried) and has to be re-created. A new durable fork copies its source’s records the same way: after a launch changes the binding, a source this launch has not built yet (a seated member nothing has woken, under the default member_restore) still records the earlier binding, and a durable fork of it is refused. Wake the source first (a delivery, or meta/identity/warm for an identity), or restore with member_restore: "eager". A meta/fork_helper fork is built with the launch’s binding either way.
• The agent memory engines build their model clients from the default configuration, so a launch with a member auth binding refuses them at init (member_auth_binding_uncarried). A later release can build them from the members’ configuration and binding.

​

Member role migrations

{
  "role_migrations": [
    { "identity": "domain:automation", "from_role": "domain" }
  ]
}

from meerkat_meta import Meta, RoleMigrationDeclaration

runtime = await (
    Meta.builder()
    .gateway("./target/debug/rpc_gateway")
    .roster(roster_provider)
    .role_migrations(
        [
            RoleMigrationDeclaration(
                identity="domain:automation", from_role="domain"
            )
        ]
    )
    .build()
)

​

Fork instruction policy

​

Activated instructions

​

What a fork copies

​

The three policies

​

What reactivate_inherited writes

• Keys: every key with an activation row in the copied prefix, in every namespace. There is no namespace filter.
• Revision and body: the key’s head at the fork boundary, which is its last copied row. The new row carries that row’s revision (namespace, key, revision_id, content_sha256) and its whole body, unchanged. An activation the source wrote after the fork boundary is not in the prefix and is not copied.
• Origin: the child’s own session. The key is then in effect for the child exactly as if the host had activated it there. The row supersedes the copied head’s activation_id.
• Identity: activation_id is fork-reactivation: followed by the first 32 hex digits of SHA-256 over the child session id, a zero byte and the head’s activation id. It depends only on the child and the head, so the same fork writes the same rows. The prefix is for operators; Meerkat recognizes these rows by reproducing them, not by their ids.
• Timestamp: the last copied message’s timestamp.
• Rules: the rows pass the ordinary activation rules: the body digest, 256 KiB per body, and the 1 MiB budget of live activation bodies in the session’s transcript, copied rows included. Each re-activation adds its body again until the child’s first compaction retires the copied rows it supersedes, so a chain of forks of a member with large bodies that does not compact between forks can reach that budget and is refused with lineage_body_budget_exceeded.
• Only what the source activated itself: each head must be an activation the source session wrote itself. A head the source only inherited from an earlier fork, and never activated, refuses the fork with not_effective_in_source.
• Only a body the source still holds: a compaction retires the body of every activation row that a later row of its key superseded. A fork whose prefix ends between such a row and the row that superseded it has no body to carry and is refused with head_body_retired. A fork at the tail copies, with its body, each key’s newest row the source activated itself: a compaction never retires it.

​

What reactivate_inherited trusts

• The copied body is the one in effect in the source at the fork boundary. Meerkat does not ask your application whether that revision is still current, still allowed, or meant for this child. A skill revision you have since withdrawn, replaced or narrowed keeps running in a child forked from a transcript that still carried it.
• Once written, the row is the child’s instruction for that key, like one your host activated on the child. An activation is never removed: to change what the child runs, activate a new revision of the key on the child, which supersedes the re-activation row.
• A fork of the child copies those rows again, so one setting carries an instruction down a chain of forks.
• The policy is one decision for every member, every key and every fork of the gateway’s mob. Choose reactivate_inherited only when every instruction your members may carry is safe to run, unchanged, in any fork of them. require_explicit_activation keeps that decision with the host for each child (and refuses forks that leave it no chance), and refuse rules out durable forks of activated members (an autonomous-host meta/fork_helper still sees their text).

​

Refusals

{
  "kind": "fork_instruction_refused",
  "source_member_id": "assistant",
  "fork_instruction_refusal": {
    "cause": { "kind": "policy_refuses" },
    "keys": [["app.skills", "calendar"]]
  }
}

fork of member 'assistant' refused: fork refused: the child would inherit activated instruction keys [app.skills/calendar] and the fork instruction policy refuses them; reactivate_inherited carries them into the child

​

Setting the policy

​

Example: a member with an activated skill

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "meta/member_activate_instruction",
  "params": {
    "identity": "assistant",
    "activation": {
      "revision": {
        "namespace": "app.skills",
        "key": "calendar",
        "revision_id": "calendar-v3",
        "content_sha256": "sha256:<hex of the body>"
      },
      "activation_id": "calendar-v3-assistant",
      "expectation": { "kind": "absent" },
      "body": "Use the calendar tools to answer scheduling questions."
    }
  }
}

from meerkat_meta import Meta

runtime = await (
    Meta.builder()
    .mob("config/mob.toml")
    .fork_instruction_policy("reactivate_inherited")
    .build()
)

​

Child mob tool policy and bundles

​

child_application_tool_policy

{
  "application_tool_policies": ["{\"schema_version\":1,...}\n"],
  "child_application_tool_policy": {
    "kind": "provider",
    "provider_id": "example",
    "policy_id": "example-tools"
  }
}

• Python: Meta.builder().child_application_tool_policy({"kind": "provider", "provider_id": "example", "policy_id": "example-tools"}).
• Rust: MobBootstrapSpec::with_child_application_tool_policy(binding) or UnifiedRuntimeBuilder::child_application_tool_policy(binding). A conflicting binding from the two refuses the build with ConflictingConfiguration.

​

Child-available tool bundles

use meerkat_meta::ChildToolBundleAvailability;

let spec = spec
    .register_tool_bundle("team", team_tools.clone())
    .register_tool_bundle_with_availability(
        "calendar",
        calendar_tools.clone(),
        ChildToolBundleAvailability::ChildAvailable,
    );

​

Mob profile tools ([profiles.*.tools])

[profiles.assistant.tools]
comms = true
builtins = true
workgraph = true
schedule = true

​

WorkGraph

​

Mob announcements

​

Mob announcement source runners

​

Mob announcement declarations

​

Storage layout and durability

​

Identity bootstrap

use meerkat_meta::{IdentityBootstrapMode, UnifiedRuntime};

let runtime = UnifiedRuntime::builder()
    .definition(definition)
    .persistent_state("state")
    .roster_provider(roster_provider)
    .identity_bootstrap_mode(
        IdentityBootstrapMode::LazyWithBackgroundWarm { concurrency: Some(2) },
    )
    .build()
    .await?;

let status = runtime
    .identity_runtime()
    .expect("identity-first runtime")
    .identity_bootstrap_status();

from meerkat_meta import IdentityBootstrapMode, Meta

runtime = await (
    Meta.builder()
    .gateway("./target/debug/rpc_gateway")
    .mob("config/mob.toml")
    .persistent_state("state/meta")
    .roster(roster_provider)
    .identity_bootstrap_mode(
        IdentityBootstrapMode.lazy_with_background_warm(concurrency=2)
    )
    .build()
)

status = await runtime.wait_identity_bootstrap(
    target="startup_ready",
    timeout=120,
)
if not status.ready or status.startup_ready is not True:
    raise RuntimeError(status)

​

Letting in-flight turns finish on shutdown

• A durable member, one whose session lives on a persistent session service and so commits each round, keeps its run: the run is suspended, not cancelled, and continues from its last committed round at the member’s next start. Its eligible queued prompts are kept for that start too, for up to 15 minutes.
• Any other member’s run is cancelled, and its queued inputs end with it.

1. asks a host composition to stop admitting new work (see below);
2. stops the schedule host from claiming occurrences: an occurrence that falls due during the window stays due, and the restarted gateway handles it under its misfire policy. A skip occurrence overdue past its grace is skipped, and a long window plus a slow restart can push a catch_up_within occurrence past its bound;
3. stops the HTTP listener from accepting connections (requests and streams already open continue);
4. closes cross-mob control, identity foreground operations and runtime delivery;
5. stops the mob with every member’s current run left running, and waits until each of those runs ends or the window passes.

• Mob-mutating tool calls (spawn, delegate, fork, wiring) are refused, typed, and the model sees the error.
• A message to a peer is held, and ends Abandoned(Stopped) at the shutdown. A turn that waits on another member’s new run cannot finish, so it is still running when the window ends.
• mob_announce commits, and subscribers receive the announcement after the restart.
• WorkGraph writes commit, and their wakes stay pending.
• Identity foreground operations are refused, typed. A caller already waiting on a turn (meta/wait_for_turn) keeps waiting and gets the turn’s outcome.
• A schedule the turn creates is stored, and fires after the restart.
• Detached jobs and monitors keep running, with their notifications pending in the inbox.
• Host callbacks are answered, under the handshake and under SIGTERM. An SDK host hit by the same signal may be stopping itself, so SDK-hosted gateways should stop through the handshake.

​

meta_gateway identity roster

{
  "identity_roster": [
    { "identity": "personal:alice", "profile": "alpha" },
    {
      "identity": "domain:security",
      "profile": "security",
      "display_name": "Security",
      "labels": { "console_group": "Internal" },
      "runtime_mode_override": "turn_driven"
    }
  ]
}

​

ConsoleUiConfig

title = "Ops"

[brand]
label = "Ops Console"
logo_url = "/assets/ops.svg"
logo_alt = "Ops"

[appearance]
default_theme = "dark"
default_variant = "graphite"

[environment]
label = "prod"

[layout]
initial_preset = "two_columns"
initial_control = "roster"
initial_agent = "identity:ops-lead"
sidebar_collapsed = false

[rail]
visible = true
collapsed = false
active_preset_id = "critical"
empty_text = "No meaningful signals yet."

[[rail.filter_presets]]
id = "critical"
label = "Critical"
watched_only = true
alert_levels = ["critical"]

[sidebar]
visible_controls = ["topology", "roster", "logs", "health"]
hidden_controls = []

[[sidebar.buttons]]
id = "ops-board"
label = "Ops Board"
href = "https://example.test/ops"
target = "_blank"
icon_name = "external-link"

[agent_list]
group_by = ["labels.console_group", "labels.group", "role"]
subgroup_by = ["labels.org", "labels.realm"]
section_order = ["Personal", "Initiatives", "Internal"]
fallback_group = "Agents"
fallback_subgroup = "Other"
default_pinned_agent_ids = ["identity:ops-lead"]
collapse_single_subgroup = true

[[agent_list.badges]]
id = "org"
label = "Org"
field = "labels.org"
tone = "info"

[[agent_list.sections]]
name = "Initiatives"
collapsed = false
empty_title = "No initiatives"
empty_text = "Create one in Linear."

[[attention.sources]]
id = "host-items"
label = "Host"
url = "/host/attention"
decide_href = "/host/decide?decision={decision_id}"

[actions]
inspect_label = "Profile"
chat_label = "Open chat"
send_label = "Send to agent"
respawn_label = "Respawn"
retire_label = "Retire"
reset_label = "Reset"
show_reset = false

[realms.ops]
title = "Ops"

[realms.ops.agent_list]
subgroup_by = ["labels.org"]

​

Host-provided attention items

{"items": [{"id": "a1", "title": "Confirm a setting",
            "details": [{"label": "For", "value": "plugin:example"}],
            "href": "/host/items/a1", "tone": "attention"}]}

• id, title and href are required. href must be a same-origin path like url; an item with any other href is dropped.
• details is optional, at most 12 label/value pairs. tone is optional: attention, info, warning or critical.
• Text is trimmed and cut at 300 characters, and the console keeps at most 50 items per source.
• A source that does not answer within 10 seconds, or whose answer is larger than 256 KiB, fails alone. A slow source delays the other sources’ items by at most those 10 seconds.

​

AuthPolicy

AuthPolicy {
    default_provider: AuthProvider,
    email_allowlist: Vec<String>,
}

​

AuthProvider

enum AuthProvider {
    GoogleOAuth,
    GitHubOAuth,
    GenericOidc,
    ServiceIdentity,
    TestProvider,
}

​

ConsolePolicy

ConsolePolicy {
    require_app_auth: bool,
    read_only: bool,
    fetch_timeout_ms: Option<u64>,
    ui: ConsoleUiConfig,
}

​

Console auth by surface

​

RuntimeOpsPolicy

RuntimeOpsPolicy {
    replica_count: u16,
    metrics: MetricsPolicy,
}

​

LocalJsonMemoryBackendConfig

LocalJsonMemoryBackendConfig {
    state_path: String,
    health_check_endpoint: Option<String>,
}

​

Agent memory injection

​

BigQueryNaming

BigQueryNaming {
    dataset: String,
    table: String,
}

​

ReleaseMetadata

ReleaseMetadata {
    targets: Vec<String>,
    support_matrix: String,
}

​

Trust manifest (meta.toml)

[[modules]]
id = "router"
command = "meerkat-router"
args = ["--port", "9001"]
restart_policy = "on_failure"

[[modules]]
id = "delivery"
command = "meerkat-delivery"

​

Constants

​

See also

• Modules — module configuration in context
• Authentication — auth policy usage
• Sessions — session store configuration