ForgeFlow

ForgeFlow is a local-first automation platform for web and desktop workflows.

It combines a drag-and-drop workflow studio, resilient execution, AI-assisted automation, and centralized operations in one stack.

What You Get

• Visual workflow builder (React Flow)
• Core editor UX: undo/redo, duplicate, edge disconnect, auto-layout, and JSON import/export
• Web automation (Playwright) and desktop automation (agent service)
• Recorder flows for web and desktop action capture with review-before-insert draft editing
• Autopilot workflow generation from natural-language prompts with confidence scoring and confirm-before-create review
• Template setup wizard with required fields, preflight checks, sample input copy, and run-readiness status
• In-app starter walkthrough for first workflow creation and publish path
• AI nodes: transform_llm, document_understanding, clipboard_ai_transfer
• Integrations (http_api, postgresql, mysql, mongodb, google_sheets, airtable, s3)
• Orchestrator queue with attended/unattended robots and dispatch lifecycle
• Process/task mining summary (bottlenecks, variants, opportunity scoring)
• Draft/publish lifecycle, rollback, schedules, approvals, and resume-from-failure
• RBAC, optional TOTP 2FA, encrypted secrets, audit log, webhooks, Prometheus metrics
• RBAC, optional TOTP 2FA, encrypted secrets, audit log, webhooks, Prometheus metrics

Screenshots

Real-time Dashboard

Visual Workflow Builder

Detailed Execution Logs

Services

• web: http://localhost:5173
• server: http://localhost:8080
• agent: http://localhost:7001
• db: PostgreSQL
• redis: runtime dependency
• ollama: local LLM runtime

Quick Start

1. Start everything:

./start.sh

2. Open http://localhost:5173
3. Sign in with .env credentials (default: local / localpass)
4. Build your first flow and run Test Run

Power shortcuts:

• Ctrl/Cmd+K quick-add node search
• Ctrl/Cmd+Z undo
• Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y redo
• Ctrl+S save draft
• Ctrl+T test run
• Ctrl+R run
• Ctrl+D duplicate selected node
• Delete remove selected node or selected edge

Demo Flows

Use these guided demos to evaluate the platform quickly:

• docs/DEMOS.md#demo-1-autopilot-invoice-triage
• docs/DEMOS.md#demo-2-orchestrator-unattended-queue
• docs/DEMOS.md#demo-3-document-understanding-and-clipboard-ai
• docs/DEMOS.md#demo-4-workflow-builder-mvp-controls
• docs/DEMOS.md#demo-5-recorder-draft-review-and-insert
• docs/DEMOS.md#demo-6-real-world-starter-pack

Production Starter Templates

Use built-in templates as a fast path from idea to first successful run:

• invoice-intake-approval: Parse invoice text, classify risk, branch to approval, and sync approved data.
• web-scrape-api-sync: Scrape table data from a page and push rows to an API endpoint.
• csv-cleanup-validation: Import CSV rows, normalize with AI, validate required fields, and branch bad records.
• email-triage-ticket-create: Classify inbound email priority, summarize content, then create a ticket.
• scheduled-health-check-alert: Run scheduled API checks, classify service state, and alert on degradation.

Create from UI:

1. Open Templates in the left sidebar.
2. Select a starter template.
3. Complete Template Setup Wizard fields and click Validate Setup.
4. Click Create Workflow.

Template setup values are injected into the created workflow definition (URLs, selectors, integration IDs, thresholds, etc.), so starters are immediately environment-specific.

Contributor Onboarding

New contributors should start here:

1. docs/tutorials/FIRST_AUTOMATION_10_MIN.md (fast baseline walkthrough)
2. docs/ONBOARDING.md (setup + contribution tracks)
3. docs/CONTRIBUTING.md (standards, definition of done, PR workflow)
4. .github/pull_request_template.md (PR structure used in this repo)

Good first areas:

• UI polish and node inspector UX (apps/web/src)
• New activity handlers (apps/server/src/lib/runner.ts)
• New API endpoints with zod validation (apps/server/src/index.ts)
• Docs and tutorials (docs/*)

Development Commands

Start stack:

./start.sh

Start without auto-update:

AUTO_UPDATE=0 ./start.sh

Run backend tests:

cd apps/server && npm test

Run web tests:

cd apps/web && npm test

Run web Playwright smoke tests:

cd apps/web && npx playwright install --with-deps chromium && npm run test:e2e

Build server + web:

cd apps/server && npm run build
cd apps/web && npm run build

Stop stack:

docker compose down

Release Automation

Create the next version tag from main:

npm run release:patch

Other bump modes:

npm run release:minor
npm run release:major

Dry run:

npm run release:patch -- --dry-run

Tag pushes (v*.*.*) trigger .github/workflows/release.yml, which reruns validation and publishes a GitHub release with generated notes.

Documentation Map

• docs/README.md
• docs/DEMOS.md
• docs/ONBOARDING.md
• docs/tutorials/FIRST_AUTOMATION_10_MIN.md
• docs/examples/workflows/first-automation.workflow.json
• docs/ACTIVITY_PACK_ROADMAP.md
• docs/ARCHITECTURE.md
• docs/API_REFERENCE.md
• docs/DEPLOYMENT.md
• docs/CONTRIBUTING.md
• docs/templates/*
• AGENTS.md (repository contributor guide)
• CHANGELOG.md
• CODE_OF_CONDUCT.md
• LICENSE

API Areas

• Auth: /api/auth/*
• Workflows: /api/workflows*
• Runs: /api/runs*
• Templates/Autopilot: /api/templates, /api/activities, /api/autopilot/plan
• Document AI: /api/document/understand
• Orchestrator: /api/orchestrator/*
• Mining: /api/mining/summary
• Schedules: /api/schedules*
• Integrations: /api/integrations*
• Metrics dashboard: /api/metrics/dashboard
• Prometheus metrics: /metrics
• Secrets/Webhooks/Admin: /api/secrets*, /api/webhooks*, /api/admin/*

Troubleshooting

Module mismatch in containers:

docker compose up --build --renew-anon-volumes

Desktop automation issues on Linux:

xhost +local:

Then verify .env DISPLAY (usually :0).

Missing Ollama model:

docker exec -it rpa-ollama ollama pull llama3.2

Support

• https://buymeacoffee.com/mackeh

Community Standards

• Code of Conduct: CODE_OF_CONDUCT.md
• License: LICENSE (MIT)