MirrorNeuron Component Guide

This guide keeps the durable project details in mn-docs so each folder-level README.md can stay short and task-focused.

Use this page when you need to choose the right repository, install a component, run local validation, or understand where a detail belongs.

Documentation Model

Most non-blueprint folder READMEs should answer four questions only:

What is this folder?
What is the shortest safe command to try it?
What should be validated before changing it?
Where is the detailed guide?

Long-lived setup, configuration, architecture, security, troubleshooting, testing, and release notes belong in mn-docs.

Blueprint folders in mn-blueprints and otterdesk-blueprints are the exception. Keep those README files self-contained because users often review, copy, or run a single blueprint folder without opening the central docs.

Workspace Map

Folder	Owns	Start here	Basic validation
`MirrorNeuron`	Elixir/OTP runtime, gRPC services, runtime scheduling, Redis state	`runtime-architecture.md`	`mix test`
`mn-deploy`	Installer, local service control, generated Docker Compose runtime	`installation.md`	`./install_bin.sh --help`
`mn-cli`	`mn` command-line interface	`cli.md`	`python3 -m pytest -q`
`mn-api`	FastAPI REST gateway over the runtime SDK	`api.md`	`python3 -m pytest -q`
`mn-python-sdk`	Python gRPC client and workflow bundle helpers	`SDK.md`	`python3 -m pytest -q`
`mn-web-ui`	Browser UI for jobs, graphs, runtime state, and blueprint runs	`monitor.md`	`npm run lint && npm test -- --run`
`mn-blueprints`	Runnable workflow blueprints and catalog metadata	`blueprints-and-skills.md`	`python3 -m pytest -q`
`mn-agents`	Shared agent templates used by blueprints	`blueprints-and-skills.md`	`python3 tools/validate_agents.py --json`
`mn-skills`	Installable Python skill packages used by blueprint payloads	`blueprints-and-skills.md`	Package-specific `python3 -m pytest -q`
`mn-system-tests`	Cross-repository smoke, integration, e2e, and benchmark tests	`testing.md`	`python3 test_all.py --help`
`Membrane`	Rust context engine, Python SDK, context compression tooling	`runtime-architecture.md`	`cargo test` and package pytest suites
`Synapse`	Blueprint-composition planner and MCP wrapper	`architect.md`	`python3 -m pytest -q` in each package
`otterdesk-blueprints`	OtterDesk-facing blueprint catalog	`blueprints-and-skills.md`	`python3 -m pytest -q`
`otterdesk-desktop-app`	Electron desktop app that launches and monitors worker blueprints	`deployments.md`	`npm run doctor`

Quick Local Path

Install or update the local runtime with the deployment repository:

cd mn-deploy
./install_bin.sh --help
./install_bin.sh

Start services after installation:

mn runtime start
mn node list

Run a checked-in blueprint:

mn blueprint run message_routing_trace
mn blueprint monitor --follow

Most run artifacts are written under:

~/.mn/runs/<run_id>/

Component Details

MirrorNeuron Core

MirrorNeuron Core is the Elixir/OTP runtime. It schedules workflow agents, routes messages, records events, persists runtime state through Redis, exposes gRPC services, and supports local or clustered execution.

Use this folder when changing runtime behavior, scheduling, persistence, clustering, resource accounting, gRPC services, or sandbox execution.

Common local commands:

cd MirrorNeuron
mix deps.get
mix format
mix test

Redis-backed tests need Redis:

docker run -d --name mirror-neuron-redis -p 6379:6379 redis:7
mix test

Read next:

Deployment Scripts

mn-deploy installs and controls a local MirrorNeuron system. The package-based installer is install_bin.sh. It can install the core release, Python SDK, CLI, API, Web UI, Redis, OpenShell, and the Membrane context engine depending on the selected options.

Useful commands:

cd mn-deploy
./install_bin.sh --help
./server.sh status
./server.sh start
./server.sh stop

Default runtime state lives in ~/.mn. Generated service settings, ports, tokens, and shared run paths are stored in ~/.mn/docker-compose.env.

Read next:

CLI

mn-cli provides the mn command. It submits blueprints, validates bundles, lists jobs, inspects runtime state, exports artifacts, and starts local services installed by mn-deploy.

Developer setup:

cd mn-cli
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e .
python3 -m pytest -q

Common commands:

mn --version
mn node list
mn blueprint run message_routing_trace
mn job status <job_id>
mn blueprint monitor --follow

Read next:

API

mn-api is a FastAPI service that exposes runtime operations over REST and uses the Python SDK gRPC client to talk to the core.

Developer setup:

cd mn-api
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e ".[test]"
python3 -m pytest -q
mn-api

The default local server is:

http://localhost:54001

Use MN_ENV=prod and MN_API_TOKEN for protected deployments.

Read next:

Python SDK

mn-python-sdk provides the gRPC client, workflow decorators, bundle generation helpers, input validation helpers, and runtime configuration utilities used by the CLI and API.

Developer setup:

cd mn-python-sdk
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e .
python3 -m pytest -q

Minimal client example:

from mn_sdk import Client

client = Client(target="localhost:55051")
print(client.list_jobs(limit=5))

Read next:

Web UI

mn-web-ui is a React/Vite browser interface for runtime dashboards, job history, graph inspection, events, dead letters, and raw manifest submission.

Developer setup:

cd mn-web-ui
npm install
npm run dev

Build and test:

npm run lint
npm test -- --run
npm run build

The local development server defaults to:

http://localhost:55173

Read next:

Blueprint Library

mn-blueprints is the runnable blueprint catalog. The root index.json is the catalog source of truth. Each blueprint folder contains a manifest, default config, payloads, a quick README, a customer-facing SPEC.md, and tests or fixtures when available.

Run a catalog blueprint:

cd mn-blueprints
mn blueprint run message_routing_trace
mn blueprint monitor --follow

Run from a local folder:

mn blueprint run --folder ./message_routing_trace

Read next:

Agent Templates

mn-agents keeps reusable, versioned agent templates. Blueprints actualize these templates with uses, with, and config rather than copying node boilerplate into every manifest.

Validate the catalog:

cd mn-agents
python3 -m pip install -r requirements-test.txt
python3 tools/validate_agents.py --json
python3 -m pytest -q

Simulate one fixture:

python3 tools/simulate_agent.py data_python_executor/fixtures/minimal.instance.json

Read next:

Skill Packages

mn-skills contains installable Python helper packages for blueprint payloads. Skills should stay generic; blueprint-specific prompts, policy, scenarios, and customer assumptions belong in the owning blueprint.

Install one package from source:

cd mn-skills
python3 -m pip install -e generate_fake_data_skill

Run package tests from the package folder when tests exist:

cd generate_fake_data_skill
python3 -m pytest -q

Read next:

System Tests

mn-system-tests coordinates checks across the core, SDK, CLI, API, Web UI, blueprints, and installers.

Set up dependencies:

cd mn-system-tests
python3 -m pip install -r requirements.txt

Inspect the test runner:

python3 test_all.py --help

Fast benchmark fixture tests:

python3 -m pytest benchmarks -q

Live integration and e2e tests are intentionally gated. Set RUN_MN_SYSTEM_TESTS=1 and use the --live runner options only when local services are available.

Read next:

Membrane

Membrane is the context-memory side of the platform. It includes a Rust gRPC context engine, a Python SDK shell, deterministic context compression tooling, and benchmark packages.

Core engine validation:

cd Membrane/mn-context-engine
cargo test

Python SDK validation:

cd Membrane/mn-context-engine-python-sdk
python3 -m pip install -e ".[dev]"
python3 -m pytest -q

Optimizer validation:

cd Membrane/mn-context-auto-optimizer
python3 -m pip install -e ".[dev]"
python3 -m pytest -q

Read next:

Synapse

Synapse is the blueprint-composition layer. It studies a problem brief, selects reusable mn-agents and mn-skills, compares against existing blueprints, and produces an inspectable composition plan.

Try the orchestrator:

cd Synapse/mn-orchastrator
PYTHONPATH=src python3 -m mn_orchastrator.cli compose \
  "Build a support triage workflow that ranks escalation risk and writes a report." \
  --workspace-root ../..

Read next:

OtterDesk

otterdesk-desktop-app is the Electron desktop app. It launches and monitors worker blueprints, stores app state, and exposes desktop workflows for local operators.

Developer setup:

cd otterdesk-desktop-app
npm install
npm run doctor
npm run dev

otterdesk-blueprints contains the OtterDesk-facing worker blueprint catalog. Use its root tests before changing catalog metadata or manifests:

cd otterdesk-blueprints
python3 -m pytest -q

Read next:

Cross-Cutting Configuration

Common environment variables include:

Variable	Used by	Purpose
`MN_GRPC_TARGET`	CLI, API, SDK	Runtime gRPC target.
`MN_CORE_GRPC_TARGET`	CLI, API, SDK	Fallback runtime gRPC target.
`MN_API_PORT`	API, deploy scripts	REST API port, defaulting to `54001` in local deployments.
`MN_RUNS_ROOT`	Core, API, CLI, blueprints	Shared run-artifact store.
`MN_API_TOKEN`	API, Web UI	Bearer token for protected REST deployments.
`MN_WEB_API_BASE_URL`	Web UI	Browser REST API base URL.

See Environment Variables for the detailed reference.

Validation Notes

Prefer the smallest component-level validation before broader system tests.
Use mn-system-tests/test_all.py when a change spans repositories.
Run live tests only when Redis, the core, API, and any required sandbox or provider services are available.
When a command in a README changes, update this guide or the linked reference page in the same change.

Open TODOs

TODO: Add a top-level license file to mn-system-tests before distributing benchmark fixtures or reports outside the project.
TODO: Add stable screenshots or short recordings for the Web UI and runtime monitor after those views settle.

MirrorNeuron Component Guide

On this page