Self-Host Colyseus Behind NAT with Localtonet

How Colyseus behind NAT works

Colyseus is an authoritative multiplayer framework for Node.js. In an authoritative architecture, the server owns the important game rules and shared state. Clients submit actions or inputs, and the server decides whether those actions are valid and how they affect the game. Colyseus supplies room-based matchmaking, reconnection support, synchronizable data structures, and SDKs for JavaScript, Unity, Godot, GameMaker, Defold, Haxe, C, Construct, and other supported environments.

A typical Colyseus connection has two related networking phases. The client first performs HTTP-based matchmaking to create or join a room. It then establishes a persistent WebSocket connection for room messages and synchronized state. Publishing only an ordinary web page is therefore not enough. The public route must support both the initial HTTP requests and the WebSocket upgrade used by the room connection.

A server running on a laptop, workstation, home server, or another private device is often behind network address translation. NAT allows the device to initiate outbound connections but normally does not direct unsolicited inbound internet traffic to the process. Carrier-grade NAT, changing public addresses, and networks where you do not control the router can make conventional port forwarding unavailable.

With Localtonet, our client runs on the Colyseus host or another device that can reach it. The client establishes an outbound connection to a selected Localtonet relay server. A Localtonet HTTP tunnel maps a public HTTPS address to the private Colyseus IP address and port. HTTP tunnels support the web traffic and WebSocket connections used by this deployment, so matchmaking and the persistent room connection can use the same public endpoint.

Prerequisites and supported setup assumptions

The current Colyseus quickstart requires Node.js and uses npm. The official project page does not publish a numeric minimum Node.js version in the evidence available for this revision, so this tutorial does not guess one. Install a current Node.js release supported by the Colyseus version generated for your project. If the generated package.json, installation output, or current Colyseus documentation specifies a narrower runtime range, that project-specific requirement takes precedence.

Confirm that Node.js and npm are available:

node --version
npm --version

Both commands should print version information. If either command is missing, fix the Node.js installation or terminal path before proceeding. Package installation failures at this stage are local runtime problems, not NAT or Localtonet problems.

You also need permission to create files and install npm packages, a terminal that can remain open while the server runs, and a second terminal for the verification client. For public access, install the Localtonet client on the same machine as Colyseus or on another device that can directly reach the Colyseus listening address.

This tutorial uses the standard local Colyseus endpoint http://localhost:2567 for the generated server. Keep the startup output visible and verify the actual port used by your project. If your generated project or environment changes the port, use that value consistently in the health check, client script, and Localtonet tunnel target.

Generate and start the Colyseus project

The current official Colyseus quickstart uses three commands. Run them from the parent directory where you want the new my-server project to be created:

npm create colyseus-app@latest ./my-server
cd my-server
npm start

Stop the initial process with Ctrl+C before editing the project. The current generated TypeScript application uses an application configuration where rooms are registered with defineRoom(). The following section replaces ambiguity with a specific room, route, and client test.

If the generator creates a materially different configuration layout because a newer Colyseus release has changed the template, do not paste code into an unrelated file. Use the generated application configuration that is imported by its server entry point, and preserve the generated startup mechanism. The room definition and registration concepts remain the same, but a future template may move the files.

Create a minimal room, register it, and add a health route

The minimal test room accepts a ping message and replies to that same client with pong. This deliberately small contract proves that matchmaking completed, the room WebSocket opened, a client message reached the server, and a server message returned to the client.

Create the room implementation

Create src/rooms/EchoRoom.ts with the following content:

import { Room, Client } from "colyseus";

export class EchoRoom extends Room {
  maxClients = 4;

  messages = {
    ping: (client: Client, payload: unknown) => {
      client.send("pong", payload);
    },
  };

  onJoin(client: Client) {
    console.log(`joined: ${client.sessionId}`);
  }

  onLeave(client: Client) {
    console.log(`left: ${client.sessionId}`);
  }
}

The room limits the test to four clients, logs joins and leaves using the current sessionId property, and handles one message type. The payload is returned only to the sender. This is a connectivity test, not a complete game protocol.

Register the room and health endpoint

Open the generated src/app.config.ts and configure the application as follows. If the generated file already contains imports, routes, or development tools you intend to keep, merge the echo_room registration and /health route rather than deleting required project setup.

import { defineServer, defineRoom } from "colyseus";
import { EchoRoom } from "./rooms/EchoRoom";

export default defineServer({
  rooms: {
    echo_room: defineRoom(EchoRoom),
  },

  express: (app) => {
    app.get("/health", (_request, response) => {
      response.json({ ok: true });
    });
  },
});

The key used in the rooms object is the matchmaking name. The test client must request echo_room exactly. The /health route provides a known HTTP response and avoids treating an absent root page as a server failure.

Create a repeatable client verification script

Ensure that the JavaScript client SDK is installed in the project:

npm install @colyseus/sdk

Create a scripts directory, then create scripts/verify-client.mjs:

import { Client } from "@colyseus/sdk";

const endpoint = process.argv[2] || "http://localhost:2567";
const client = new Client(endpoint);

const timeout = setTimeout(() => {
  console.error("Timed out waiting for pong.");
  process.exit(1);
}, 10000);

try {
  console.log(`Connecting to ${endpoint}`);

  const room = await client.joinOrCreate("echo_room");
  console.log(`Joined echo_room as ${room.sessionId}`);

  room.onMessage("pong", async (payload) => {
    clearTimeout(timeout);
    console.log("Received pong:", payload);
    await room.leave();
    process.exit(0);
  });

  room.send("ping", { text: "hello from verification client" });
} catch (error) {
  clearTimeout(timeout);
  console.error("Verification failed:", error);
  process.exit(1);
}

The endpoint is accepted as a command-line argument. With no argument, the script tests http://localhost:2567. Later, the same script will accept the public Localtonet HTTPS URL. Using the identical room and message check on both paths makes failures easier to compare.

Verify HTTP, matchmaking, and WebSockets locally

Start the configured server again from the project directory:

npm start

Leave that terminal open. The process should remain active without compilation or binding errors. Confirm that the output reports the expected local endpoint. The commands below use port 2567; substitute the port reported by your project if it differs.

Test the health route with a browser or an HTTP command-line client:

curl http://localhost:2567/health

The expected body is:

{"ok":true}

Now run the complete room test from another terminal:

node scripts/verify-client.mjs http://localhost:2567

A successful result prints messages similar to the following. Session identifiers vary on every run:

Connecting to http://localhost:2567
Joined echo_room as <session-id>
Received pong: { text: 'hello from verification client' }

The server terminal should also log the join and leave events. Together, these results establish four facts: the HTTP listener is available, matchmaking recognizes echo_room, the WebSocket room connection opens, and application messages travel in both directions.

Do not continue to tunnel configuration if either local test fails. An HTTP success without a room success points toward registration, SDK compatibility, or room logic. A room timeout with an exception in the server terminal points toward the application. A connection refusal usually means the process is stopped, the host or port is wrong, or the service did not bind successfully.

Expose Colyseus with a Localtonet HTTP tunnel

Keep Colyseus running and create an HTTP tunnel to the endpoint that passed the local tests. The HTTP tunnel is the appropriate tunnel family because Colyseus combines HTTP matchmaking with a WebSocket room connection. Localtonet HTTP tunnels handle the HTTP request and WebSocket upgrade against the same configured local target.

The exact relay choices and available process types can vary by account, client version, region, or deployment. Select values shown in your current dashboard rather than copying a server code or region from an old article.

For current dashboard details, see our Localtonet HTTP tunnel documentation. Custom-domain DNS requirements should always be taken from the current documentation rather than inferred from an assigned subdomain.

Verify the public endpoint with a real Colyseus client

First test the known health route. Replace the example host with the complete HTTPS URL assigned to your tunnel:

curl https://your-assigned-public-host/health

The expected response remains:

{"ok":true}

Next, pass the public HTTPS URL to the same verification script used locally:

node scripts/verify-client.mjs https://your-assigned-public-host

The expected result is a successful join followed by the returned pong payload:

Connecting to https://your-assigned-public-host
Joined echo_room as <session-id>
Received pong: { text: 'hello from verification client' }

This test is stronger than opening the public URL in a browser. The health request confirms public HTTP forwarding. The script then exercises Colyseus matchmaking, the WebSocket upgrade, the room connection, and bidirectional application messaging.

Run the final test from a device outside the server's LAN, such as a computer or phone on another internet connection. If the script still succeeds, the client is using the public tunnel rather than a private route available only inside your network.

A production JavaScript or TypeScript client uses the same endpoint pattern:

import { Client } from "@colyseus/sdk";

const client = new Client("https://your-assigned-public-host");
const room = await client.joinOrCreate("echo_room");

room.onMessage("pong", (payload) => {
  console.log("Server replied:", payload);
});

room.send("ping", { text: "hello" });

Replace echo_room with the room name registered by your real application. Do not append a guessed WebSocket path or manually convert the endpoint unless the current SDK documentation for your target platform requires a different endpoint format. The JavaScript SDK accepts the HTTPS server endpoint and performs the required matchmaking and room connection flow.

SDK syntax differs across platforms. For example, current official examples show HTTPS endpoints for JavaScript, Unity, GameMaker, Defold, Haxe, and C clients, while the Godot example uses a secure WebSocket endpoint. Follow the endpoint format documented for the SDK you ship rather than mechanically copying JavaScript syntax into another engine.

Secure and operate the deployment

A reachable prototype is not automatically a production-ready multiplayer service. Localtonet supplies connectivity to the configured target. It does not replace authentication, authorization, input validation, process supervision, monitoring, persistence, backups, or capacity planning.

Keep game decisions authoritative

Treat every client message as untrusted input. Validate its type, shape, range, rate, ownership, and relationship to the current room state. A client should not be able to assign itself a privileged role, move another player's entity, submit impossible coordinates, or perform an action after it is no longer a room member.

Authenticate players when identity matters, and authorize each room join on the server. Do not assume that possession of the public URL grants permission. Public reachability and application authorization solve different problems.

Restrict development and administrative interfaces

Review playground, monitor, profiler, debug, and administration routes before exposing the server. Ordinary players usually do not need access to these interfaces. Colyseus 0.18 added guard options for monitor and playground use and introduced basic authentication middleware for HTTP routes, but those controls still require deliberate application configuration.

Colyseus 0.18 also makes playground data endpoints return a 404 on production mounts unless a guard is configured. This is specifically a 0.18 behavior and should not be assumed for an older project. Check the release and migration documentation for the version actually deployed.

Plan for process and host continuity

Colyseus and the Localtonet client are separate running processes. A closed terminal, server exception, operating system restart, sleeping laptop, lost network connection, or stopped tunnel can disconnect players. Persistent deployments should use an always-on host and a process supervision method suitable for that operating system.

Decide how deployments affect active rooms. Restarting the process interrupts WebSocket sessions and can discard in-memory state. If the game requires durable accounts, inventories, leaderboards, or recoverable room data, implement and test an appropriate persistence design. Colyseus 0.18 includes an official database package based on Drizzle ORM for SQLite and PostgreSQL use cases, but that package is not required for this basic tunnel workflow.

Monitor both failure domains

Monitor application exceptions, room creation failures, rejected joins, memory, CPU, event-loop behavior, and connection counts. Separately monitor whether the Localtonet client and tunnel remain connected. A connected tunnel cannot make an exited Colyseus process healthy, and a healthy local server is not publicly reachable through a stopped tunnel.

Apply Colyseus 0.18 migration notes only to 0.18

The following details are version-specific and are not prerequisites for the minimal room tutorial:

• A Schema supports at most 63 fields in Colyseus 0.18. Inherited fields count toward the limit.
• client.id was removed. Use client.sessionId, as the room example in this guide does.
• setMetadata() and setMatchmaking({ metadata }) replace metadata instead of merging it.
• Existing email and password users of @colyseus/auth have migration considerations related to the new password hasher.
• Version 0.18 adds request and response messaging, prediction and lag-compensation features, room plugins, configurable SDK reconnection, and other capabilities that are not needed for the echo test.

If an existing project runs an earlier release, do not apply these changes independently. Follow the migration path for the source and target versions, verify client SDK compatibility, and test serialized state, room lifecycle, matchmaking, and reconnection before deployment.

Troubleshooting the complete connection path

Diagnose from the inside out

Start on the Colyseus host. Request /health locally and run the local verification script. If either fails, Localtonet is not the cause. Fix the server process, route, room registration, dependency versions, or application code first.

If Localtonet runs on another device, repeat the health and room tests from that device using the Colyseus host's LAN address. A service bound only to loopback on the Colyseus machine cannot be reached by another tunnel device. Do not create the tunnel until this intermediate path works.

Next, check that the intended Localtonet device is connected, the selected relay server is available, the tunnel is started, and the target exactly matches the tested local IP address and port. Avoid changing several values at once because doing so makes the successful correction difficult to identify.

Finally, run the public health and room tests from an outside network. Compare the client timestamp with the Colyseus logs. If no request reaches Colyseus, focus on the public endpoint, tunnel state, and target mapping. If Colyseus receives and rejects the request, focus on room registration, authentication, authorization, SDK compatibility, and room exceptions.

Frequently asked questions