Install the Python MCP sidecars

Revka ships as a single revka binary, but two of its core capabilities — persistent graph memory and multi-agent workflow orchestration — are delivered by Python MCP (Model Context Protocol) sidecars that run alongside the binary:

Sidecar	Launcher path	Config key	What it powers
Kumiho MCP	~/.revka/kumiho/run_kumiho_mcp.py	[kumiho].mcp_path	Persistent graph memory (kumiho_memory_* tools)
Operator MCP	~/.revka/operator_mcp/run_operator_mcp.py	[operator].mcp_path	Workflow execution, teams, and orchestration tools

revka onboard installs both sidecars automatically at the end of the wizard, so most users never run anything on this page by hand. Use this page when you need to (re)install the sidecars on their own, install from a source checkout, point at a specific Python interpreter, or fix a partial install that revka doctor flagged.

Note

The Kumiho MCP sidecar is a client stub, not the memory backend. The Kumiho control plane (a FastAPI + Neo4j service) is reached over HTTP via [kumiho].api_url — it is not installed locally. See Kumiho setup for the backend side.

Prerequisites

• Python 3.11+ on PATH. The installer warns (but does not abort) if it detects an older interpreter.
• Network access to PyPI — the installer runs pip install into isolated per-sidecar virtualenvs.
• A reachable Kumiho control-plane URL and auth token for actual persistence. These are collected by revka onboard and written to ~/.revka/.env. Without them the Kumiho MCP process still starts but degrades to stateless operation.
• (Optional) Node.js 18+ / npm — only needed for the --with-session-manager Session Manager sidecar.

Install with the binary (recommended)

If revka is already on your PATH, the cross-platform installer is a single command:

revka install --sidecars-only

This provisions both sidecars: it detects Python, creates isolated venvs at ~/.revka/kumiho/venv/ and ~/.revka/operator_mcp/venv/, pip-installs the packages, materializes the launcher scripts, and syncs the Operator’s orchestration skills into ~/.revka/skills/. The Operator MCP package source is embedded in the revka binary at compile time, so nothing is downloaded for it at runtime.

The command is idempotent — re-running it is safe and never overwrites your config.toml, .env, or a user-authored launcher.

Flags

Flag	Effect
--sidecars-only	Required. Installs only the sidecars (the full install flow is handled by install.sh).
--skip-kumiho	Skip the Kumiho MCP sidecar.
--skip-operator	Skip the Operator MCP sidecar.
--with-session-manager	Also install the Node.js Session Manager sidecar (requires npm). See below.
--dry-run	Print the planned actions without executing anything.
--python <path>	Use an explicit Python interpreter, e.g. --python /usr/bin/python3.11.
--from-source <repo>	Dev mode: install the Operator MCP from a local Revka checkout. See below.

# Preview the plan without changing anything
revka install --sidecars-only --dry-run

# Force a specific interpreter
revka install --sidecars-only --python /usr/bin/python3.11

Tip

ensure_sidecars_ready runs transparently on every agent and daemon start. If a sidecar’s venv interpreter or launcher is missing, Revka prompts you to install it interactively — so a missed install is usually self-healing on the next run.

Install from a source checkout

If you do not have the revka binary yet (for example, you cloned the repo to build from source), run the bundled installer scripts directly:

POSIX (macOS / Linux / WSL)

./scripts/install-sidecars.sh

Windows

scripts\install-sidecars.bat

These scripts produce the same ~/.revka/ layout as revka install --sidecars-only and are also idempotent. They accept --skip-kumiho, --skip-operator, --dry-run, and --python <path>. The same logic runs automatically from ./install.sh and setup.bat when a checkout contains the Operator source and the launchers are missing; disable it with ./install.sh --skip-sidecars.

The Operator install prefers the canonical operator-mcp/Makefile (make install) when make is available, and falls back to a minimal python -m venv + pip install + copy otherwise. Windows always uses the fallback path (with robocopy in place of rsync).

Kumiho MCP install detail

The Kumiho sidecar install does the following:

1. Creates the venv at ~/.revka/kumiho/venv/.

2. Installs the Kumiho package with the MCP extra:

   ~/.revka/kumiho/venv/bin/pip install 'kumiho[mcp]>=0.9.20'

   The [mcp] extra pulls in mcp>=1.0.0 and httpx>=0.27.0, which the stdio server in kumiho.mcp_server requires.

3. Writes ~/.revka/kumiho/run_kumiho_mcp.py — a thin shim that re-executes python -m kumiho.mcp_server out of that venv. (The binary installer also writes the kumiho_sdk_bridge.py helper used for low-latency loopback reads.)

kumiho[mcp] pin

The version pin is kumiho[mcp]>=0.9.20 and is kept in sync with operator-mcp/requirements.txt. The pin is fixed in the binary, so re-running revka install --sidecars-only after a revka update is the simplest way to pick up a newer compatible Kumiho release.

Manual install

If you prefer to set up the Kumiho venv by hand:

mkdir -p ~/.revka/kumiho
python3 -m venv ~/.revka/kumiho/venv
~/.revka/kumiho/venv/bin/pip install --upgrade pip
~/.revka/kumiho/venv/bin/pip install 'kumiho[mcp]>=0.9.20'

Then point [kumiho].mcp_path in ~/.revka/config.toml at your launcher (or leave it unset to use the default location).

The kumiho_memory upgrade gap

There are two Python packages involved in graph memory:

• kumiho — low-level CRUD plus memory_store / memory_retrieve.
• kumiho_memory — the high-level memory reflexes the agent’s session bootstrap actually calls: kumiho_memory_engage, kumiho_memory_reflect, kumiho_memory_recall, kumiho_memory_consolidate, and kumiho_memory_dream_state. kumiho.mcp_server auto-discovers and merges these tools in when the package is importable.

The source script install-sidecars.sh installs both packages:

~/.revka/kumiho/venv/bin/pip install 'kumiho[mcp]>=0.9.20' 'kumiho_memory>=0.5.0'

Older installs (and the binary’s kumiho[mcp] pin path) may have only kumiho, not kumiho_memory. When that happens, the agent fires high-level memory tool calls that don’t exist, and advanced memory reflexes are disabled. revka doctor reports this in its sidecars category with a warning. Close the gap with:

~/.revka/kumiho/venv/bin/python -m pip install 'kumiho_memory>=0.5.0'

On Windows, the venv interpreter is at ~/.revka/kumiho/venv/Scripts/python.exe.

Operator MCP install detail

The Operator sidecar creates ~/.revka/operator_mcp/venv/, pip-installs the Operator package, syncs the flat package tree (used by the dashboard and scheduler readers) into ~/.revka/operator_mcp/, copies orchestration skills into ~/.revka/skills/, and writes the launcher ~/.revka/operator_mcp/run_operator_mcp.py.

Updates preserve runtime state — the sync step keeps existing .json, .jsonl, .db, venv/, session-manager/, and runlogs/ files in place, so re-running the installer does not wipe your workflow checkpoints or run history.

--from-source dev mode

For iterating on the Python side without rebuilding the Rust binary (whose embedded Operator snapshot is fixed at compile time), point the installer at a local Revka repo root:

revka install --sidecars-only --from-source /path/to/Revka

The installer uses <path>/operator-mcp/ as the pip install source instead of the embedded copy. It validates the path by checking for operator-mcp/pyproject.toml and errors out if that file is missing.

Node Session Manager

The Session Manager is an opt-in Node.js sidecar that relays live DAG / timeline overlay events during workflow runs:

revka install --sidecars-only --with-session-manager

It is off by default on purpose. The Session Manager drives spawned agents through the Claude Agent SDK, which accepts only ANTHROPIC_API_KEY (pay-per-token) and cannot use a Claude Pro/Max subscription. The default path uses direct subprocess spawning (claude --print + codex exec), which routes spawned-agent calls through each CLI’s own OAuth — typically much cheaper. The Operator runs fine without the Session Manager; you just won’t get the streaming live-execution overlay.

A Session Manager install failure (missing npm, network blip) is non-fatal — the Operator falls back to subprocess mode and the rest of the sidecar install still succeeds.

Verify the install

The end-to-end check is revka doctor, whose sidecars category confirms the Kumiho venv Python exists, that kumiho is importable, and that kumiho_memory is importable (warning if missing):

revka doctor

Sidecar status check (manual)

Internally, Revka checks each sidecar by confirming that both its venv interpreter and its launcher script exist. You can reproduce that check directly:

POSIX

ls ~/.revka/kumiho/venv/bin/python3
ls ~/.revka/kumiho/run_kumiho_mcp.py
ls ~/.revka/operator_mcp/venv/bin/python3
ls ~/.revka/operator_mcp/run_operator_mcp.py

# Package import smoke tests
~/.revka/kumiho/venv/bin/python3 -c 'import kumiho; print(kumiho.__version__)'
~/.revka/operator_mcp/venv/bin/python3 -c 'import operator_mcp; print("ok")'

Windows

Get-Item ~\.revka\kumiho\venv\Scripts\python.exe
Get-Item ~\.revka\kumiho\run_kumiho_mcp.py
Get-Item ~\.revka\operator_mcp\venv\Scripts\python.exe
Get-Item ~\.revka\operator_mcp\run_operator_mcp.py

You can also confirm the MCP tools loaded by visiting the gateway’s tools endpoint (http://127.0.0.1:42617/tools) and checking that kumiho_memory_* and the Operator workflow tools appear.

Troubleshooting

Symptom	Fix
Logs show Kumiho MCP script not found: ~/.revka/kumiho/run_kumiho_mcp.py	Run revka install --sidecars-only (or ./scripts/install-sidecars.sh).
ModuleNotFoundError: kumiho.mcp_server or ModuleNotFoundError: mcp	Reinstall with the extra: ~/.revka/kumiho/venv/bin/pip install -U 'kumiho[mcp]'.
revka doctor warns that kumiho_memory is missing	~/.revka/kumiho/venv/bin/python -m pip install 'kumiho_memory>=0.5.0'.
MCP tools list is empty in the dashboard	Check ~/.revka/logs/ for a stderr trail; confirm the Kumiho auth token and control-plane URL are present in ~/.revka/.env (written by revka onboard).
Kumiho control plane unreachable	Verify [kumiho].api_url in ~/.revka/config.toml points at a reachable endpoint.
run_operator_mcp.py crashes with ModuleNotFoundError: operator_mcp	Re-run the installer — the package tree likely failed to copy.
Live DAG overlay empty during workflow runs	Session Manager not installed — re-run with --with-session-manager (needs npm).
No working Python interpreter found	Install Python 3.11+, or pass --python /path/to/python.

Related

Kumiho setup Config keys, auth tokens, and backend modes for the Kumiho control plane.

Kumiho graph memory The two-reflex pattern, capture types, and how memory flows through the agent.

Operator MCP The orchestration sidecar — workflows, teams, and run state.

revka doctor, status & self-test Run diagnostics to verify the sidecars and the rest of your setup.