Skip to main content
This guide covers everything you need to install and run AutoMFlows on your system.

​
System Requirements

Node.js

Version 20 or newer required

npm

Included with Node.js installation

Disk Space

~1GB for dependencies and browser binaries

Operating System

Windows, macOS, or Linux

​
Installing Node.js

AutoMFlows requires Node.js 20 or newer. Choose your operating system below:

​
Windows

  1. Download the LTS (20.x) installer from nodejs.org
  2. Run the installer and follow the prompts
  3. Restart your terminal after installation

​
macOS

​
Linux

​
Verify Installation

After installing Node.js, verify the installation: 
node -v   # should be v20.x.x or higher
npm -v
If node -v shows a version lower than 20, you need to upgrade Node.js before proceeding.

​
Installing AutoMFlows

Once Node.js is installed, follow these steps to set up AutoMFlows:
1

Clone the repository

Clone the AutoMFlows repository from GitHub:
git clone https://github.com/ashxtrem/AutoMFlows.git
cd AutoMFlows
AutoMFlows uses an npm workspaces monorepo structure with backend, frontend, shared, and mcp-server packages.
2

Install dependencies

Install all workspace dependencies:
npm install
This command installs dependencies for all four workspaces:
  • backend: Express server with Playwright execution engine
  • frontend: React + ReactFlow visual editor
  • shared: TypeScript types and utilities
  • mcp-server: Model Context Protocol server for AI/IDE integration
The backend package has a postinstall script that automatically installs Playwright Chromium browser.
3

Build the shared package

The shared package must be built before running the application:
cd shared && npm run build && cd ..
This compiles TypeScript types and utilities that both backend and frontend depend on.
4

Install Playwright browsers (optional)

While Chromium is installed automatically, you can install additional browsers:
cd backend
npx playwright install chromium  # Already installed via postinstall
npx playwright install firefox
npx playwright install webkit
cd ..
AutoMFlows supports all three Playwright browsers:
  • Chromium: Fast and widely compatible
  • Firefox: Gecko engine support
  • WebKit: Safari engine support

​
Running AutoMFlows

AutoMFlows provides convenient startup scripts that handle the entire launch process: 
./start.sh
Make the script executable if needed:
chmod +x start.sh
./start.sh
The startup scripts automatically:
  • Install dependencies if needed
  • Install Playwright browsers (Chromium, Firefox, WebKit)
  • Build the shared package
  • Kill processes on conflicting ports (3003, 5173)
  • Start backend and frontend servers concurrently
  • Display access URLs and LAN IP (with --lan flag)

​
LAN Access

To access AutoMFlows from other devices on your network, use the --host or --lan flag: 
./start.sh --lan
The script will display your LAN IP address for access from other devices.

​
Manual Startup

You can also start the servers manually using npm workspace scripts:
Start backend and frontend in separate terminals:Terminal 1 - Backend:
npm run dev:backend
Terminal 2 - Frontend:
npm run dev:frontend
For LAN access (frontend):
npm run dev:frontend:host

​
Available npm Scripts

The root package.json defines these workspace scripts: 
{
  "scripts": {
    "dev:backend": "npm run dev --workspace=backend",
    "dev:frontend": "npm run dev --workspace=frontend",
    "dev:frontend:host": "npm run dev --workspace=frontend -- --host",
    "build": "npm run build --workspaces",
    "build:backend": "npm run build --workspace=backend",
    "build:frontend": "npm run build --workspace=frontend",
    "lint": "eslint backend/src frontend/src",
    "type-check": "npm run type-check --workspaces"
  }
}

​
Accessing the Application

Once the servers are running, access AutoMFlows at:

Frontend

Visual workflow builderhttp://localhost:5173

Backend API

RESTful API serverhttp://localhost:3003

Swagger Docs

Interactive API documentationhttp://localhost:3003/api-docs
If port 5173 is already in use, Vite will automatically use the next available port (5174, 5175, etc.). Check the terminal output for the actual URL.

​
Docker Installation

For containerized deployment, AutoMFlows includes Docker support:
1

Navigate to docker directory

cd docker
2

Build and run with Docker Compose

docker-compose up --build
The application will be available at http://localhost:3000.

​
Docker Configuration

The docker-compose.yml configuration: 
version: '3.8'

services:
  automflows:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
    volumes:
      - ./screenshots:/app/screenshots
    restart: unless-stopped
Screenshots are persisted to the ./screenshots directory on your host machine.

​
Workspace Structure

AutoMFlows uses npm workspaces for monorepo management: 
AutoMFlows/
├── backend/          # Express + Playwright execution engine
│   ├── src/
│   └── package.json
├── frontend/         # React + ReactFlow visual editor
│   ├── src/
│   └── package.json
├── shared/           # TypeScript types and utilities
│   ├── src/
│   └── package.json
├── mcp-server/       # Model Context Protocol server
│   └── package.json
├── plugins/          # Custom node plugins
├── docker/           # Docker configuration
├── start.sh          # Unix/Linux/macOS startup script
├── start.ps1         # Windows startup script
└── package.json      # Root workspace configuration

​
Environment Configuration

AutoMFlows works out of the box with sensible defaults. For advanced configuration:

​
Backend Configuration

The backend uses these environment variables:
  • PORT: Backend server port (default: 3003)
  • NODE_ENV: Environment mode (development or production)
  • HOST: Bind address (default: localhost, set to 0.0.0.0 for LAN access)

​
Frontend Configuration

The frontend (Vite) uses:
  • Default port: 5173
  • Use --host flag for LAN access
  • Vite automatically finds next available port if 5173 is in use

​
Troubleshooting

Ensure you have Node.js 20+ installed:
node -v
If the version is correct but install still fails, try:
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
Make sure TypeScript is installed:
cd shared
rm -rf dist node_modules
npm install
npm run build
Check for TypeScript errors in the output.
Manually install Playwright browsers:
cd backend
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit
If that fails, you may need to install system dependencies:
# Linux
npx playwright install-deps

# macOS - usually no additional deps needed

# Windows - download Visual C++ Redistributable if needed
The startup scripts automatically kill processes on ports 3003 and 5173. If this fails:Find and kill the process manually:
# macOS/Linux
lsof -ti :3003 | xargs kill -9
lsof -ti :5173 | xargs kill -9

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort 3003).OwningProcess | Stop-Process -Force
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess | Stop-Process -Force
Or change the port:
  • Backend: Set PORT environment variable
  • Frontend: Vite will automatically use next available port
Check that the frontend is configured to connect to the correct backend URL. The frontend should automatically connect to http://localhost:3003 by default.Verify the backend is accessible:
curl http://localhost:3003/api-docs
Unix/Linux/macOS:
chmod +x start.sh
./start.sh
Windows PowerShell:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\start.ps1

​
Next Steps

Quickstart

Create your first workflow in minutes

Node Types

Explore 20+ available node types

Plugin Development

Build custom nodes to extend functionality

API Reference

Interactive Swagger API documentation
For additional help, visit the GitHub repository or check the server logs for detailed error messages.

Build docs developers (and LLMs) love

Get started for freeTalk to us