Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
This page provides a comprehensive guide for setting up the Flow platform for local development. Flow is a monorepo consisting of a FastAPI backend and a Next.js frontend, utilizing several infrastructure components including PostgreSQL with pgvector, Redis, and Qdrant.
The development environment can be managed either entirely via Docker Compose or through a hybrid approach where infrastructure runs in Docker while the application services run natively on the host machine.
Architecture Overview
Flow's local development environment is structured as a monorepo with two primary service areas: apps/web (Frontend) and services/api (Backend). These interact with a suite of infrastructure services to provide agentic capabilities, RAG (Retrieval-Augmented Generation), and long-term memory.
The following diagram illustrates the relationship between the local development services:
The application uses Server-Sent Events (SSE) for streaming agent executions and pgvector for document retrieval.
Sources: README.md:12-25, AGENTS.md:21-25
Infrastructure Requirements
Flow relies on specific ports and environment variables for local operation. When running via docker compose, these are mapped to host ports to allow local tools (like database IDEs) to connect.
Port Mappings
| Service | Container Port | Host Port | Purpose |
|---|---|---|---|
| Web UI | 3000 | 13000 | Next.js Frontend |
| API | 8000 | 18000 | FastAPI / OpenAPI Docs |
| Postgres | 5432 | 55432 | Primary Database |
| Redis | 6379 | 16379 | Background Jobs & Cache |
| Qdrant | 6333 | 16333 | Agentic RAG (Optional) |
Sources: README.md:43-52, AGENTS.md:27-31
Environment Configuration
Initial setup requires copying the example environment file and providing an OpenAI API key for embeddings and LLM generations.
cp .env.example .env
# FLOW_OPENAI_API_KEY=sk-...
Sources: README.md:36-40
Setup Methods
1. Docker-Only Setup (Recommended)
This is the fastest way to get the full stack running. It builds the API, Worker, and Web containers alongside the infrastructure.
cd /path/to/Flow
docker compose up --build
Once running, the UI is accessible at http://localhost:13000 and API documentation at http://localhost:18000/docs.
Sources: README.md:34-41
2. Hybrid Setup (Native Development)
For active development, it is often preferred to run infrastructure in Docker and the application code natively to benefit from hot-reloading and faster debug cycles.
Infrastructure Start:
docker compose up -d db redis qdrant
Backend Setup (services/api):
The backend uses uv for dependency management.
export FLOW_DATABASE_URL=postgresql://flow:flow@localhost:55432/flow
export FLOW_REDIS_URL=redis://localhost:16379/0
export FLOW_JWT_SECRET=$(openssl rand -hex 32)
cd services/api
uv sync --extra dev
uv run uvicorn flow.interfaces.http.main:app --reload --port 8000
Frontend Setup (apps/web):
The frontend uses npm and requires an environment variable to point to the local API.
cd apps/web
npm install
npm run dev
# Set NEXT_PUBLIC_FLOW_API_URL=http://localhost:8000 in .env.local
Sources: README.md:152-171, AGENTS.md:10-15
Data Seeding and Initialization
After the services are running, the database must be initialized with canonical agents and skills. This is performed using Python scripts located in the services/api/scripts directory.
Seeding Agents and Skills
Seeding is idempotent; running these scripts multiple times will update existing configurations without duplicating data.
| Script | Purpose |
|---|---|
seed_agents_and_datasets.py | Creates 7 canonical agents (General Assistant, Research Analyst, etc.) and their evaluation golden sets. |
seed_skills.py | Populates agents with specialized skills (e.g., PDF extraction, sentiment analysis). |
Execution Command:
# Run from services/api
uv run python scripts/seed_agents_and_datasets.py
uv run python scripts/seed_skills.py
Sources: services/api/scripts/seed_agents_and_datasets.py:16-25, services/api/scripts/seed_skills.py:11-15
Golden Set Initialization
Golden sets are curated test cases used for agent evaluation. The seeding process creates sets for various domains:
- Research Analyst: Synthesizing academic sources.
- Code Review: Detecting security vulnerabilities.
- Bug Triage: Severity classification and root cause analysis.
Sources: services/api/scripts/seed_agents_and_datasets.py:175-350
Testing the Setup
To verify the installation, several test suites are available. These should be run from the services/api directory using pytest.
# Unit and offline tests
uv run pytest tests/ -v --ignore=tests/test_health.py
# Full suite (requires Postgres)
uv run pytest tests/ -v
For the frontend, regression checks for API contracts can be executed natively:
cd services/api && uv run pytest tests/test_preference_routes_patch.py -v
Sources: README.md:183-191, apps/web/README.md:20-25
Summary
Setting up Flow for local development involves configuring a multi-service environment spanning Next.js and FastAPI. Developers can utilize Docker for a managed experience or native tools (uv, npm) for a more responsive development cycle. Proper initialization through the provided seeding scripts is essential to populate the environment with the necessary agent architectures and skillsets.