### Install Dependencies (TypeScript)

Source: https://github.com/lukacf/meerkat/blob/main/examples/README.md

Navigate to the examples directory and install Node.js dependencies using npm.

```bash
cd examples && npm install
```

--------------------------------

### Quick Start

Source: https://github.com/lukacf/meerkat/blob/main/sdks/python/README.md

A basic example demonstrating how to use the MeerkatClient to create a session, interact with it, and archive it.

```APIDOC
## Quick Start

### Description
This example shows the basic usage of the MeerkatClient to create a session, send a query, receive a response, and archive the session.

### Code Example
```python
import asyncio
from meerkat import MeerkatClient

async def main() -> None:
    async with MeerkatClient() as client:
        session = await client.create_session("What is the capital of France?")
        print(session.text)

        result = await session.turn("And Germany?")
        print(result.text)

        await session.archive()

asyncio.run(main())
```
```

--------------------------------

### Complete Meerkat Service Example

Source: https://github.com/lukacf/meerkat/blob/main/docs/rust/advanced.mdx

A full example demonstrating the setup and usage of the Meerkat service. It includes creating a session, starting a turn with a prompt, and reading session details like total tokens. This example is suitable for embedded/testing substrates.

```rust
use meerkat::{AgentFactory, Config, build_ephemeral_service};
use meerkat::{CreateSessionRequest, StartTurnRequest, SessionService};
use meerkat_core::service::InitialTurnPolicy;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::load().await?;
    let factory = AgentFactory::new(std::env::current_dir()?);
    let service = build_ephemeral_service(factory, config, 64); // embedded/testing substrate only

    let result = service.create_session(CreateSessionRequest {
        model: "claude-sonnet-4-6".into(),
        prompt: "What is 25 * 17?".into(),
        render_metadata: None,
        system_prompt: Some("You are a helpful math assistant.".into()),
        max_tokens: Some(2048),
        event_tx: None,
        skill_references: None,
        initial_turn: InitialTurnPolicy::RunImmediately,
        build: None,
        labels: None,
    }).await?;

    println!("Response: {}", result.text);

    let result = service.start_turn(&result.session_id, StartTurnRequest {
        prompt: "Now divide that result by 5.".into(),
        system_prompt: None,
        render_metadata: None,
        handling_mode: HandlingMode::Queue,
        event_tx: None,
        skill_references: None,
        flow_tool_overlay: None,
        additional_instructions: None,
    }).await?;

    println!("Follow-up: {}", result.text);

    let view = service.read(&result.session_id).await?;
    println!("Total tokens: {}", view.billing.total_tokens);

    Ok(())
}
```

--------------------------------

### Configure Prerequisites

Source: https://github.com/lukacf/meerkat/blob/main/examples/028-mobpack-release-triage-sh/README.md

Set the required API key and install the rkat tool before running the example.

```bash
export ANTHROPIC_API_KEY=sk-...
cargo install rkat

# Optional when working from this repo instead of a global install:
export RKAT=../../target/debug/rkat
```

--------------------------------

### Start the Meerkat development environment

Source: https://github.com/lukacf/meerkat/blob/main/examples/032-wasm-webcm-agent/README.md

Executes the setup script to download the WebCM emulator, build the WASM runtime, and launch the Vite development server.

```bash
./examples.sh
# Open http://127.0.0.1:4032
# Enter API keys (pre-filled from env if ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY are set)
# Click "Boot VM & Start"
```

--------------------------------

### Execute Examples Script

Source: https://github.com/lukacf/meerkat/blob/main/examples/004-cli-one-liners-sh/README.md

Make the examples script executable and run it.

```bash
chmod +x examples.sh && ./examples.sh
```

--------------------------------

### Run Meerkat Examples via CLI

Source: https://github.com/lukacf/meerkat/blob/main/examples/README.md

Commands to configure the API key, install dependencies, and execute examples across different programming languages.

```bash
# Set your API key
export ANTHROPIC_API_KEY=sk-...

# Install shared TypeScript example dependencies once
cd examples && npm install

# Run a Python example
(cd 002-hello-meerkat-py && python main.py)

# Run a TypeScript example
(cd 003-hello-meerkat-ts && npx tsx main.ts)

# Run a shell example
(cd 010-mcp-tool-server-sh && ./setup.sh)
```

--------------------------------

### Install Prerequisites

Source: https://github.com/lukacf/meerkat/blob/main/examples/029-web-incident-war-room-sh/README.md

Set the required API key and install the necessary CLI tools.

```bash
export ANTHROPIC_API_KEY=sk-...
cargo install rkat wasm-pack
```

--------------------------------

### Run Dev Mode

Source: https://github.com/lukacf/meerkat/blob/main/examples/033-the-office-demo-sh/README.md

Install Node.js dependencies and start the development server for live reloading and auto-syncing the WASM runtime.

```bash
cd web && npm install && npm run dev
```

--------------------------------

### Run Rust Examples

Source: https://github.com/lukacf/meerkat/blob/main/examples/README.md

Execute Rust-based examples directly from the workspace root using Cargo.

```bash
cargo run -p meerkat --example 001-hello-meerkat --features jsonl-store
```

--------------------------------

### Installation

Source: https://github.com/lukacf/meerkat/blob/main/sdks/python/README.md

Instructions for installing the Meerkat Python SDK.

```APIDOC
## Installation

### Description
Install the Meerkat Python SDK using pip.

### Usage
```bash
pip install meerkat-sdk
```

### Local Development
For local development, install the SDK in editable mode with development dependencies.

### Usage
```bash
pip install -e "sdks/python[dev]"
```
```

--------------------------------

### Install web build prerequisites

Source: https://github.com/lukacf/meerkat/blob/main/docs/cli/commands.mdx

Installs the necessary tools for building mob web components.

```bash
cargo install wasm-pack
wasm-pack --version
```

--------------------------------

### Execute meerkat_run Tool

Source: https://github.com/lukacf/meerkat/blob/main/docs/api/mcp.mdx

Request and response examples for starting a Meerkat agent session.

```json
{
  "prompt": "Write a haiku about Rust"
}
```

```json
{
  "prompt": "Analyze this code for bugs",
  "system_prompt": "You are a senior code reviewer.",
  "model": "claude-opus-4-6",
  "max_tokens": 4096,
  "provider": "anthropic",
  "output_schema": {
    "type": "object",
    "properties": {
      "bugs": {"type": "array", "items": {"type": "string"}},
      "severity": {"type": "string"}
    },
    "required": ["bugs", "severity"]
  },
  "structured_output_retries": 2,
  "stream": false,
  "verbose": false,
  "tools": [
    {
      "name": "read_file",
      "description": "Read a file from disk",
      "input_schema": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"]
      },
      "handler": "callback"
    }
  ],
  "enable_builtins": false,
  "builtin_config": {
    "enable_shell": false,
    "shell_timeout_secs": 30
  },
  "keep_alive": null,
  "comms_name": null,
  "hooks_override": null
}
```

```json
{
  "content": [{
    "type": "text",
    "text": "{\"content\":[{\"type\":\"text\",\"text\":\"Agent response here\"}],\"session_id\":\"01936f8a-...\",\"turns\":1,\"tool_calls\":0,\"structured_output\":null,\"schema_warnings\":null}"
  }]
}
```

--------------------------------

### Install Meerkat SDK for Development

Source: https://github.com/lukacf/meerkat/blob/main/sdks/python/README.md

Installation command for local development environments.

```bash
pip install -e "sdks/python[dev]"
```

--------------------------------

### Install Meerkat SDK

Source: https://github.com/lukacf/meerkat/blob/main/docs/sdks/python/overview.mdx

Commands to install the SDK for standard usage or local development.

```bash
pip install meerkat-sdk
```

```bash
pip install -e "sdks/python[dev]"
```

--------------------------------

### Build and run the REST server

Source: https://github.com/lukacf/meerkat/blob/main/docs/api/rest.mdx

Commands to start the server in development or production modes.

```bash
cargo run --package meerkat-rest -- --realm team-alpha
```

```bash
cargo build --release --package meerkat-rest
./target/release/rkat-rest --realm team-alpha
```

--------------------------------

### Start REST Server

Source: https://github.com/lukacf/meerkat/blob/main/examples/022-rest-api-client-py/README.md

Start the REST server in a terminal. Ensure ANTHROPIC_API_KEY is set.

```bash
# Terminal 1: Start REST server (default port 8080, configured in [rest] section)
ANTHROPIC_API_KEY=sk-... rkat-rest
```

--------------------------------

### Install Meerkat CLI

Source: https://github.com/lukacf/meerkat/blob/main/docs/quickstart.mdx

Install the Meerkat CLI from source. For pre-built binaries, refer to Mini surfaces.

```bash
cargo install --path meerkat-cli
```

--------------------------------

### Config Management Example

Source: https://github.com/lukacf/meerkat/blob/main/sdks/typescript/README.md

Demonstrates how to read, set, and patch configuration settings for the Meerkat client.

```APIDOC
## Config Management Example

This example shows how to manage client configuration, including reading, replacing, and merging configuration settings.

### Method
- `client.getConfig()`
- `client.setConfig(config)`
- `client.patchConfig(patch)`

### Request Example
```typescript
const client = new MeerkatClient();
await client.connect();

// Read the current config.
const config = await client.getConfig();
console.log(config.generation, config.config);

// Replace the entire config.
await client.setConfig({ ...config.config, max_tokens: 4096 });

// Or merge-patch specific fields.
const updated = await client.patchConfig({ max_tokens: 8192 });
console.log(updated.config.max_tokens);  // 8192

await client.close();
```
```

--------------------------------

### Install Meerkat SDK

Source: https://github.com/lukacf/meerkat/blob/main/examples/002-hello-meerkat-py/README.md

Install the required package via pip.

```bash
pip install meerkat-sdk   # or: pip install -e sdks/python
```

--------------------------------

### Run the Keep-Alive Event Mesh example

Source: https://github.com/lukacf/meerkat/blob/main/examples/024-host-mode-event-mesh-rs/README.md

Execute the example using the provided cargo command with your Anthropic API key.

```bash
ANTHROPIC_API_KEY=... cargo run -p meerkat --example 024-host-mode-event-mesh
```

--------------------------------

### Run Python Example

Source: https://github.com/lukacf/meerkat/blob/main/examples/022-rest-api-client-py/README.md

Execute the main Python script to interact with the REST API.

```bash
# Terminal 2: Run the example
python main.py
```

--------------------------------

### Install dependencies and run Python tests

Source: https://github.com/lukacf/meerkat/blob/main/sdks/python/README.md

Installs the Python SDK in editable mode with development dependencies and executes the test suite using pytest.

```bash
pip install -e "sdks/python[dev]"

pytest sdks/python/tests/test_types.py -v
pytest sdks/python/tests/test_audit_parity.py -v
pytest sdks/python/tests/test_e2e.py -v
pytest sdks/python/tests/test_e2e_smoke.py -v
```

--------------------------------

### Meerkat Skills Configuration Example

Source: https://github.com/lukacf/meerkat/blob/main/docs/guides/skills.mdx

Example TOML configuration for Meerkat skills, showing how to enable skills, set maximum injection size, define inventory thresholds, and specify skill repositories with their transport and URL.

```toml
# realm config (or ~/.rkat/skills.toml and .rkat/skills.toml in layered compatibility mode)
enabled = true
max_injection_bytes = 32768    # max size of injected skill content
inventory_threshold = 12       # flat listing below, collection mode above

[[repositories]]
name = "company"
transport = "git"
url = "https://github.com/company/skills.git"
```

--------------------------------

### Check Prerequisites

Source: https://github.com/lukacf/meerkat/blob/main/examples/033-the-office-demo-sh/README.md

Verify that Rust, wasm-pack, and Node.js are installed and accessible in your PATH.

```bash
rustc --version # stable Rust toolchain
wasm-pack --version
node --version  # 20+
```

--------------------------------

### Incident Kickoff Prompt

Source: https://github.com/lukacf/meerkat/blob/main/examples/029-web-incident-war-room-sh/README.md

Example prompt to initialize the war room scenario.

```text
Run this as a SEV-1 war room. State severity and customer impact, create a
task board, assign workstreams to each role, and tell me when the next update
is due.
```

--------------------------------

### Structured Output Example Request

Source: https://github.com/lukacf/meerkat/blob/main/docs/api/rest.mdx

Use this JSON structure to request structured output from the Meerkat API. Provide a prompt, model, and an output_schema to guide the response format. The structured_output_retries parameter can be used to attempt retries on schema mismatches.

```json
{
  "prompt": "Extract the capital of France",
  "model": "claude-opus-4-6",
  "output_schema": {
    "schema": {
      "type": "object",
      "properties": {
        "country": {"type": "string"},
        "capital": {"type": "string"}
      },
      "required": ["country", "capital"]
    },
    "name": "capital_extraction",
    "strict": false,
    "compat": "lossy",
    "format": "meerkat_v1"
  },
  "structured_output_retries": 2
}
```

--------------------------------

### Install Meerkat SDK (Python)

Source: https://github.com/lukacf/meerkat/blob/main/examples/README.md

Install the Meerkat Python SDK using pip. Alternatively, install from a local source.

```bash
pip install meerkat-sdk
```

```bash
pip install -e sdks/python
```

--------------------------------

### Quick Start Session Management

Source: https://github.com/lukacf/meerkat/blob/main/sdks/python/README.md

Demonstrates creating a session, sending turns, and archiving the session using the MeerkatClient.

```python
import asyncio
from meerkat import MeerkatClient

async def main() -> None:
    async with MeerkatClient() as client:
        session = await client.create_session("What is the capital of France?")
        print(session.text)

        result = await session.turn("And Germany?")
        print(result.text)

        await session.archive()

asyncio.run(main())
```

--------------------------------

### Install Meerkat CLI

Source: https://github.com/lukacf/meerkat/blob/main/README.md

Install the Meerkat CLI using Cargo. Ensure you have Rust 1.94+ installed. Set your API key as an environment variable.

```bash
cargo install rkat
export ANTHROPIC_API_KEY=sk-...
```

--------------------------------

### Build and Run Demo

Source: https://github.com/lukacf/meerkat/blob/main/examples/033-the-office-demo-sh/README.md

Execute the provided script to build the WASM runtime and the Vite application, then serve the application locally.

```bash
cd examples/033-the-office-demo-sh
chmod +x examples.sh && ./examples.sh
```

--------------------------------

### Quick Start with MeerkatClient

Source: https://github.com/lukacf/meerkat/blob/main/docs/sdks/python/overview.mdx

Demonstrates creating a session, performing turns, and streaming responses using the asynchronous client.

```python
import asyncio
from meerkat import MeerkatClient, TextDelta

async def main() -> None:
    async with MeerkatClient() as client:
        session = await client.create_session("What is the capital of France?")
        print(session.text)

        result = await session.turn("And Germany?")
        print(result.text)

        async with session.stream("Give one extra fact.") as events:
            async for event in events:
                match event:
                    case TextDelta(delta=chunk):
                        print(chunk, end="", flush=True)
            print()

        await session.archive()

asyncio.run(main())
```

--------------------------------

### Serve Application Locally

Source: https://github.com/lukacf/meerkat/blob/main/examples/033-the-office-demo-sh/README.md

Start a Python HTTP server to serve the built application files from the 'web/dist' directory.

```bash
python3 -m http.server 4174 --directory web/dist
open http://127.0.0.1:4174
```

--------------------------------

### Configure Environment and Build CLI

Source: https://github.com/lukacf/meerkat/blob/main/examples/004-cli-one-liners-sh/README.md

Set the required API key and build the project using cargo.

```bash
export ANTHROPIC_API_KEY=sk-...
cargo build -p meerkat-cli
```

--------------------------------

### POST /initialize

Source: https://github.com/lukacf/meerkat/blob/main/docs/api/rpc.mdx

Returns the server capabilities.

```APIDOC
## POST /initialize

### Description
Returns server capabilities.

### Method
POST

### Endpoint
/initialize
```

--------------------------------

### Create Session with Realtime Model

Source: https://github.com/lukacf/meerkat/blob/main/docs/api/rest.mdx

Create a session with a realtime-capable model to enable realtime audio. The runtime automatically attaches the transport, and the status endpoint reports `binding_ready` once confirmed. Control realtime mode by swapping the session's model.

```bash
curl -X POST http://127.0.0.1:8080/sessions \
  -H 'content-type: application/json' \
  -d '{"prompt":"Ready for voice.","model":"gpt-realtime","provider":"openai"}'
```

--------------------------------

### Install Meerkat from Crates.io (Rust)

Source: https://github.com/lukacf/meerkat/blob/main/examples/README.md

Install Meerkat using Cargo, the Rust package manager, from crates.io.

```bash
cargo install meerkat
```

--------------------------------

### POST /session/create

Source: https://github.com/lukacf/meerkat/blob/main/docs/api/rpc.mdx

Create a session and run the first turn.

```APIDOC
## POST /session/create

### Description
Create session and run first turn.

### Method
POST

### Endpoint
/session/create
```

--------------------------------

### Serve Web Application

Source: https://github.com/lukacf/meerkat/blob/main/examples/031-wasm-mini-diplomacy-sh/README.md

Command to serve the built web application locally.

```bash
python3 -m http.server 4173 --directory web/dist
open http://127.0.0.1:4173
```

--------------------------------

### OutputSchema wrapper format example

Source: https://github.com/lukacf/meerkat/blob/main/docs/guides/structured-output.mdx

An example of the wrapper format for OutputSchema, explicitly defining schema and configuration options.

```json
{
  "schema": {
    "type": "object",
    "properties": {
      "result": { "type": "string" }
    }
  },
  "name": "my-schema",
  "strict": true,
  "compat": "strict",
  "format": "meerkat_v1"
}
```

--------------------------------

### Install Meerkat TypeScript SDK

Source: https://github.com/lukacf/meerkat/blob/main/docs/quickstart.mdx

Install the Meerkat SDK for TypeScript using npm. Requires the `rkat-rpc` binary on your PATH.

```bash
npm install @rkat/sdk
```

--------------------------------

### Run Multi-Provider Application

Source: https://github.com/lukacf/meerkat/blob/main/examples/021-multi-provider-routing-py/README.md

Execute the application by providing necessary API keys as environment variables.

```bash
ANTHROPIC_API_KEY=sk-... OPENAI_API_KEY=sk-... python main.py
```

--------------------------------

### Install Meerkat Python SDK

Source: https://github.com/lukacf/meerkat/blob/main/docs/quickstart.mdx

Install the Meerkat SDK for Python using pip. Requires the `rkat-rpc` binary on your PATH.

```bash
pip install meerkat-sdk
```

--------------------------------

### Run MCP Tool Server Integration Script

Source: https://github.com/lukacf/meerkat/blob/main/examples/010-mcp-tool-server-sh/README.md

Execute the setup script to create isolated CLI roots, register a project-scoped MCP server, print the generated configuration, verify the server, and run a live prompt that utilizes MCP tools.

```bash
./setup.sh
```

--------------------------------

### Install wasm-pack

Source: https://github.com/lukacf/meerkat/blob/main/docs/guides/mobpack.mdx

Install the `wasm-pack` tool, which is a prerequisite for building WebAssembly modules for the web. Ensure the cargo bin directory is in your PATH.

```bash
cargo install wasm-pack
export PATH="$HOME/.cargo/bin:$PATH"
```

--------------------------------

### Create a New Session with Full Options (REST)

Source: https://context7.com/lukacf/meerkat/llms.txt

Use this endpoint to initiate a new session with detailed configuration, including model selection, system prompts, output schemas, and feature flags.

```bash
curl -X POST http://127.0.0.1:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{ \
    "prompt": "Extract the main topics from this text", \
    "model": "claude-sonnet-4-6", \
    "provider": "anthropic", \
    "max_tokens": 4096, \
    "system_prompt": "You are a helpful assistant.", \
    "output_schema": { \
      "schema": { \
        "type": "object", \
        "properties": { \
          "topics": {"type": "array", "items": {"type": "string"}} \
        }, \
        "required": ["topics"] \
      }, \
      "name": "topic_extraction" \
    }, \
    "structured_output_retries": 2, \
    "enable_builtins": true, \
    "enable_shell": false \
  }'
```

--------------------------------

### Connect and manage a realtime session

Source: https://github.com/lukacf/meerkat/blob/main/docs/guides/realtime.mdx

Demonstrates the workflow for creating a realtime-capable session, waiting for binding readiness, and retrieving session history.

```python
from meerkat import MeerkatClient

async with MeerkatClient() as client:
    await client.connect(realm_id="team-alpha")

    # 1. Create a session on a realtime-capable model — transport attaches automatically.
    session = await client.create_session(
        prompt="Ready for voice.",
        model="gpt-realtime",
        provider="openai",
    )

    # 2. Wait for the binding to reach BindingReady.
    while True:
        status = await client.runtime_realtime_attachment_status(session.id)
        if status.status == "binding_ready":
            break
        await asyncio.sleep(0.1)

    # 3. Obtain a bootstrap token and open the audio WebSocket.
    bootstrap = await client.realtime_open_info(session.id)
    # ... open ws to bootstrap.url, exchange audio chunks ...

    # 4. The session's history accumulates committed turns as audio commits
    #    at turn boundaries — same as a text session.
    history = await client.session_history(session.id)
```

--------------------------------

### Get MCP Server Details

Source: https://github.com/lukacf/meerkat/blob/main/docs/examples/tools.mdx

Retrieve detailed information for a specific registered MCP server by using the `rkat mcp get` command followed by the server's name.

```bash
# Get details for a specific server
rkat mcp get filesystem
```

--------------------------------

### Run mdm-kennel, mdm-target, and mdm-tux in Kennel Mode

Source: https://github.com/lukacf/meerkat/blob/main/examples/035-mdm-tux-rs/README.md

Sets up the mdm-kennel broker, registers an mdm-target agent with it, and connects the mdm-tux controller to discover and manage targets via the kennel.

```bash
cd examples/035-mdm-tux-rs

# Terminal 1 — kennel broker
cargo run --bin mdm-kennel -- --listen 127.0.0.1:5000

# Terminal 2 — target agent (registers with kennel)
ANTHROPIC_API_KEY=sk-ant-... cargo run --bin mdm-target -- \
    --kennel 127.0.0.1:5000 --rpc-port 4800 --name my-mac

# Terminal 3 — TUX controller (discovers targets via kennel)
cargo run --bin mdm-tux -- --kennel 127.0.0.1:5000
```

--------------------------------

### Get Specific MCP Server Configuration with rkat CLI

Source: https://context7.com/lukacf/meerkat/llms.txt

Retrieve the configuration for a specific MCP server within a given scope using the `rkat mcp get` command.

```bash
rkat mcp get filesystem --scope project
```

--------------------------------

### Linux systemd Installation Commands

Source: https://github.com/lukacf/meerkat/blob/main/examples/035-mdm-tux-rs/README.md

Commands to install the MDM target binary, reload the systemd daemon, and enable/start the mdm-target service. This ensures the service is managed by systemd and runs automatically.

```bash
sudo cp target/release/mdm-target /usr/local/bin/mdm-target
sudo systemctl daemon-reload
sudo systemctl enable --now mdm-target
```

--------------------------------

### Access help documentation

Source: https://github.com/lukacf/meerkat/blob/main/docs/cli/commands.mdx

Display advanced run flags and usage information.

```bash
rkat run --help
```

--------------------------------

### Memory Search Tool Output Example

Source: https://github.com/lukacf/meerkat/blob/main/docs/reference/builtin-tools.mdx

This is an example of the JSON output returned by the memory search tool when matches are found. It includes content, score, session ID, and turn number.

```json
[
  {
    "content": "The project codename is AURORA-7",
    "score": 0.87,
    "session_id": "<uuid>",
    "turn": 3
  }
]
```

--------------------------------

### Start Meerkat RPC Server with a Specific Realm

Source: https://github.com/lukacf/meerkat/blob/main/docs/concepts/realms.mdx

When starting the RPC server, use the `--realm` flag to connect to a specific realm. This is crucial for isolating or sharing state with other services.

```bash
rkat-rpc --realm team-alpha
```

--------------------------------

### Serve Browser Bundle

Source: https://github.com/lukacf/meerkat/blob/main/examples/029-web-incident-war-room-sh/README.md

Serve the generated browser bundle using a local HTTP server.

```bash
cd .work/incident-war-room-web
python3 -m http.server 4173
```

--------------------------------

### GET /models/catalog

Source: https://github.com/lukacf/meerkat/blob/main/docs/concepts/providers.mdx

Retrieves the model catalog.

```APIDOC
## GET /models/catalog

### Description
Retrieves the model catalog, including built-in models and configured self-hosted aliases.

### Method
GET

### Endpoint
`/models/catalog`

### Response
#### Success Response (200)
- **models** (array) - A list of available models.
- **providers** (object) - Information about supported providers.

#### Response Example
```json
{
  "models": [
    {
      "id": "claude-sonnet-4-6",
      "provider": "anthropic",
      "description": "Claude Sonnet 4.6"
    },
    {
      "id": "gpt-5.4",
      "provider": "openai",
      "description": "GPT-5.4"
    }
  ],
  "providers": {
    "anthropic": {
      "name": "Anthropic",
      "capabilities": ["chat", "completions"]
    },
    "openai": {
      "name": "OpenAI",
      "capabilities": ["chat", "completions"]
    }
  }
}
```
```

--------------------------------

### StartConversationRun

Source: https://github.com/lukacf/meerkat/blob/main/specs/machines/meerkat_machine/contract.md

Starts a conversation run from the Attached state.

```APIDOC
## StartConversationRun

### Description
Starts a conversation run from the Attached state.

### Method
StartConversationRun

### Endpoint
/lukacf/meerkat

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **SubmitRunPrimitive** (event) - Indicates that a run primitive should be submitted.

#### Response Example
```json
{
  "event": "SubmitRunPrimitive"
}
```
```

--------------------------------

### GET /capabilities

Source: https://github.com/lukacf/meerkat/blob/main/examples/022-rest-api-client-py/README.md

Lists the capabilities supported by the server.

```APIDOC
## GET /capabilities

### Description
List capabilities.

### Method
GET

### Endpoint
/capabilities
```

--------------------------------

### Configure Realms and Bindings in TOML

Source: https://github.com/lukacf/meerkat/blob/main/docs/guides/auth.mdx

Define backend and auth profiles, then create bindings within a realm in the `config.toml` file. This allows for multiple sessions against different accounts or tenants.

```toml
# ~/.rkat/config.toml (or project-local .rkat/config.toml)

[realm.prod.backend.anthropic_primary]
provider = "anthropic"
backend_kind = "anthropic_api"

[realm.prod.backend.openai_primary]
provider = "openai"
backend_kind = "openai_api"

[realm.prod.auth.anthropic_oauth]
provider = "anthropic"
auth_method = "claude_ai_oauth"
source = { kind = "managed_store", profile = "anthropic_oauth" }

[realm.prod.auth.openai_apikey]
provider = "openai"
auth_method = "api_key"
source = { kind = "managed_store", profile = "openai_apikey" }

[realm.prod.binding.default]
backend_profile = "anthropic_primary"
auth_profile    = "anthropic_oauth"

[realm.prod.binding.openai]
backend_profile = "openai_primary"
auth_profile    = "openai_apikey"
```

--------------------------------

### Execute Build and Test Commands

Source: https://github.com/lukacf/meerkat/blob/main/CLAUDE.md

Standard commands for building the workspace, running various test suites, and executing the CLI or examples.

```bash
# Build everything
./scripts/repo-cargo build --workspace

# Run fast tests (unit + integration-fast; skips doctests)
./scripts/repo-cargo nextest run --workspace --show-progress none --status-level none --final-status-level fail

# Run all tests including doc-tests (SLOW due to doc-test compilation)
./scripts/repo-cargo test --workspace

# Run deterministic end-to-end lane
./scripts/repo-cargo e2e-fast

# Run explicit build/composition end-to-end lane (ignored by default)
./scripts/repo-cargo test -p meerkat-integration-tests --test e2e_build_lane -- --ignored

# Run real local-resource end-to-end lane
./scripts/repo-cargo e2e-system

# Run targeted live-provider lane (ignored by default)
./scripts/repo-cargo e2e-live

# Run kitchen-sink live smoke lane (ignored by default)
./scripts/repo-cargo e2e-smoke

# Run per-model catalog validation lane (ignored by default)
./scripts/repo-cargo e2e-models

# Cargo aliases (defined in .cargo/config.toml)
./scripts/cargo-rct       # Fast tests (unit + integration-fast)
./scripts/repo-cargo unit # Unit tests only
./scripts/repo-cargo int  # Integration-fast tests only
./scripts/repo-cargo e2e-fast    # Deterministic e2e lane
./scripts/repo-cargo test -p meerkat-integration-tests --test e2e_build_lane -- --ignored  # Build/composition lane
./scripts/repo-cargo e2e-system  # Real binary / local resource lane
./scripts/repo-cargo e2e-live    # Targeted live-provider lane
./scripts/repo-cargo e2e-smoke   # Compound live-provider smoke lane
./scripts/repo-cargo e2e-models  # Live per-model catalog validation (on-demand / pre-release)

# Legacy compatibility shims (during migration)
./scripts/repo-cargo int-real  # Alias for e2e-system
./scripts/repo-cargo e2e       # Alias for e2e-live + e2e-smoke

# Run the CLI
./scripts/repo-cargo run -p meerkat-cli -- run "prompt"

# Run a specific example
ANTHROPIC_API_KEY=... ./scripts/repo-cargo run --example simple
```

--------------------------------

### GET /config

Source: https://github.com/lukacf/meerkat/blob/main/examples/022-rest-api-client-py/README.md

Reads the current runtime configuration.

```APIDOC
## GET /config

### Description
Read runtime config.

### Method
GET

### Endpoint
/config
```

--------------------------------

### GET /comms/peers

Source: https://github.com/lukacf/meerkat/blob/main/examples/022-rest-api-client-py/README.md

Lists all available communication peers.

```APIDOC
## GET /comms/peers

### Description
List comms peers.

### Method
GET

### Endpoint
/comms/peers
```

--------------------------------

### GET /comms/peers

Source: https://github.com/lukacf/meerkat/blob/main/docs/api/rest.mdx

List discoverable peers for a session.

```APIDOC
## GET /comms/peers

### Description
List discoverable peers for a session. Requires the comms feature.

### Method
GET

### Endpoint
/comms/peers

### Parameters
#### Query Parameters
- **session_id** (string) - Required - Session ID to query peers for.

### Response
#### Success Response (200)
- **peers** (array) - List of discoverable peers with name and address.

#### Response Example
{
  "peers": [
    {"name": "reviewer", "address": "127.0.0.1:4201"},
    {"name": "coordinator", "address": "inproc"}
  ]
}
```

--------------------------------

### GET /health

Source: https://github.com/lukacf/meerkat/blob/main/docs/api/rest.mdx

Perform a liveness check on the server.

```APIDOC
## GET /health

### Description
Liveness check for the server.

### Method
GET

### Endpoint
/health
```