Host a Node.js WebSocket game server: what to prepare

The short answer

Open a terminal in your project folder and run ncg pack . --node --install, then ncg check .ncg/build and ncg submit. The first command builds a folder with your code, the packages built for Linux and a small start script, and packs it into the archive we upload. It installs nothing unless you give it --install, and it never changes your own node_modules.

What the host provides

• Node.js 24, the long-term-support line. One exact version is installed on every server and checked against the official signed release before it is used. When we move to a newer line, this guide changes the same day.
• No npm and no package install. Everything your server needs at run time must be in the archive. That is why the packages are built for Linux x64 (glibc) on your computer, whatever your computer runs.
• A start script named server. ncg pack writes it. It starts your file with node and a memory ceiling that fits the profile you chose. Your manifest's command is that script, because a command must be a file inside your archive.
• Ubuntu 24.04. Anything you build for Linux yourself must not need a newer glibc than 2.39.

If you would rather use a different Node version, you can put your own Linux x64 node in the archive and start it from your own script. The check then judges that program instead.

Steps

1. Make the server listen on all addresses. Bind 0.0.0.0, read the port from the environment with a default, and never bind 127.0.0.1 only.
2. Add a health page and a join check. A small route such as /health that answers ok, and one that proves a player could join. The Node prompt makes your AI add both.
3. Handle SIGTERM. Save and exit within the grace time when the host asks you to stop.
4. Run ncg init .. It reads the project and writes ncg.json, marking what it could not find.
5. Run ncg pack . --node --install. The exact command it runs is printed first. It needs npm 10.3 or newer and a package-lock.json. No package install script runs. If the lockfile points at git, a web address, a folder or a link instead of the npm registry, ncg stops before npm starts and says which package; replace it with a registry version (or use --bundle).
6. Run ncg check .ncg/build. This is what the service would say about your upload, before anything leaves your computer.

If your WebSocket is not at the root path

By default the gateway connects to ws://<your server>:<port>/. If your server only accepts upgrades at /ws, write that in ncg.json:

"wsPath": "/ws"

The path is fixed by you when you release. Nothing a player sends (path, query or headers) becomes part of the address the gateway connects to, so a player cannot reach another path on your server or on anyone else's. A path uses letters, digits and . _ ~ - /, up to 128 characters, with an optional fixed query of up to eight key=value pairs.

socket.io

socket.io works only in WebSocket-only mode. In the browser, connect to the gateway address with transports: ['websocket'] and addTrailingSlash: false (socket.io-client 4.6 or newer), and put the fixed query in the manifest:

"wsPath": "/socket.io/?EIO=4&transport=websocket"

Long polling does not pass through the gateway, and neither does the client query option. Send tokens in the auth option instead. The socket.io prompt makes your AI change exactly that.

What does not work

• Colyseus. It starts with plain web requests for matchmaking before the WebSocket. We say so before you upload, and the check says so before you start.
• Packages for the wrong system. A package with a native add-on built for Windows, macOS, ARM or Alpine is refused with the package named. ncg pack --install asks for Linux x64 builds only.
• uWebSockets.js for a different Node. Its add-ons are built per Node version. Use the build for Node 24, or the ws library.
• Install scripts. They never run on our servers. If your game needs one, move that work into the build.
• TypeScript as the start file. Compile it first and point ncg pack at the output with --entry.
• A source folder. Uploading a project with package.json and no start script 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.