modusflow 1.0.0

A self-hostable, zero-cost, local-first automation platform for creating and running visual workflows

ModusFlow

A self-hostable, zero-cost, local-first automation platform for creating and running visual workflows.

Features

• 🎨 Visual Workflow Editor: Drag-and-drop interface using React Flow
• 🤖 AI-Assisted Generation: Generate workflows from plain English prompts
• ⚡ Async DAG Engine: Parallel execution where possible
• 💾 Local-First: SQLite for history, JSON/YAML for workflows (Git-friendly)
• 🖥️ CLI Tool: Headless execution and validation
• 🔧 Node Types: Python scripts, HTTP requests, AI models, Shell commands, Delays
• 📊 Live Logging: Real-time execution logs per node
• 💰 Cost Estimation: Token and cost tracking for AI nodes
• 🔄 Error Handling: Retries, on_fail paths, custom error handling

Quick Start

Prerequisites

• Python 3.8+
• Node.js 16+
• (Optional) API keys for AI providers (Anthropic, OpenAI, or OpenRouter)

Backend Setup

cd backend
pip install -r requirements.txt

# Copy .env.example to .env and add your API keys
cp .env.example .env

# Start the backend
uvicorn app.main:app --reload --port 8000

Frontend Setup

cd frontend
npm install
npm run dev

Visit http://localhost:5173 to access the visual editor.

CLI Installation

cd cli
pip install -e .

CLI Usage

# Run a workflow
modusflow run data/workflows/example_web_scraper.json

# Generate a workflow from a prompt
modusflow generate "scrape a website and summarize with AI" -o my_workflow.json

# Validate a workflow
modusflow validate data/workflows/example_web_scraper.json

Architecture

• Backend: FastAPI + Python async execution engine
• Frontend: React + TypeScript + React Flow + Monaco Editor
• Storage:
  • SQLite database for execution history (data/modusflow.db)
  • JSON/YAML files for workflows (data/workflows/*.json)
• AI: Free-tier LLMs via Anthropic (Claude Haiku), OpenAI (GPT-3.5), or OpenRouter

Node Types

Python Node

Execute Python code. Output should be JSON-printable or plain text.

import json
result = {"message": "Hello, World!"}
print(json.dumps(result))

HTTP Node

Make HTTP requests (GET, POST, PUT, DELETE, PATCH).

{
  "url": "https://api.example.com/data",
  "method": "GET",
  "headers": {"Authorization": "Bearer token"}
}

AI Node

Call AI models (Claude, GPT, etc.).

{
  "provider": "anthropic",
  "model": "claude-3-haiku-20240307",
  "prompt": "Summarize: ${previous_node}",
  "system_prompt": "You are a helpful assistant."
}

Shell Node

Execute shell commands.

{
  "command": "ls -la | head -10"
}

Delay Node

Wait for a specified duration.

{
  "seconds": 2.5
}

Using Node Outputs

Reference outputs from previous nodes using ${node_id} syntax:

{
  "prompt": "Summarize this: ${fetch_node}"
}

Error Handling

• Retries: Set retries and retry_delay on any node
• On-Fail Path: Set on_fail to a node ID that executes on failure
• Status Tracking: Each node tracks success/failure status

Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

# Or build manually
docker build -t modusflow .
docker run -p 8000:8000 -v $(pwd)/data:/app/data modusflow

Development

Project Structure

ModusFlow1/
├── backend/           # FastAPI backend
│   ├── app/
│   │   ├── main.py   # FastAPI app
│   │   ├── executor.py  # DAG execution engine
│   │   ├── ai_client.py  # AI provider clients
│   │   ├── routes/      # API routes
│   │   └── models.py    # Pydantic models
│   └── requirements.txt
├── frontend/         # React frontend
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── store/       # Zustand state
│   │   └── types.ts     # TypeScript types
│   └── package.json
├── cli/              # CLI tool
│   └── modusflow/
│       └── cli.py
└── data/             # Data directory
    ├── workflows/    # Workflow JSON files
    └── modusflow.db  # SQLite database

License

MIT