lila (Lichess)

Lila (li[chess in sca]la) is the open-source engine behind Lichess.org, the world’s most popular free chess server. Built as a non-profit by hundreds of contributors, it delivers real-time multiplayer chess across all time controls — bullet, blitz, rapid, and classical — alongside Stockfish-powered AI analysis distributed across a global volunteer network called Fishnet.

The platform is architected in Scala 3 using a modified Play 2.8 framework, with 84 independent domain modules wired together via Macwire dependency injection. Each feature area — games, tournaments, puzzles, studies, moderation — lives in its own module with a dedicated Env class, keeping boundaries strict and enabling teams to work in isolation. The TypeScript frontend uses Snabbdom for virtual DOM rendering and is organized as a pnpm monorepo of UI packages.

Lichess stores over 12 billion games in MongoDB, indexed with Elasticsearch for game search. WebSocket connections are handled by a separate server (lila-ws) that communicates through Redis, decoupling real-time communication from the main application. All rated games are published in a free public PGN database at database.lichess.org, making the platform a major resource for chess research and AI training.

With full support for over 140 languages via Crowdin localization, granular OAuth 2.0 scopes for third-party integrations, a documented REST and streaming API, and features like blind mode accessibility and DGT board integration, Lichess is designed to be genuinely open — both as source code and as a service.

What You Get

• Real-time multiplayer chess - Play live games across bullet, blitz, rapid, and classical time controls with low-latency WebSocket connections, instant move validation via the scalachess library, and automatic clock management.
• Distributed Stockfish analysis via Fishnet - Submit any game for deep AI engine analysis powered by Stockfish running on a global network of donated computing resources, with multi-variation evaluation and move annotations.
• Public PGN database of 12B+ games - Access and bulk-download all rated Lichess games in standard PGN format from database.lichess.org for research, machine learning training data, or personal study.
• Interactive puzzle trainer with adaptive difficulty - Solve thousands of community-sourced tactical puzzles rated with Glicko scoring, with difficulty adapting to your skill level and themed puzzle sets for endgames, tactics, and openings.
• Collaborative study boards - Create shared analysis boards where multiple users annotate games in real-time, embed engine lines, and build structured lessons with branching move trees.
• Swiss and arena tournament system - Run and participate in Swiss-style or arena (time-based) tournaments with automatic pairings, live leaderboards, team competitions, and simul events.
• Granular OAuth 2.0 API - Integrate with Lichess via a documented REST and NDJSON streaming API with fine-grained token scopes for games, challenges, puzzles, messages, and team management.
• DGT board integration - Connect a physical DGT electronic chess board to play and analyze on lichess.org with live position synchronization.
• Multi-language UI (140+ languages) - Fully localized interface contributed by the community via Crowdin, covering game controls, notifications, and educational content.
• Blind mode accessibility - Screen-reader-optimized interface with keyboard navigation and audio cues enabling visually impaired players to fully participate.

Common Use Cases

• Chess coaching and student management - A coach sets up a Lichess class (Clas module) to assign puzzle sets, track student progress across games, and share annotated study boards with multiple students simultaneously without any subscription fees.
• Chess AI research and training data - A machine learning researcher downloads millions of rated games from database.lichess.org in PGN format to build training datasets for move prediction models or opening tree analysis.
• Community tournament hosting - A chess club uses Lichess’s built-in Swiss and arena tournament tools to organize weekly online events with automatic bracket management, no setup cost, and real-time standings for participants.
• Bot development and testing - A developer registers a bot account via the Lichess API and uses the BOT challenge and game streaming endpoints to deploy and test an engine written in any language against live human or bot opponents.
• Game analysis content creation - A chess YouTuber imports games via the API to retrieve Stockfish evaluations, move annotations, and board positions for scripting annotated video content about high-profile tournament games.
• Self-hosted private server - A development team or university chess program clones the lila repo to run a private Lichess instance on internal infrastructure for controlled, private play and analysis environments.

Under The Hood

Architecture Lila is built as a modular monolith: 84 domain modules each encapsulate their own business logic, persistence layer, and service boundaries within a single deployable Scala application. Each module exposes an Env class that wires its own dependencies via Macwire, and the root application Env composes these in explicit dependency order. This approach enforces single-responsibility at the module level while avoiding the operational complexity of microservices. Stateless HTTP controllers receive fully wired environments, separating request handling from business logic. Real-time game state is managed through AsyncActor instances per game, keeping mutable game data off the shared heap and serializing concurrent moves within each game room. The WebSocket layer runs as a completely separate server process communicating through Redis pub/sub, isolating connection-handling load from application logic.

Tech Stack The backend runs on Scala 3 with a customized Play 2.8 framework, using Akka Streams for asynchronous data pipelines and Scala Futures throughout. Chess logic is delegated entirely to the scalachess submodule — an independent library — keeping the application layer free of chess rules. MongoDB stores games, users, and all structured data, with Elasticsearch providing full-text and filter-based game search. The TypeScript frontend is organized as a pnpm monorepo of independent UI packages, each compiled and bundled separately. Snabbdom provides the virtual DOM layer, with Sass for styling. Fishnet — the distributed analysis network — connects via Redis and communicates over a defined JSON protocol, allowing any volunteer to run a worker node and contribute CPU time.

Code Quality The codebase maintains strong type safety throughout — opaque types prevent accidental mixing of identifiers (UserId, GameId, PuzzleId are distinct types), and functional error handling using Option and Either avoids null propagation. There are 85 Scala test files covering binary serialization, game logic, and domain utilities, plus 19 TypeScript test files for frontend components using node:test. Linting is enforced with Oxlint for TypeScript and Scalafmt for Scala. The modular architecture makes individual units independently testable, and CI runs against the full suite. Error handling in the round module uses explicit state transitions rather than exceptions, making game flow auditable at compile time.

What Makes It Unique Lila’s most distinctive technical choice is treating distributed AI analysis as a first-class platform feature rather than an optional add-on. The Fishnet protocol allows any user to run a compute worker, democratizing Stockfish analysis at scale without centralized server costs. The platform’s 84-module architecture reflects 14 years of organic growth with intentional refactoring — few chess servers of this scale publish their entire production codebase. The combination of a comprehensive public API with fine-grained OAuth scopes, a completely free PGN database of 12 billion games, and zero ads or paywalls creates an ecosystem unusually open to third-party innovation. The DGT board integration and blind mode accessibility show that the platform targets serious chess players across all ability levels, not just casual audiences.

Self-Hosting

Lila is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). The AGPL is a strong copyleft license — if you run lila as a network service (i.e., let others use it over the internet), you must make the complete corresponding source code available to those users, even if you have not distributed any software binaries. This means that running a private Lichess instance for paying customers requires publishing all modifications to the codebase. Internal use within a single organization (not offered as a service to external users) generally does not trigger the source-sharing requirement, but legal review for your specific context is advisable.

Running lila yourself is a substantial operational undertaking. The full Lichess production stack involves the lila application server, a separate lila-ws WebSocket server, MongoDB for primary storage, Elasticsearch for search, Redis for inter-process communication, and nginx as a reverse proxy. The development onboarding guide covers starting a local environment, but production deployments require expertise in Scala JVM tuning, MongoDB replication, and Redis cluster configuration. There is no official Helm chart, Docker Compose for production, or managed hosting option — you own the full infrastructure, monitoring, backup strategy, and upgrade process. The development wiki and Discord community provide guidance, but there is no commercial support contract.

Compared to using Lichess.org directly, self-hosting sacrifices access to the volunteer Fishnet analysis network (you must run your own Stockfish workers), the public game database, community features such as teams and forums that depend on a large user base, and the continuous improvements deployed daily by the core team. Lichess.org does not offer a paid SaaS tier or white-label enterprise plan — the service is entirely free and non-commercial. Self-hosting is therefore primarily valuable for private environments, research setups, or organizations with regulatory requirements that prevent using external services.