Flujo

What is Flujo about?

Flujo enables developers and AI practitioners to orchestrate multi‑model workflows locally. It bundles environment‑variable encryption, model configuration (including OpenAI, Anthropic, Ollama, etc.), MCP server installation, visual flow design, and a chat interface for real‑time interaction.

How to use Flujo?

1. Installation – clone the repo, run npm install (or yarn), then npm run dev for development or npm run build && npm start for production.
2. Desktop mode – use npm run electron-dev (development) or npm run electron-dist (packaged).
3. Docker – docker-compose up -d or the provided ./scripts/build-docker.sh and ./scripts/run-docker.sh scripts.
4. Configure – add API keys in Settings, define models under the Models page, install MCP servers via the MCP page, then create flows on the Flows page.
5. Interact – select a flow in the Chat page and start conversing with the orchestrated workflow.

Key Features

• Secure API‑key storage with encryption and global access.
• Model Management supporting multiple providers and local Ollama models.
• MCP Server Integration – install from GitHub, local filesystem, or Docker; inspect tools and bind environment variables.
• Visual Flow Builder – drag‑and‑drop nodes, configure system prompts per model/flow/node, support for branching, loops, and orchestration.
• Chat Interface – converse with flows, edit/disable messages, attach files, and (future) audio transcription.
• External Tool Compatibility – expose Flujo as an OpenAI‑compatible endpoint for tools like CLine or Roo.
• Electron & Docker support for desktop and containerized deployments.

Use Cases

• Building complex AI pipelines that combine LLMs, retrieval, and custom tools.
• Rapid prototyping of multi‑agent systems without writing code.
• Securely managing and reusing API keys across projects.
• Providing a chat‑based front‑end for internal knowledge bases or customer support bots.
• Integrating legacy MCP‑based services into modern Node.js workflows.

FAQ

Q: Do I need an internet connection? A: Only for cloud providers (OpenAI, Anthropic, etc.). Local Ollama models run offline.

Q: How are API keys protected? A: Keys are encrypted before being written to disk and are never exposed in plain text unless logging is manually enabled.

Q: Can I run multiple MCP servers simultaneously? A: Yes. Each server can be installed, started, and referenced independently in flows.

Q: What ports does Flujo use? A: The web UI defaults to http://localhost:4200. Docker containers expose the same port unless overridden.

Q: How do I add a custom tool to a flow? A: Install the tool on an MCP server, then reference it in the node’s “Allowed Tools” list or directly in the system prompt.

DISCLAIMER

FLUJO is still an early preview! Here's a 30 second video to show it off:

For anything that you struggle with (MCP Installation, Application Issues, Usability Issues, Feedback): PLEASE LET ME KNOW! -> Create a Github Issue or write on Discord (https://discord.gg/KPyrjTSSat) and I will look into it! Maybe a response will take a day, but I will try to get back to each and every one of you.

Here's a video guiding you through the whole thing - from installation to output! (15min) Sorry for the bad audio, a new Video is coming soon!

FLUJO animated Short #1 - "A sad song about MCP"

IMPORTANT SECURITY NOTE

FLUJO has currently EXTENSIVE logging enabled by default! This may expose your encrypted API-Keys to the terminal output!. Be VERY careful when grabbing videos or streaming and showing the terminal output!

FLUJO

FLUJO is an open-source platform that bridges the gap between workflow orchestration, Model-Context-Protocol (MCP), and AI tool integration. It provides a unified interface for managing AI models, MCP servers, and complex workflows - all locally and open-source.

FLUJO is powered by the PocketFlowFramework and built with CLine and a lot of LOVE.

🌟 Key Features

🔑 Environment & API Key Management

• Secure Storage: Store environment variables and API keys with encryption
• Global Access: Use your stored keys across the entire application
• Centralized Management: Keep all your credentials in one secure place

🤖 Model Management

• Multiple Models: Configure and use different AI models simultaneously
• Pre-defined Prompts: Create custom system instructions for each model
• Provider Flexibility: Connect to various API providers (OpenAI, Anthropic, etc.)
• Local Models: Integrate with Ollama for local model execution

🔌 MCP Server Integration

• Easy Installation: Install MCP servers from GitHub or local filesystem
• Server Management: Comprehensive interface for managing MCP servers
• Tool Inspection: View and manage available tools from MCP servers
• Environment Binding: Connect server environment variables to global storage
• Docker Support: Run Docker-based MCP servers within Flujo

🔄 Workflow Orchestration

• Visual Flow Builder: Create and design complex workflows
• Model Integration: Connect different models in your workflow
• Tool Management: Allow or restrict specific tools for each model
• Prompt Design: Configure system prompts at multiple levels (Model, Flow, Node)

💬 Chat Interface

• Flow Interaction: Interact with your flows through a chat interface
• Message Management: Edit or disable messages or split conversations to reduce context size
• File Attachments: Attach documents or audio for LLM processing (really bad atm, because for this you should use mcp!)
• Transcription: Process audio inputs with automatic transcription (really bad atm, see roadmap)

🔄 External Tool Integration

• OpenAI Compatible Endpoint: Integrate with tools like CLine or Roo
• Seamless Connection: Use FLUJO as a backend for other AI applications

🚀 Getting Started

Manual installation:

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Installation

1. Clone the repository:

   git clone https://github.com/mario-andreschak/FLUJO.git
   cd FLUJO
   

2. Install dependencies:

   npm install
   # or
   yarn install
   

3. Start the development server:

   npm run dev
   # or
   yarn dev
   

4. Open your browser and navigate to:

   http://localhost:4200
   

5. FLUJO feels and works best if you run it compiled:

   npm run build
   npm start
   

6. To run as a desktop application:

   npm run electron-dev    # Development mode
   # or
   npm run electron-dist   # Build and package for your platform
   

📖 Usage

Setting up often used API keys

1. Navigate to Settings
2. Save your API Keys globally to secure them

Setting Up Models

1. Navigate to the Models page
2. Click "Add Model" to create a new model configuration
3. Configure your model with name, provider, API key, and system prompt
4. Save your configuration

Managing MCP Servers

1. Go to the MCP page
2. Click "Add Server" to install a new MCP server
3. Choose from GitHub repository or local filesystem
4. Configure server settings and environment variables
5. Start and manage your server

Using SSE MCP-Servers

1. Got to the MCP Page
2. Click "Add Server" to install a new MCP server
3. Select "Local Server"
4. Enter a Server Name, enter "/" as Server Root Path
5. Leave Build Command and Install Command empty
6. Enter "npx" as Run Command
7. Add 1. Argument "mcp-remote"
8. Add 2. Argument "(your MCP SSE-Url here)"

Using official Reference servers

1. Go to the MCP page
2. Click "Add Server" to install a new MCP server
3. Go to the "Reference Servers" Tab
4. (First time executing:) Click "Refresh" and waaaaaaait.
5. Click a server of your choice, wait for the screen to change, click "Save" / "Update Server" at the bottom.

Using Docker-based MCP Servers

When running FLUJO in Docker, you can use Docker-based MCP servers:

1. Go to the MCP page
2. Click "Add Server" to install a new MCP server
3. Choose "Docker" as the installation method
4. Provide the Docker image name and any required environment variables
5. Start and manage your server

Creating Workflows

1. Visit the Flows page
2. Click "Create Flow" to start a new workflow
3. Add processing nodes and connect them
4. Configure each node with models and tools
5. Save your flow

Branching

1. Connect one MCP node to multiple subsequent ones
2. Define the branching in the prompt, using the handoff-tools on the "Agent Tools" tab

Loops

1. Same as branching, but connect back to a previous node

Orchestration

1. Same as loops but with multiple ones

Using the Chat Interface

1. Go to the Chat page
2. Select a flow to interact with
3. Start chatting with your configured workflow

🔄 MCP Integration

FLUJO provides comprehensive support for the Model Context Protocol (MCP), allowing you to:

• Install and manage MCP servers
• Inspect server tools
• Connect MCP servers to your workflows
• Reference tools directly in prompts
• Bind environment variables to your global encrypted storage

Docker Installation

The easiest way to run FLUJO is using Docker, which provides a consistent environment and supports running Docker-based MCP servers.

Prerequisites

• Docker and Docker Compose installed on your system

Using Docker Compose

1. Clone the repository:

   git clone https://github.com/mario-andreschak/FLUJO.git
   cd FLUJO
   

2. Build and start the container:

   docker-compose up -d
   

3. Access FLUJO in your browser:

   http://localhost:4200
   

Using Docker Scripts

For more control over the Docker build and run process, you can use the provided scripts:

1. Build the Docker image:

   ./scripts/build-docker.sh
   

2. Run the Docker container:

   ./scripts/run-docker.sh
   

Options for run-docker.sh:

• --tag=<tag>: Specify the image tag (default: latest)
• --detached: Run in detached mode
• --no-privileged: Run without privileged mode (not recommended)
• --port=<port>: Specify the host port (default: 4200)

For more detailed information about Docker support, including Docker-in-Docker capabilities, persistent storage, and troubleshooting, see DOCKER.md.

📄 License

FLUJO is licensed under the MIT License.

🚀 Roadmap

Here's a roadmap of upcoming features and improvements:

• Real-time Voice Feature: Adding support for Whisper.js or OpenWhisper to enable real-time voice capabilities.
• Visual Debugger: Introducing a visual tool to help debug and troubleshoot more effectively.
• MCP Roots Support: Implementing Checkpoints and Restore features within MCP Roots for better control and recovery options.
• MCP Prompts: Enabling users to build custom prompts that fully leverage the capabilities of the MCP server.
• MCP Proxying STDIO<>SSE: Likely utilizing SuperGateway to proxy standard input/output with Server-Sent Events for enhanced communication: Use MCP Servers managed in FLUJo in any other MCP client.
• Enhanced Integrations: Improving compatibility and functionality with tools like Windsurf, Cursor, and Cline.
• Advanced Orchestration: Adding agent-driven orchestration, batch processing, and incorporating features inspired by Pocketflow.
• Online Template Repository: Creating a platform for sharing models, flows, or complete "packages," making it easy to distribute FLUJO flows to others.
• Edge Device Optimization: Enhancing performance and usability for edge devices.

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📬 Contact

• GitHub: mario-andreschak
• LinkedIn: https://www.linkedin.com/in/mario-andreschak-674033299/

Notes:

• You can add ~FLUJO=HTML, ~FLUJO=MARKDOWN, ~FLUJO=JSON, ~FLUJO=TEXT in your message to format the response, this will give varying results in different tools where you integrate FLUJO.
• You can add ~FLUJOEXPAND=1 or ~FLUJODEBUG=1 somewhere in your message to show more details
• in config/features.ts you can change the Logging-level for the whole application
• in config/features.ts you can enable SSE support which is currently disabled by default

---

FLUJO - Empowering your AI workflows with open-source orchestration.