# MirrorNeuron Docs (/docs/README)



# MirrorNeuron Docs [#mirrorneuron-docs]

Documentation for MirrorNeuron, including installation, architecture, CLI usage, blueprint development, security, and troubleshooting.

## Project Scope [#project-scope]

MirrorNeuron is an Elixir/BEAM runtime with Python tooling for running message-driven workflow graphs. The documentation covers:

* Runtime architecture and clustering.
* Local installation and first-run setup.
* CLI, API, SDK, Web UI, blueprints, and skills.
* Security considerations for running worker payloads.
* Troubleshooting and contribution guidance.

## Prerequisites [#prerequisites]

* macOS, Linux, or WSL2.
* Python 3.11+ for CLI, SDK, API, system tests, and Python-defined blueprints.
* Docker for the default local Redis and core workflow.
* Redis for runtime state.
* OpenShell when running sandboxed workers.

Elixir/Erlang are required for core runtime development. Released-package installs use OTP tarballs instead of building the core from source.

## Quick Start [#quick-start]

Install MirrorNeuron from released packages:

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

Start the runtime and run a sample blueprint:

```bash
mn runtime start
mn blueprint run message_routing_trace
mn blueprint monitor
```

Check jobs:

```bash
mn job list
mn node list
```

## Architecture Summary [#architecture-summary]

```text
CLI / API / Web UI
      |
      v
BEAM runtime: jobs, agents, routing, leases, recovery, events
      |
      v
Execution runners: HostLocal, OpenShell, Python, shell, worker payloads
      |
      v
Redis durable state and optional Redis Sentinel HA
```

Read:

* [Runtime Architecture](runtime-architecture.md)
* [Cluster Architecture](cluster_architecture.md)
* [Nomad-Inspired Runtime Features](nomad-inspired-runtime.md)
* [Security Model](security.md)

## Documentation Index [#documentation-index]

| Topic                               | Document                                                                             |
| ----------------------------------- | ------------------------------------------------------------------------------------ |
| Repository/component guide          | [component-guide.md](component-guide.md)                                             |
| Skill catalog                       | [skill-catalog.md](skill-catalog.md)                                                 |
| Getting started                     | [quickstart.md](quickstart.md)                                                       |
| Installation                        | [installation.md](installation.md)                                                   |
| CLI reference                       | [cli.md](cli.md)                                                                     |
| Blueprints and skills               | [blueprints-and-skills.md](blueprints-and-skills.md)                                 |
| Blueprint standard                  | [blueprint-standard.md](blueprint-standard.md)                                       |
| Docker and OpenShell for blueprints | [docker\_and\_openshell\_for\_blueprints.md](docker_and_openshell_for_blueprints.md) |
| Nomad-inspired runtime features     | [nomad-inspired-runtime.md](nomad-inspired-runtime.md)                               |
| Services and health checks          | [services-and-health-checks.md](services-and-health-checks.md)                       |
| Model runtime                       | [model-runtime.md](model-runtime.md)                                                 |
| Resources and devices               | [resources-and-devices.md](resources-and-devices.md)                                 |
| Deployments                         | [deployments.md](deployments.md)                                                     |
| Schedules and events                | [schedules-and-events.md](schedules-and-events.md)                                   |
| Runtime architecture                | [runtime-architecture.md](runtime-architecture.md)                                   |
| Cluster architecture                | [cluster\_architecture.md](cluster_architecture.md)                                  |
| Reliability and recovery            | [reliability.md](reliability.md)                                                     |
| Security                            | [security.md](security.md)                                                           |
| Troubleshooting                     | [troubleshooting.md](troubleshooting.md)                                             |
| Contributing                        | [contributing.md](contributing.md)                                                   |

## Security Notes [#security-notes]

MirrorNeuron can run local code, create sandboxes, call external services, connect to model providers, and pass selected environment variables to worker payloads.

Before running third-party bundles or exposing a cluster:

* Keep runtime API and gRPC ports bound to trusted networks.
* Review bundle `manifest.json`, `payloads/`, `pass_env`, and runner policies.
* Use OpenShell policies for untrusted network access.
* Do not pass broad secrets into workers.
* Prefer Redis Sentinel HA over single Redis for multi-box deployments.
* Treat incoming live messages, emails, Slack events, and model outputs as untrusted input.

## Contributing [#contributing]

Keep docs concise and command examples copyable. When documenting behavior, link to the relevant component README or source file when practical.

## License [#license]

See [LICENSE](LICENSE).