External engine (ALPHA)
Using engines running outside of the browser on https://lichess.org/analysis.
Work in progress
- Implement MVP
- Complete lichess-org/lila#10867
- Build easily installable local providers
Reference implementation in Rust. Cross platform command line application wrapping an UCI engine. Secure, but not robust against denial of service.
Minimal GUIs with bundled Stockfish for Linux, Windows and Mac
Protocol (still subject to change)
Lichess provides a reference implementation for an external engine provider. Third parties can also implement their own engine providers.
An external engine provider is a WebSocket server. To inform the client about the connection details, it triggers a navigation to an authorization endpoint, where the user can confirm that their client should use the given engine provider. The client will then open a WebSocket connection for each session with a chess engine.
The client sends UCI commands as text messages over the WebSocket connection. Each command is sent in its own WebSocket message, containing no line feeds or carriage returns.
The provider responds as if the client were exclusively communicating with a UCI engine, by sending UCI commands as individual WebSocket messages.
registration are not supported.
Important considerations for providers
The most straight-forward implementation would be to forward all WebSocket messages to a UCI engine as a thin proxy. However, some important considerations arise that require dealing with UCI specifics and tracking the engine state.
⚠️With many engines, a malicious user who can execute arbitrary commands will be able to damage the host system, cause data loss, exfiltrate data, or even achieve arbitrary code execution.
Recommendation: Use the
safe-uciadapter as a wrapper around UCI engines. If possible, bind the server only on the loopback interface to limit the attack surface. Generate a strong
secretfor the engine registration and do not forget to check it.
Analysis is resource intensive. Be sure to put limits on CPU and memory usage and inforce them, in order for your system to stay responsive.
Network connections can be interrupted.
Recommendation: Send pings over all WebSocket connections at intervals. If a client times out or disconnects, stop ongoing searches in order to prevent deep or infinite analysis from consuming resources indefinitely.
Clients may open multiple connections.
Recommendation: Manage shared access to a single engine process. At each point, one of the WebSocket connections has an exclusive session with the engine. Track the engine state and options associated with each session.
When receiving a message (except
stop) on a connection, an exclusive session is requested for that connection. In order to switch sessions, end any ongoing search in the previous session (by injecting
stop) and wait until any outstanding engine output has been delivered. Then issue
ucinewgame, to ensure the following session is clean, and reapply any options associated with the session.
Register external engine
To inform the client about connection details, trigger a navigation to
with the following query parameters:
||URL of the provider server. External engine registrations are stored in local storage, so this may refer to
||required||A secret token that the client should include in every connection request.|
||Short engine or provider name to show on the client.|
||Maximum number of threads supported for
||Maximum number of memory supported for
||Comma-separated list of variants supported by
The client will open WebSocket connections to the url as provided in the registration above. It will set the following additional query parameters:
||The secret token as provided in the registration above. The provider must check and reject connection attempts if the token does not match.|
||Each new tab or session will have a different identifier. Reconnections will reuse the identifier.|
To properly work on the Lichess analysis board, engines must support:
depth(reaching 6 must be fast)
nodes(with order of magnitude comparable to Stockfish)