docs / quickstart

Getting Started

From a fresh clone to a running chat UI in a few minutes. Local dev mode needs no external infrastructure — no Keycloak, no Postgres, no OpenSearch — just an LLM API key.

What you'll have running

Local dev mode starts four processes: control-plane-backend (teams, sessions, agent enrollment), knowledge-flow-backend (document ingestion and retrieval), fred-agents (the agent pod that actually runs conversations), and the frontend (the chat UI you'll open in your browser).

By default, all data — chat history, documents, embeddings, metrics — is stored locally: SQLite for SQL/metadata, ChromaDB for vectors. Authentication is mocked, so there's no identity provider to stand up first.

This is the fast path for trying Fred and building agents, not a production topology. For something closer to a real deployment — Keycloak, OpenFGA, Postgres, OpenSearch, Temporal, all for real — see Closer to production below.

Source: README.md "Getting started" and "How Fred is structured"

Choose your setup

Dev Container recommended

Everything pre-installed, in an isolated container. No local Python/Node version juggling.

  • Docker / Docker Desktop
  • VS Code + the Dev Containers extension
  • Clone the repo, open in VS Code, F1 → Dev Containers: Reopen in Container

Ports 8000, 8111, 8222, and 5173 are forwarded to your host automatically.

Native

Everything installed directly on your machine. Unix-based OS only (Mac/Linux).

  • Python 3.12.8 (via pyenv) + python3-venv
  • Node.js 22.13.0 (via nvm)
  • make, yq, SQLite ≥ 3.35
  • Pandoc + LibreOffice (document ingestion) · libmagic (file-type detection)

Source: README.md "Development environment setup" (Option 1 / Option 2)

Point Fred at a model

Out of the box, Fred is configured for OpenAI's public API — gpt-4o for the agent pod, gpt-4o-mini chat + text-embedding-3-large embeddings for knowledge-flow. If that's what you're using, all you need is your key. Ollama (local/shared open models) and Azure OpenAI are also supported — swapping provider means editing a couple of fields in each backend's configuration.yaml, detailed in the README.

Whichever provider you pick, the API key goes in .env, never in configuration.yaml — that file is committed, .env is not.

Source: README.md "Model configuration"

Run it

  1. Copy the environment templates

    cp apps/fred-agents/config/.env.template apps/fred-agents/config/.env
cp apps/knowledge-flow-backend/config/.env.template apps/knowledge-flow-backend/config/.env
cp apps/control-plane-backend/config/.env.template apps/control-plane-backend/config/.env

    Then edit each one to add your OPENAI_API_KEY (or your chosen provider's key).

  2. Start everything

    # default — single process, everything in one place
make run

# or: split into separate API processes on their own ports
make run-multi

  3. Open the UI

    Head to http://localhost:5173 — that's it.

ComponentPort
frontend5173
fred-agents (agent pod)8000
knowledge-flow-backend8111
control-plane-backend8222

Source: README.md "Start Fred components", "Head for the Fred UI!"

Closer to production

When you're ready to see Fred run the way it actually deploys — Keycloak, OpenFGA, Postgres, OpenSearch, and Temporal, all real — the README's k3d Local Deployment section walks through a local Kubernetes cluster via Helm, using the backing services from fred-deployment-factory. One command builds, imports, and deploys: make k3d-deploy.

Source: README.md "k3d Local Deployment"