MirrorNeuron Core 🧠

Desktop-first runtime for durable, self-organizing AI workflows.

MirrorNeuron Core is the Elixir/OTP runtime at the center of the MirrorNeuron project: a durable, message-driven foundation for AI workflows that need to keep running, recover cleanly, and coordinate work across agents, services, and local machines.

MirrorNeuron is built around a simple direction: software is moving from hardcoded workflows and static UIs toward reusable intelligence. An agent should be able to assemble the workflow logic and task-specific interface it needs at runtime, while the infrastructure underneath stays deterministic, observable, and reliable.

Core is that infrastructure layer. It runs workflow graphs, stores job state, routes messages between runtime nodes and agents, records events, coordinates local or clustered execution, and exposes gRPC services for the surrounding MirrorNeuron ecosystem.

Important

MirrorNeuron is in alpha. APIs, manifests, release artifacts, and ecosystem components may change between releases.

Why MirrorNeuron Core exists
Desktop runtime, not cloud runtime
Private swarm model
Hardware strategy
The idea: generated software, deterministic runtime
Features
Architecture at a glance
When to use this repository
Quick install
Local development
Usage
Resource-aware scheduling preview
Adaptive runtime reliability
Execution profiles
Configuration highlights
API boundary
Project structure
Testing
Deployment and releases
Troubleshooting
Ecosystem
Documentation
Roadmap
Contributing
Security
License

Why MirrorNeuron Core exists

Most agent prototypes begin as a prompt, a script, or a tightly coupled workflow UI. That works until the work becomes long-running, multi-step, interruptible, or spread across more than one process. At that point, the agent needs more than a model call: it needs a runtime.

MirrorNeuron Core focuses on the deterministic side of agentic software.

Durable execution	Run workflow graphs with persisted job state, event history, terminal state, and recovery-aware runtime behavior.
Desktop-first operation	Target local desktops, workstations, and private multi-computer swarms instead of requiring a managed cloud control plane.
Message-driven coordination	Route work between agents and services through explicit runtime messages instead of hidden in-process coupling.
Resource-aware placement	Plan service and batch agents onto eligible runtime nodes using CPU, memory, disk, GPU, constraints, and execution profiles.
Self-healing by design	Use OTP supervision, reconnect policies, reliability strategies, persisted state, and cluster health checks to keep local workflow execution recoverable.
Stable service boundary	Expose protobuf-backed gRPC services so CLIs, SDKs, APIs, agents, blueprints, and tools can share the same runtime core.

The goal is to let the edge of the system stay flexible — generated interfaces, generated workflow logic, task-specific agents — while the center of the system stays boring in the best possible way: stateful, testable, recoverable, and explicit.

Desktop runtime, not cloud runtime

MirrorNeuron Core is designed for developers who want AI workflows to run on the machines they already own: a laptop, a workstation, a home lab box, a local GPU machine, or a small private swarm of trusted computers.

You should not need a complete Kubernetes-style platform to make desktop workflows reliable. Core borrows useful ideas from systems like Airflow and Nomad — durable runs, explicit job state, scheduling, placement constraints, resource admission, observability, and recovery — and reshapes them for local runtime environments.

Cloud-first orchestration
  cluster account + hosted control plane + infrastructure team + remote workers

MirrorNeuron Core
  desktop PC + local Redis + runtime nodes + private swarm when needed

This repository is not trying to be a cloud platform. The focus is local reliability: workflows that are easy to start, easy to inspect, and able to recover from ordinary desktop failures such as process restarts, flaky peer nodes, resource contention, or unavailable executors.

Private swarm model

A single desktop should be enough for many workflows. When more capacity is needed, Core can coordinate local or clustered execution across private machines. Think of it as a small, trusted runtime fabric for developer-owned hardware.

flowchart LR
  App[CLI / SDK / API / Local UI] --> GRPC[gRPC services]
  GRPC --> Core[MirrorNeuron Core]

  Core --> Scheduler[Resource-aware scheduler]
  Core --> Router[Message router]
  Core --> Events[Event log]
  Core --> State[(Redis job state)]
  Core --> Reliability[Reliability observer]

  Scheduler --> Local[Desktop runtime node]
  Scheduler --> Mac[Apple Silicon node]
  Scheduler --> GPU[NVIDIA / AMD GPU node]
  Scheduler --> CPU[Intel / AMD CPU node]

  Local --> Agents[Agents / Skills / Blueprints]
  Mac --> Agents
  GPU --> Agents
  CPU --> Agents

A private swarm is not a requirement. It is the scaling path when a workflow needs another machine: attach the node, advertise its capabilities, and let the runtime decide where eligible work can run.

Hardware strategy

MirrorNeuron Core aims to reduce the amount of hardware-specific work developers need to do. The workflow should describe what it needs; the runtime should match that need to available local capacity.

The current runtime surface already includes node capabilities, GPU advertising, resource admission, scheduler constraints, and execution profiles. The hardware target is ordinary developer-owned compute:

Hardware class	Runtime direction
Intel / AMD CPUs	Treat standard CPU machines as first-class runtime nodes for generic workflow and model work.
Apple Silicon	Treat local macOS arm64 machines as useful runtime capacity when the execution profile and model backend fit.
NVIDIA GPUs	Advertise GPU capacity and capabilities so accelerator-heavy agents can be placed on eligible nodes.
AMD GPUs	Keep GPU placement generic enough that supported backends can advertise AMD GPU capacity where available.
Specialized boxes	When a workflow needs dedicated acceleration, surface that requirement clearly so the user can attach a capable machine — for example, a dedicated NVIDIA workstation or accelerator box — to the private swarm instead of rewriting the workflow.

The intended developer experience is simple: run the workflow. If the workflow can run on available generic hardware, the runtime should allocate resources and use the right execution profile. If it needs special hardware, the runtime should make that visible early and tell the developer what kind of node must be added.

The idea: generated software, deterministic runtime

MirrorNeuron is designed for a different shape of application: one where the agent can generate or adapt the logic and interface it needs while the runtime remains explicit and dependable.

Traditional app
  fixed UI + fixed workflow + hidden state

Agent-native app
  generated task interface + generated workflow logic + deterministic runtime

For developers, MirrorNeuron Core is the lower-level runtime that other pieces build on: scheduling, coordination, events, persistence, clustering behavior, resource admission, reliability policies, and service contracts.

That separation matters. Agents can reorganize the software experience at runtime, but workflow execution should still have clear state, clear ownership, clear placement, and clear recovery behavior.

Features

Feature	Status	Notes
Workflow manifest validation	Available	Validates graph structure and supported runtime primitives.
Message-driven execution	Available	Routes workflow messages between runtime nodes and agents.
Built-in runtime primitives	Available	Includes `router`, `executor`, `aggregator`, `sensor`, and `module`.
Durable job state	Available	Persists job metadata, events, agents, and terminal state through Redis.
Runtime monitoring	Available	Lists jobs, job details, cluster overview, metrics, and dead letters.
Cluster coordination	Available	Uses Erlang distribution plus `libcluster` and Horde.
Redis high-availability helpers	Available	Includes scripts and config for Redis Sentinel development workflows.
Shared run artifacts	Available	Supports pre-mounted shared filesystem storage for large payloads and per-job artifact staging across LAN cluster nodes.
gRPC services	Available	Job, cluster, and observability protobuf services are included.
Resource-aware scheduling	Preview	Plans service and batch agents onto eligible nodes using CPU, memory, disk, GPU, constraints, and execution profiles.
REST API, CLI, Web UI, SDK	External components	Provided by separate ecosystem repositories.

Architecture at a glance

flowchart TB
  Manifest[Workflow manifest] --> Validate[Manifest validation]
  Validate --> Plan[Scheduler planning]
  Plan --> Run[Runtime-managed job]

  Run --> Agents[Workflow agents]
  Run --> Events[Event recording]
  Run --> State[(Redis-backed state)]
  Run --> GRPC[gRPC services]

  Agents --> Router[Message routing]
  Router --> Agents

  GRPC --> Clients[CLI / Python SDK / API / Web UI]

Core sits between higher-level developer surfaces and the operational substrate that keeps workflow execution reliable. Higher-level components can change how agents are authored, invoked, or presented to users without requiring each one to rebuild the runtime primitives from scratch.

When to use this repository

Use MirrorNeuron Core when you are building or extending systems that need:

AI workflows that continue across multiple steps instead of completing in one request-response turn.
Desktop or workstation execution with durable runtime behavior.
A private multi-computer swarm without adopting a cloud-first orchestration stack.
Agent coordination through messages and explicit runtime services.
Redis-backed job state for durable execution.
Event recording around workflow execution.
Resource-aware scheduling across CPU, memory, disk, GPU, constraints, and execution profiles.
A gRPC/protobuf boundary for integrating runtimes, SDKs, API services, agents, blueprints, or skills.

Core is not a model provider, hosted cloud service, monolithic desktop app, or complete Kubernetes replacement. It is the dependable runtime layer underneath agent-native workflow software.

Quick install

Use the deployment repository installer when installing MirrorNeuron as a user-facing local system:

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

For the released-package installer, use mn-deploy/install_new.sh from the deployment repository:

git clone https://github.com/MirrorNeuronLab/mn-deploy.git
cd mn-deploy
./install_new.sh

That installer uses released packages instead of source checkouts:

Core runtime from GitHub Release OTP tarballs
Python CLI/API/SDK packages from PyPI
Web UI package from npm

Local development

Clone the core repository and install dependencies:

git clone https://github.com/MirrorNeuronLab/MirrorNeuron.git
cd MirrorNeuron
mix deps.get

Start Redis locally or with Docker:

docker run --rm --name mirror-neuron-redis -p 6379:6379 redis:7

Run the runtime in development mode:

mix run --no-halt

Build a local OTP release:

MIX_PROJECT_VERSION=1.0.0 MIX_ENV=prod mix release --overwrite
_build/prod/rel/mirror_neuron/bin/mirror_neuron start

Usage

Validate a manifest

MirrorNeuron.validate_manifest("path/to/manifest.json")

Plan placement before running

MirrorNeuron.plan_manifest("path/to/manifest.json")

Run a manifest

MirrorNeuron.run_manifest("path/to/manifest.json")

Inspect jobs and events

MirrorNeuron.list_jobs()
MirrorNeuron.inspect_job("job-id")
MirrorNeuron.inspect_agents("job-id")
MirrorNeuron.events("job-id")

Pause, resume, or cancel a job

MirrorNeuron.pause("job-id")
MirrorNeuron.resume("job-id")
MirrorNeuron.cancel("job-id")

Resource-aware scheduling preview

MirrorNeuron can plan service and batch workflow agents onto eligible runtime nodes before starting a job. Node-level resources and constraints may be declared in the manifest, and policies.scheduler.strategy can be binpack or spread.

{
  "policies": {
    "job_type": "batch",
    "scheduler": { "strategy": "binpack" }
  },
  "nodes": [
    {
      "node_id": "worker",
      "agent_type": "executor",
      "resources": {
        "cpu_cores": 2,
        "memory_mb": 4096,
        "gpu_count": 1
      },
      "constraints": [
        { "attribute": "capabilities", "operator": "contains", "value": "cuda" }
      ]
    }
  ]
}

Submitted jobs persist their scheduler plan under the job's scheduler field so API and monitoring clients can inspect where agents were intended to run.

Adaptive runtime reliability

Manifests may set "recovery_mode": "auto" or omit recovery_mode. For new jobs, the runtime resolves the requested policy into an effective policy based on observed cluster health:

Runtime condition	Effective behavior
Single node or uncertain/flapping cluster	Use `local_restart`.
Healthy multi-node cluster with a durable bundle and eligible placement	Use `cluster_recover`.
Explicit `manual_recover`	Keep manual recovery.
Explicit `cluster_recover` on an unsafe single-node cluster	Start degraded as `local_restart`.

The runtime persists both requested_recovery_policy and effective recovery_policy, plus a compact reliability map for observability. Running job policies are not rewritten when cluster health changes; reliability events are emitted instead.

This is especially important for desktop environments, where machines sleep, restart, disconnect, run out of local resources, or appear and disappear from a private network more often than cloud workers do.

Execution profiles

Dependency-heavy agents should reference an execution profile instead of installing native packages during each run. Configure the profile on runtime nodes, then reference it from the worker config.

MN_EXECUTION_PROFILES_JSON='{"opencv-video-guardian":{"image":"registry.local/business_facility_safety_video_guardian:2026-05","pool":"opencv_gpu","pool_slots":1,"gpu":true,"required_capabilities":["video-codec:h264"],"policy":"policies/video-egress.yaml","reuse_shared_sandbox":true,"persistent_workspace":true,"warmup_command":"python -c \"import cv2\""}}' \
MN_NODE_EXECUTION_PROFILES=opencv-video-guardian \
MN_NODE_CAPABILITIES=video-codec:h264,ffmpeg \
mix run --no-halt

{
  "node_id": "video_guardian",
  "agent_type": "sandbox_worker",
  "config": {
    "execution_profile": "opencv-video-guardian"
  }
}

The BEAM runtime keeps orchestration, leases, placement, reconnect, and manual recovery. Heavy dependencies such as OpenCV, ffmpeg, and model runtimes stay in the profile image or a prewarmed node cache. When a manifest selects an execution profile, the profile owns OpenShell security settings such as image, policy, remote access, SSH key, workspace reuse, upload path, pool, GPU, and capability settings.

Configuration highlights

Runtime configuration is read from environment variables in config/runtime.exs.

Variable	Purpose
`MN_REDIS_URL`	Redis connection URL for persisted runtime data.
`MN_REDIS_NAMESPACE`	Prefix/namespace for stored MirrorNeuron runtime data.
`MN_RECOVERY_EVAL_TTL_SECONDS`	Retention for terminal recovery eval diagnostics; defaults to 86400.
`MN_CORE_HOST`	Host/IP used by the gRPC listener; defaults to loopback-style local binding.
`MN_GRPC_PORT`	gRPC service port.
`MN_GRPC_AUTH_TOKEN`	Bearer token for protected gRPC calls such as pause, resume, and resource updates.
`MN_GRPC_ADMIN_TOKEN`	Required token for destructive administrative calls such as `ClearJobs`.
`MN_NODE_NAME`	Erlang node name used by release and cluster scripts.
`MN_CLUSTER_NODES`	Comma-separated Erlang node names for cluster discovery.
`MN_COOKIE`	Erlang distribution cookie; use a strong non-default value for distributed nodes.
`MN_JOB_LEASE_DURATION_MS`	Job lease duration for fenced runtime ownership; defaults to 60000.
`MN_JOB_LEASE_RENEW_INTERVAL_MS`	Job lease renewal cadence; defaults to 10000.
`MN_JOB_CALL_TIMEOUT_MS`	Timeout for runtime job control calls such as pause, resume, cancel, pressure, and external message submit; defaults to 15000.
`MN_DELIVERY_RETRY_ATTEMPTS`	Number of agent lookup retries before a delivery becomes a dead letter; defaults to 50.
`MN_DELIVERY_RETRY_INTERVAL_MS`	Delay between delivery lookup retries; defaults to 50.
`MN_RELIABILITY_STRATEGY`	Conservative runtime strategy resolver for new jobs.
`MN_NODE_RECONNECT_ATTEMPTS`	Runtime node reconnect attempts before jobs are paused for manual restart.
`MN_NODE_EXECUTION_PROFILES`	Comma-separated execution profiles this runtime node may advertise after warmup.
`MN_NODE_CAPABILITIES`	Comma-separated runtime capabilities such as `video-codec:h264` or `ffmpeg`.
`MN_NODE_GPU`	Optional override for whether this runtime node advertises GPU capacity.
`MN_RESOURCE_ADMISSION_ENABLED`	Enables local resource checks before accepting work.
`MN_BLOB_STORE_ROOT`	Durable content-addressed blob root. In LAN clusters, point this at a host-mounted NFS path such as `/root/.mn/shared/blobs`.
`MN_JOB_ARTIFACT_ROOT`	Per-job artifact staging root. Defaults next to the blob root and is cleaned when terminal jobs age out or are deleted.

For Redis Sentinel, resource thresholds, network-only nodes, execution profiles, and release deployment settings, check config/runtime.exs and the documentation repo.

Large job payloads are shared by filesystem path, not by a MirrorNeuron HTTP artifact server. For a LAN cluster, mount the same NFS export on every host and bind-mount it into each container at the same logical location. The Docker Compose default expects ${MN_HOST_SHARED_STORAGE_ROOT:-./mn/shared} to contain blobs/ for durable sha256 content and jobs/ for temporary per-job staging. MirrorNeuron does not start or expose NFS ports itself; the host OS owns the NFS mount lifecycle.

API boundary

MirrorNeuron Core includes protobuf definitions and generated Elixir modules for:

proto/job.proto
proto/cluster.proto
proto/observability.proto

Generated modules live under lib/mirror_neuron_grpc/. The gRPC listener binds to MN_CORE_HOST and listens on MN_GRPC_PORT.

JobService.ClearJobs is a destructive administrative RPC. It is denied unless the server has MN_GRPC_ADMIN_TOKEN set and the request includes the same value in admin_token.

ClusterService.NetworkHandshake is used by cluster join flows to verify the join token and keep network-facing nodes scoped to cluster/resource inspection when MN_NETWORK_ONLY=true.

Project structure

.
├── config/                  # Mix and runtime configuration
├── lib/
│   ├── mirror_neuron/       # Core runtime modules
│   └── mirror_neuron_grpc/  # Generated gRPC/protobuf modules
├── proto/                   # gRPC protobuf definitions
├── scripts/                 # Local, cluster, Redis, and release helper scripts
├── tests/                   # ExUnit tests and script-based regression checks
├── mix.exs                  # Mix project definition
├── mix.lock                 # Locked dependencies
├── RELEASE.md              # Release policy and tag workflow
└── LICENSE                 # MIT license

Testing

Install dependencies:

mix deps.get

Check formatting:

mix format --check-formatted

Run tests:

mix test

The default test lane is intended to be deterministic and CI-friendly. It uses in-process fakes for fast cluster join/leave behavior, fake executables for Docker/OpenShell command-shape checks, and Redis-backed tests when Redis is available in CI. Tests that require real third-party services such as Docker, OpenShell, Redis Sentinel failover, or multi-node infrastructure should be kept behind explicit tags or environment gates and run as a separate integration validation lane.

Compile with warnings as errors:

mix compile --warnings-as-errors

Run a local production release build:

MIX_PROJECT_VERSION=1.2.3 MIX_ENV=prod mix release --overwrite

Run shell syntax checks:

while IFS= read -r -d '' script; do
  bash -n "$script"
done < <(find scripts -name '*.sh' -print0)

Deployment and releases

MirrorNeuron Core is released from Git tags. Tags must use SemVer with a leading v, for example:

v1.0.1
v1.1.0
v2.0.0
v1.0.1-rc.1

The release workflow builds platform-specific OTP tarballs:

MirrorNeuron-vX.Y.Z-darwin-arm64-otp-release.tar.gz
MirrorNeuron-vX.Y.Z-linux-x64-otp-release.tar.gz
MirrorNeuron-vX.Y.Z-linux-arm64-otp-release.tar.gz
SHA256SUMS.txt

Create a stable release:

git checkout main
git pull
mix deps.get
mix format --check-formatted
mix test
git tag v1.0.1
git push origin v1.0.1

See RELEASE.md for the full release process.

Troubleshooting

Problem	Check
Runtime cannot connect to Redis	Confirm Redis is running and `MN_REDIS_URL` points to the correct host, port, and database.
gRPC port is already in use	Change `MN_GRPC_PORT` or stop the process using port `50051`.
Cluster nodes do not join	Verify `MN_NODE_NAME`, `MN_CLUSTER_NODES`, `MN_COOKIE`, EPMD connectivity, and Erlang distribution ports.
Resource admission rejects jobs	Check `MN_RESOURCE_ADMISSION_ENABLED` and resource threshold variables.
Expected GPU work is not placed on a node	Check `MN_NODE_GPU`, `MN_NODE_CAPABILITIES`, execution profiles, and manifest constraints.
Large blob payloads are missing on a peer node	Confirm every cluster host has the same NFS export mounted and that `MN_BLOB_STORE_ROOT` points at the shared `blobs/` directory.
Redis Sentinel failover is not resolving	Verify `MN_REDIS_SENTINELS`, `MN_REDIS_SENTINEL_MASTER`, credentials, and optional host mapping.
OTP release fails after extraction	Make sure the release asset matches the target OS and CPU architecture.

Ecosystem

Component	Repository
Core runtime	https://github.com/MirrorNeuronLab/MirrorNeuron
REST API	https://github.com/MirrorNeuronLab/mn-api
CLI	https://github.com/MirrorNeuronLab/mn-cli
Web UI	https://github.com/MirrorNeuronLab/mn-web-ui
Python SDK	https://github.com/MirrorNeuronLab/mn-python-sdk
Deployment tooling	https://github.com/MirrorNeuronLab/mn-deploy
System tests	https://github.com/MirrorNeuronLab/mn-system-tests
Blueprints	https://github.com/MirrorNeuronLab/mirrorneuron-blueprints
Documentation	https://github.com/MirrorNeuronLab/mn-docs

Documentation

Resource	What to read it for
MirrorNeuron documentation	Project-level architecture, component responsibilities, runtime model, and deployment expectations.
Component guide	How MirrorNeuron Core fits into the broader MirrorNeuron stack.
Runtime architecture	Runtime model and execution architecture.
Cluster architecture	Clustered runtime behavior and deployment shape.
Reliability guide	Reliability expectations and operational model.
Security model	Security assumptions and boundaries.

Roadmap

Current roadmap items should be tracked in issues or the documentation repository. Useful future additions to this README include:

A maintained compatibility matrix for OS, CPU architecture, model backend, accelerator type, and OTP release artifact.
A manifest schema reference.
A complete gRPC API reference.
More desktop and private-swarm deployment examples.
Screenshots or short recordings for CLI, Web UI, and workflow execution.

Contributing

Contributions are welcome. Before opening a pull request:

Run formatting and tests.
Keep changes scoped.
Add or update tests for behavior changes.
Update documentation when configuration, commands, or release behavior changes.

References:

Security

Do not disclose vulnerabilities in public issues.

Security model: https://github.com/MirrorNeuronLab/mn-docs/blob/main/security.md
Report a vulnerability: https://github.com/MirrorNeuronLab/MirrorNeuron/security

Acknowledgments

MirrorNeuron Core uses the Elixir/OTP ecosystem, Redis, gRPC, protobuf, Horde, and libcluster. See mix.exs and mix.lock for the current dependency list.

License

MirrorNeuron Core is licensed under the MIT License. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 247 Commits
.github/workflows		.github/workflows
config		config
lib		lib
priv		priv
proto		proto
protoc_install		protoc_install
scripts		scripts
tests		tests
.formatter.exs		.formatter.exs
.gitignore		.gitignore
.python-version		.python-version
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
docker-compose.yml		docker-compose.yml
mix.exs		mix.exs
mix.lock		mix.lock
node.alias		node.alias
protoc-25.3-osx-universal_binary.zip		protoc-25.3-osx-universal_binary.zip

Folders and files

Latest commit

History

Repository files navigation

MirrorNeuron Core 🧠

Contents

Why MirrorNeuron Core exists

Desktop runtime, not cloud runtime

Private swarm model

Hardware strategy

The idea: generated software, deterministic runtime

Features

Architecture at a glance

When to use this repository

Quick install

Local development

Usage

Validate a manifest

Plan placement before running

Run a manifest

Inspect jobs and events

Pause, resume, or cancel a job

Resource-aware scheduling preview

Adaptive runtime reliability

Execution profiles

Configuration highlights

API boundary

Project structure

Testing

Deployment and releases

Troubleshooting

Ecosystem

Documentation

Roadmap

Contributing

Security

Acknowledgments

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages