Skip to content

quickstart.md

Latest commit

 

History

History
198 lines (133 loc) · 3.55 KB

quickstart.md

File metadata and controls

198 lines (133 loc) · 3.55 KB

Validate And Run Your First Workflow

This tutorial gets you from a fresh checkout to one validated workflow and one submitted job using a checked-in OtterDesk blueprint.

What You Will Do

By the end, you will have:

  • validated a local blueprint bundle
  • started the MirrorNeuron runtime
  • submitted one workflow
  • inspected job and run state

Before You Start

You need:

  • macOS, Linux, or WSL2
  • Python 3.11+
  • Docker
  • the mn CLI on your PATH

Elixir/Erlang are needed only when developing the BEAM runtime directly. If the CLI or local services are not ready yet, follow Installation.

Step 1: Validate A Checked-In Blueprint

From the workspace root:

mn blueprint validate otterdesk-blueprints/tax_form_ocr_capture_assistant

Expected output includes:

valid

This checks the manifest, service declarations, model requirements, and input contract without submitting a runtime job.

Step 2: Start The Runtime

mn runtime start

Expected output includes:

MirrorNeuron services started

If your local command prints a different success line, verify with:

mn runtime health
mn node list

Expected output includes a healthy runtime and either an empty local node list or one or more reachable runtime nodes.

Step 3: Run The Workflow

mn blueprint run --folder otterdesk-blueprints/tax_form_ocr_capture_assistant

Expected output includes:

Job submitted

The CLI may print live events, a job id, and a blueprint run id. Keep both ids for inspection commands.

Step 4: Inspect Jobs

mn job list

Expected output includes either:

Job ID

or:

No jobs found

Check a single job:

mn job status <job_id>

Expected output includes a status field such as running, completed, failed, or cancelled.

Step 5: Inspect Blueprint Runs

Show recent blueprint runs:

mn blueprint monitor

Inspect logs and events for one run:

mn blueprint tail <run_id>
mn blueprint logs <run_id>
mn blueprint export <run_id> --format markdown

Most run artifacts are written under:

$MN_HOME/runs/<run_id>/

Step 6: Try The Catalog Flow

List catalog blueprints:

mn blueprint list

Run a catalog blueprint by id:

mn blueprint run portfolio_risk_review_assistant

Use --update when you want to refresh the cached blueprint repository first:

mn blueprint run portfolio_risk_review_assistant --update

Security Basics

Before running bigger or third-party workflows:

  • Review manifest.json and payloads/.
  • Check whether a node uses HostLocal, DockerWorker, or OpenShell.
  • Check pass_env before secrets are exposed to workers.
  • Use mock, sample, or dry-run settings before external email, Slack, browser, or delivery adapters.
  • Treat live messages, browser data, and model outputs as untrusted input.

Read Security Model before exposing a runtime to other users or machines.

Troubleshooting

mn: command not found

Install the CLI or activate the project virtual environment. Then verify:

which mn
mn --help

Runtime connection refused

The runtime is not reachable.

mn runtime start
mn runtime health
mn node list

Model requirement failures

Install or inspect the required Docker Model Runner model:

mn model list
mn model doctor gemma4:e2b

Next Steps