MirrorNeuron Documentation
Documentation for MirrorNeuron Documentation.
MirrorNeuron Documentation
MirrorNeuron is a durable runtime and control plane for adaptive, message-driven AI workflows. It runs on a laptop, on edge boxes, or across a small cluster.
The documentation has two goals:
- A new user should install, configure, run, and safely test MirrorNeuron in under 10 minutes.
- A new contributor should understand the architecture well enough to make a small pull request in under one hour.
Start Here
- README: project overview, quick start, and doc map.
- Component Guide: choose the right folder and validation command.
- Quickstart: validate and run your first workflow.
- Installation: install runtime dependencies and start local services.
- Security Model: understand what powers you are giving the runtime.
- Troubleshooting: common setup, Redis, OpenShell, and cluster errors.
Documentation Map
| Page | Type | Use it when |
|---|---|---|
| Component Guide | Overview | You need the repository map, folder responsibilities, and local validation commands. |
| Quickstart | Tutorial | You want the shortest path to first success. |
| Installation | Tutorial | You need to install Redis, OpenShell, Elixir, and Python tooling. |
| Examples | Tutorial | You want to choose the right checked-in blueprint. |
| Skill Catalog | Reference | You need centralized summaries for reusable skill packages. |
| Cluster Guide | How-to | You need to start or inspect a multi-box runtime. |
| Nomad-Inspired Runtime Features | Overview | You want the status and code map for reconciliation, job types, policies, drain, services, resources, deployments, and schedules. |
| Redis High Availability | How-to | You need Redis Sentinel failover. |
| Monitor Guide | How-to | You need to inspect live jobs and events. |
| CLI Reference | Reference | You need exact CLI commands and options. |
| Environment Variables | Reference | You need config names, defaults, and effects. |
| API Reference | Reference | You need HTTP or Elixir API shapes. |
| Job Bundle Format | Reference | You are writing or validating manifest.json. |
| Python SDK | Reference | You want to compile Python workflow definitions into bundles. |
| Blueprint Standard | Reference | You need the cross-blueprint contract for manifests, run stores, agents, aliases, artifacts, privacy, and UI surfaces. |
| Services and Health Checks | How-to | You need service declarations, registry lookup, or required service preflight. |
| Model Runtime | How-to | You need to install, inspect, validate, or use local Docker Model Runner LLMs. |
| Docker and OpenShell for Blueprints | How-to | You need local files, ports, web UIs, host services, or sandbox resources to work first time. |
| Resources and Devices | Reference | You need CUDA, Metal, GPU memory, ports, volumes, or runtime-driver placement. |
| Deployments | How-to | You need rolling, canary, promotion, rollback, or versioned long-running jobs. |
| Schedules and Events | How-to | You need cron, delayed, or event-triggered jobs. |
| Runtime Architecture | Explanation | You want the control-plane/execution-plane mental model. |
| Cluster Architecture | Explanation | You want leader, node, and relocation behavior. |
| Reliability Guide | Explanation | You want recovery, leases, backpressure, and retention behavior. |
| Security Model | Explanation | You need trust boundaries and safe defaults. |
| Blueprints and Skills | How-to | You are extending MirrorNeuron safely. |
| Testing | Reference | You need the test matrix and commands. |
| Contributing | Tutorial | You are preparing a pull request. |
| Documentation Style | Reference | You are editing docs. |
First Safe Workflow
After Redis and the runtime are started, run the smallest checked-in workflow:
mn blueprint run message_routing_traceExpected output:
Job submitted successfullySecurity Quick Read
MirrorNeuron can run local commands, create sandboxes, call APIs, pass selected secrets into workers, and coordinate jobs across boxes. Before using it in a shared or production environment:
- Review every bundle before running it.
- Keep
pass_envnarrow. - Prefer OpenShell over HostLocal for less-trusted worker code.
- Keep Redis protected and use Redis Sentinel for multi-box reliability.
- Change
MN_COOKIEfor any non-local cluster. - Bind API/gRPC listeners only to trusted networks.
Read Security Model for the full checklist.
Contributor Path
- Read Runtime Architecture.
- Run Testing commands.
- Make a small focused change.
- Update docs when behavior changes.
- Use the Contributing checklist before opening a PR.