MeshFlows Documentation¶
MeshFlows is open-source (GPL) workflow orchestration and integration infrastructure: deploy the Engine, design or author workflows, and extend the platform with new capabilities.
Build integrations once, start them many ways (HTTP, schedule, messaging), and grow the platform by adding capability providers — without forking the Orchestrator for every new system.
Engine overview · Flows overview · Why MeshFlows · Capability comparison · Run locally · Issues
Why teams use it¶
For developers: YAML workflows (and a production-ready visual designer), clear step/capability contracts, Git-based delivery, and a local Compose stack that matches how you run on Kubernetes.
For CTOs / architects: a self-hosted, GPL-licensed platform you control — durable orchestration, pluggable integrations, multi-trigger workflows, and an extension model that keeps custom connectors out of the core runtime.
Compared with UI-first automation tools or embedded in-app workflow engines, MeshFlows focuses on registry-first connectors, separate integration artifacts, and a runtime for reliable message/API traffic — see Why MeshFlows.
Two ways in¶
MeshFlows is something you run and something you author against — not a library you embed inside an application process.
Run the platform¶
Deploy the Engine — Gateway, Orchestrator, workers, Identity, Storage, Scheduler, egress services, Dashboard, and supporting infra (RabbitMQ, Postgres, observability).
The platform is easy to extend: add a capability provider that registers with the capability registry; workflows call it through service_call steps. New cloud or line-of-business connectors (for example Azure services) follow the same path — they are not bundled today, but they do not require core Engine changes.
- Prerequisites
- Local development (Docker Compose) or Kubernetes / AKS
- Runtime secrets · Platform secrets
- Operations
- Integration end-to-end — new provider + connection + workflow
- Add a Capability Provider — Python / Go / C# starters
- Capability provider contract — register and expose new capabilities
Author and design workflows¶
Define behaviour as YAML under flows/, or use the Dashboard designer (production-ready) for authoring and inspection. Attach separate trigger documents so the same workflow can start from HTTP, a schedule, and/or messaging (for example RabbitMQ) — without duplicating the workflow per channel.
Build → Run → Operate¶
| Stage | What you do | Where to look |
|---|---|---|
| Build | Design or write workflow YAML, connections, policies; attach triggers (HTTP, schedule, AMQP, …) | First workflow, Workflow YAML, Script steps, C# custom process |
| Run | Starts arrive via Gateway, Scheduler, or messaging; Orchestrator executes steps and resolves capability providers | Gateway, Orchestrator API, Scheduler |
| Operate | Health, traces/logs, secrets, rollouts, capacity; ship new capability providers as the estate grows | Operations, Integration end-to-end, Observability, CI/CD |
What it is good for¶
- Integration & orchestration — HTTP, FTP/SFTP, SSH, RabbitMQ, SMTP/IMAP, and related egress; XML/JSON/CSV/Liquid transforms
- One workflow, many starts — schedule, HTTP, and event-driven starts via separate trigger YAML against the same definition
- Extensible capabilities — straightforward provider registration (Python / Go / C# starters); workflows consume capabilities as
service_callsteps - Self-hosted delivery — Docker Compose locally; Kustomize on Kubernetes (including AKS)
It is not an embeddable in-process library for an existing app runtime, and it is not primarily a human-approval BPM suite. Optional managed SaaS / commercial support tiers are out of scope for this product documentation.
Components¶
| Component | Role |
|---|---|
| Engine | Microservices: execute workflows, expose APIs, transform data, store runtime state, authenticate, schedule, egress, Dashboard designer |
| Flows | Git-versioned workflow artifacts and runtime config; deployable with or independently of Engine updates |
| Wiki | This documentation site (MkDocs), also deployable as a container |
Architecture deep-dive: Engine architecture. License: GNU GPL.
Run locally¶
cd engine
cp .env.example .env # fill secrets first
docker-compose up -d
Health and a sample invoke:
curl http://localhost:8080/v1/status
curl http://localhost:8083/readyz
curl -X POST http://localhost:8080/v1/run/demo \
-H "Content-Type: application/json" \
-d '{"xml":"<root/>"}'
More: Local development, Develop and Test.
Documentation map¶
- Engine how-to — deploy, secrets, operations, scheduler, develop & test, AKS, capability providers
- Engine reference — architecture, APIs, observability, security, CI/CD, capability contracts
- Flows how-to — authoring, scripts, scheduling, deployment, testing
- Flows reference — YAML schema, step types, context, policies
Troubleshooting¶
Internal docs published to wiki¶
| Internal path | Wiki page |
|---|---|
internal/lab-https-setup.md |
Lab HTTPS Setup |
internal/k8s-gateway-api-migration.md |
Gateway API Migration |
internal/scheduler-operations.md |
Scheduler Operations |
internal/SCRIPT_STEPS_GUIDE.md |
Script Steps |
internal/message-size-scaling-plan.md |
Tuning — Message size limits |
Support¶
This MkDocs site (wiki/docs/, {env}-wiki.meshflows.org) is the product wiki. The Forgejo repository wiki is a compact pointer only — not a second docs tree.
- Report bugs and feature requests: Forgejo Issues
- Source and packages: code.meshflows.org/meshflowsgpl/meshflows
- Contributions: CONTRIBUTING.md
Last updated: August 2026