Mobs

Mobs are Meerkat’s multi-agent runtime. A mob is a durable team of agent members with stable identities, profile-driven behavior, peer wiring, optional flows, and host-visible lifecycle state. Use mobs when one session is no longer the right unit of work: release triage teams, code review panels, research teams, incident rooms, long-running helper pools, and browser-deployed mobpacks all use the same underlying mob runtime.

Mobs are the multi-agent path in Meerkat. The agent-facing delegate tool, explicit mob_* tools, SDK Mob classes, mob/* RPC methods, public MCP mob tools, and mobpack deployment all route through the mob system.

Choose A Path

Need	Use
One quick helper from an agent prompt	`delegate` inside `rkat run --tools full`
A persistent team the agent can manage	agent-side `mob_create`, `mob_spawn_member`, `mob_wire`, `mob_check_member`
An app or service orchestrating members directly	host APIs: JSON-RPC `mob/`, public MCP `meerkat_mob_`, Python `Mob`, TypeScript `Mob`
A browser-deployed team	Web SDK `@rkat/web` with `MeerkatRuntime.createMob`, or `rkat mob web build` from a mobpack
A repeatable workflow across members	mob flows
A signed, portable team definition	mobpack

Mental Model

A MobDefinition describes profiles, limits, wiring rules, topology, and flows. The running mob records the roster, member lifecycle, events, flow runs, and work state. Each member is an agent session, but public mob APIs address the member by stable AgentIdentity, not by an internal session or runtime binding.

Core Concepts

Concept	Meaning
Mob	Durable orchestration aggregate: definition, members, events, flows, lifecycle
Profile	Role template: model, tool posture, skills, runtime mode, peer description
Member	One spawned participant with a stable `AgentIdentity`
Wiring	Directed peer visibility between members
Runtime mode	`autonomous_host` by default, `turn_driven` when explicit control is needed
Flow	Declarative workflow that dispatches steps to members
Work lane	Cancellable tracked work submitted to a mob or member
Mobpack	Portable signed artifact containing a mob definition and optional assets

Agent Tools Vs Host APIs

Keep this distinction sharp:

Surface	Caller	Names	Purpose
Agent-side tools	The model inside a session	`delegate`, `mob_create`, `mob_spawn_member`, `mob_wire`, `mob_check_member`	Let an agent create helpers and coordinate its own team
Host APIs	Your application, CLI, SDK, or service	`mob/create`, `mob/spawn`, `mob/flow_run`, SDK `Mob` methods	Let software create, inspect, drive, and supervise mobs
Public MCP tools	External MCP clients	`meerkat_mob_*`	Expose the typed host control plane through MCP

Agent-side tools are late-bound through the session build path. Host APIs are the stable control plane for applications and SDKs. Do not treat raw mob_* agent tools as if they were JSON-RPC methods.

Fast Path: Delegate

delegate creates an implicit session-owned mob on first use, spawns a helper, and wires the helper to the creating session. Use it for bounded helper work that should report back.

rkat run --tools full "Ask one helper to inspect the test failure, then summarize what it found."

For recurring teams, use explicit mobs instead of a chain of ad hoc delegates.

Define A Mob

A small mob definition has profiles and optional wiring:

{
  "id": "release-triage",
  "orchestrator": { "profile": "lead" },
  "profiles": {
    "lead": {
      "model": "claude-opus-4-8",
      "peer_description": "Coordinates triage and assigns work",
      "tools": {
        "builtins": true,
        "comms": true,
        "mob": true
      }
    },
    "analyst": {
      "model": "claude-sonnet-4-6",
      "peer_description": "Investigates one issue and reports evidence",
      "tools": {
        "builtins": true,
        "comms": true
      }
    }
  },
  "wiring": {
    "auto_wire_orchestrator": true,
    "role_wiring": [
      { "a": "lead", "b": "analyst" }
    ]
  },
  "limits": {
    "max_flow_duration_ms": 600000,
    "max_step_retries": 1
  }
}

Profiles are role contracts. Spawn requests may override selected profile fields, but the definition remains the durable source for the mob’s intended shape.

Profile model and provider fields

Beyond model, a profile can pin provider identity and per-member behavior:

[profiles.lead]
model = "claude-internal-preview"
# Explicit typed provider (closed vocabulary: anthropic | openai | gemini |
# self_hosted | other). Required for uncatalogued model ids; rejected at load
# if it contradicts a catalogued model's owner.
provider = "anthropic"
# Durable self-hosted binding (with provider = "self_hosted" and a
# [self_hosted.models] entry in the host config).
# self_hosted_server_id = "local"
# Default provider for `Auto` image-generation targets (profile-level wins
# over the mob-level default below).
image_generation_provider = "gemini"
# Per-profile auto-compaction threshold in tokens (non-zero; wins over the
# global config knob and model-aware context-window scaling).
auto_compact_threshold = 60000
# Profile fields that win over durable session metadata when a member
# resumes. Without this, editing `model` in the definition does NOT apply to
# resumed durable sessions. Vocabulary: model | provider | provider_params.
resume_overrides = ["model", "provider"]

Custom model registry entries

[models.<id>] tables declare uncatalogued models once, at the definition level. One entry feeds provider inference, compaction scaling, capability gates, and call timeouts for every profile that references the model:

# Mob-level default for `Auto` image-generation targets (top-level key).
image_generation_provider = "gemini"

[models.claude-internal-preview]
provider = "anthropic"          # required; concrete API provider only
display_name = "Claude Internal Preview"
context_window = 500000          # drives compaction scaling
max_output_tokens = 16384
vision = true                    # capability flags default to false
web_search = false
call_timeout_secs = 900

[profiles.lead]
model = "claude-internal-preview"

The same [models.<id>] table shape works in the host’s config.toml under [models], next to the per-provider default model strings. At load time, rkat mob validate rejects a profile model that is neither catalogued, custom-defined under [models.<id>], nor provider-annotated (unknown_model), instead of failing at the member’s first delivery.

Mobs do not use prefabs or templates. Create mobs from MobDefinition directly, or package that definition as a mobpack.

Create And Spawn

JSON-RPC
Python
TypeScript
Web SDK
CLI

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "mob/create",
  "params": {
    "definition": {
      "id": "release-triage",
      "profiles": {
        "lead": { "model": "claude-opus-4-8" },
        "analyst": { "model": "claude-sonnet-4-6" }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "mob/spawn_many",
  "params": {
    "mob_id": "release-triage",
    "specs": [
      { "profile": "lead", "agent_identity": "lead-1" },
      { "profile": "analyst", "agent_identity": "analyst-1" },
      { "profile": "analyst", "agent_identity": "analyst-2", "runtime_mode": "turn_driven" }
    ]
  }
}

mob = await client.create_mob(
    definition={
        "id": "release-triage",
        "profiles": {
            "lead": {"model": "claude-opus-4-8"},
            "analyst": {"model": "claude-sonnet-4-6"},
        },
    }
)

await mob.spawn(profile="lead", agent_identity="lead-1")
await mob.spawn_many([
    {"profile": "analyst", "agent_identity": "analyst-1"},
    {"profile": "analyst", "agent_identity": "analyst-2", "runtime_mode": "turn_driven"},
])

const mob = await client.createMob({
  definition: {
    id: "release-triage",
    profiles: {
      lead: { model: "claude-opus-4-8" },
      analyst: { model: "claude-sonnet-4-6" },
    },
  },
});

await mob.spawn({ profile: "lead", agentIdentity: "lead-1" });
await mob.spawnMany([
  { profile: "analyst", agentIdentity: "analyst-1" },
  { profile: "analyst", agentIdentity: "analyst-2", runtimeMode: "turn_driven" },
]);

import { MeerkatRuntime } from "@rkat/web";
import * as wasm from "@rkat/web/wasm/meerkat_web_runtime.js";

const runtime = await MeerkatRuntime.init(wasm, {
  model: "gpt-5.5",
  openaiApiKey: "proxy",
  openaiBaseUrl: "http://localhost:3100/openai",
});

const mob = await runtime.createMob({
  id: "release-triage",
  profiles: {
    lead: { model: "gpt-5.5" },
    analyst: { model: "gpt-5.4-mini" },
  },
});

const members = await mob.spawn([
  { profile: "lead", agent_identity: "lead-1" },
  { profile: "analyst", agent_identity: "analyst-1" },
  { profile: "analyst", agent_identity: "analyst-2", runtime_mode: "turn_driven" },
]);

rkat run --tools full "Create a release-triage mob with a lead and two analysts, then report member status."
rkat mob spawn-helper release-triage "Investigate the latest failing check" --agent-identity analyst-3 --profile analyst --json
rkat mob wait-kickoff release-triage --timeout-ms 30000 --json

Spawn defaults matter:

Field	Default
`runtime_mode`	`autonomous_host`
`launch_mode`	fresh member
`tool_access_policy`	inherit
`auto_wire_parent`	surface-dependent helper behavior

Autonomous members run as long-lived peers. turn_driven members are useful when a host wants explicit dispatch control.

Identity And Respawn

Mobs separate stable member identity from runtime binding details:

Identity	Scope
`AgentIdentity`	Stable public member key; use this in APIs, wiring, status, work, and events
`AgentRuntimeId`	Current runtime binding; rotates when a member respawns
`FenceToken`	Monotonic stale-write guard for runtime binding effects
`Generation`	Member generation counter after respawn

Use AgentIdentity for facts that survive respawn, such as wiring and durable configuration. Runtime IDs and fence tokens protect the lower-level binding.

Wire Peers

Wiring controls which members can see and message each other.

JSON-RPC
Python
TypeScript

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "mob/wire",
  "params": {
    "mob_id": "release-triage",
    "agent_identity": "lead-1",
    "peer": "analyst-1"
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "mob/unwire",
  "params": {
    "mob_id": "release-triage",
    "agent_identity": "lead-1",
    "peer": "analyst-1"
  }
}

await mob.wire("lead-1", "analyst-1")
await mob.unwire("lead-1", "analyst-1")

await mob.wire("lead-1", "analyst-1");
await mob.unwire("lead-1", "analyst-1");

Topology rules can reject wiring or dispatch that violates the definition. Use strict topology when roles must not communicate outside an approved graph.

Send Work

Use member send for direct content delivery. Use the work lane when the caller needs a tracked, cancellable work reference.

Member send
Tracked work

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "mob/member_send",
  "params": {
    "mob_id": "release-triage",
    "agent_identity": "lead-1",
    "content": "Decompose the task and assign work to the analysts.",
    "handling_mode": "queue"
  }
}

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "mob/submit_work",
  "params": {
    "member_ref": "member_ref_from_spawn_or_members",
    "content": "Inspect the failing release check and return evidence.",
    "origin": "external"
  }
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "mob/cancel_work",
  "params": {
    "mob_id": "release-triage",
    "work_ref": "work_123"
  }
}

member_ref is an opaque handle returned by spawn, member list, member send, helper spawn, fork, and respawn responses. Application code should pass it back to work-lane APIs as-is instead of constructing it from mob_id and agent_identity.

Flows

Flows are declarative mob workflows. They let a host dispatch repeatable work without hard-coding all member turns in application code. The classic flow shape is a flat DAG: steps declare roles, messages, dependencies, fan-out/fan-in behavior, optional conditions, and tool overlays. Frame-based flows add nested FlowSpec.root frames and repeat_until loops. Both are owned by the mob runtime; support modules such as flow-run projection are not separate public machines.

{
  "flows": {
    "triage": {
      "steps": {
        "scan": {
          "role": "lead",
          "message": "Review the incident queue and pick the top issue."
        },
        "investigate": {
          "role": "analyst",
          "message": "Investigate the selected issue and return evidence.",
          "depends_on": ["scan"],
          "dispatch_mode": "fan_out"
        },
        "summarize": {
          "role": "lead",
          "message": "Summarize findings and recommend next action.",
          "depends_on": ["investigate"],
          "dispatch_mode": "fan_in"
        }
      }
    }
  }
}

Run and inspect a flow:

JSON-RPC
Python
TypeScript
CLI

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "mob/flow_run",
  "params": {
    "mob_id": "release-triage",
    "flow_id": "triage",
    "params": { "severity": "critical" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "mob/flow_status",
  "params": {
    "mob_id": "release-triage",
    "run_id": "flow_run_123"
  }
}

run_id = await mob.run_flow("triage", {"severity": "critical"})
status = await mob.flow_status(run_id)
result = await mob.run_result(run_id)

const runId = await mob.runFlow("triage", { severity: "critical" });
const status = await mob.flowStatus(runId);
const result = await mob.runResult(runId);

rkat mob run release-triage --flow triage --param severity='"critical"'
rkat mob status release-triage <RUN_ID>

Observe And Operate

Task	Methods
List and inspect mobs	`mob/list`, `mob/status`, `mob/snapshot`
Inspect roster	`mob/members`, `mob/member_status`, `mob/list_members_matching`
Watch events	`mob/events`, SDK event subscriptions
Manage lifecycle	`mob/lifecycle`, `mob/retire`, `mob/respawn`, `mob/destroy`
Manage flows	`mob/flows`, `mob/flow_run`, `mob/flow_status`, `mob/flow_cancel`
Manage work	`mob/submit_work`, `mob/conclude_objective`, `mob/cancel_work`, `mob/cancel_all_work`
Wait for startup	`mob/wait_kickoff`, `mob/wait_ready`
Manage profiles	`mob/profile/create`, `mob/profile/get`, `mob/profile/list`, `mob/profile/update`, `mob/profile/delete`

The event log is append-only. For UI and service loops, prefer event cursors or SDK subscriptions over repeated full snapshots. rkat mob force-cancel <MOB_ID> <AGENT_IDENTITY> (RPC mob/force_cancel) cooperatively cancels a member’s in-flight turn without retiring it — the member stays in the roster and can take new turns. As the operator remedy for a wedged member it is legal whenever the mob is running and idempotent: cancelling a member whose runtime is no longer live, or one already retiring, converges as a no-op success rather than an admission error. Only an identity the roster has never seen is refused, with a typed MemberNotFound.

Persistence

Persistent mobs use SQLite/WAL-backed storage. In-memory storage is used for tests and WASM/browser-embedded paths. The mob store is realm-scoped in the runtime-backed surfaces, so a process restart can recover mob state, members, events, flow snapshots, and work records.

Supervisor Rotation

mob/rotate_supervisor is a synchronous-looking view over a durable operation. The mob records a stable operation ID and the complete target authority before sending the one-way handoff to any member. Each member fences the old epoch, advances the handoff independently, and exposes a durable pending, completed, or rejected receipt for that operation ID. A caller timeout means only that the terminal receipt was not observed before the deadline. It does not cancel or roll back the member operation; a retry uses the persisted operation ID and resumes observation. See Delivery, Interaction, and Durable Operations for the protocol boundary and recovery semantics.

Multi-Host Placement

Use a member-host daemon when the controlling mob should place and supervise members on another machine. The daemon uses its own restart-stable realm, ideally a dedicated realm or context root; realms are not distributed and do not need to match the controller’s realm. --isolated is rejected because it would select a new throwaway realm on every restart and lose the daemon’s durable member-host state.

# On the member host. The descriptor is mode 0600 and its bootstrap token is
# single-use.
rkat --realm worker-west-host mob host \
  --listen-tcp 0.0.0.0:4300 \
  --advertise-tcp tcp://worker-west.example.com:4300 \
  --allow-remote \
  --descriptor-out ./worker-west.host.json

# On the controlling host.
rkat --realm team-alpha mob bind-host release-triage \
  --descriptor ./worker-west.host.json
rkat --realm team-alpha mob hosts release-triage --json

Mixed local/placed edges also need a reverse lane on the controlling process, so member hosts can deliver to members that remain local. Configure this in the controlling realm’s effective configuration:

[mob_host]
listen_tcp = "0.0.0.0:4301"
advertise_tcp = "tcp://controller.example.com:4301"

advertise_tcp must be dialable from every member host. Without an explicit controller endpoint, mixed-host route installation remains pending and fails closed rather than publishing a process-local address. The descriptor handoff above does not require network pairing. If you enable the host’s pairing branch, provide its runtime-only secret through --pairing-password-env <ENV> or --pairing-password-file <PATH> so it stays out of process arguments. These options conflict with each other and with the compatibility-only --pairing-password <PASSWORD> form. The secret is never written to [mob_host] configuration and must be at least 32 bytes. The bind report’s host id is the placement value for mob/spawn and mob/spawn_many. Omitting placement keeps the member local:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "mob/spawn",
  "params": {
    "mob_id": "release-triage",
    "profile": "analyst",
    "agent_identity": "west-analyst-1",
    "placement": "<HOST_ID>"
  }
}

Use mob/hosts, mob/route_installs, and mob/member_history (or the matching CLI commands) for placement diagnostics. Python and TypeScript expose the full typed RPC family. REST and public MCP intentionally expose the three read-only observations, while host binding, grants, hard cancel, and member live control remain outside REST and public MCP. Host binding, grants, and member live control also have explicit CLI verbs; hard cancel is RPC/SDK-only (rkat mob force-cancel is the distinct cooperative boundary cancel). Browser/WASM mobs remain single-host and reject non-local placement through their typed capability boundary. Embedded and explicitly delegated non-owner console principals need control scopes. Stock v1 RPC, REST, stdio, MCP, and CLI entrypoints mint the owning console principal; manage narrower delegated principals with rkat mob grant, rkat mob revoke-grant, and rkat mob grants. Scope denials and host/cursor/fence failures are typed consistently across console surfaces.

External Members

Most members are normal session-backed agents. External members are advanced: they require an external runtime binding with a concrete address and trusted peer identity so the orchestrator can route supervisor bridge traffic to the right process. This binds one already-running external member; for a managed host that can materialize multiple placed members, use the member-host flow above. For a remote rkat process, start it with the signed comms listener and write the binding file:

rkat run \
  --comms-name worker-west-1 \
  --comms-listen-tcp 0.0.0.0:4200 \
  --comms-advertise-tcp worker-west-1.example.com:4200 \
  --comms-binding-out ./worker-west-1.binding.json \
  --keep-alive \
  "You are worker-west-1."

--comms-binding-out writes the current external binding shape: kind: "external", advertised address, Ed25519 public identity, and typed bootstrap_token. Current mob supervisors require that typed bootstrap token for external bridge binding; a bare External backend tag, a raw address, or a query-string-only bootstrap token is rejected. Use external members only when the member must run outside the local Meerkat runtime, such as another host, sandbox, or service process.

Live Channels

Live channels are per session. To use live audio/text or model-gated image input with a mob member, give that member a realtime-capable model such as gpt-realtime-2, spawn the member, then open a live channel against the member’s session through the live/* surface. See Live channels.

Mobpacks

A mobpack packages a mob definition and optional assets into a portable artifact:

rkat mob pack ./mobs/release-triage -o ./dist/release-triage.mobpack
rkat mob inspect ./dist/release-triage.mobpack
rkat mob validate ./dist/release-triage.mobpack --trust-policy permissive
rkat mob run ./dist/release-triage.mobpack --prompt "triage latest release regressions" --trust-policy permissive

Use mobpacks when the mob should be versioned, signed, reviewed, deployed, or bundled for browser deployment. mob web build copies required prebuilt wasm-pack output into that bundle; it does not compile wasm32.

Troubleshooting

Symptom	Check
Helper never replies	Confirm `--tools full` or mob tools are enabled, then inspect `mob_check_member` / `mob/member_status`
`member_already_exists`	Pick a new `agent_identity` or `respawn` the existing member
`profile_not_found`	Confirm the profile name exists in the `MobDefinition` or profile store
`topology_violation`	Check role wiring and topology rules before sending work
External spawn rejected	Verify the external binding includes address and trusted identity
Flow run missing	Use `mob/flows` first and confirm the `flow_id` exists in the definition
Live open fails	Confirm the member’s model has realtime capability and `rkat-rpc --live-ws` is enabled when using RPC audio

Mob architecture

Runtime ownership, member identity, flows, persistence, and live-channel boundaries.

Mobs concept

The conceptual model behind members, profiles, wiring, and host-vs-agent surfaces.

Mobpack

Package, sign, validate, deploy, and build browser-target mob artifacts.

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

Choose A Path

Mental Model

Core Concepts

Agent Tools Vs Host APIs

Fast Path: Delegate

Define A Mob

Profile model and provider fields

Custom model registry entries

Create And Spawn

Identity And Respawn

Wire Peers

Send Work

Flows

Observe And Operate

Persistence

Supervisor Rotation

Multi-Host Placement

External Members

Live Channels

Mobpacks

Troubleshooting

See Also

Mob architecture

Mobs concept

Mobpack

​Choose A Path

​Mental Model

​Core Concepts

​Agent Tools Vs Host APIs

​Fast Path: Delegate

​Define A Mob

​Profile model and provider fields

​Custom model registry entries

​Create And Spawn

​Identity And Respawn

​Wire Peers

​Send Work

​Flows

​Observe And Operate

​Persistence

​Supervisor Rotation

​Multi-Host Placement

​External Members

​Live Channels

​Mobpacks

​Troubleshooting

​See Also

Mob architecture

Mobs concept

Mobpack

Choose A Path

Mental Model

Core Concepts

Agent Tools Vs Host APIs

Fast Path: Delegate

Define A Mob

Profile model and provider fields

Custom model registry entries

Create And Spawn

Identity And Respawn

Wire Peers

Send Work

Flows

Observe And Operate

Persistence

Supervisor Rotation

Multi-Host Placement

External Members

Live Channels

Mobpacks

Troubleshooting

See Also