Skip to main content
Before you submit a workflow for execution, validating your job bundle catches structural errors early — saving you from ambiguous runtime failures. This guide covers the full loop: validating a bundle, submitting it in different modes, setting a timeout, and inspecting jobs, agents, and events once a run completes.

​
Validate a job bundle

Run validate against any job bundle folder before you attempt to execute it. This checks the bundle structure, parses manifest.json, and verifies all node and edge relationships. 
./mirror_neuron validate examples/research_flow
The validator reports:
  • bundle structure issues
  • manifest syntax errors
  • missing or malformed node and edge definitions
  • entrypoint problems
Fix any errors reported before proceeding to run.

​
Run a workflow

​
Interactive mode

The default mode renders a live terminal view as the workflow executes. 
./mirror_neuron run examples/research_flow
The CLI displays:
  • a banner with job metadata
  • a job submission confirmation card
  • a live progress panel that updates as agents advance
  • a final run summary when the job completes
Interactive mode is the best choice for manual runs and debugging.

​
JSON mode

Use --json when you need machine-readable output, such as in CI pipelines or scripts that parse the result. 
./mirror_neuron run examples/research_flow --json
JSON mode suppresses the interactive UI and writes structured output to stdout instead.

​
Detached mode

Use --no-await to submit the job and return immediately without waiting for it to complete. The workflow continues running in the background. 
./mirror_neuron run examples/divisibility_monitor --no-await
Detached mode is particularly useful for long-lived workflows that run until manually cancelled. Use ./mirror_neuron monitor to observe them after submission.

​
Setting a timeout

Pass --timeout with a value in milliseconds to bound how long the CLI waits for the job to finish. 
./mirror_neuron run examples/research_flow --timeout 10000
If the job does not complete within the timeout window, the CLI exits. The job itself continues running on the server unless you explicitly cancel it.

​
Inspect a completed job

After a run completes — or while it is still running — you can inspect its state directly from the CLI.

​
View job details

./mirror_neuron job inspect <job_id>
This returns the current job status, timestamps, and a summary of the agent graph.

​
List agents for a job

./mirror_neuron agent list <job_id>
This shows each agent in the job alongside its current status. Typical agent statuses are ready, busy, queued, running, completed, error, and paused.

​
List all jobs

./mirror_neuron job list
Add --live to poll continuously: 
./mirror_neuron job list --live

​
Check runtime nodes

./mirror_neuron node list
On a single machine this usually returns one node. On a cluster it shows all connected peers.

​
View job events

Events give you a sequential log of what happened during execution — message routing decisions, sandbox completions, lease acquisitions, and errors. 
./mirror_neuron events <job_id>
Events are especially useful when debugging message flow between agents or diagnosing why a sandbox worker did not complete as expected.

​
Control a running job

You can pause, resume, or cancel a job at any time. 
./mirror_neuron pause <job_id>

​
Send a message to an agent

For sensor-style workflows or manual testing, you can inject a message directly into a running agent. 
./mirror_neuron send <job_id> <agent_id> '{"type":"manual_result","payload":{"ok":true}}'
The message must be a valid JSON object. The type field determines how the receiving agent processes it.

​
Example: full run and inspect sequence

The following sequence validates, runs, and inspects the built-in research_flow example end to end.
1

Validate the bundle

./mirror_neuron validate examples/research_flow
Confirm the output shows no errors before continuing.
2

Run the workflow

./mirror_neuron run examples/research_flow
Watch the progress panel. Note the job ID printed in the submission card — you will need it in the next steps.
3

Inspect the job

./mirror_neuron job inspect <job_id>
4

List agents

./mirror_neuron agent list <job_id>
All agents should show completed status after a successful run.
5

Review events

./mirror_neuron events <job_id>
Scan the event log to confirm the expected message flow occurred.