Quick Start

npm install -g m8flow
m8flow run

Your browser opens automatically. Start building ML pipelines in seconds — no Docker, no config files, no cloud accounts.

Why M8Flow?

Most ML tooling forces you to write boilerplate, manage environments manually, or pay for cloud compute. M8Flow takes a different approach:

| Problem | M8Flow Solution | |---|---| | Writing pipeline code from scratch | Visual drag-and-drop node editor | | Complex environment setup | Automatic Python venv + dependency install | | No AI assistance for ML workflows | Built-in AI pipeline generation (OpenRouter / Gemini / Mistral) | | Vendor lock-in and cloud costs | 100% local-first — your machine, your data | | Slow iteration cycles | Live pipeline execution with real-time logs |

Features

• Visual drag-and-drop pipeline builder — connect nodes with edges, no boilerplate
• AI-assisted workflow generation — describe your pipeline in plain English
• Multi-provider AI support — OpenRouter, Google Gemini, Mistral La Plateforme
• Local-first architecture — all data stays on your machine
• Automatic environment setup — Python virtualenv + dependencies on first run
• 60+ built-in ML nodes — preprocessing, models, evaluation, visualization
• Custom Python components — add your own nodes with AI code generation
• CSV dataset handling — upload files, inspect schemas, feed into pipelines
• Pipeline versioning — save checkpoints, compare versions, roll back
• Real-time execution monitoring — live logs, node status, output previews
• Cross-browser state sync — flows persist across tabs and browsers via local server
• Port conflict auto-resolution — never manually kill a port again

Requirements

| Tool | Minimum | |--------|---------| | Node | 18.x | | Python | 3.8+ | | npm | 8.x |

Commands

m8flow run

Launches the complete local M8Flow environment.

Options:
  -p, --port <n>      Frontend port (default: 3000)
  -b, --backend <n>   Backend port  (default: 8000)
  --no-browser        Skip opening the browser automatically
  --verbose           Stream full backend logs
  -h, --help          Show help

m8flow run                           # standard launch
m8flow run --port 4000               # custom port
m8flow run --no-browser --verbose    # headless with logs

m8flow doctor

Diagnoses your environment before running.

m8flow doctor

  M8Flow Doctor  v1.1.3

    ✔  Node.js  (20.11.0)
    ✔  Python   (Python 3.11.5)
    ✔  Virtual environment
    ✔  Python dependencies
    ✔  Bundled assets
    ✔  Port Frontend (3000)  — free
    ✔  Port Backend  (8000)  — free

What happens when you run m8flow run

| Step | What M8Flow does | |------|-----------------| | 1 | Locates Python 3.8+ on your PATH | | 2 | Creates ~/.m8flow/ storage directories | | 3 | Creates an isolated Python virtualenv | | 4 | Installs all ML dependencies (once only — hash-cached) | | 5 | Auto-resolves port conflicts | | 6 | Starts FastAPI backend via uvicorn | | 7 | Serves the React frontend via Node HTTP server | | 8 | Waits for backend health check (up to 120 s) | | 9 | Opens http://localhost:3000 in your browser |

Architecture

m8flow run
├── Node.js CLI (bin/m8flow.js)
│   ├── Python venv setup  →  ~/.m8flow/venv/
│   ├── Frontend server    →  localhost:3000   (Node static)
│   └── Backend server     →  localhost:8000   (uvicorn)
│
├── Frontend  — React + XYFlow canvas, Zustand state
│   └── Visual node editor, AI chat, dataset manager
│
└── Backend   — FastAPI + Python runtime
    ├── Pipeline executor  (topological DAG execution)
    ├── LLM service        (OpenRouter / Gemini / Mistral)
    ├── Self-healer        (AI auto-fix on node errors)
    └── Template library   (60+ pre-built ML components)

| Layer | Technology | |---|---| | Frontend | React, XYFlow, Zustand, Vite | | Backend | FastAPI, Python, uvicorn | | Runtime | Isolated Python virtualenv | | CLI | Node.js 18+, ESM, execa | | AI Layer | OpenRouter · Google Gemini · Mistral La Plateforme | | Storage | Local filesystem (~/.m8flow/) |

AI Keys

M8Flow works without any API key (demo mode with limited models). For full AI pipeline generation, add at least one key in Settings → API Keys:

| Provider | Key prefix | Models | |---|---|---| | OpenRouter | sk-or-... | Llama 3.3, NVIDIA Nemotron, Gemma, and 200+ more | | Google Gemini | AIza... | Gemini 2.5 Flash, Flash Lite, Pro | | Mistral | any | Codestral, Mistral Small, Mixtral |

Keys are stored locally in your browser and on your machine — never sent to M8Flow servers.

Data & Storage

Everything lives on your machine:

| Path | Contents | |------|---------| | ~/.m8flow/uploads/ | Uploaded CSV datasets | | ~/.m8flow/models/ | Trained model files | | ~/.m8flow/pipelines/ | Saved pipeline state | | ~/.m8flow/venv/ | Python virtualenv | | ~/.m8flow/app_state.json | Flows, projects, settings |

Build from Source

git clone https://github.com/mursaleen231213/m8flow
cd m8flow

# Build React frontend + bundle Python backend
node cli/scripts/build.js

# Install locally
cd cli && npm install -g .

# Launch
m8flow run

Push updates to npm

cd cli
npm version patch          # bump version
npm publish --otp=<code>   # publish (OTP from authenticator)

Uninstall

npm uninstall -g m8flow

# Remove all local data (optional):
rm -rf ~/.m8flow          # Mac/Linux
Remove-Item -Recurse -Force "$env:USERPROFILE\.m8flow"  # Windows