Quickstart

Install

brew install lukacf/meerkat/rkat

The tap supports macOS and Linux. Release archives also contain rkat, rkat-rpc, rkat-rest, and rkat-mcp.

pip install meerkat-sdk

The SDK resolves and can download a compatible rkat-rpc by default.

npm install @rkat/sdk

The SDK resolves and can download a compatible rkat-rpc by default.

npm install @rkat/web

The web package runs Meerkat in the browser rather than spawning rkat-rpc. Continue with the Web/WASM example.

Meerkat is pre-1.0, so exactly pin the crate family and bump deliberately:

[dependencies]
meerkat = { version = "=0.8.42", features = ["sqlite-store", "session-store"] }
meerkat-store = "=0.8.42"
meerkat-tools = "=0.8.42"
tokio = { version = "1", features = ["full"] }

Start with the Rust SDK overview for runtime-backed SessionService construction.

cargo install rkat

Configure One Provider

The fastest path is a dedicated Meerkat environment variable:

export RKAT_OPENAI_API_KEY="sk-..."

export RKAT_ANTHROPIC_API_KEY="sk-ant-..."

export RKAT_GEMINI_API_KEY="AIza..."

Provider-native names also work. For OAuth, Azure, cloud IAM, managed-store credentials, and tenant-scoped bindings, see Auth.

Meerkat’s OpenAI/global catalog default is gpt-6-astra. Explicit model and binding defaults are preserved. Catalog support does not guarantee API access or support through Azure, Copilot, or custom backends. Select an available model explicitly or configure a binding default_model when needed.

Run A First Session

CLI
Python
TypeScript

With the OpenAI variable above:

rkat run "What is the capital of France? Answer in one sentence."

With another provider, select a matching model:

rkat run --model claude-sonnet-4-6 "Explain async/await"
rkat run --model gemini-3.8-flash "Explain async/await"

import asyncio
from meerkat import MeerkatClient


async def main():
    async with MeerkatClient() as client:
        session = await client.create_session(
            "What is the capital of France? Answer in one sentence."
        )
        print(session.text)


asyncio.run(main())

import { MeerkatClient } from "@rkat/sdk";

const client = new MeerkatClient();
await client.connect();
const session = await client.createSession(
  "What is the capital of France? Answer in one sentence.",
);
console.log(session.text);
await client.close();

The SDKs connect to rkat-rpc; the CLI constructs the same runtime-backed session in-process. CLI commands derive a stable workspace realm by default. A bare RPC/REST/MCP server or SDK connection creates a fresh isolated realm. Pass one explicit ID when several processes should see the same sessions and config:

rkat --state-root /srv/meerkat/realms --realm team-alpha run "Draft a release note"
rkat-rpc --state-root /srv/meerkat/realms --realm team-alpha

import asyncio
from meerkat import MeerkatClient


async def main():
    client = MeerkatClient()
    try:
        await client.connect(realm_id="team-alpha", state_root="/srv/meerkat/realms")
        session = await client.create_session("Draft a release note")
        print(session.text)
    finally:
        await client.close()


asyncio.run(main())

const client = new MeerkatClient();
await client.connect({
  realmId: "team-alpha",
  stateRoot: "/srv/meerkat/realms",
});

The processes must also resolve the same physical storage root/provider. See Realms.

Add An MCP Server

rkat mcp add filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem /tmp
rkat run --wait-for-mcp "List the files in /tmp"

Config changes apply to newly built/resumed agents. MCP servers normally connect in the background and tools appear as each server becomes ready; --wait-for-mcp makes the first prompt wait for configured servers. For a remote streamable-HTTP server (replace the example URL with the service you use):

rkat mcp add --transport http knowledge https://mcp.example.com
rkat mcp login knowledge
rkat run --wait-for-mcp "Search the knowledge base for onboarding docs"

Bound One Run

rkat run \
  --max-tokens 4000 \
  --max-duration 30s \
  --max-tool-calls 5 \
  "Inspect this project and summarize the main risks"

--max-tokens caps LLM output per turn.
--max-tool-calls bounds tool use for the run.
--max-duration bounds the run’s agent lifetime; a deadline is a hard terminal failure rather than a warning.

For aggregate turn deadlines, lifetime token budgets, retry policy, and admission limits, use realm configuration.

Add Built-In Capabilities

The full preset enables the product CLI’s broad tool composition, including shell, MCP, skills, comms, schedules, WorkGraph, and mob orchestration where compiled:

rkat run --tools full \
  "Create a small mob to inspect src/, collect the findings, and summarize them."

Use --allow-tool and --block-tool for a narrower first-turn scope. Shell access and other effectful tools should be granted deliberately.

Next Steps

Examples gallery - choose a maintained workflow
Sessions example - continue a multi-turn conversation
Auth - configure bindings and OAuth
Providers - inspect models and parameters
Rust SDK - embed runtime-backed sessions
Python SDK - build from Python
TypeScript SDK - build from Node.js
Web/WASM - run in the browser

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

Install

Configure One Provider

Run A First Session

Add An MCP Server

Bound One Run

Add Built-In Capabilities

Next Steps

​Install

​Configure One Provider

​Run A First Session

​Share State Across Surfaces

​Add An MCP Server

​Bound One Run

​Add Built-In Capabilities

​Next Steps

Install

Configure One Provider

Run A First Session

Share State Across Surfaces

Add An MCP Server

Bound One Run

Add Built-In Capabilities

Next Steps