Skip to main content
Before you can run workflows, you need four things on your machine: Elixir and Erlang for the BEAM runtime, Redis for job state persistence, Docker to run Redis locally, and OpenShell for sandboxed executor processes. This guide walks you through each in order and ends with a smoke test to confirm everything is wired up correctly.

​
Requirements

MirrorNeuron runs on macOS or Linux. You need:
  • Elixir and Erlang — the BEAM runtime that powers MirrorNeuron’s orchestration layer
  • Redis — stores job state, agent snapshots, and event history
  • Docker — the simplest way to run Redis locally
  • OpenShell — provides the isolated sandbox environment used by executor nodes
If you plan to run LLM-based examples such as llm_codegen_review, you also need a Gemini API key available in your environment on the machine running the job.
1

Install Elixir and Erlang

On macOS, install Elixir with Homebrew (Erlang is included as a dependency):
brew install elixir
Confirm the installation:
elixir --version
mix --version
For Linux, use your distribution’s package manager or follow the official Elixir installation guide.
2

Start Redis

The simplest local path is to run Redis in Docker:
docker rm -f mirror-neuron-redis 2>/dev/null || true
docker run -d --name mirror-neuron-redis -p 6379:6379 redis:7
Verify Redis is responding:
docker exec mirror-neuron-redis redis-cli ping
You should see:
PONG
3

Install OpenShell

Download and install OpenShell using the official installer:
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
Confirm the installation:
~/.local/bin/openshell --version
If openshell is not on your PATH, add it:
export PATH="$HOME/.local/bin:$PATH"
Alternatively, point MirrorNeuron directly to the binary using an environment variable:
export MIRROR_NEURON_OPENSHELL_BIN="$HOME/.local/bin/openshell"
4

Start the OpenShell gateway

MirrorNeuron’s executor nodes communicate with OpenShell through its gateway process. Start it and confirm it is connected:
openshell gateway start
openshell status
Look for Status: Connected in the output before continuing.
5

Fetch dependencies and build

From inside the MirrorNeuron directory, fetch dependencies, run the test suite, and build the CLI binary:
mix deps.get
mix test
mix escript.build
This produces the mirror_neuron CLI binary in the project root. The terminal monitor is available as a subcommand:
./mirror_neuron monitor
6

Set environment variables

Export these variables in your shell before running MirrorNeuron:
export MIRROR_NEURON_REDIS_URL="redis://127.0.0.1:6379/0"
export MIRROR_NEURON_EXECUTOR_MAX_CONCURRENCY="4"
export MIRROR_NEURON_COOKIE="mirrorneuron"
VariablePurpose
MIRROR_NEURON_REDIS_URLConnection URL for the Redis instance used for persistence
MIRROR_NEURON_EXECUTOR_MAX_CONCURRENCYMaximum number of executor leases that can run concurrently on this node
MIRROR_NEURON_COOKIEBEAM distribution cookie, used to authenticate cluster members
If you are using LLM-based examples, also export your Gemini API key:
export GEMINI_API_KEY="your-api-key-here"
Add these exports to your shell profile (.zshrc, .bashrc, etc.) so they are set automatically in every new session.
7

Run the smoke test

Validate and run the included research_flow example to confirm your installation is working:
./mirror_neuron validate examples/research_flow
./mirror_neuron run examples/research_flow
./mirror_neuron monitor --json | head -n 20
A successful validate prints a confirmation with no errors. A successful run shows the CLI banner, a progress view, and a final run summary.

​
Cluster setup

For two-box or larger cluster deployments, additional prerequisites apply. See the Cluster Guide for details.

​
Troubleshooting

If any step above does not behave as expected, check the Troubleshooting guide for common issues and fixes.