Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt

Use this file to discover all available pages before exploring further.

Meerkat is a library-first agent runtime with one execution pipeline and multiple host surfaces. The CLI, REST server, JSON-RPC server, MCP server, Rust facade, Python SDK, TypeScript SDK, and Web/WASM runtime all converge on the same session, provider, tool, and transcript model. The architecture is strict about ownership: runtime-backed surfaces route through MeerkatMachine, multi-agent work routes through MobMachine, auth and scheduling use their own authority machines, and the agent loop itself stays a provider-neutral library primitive.

​
System Map

​
Public Surfaces

SurfaceRole
rkatCLI for local runs, session resume, model/auth/config management, blobs, MCP config, and mob helper/artifact workflows.
rkat-rpcJSON-RPC 2.0 over stdio or TCP. This is the primary programmatic server and SDK backend.
rkat-restHTTP/JSON plus SSE for services that prefer REST-style integration.
rkat-mcpMeerkat exposed as Model Context Protocol tools.
Rust crate meerkatEmbeddable facade around factory, provider, session, and optional runtime features.
Python SDK meerkatAsync JSON-RPC client.
TypeScript SDK @rkat/sdkTypeScript JSON-RPC client.
Web SDK @rkat/webBrowser/WASM runtime, JS tool callbacks, external auth resolver, and mobpack target.
Reduced distributions are source builds of the same crates with narrower Cargo feature sets, not separate public binaries.

​
Core Runtime Pieces

PieceOwnerResponsibility
Agent loopmeerkat-coreProvider-neutral turn loop, messages, tool calls, streaming assembly, errors, and trait contracts.
FactorymeerkatBuilds an agent from config, provider registry, tools, stores, skills, hooks, memory, and runtime bindings.
Session servicemeerkat-sessionCreate, resume, run, stream, interrupt, list, and archive sessions.
Runtime kernelmeerkat-runtimeMeerkatMachine, runtime stores, session registration, input admission, completion wakeups, runtime bindings, auth handles.
Mob runtimemeerkat-mobMobs, member lifecycle, flows, wiring, supervisor bridge, and mob storage.
Live channelsmeerkat-live + meerkat-openaiLive channel host, transport bootstrap, and provider adapter.
Wire contractsmeerkat-contractsJSON-RPC, REST, and SDK-facing wire types plus generated schemas.
Provider adaptersmeerkat-anthropic, meerkat-openai, meerkat-geminiProvider-specific request lowering, streaming, auth, model capabilities, images, and live support.

​
Machine Authority

The canonical machine catalog contains six machines:
  • MeerkatMachine
  • MobMachine
  • AuthMachine
  • ScheduleLifecycleMachine
  • OccurrenceLifecycleMachine
  • WorkGraphLifecycleMachine
The catalog also contains five canonical compositions:
  • meerkat_mob_seam
  • auth_lease_bundle
  • schedule_bundle
  • schedule_runtime_bundle
  • schedule_mob_bundle
The short rule is: if a state transition has semantic meaning, it needs one owner. Generated machine artifacts, specs, and drift checks keep that ownership aligned with production Rust code.

​
Realm And Persistence Model

realm_id is the sharing key across surfaces. A realm contains sessions, config, auth bindings, schedules, blobs, and mob state. CLI commands default to a workspace-derived realm; servers and SDKs can create an opaque realm or use an explicit one. When SQLite support is compiled, new persistent realms default to SQLite. JSONL remains available as an explicit inspectable backend. WASM and tests use in-memory state unless the embedding supplies a store.

​
Provider Model

Provider selection is model-profile driven. Meerkat does not infer semantic capabilities from model name substrings. Capability flags such as realtime, structured output, compaction, web search, image generation, and media support come from the catalog and provider-owned profiles. Auth is realm/binding scoped. Environment keys are still supported as a bootstrap path, but long-lived provider access should go through auth bindings and the auth lease path.

​
Orchestration Model

Mobs are the multi-agent runtime path. A delegated helper, a forked worker, a flow step, and a reusable profile-backed member are all mob members. Stable public identity is AgentIdentity; per-runtime binding identity is AgentRuntimeId, fenced by FenceToken and generation. Agent-facing delegate and mob_* tools are separate from host control planes. Host apps use typed mob/* JSON-RPC methods, REST helper endpoints, MCP meerkat_mob_* tools, or SDK wrappers.

​
Live Channels

Live audio/text is exposed through JSON-RPC live/* methods. Start rkat-rpc with --live-ws <addr> when a channel needs WebSocket transport bootstrap. ModelCapabilities.realtime gates live/open. The current catalog realtime row is OpenAI gpt-realtime-2.

​
Reading Order

Runtime Architecture

How sessions enter the runtime and reach the agent loop.

Machine Authority

The canonical machine catalog, generated artifacts, and verification gates.

Mob Architecture

Multi-agent orchestration, identity, runtime bindings, flows, and mobpacks.