Skip to main content
MirrorNeuron ships eight runnable example bundles that cover different parts of the runtime — from a simple two-agent routing flow all the way to large-scale cluster simulations and Gemini-powered LLM codegen loops. This guide describes what each example demonstrates, how to run it, and the recommended progression order if you are working through them for the first time. Work through the examples in this order to build understanding incrementally:
  1. research_flow — local routing and aggregation, no sandbox
  2. openshell_worker_demo — sandbox execution with shell and Python payloads
  3. divisibility_monitor — long-lived BEAM module agents with explicit message loops
  4. prime_sweep_scale — sharded work, scale benchmarks, cluster placement
  5. streaming_peak_demo — runtime streaming messages and incremental consumption
  6. mpe_simple_push_visualization — shared multi-agent environment with HTML output
  7. llm_codegen_review — multi-agent LLM collaboration with a code validator
  8. ecosystem_simulation — large stateful simulation under cluster load
Each step adds a new capability on top of the previous one, so running them in order gives you the fastest path to understanding the runtime.

​
1. research_flow

The smallest useful MirrorNeuron workflow. It validates routing and aggregation between agents without any sandbox dependency, making it the ideal first example. What it demonstrates:
  • Defining a minimal multi-agent graph in manifest.json
  • Message routing from a source agent through to an aggregator
  • How the CLI validates and runs a simple bundle
./mirror_neuron validate examples/research_flow
./mirror_neuron run examples/research_flow

​
2. openshell_worker_demo

The first example that uses sandboxed execution. Worker code runs inside isolated OpenShell sandboxes using both shell scripts and Python. What it demonstrates:
  • Shell and Python executor payloads within a single bundle
  • Bundle-based payload staging into the sandbox working directory
  • Bundle-scoped OpenShell policy files that travel with the bundle
./mirror_neuron validate examples/openshell_worker_demo
./mirror_neuron run examples/openshell_worker_demo --json
The bundle includes a network policy file at payloads/policies/api-egress.yaml. You reference it in your executor config using the policy key, resolved relative to the bundle’s payloads/ directory: 
{
  "config": {
    "upload_path": "word_count",
    "workdir": "/sandbox/job/word_count",
    "command": ["bash", "scripts/collect_metrics.sh"],
    "policy": "policies/api-egress.yaml"
  }
}
Carrying a policy file inside your bundle means each bundle can define its own network allowlist without relying on a global policy configuration.

​
3. divisibility_monitor

A long-lived workflow that runs until you manually stop it. Two BEAM module agents pass messages in a loop without any sandbox involvement, demonstrating how MirrorNeuron handles open-ended jobs. What it demonstrates:
  • Long-lived jobs that do not have a natural completion point
  • Agent-to-agent message loops with explicit message types
  • local_restart recovery mode, which prevents old demo runs from auto-resuming
  • Using --no-await to submit a background job and monitor it separately
./mirror_neuron validate examples/divisibility_monitor
./mirror_neuron run examples/divisibility_monitor --no-await
Watch the agents loop in real time: 
./mirror_neuron monitor
Cancel when you are done: 
./mirror_neuron cancel <job_id>

​
4. prime_sweep_scale

A scale benchmark that fans out primality checks across many executor workers and aggregates the results. Useful for testing execution scheduling, sandbox reuse, and cluster work distribution. What it demonstrates:
  • Sharding a large numeric range across many logical executor workers
  • Aggregating results from parallel workers into a final summary
  • Stressing execution scheduling and sandbox reuse
  • Running distributed work across a two-node cluster
bash examples/prime_sweep_scale/run_scale_test.sh \
  --start 1000003 \
  --end 1001202
Key files in this bundle:
  • generate_bundle.py — generates the job bundle with the desired worker count and range
  • run_scale_test.sh — end-to-end test runner
  • summarize_result.py — post-processes the aggregated output

​
5. streaming_peak_demo

Demonstrates MirrorNeuron’s runtime-level streaming support. One agent produces a stream of gzipped NDJSON chunks; another consumes it incrementally and detects abnormal peaks. What it demonstrates:
  • Streaming messages between agents at the runtime level
  • Gzipped NDJSON as a wire payload format
  • Incremental consumption of a data stream
  • Detecting and reporting anomalies in streaming data
bash examples/streaming_peak_demo/run_streaming_e2e.sh
Key files:
  • generate_bundle.py — generates the bundle with configurable stream parameters
  • run_streaming_e2e.sh — end-to-end local runner
  • summarize_result.py — extracts the largest detected anomaly from results

​
6. mpe_simple_push_visualization

Runs a shared PettingZoo MPE (Multi-Particle Environment) crowd simulation with many agents inhabiting one environment. A single HostLocal simulation worker and one visualizer keep execution lightweight while producing a browser-viewable HTML output. What it demonstrates:
  • Running one shared multi-agent environment rather than isolated per-agent sandboxes
  • Producing an HTML visualization of the full arena over simulation time
  • A compact simulation example relative to the full ecosystem_simulation
bash examples/mpe_simple_push_visualization/run_simple_push_e2e.sh
To generate and immediately open the HTML visualization in your browser: 
bash examples/mpe_simple_push_visualization/run_simple_push_e2e.sh --open
Key files:
  • generate_bundle.py — generates the bundle
  • run_simple_push_e2e.sh — end-to-end runner with optional --open flag
  • summarize_result.py — post-processes the simulation output

​
7. llm_codegen_review

A meaningful end-to-end multi-agent collaboration example powered by Gemini. A coder agent generates code, a reviewer agent critiques it, and the loop runs for three rounds before a Python validator evaluates the final result. What it demonstrates:
  • Multi-agent LLM collaboration with a structured generate→review→regenerate cycle
  • Gemini 2.5 Flash Lite as the default model (requires an API key)
  • Three rounds of iterative code improvement
  • A final Python validator that evaluates the output
bash examples/llm_codegen_review/run_llm_e2e.sh
This example requires a Gemini API key. Set it in your environment before running. Refer to the bundle’s README for the required environment variable name.

​
8. ecosystem_simulation

The most demanding example. It models a large population of animals competing for limited regional resources across many simulation steps, exercising cross-region messaging, migration, breeding, and summary ranking. Use this to stress-test the runtime under cluster load. What it demonstrates:
  • A BEAM-native sharded world model with many stateful agents
  • Cross-region messaging and agent migration between shards
  • Randomized world resource allocation and per-run DNA initialization
  • Top-10 DNA profile ranking as the final output
  • The runtime under sustained cluster load
bash examples/ecosystem_simulation/run_simulation_e2e.sh
Key files:
  • generate_bundle.py — generates the bundle with configurable world parameters
  • run_simulation_e2e.sh — local end-to-end runner
  • summarize_result.py — extracts and ranks the top DNA profiles
  • watch_ascii.exs — live ASCII visualization of the simulation as it runs
The ecosystem simulation is resource-intensive. Run prime_sweep_scale first to verify your cluster is healthy before attempting the full simulation workload.