Quickstart

This page documents MobKit v0.8.34 (mirrored from v0.8.34).

Install

Rust crate
TypeScript
Python

Cargo.toml

[dependencies]
meerkat-mobkit = "0.8.34"
tokio = { version = "1", features = ["full"] }

npm install @rkat/mobkit-sdk

pip install meerkat-mobkit

The Python and TypeScript packages are clients and do not bundle a gateway executable. Download mobkit-rpc-gateway-<version>-<target>.tar.gz for Unix or macOS, or mobkit-rpc-gateway-<version>-<target>.zip for Windows, from GitHub Releases and extract its rpc_gateway binary (rpc_gateway.exe on Windows). Linux archives published after v0.8.30 are built against glibc 2.31 (Debian 11) and load on any distribution with glibc 2.31 or newer; the v0.8.30 Linux archives were built on Ubuntu 24.04 and need glibc 2.39. For a source build, run ./scripts/repo-cargo build -p meerkat-mobkit --bin rpc_gateway --locked, then run ./scripts/repo-cargo --print-env; the debug binary is at <CARGO_TARGET_DIR>/debug/rpc_gateway. Pass the extracted or built path to .gateway(...).

Bootstrap a runtime

The fastest way to get a running system is start_mobkit_runtime. It takes a module configuration, agent event stream, and a startup timeout. Host-supplied modules are optional, so this runnable baseline starts with an empty module and discovery list.

Rust
TypeScript
Python

use meerkat_mobkit::{
    start_mobkit_runtime, DiscoverySpec, EventEnvelope, MobKitConfig,
    UnifiedEvent,
};
use std::time::Duration;

let config = MobKitConfig {
    modules: vec![],
    discovery: DiscoverySpec {
        namespace: "my-app".to_string(),
        modules: vec![],
    },
    pre_spawn: vec![],
};

let agent_events: Vec<EventEnvelope<UnifiedEvent>> = vec![];
let timeout = Duration::from_secs(30);

let mut runtime = start_mobkit_runtime(config, agent_events, timeout)?;
println!("Loaded modules: {:?}", runtime.loaded_modules());

for event in &runtime.merged_events {
    println!("{} [{}] {:?}", event.event_id, event.source, event.event);
}

import { MobKit } from "@rkat/mobkit-sdk";

const rt = await MobKit.builder()
  .mob("config/mob.toml")
  .persistentState(".mobkit/state")
  .gateway("/path/to/rpc_gateway")
  .build();

const status = await rt.mobHandle().status();
console.log("Runtime status:", status.running);
await rt.shutdown();

from meerkat_mobkit import MobKit

async with await MobKit.builder().gateway("/path/to/rpc_gateway").build() as rt:
    handle = rt.mob_handle()
    status = await handle.status()
    print("Running:", status.running)
    print("Modules:", status.loaded_modules)

Use the unified runtime

For production deployments that combine a Meerkat mob with MobKit modules, use the UnifiedRuntime builder:

use meerkat_mobkit::UnifiedRuntime;

let runtime = UnifiedRuntime::builder()
    .mob_spec(mob_spec)
    .module_config(module_config)
    .timeout(Duration::from_secs(30))
    .build()
    .await?;

The unified runtime bootstraps both systems, merges their event streams, and manages the combined lifecycle. See the unified runtime guide for details.

Open the console

Once the runtime is serving HTTP, open the admin console at:

<http_base_url>/console

The bundled gateways bind an available loopback port and return the exact http_base_url in the initialization result. A library host may choose its own address. The console shows the agent sidebar, conversation workspace, signals rail, topology, logs, and health overview. The bundled app seeds from REST, sends through JSON-RPC, and tails replayable timeline frames over SSE.

Identity-first (household apps)

For apps with durable agent identities (like HomeCore), use the identity-first API:

from meerkat_mobkit import MobKit
from meerkat_mobkit.identity_first_models import DurableAgentSpec, ManagedPeerEdge

# Define your household roster
class MyRoster:
    async def roster(self, context):
        return [
            DurableAgentSpec(identity="identity:luka", profile="personal", addressability="addressable"),
            DurableAgentSpec(identity="triage:main", profile="triage", addressability="internal_only"),
        ]

class MyTopology:
    async def compute_edges(self, target_identities, context):
        return [ManagedPeerEdge(a="identity:luka", b="triage:main")]

# Boot the runtime
rt = await (
    MobKit.builder()
    .mob_inline(MOB_TOML)
    .persistent_state("./state")
    .roster(MyRoster())
    .topology_provider(MyTopology())
    .gateway("./rpc_gateway")
    .build()
)

# Use identity-scoped handles
triage = rt.agent("triage:main")
luka = rt.agent("identity:luka")

# send_and_wait / dispatch_and_wait wait on the turn's completion cursor.
# Never wait by comparing output text: an agent may answer the same thing
# twice, and a text comparison then reports "nothing happened" until timeout.
output = await triage.dispatch_text_and_wait(
    "New event from connector", origin="connector", timeout=60,
)

await luka.send_and_wait("What's happening today?", timeout=60)

Profiles are templates; members are declared. The [profiles.*] tables in MOB_TOML produce no members on their own: the identities your roster returns (or ensure_member names) are the only members that exist, and nothing spawns one member per profile for you. The roster callback’s context argument is empty on both SDKs (the gateway sends the definition, the SDK dispatchers do not pass it through), so a profile-shaped crew is one loop over the [profiles.*] of your own parsed MOB_TOML; see Profiles are templates. If the definition declares [wiring] (auto_wire_orchestrator or role_wiring), call rt.mob_handle().reconcile_edges() after boot and after each rt.reconcile(); ensure_member reconciles on its own. Pin runtime_mode = "turn_driven" on profiles that back addressable identities: meerkat defaults to autonomous_host, which runs a kickoff turn at spawn and cannot receive ambient per-turn memory (see Runtime modes).

Use respawn() for non-destructive recovery that keeps continuity, and reset() only when the app intentionally wants a destructive new generation and session. If you change a durable identity’s role in the roster, its resume fails closed until that boot declares the migration with .role_migrations([...]). See the Python SDK page for the builder form and Configuration for the init parameter.

What’s next

Modules — how the module system works
Events — the unified event model
Operational subsystems - gating, delivery, durable scheduling, memory
Architecture — internal design and crate structure

Getting started

Core concepts

Guides

Install

Bootstrap a runtime

Use the unified runtime

Open the console

Identity-first (household apps)

What’s next

​Install

​Bootstrap a runtime

​Use the unified runtime

​Open the console

​Identity-first (household apps)

​What’s next

Install

Bootstrap a runtime

Use the unified runtime

Open the console

Identity-first (household apps)

What’s next