Install MirrorNeuron Locally

This guide installs the dependencies needed to validate bundles, run local workflows, and execute the test suite.

Requirements

• macOS, Linux, or WSL2
• git
• Python 3.10+
• Docker (and the docker-model runtime plugin)

Docker Desktop includes the plugin on macOS and Windows. On Linux, install the runtime plugin:

sudo apt-get update
sudo apt-get install docker-model-plugin

Optional:

• model provider keys for LLM blueprints
• two machines with SSH access for cluster and Redis HA smoke tests

Option 1: Install With The Deployment Script

Use the deployment script when you want a system-wide mn command.

curl -fsSL https://mirrorneuron.io/install.sh | bash

Expected result:

mn installed

Verify:

mn --help

Expected output includes:

MirrorNeuron CLI

Option 2: Set Up From The Monorepo

From the workspace root:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r mn-system-tests/requirements.txt

Expected result:

Successfully installed

The system-test requirements install the local Python SDK and CLI in editable mode.

Step 1: Install Elixir And Erlang

On macOS with Homebrew:

brew install elixir
elixir --version
mix --version

Expected output includes:

Elixir
Mix

On Linux, use your package manager or asdf and verify with the same commands.

Step 2: Fetch Core Dependencies

cd MirrorNeuron
mix deps.get
mix compile

Expected output:

Generated mirror_neuron app

If dependencies are already compiled, Mix may print less output. A zero exit code is the success signal.

Step 3: Start Redis

The simplest local Redis path is Docker:

docker rm -f mirror-neuron-redis 2>/dev/null || true
docker run -d --name mirror-neuron-redis -p 6379:6379 redis:7
docker exec mirror-neuron-redis redis-cli ping

Expected output:

PONG

Step 4: Install OpenShell

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
~/.local/bin/openshell --version

Expected output includes:

openshell

If openshell is not on your PATH:

export PATH="$HOME/.local/bin:$PATH"

Or point MirrorNeuron directly to the binary:

export MN_OPENSHELL_BIN="$HOME/.local/bin/openshell"

Step 5: Start The OpenShell Gateway

openshell gateway start
openshell status

Expected output includes:

Status: Connected

If OpenShell is not needed for your first pure-router workflow, you can skip this until you run executor blueprints.

Step 6: Configure Local Environment

Recommended local defaults:

export MN_REDIS_URL="redis://127.0.0.1:6379/0"
export MN_EXECUTOR_MAX_CONCURRENCY="4"
export MN_COOKIE="mirrorneuron"

Optional for LLM-enabled blueprints:

export LITELLM_MODEL="gemini/gemini-2.5-flash-lite"
export LITELLM_API_KEY="..."

Optional for local Docker Model Runner LLM blueprints:

docker model status
mn model install gemma4:e2b
mn model doctor gemma4:e2b

gemma4:e2b resolves to Docker's ai/gemma4:E2B model and is the default MirrorNeuron local model for hosts with 8GB VRAM or 16GB unified memory.

Use a unique Redis namespace when running tests beside a developer runtime:

export MN_REDIS_NAMESPACE="mirror_neuron_dev_$(date +%s)"

Step 7: Smoke Test

From the workspace root:

mn blueprint run message_routing_trace

Expected output:

Blueprint 'message_routing_trace' validated. Running...

Start services:

mn runtime start
mn blueprint run message_routing_trace

Expected output:

Job submitted successfully

Uninstall Local Services

Stop MirrorNeuron:

mn runtime stop

Stop local Redis:

docker rm -f mirror-neuron-redis

If installed through the deployment script, remove the install directory and executable:

rm -rf ~/.local/share/MirrorNeuron
rm -f ~/.local/bin/mn

Warning: only remove these paths if they belong to the MirrorNeuron install you want to delete.

Security Notes

• Keep local Redis bound to trusted interfaces.
• Change MN_COOKIE before using a real cluster.
• Do not expose API or gRPC ports publicly without an authentication boundary.
• Review third-party bundles before running them.

Cluster Prerequisites

For two-box or larger clusters, continue with:

• Cluster Guide
• Redis High Availability

Common Install Issues

If setup does not work as expected:

• Troubleshooting
• Testing