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 with a free plan and paid subscriptions. 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 and reading exercises, and voice practice.
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 stay within curriculum boundaries and include native-language support, flashcards use SM-2 spaced repetition, and Lingu provides contextual text and voice tutoring with durable user-controlled memories. Generated Listening and Reading practice, pronunciation exercises, XP, streaks, skill scores, unit competencies, and end-of-level tests complete the learning workflow.
Don't want to manage your own server? FreeLingo is available as a fully managed hosted service at freelingo.app.
Sign up, start with a free plan, or upgrade to a paid subscription — no Docker, no GPU, no maintenance required. The hosted instance is operated by the FreeLingo team.
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 via the contact form 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 LLM, TTS, and STT services —
the frontend never calls them directly.
See the architecture specification for system structure and the Docker specification for runtime and image details.
freelingo/
├── assets/ # Logos and static assets
├── backend/ # FastAPI (Python)
├── data/ # Shared data files
├── 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 # AI assistant instructions
├── CHANGELOG.md # Version history
├── CODE_OF_CONDUCT.md # Community guidelines
├── COMMERCIAL_LICENSE.md # Commercial licence terms
├── CONTRIBUTING.md # Contribution guidelines
├── CONTRIBUTOR_LICENSE_AGREEMENT.md # CLA for contributors
├── DEVELOPMENT.md # Local development setup
├── docker-compose.yml # Production deployment
├── docker-compose.dev.yml # Development deployment
├── LICENSE # AGPL-3.0 licence
├── README.md # This file
└── run-dev.sh # Development helper script
- Frontend: Next.js 16, shadcn/ui, Tailwind CSS, Zustand, next-intl
- Backend: FastAPI, SQLAlchemy async, Alembic, Pydantic v2
- Data: PostgreSQL 16 and Redis 7
- LLM: Ollama, OpenAI, Anthropic, or DeepSeek
- Speech: Kokoro-FastAPI or OpenAI TTS; faster-whisper or OpenAI Whisper
- Auth: JWT access and refresh tokens with admin/user roles
- Deployment: Docker Compose
Requirements: Docker, Docker Compose, Git, either a supported cloud LLM API or Ollama, and either an NVIDIA GPU for the default local speech services or an OpenAI API key for cloud speech.
# 1. Clone the repository
git clone https://github.com/artcc/freelingo.git
cd freelingo
# 2. Configure environment
cp .env.example .env
# Edit .env: select the LLM and speech providers, configure credentials, and review other settings
# 3. If using the default Ollama provider, pull the recommended model on the host
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).
By default, the first registered user becomes an administrator; set FIRST_USER_IS_ADMIN=false to
disable this behavior.
- Open Portainer → Stacks → Add stack.
- Choose Repository and enter the repo URL, or paste the contents of
docker-compose.ymldirectly into the Web editor. - Add the variables from
.env.example. At minimum, configureDATA_PATH, thePOSTGRES_*values,REDIS_PASSWORD,SECRET_KEY, and the selected LLM and speech providers and credentials. - 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 proxies all LLM, TTS, and STT calls so the frontend never talks directly to providers.
- The
LLM_PROVIDERfield controls the LLM provider:ollama(local, recommended),openai,anthropic, ordeepseek. - Anthropic's output budget is configurable with
ANTHROPIC_MAX_TOKENS(default:8192) and must stay within the selected model's supported output limit. TTS_PROVIDERandSTT_PROVIDERare independent:local(Kokoro / faster-whisper) oropenai(OpenAI API).- Conversation, token, freemium, and trial limits are configurable in
.env.example. In general quota defaults,0means unlimited; in freemium feature quotas,0blocks that feature. - Supported study languages include English (
en-GB,en-US), Spanish (es-ES), Italian (it-IT), Portuguese (pt-PT), German (de-DE), French (fr-FR), Japanese (ja-JP), Korean (ko-KR), and Mainland Chinese (zh-CN). The study language is chosen on/onboardingand can be expanded later from Settings → My Languages. The user's native language is asked during registration and is used for flashcard translations, tutor feedback, lesson native explanations, and cached native-language help in static grammar, phrasebook, and vocabulary resources.
Redis requires vm.overcommit_memory=1 on the host to safely perform background saves (RDB snapshots). Without it, a fork() under low memory can fail and Redis may lose data on restart.
Run once on the server:
sudo sysctl vm.overcommit_memory=1
echo "vm.overcommit_memory = 1" | sudo tee -a /etc/sysctl.confThe first command applies the setting immediately (no reboot needed); the second persists it across reboots. This is a host-level setting — it cannot be applied from within the container without elevated privileges.
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 are required services. Each supports two providers selected independently via .env.
TTS_PROVIDER=localuses Kokoro-FastAPI;TTS_PROVIDER=openaiuses OpenAI TTS.STT_PROVIDER=localuses faster-whisper;STT_PROVIDER=openaiuses OpenAI Whisper.OPENAI_API_KEYis required when either service uses OpenAI.
The default local services in docker-compose.yml are configured for NVIDIA GPUs:
TTS_PROVIDER=local
STT_PROVIDER=localKokoro's bundled voices are English-only. Use OpenAI TTS for other study languages. For CPU-only local deployment, select CPU images, remove GPU reservations, and use a smaller Whisper model as documented in the Docker specification.
OpenAI providers require no local GPU or speech containers:
TTS_PROVIDER=openai
STT_PROVIDER=openai
OPENAI_API_KEY=sk-...The services reuse OPENAI_API_KEY when OpenAI is also the LLM provider. See .env.example for
available settings and the speech-services specification for
provider contracts.
See DEVELOPMENT.md for instructions on running the project locally for development on macOS.
Bug reports, feature suggestions, documentation improvements, and code contributions are welcome. Read CONTRIBUTING.md before opening an issue or pull request.
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 via the contact form.
Arturo Carretero Calvo — @artcc