Skip to main content
Mobs are Meerkat’s multi-agent runtime. There is no separate sub-agent substrate: delegation, helper agents, flows, and reusable profiles all compile to mob members managed by meerkat-mob.

​
Core Model

MobActor serializes mob commands, persists mob state, and projects public status from MobMachine authority. Member sessions are still ordinary Meerkat sessions, so they inherit provider, tool, auth, memory, and live-channel behavior from the session runtime.

​
Identity

Mob member identity has two layers:
IdentityMeaning
AgentIdentityStable member identity. Public mob APIs, wiring, delegation, status, and profiles use this.
AgentRuntimeIdRuntime binding identity. It can rotate on respawn or binding replacement.
FenceTokenMonotonic binding epoch used to reject stale runtime effects.
GenerationMember generation counter, incremented on respawn.
Use AgentIdentity for facts that survive respawn. Use AgentRuntimeId only for per-binding runtime facts.

​
Runtime Bindings

Members can run as local session-backed agents or as external peers.
BindingContract
RuntimeBinding::SessionMeerkat provisions and owns a local session for the member.
RuntimeBinding::ExternalThe host declares the external runtime address, Ed25519 public identity, and typed bootstrap token. The mob derives the real peer id and routes through that runtime.
External members require an explicit runtime binding. A bare External backend tag is not enough because the runtime needs a concrete process identity before it can route work or trust peer messages. For a remote rkat member, generate the current binding with rkat run --comms-listen-tcp ... --comms-binding-out <path>.

​
Public Surfaces

SurfaceMob role
CLI rkat mob ...Helper, artifact, typed callable run, and run-resource commands: run, runs, status, logs, attach, flow execution, pack, deploy, web build.
JSON-RPC mob/*Host control plane for mob lifecycle, members, flows, and profiles.
RESTHTTP adapter for selected mob helper workflows.
MCP meerkat_mob_*Public MCP control plane.
Agent tools mob_* / delegateAgent-facing delegation and session-owned implicit mobs.
Python / TypeScript SDKsTyped wrappers over the RPC mob surface.
Web SDKIn-browser mob runtime and mobpack deployment target.

​
Flows

Flows are declarative work graphs. They support one-to-one, fan-out, fan-in, branching, and frame/loop nodes. Flow status is persisted, so a host can check live state first and fall back to the terminal snapshot.

​
Persistence

Persistent mob state is SQLite/WAL-backed through SqliteMobStores. In-memory storage is used for tests and WASM. The previous exclusive-handle mob store is gone. Mobpacks are portable mob artifacts. They package definitions and trust policy material for deployment through: 
rkat mob pack ./mob -o ./dist/mob.mobpack
rkat mob inspect ./dist/mob.mobpack
rkat mob validate ./dist/mob.mobpack
rkat mob run ./dist/mob.mobpack --prompt "run this mob"
rkat mob web build ./dist/mob.mobpack -o ./dist/web --wasm ./path/to/runtime_bg.wasm

​
Live Channels

Live channels are per session. For a mob member, open live/open against that member’s session using a realtime-capable model such as gpt-realtime-2. The old realtime attachment/status plane has been removed. Live channel lifecycle is caller-initiated through the live/* method family.

​
Source Pointers

AreaSource
Mob actormeerkat-mob/src/runtime/actor.rs
Mob handlemeerkat-mob/src/runtime/handle.rs
Member identitymeerkat-mob/src/ids.rs
Storagemeerkat-mob/src/store/
Agent-facing toolsmeerkat-mob-mcp/src/agent_tools.rs
Supervisor bridgemeerkat-mob/src/runtime/supervisor_bridge.rs
Mobpackmeerkat-mob-pack/

​
See Also