Skip to main content
A mob is Meerkat’s durable multi-agent unit. It turns several agent sessions into a coordinated team with stable member identities, role profiles, peer wiring, shared lifecycle events, and optional flows.

​
Why Mobs Exist

Single sessions are excellent for linear work. Mobs are for work that benefits from separate participants:
  • one lead plus several analysts
  • independent reviewers that compare findings
  • long-lived helper pools
  • incident rooms with specialized roles
  • browser-deployed teams packaged as mobpacks
Meerkat does not maintain a separate “sub-agent” substrate. Delegation and multi-agent orchestration compile to mob members.

​
The Objects

​
Stable Identity

Public mob APIs use AgentIdentity. Runtime bindings can rotate when a member respawns, moves, or reconnects, but the member’s public identity remains the key for status, wiring, work, and events.
This is why callers wire lead-1 to analyst-1 instead of wiring internal session IDs. A role or profile is not the member’s durable identity. A trusted Rust host can resume one cold durable session under a new role only by declaring the exact predecessor role on that one Resume request. The mob id and AgentIdentity stay fixed. An absent or incorrect declaration fails closed, and the declaration is never stored as permission for later resumes.

​
Host Vs Agent Surfaces

Mobs deliberately expose two kinds of interfaces: Agent tools let an agent create or coordinate helpers while it is working. Host APIs let applications create, supervise, inspect, and drive teams directly. Some authority-sensitive operations are intentionally narrower: host binding, grants, and member live control are operator surfaces. Among public transport APIs, hard cancel is limited to JSON-RPC and its Python/TypeScript SDK wrappers as mob/hard_cancel_member; trusted in-process MobHandle callers also have that authority through hard_cancel_member. One-shot role migration is a trusted Rust-host and internal member-host materialization contract, not an agent, CLI, REST, public MCP, or SDK spawn field.

​
Local And Placed Members

The controlling host owns mob identity, roster, topology, placement, routing obligations, grants, merged observation, and teardown. A bound member host owns the realm-local session execution, transcript, credentials, compaction, and memory of members placed there. Realms are not distributed. Placement is transparent to member identity and ordinary work APIs. Operators use mob/hosts, mob/route_installs, and mob/member_history to distinguish host reachability, route convergence, and remote session history when they need the underlying evidence. A placed member’s raw session id belongs to the member host’s realm. The controller’s generic session/* APIs cannot read or mutate it. Use identity-routed mob operations and mob/member_history; remote transcript revision and edit APIs are not bridged in v1.

​
Runtime Modes

autonomous_host is the default when a member’s runtime mode is omitted. The member behaves like a long-lived peer and receives work through the mob runtime. turn_driven is explicit. Use it when the host wants tighter control over when the member starts turns.

​
Flows And Work

Flows are repeatable workflows over members. Work lanes are tracked, cancellable pieces of work sent to a mob or member. Use a flow when the workflow itself is reusable; use work submission when an application needs a handle for one unit of work.

​
Portability

Mobpacks package a mob definition and optional assets into a .mobpack file. They are the portable deployment shape for signed teams, repeatable CLI/service deployment, and browser-target builds.

​
See Also

Mobs guide

Build, spawn, wire, run flows, observe, and troubleshoot mobs.

Mob architecture

Runtime ownership, identity, persistence, and flow internals.

Mobpack

Package and deploy portable mob artifacts.