ForgeFlow

ForgeFlow is a local-first orchestration studio for building, testing, and operating multi-agent workflows with live model providers and MCP servers.

Status

ForgeFlow is under active development. The core studio, runtime, provider connections, and MCP configuration flows are usable today, but APIs and UX details may continue to evolve.

Overview

• A React studio for designing workflows, configuring agents, and managing reusable connections
• A FastAPI runtime for workflow execution, approvals, live events, and persisted runs
• A versioned asset system for workflows, agents, provider connections, MCP servers, and subworkflows
• A local-first control plane that stores data on your machine and binds to 127.0.0.1 by default

ForgeFlow connects to live provider APIs and local runtimes using user-supplied credentials. It is designed for local operation by default, with explicit configuration required if you choose to expose it beyond your machine.

Studio overview

Workflow Studio with a sample pipeline:

Agents workspace with reusable specialists:

Connections workspace for shared providers and MCP infrastructure:

Visual Agent Builder

Workflows List

Capabilities

• Visual workflow editor with start, agent, condition, approval, loop, fan_out, join, mapper, delay, cli_agent, subworkflow, and end nodes
• Dedicated Agents workspace plus a focused Agent Builder
• Shared Connections workspace for provider connections and MCP servers
• Persisted workflow runs, agent test runs, approvals, and live execution events
• Provider-backed agent execution through Strands integrations
• MCP discovery and runtime tool mounting owned by ForgeFlow rather than exposed as raw mcp_client

Supported providers

ForgeFlow currently exposes these providers in the studio:

• OpenAI
• OpenAI Responses
• Anthropic
• Gemini
• Amazon Bedrock
• xAI
• Kimi
• LiteLLM
• Llama API
• llama.cpp
• Mistral
• Ollama
• Amazon SageMaker
• Writer

Authentication depends on provider type:

• API key: OpenAI, OpenAI Responses, Anthropic, Gemini, xAI, Kimi, LiteLLM, Llama API, Mistral, Writer
• AWS credentials/profile/ambient auth: Bedrock, SageMaker
• Endpoint-only local runtime: Ollama, llama.cpp

MCP support

ForgeFlow manages MCP server configuration at the application layer.

• Supported transports: stdio and streamable_http
• MCP tools can be discovered, inspected, and explicitly attached to agents
• MCP prompts and resources are discoverable in the UI
• Strands mcp_client is intentionally not exposed as a direct user capability

Security model

• Backend and frontend bind to loopback addresses by default
• The launcher generates a local bearer token if FORGEFLOW_LOCAL_API_TOKEN is not set
• API requests require that bearer token
• Secrets are encrypted locally using either FORGEFLOW_SECRET_ENCRYPTION_KEY or the managed key file in the artifacts directory
• Credentials are supplied locally at runtime and are not required to clone, build, or explore the repository

If you intentionally expose ForgeFlow beyond your machine, treat it as a real application boundary and supply your own network, auth, and secret-management controls.

Architecture

• frontend/: React 19 + Vite studio
• backend/: FastAPI API, workflow runtime/compiler, persistence, provider runtime, and tests
• docs/screenshots/: README screenshots
• docker-compose.yml: local PostgreSQL service for development
• start-forgeflow.sh: root launcher for backend + frontend with backend log setup

Prerequisites

• Python 3.11+
• uv
• Node.js 20+
• Docker Desktop or another Docker engine if you want the default PostgreSQL setup

Quick start

1. Install backend dependencies

cd backend
uv sync

2. Install frontend dependencies

cd frontend
npm install

3. Configure the backend environment

cd backend
cp .env.example .env

Set a local API token in backend/.env, or let the launcher generate one at startup.

Default storage is PostgreSQL at localhost:5432. For a simple SQLite setup instead:

export FORGEFLOW_DATABASE_URL='sqlite+pysqlite:////tmp/forgeflow.db'
export FORGEFLOW_ARTIFACTS_ROOT='/tmp/forgeflow-artifacts'

4. Start the app

From the repo root:

./start-forgeflow.sh

This launcher:

• loads backend/.env when present
• generates the local API token when needed
• starts the FastAPI backend through uv
• starts the Vite frontend
• writes backend logs to .forgeflow-logs/
• auto-starts PostgreSQL through docker-compose.yml when the configured database is PostgreSQL

If you prefer starting from the frontend directory:

cd frontend
npm run dev:fullstack

Running services separately

Backend:

cd backend
uv run python -m uvicorn app.main:create_app --factory --host 127.0.0.1 --port 8000 --reload

Frontend:

cd frontend
npm run dev

If you run services separately, make sure the frontend has the same VITE_FORGEFLOW_LOCAL_API_TOKEN value as the backend FORGEFLOW_LOCAL_API_TOKEN.

Development and verification

Backend:

backend/.venv/bin/pytest backend/tests -q

Frontend:

cd frontend
npm test
npm run lint
npm run build

Development notes

• Use uv for Python dependency and backend runtime commands
• Workflow tool and mcp_tool nodes are intentionally rejected; tools belong on agents
• Condition nodes require an explicit else branch
• Regex condition operators are disabled for safety
• Docker Compose uses a development-only PostgreSQL password; do not reuse it outside local development

See CONTRIBUTING.md, SECURITY.md, and AGENTS.md for contributor and security guidance.