Host a Python WebSocket game server: what to prepare

The short answer

In your project folder run ncg pack . --python --install, then ncg check .ncg/build and ncg submit. The first command downloads wheels for Linux x86-64 and Python 3.12 only, writes them into a vendor folder, adds a start script named server, and packs everything. It installs nothing unless you pass --install, and it never touches your own virtual environment.

What the host provides

• Python 3.12 and the standard library. Nothing else. There is no pip on the servers and no network install at start.
• Your libraries, as wheels. The command asks for cp312 and manylinux x86-64 wheels with no source builds (--only-binary=:all:), so no library is compiled and no install script runs. ncg also refuses, before pip starts, any requirements.txt line that is a folder, a web address, a repository or a pip option such as --index-url or --no-binary, because pip would build those with their own build code on your computer. Use plain lines such as websockets==14.1; pip is given a cleaned copy.
• A start script named server. It sets PYTHONPATH to your vendor folder, then runs your file with python3. Your manifest's command is that script.
• Ubuntu 24.04, so shipped Linux libraries must not need a newer glibc than 2.39.

Steps

1. List every library in requirements.txt, pinned if you can.
2. Listen on 0.0.0.0 and read the port from the environment with a default.
3. Add a health route and a join check that answers with a known reply. The Python prompt makes your AI add them, and the clean stop on SIGTERM.
4. Run ncg init ., then ncg pack . --python --install, then ncg check .ncg/build.

If your WebSocket is not at the root path

A FastAPI or Starlette route such as /ws is not the root. Declare it in ncg.json as "wsPath": "/ws". The path is fixed by you at release. A player's path and query never reach your server. See the Node guide for the allowed characters.

What does not work

• A library with no Linux wheel. If a package only ships source, --only-binary stops with the package named. Pick a version that has a wheel, or another library.
• Extensions built for Windows, macOS, ARM or Alpine. Only cp312 manylinux x86-64 is accepted.
• Designs that need a plain web request before the WebSocket. The gateway passes WebSocket connections only, so long polling and HTTP matchmaking do not work.
• A source folder. A project with requirements.txt and no vendored packages is held with the command to run.

Mistakes that waste the most time

Frequently asked questions

Written by Charging Bull Software. Facts on this page are checked against the product source and dated sources listed above; where something is not proven, the page says so.