Flowise Admin Guide

This guide is for the people who deploy, operate, secure, and extend Flowise: platform admins, DevOps/SRE, backend developers, and architects. It documents the system architecture, the full configuration surface, deployment strategies (including high-scale queue mode), security hardening, the data model, operations, and the custom-node SDK for developers extending the platform.

For builder-facing usage (the visual canvas, node types, RAG, deploying a chatbot), see the Flowise User Guide. This guide assumes that knowledge and goes underneath it.

Note

Scope discipline. Flowise is a workflow-automation platform that ships hundreds of integration nodes. This guide documents the platform — server architecture, the node-loading/execution engine, configuration, and the SDK contract every node implements — not each of the 300+ individual integrations. Once you understand INode and NodesPool, every integration is the same shape.

1. Executive summary

What it is: Flowise turns a visual graph of nodes into an executable LLM application — a chatbot, an autonomous agent, or a REST API. The server loads every node into an in-memory pool at boot, instantiates the graph per request, executes it (optionally on background workers), and streams results over SSE.

Operational headline: a single container with SQLite is enough for evaluation and small teams. For production, switch to PostgreSQL, externalize storage and secrets, and enable queue mode to scale execution horizontally.

2. Architecture

2.1 Monorepo layout

Flowise is a single repository with multiple packages built by Turborepo:

The first three are the product; the last three are publishable building blocks. flowise (server) depends on flowise-components and flowise-ui as workspace dependencies, so a single flowise start serves the API, the UI, and the node library together.

2.2 Runtime topology

                         ┌──────────────────────────────────────────┐
   Browser / API client  │              flowise (server)            │
        │                │                                          │
        ▼                │  Express app                             │
  ┌───────────┐  HTTP/SSE│   ├── /api/v1/* routers (66 sub-routers) │
  │  React UI │◄────────►│   ├── auth (passport) + RBAC middleware  │
  │ (flowise- │          │   ├── NodesPool (all nodes, in memory)   │
  │   ui)     │          │   ├── execution engine (build + run graph)│
  └───────────┘          │   ├── SSEStreamer (token streaming)      │
                         │   ├── AbortControllerPool (cancel runs)  │
                         │   ├── CachePool / RateLimiterManager     │
                         │   └── ScheduleBeat (cron-triggered flows) │
                         └───────┬───────────────┬──────────────────┘
                                 │               │
                    ┌────────────▼───┐    ┌──────▼───────────────────┐
                    │  Database      │    │  Optional (MODE=queue)   │
                    │ (TypeORM):     │    │  BullMQ + Redis          │
                    │ sqlite/pg/     │    │   ├── QueueManager       │
                    │ mysql/mariadb  │    │   ├── prediction workers │
                    └────────────────┘    │   └── RedisEventSubscriber│
                    ┌────────────────┐    └──────────────────────────┘
                    │ Object storage │
                    │ local/s3/gcs/  │    ┌──────────────────────────┐
                    │ azure          │    │ Secrets: file / AWS SM   │
                    └────────────────┘    └──────────────────────────┘

2.3 Boot sequence

flowise start → BaseCommand.init() (loads .env, maps --FLAGS to process.env) → DataSource.init() → Server.start(). The App.initDatabase() sequence (in packages/server/src/index.ts) is the authoritative startup order:

1. DataSource initialize — connect via TypeORM.
2. Run migrations — each in its own transaction; schema is auto-migrated on every boot.
3. IdentityManager — auth/enterprise identity (users, orgs, workspaces, plan features).
4. NodesPool — scan flowise-components and load every node class into memory.
5. AbortControllerPool — registry for cancelling in-flight predictions.
6. Encryption key — load/generate the key used to encrypt stored credentials.
7. Auth secrets — resolve JWT/session/hash secrets (env → AWS Secrets Manager → filesystem).
8. Rate limiters — built per-chatflow from saved rate-limit config.
9. CachePool + UsageCacheManager — response/usage caches.
10. QueueManager — only when MODE=queue; wires BullMQ queues and the Bull-Board dashboard.
11. Metrics provider — Prometheus or OpenTelemetry, if ENABLE_METRICS=true.
12. SSEStreamer — server-sent-events channel for streaming.
13. Webhook listener registry + ScheduleBeat — webhook triggers and cron-scheduled flows.

Important

Migrations run automatically at startup against per-dialect migration sets (packages/server/src/database/migrations/{sqlite,postgres,mysql,mariadb}). Always back up the database before upgrading the image — a new release may add migrations that alter the schema in place.

2.4 The execution engine

When a prediction request arrives:

1. The chatflow's saved JSON graph is loaded.
2. Nodes are instantiated from NodesPool and topologically resolved.
3. Each node's init()/run() is invoked with resolved inputs and an options bag (session, credentials, callbacks).
4. Streaming output is pushed through SSEStreamer; the run is cancellable via AbortControllerPool.
5. In MODE=queue, steps 2–4 run on a worker process; the web process enqueues the job and subscribes to events via Redis.

AgentFlow V2 (in packages/agentflow + packages/components/nodes/agentflow) is Flowise's own orchestration layer for multi-step/branching agents, distinct from the underlying LangChain agent primitives.

3. Requirements

4. Configuration mastery

Flowise is configured entirely through environment variables, which can be set in .env, the process environment, the Docker Compose .env, or passed as CLI flags to flowise start (every variable below has a matching --FLAG, defined in packages/server/src/commands/base.ts).

Tip

npx flowise start --PORT=3001 --DATABASE_TYPE=postgres --MODE=queue is equivalent to setting those three env vars. Flags override .env.

4.1 Core & networking

4.2 Database

4.3 Secrets & credential encryption

Caution

The encryption key decrypts every stored credential. If you lose it, all stored provider keys become unrecoverable and flows that use them break. In production, set SECRETKEY_STORAGE_TYPE=aws or inject FLOWISE_SECRETKEY_OVERWRITE from your secret manager — never bake it into an image.

4.4 Authentication

Authentication is built on Passport with strategies for local login, JWT cookies, and SSO providers (Google, GitHub, Auth0, generic OpenID Connect). The public prediction API authenticates with API keys (managed under the ApiKey entity / /api/v1/apikey).

4.5 Storage

4.6 Queue mode (scaling)

4.7 Security

4.8 Logging, metrics, proxy, schedule

4.9 Enterprise

5. The data model

TypeORM entities (packages/server/src/database/entities) define the schema. Core (Apache) tables:

Enterprise tables (packages/server/src/enterprise/database/entities): User, Organization, Role, OrganizationUser, Workspace, WorkspaceUser, LoginMethod, LoginSession, LoginActivity, WorkspaceShared, WorkspaceUsers.

Migrations are maintained separately per dialect under migrations/{sqlite,postgres,mysql,mariadb} and applied automatically on boot.

6. API reference

The API is mounted at /api/v1 (see packages/server/src/routes/index.ts, which composes 66 sub-routers). Authentication: API key (Authorization: Bearer <key>) for the public prediction surface; JWT cookie session for the management API behind the UI. Some routes are gated by plan features via IdentityManager.checkFeatureByPlan(...).

6.1 Most-used endpoints

6.2 Enterprise endpoints

/api/v1/auth, /user, /organization, /role (feat:roles), /workspace, /account, /loginmethod, /audit (feat:login-activity), /logs (feat:logs). The account.route (under enterprise/routes) handles registration, email verification, password reset, and billing.

6.3 Interactive docs

Run the flowise-api package (Swagger UI generated from Express JSDoc) for a live, parameter-level API explorer.

7. Deployment

7.1 Docker Compose (recommended baseline)

cd Flowise/docker
cp .env.example .env
# edit .env: set DATABASE_*, secrets, STORAGE_*, etc.
docker compose up -d

The provided docker-compose.yml:

• Pulls flowiseai/flowise:latest, restart: always.
• Maps every config variable from .env into the container.
• Persists ~/.flowise via a volume (~/.flowise:/root/.flowise).
• Defines a healthcheck hitting /api/v1/ping.

Warning

The default volume mounts the host's ~/.flowise. For production, point DATABASE_* at an external PostgreSQL and STORAGE_TYPE at S3/GCS/Azure so state isn't trapped on one host's disk. The bundled compose also has no TLS — terminate HTTPS at a reverse proxy (Traefik/Nginx/cloud LB) and set SECURE_COOKIES=true, TRUST_PROXY, and NUMBER_OF_PROXIES.

7.2 Production checklist

• [ ] DATABASE_TYPE=postgres with managed PostgreSQL (and DATABASE_SSL=true).
• [ ] STORAGE_TYPE=s3|gcs|azure for durable file storage.
• [ ] SECRETKEY_STORAGE_TYPE=aws or injected FLOWISE_SECRETKEY_OVERWRITE.
• [ ] Strong, externally-managed JWT_*, EXPRESS_SESSION_SECRET, TOKEN_HASH_SECRET (openssl rand -hex 32).
• [ ] HTTPS at the proxy; SECURE_COOKIES=true; CORS_ORIGINS and IFRAME_ORIGINS locked to known origins.
• [ ] HTTP_SECURITY_CHECK=true, sensible HTTP_DENY_LIST (block cloud metadata IPs, internal ranges).
• [ ] Custom-code deps restricted (ALLOW_BUILTIN_DEP=false, tight TOOL_FUNCTION_*_DEP).
• [ ] MCP: keep CUSTOM_MCP_PROTOCOL=sse; only stdio for fully trusted operators.
• [ ] Backups for the database and the encryption key.
• [ ] ENABLE_METRICS=true wired to Prometheus/OTel; log shipping configured.

7.3 Scaling with queue mode

For high concurrency, run the web tier and worker tier separately:

# Web process(es) — serve API/UI, enqueue jobs
MODE=queue REDIS_HOST=redis ... npx flowise start

# Worker process(es) — execute flows
MODE=queue REDIS_HOST=redis ... npx flowise worker

The repo ships dedicated compose files for this: docker/docker-compose-queue-prebuilt.yml and docker/docker-compose-queue-source.yml, plus a docker/worker image with its own healthcheck. Scale by adding worker replicas; tune WORKER_CONCURRENCY and job retention (REMOVE_ON_AGE/REMOVE_ON_COUNT). Enable ENABLE_BULLMQ_DASHBOARD to watch the queue via Bull-Board.

Note

The CLI exposes three commands: flowise start (web/all-in-one), flowise worker (queue worker), and flowise user (user administration). All accept any config variable as a --FLAG.

7.4 Managed platforms

One-click templates exist for AWS, Azure, GCP, Digital Ocean, Railway, Render, Northflank, HuggingFace Spaces, Elestio, Sealos, and RepoCloud. Flowise Cloud is the vendor-hosted option.

8. Security

Flowise executes user-authored graphs and, optionally, user-authored code — so the security model centers on sandboxing untrusted input and constraining outbound access.

8.1 Threat surface & controls

8.2 Authentication & authorization

• App access: Passport (local + JWT cookie). SSO via Google, GitHub, Auth0, OpenID Connect.
• API access: API keys (ApiKey entity), validated by validateAPIKey middleware; some URLs are API-key-blacklisted or whitelisted (API_KEY_BLACKLIST_URLS, WHITELIST_URLS).
• RBAC (enterprise): Organizations → Workspaces → Roles. Feature gates (IdentityManager.checkFeatureByPlan) restrict datasets, evaluations, roles, audit logs, etc. by license plan.
• Rate limiting: per-chatflow limits via RateLimiterManager (optionally backed by Redis).

8.3 Known security items

• #6444 — request for CVE assignment for GHSA-jg8m-mc94-2g3x (Critical RCE). Track the advisory and stay on the latest release.
• #6433 — proposed pre-execution trust-verification hook for MCP tool calls.
• #6413 — agent-memory poisoning hardening (OWASP ASI06).

Caution

Treat any Flowise instance that allows untrusted users to author Custom Tools/Functions or Custom MCP stdio servers as a remote-code-execution surface. Isolate it (dedicated network segment, no cloud-metadata access, least-privilege IAM) and keep dependency allowlists tight.

9. Operations

9.1 Start / stop / health

9.2 Backups

Back up two things together: the database (SQLite file or your Postgres/MySQL dump) and the encryption key (SECRETKEY_PATH file or the AWS secret). Restoring a database without its matching key leaves credentials undecryptable. Also back up BLOB_STORAGE_PATH (or rely on your object store's durability).

9.3 Upgrades

1. Read the release notes for breaking changes/migrations.
2. Back up DB + key.
3. Pull the new image / pnpm install && pnpm build.
4. Restart — migrations run automatically.
5. Smoke-test /api/v1/ping, a prediction, and a RAG flow.

9.4 Monitoring

Enable metrics (ENABLE_METRICS=true) and scrape Prometheus (prom-client) or export to an OpenTelemetry collector. Per-node metrics are included by default (METRICS_INCLUDE_NODE_METRICS=true). Watch: prediction latency/error rate, queue depth and worker concurrency (queue mode), DB connections, and event-loop lag (heavy graphs are CPU-bound).

10. Extending Flowise: the custom-node SDK

Every integration is a node implementing the INode contract in packages/components/src/Interface.ts. The loading engine (NodesPool) discovers node classes in flowise-components at boot, so a new node is just a class file that exports a default class with the right shape.

10.1 The INode contract

A node combines descriptive properties with optional inputs, credential, and execution methods:

export interface INodeProperties {
    label: string          // display name in the palette
    name: string           // unique internal id
    type: string           // node type
    icon: string           // icon asset
    version: number        // node version (for migrations)
    category: string       // palette grouping (Chat Models, Tools, ...)
    baseClasses: string[]  // output types it satisfies (drives anchor compatibility)
    description?: string
    badge?: string
    deprecateMessage?: string
    // ...
}

export interface INode extends INodeProperties {
    credential?: INodeParams
    inputs?: INodeParams[]
    output?: INodeOutputsValue[]
    loadMethods?: {
        [key: string]: (nodeData: INodeData, options?: ICommonObject) => Promise<INodeOptionsValue[]>
    }
    vectorStoreMethods?: {
        upsert: (nodeData, options?) => Promise<IndexingResult | void>
        search: (nodeData, options?) => Promise<any>
        delete: (nodeData, ids, options?) => Promise<void>
    }
    init?(nodeData: INodeData, input: string, options?: ICommonObject): Promise<any>
    run?(nodeData: INodeData, input: string, options?: ICommonObject): Promise<string | ICommonObject>
}

Key concepts:

• baseClasses drive anchor compatibility — a node whose baseClasses includes BaseChatModel can connect to any input that accepts a BaseChatModel. This is how the canvas knows a chat model can plug into a chain's "Chat Model" slot.
• inputs: INodeParams[] declares the fields the UI renders. Each INodeParams has a type (string, number, boolean, password, json, code, options, asyncOptions, datagrid, file, folder, tabs, …), plus options, defaults, conditional show/hide rules, and acceptVariable to allow {{$vars.*}}.
• loadMethods populate asyncOptions dropdowns dynamically (e.g. fetch a provider's model list at edit time).
• vectorStoreMethods are implemented by vector-store nodes to support upsert/search/delete.
• init() builds the underlying object (e.g. a LangChain chat model); run() executes it. Most "instance" nodes implement init() and return a LangChain/LlamaIndex object that downstream nodes consume.
• credential references one or more INodeCredential definitions; the resolved (decrypted) secret is passed in options at runtime.

10.2 Anatomy of a typical node

class MyChatModel_ChatModels implements INode {
    label = 'My Chat Model'
    name = 'myChatModel'
    version = 1.0
    type = 'MyChatModel'
    icon = 'mymodel.svg'
    category = 'Chat Models'
    baseClasses = ['MyChatModel', 'BaseChatModel', 'BaseLanguageModel']
    credential: INodeParams = { label: 'Connect Credential', name: 'credential', type: 'credential', credentialNames: ['myApi'] }
    inputs: INodeParams[] = [
        { label: 'Model Name', name: 'modelName', type: 'string', default: 'my-default' },
        { label: 'Temperature', name: 'temperature', type: 'number', default: 0.7, optional: true }
    ]
    async init(nodeData: INodeData, _: string, options: ICommonObject): Promise<any> {
        const apiKey = getCredentialParam('myApiKey', await getCredentialData(nodeData.credential, options), nodeData)
        return new ProviderChatModel({ apiKey, model: nodeData.inputs?.modelName, temperature: nodeData.inputs?.temperature })
    }
}
module.exports = { nodeClass: MyChatModel_ChatModels }

A node usually instantiates a real LangChain/LlamaIndex class — document the node's params and which class it wraps, not the library internals.

10.3 Credentials as nodes

Credentials are declared the same way (INodeCredential with inputs: INodeParams[]) and live alongside nodes in packages/components/credentials. They appear in the Connect Credential dropdown for any node that lists them in credentialNames.

10.4 Building & contributing

pnpm install
pnpm build            # turbo build across all packages
pnpm dev              # watch mode; UI on :8080, server on :3000
pnpm test             # jest across packages
pnpm lint             # eslint

Use migration:create (root) and the per-dialect typeorm:migration-* scripts (server package) when changing the schema. The repo uses changesets for versioning and husky + lint-staged for pre-commit checks. See CONTRIBUTING.md.

11. Code quality & conventions

• Language/build: TypeScript 5.4, Turborepo task graph, pnpm workspaces, Vite (UI + embeddable packages), gulp (asset copy for server/components), oclif (CLI).
• Style: Prettier (4-space, single quotes, no semicolons, width 140) + ESLint (TS, React, a11y, unused-imports). Enforced via husky/lint-staged.
• Testing: Jest unit tests (note the *.test.ts files alongside controllers/services/nodes) + Cypress E2E in packages/server/cypress. Coverage is modest — confidence_gaps flagged thin test coverage; treat broad refactors with care.
• Patterns: Singleton "pools/managers" initialized at boot (NodesPool, CachePool, QueueManager, RateLimiterManager, IdentityManager); dependency-injection-free, module-singleton style. Clear MVC split in server (routes/ → controllers/ → services/).
• Error handling: centralized errorHandlerMiddleware; InternalFlowiseError carries HTTP status codes (http-status-codes). A deliberate uncaughtException/unhandledRejection catch-all keeps the process alive (flagged with a TODO to surface proper UI errors).

12. Potential improvements & tech debt

Observed from the source (candidates, not prescriptions):

• Process-level error swallowing. BaseCommand.init registers global uncaughtException/unhandledRejection handlers that only log — the in-code TODO notes this should be replaced with structured error propagation to the UI.
• WORKER_CONCURRENCY default of 100000 is effectively "unbounded"; operators should set a realistic value to avoid resource exhaustion under load.
• Node-version drift. README says Node >= 20; engines.node is ^24 and the Docker image is node:24-alpine. Pin a single supported version to avoid native-module build surprises (faiss-node, sqlite3 are in onlyBuiltDependencies).
• Test coverage is thin relative to surface area (the briefing flagged low coverage); the auto-runMigrations({ transaction: 'each' }) on every boot makes a migration test harness valuable before releases.
• Custom-code sandbox depends on vm2 (pinned 3.11.2); vm2 is historically a source of sandbox-escape CVEs. Keep dependency allowlists tight and monitor advisories.
• Pending hardening tracked in issues: MCP pre-execution trust hook (#6433), agent-memory poisoning defense (#6413), and the critical RCE advisory (#6444).

13. Troubleshooting (operations)

Error: Database migrations fail on boot

• Cause: Schema drift or a partially-applied migration after a downgrade.
• Solution: Restore from backup; never downgrade across a migration boundary. Check the dialect-specific migration set matches DATABASE_TYPE.

Problem: Credentials decrypt to garbage after a restore

• Cause: Database restored without the matching encryption key.
• Solution: Restore the SECRETKEY_PATH file / AWS secret from the same backup point. Re-enter credentials only if the key is truly lost.

Problem: Predictions hang or pile up (queue mode)

• Cause: No workers running, Redis unreachable, or WORKER_CONCURRENCY mis-set.
• Solution: Confirm at least one flowise worker is up and connected to the same Redis; inspect Bull-Board (ENABLE_BULLMQ_DASHBOARD); check REDIS_*.

Error: Access to this host is denied by policy.

• Cause: SSRF protection blocked an outbound request from a node.
• Solution: Intended for internal/blocked hosts. If legitimate, narrow HTTP_DENY_LIST; never disable HTTP_SECURITY_CHECK in production.

Problem: Behind a load balancer, cookies/HTTPS misbehave

• Cause: Proxy headers not trusted.
• Solution: Set TRUST_PROXY, NUMBER_OF_PROXIES, and SECURE_COOKIES=true; terminate TLS at the proxy.

Problem: Web scraper / PDF loaders fail in Docker

• Cause: Missing/looked-up Chromium path.
• Solution: The official image bundles Chromium at /usr/bin/chromium-browser; for custom images set PUPPETEER_EXECUTABLE_FILE_PATH / PLAYWRIGHT_EXECUTABLE_FILE_PATH.

Problem: Out-of-memory during build

• Cause: Monorepo build is memory-hungry.
• Solution: NODE_OPTIONS=--max-old-space-size=4096 (image already uses 8192).

14. Quick reference

14.1 CLI

14.2 Critical production env vars

14.3 Key source locations