Flowise User Guide

Flowise is an open-source, low-code platform for building AI agents and LLM applications visually. You assemble applications by dragging nodes onto a canvas and wiring them together — chat models, tools, document loaders, vector stores, memory, and full autonomous agents — then deploy the result as a chatbot, an embeddable widget, or a REST API. No glue code required for the common cases, and a full code escape hatch when you need one.

This guide is for people who build and run flows in Flowise: makers, prompt engineers, analysts, and developers who want working AI applications without writing a backend. It covers installation, the visual builder, every major node category, the three flow types, deployment, and troubleshooting. For server architecture, scaling, enterprise features, and the custom-node SDK, see the Flowise Admin Guide.

Note

Flowise ships hundreds of integrations (54+ chat-model files, 70+ tool files, 49 document loaders, 36 vector stores, and more). This guide teaches the platform — the concepts and representative nodes you use every day — rather than cataloguing every integration. Once you understand one node in a category, the rest follow the same pattern.

1. Quick Start

Get a working Flowise instance and your first chatbot in about five minutes.

1.1 Install and start

You need Node.js 20 or newer (download).

npm install -g flowise
npx flowise start

Open http://localhost:3000 in your browser. On first launch you create an admin account, then you land in the Flowise dashboard.

2024-... INFO [server]: Starting Flowise...
2024-... INFO [server]: 📦 Data Source initialized successfully
2024-... INFO [server]: ⚡️ [server]: Flowise Server is listening at :3000

Tip

npx flowise start runs the globally installed package. If you skipped -g, npx flowise start still works — npx downloads the package on demand.

1.2 Build your first chatbot

1. Click Chatflows → Add New.
2. From the node panel on the left, drag in a Chat Model node (e.g. ChatOpenAI) and a Conversation Chain (under Chains) — or, for the modern experience, start an Agentflow (see §5).
3. Wire the chat model's output anchor into the chain's Chat Model input anchor.
4. Click the chat model node, open the Connect Credential dropdown, and add your provider API key.
5. Click Save (top right), give the flow a name.
6. Click the chat bubble icon (bottom right) and send a message.

You:  Hello!
Bot:  Hi there — how can I help you today?

You now have a running conversational AI. Everything else in this guide builds on this loop: add nodes → connect them → attach credentials → test in chat → deploy.

Important

Flowise never bundles model API keys. You supply your own provider credentials (OpenAI, Anthropic, Google, AWS Bedrock, Ollama, etc.) the first time you use a node that needs one. Credentials are encrypted at rest — see §8.2.

2. Installation

Flowise runs anywhere Node.js runs. Choose the method that matches how you intend to use it.

2.1 Installation methods

npm (global)

Best for trying Flowise and single-user local use.

npm install -g flowise
npx flowise start

Update to the latest release:

npm update -g flowise

Docker Compose

Best for a persistent self-hosted instance.

git clone https://github.com/FlowiseAI/Flowise.git
cd Flowise/docker
cp .env.example .env       # edit values as needed
docker compose up -d

Open http://localhost:3000. Stop with:

docker compose stop

Docker (single image)

docker build --no-cache -t flowise .
docker run -d --name flowise -p 3000:3000 flowise
docker stop flowise

From source (pnpm)

Best for contributors and custom builds — see the Admin Guide.

npm i -g pnpm
git clone https://github.com/FlowiseAI/Flowise.git
cd Flowise
pnpm install
pnpm build
pnpm start

2.2 System requirements

Warning

If pnpm build fails with exit code 134 (JavaScript heap out of memory), raise the Node heap and rebuild:

export NODE_OPTIONS="--max-old-space-size=4096"   # macOS / Linux / Git Bash
pnpm build

On Windows PowerShell use $env:NODE_OPTIONS="--max-old-space-size=4096".

2.3 Where your data lives

By default Flowise stores everything under a .flowise folder in your home directory:

• The SQLite database (DATABASE_PATH) — your flows, credentials, chat history.
• The encryption key (SECRETKEY_PATH) — used to encrypt stored credentials.
• File storage (BLOB_STORAGE_PATH) — uploaded documents and generated files.

Caution

Back up the .flowise directory — losing the encryption key makes stored credentials unrecoverable. For production, point storage and secrets at durable backends (S3/GCS/Azure, AWS Secrets Manager). See the Admin Guide.

3. The Flowise interface

After login you work inside a sidebar-driven dashboard. The main areas:

3.1 The canvas

Every flow is edited on a canvas:

• Node panel (left) — searchable list of all available nodes, grouped by category.
• Canvas (center) — drag nodes here and connect their anchors.
• Anchors — colored dots on node edges. An output anchor connects to a compatible input anchor; Flowise only allows type-compatible connections (an LLM output can feed an "LLM" input, etc.).
• Node settings — click a node to edit its parameters in place.
• Save / Chat / Settings / API — top-right controls to persist, test, configure, and get embed/API snippets.

Tip

Use the search box at the top of the node panel. Typing pdf, pinecone, or anthropic jumps straight to the matching node instead of scrolling categories.

4. Nodes: the building blocks

A node is one capability — a chat model, a tool, a loader, a memory store. You configure a node by filling in its fields and connecting its anchors. The table below maps the categories you'll see in the node panel.

Note

Most nodes are thin wrappers around well-known libraries (LangChain, LlamaIndex). That means a node's options mirror the underlying provider's options — e.g. ChatOpenAI exposes model, temperature, max tokens, streaming, exactly as the provider does. You're configuring real, documented behavior, not a Flowise abstraction.

4.1 Node anatomy

Every node shows three kinds of fields:

• Inputs — values or upstream connections (a model, a tool, a prompt).
• Credential — a secure connection to a provider (added once, reused everywhere).
• Additional Parameters — an expandable section with advanced/optional settings.

Fields support variables: type {{$vars.myVariable}} to inject a stored Variable, or reference a previous node's output. This lets you parameterize flows without hard-coding values.

4.2 Disabling nodes

Administrators can hide nodes from the panel with the DISABLED_NODES setting (e.g. DISABLED_NODES=bufferMemory,chatOpenAI) and toggle community-contributed nodes with SHOW_COMMUNITY_NODES. See the Admin Guide if a node you expect is missing.

5. The three flow types

Flowise gives you three ways to build, in increasing order of autonomy.

5.1 Chatflow — chains and RAG

A Chatflow is a directed graph of chains, models, and retrievers. Use it for deterministic pipelines: a question-answering bot over your docs, a summarizer, a classifier.

Example — RAG over your PDFs:

Document Loader (PDF)
        │
Text Splitter (Recursive)
        │
Embeddings (OpenAIEmbedding) ── Vector Store (Pinecone) ── Retriever
                                                               │
                                          Conversational Retrieval QA Chain ── Chat Model

The chain retrieves the most relevant chunks for each question and passes them to the model as context, so answers are grounded in your documents.

5.2 Agent — a single autonomous agent

An Agent node is an LLM that can decide, on its own, which tools to call to satisfy a request. You give it a system prompt, attach a chat model and one or more tools, and it loops: think → call a tool → observe → repeat → answer.

Tool Agent ── Chat Model
   ├── Tool: Calculator
   ├── Tool: SerpAPI (web search)
   └── Tool: Custom Tool (your function)

Ask "What's the population of France divided by 2?" and the agent searches the web, then uses the calculator — choosing both tools itself.

Tip

Tool-calling agents work best with models that support function/tool calling (OpenAI, Anthropic, Gemini, etc.). If you see "This agent only compatible with function calling models", switch to a tool-capable chat model.

5.3 AgentFlow V2 — multi-step agent orchestration

Agentflows are Flowise's modern canvas for multi-step, branching, multi-agent workflows. Instead of one agent looping, you lay out an explicit graph of specialized nodes. This is the recommended way to build complex agents.

The AgentFlow V2 node set:

Example — research assistant:

Start → Condition Agent ("is this a research question?")
          ├─ yes → Agent (web search tools) → LLM (summarize) → Direct Reply
          └─ no  → Direct Reply ("I only answer research questions")

Note

AgentFlow V2 also offers a generator: describe the agent you want in plain language and Flowise drafts a starting graph for you. You then refine it on the canvas.

6. Common tasks (recipes)

6.1 Chat with your documents (RAG)

1. Create a Document Store (sidebar) and upload your files, or build the pipeline inline in a chatflow.
2. Pick a Text Splitter (RecursiveCharacterTextSplitter is a safe default).
3. Choose an Embeddings node and a Vector Store (InMemory for testing, Pinecone/Postgres/Qdrant for production).
4. Upsert the documents (the Document Store has an Upsert button; inline flows upsert on first run).
5. Add a Conversational Retrieval QA Chain + Chat Model, wire the retriever in.
6. Test in chat — answers now cite your content.

6.2 Give an agent a custom tool

1. Go to Tools → Create, or drag a Custom Tool node.
2. Define the tool's name, description (the agent reads this to decide when to use it), and input schema.
3. Write the JavaScript body — it can call APIs, do math, format data, and return a string.
4. Attach the tool to an Agent node. The agent will call it whenever the description matches the user's need.

Important

The tool description is how the agent decides to use it. Write it like an instruction to a teammate: "Use this to look up a customer's order status by order ID." Vague descriptions cause the agent to skip or misuse the tool.

6.3 Connect external apps via MCP

Flowise supports the Model Context Protocol (MCP), letting agents use tools exposed by external MCP servers (Slack, GitHub, Postgres, Brave Search, and your own).

• Use a built-in MCP tool node (e.g. MCP → Slack, MCP → Github), or
• Register a Custom MCP Server under the sidebar and expose its tools to your agents.

Caution

MCP servers can be powerful. The stdio transport can run arbitrary commands on the server — only enable it for fully trusted users. Flowise defaults to the safer sse transport and enforces an environment-variable allowlist. See the Admin Guide's security section.

6.4 Schedule a flow to run automatically

Agentflows can be triggered on a schedule (cron-style). Configure the schedule in the flow's settings; the minimum interval is governed by MIN_SCHEDULE_INTERVAL_SECONDS (default 60s). Use this for digests, monitoring, and recurring report generation.

6.5 Use variables and overrides

• Variables (sidebar) hold reusable values; reference them as {{$vars.name}} in any field.
• Override config lets API callers pass per-request values (e.g. a different system prompt) when calling /api/v1/prediction.

7. Deploying and sharing your flow

Once a flow works in the test chat, you have four ways to ship it. Open the flow and click the </> (API) button to get ready-made snippets.

7.1 Shareable chatbot

Every saved chatflow gets a hosted chatbot page. Open the flow's settings → Share Chatbot to get a public URL and to customize the title, colors, welcome message, and avatar.

7.2 Embed on your website

Copy the embed snippet to drop a chat widget into any site:

<script type="module">
    import Chatbot from 'https://cdn.jsdelivr.net/npm/flowise-embed/dist/web.js'
    Chatbot.init({
        chatflowid: 'your-chatflow-id',
        apiHost: 'http://localhost:3000'
    })
</script>

You can theme the widget (button color, window size, welcome text) through the theme option in the snippet.

7.3 REST API (prediction)

Call your flow programmatically. Public prediction endpoint:

curl http://localhost:3000/api/v1/prediction/<your-chatflow-id> \
     -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <YOUR_API_KEY>" \
     -d '{"question": "Hello, what can you do?"}'

{
  "text": "I can answer questions about your documents and search the web...",
  "chatId": "abc-123",
  "chatMessageId": "def-456"
}

Create API keys under API Keys in the sidebar. To stream responses token-by-token, set "streaming": true and read the server-sent events. For the complete endpoint reference (chatflows, predictions, executions, document stores, vectors, tools, variables, and more), see the Admin Guide and the built-in Swagger UI.

7.4 Python / TypeScript SDKs

Flowise publishes client libraries and an embeddable React component (flowise-embed-react) for application developers. The API button generates copy-paste snippets for each.

Tip

Use Override Config on the API call to change a flow's behavior per request — for example, supplying a per-user system prompt or a different temperature — without editing the flow.

8. Working with credentials, files, and history

8.1 Chat sessions and history

Each conversation has a sessionId. Memory nodes key history off it, so different users (or different sessionIds on API calls) keep separate histories. The Executions view logs agent runs so you can replay exactly which tools were called and what each step returned.

8.2 Credentials

Credentials are created once and reused across flows:

1. Credentials → Add Credential, pick the provider, paste the secret.
2. Reference it from any node via Connect Credential.

Secrets are encrypted at rest with the instance encryption key and are never returned to the browser in plaintext. Some nodes also accept provider keys via environment variables (e.g. AZURE_OPENAI_API_KEY) as a default — see the Admin Guide's config reference.

8.3 Uploads and attachments

Flows can accept file and image uploads (for vision models and document Q&A). The upload size limit is controlled by FLOWISE_FILE_SIZE_LIMIT (default 50mb). Images are passed to multimodal models; documents are routed to loaders.

9. How Flowise works (concepts)

You don't need this section to use Flowise, but it helps you reason about behavior.

• A flow is a graph. Nodes are instantiated at runtime and connected by data type. When you send a message, Flowise walks the graph, runs each node, and streams the result back.
• Agents loop; chains don't. A chain runs its steps once in order. An agent repeatedly calls the model, lets it pick tools, and stops when the model produces a final answer.
• RAG = retrieve then generate. Your documents are chunked, embedded, and stored as vectors. At query time the most similar chunks are retrieved and handed to the model as context — that's how Flowise answers from your data without retraining a model.
• Memory is per session. History is scoped to a sessionId, persisted by whichever memory node you attach.
• Streaming uses server-sent events, so chat responses appear token-by-token.
• Queue mode (optional) offloads flow execution to background workers for scale — invisible to you as a builder, important to your admin. See the Admin Guide.

10. Troubleshooting

Format: the exact message → why it happens → how to fix → how to prevent.

Error: This agent only compatible with function calling models.

• Cause: You attached a chat model that doesn't support tool/function calling to a tool-using agent.
• Solution: Switch to a tool-capable model (ChatOpenAI, ChatAnthropic, ChatGoogleGenerativeAI, etc.).
• Prevention: Check the provider's tool-calling support before wiring it into an agent.

Error: Access to this host is denied by policy.

• Cause: A request node (HTTP, web scraper, custom tool) tried to reach a host blocked by Flowise's SSRF protection (HTTP_DENY_LIST / HTTP_SECURITY_CHECK).
• Solution: Verify the URL is correct and public. If the host is legitimately needed, ask your admin to adjust the deny list.
• Prevention: Don't point request tools at internal/private addresses; use public endpoints.

Error: Worker name is required! / Worker prompt is required!

• Cause: A multi-agent Worker node is missing its name or prompt.
• Solution: Open the Worker node and fill in both fields.
• Prevention: Configure every worker before running a multi-agent supervisor flow.

Error: Invalid JSON in the Worker

• Cause: A JSON field (worker input variables, tool input) contains malformed JSON.
• Solution: Validate the JSON — check for trailing commas and unquoted keys.
• Prevention: Use the node's JSON editor, which highlights syntax errors.

Error: Aborted!

• Cause: The run was cancelled (you clicked stop, the request timed out, or the server is shutting down).
• Solution: Re-run. If it recurs, check for a long-running tool or an external API timeout.
• Prevention: Set sensible timeouts on HTTP/tool nodes; avoid unbounded loops.

Error: Provided prompt is missing required input variables: [...]

• Cause: A prompt template references a variable (e.g. {context}) that isn't supplied by an upstream node.
• Solution: Connect the node that provides that variable, or remove the placeholder from the template.
• Prevention: Keep prompt placeholders in sync with the inputs your flow actually produces.

Error: Error fetching model list / Model file does not exist or is empty

• Cause: A node tried to load its dynamic model dropdown but the model-list source was unreachable or MODEL_LIST_CONFIG_JSON points at a missing file.
• Solution: Check connectivity and the path; remove MODEL_LIST_CONFIG_JSON to fall back to defaults.
• Prevention: Validate any custom model-list file before setting the variable.

Problem: Chatbot crashes / blank error in the UI

• Cause: Known issue #6466 — frontend error handling can crash when an Axios error has no response.
• Solution: Retry; check the server logs for the real error. Upgrade to the latest release where this is addressed.

Problem: "Unknown content type thinking" with Gemini agents

• Cause: Known issue #6448 — AgentFlow V2 with Gemini "thinking" mode enabled.
• Solution: Disable the model's thinking/extended-reasoning option, or use a different model, until patched.

Problem: A node I expected isn't in the panel

• Cause: It's disabled (DISABLED_NODES), or it's a community node and SHOW_COMMUNITY_NODES is off.
• Solution: Ask your admin to enable it (see Admin Guide).

Problem: Build fails with exit code 134

• Cause: Node ran out of heap during pnpm build.
• Solution: export NODE_OPTIONS="--max-old-space-size=4096" then rebuild (§2.2).

11. FAQ

Q: Is Flowise free? Yes. The core platform is open source under the Apache 2.0 license. Some advanced/enterprise features (SSO, RBAC, audit logs, organizations) require a commercial license; the rest is free to self-host.

Q: Do I need to know how to code? No for the common cases — you build visually. Coding helps when you write Custom Tools, Custom Functions, or integrate via the API. There's always a code escape hatch when you need one.

Q: Which LLM providers are supported? Dozens — OpenAI, Anthropic, Google (Gemini/Vertex), Azure OpenAI, AWS Bedrock, Mistral, Cohere, Groq, Ollama (local), HuggingFace, and many more. Bring your own API keys.

Q: Can I run models locally / offline? Yes — use Ollama or LocalAI chat-model and embedding nodes to run open-weight models on your own hardware.

Q: What's the difference between a Chatflow and an Agentflow? A Chatflow is a fixed pipeline (chains, RAG). An Agentflow (AgentFlow V2) is a multi-step, branching, possibly multi-agent workflow with explicit control-flow nodes (Condition, Loop, Human Input). Use Agentflows for anything beyond a single chain or single agent.

Q: How does Flowise answer questions about my own documents? Through retrieval-augmented generation (RAG): your docs are chunked, embedded, and stored in a vector store; relevant chunks are retrieved per question and given to the model. See §6.1.

Q: Where are my flows and keys stored? In the Flowise database (SQLite by default), under ~/.flowise. Credentials are encrypted with the instance encryption key. Back this folder up.

Q: Can multiple people use one instance? Yes. Workspaces, organizations, and role-based access control are available (enterprise features). See the Admin Guide.

Q: How do I deploy to production? Use Docker or a cloud platform (AWS, Azure, GCP, Railway, Render, and others have one-click templates). Switch the database to PostgreSQL and consider queue mode for scale. See the Admin Guide.

Q: How do I call my flow from my app? POST to /api/v1/prediction/<chatflowid> with an API key, or embed the chat widget. See §7.

Q: My agent ignores a tool I gave it. Why? Almost always the tool description is too vague. Rewrite it as a clear instruction about when to use the tool (§6.2).

Q: Can I import/export flows? Yes — use Export/Import to move flows between instances as JSON, or clone templates from the Marketplace.

Q: Is there a hosted version? Yes — Flowise Cloud is the managed offering if you'd rather not self-host.

12. Quick reference

12.1 First-run commands

12.2 Flow type cheat-sheet

12.3 Key endpoints (with an API key)

12.4 Useful settings (set as env vars or --FLAGS)

Tip

Anything in the configuration reference can be passed on the command line as a flag: npx flowise start --PORT=3001 --DEBUG=true. The full list lives in the Admin Guide.