One flag.
Two runtimes.

Two ways to run it

Package users get an install that behaves like a desktop app — one command, no configuration. Contributors clone the repo and run the full stack with Redis and a Celery worker.

Package users — one command

Install the CLI, then bring the stack up. Lite mode needs no Redis, no Celery, and no environment file. Secrets are generated on first boot and the database URL and config live in ~/.fagoon.

$ pipx install fagoon
$ fagoon up                 # lite mode: no Redis, no Celery, zero env
$ fagoon up --ollama        # add the local Gemma fallback LLM

Open http://localhost:8000 and complete the setup wizard — an LLM key and the features you want enabled.

Contributors — clone and run

Copy the example environment file, fill in the minimal values, and bring up the full Compose stack. This builds from source and runs Redis plus a Celery worker alongside the app and database.

$ git clone https://github.com/<owner>/fagoon
$ cp .env.example .env      # fill minimal values
$ docker compose -f deploy/docker-compose.full.yml up --build

What it's built on

A layered FastAPI backend orchestrating AI providers, with PostgreSQL as both the relational store and the vector database.

The dual-mode runtime

Everything else in Fagoon follows from one design move: put an interface between the application and its infrastructure, then pick the backend once at startup. The flag is read a single time in src/core/runtime.py, which builds the right backends and attaches them to app.state.

Lite vs Full at a glance

Business code never touches Redis or Celery

This is the contract the whole design depends on. Application code talks only to three abstractions on app.state. Only the backend modules, runtime.py, and celery_app.py may import the real packages.

Four layers, strict boundaries

A clean separation that physically isolates routing, business logic, third-party clients, and bootstrapping. Each layer may only call inward.

Lifespan singletons

Heavy clients are initialized once during the FastAPI lifespan and attached to app.state — never instantiated per request: postgres_manager, httpx_client, vector_store, agent_manager, and chat_orchestrator.

Folder structure

The tree below mirrors the layered architecture — routing, services, providers, and models live in physically separate places.

.github/workflows/     # ci.yml (tests + guards) · release.yml (multi-arch + PyPI)
alembic/              # database migrations & schema history
deploy/               # Dockerfile, entrypoint.sh, both compose files
fagoon_cli/           # Typer control CLI + bundled compose files
scripts/              # setup & import-guard helper scripts
src/
├── api/v1/           # routers/ (domain routers) + setup_api.py
│   └── custom_middleware.py   # Auth & CORS
├── core/             # bootstrap · globals · runtime · settings
├── models/sql/       # SQLAlchemy models → PostgreSQL
├── providers/        # OpenAI, Gemini, … client wrappers
├── schemas/          # Pydantic request/response validation
├── services/         # cache · database · limiter · rag · taskqueue …
│   ├── google_workspace/      # Gmail, Docs, Drive
│   └── tool_handlers/         # search, mermaid, deep research
├── launch_server.py  # entry point · lifespan · teardown registry
└── constants.py
tests/                # unit · integration · guardrails
pyproject.toml         # packaging, scripts, deps
GEMINI.md              # AI mandate & current-state doc

What you can build

Fagoon bridges visual workflow construction, a live code sandbox, conversational channels, and secure external API endpoints — all from one dashboard.

Visual Workflow Canvas & Orchestrator

A drag-and-drop Directed Acyclic Graph builder where you chain multi-modal nodes into automated pipelines. Reach it from the Workflows sidebar icon or /workflow.

Publish a workflow as an API

Any saved workflow can become a fully-fledged REST endpoint, triggerable from your own sites or servers. Save in the canvas, then click 🔑 API Integration on the header bar.

$ curl -X POST "https://fagoon.tech/api/v1/workflow-api/{slug}/execute" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{"input": "Describe a spaceship"}'

Enterprise Vibe Coder

A visual sandbox that compiles, renders, and previews interactive HTML5 and React single-page apps live, using high-speed AI streaming. Reach it from the Vibe Coder sidebar icon or /coder.

Standard Chat Portal

A versatile multi-model conversational interface with retrieval-augmented generation. Open the home route /chat or a saved conversation at /c/{historyId}.

Autonomous AI Agents Hub

A specialized environment for goal-directed, pre-configured agents that perform enterprise tasks in loops. Open Agents in the sidebar or /agents.

Model Configuration Portal

A secure admin console to add and modify model setups and coordinate permissions across features. Open Manage Models or /manage-models.

User Settings & Preferences

Tailor persona, behavior, and appearance. Open your profile avatar → Profile, or /profile.

RAG-enabled agent chat

Retrieval-augmented generation streamed over Server-Sent Events. Entry point: POST /api/v1/agent/chat.

Background video generation

Long-running rendering, safe in both modes. The HTTP request returns immediately with a job_id; the work happens in a Celery worker (full) or an inline asyncio task (lite). Entry point: /api/v1/video-generation/….

Google Workspace operations

An OAuth authorization flow followed by token-delegated requests to Gmail, Docs, and Drive.

Authentication flow

AuthMiddleware runs on all non-public routes, bypassing paths in ALLOWED_URL_PATH_WITHOUT_AUTHORIZATION.

Database switching & live migration

Users can move from the bundled local Postgres to an external, user-supplied database. The process runs sequentially for zero-downtime safety — the local DB is left intact as a fallback. Handled in src/services/database/switch_service.py.

The fagoon CLI

A thin Typer wrapper over Docker Compose, giving package users an n8n-like one-command experience. It ships its own bundled compose files, so nothing has to be downloaded by hand.

Configuration & secrets

A layered settings resolver lets one codebase serve both audiences: a contributor's environment wins, while a package user who sets nothing still boots on the file and default layers.

Resolution precedence (highest first)

First-boot bootstrap

On first run, ensure_bootstrap generates the JWT_SECRET and a Fernet encryption_key, persisting them to config.json with 0o600 permissions. This is what lets a package user install with zero environment variables. User-supplied integration secrets (LLM keys, Google OAuth) are entered via the UI and stored encrypted in the DB credentials table.

Key environment variables

Development & quality

Tests run under pytest with lite mode as the default test environment. Three checks gate every change.

# Run the core test suite
$ uv run pytest tests

# Architecture boundary — forbid stray redis/celery imports
$ uv run lint-imports
$ bash scripts/guard_imports.sh

# Code style
$ uv run ruff check .

# Database migrations
$ alembic upgrade head

Guardrails, CI & release

The answer to "I can't review every PR." Three automated gates make it physically impossible to merge a change that breaks the lite-mode contract.

Pipelines

ci.yml runs tests, the lite-boot proof, and architecture checks on every PR and on main — publishing nothing. release.yml fires only on v* tags: it builds a multi-arch image to GHCR, publishes the CLI to PyPI via trusted publishing, and cuts a GitHub release. CODEOWNERS forces maintainer review on the mode-machinery files.

How dual-mode was built — 10 phases

The refactor is one move — "put an interface between code and backend" — repeated for the three things that touch Redis and Celery. Each phase has a known-good starting point and a verification step.

What not to do

The constraints that keep both modes honest. Breaking any of these is how lite installs crash and how concurrency bugs creep in.