MirrorNeuron ships a terminal monitor designed to give you the same operational overview you would expect from a lightweight web dashboard — without leaving your terminal. Whether you are watching a single local job or inspecting a two-box cluster under load, the monitor and its companion CLI commands give you everything you need to understand what is running, where agents are placed, and what happened when something goes wrong.
Start the monitor
The monitor opens a terminal dashboard. No additional configuration is required for local use.
What the monitor shows
At the overview level, the monitor displays:
- connected cluster nodes
- executor pool usage
- all visible jobs with their current status
- how many boxes (runtime nodes) each job is using
- sandbox count per job
- the last significant event for each job
At the job detail level, open any job to see:
- job summary and current status
- runtime footprint (which nodes the job is using)
- active sandboxes
- agents and their individual statuses
- recent events
Navigating the monitor
Once the monitor is open, use the following controls:
| Key | Action |
|---|
| Type a row number | Open the job at that row |
| Type a full job ID | Open that job directly |
r | Refresh the current view |
b | Go back to the overview |
q | Quit the monitor |
Understanding monitor values
Boxes
The boxes column in the overview shows how many distinct runtime nodes appear in the job’s agent snapshots. A job running entirely on one machine shows 1. A distributed job spread across two nodes shows 2.
Sandboxes
The sandbox count is derived from executor snapshots and sandbox-related events. For short-lived executor jobs, this gives you a practical operational picture without needing to inspect OpenShell directly.
Status values
Job statuses
Agent statuses
| Status | Meaning |
|---|
pending | Job submitted, not yet started |
running | Job is actively executing |
completed | Job finished successfully |
failed | Job encountered an unrecoverable error |
cancelled | Job was manually cancelled |
| Status | Meaning |
|---|
ready | Agent initialized, waiting for input |
busy | Agent is actively processing a message |
queued | Agent has work pending |
running | Agent is executing in a sandbox |
completed | Agent finished its work |
error | Agent encountered an error |
paused | Agent was explicitly paused |
Filter to running jobs only
To hide completed and failed jobs and focus on what is currently active:
./mirror_neuron monitor --running-only
JSON mode
Use --json to emit the monitor data as structured JSON instead of rendering the terminal UI. This is useful for automation, scripting, or feeding data into an external dashboard.
./mirror_neuron monitor --json
JSON mode is a stable output format suitable for building monitoring integrations on top of MirrorNeuron without relying on screen-scraping the terminal UI.
Monitor a cluster
When running on multiple nodes, pass the cluster IP addresses so the monitor can attach to the distributed runtime:
./mirror_neuron monitor \
--box1-ip 192.168.4.29 \
--box2-ip 192.168.4.35 \
--self-ip 192.168.4.29
Additional cluster options
| Flag | Description |
|---|
--seed-ip <ip> | Specify a seed node IP for initial cluster discovery |
--redis-host <host> | Redis hostname (defaults to the box 1 IP) |
--redis-port <port> | Redis port |
--cookie <cookie> | BEAM distribution cookie |
--cli-port <port> | Port for the CLI control connection |
Programmatic monitoring with CLI commands
For scripting or integration workflows, use the CLI commands directly instead of the interactive monitor.
List all jobs
Poll continuously with --live:
./mirror_neuron job list --live
Inspect a specific job
./mirror_neuron job inspect <job_id>
List agents for a job
./mirror_neuron agent list <job_id>
View the event log
./mirror_neuron events <job_id>
- message routing decisions
- lease acquisition and renewal events
- sandbox start and completion events
- agent status transitions
- error details
Use events when the monitor shows unexpected agent statuses or a job stalls. The event sequence reveals exactly where in the workflow execution diverged from your expectations.
When to use the monitor versus CLI commands
Use ./mirror_neuron monitor when you want a live operational overview — identifying active jobs, checking sandbox counts, or watching agent placement across nodes.
Use ./mirror_neuron job inspect, agent list, and events when you need precise, scriptable output for a specific job — debugging a failure, integrating with CI, or feeding data into another tool. 