Langflow Administrator and Developer Guide

This guide is the source-of-truth operational reference for Langflow — the visual flow-builder for LLM applications maintained by langflow-ai. It is written for the people who keep Langflow running and the people who extend it: self-hosters, platform engineers, SREs, security reviewers, and developers who write Custom Components or contribute to core. The companion User Guide covers everyday product use; this Admin Guide deliberately does NOT repeat tutorials, recipe walkthroughs, the Playground tour, or the editor canvas. It picks up where the User Guide leaves off.

The repository ships two distributions that share most code: langflow (the full server with React UI, multi-user database, auth, MCP, Store, deployment adapters, and a 400+ component catalog) and lfx (a slim runtime + DevOps CLI that runs flow JSON without a database or UI). Both are deployed from the same monorepo and built around the same graph engine. Where settings, behaviours, or operational concerns differ between them, this guide calls it out explicitly.

1. Executive Summary

Langflow is a Python (FastAPI/SQLModel) backend wrapped in a React 19 single-page application. Users compose flows on a canvas, the editor compiles the canvas into a typed DAG of components, and the backend executes the DAG either synchronously, with Server-Sent Events streaming, or in a fan-out polling mode. The server keeps state in SQLite by default (auto-migrated to an async driver) and is production-recommended on PostgreSQL 14+ via the [postgresql] optional extra. Authentication is JWT-based (HS256 by default; RS256/RS512 available) layered with a per-user database-stored API key system, and an opt-in SSO module that supports JWT, OIDC, SAML, and LDAP providers. Background work (Celery), object storage (local or S3), Prometheus + OpenTelemetry, Sentry, and a configurable cache (async, redis, memory, disk) round out the operational surface.

2. Architecture

2.1 High-Level Component Diagram

                         ┌─────────────────────────────────────────────┐
                         │              Reverse Proxy                   │
                         │         (Traefik / nginx / etc.)            │
                         └──────────┬──────────────┬───────────────────┘
                                    │              │
                         ┌──────────▼──────┐ ┌─────▼──────────────────┐
                         │  React 19 SPA   │ │   FastAPI Backend      │
                         │  (XY Flow       │ │   (uvicorn :7860)      │
                         │   canvas,       │ │                        │
                         │   TypeScript)   │ │  /api/v1/*  /api/v2/* │
                         └────────────────┘ │  /health  /health_check│
                                            │  /logs    /logs-stream │
                                            └──────┬─────┬───────────┘
                                                   │     │
                         ┌─────────────────────────▼┐  ┌─▼──────────────┐
                         │  SQLite (default)         │  │  Cache Layer    │
                         │  or PostgreSQL 14+        │  │  async/redis/   │
                         │  (SQLAlchemy + Alembic)   │  │  memory/disk    │
                         └──────────────────────────┘  └────────────────┘
                                                             │
                         ┌───────────────────────────────────▼──────────┐
                         │  Optional Services                           │
                         │  • Celery workers (Redis/RabbitMQ broker)    │
                         │  • S3 object storage                        │
                         │  • Prometheus metrics (:9090)               │
                         │  • Sentry error tracking                    │
                         │  • MCP Composer (uvx-managed)               │
                         └─────────────────────────────────────────────┘

2.2 Backend Stack

2.3 Frontend Stack

2.4 Service Manager Architecture

Langflow uses a dependency-injection service manager pattern. All backend services are registered as factories with a central ServiceManager singleton. Services are lazily instantiated on first access and torn down cleanly on shutdown.

18 registered service types (from ServiceType enum):

Each service has a corresponding ServiceFactory subclass. The factory's create() method type hints declare dependencies on other services, which the manager resolves automatically via reflection (infer_service_types()).

2.5 Flow Execution Model

1. Canvas → DAG: The React editor serializes a flow as JSON (nodes + edges). The backend deserializes this into a Graph object.
2. Topological sort: graph.sort_vertices() produces an execution order respecting data dependencies. Optional start_component_id / stop_component_id prune the DAG.
3. Parallel build: Independent vertices in the same layer execute concurrently via asyncio.gather().
4. Event delivery: Three modes controlled by LANGFLOW_EVENT_DELIVERY:
   • streaming (default): SSE via DisconnectHandlerStreamingResponse, NDJSON format
   • polling: Client polls; server returns buffered NDJSON events
   • direct: Required when workers > 1 (multi-process); auto-selected
5. Webhook forwarding: WebhookEventManager broadcasts build events to SSE-connected UI clients when flows are triggered externally.

2.6 API Surface

Core API (v1)

25+ route groups mounted on /api/v1:

API v2

lfx Serve Endpoints

When running lfx serve, a lightweight FastAPI app exposes:

Health Endpoints

Warning

/health returns 200 even before Langflow is fully initialized (it is served by uvicorn). Use /health_check for readiness probes in Kubernetes or load balancer health checks.

3. Component Inventory

3.1 Monorepo Layout

langflow/
├── src/
│   ├── backend/
│   │   └── base/
│   │       └── langflow/           # Full-server Python package
│   │           ├── api/            # FastAPI routers (v1 + v2)
│   │           ├── agentic/        # Agentic flow execution
│   │           ├── services/       # 18 service implementations
│   │           ├── components/     # 400+ built-in component catalog
│   │           └── core/           # Celery config, graph utilities
│   ├── frontend/                   # React 19 + TypeScript SPA
│   │   ├── src/
│   │   │   ├── components/         # UI components
│   │   │   ├── pages/              # Route pages
│   │   │   └── utils/              # Helpers, cookie manager
│   │   └── tests/                  # Playwright e2e tests
│   └── lfx/                        # Lightweight runtime + CLI
│       └── src/lfx/
│           ├── cli/                # 11 CLI commands (Typer)
│           ├── graph/              # Graph engine (shared)
│           ├── services/           # Settings, auth base, MCP composer
│           └── events/             # EventManager
├── deploy/                         # Docker Compose, Traefik, Prometheus
├── docker/                         # Dev Dockerfiles
├── docker_example/                 # Quick-start Compose files
├── docs/                           # Docusaurus documentation site
├── scripts/                        # CI, translations, GP client
└── tests/                          # Backend test suites

3.2 Codebase Statistics

4. Requirements

4.1 Runtime Requirements

4.2 Hardware Sizing

Note

Memory usage scales with flow complexity and concurrent executions. Each running flow holds its entire graph in memory during execution.

4.3 Python Package Extras

The langflow package provides 80+ optional extras for LLM providers, vector stores, and integrations. Key extras:

Install with specific extras:

pip install "langflow[postgresql,redis,openai,anthropic]"

5. Configuration Reference

All settings are controlled via environment variables with the LANGFLOW_ prefix. The configuration is backed by two Pydantic BaseSettings models: Settings (general) and AuthSettings (authentication).

5.1 Core Settings

5.2 Database Settings

SQLite pragmas (defaults):

{"synchronous": "NORMAL", "journal_mode": "WAL", "busy_timeout": 30000}

Important

For production with multiple users, migrate to PostgreSQL. SQLite has limited concurrent write capability even with WAL mode. Set LANGFLOW_DATABASE_URL=postgresql://user:pass@host:5432/langflow and install with pip install "langflow[postgresql]".

5.3 Cache Settings

5.4 Storage Settings

5.5 MCP Settings

5.6 Performance and Limits

5.7 Telemetry and Monitoring

5.8 Feature Flags

5.9 Public Flow Settings

6. Security

6.1 Authentication Architecture

Langflow implements a layered authentication system:

Request → JWT Bearer Token OR API Key (X-API-Key header)
           │                         │
           ▼                         ▼
      JWT Validation            Key Lookup
      (HS256/RS256/RS512)       (DB or env)
           │                         │
           └─────────┬───────────────┘
                     ▼
              User Context
              (superuser / active / inactive)

JWT Configuration

Important

For production, switch to RS256 or RS512. Asymmetric keys allow token verification without exposing the signing key. Keys are auto-generated on first start and persisted to CONFIG_DIR/private_key.pem and CONFIG_DIR/public_key.pem with restricted file permissions (0600 on Unix).

API Key Source

Cookie Settings

6.2 Auto-Login Mode

Caution

AUTO_LOGIN=true is the default. This creates a superuser with default credentials and skips authentication checks. Set LANGFLOW_AUTO_LOGIN=false in any network-accessible deployment. When disabled, configure LANGFLOW_SUPERUSER and LANGFLOW_SUPERUSER_PASSWORD for initial admin access. Credentials are scrubbed from in-memory settings after superuser setup.

6.3 SSO Configuration

SSO requires SSO_ENABLED=true and a valid SSO_CONFIG_FILE pointing to a YAML file with provider-specific settings.

6.4 CORS Configuration

Warning

The default CORS_ORIGINS=* with CORS_ALLOW_CREDENTIALS=true is insecure. In production, set specific origins. The v2.0 release plans to change the credentials default to false when using wildcard origins.

6.5 SSRF Protection

Important

SSRF protection is disabled by default. When disabled, components can make requests to internal services, private networks, and cloud metadata endpoints (e.g., 169.254.169.254). Enable in production, especially in multi-tenant deployments. The v2.0 release plans to enable this by default.

6.6 Custom Component Security

Note

The component security feature is in beta. For true multi-tenant isolation, use hardware-level separation.

6.7 Webhook Authentication

6.8 Superuser CLI

6.9 Security Hardening Checklist

• [ ] Set LANGFLOW_AUTO_LOGIN=false
• [ ] Configure LANGFLOW_SUPERUSER and LANGFLOW_SUPERUSER_PASSWORD with strong credentials
• [ ] Switch LANGFLOW_ALGORITHM to RS256 or RS512
• [ ] Set LANGFLOW_CORS_ORIGINS to specific allowed origins
• [ ] Enable LANGFLOW_SSRF_PROTECTION_ENABLED=true
• [ ] Set LANGFLOW_ALLOW_CUSTOM_COMPONENTS=false in multi-tenant environments
• [ ] Set LANGFLOW_ENABLE_SUPERUSER_CLI=false
• [ ] Enable LANGFLOW_WEBHOOK_AUTH_ENABLE=true
• [ ] Set LANGFLOW_NEW_USER_IS_ACTIVE=false (require admin approval for new accounts)
• [ ] Use TLS termination at reverse proxy (Traefik, nginx)
• [ ] Restrict LANGFLOW_CONFIG_DIR filesystem permissions
• [ ] For RSA keys: verify private_key.pem has 0600 permissions

7. Deployment

7.1 Docker Compose (Production)

The deploy/ directory provides a production-ready Docker Compose configuration with Traefik reverse proxy:

# Key environment variables for deploy/.env
DOMAIN=langflow.example.com
TRAEFIK_TAG=langflow
STACK_NAME=langflow

Architecture:

Internet → Traefik (:80/:443)
             ├── /api/*  → backend (:7860)
             ├── /*      → frontend (:80)
             └── /flower → flower (:5555)

Internal:
  backend (:7860) → PostgreSQL (:5432)
                  → Redis (:6379)
  celeryworker    → Redis (:6379)
  pgadmin (:5050)
  prometheus (:9090) → flower (:5555)

Traefik routing labels (from deploy/docker-compose.override.yml):

# Backend
traefik.http.routers.langflow-backend-http.rule=PathPrefix(`/api/v1`) || PathPrefix(`/api/v2`) || PathPrefix(`/docs`) || PathPrefix(`/health`)

# Frontend
traefik.http.routers.langflow-frontend-http.rule=PathPrefix(`/`)

7.2 Quick-Start Docker Compose

For evaluation or small deployments, use the simplified compose file:

# docker_example/pre.docker-compose.yml
services:
  langflow:
    image: langflowai/langflow:1.0-alpha
    ports:
      - "7860:7860"
    depends_on:
      - postgres
    environment:
      - LANGFLOW_DATABASE_URL=postgresql://langflow:langflow@postgres:5432/langflow
      - LANGFLOW_CONFIG_DIR=app/langflow
    volumes:
      - langflow-data:/app/langflow

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: langflow
      POSTGRES_PASSWORD: langflow
      POSTGRES_DB: langflow
    volumes:
      - langflow-postgres:/var/lib/postgresql/data

7.3 Development Docker Compose

# docker/dev.docker-compose.yml
services:
  langflow:
    build:
      context: ..
      dockerfile: docker/dev.Dockerfile
    ports:
      - "7860:7860"
      - "3000:3000"
    environment:
      - LANGFLOW_DATABASE_URL=postgresql://langflow:langflow@postgres:5432/langflow
      - LANGFLOW_SUPERUSER=langflow
      - LANGFLOW_SUPERUSER_PASSWORD=langflow
      - LANGFLOW_CONFIG_DIR=/var/lib/langflow

Backend command:

uvicorn --factory langflow.main:create_app --host 0.0.0.0 --port 7860 --reload --loop asyncio

7.4 Kubernetes Considerations

• Readiness probe: Use GET /health_check (not /health). The /health endpoint returns 200 before the application is fully initialized.
• Port environment variable: Kubernetes auto-creates LANGFLOW_RUNTIME_PORT=tcp://<ip>:<port> for services. Langflow's settings validator automatically parses URL-format port values.
• Multi-worker: When running multiple replicas, set LANGFLOW_EVENT_DELIVERY=direct (auto-detected when workers > 1).
• Database migrations: Use LANGFLOW_MIGRATION_LOCK_NAMESPACE for coordinated advisory locking when multiple instances share a PostgreSQL database.
• Variable store: Set LANGFLOW_VARIABLE_STORE=kubernetes to use Kubernetes secrets for Global Variables instead of the database.

7.5 Reverse Proxy Configuration

When deploying behind a reverse proxy that strips a URL prefix:

LANGFLOW_ROOT_PATH=/langflow

This sets the ASGI root_path, ensuring MCP SSE transport includes the correct prefix in POST-back URLs.

7.6 SSL/TLS

For direct TLS termination (without a reverse proxy):

LANGFLOW_SSL_CERT_FILE=/path/to/cert.pem
LANGFLOW_SSL_KEY_FILE=/path/to/key.pem

Tip

In most production deployments, TLS is terminated at the reverse proxy (Traefik, nginx, cloud load balancer). Use these settings only when Langflow is directly exposed.

7.7 Celery Workers

Enable background task processing with Celery:

LANGFLOW_CELERY_ENABLED=true
LANGFLOW_REDIS_HOST=redis
LANGFLOW_REDIS_PORT=6379

Celery configuration supports both Redis and RabbitMQ brokers:

8. Operations

8.1 Startup Sequence

1. create_app() factory initializes FastAPI
2. register_all_service_factories() registers all 18 service factories
3. register_builtin_adapters() loads deployment adapters (conditionally)
4. External cache connection test (if redis/external cache configured)
5. initialize_database() runs Alembic migrations
6. setup_superuser() creates or validates superuser account
7. assign_orphaned_flows_to_superuser() cleans up unassigned flows
8. clean_transactions() + clean_vertex_builds() prune old records
9. All services marked ready

8.2 Database Migrations

Alembic migrations run automatically on startup. For PostgreSQL multi-instance deployments, migrations use advisory locks to prevent concurrent migration execution.

# Check migration log
LANGFLOW_ALEMBIC_LOG_FILE=alembic/alembic.log
LANGFLOW_ALEMBIC_LOG_TO_STDOUT=true  # Log to stdout instead

8.3 Monitoring

Prometheus Metrics

Enable with LANGFLOW_PROMETHEUS_ENABLED=true. Metrics are served on port 9090 (configurable via LANGFLOW_PROMETHEUS_PORT).

Prometheus scrape config (from deploy/prometheus.yml):

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["prometheus:9090"]
  - job_name: flower
    static_configs:
      - targets: ["flower:5555"]

Log Streaming

Authenticated endpoints for real-time log access:

Note

Log endpoints require authentication. Logs may contain sensitive information. Log streaming uses an in-memory ring buffer (log_buffer) and requires the log buffer to be enabled.

Sentry Integration

LANGFLOW_SENTRY_DSN=https://[email removed]/0
LANGFLOW_SENTRY_TRACES_SAMPLE_RATE=0.1   # Sample 10% of transactions
LANGFLOW_SENTRY_PROFILES_SAMPLE_RATE=0.1

8.4 Backup and Recovery

SQLite:

# Stop Langflow, copy the database file
cp $(LANGFLOW_CONFIG_DIR)/langflow.db langflow.db.backup

PostgreSQL:

pg_dump -h host -U langflow langflow > langflow_backup.sql

File storage:

• Local: back up the directory specified by LANGFLOW_CONFIG_DIR and LANGFLOW_KNOWLEDGE_BASES_DIR
• S3: standard S3 bucket backup/versioning

Critical files to preserve:

• CONFIG_DIR/secret_key — JWT signing key (HS256)
• CONFIG_DIR/private_key.pem — RSA private key (RS256/RS512)
• CONFIG_DIR/public_key.pem — RSA public key
• The database (flows, users, API keys, Global Variables)
• Knowledge base files

8.5 Data Retention

Langflow automatically prunes old data based on configurable limits:

Pruning runs during startup (clean_transactions(), clean_vertex_builds()) and periodically for public flows.

9. Troubleshooting

9.1 Startup Failures

9.2 Database Issues

9.3 MCP Issues

9.4 Performance Issues

9.5 Authentication Issues

10. Quick Reference

10.1 CLI Commands (lfx)

10.2 Default Credentials

Caution

Change all default credentials before any network-accessible deployment.

10.3 Key File Locations

10.4 Port Reference

11. Internals

11.1 Module Reference

langflow.main

Entry point. create_app() factory produces the FastAPI application, calls initialize_services().

langflow.services.utils

Orchestrates startup: initialize_services() registers all factories, validates external caches, runs database migrations, creates superuser, and prunes stale records.

Key functions:

• register_all_service_factories() — registers 18 service factories + MCP composer
• register_builtin_adapters() — loads Watsonx Orchestrate adapter (feature-flagged)
• setup_superuser() — creates/validates superuser, scrubs credentials from memory after
• teardown_superuser() — removes default superuser when AUTO_LOGIN is disabled
• clean_transactions() / clean_vertex_builds() — bulk-delete old records beyond configured limits

langflow.api.build

Core flow execution engine:

• start_flow_build() — creates job queue, starts build coroutine
• generate_flow_events() — builds graph, sorts vertices, executes DAG with event emission
• build_vertices() — recursive vertex builder with concurrent asyncio.gather()
• cancel_flow_build() — cancels running build jobs

langflow.services.event_manager

WebhookEventManager — in-memory SSE broadcast system for webhook-triggered builds. Uses asyncio.Queue per subscriber (max 100 items), 1-second emit timeout, automatic dead-queue cleanup.

langflow.api.router

Mounts all v1 and v2 routers. Conditionally includes deployment router (Watsonx Orchestrate) based on FEATURE_FLAGS.wxo_deployments.

langflow.services.factory

ServiceFactory base class with automatic dependency inference via infer_service_types(). Uses cachetools.LRUCache to memoize factory introspection results.

lfx.services.settings

Two Pydantic BaseSettings models:

• Settings — general configuration (100+ fields, all prefixed LANGFLOW_)
• AuthSettings — authentication configuration (JWT, SSO, cookies, superuser)

Custom EnvSettingsSource supports comma-separated list parsing for list-type fields.

11.2 Security Analysis

Password hashing: bcrypt via passlib.CryptContext

Key management:

• HS256: Secret key auto-generated with secrets.token_urlsafe(32), persisted to filesystem with restricted permissions
• RS256/RS512: 2048-bit RSA key pairs auto-generated via cryptography library. Private keys stored with 0600 permissions (Unix) or equivalent ACL (Windows)
• Credentials scrubbed from in-memory settings after superuser setup (reset_credentials())

Known security defaults to address:

• AUTO_LOGIN=true — bypasses all authentication
• CORS_ORIGINS=* with CORS_ALLOW_CREDENTIALS=true — overly permissive
• SSRF_PROTECTION_ENABLED=false — allows internal network access
• ALLOW_CUSTOM_COMPONENTS=true — permits arbitrary code execution
• WEBHOOK_AUTH_ENABLE=false — unauthenticated webhook access
• ENABLE_SUPERUSER_CLI=true — allows CLI superuser creation

11.3 Code Patterns

Service manager pattern: All services implement the abstract Service base class with name, ready, get_schema(), teardown(), and set_ready(). Factories declare dependencies through type hints on create().

Dependency injection: FastAPI dependency functions (get_settings_service(), get_db_service(), etc.) retrieve service instances from the global ServiceManager. Lazy initialization with factory fallbacks.

Async sessions: session_scope() context manager wraps SQLAlchemy async sessions with auto-commit/rollback. The legacy get_session() is deprecated (NotImplementedError).

Event-driven execution: EventManager registers named events (on_token, on_end_vertex, on_build_start, etc.) and delivers them via asyncio.Queue. WebhookForwardingQueue adapts the interface for SSE broadcast.

Adapter registry: Generic AdapterRegistry[T] with decorator-based registration (@register_adapter). Used for deployment providers (Watsonx Orchestrate). Feature-flagged and import-guarded.

11.4 Testing

The codebase has extensive test coverage across multiple layers:

CLI commands have thorough unit test coverage (120+ test classes for lfx CLI alone), testing command-line argument parsing, file operations, error handling, and edge cases.

11.5 Known Issues

Based on community-reported bugs (GitHub Issues):

11.6 Internationalization

Langflow uses Globalization Pipeline (GP) for translations. The scripts/gp/ directory contains HMAC-authenticated API clients for uploading English source strings and downloading translated bundles. Target languages are managed via the GP service, with tests verifying upload/download integrity.

12. Environment Variable Quick Reference

Complete alphabetical reference of all LANGFLOW_ environment variables documented in this guide: