Open source AI language learning platform available in two modes: self-hosted (free, run it on your own infrastructure) and as a hosted service operated by the FreeLingo team (paid subscription). A language model evaluates your CEFR level, generates a personalized study plan, and guides you through grammar, vocabulary, reading comprehension, writing lessons, AI-generated listening exercises, and AI-generated reading exercises — with optional voice features.
The study plan follows a CEFR-aligned curriculum (A1-C2) organized into units with clear competencies and prerequisites. After a deterministic placement assessment, FreeLingo creates a weekly roadmap based on your selected intensity (4, 8, 12, or 16 weeks), then unlocks lessons in sequence: grammar, vocabulary, reading, writing, and review.
The platform combines structure and adaptation: lessons are generated within curriculum boundaries, flashcards use SM-2 spaced repetition, and the AI tutor provides contextual streaming feedback in English (with optional brief support in the learner's native language). Listening exercises are generated on demand by the LLM, synthesised to MP3 via TTS, and cached per CEFR level — the user listens, answers 5 comprehension questions, and earns XP before the transcript is revealed. Reading exercises follow the same caching model but without audio — the AI generates a passage and 5 comprehension questions displayed side by side; the user reads and answers immediately, earning XP per correct answer. Progress tracking includes XP, streaks, skill scores, unit competencies, and an end-of-level completion test.
Don't want to manage your own server?
FreeLingo is available as a fully managed hosted service at freelingo.app.
Sign up, choose a subscription plan, and start learning immediately — no Docker, no GPU, no maintenance required. The hosted instance is operated by the FreeLingo team and always runs the latest stable version.
Self-hosting remains free and open source under the AGPL-3.0 licence. The hosted service exists for users who prefer a managed experience.
Need FreeLingo for your team or organisation?
- Private / on-premise deployment — Deploy FreeLingo on your own infrastructure with full control over data and configuration. Ideal for schools, language academies, and companies with data-sovereignty requirements.
- Dedicated managed instance — A turnkey deployment operated exclusively for your organisation: setup, hosting, maintenance, and updates included. Your data stays isolated in a dedicated environment.
- Commercial licence — Organisations that need to deploy a customised or white-labelled version without the open-source obligations of the AGPL can obtain a commercial licence. See COMMERCIAL_LICENSE.md for details.
Get in touch to discuss your requirements.
If FreeLingo is useful to you or your organisation, consider sponsoring the project on GitHub to support continued development and keep the self-hosted version free for everyone.
Monorepo: backend/ (Python FastAPI) + frontend/ (Next.js 16 App Router)
deployed via Docker Compose with PostgreSQL 16 and Redis 7.
The backend proxies all external services (Ollama, Kokoro, Whisper) —
the frontend never calls them directly.
freelingo/
├── assets/ # Logos and static assets
├── backend/ # FastAPI (Python)
├── docs/ # GitHub Pages landing site
├── frontend/ # Next.js (React)
├── messages/ # i18n translation files (de, en, es, fr, it, nl, pl, pt, ro, ru)
├── specs/ # Specification files
├── AGENTS.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
└── docker-compose.yml
| Layer | Technology |
|---|---|
| Frontend | Next.js 16+, shadcn/ui, Tailwind CSS, Zustand, next-intl |
| Backend | FastAPI, SQLAlchemy async, Alembic, Pydantic v2 |
| Database | PostgreSQL 16 |
| Cache | Redis 7 |
| LLM | Ollama (local) · OpenAI · Anthropic · DeepSeek |
| TTS | Kokoro-FastAPI (local) · OpenAI TTS API |
| STT | faster-whisper (local) · OpenAI Whisper API |
| Auth | JWT (access + refresh), multi-user, roles (admin/user). |
| Deploy | Docker Compose |
| Phase | Name | Status |
|---|---|---|
| 1 | Learning platform | ✅ Complete |
| 1+ | Learning Resources Hub | ✅ Complete |
| 2 | Local TTS + STT | ✅ Complete |
| 3 | Real-time conversation | ✅ Complete |
| 4 | Multi-language support | ✅ Complete |
| 5 | Stripe subscriptions | ✅ Complete |
| 6 | Listening | ✅ Complete |
| 7 | Reading | ✅ Complete |
| 8 | Feedback board | ✅ Complete |
| 9 | Memory | ✅ Complete |
Requirements: Docker, Docker Compose, Git, and Ollama running on the host.
# 1. Clone the repository
git clone https://github.com/artcc/freelingo.git
cd freelingo
# 2. Configure environment
cp .env.example .env
# Edit .env: set OLLAMA_BASE_URL, choose your model, and review other settings
# 3. Pull the recommended model (run on the host, not inside Docker)
ollama pull gemma4:e4b
# 4. Start all services (migrations run automatically on first start)
docker compose up -dAccess at http://localhost:3000 (or http://<server-ip>:3000).
The first registered user becomes admin automatically.
- Open Portainer → Stacks → Add stack.
- Choose Repository and enter the repo URL, or paste the contents of
docker-compose.ymldirectly into the Web editor. - Scroll down to Environment variables and add the variables from
.env.example(at minimum:SECRET_KEY,OLLAMA_BASE_URL,POSTGRES_PASSWORD). - Click Deploy the stack.
- Access the app at
http://<server-ip>:3000. Database migrations run automatically when the backend starts.
Tip: If Ollama runs on the same host as Portainer, set
OLLAMA_BASE_URL=http://host.docker.internal:11434. On Linux you may need to add theextra_hostsentry in the compose file (already included by default).
- The recommended model for Ollama is
gemma4:e4b. It can be changed in.env. - The backend acts as a proxy for Ollama/TTS/STT calls so the frontend never talks directly to those services.
- The
LLM_PROVIDERfield controls the LLM provider:ollama(local, recommended),openai,anthropic, ordeepseek. TTS_PROVIDERandSTT_PROVIDERare independent:local(Kokoro / faster-whisper) oropenai(OpenAI API).- The target language is always English (
en-USAmerican English oren-GBBritish English). The variant is chosen on the/onboardingscreen immediately after registration. The user's native language is asked during registration and is used only for flashcard translations and tutor feedback.
The real-time voice conversation feature uses a WebSocket connection (/ws/conversation). Next.js does not proxy WebSocket upgrades natively, so a reverse proxy is required in any production deployment to route /ws/* traffic to the backend container.
This is also a hard browser requirement: getUserMedia (microphone access) only works in a secure context — HTTPS or localhost. A reverse proxy terminating TLS is therefore mandatory for the conversation feature to work at all in production.
The WebSocket URL is derived automatically from window.location, so no extra configuration is needed on the frontend side — just ensure your reverse proxy forwards /ws/* to backend:8000.
TTS and STT each support two providers, selected independently via .env.
| Variable | Values | Notes |
|---|---|---|
TTS_PROVIDER |
local · openai |
local uses Kokoro-FastAPI; openai uses OpenAI TTS API |
STT_PROVIDER |
local · openai |
local uses faster-whisper; openai uses OpenAI Whisper API |
OPENAI_API_KEY |
string | Required for openai provider on either service |
When using openai providers, the kokoro and whisper Docker services can be removed from the stack — no local GPU required.
The kokoro and whisper services in docker-compose.yml are pre-configured for NVIDIA GPUs.
TTS_PROVIDER=local
STT_PROVIDER=localThe Kokoro image (ghcr.io/remsky/kokoro-fastapi-gpu) supports all NVIDIA architectures via two builds: :latest-cu128 (0.4.0+) for Blackwell/RTX 50-series, and :latest for Maxwell through Hopper (confirmed Pascal/GTX 10xx support).
For CPU-only hosts, replace the image tags and remove the deploy block in docker-compose.yml:
kokoro:
image: ghcr.io/remsky/kokoro-fastapi-cpu:latest
restart: unless-stopped
whisper:
image: onerahmet/openai-whisper-asr-webservice:latest
restart: unless-stopped
environment:
- ASR_MODEL=base
- ASR_ENGINE=faster_whisperUse
ASR_MODEL=baseorsmallon CPU. Larger models are very slow without a GPU.
All voices are for English. Grades reflect training data quality and quantity.
| Voice | Gender | Accent | Grade |
|---|---|---|---|
af_heart |
F | American | A ⭐ |
af_bella |
F | American | A- |
af_nicole |
F | American | B- |
am_fenrir |
M | American | C+ |
am_michael |
M | American | C+ |
am_puck |
M | American | C+ |
bf_emma |
F | British | B- |
bm_george |
M | British | C |
Set with TTS_VOICE=<voice> in .env. Default: af_heart.
| Model | VRAM | Speed vs large | Notes |
|---|---|---|---|
tiny.en |
~1 GB | ~10x | Very low accuracy |
small.en |
~2 GB | ~4x | OK for CPU |
medium |
~5 GB | ~2x | Good balance |
large-v3-turbo |
~6 GB | ~8x | Recommended — best speed/accuracy ratio |
large-v3 |
~10 GB | 1x | Maximum accuracy |
Set with STT_MODEL=<model> in .env. Default: large-v3-turbo.
| Engine | Notes |
|---|---|
faster_whisper |
Recommended — 4× faster than openai_whisper, lower VRAM via CTranslate2 |
openai_whisper |
Original PyTorch implementation |
whisperx |
Adds speaker diarization; requires HuggingFace token |
Set with STT_ENGINE=<engine> in .env. Default: faster_whisper.
TTS_PROVIDER=openai
STT_PROVIDER=openai
OPENAI_API_KEY=sk-...Uses the same OPENAI_API_KEY as the LLM if LLM_PROVIDER=openai. No extra services needed.
See CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting pull requests. By opening a pull request you accept the Contributor License Agreement.
Distributed under the GNU Affero General Public License v3.
Organisations that need to deploy FreeLingo without the AGPL's copyleft obligations can obtain a commercial licence. See COMMERCIAL_LICENSE.md or get in touch.
Arturo Carretero Calvo — @artcc