This guide shows you how to host any Colyseus multiplayer game on Edgegap's dedicated game servers, then add matchmaking so players are grouped and connected to a server near them automatically.
Once your game server is containerized, Edgegap deploys it worldwide to 615+ Edge Cloud locations (on-demand) from a simple API call and billed exclusively on usage: no entire server to rent, provision or keep running between matches. For persistent servers of reserved capacity, Edgegap offers Private Fleets. Edgegap's Matchmaking builds on top of that and is optional.
Your rooms, schemas and client SDKs stay the same. The simplest setup, and the one this guide tests, gives each match its own Colyseus server: Edgegap starts it near the match's players and it stops itself when the match is over, so you don't need PM2, Redis presence or room-count capacity planning. One server can also host several rooms, for example a lobby and its matches: it then stops 30 seconds after the last player leaves, even if a room stays open. For always-on servers, use Private Fleets.
This guide covers:
Preparing your Colyseus project, your Edgegap account and a containerization tool
Connecting your coding agent to Edgegap (optional)
Getting your Colyseus server ready for Edgegap
Containerizing the server and creating an app version
Deploying a test server and connecting a client
Adding matchmaking (optional)
Pointing your other clients at Edgegap
Testing the full loop with two players
You can do it two ways, and mix them:
With a coding agent. Connect Claude Code, Cursor or another agent to the Edgegap MCP server and its agent skills. The
edgegap-colyseusskill makes the server changes, writes the Dockerfile, deploys a test server and wires the matchmaker into your clients. You handle the Edgegap dashboard, the secrets, and playtest.By hand. Every step below also works without an agent.
The guide uses Edgegap's fork of the official Colyseus Realtime Tanks demo: one Colyseus 0.17 server and nine clients, from Three.js to Unity and Godot. Edgegap hosting is already built into the fork, so you can run it as is, or use it as a reference for your own game.

Colyseus’s Realtime Tanks demo, running on Edgegap
1. Before you start
A free Edgegap account. Verify your email. No credit card is needed to test.
A Colyseus server. This guide uses Colyseus 0.17 (
defineServer/defineRoom). Colyseus 0.15 and 0.16 should work the same way, with a different entry point, but weren't tested.Node.js (version 22 recommended) and a containerization tool, running. We recommend Docker Desktop.
Unity clients: the fork's Unity matchmaker client needs Unity 2023.1 or Unity 6 (it uses
Awaitable).For the agent path: an Edgegap API token, from Dashboard → User Settings → Tokens. It is organization-wide, so treat it like a password: never put it in a client, your server image or a chat.
Shortcut: run the sample first. Clone the Realtime Tanks fork, then follow steps 4 to 8 with its
server/folder. Every change from step 3 is already in it. On Windows, rungit config --global core.longpaths truebefore cloning: some client file paths are too long for Windows defaults.
2. Connect your coding agent to Edgegap
Skip this step if you're doing everything by hand.
The Edgegap MCP server lets your agent create apps and versions, deploy servers, read logs and generate matchmaker configurations on your account. The edgegap-colyseus skill gives it the files tested with Realtime Tanks: a lifecycle module, a Dockerfile, a deploy script, a matchmaker configuration and matchmaker clients for the browser, Unity and Godot.
Claude Code: install the Edgegap plugin. It adds both the MCP server and the skills, and asks for your API token during install (stored in your system's credential store):
/plugin marketplace add edgegap/llm-agent-skills, then /plugin install edgegap@edgegap. Restart the session.
Only want the MCP server, without the plugin? Run this in your own terminal instead: claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user. Don't do both, or you'll have two edgegap servers.
Cursor, VS Code and other clients that send headers: add https://mcp.edgegap.dev/mcp with the header Authorization: token YOUR_EDGEGAP_API_TOKEN, and install the skills with npx skills add edgegap/llm-agent-skills --skill "*".
Claude Desktop: custom connectors can't send the header, so use the local server instead (Node 22): { "mcpServers": { "edgegap": { "command": "npx", "args": ["-y", "@edgegap/mcp"] } } }. It asks for the token on first use.
Check it works:
"List my Edgegap apps."
3. Get your Colyseus server ready for Edgegap
Edgegap starts a server when a match needs one. Only your game knows when the match is over, so the server stops its own deployment. Otherwise an empty server keeps running, and billing, until its max duration.
Three changes, in the fork's server/src/edgegap.ts and its BattleRoom.ts:
A lifecycle module that runs only on Edgegap (when
ARBITRIUM_REQUEST_IDis set, which Edgegap does on every deployment). It stops the deployment when nobody joined within 120 seconds, when everyone left and nobody came back within 30 seconds, or when the match ends.Count players in your rooms: call
playerJoined()inonJoinandplayerLeft()when a seat is really gone. WithallowReconnection, that's after the reconnection window fails, not on the drop. Reconnection wasn't tested on Edgegap; with one server per match, a client that reconnects must save the server address along with its reconnection token.End the match if your game has one: lock the room, show the result for a few seconds,
disconnect(), then stop. Realtime Tanks does this afterMATCH_ROUNDSwon rounds (default 0, an endless arena).
Also turn the playground and monitor off on Edgegap: anyone with the server's address could open them. The fork mounts them only when it isn't running on Edgegap, so npm run dev works exactly as before.
With your agent:
"Load the edgegap skill, then edgegap-colyseus. Add the lifecycle module to my Colyseus server, count players in every room, stop the server when a match ends, and keep the playground and monitor off on Edgegap. Then test it locally in Docker."
4. Containerize the server and create an app version
Edgegap runs linux/amd64 containers. The fork's server/Dockerfile starts from node:22-slim and runs Node as the main process, so your server receives Edgegap's stop signal and Colyseus closes its rooms cleanly.
Build for Edgegap's platform, even on Apple Silicon, with a new tag for every build:
cd server
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/realtime-tanks:v1 .
Test the image locally before you push it. ARBITRIUM_REQUEST_ID makes it behave as on Edgegap: docker run --rm -p 2567:2567 -e ARBITRIUM_REQUEST_ID=local -e EMPTY_TIMEOUT_S=10 registry.edgegap.com/<project>/realtime-tanks:v1. A client on ws://localhost:2567 joins, and 10 seconds after it leaves, the container exits.
Then docker login registry.edgegap.com with the credentials from the Container Registry page, and docker push registry.edgegap.com/<project>/realtime-tanks:v1.
Create the application and version in the dashboard:
Your image and tag, with the registry credentials.
0.25 vCPU and 512 MB to start.
Port 2567, protocol WS, name
gameport, with TLS Upgrade turned on.A max duration of 60 minutes while testing.
TLS Upgrade lets every client, browser builds included, connect with wss://. Edgegap handles the certificate and forwards plain HTTP and WebSocket traffic to port 2567. Colyseus's matchmake request and the room connection both use that one port.
With your agent:
"Build my Colyseus server for linux/amd64, push it with a new tag, and create the Edgegap app and version: port 2567, protocol WS, TLS Upgrade on, named gameport, 0.25 vCPU and 512 MB, 60 minutes max."
5. Deploy a test server and connect a client
Start a server near you from the fork's deploy script. Your API token stays on your machine:
macOS and Linux: EDGEGAP_API_TOKEN=<token> npm run edgegap:deploy -- realtime-tanks v1
Windows (PowerShell): $env:EDGEGAP_API_TOKEN="<token>"; npm run edgegap:deploy -- realtime-tanks v1
It prints wss://<request_id>.pr.edgegap.net:<port>. You can also deploy from the dashboard (Deploy, pick a location close to you), or ask your agent: "Deploy my latest Edgegap version near me, wait until it's ready, and give me the wss:// address."
Pass the address to a client. In the Three.js client, add ?server=wss://... to the page address; in Godot or a Unity desktop build, start it with --server=wss://.... Always use the host name, not the IP address, or the certificate check fails.
If the first join returns 502, retry: a server that has just started can answer 502 for a few seconds. The fork's clients retry for up to 20 seconds.
When the client leaves, the server log shows self-stop: empty for 30s and the deployment disappears from the dashboard. The free tier runs one deployment at a time.
In a real game without Edgegap's matchmaker, your backend or lobby calls the same Deploy API (POST /v2/deployments) when a group is ready, and sends the address to its players. Next, let the matchmaker do that for you.
6. Add matchmaking
Edgegap's matchmaker groups players, deploys your server near them and gives every client its address. The fork's Three.js, Unity and Godot clients send a ticket, show "Searching for players...", and connect once the server is assigned. Tested on Edgegap: Three.js in the browser, Godot desktop and a Unity Windows build. Unity WebGL and the Godot web export weren't run.
Start from the fork's
matchmaker-config.json. Itscasualprofile matches 2 to 8 players, and after 15 seconds it starts a match with whoever is waiting (2 at least). Set your application name and version in it.Browser builds: list every web address that serves your game in
allowed_cors_origins, or the browser blocks the matchmaker's replies. The file allows local development servers only. Leave out any latency rule for browser players: browsers can't send the latency pings desktop games use.In the dashboard, open Matchmaker, select Create Matchmaker, upload the file and select Create and Start.
When it shows Online, copy its API URL and Auth Token. The Auth Token is meant to ship in your game: it can only create and read matchmaking tickets. It is not your Edgegap API token.
Give them to the clients: Three.js
?mm=<API URL>&mmToken=<Auth Token>(orVITE_MM_URL/VITE_MM_TOKEN), Unity--mm=<API URL> --mm-token=<Auth Token>or the fields onGameManager, Godot-- --mm=<API URL> --mm-token=<Auth Token>. Aserversetting always wins over the matchmaker.
With your agent:
"Using the edgegap-colyseus skill, add Edgegap matchmaking to my clients: a casual profile of 2 to 8 players, my web origins in allowed_cors_origins, and a join that retries after the server is assigned."
By hand: see the Matchmaking documentation.
7. Point your other clients at Edgegap
Every Colyseus client SDK connects to the same wss:// address. The fork wires direct mode into all nine of its clients. Only the Three.js, Godot desktop and Unity Windows clients were run on Edgegap; the settings below for the other clients were written but not tested:
Three.js, PlayCanvas, Construct 3:
?server=wss://...in the page address.Godot:
--server=wss://...; web export:?server=wss://....Unity:
--server=wss://..., theserverUrlfield, or?server=wss://...in WebGL.Defold: HTML5
?server=wss://...; native--config=tanks.server_url=wss://....GameMaker, Haxe, MonoGame:
--server=wss://...(HTML5 and JS builds:?server=wss://...; MonoGame also readsTANKS_SERVER_URL).
The matchmaker client is small and has no dependencies, so it ports easily to other engines. Start from Matchmaker.ts, EdgegapMatchmaker.cs or edgegap_matchmaker.gd.
8. Test the full loop with two players
Make sure no test deployment is still running. On the free tier, a leftover one blocks the matchmaker's deployment.
Open two clients with the matchmaker settings. They can be different engines, for example the Three.js client in a browser and a Godot desktop build.
Select Play in both: searching, then both land in the same arena. The server log shows both ticket IDs.
Quit both. Thirty seconds later, the server stops its own deployment and it disappears from the dashboard.
Before launch: set inspect to false in the matchmaker configuration, list your real web origins, raise the max duration to fit your matches, and let only matched players in (each matched deployment receives its ticket IDs in MM_TICKET_IDS; check them in onAuth).
On the free tier, the matchmaker stops 3 hours after each start (restart it from the dashboard), deployments stop after 60 minutes, and one deployment runs at a time.
Going live? Ask your agent to run the edgegap-launch skill's checklist.
Stuck? Ask your agent to load edgegap-troubleshoot, or ask our team and other studios on the Edgegap Discord.
Frequently Asked Questions
Common questions about hosting Colyseus games on Edgegap's dedicated servers.
How do I host a Colyseus server?
Package your Colyseus server as a container with port 2567 exposed, then run it on a host. On Edgegap, each match gets its own server near its players, reached over wss:// with TLS Upgrade, and the server stops itself when the match ends.
Can one Colyseus server run several rooms on Edgegap?
Yes. A deployment runs one Colyseus process, which can host any number of rooms; it stops itself 30 seconds after the last player leaves. Most games use one match per deployment instead, which removes the need for PM2, Redis presence or a load balancer.
Does Colyseus work with Unity and Godot on Edgegap?
Yes. Colyseus's Unity and Godot SDKs connect to the server's wss:// address like any other client. The Realtime Tanks sample includes Edgegap matchmaking for its Three.js, Unity and Godot clients, tested end to end on Edgegap with Three.js, Godot desktop and Unity Windows builds.
How do browser clients connect to a Colyseus server securely?
A page served over https:// can only open secure WebSockets (wss://). Turn on TLS Upgrade on the server's WS port: Edgegap handles the certificate and forwards plain traffic to Colyseus, so the server needs no certificate.
Do I need Colyseus's matchmaker with Edgegap?
Colyseus still handles joining the room on its server. Edgegap's matchmaker decides which players play together and starts their server. You can also skip it and have your backend start servers with Edgegap's Deploy API.

Clients
Learn more from clients who integrated Edgegap
31 case studies are available from studios that moved to Edgegap from another platform.

A Flawless Global Launch for Rivals of Aether 2
Aether Studios
Learn how Aether Studios quickly added Edgegap and delivered flawless launch & post-launch to their community.
Case Study

Overcome Latency Introduced by VR’s use of WiFi in Competitive Multiplayer
Halfbrick Studios
Discover how Halfbrick successfully launched & maintains a multiplayer-focused Early Access on META Quest's VR platform.
Case Study

MENA’s Social App Adds Online Games
WOLF
Learn how the highly popular MENA-region social app added matchmaking & multiplayer games orchestration easily to WOLF Qanawat.
Case Study

Hybrid Orchestration Keeps Kickoff Tactics Ready for Any Traffic
Birch Games
How hybrid orchestration helped Birch Games handle traffic, pairing egress-free Fleets with the regionless cloud.
Case Study

7 Days Blood Moons
The Fun Pimps & iLLOGIKA
Learn how Illogika dramatically reduced server costs & ensured the online experience the 7 Days to Die franchise expects.
Case Study

Authentic Online Warfare Requires the Ultimate Orchestration
Highwire Games
Learn how Highwire's need for performance required orchestration only Edgegap can deliver.
Case Study

22,000 Reviews, 4.8 Stars, and Infrastructure That Scaled Automatically
Sinn Studios
How a simple, Slack-supported integration got Sinn Studio's hit VR title online fast and keeps it there.
Case Study

Dynamic Server Orchestration
Under NDA - AAA Studio
Discover how one the world's biggest AAA studio improved its peer-to-peer multiplayer experience through edge computing.
Case Study

Near Zero Latency for AAA Fighting Game
AAA Studio - Under NDA
How an unannounced project delivered the lowest lag possible and improved fairness in its 1v1 game.
Case Study

Play Gods with Multiplayer Physics
Squido Studio
Learn how Squido uses Edgegap's highligh optimized game servers to deliver mind-bending & chaotic VR gameplay.
Case Study

A Fully Managed Solutions that Saves Time for Indies Multiplayer VR Horror
Dirty Pearl Studios
Discover how Dirty Pearl Studios saved development time thanks to Edgegap’s easy integration and automated orchestration alongside its Nakama integration.
Case Study

Instant Global Server Deployment for Collaborative XR Medical Education
AlensiaXR
How AlensiaXR uses Edgegap to deliver low-latency, always-available shared anatomy sessions to medical students worldwide.
Case Study

The Lightkeepers: A VR Social Co-op Game with Dedicated Servers
Spectral Games
How Spectral Games used Edgegap Matchmaking and Server Browser to launch dedicated servers for its VR social lobby, with no prior server experience.
Case Study

Fast & reliable deployments worldwide for PvPvE challenger Gravebound
Crater Studios
How Edgegap’s orchestration and matchmaking helped Crater Studios dramatically helped a small them focus on gameplay instead of infrastructure.
Case Study

Rapid Scaling of Web Metaverse
Hiber
Learn how Hiber eliminated the guesswork out of its server capacity planning with Edgegap.
Case Study

High Hardware Requirements & Custom Game Server Pools
Alderon Games
Learn how Alderon Games instantly leverages a custom pool of game servers across multiple providers worldwide for its popular MMO.
Case Study

Easy Integration for Indie Devs
WhaleFood Games
Read how WhaleFood Games "kicked out" its netcode issues with Edgegap.
Case Study

Cutting-edge tech that powers South-East Asia’s first-ever eSports title.
Anantarupa Studios
Learn how Edgegap transformed South-East Asia’s gaming landscape streamlining complex infrastructure and cutting-edge tech with one seamless solution.
Case Study

One Strike. Global Reach.
Triple Hill Interactive
How Triple Hill Interactive leverages Edgegap's orchestration to deliver low latency and improve fairness in a genre where every millisecond counts.
Case Study

Fast-paced Team Battle Royale... with Gun-totting Animal Plushes!
SANDYFLOOR
Discover how a Korea-based Indie Studio launched it multiplayer worldwide.
Case Study

Mobile Horse Racing Goes Global with Instant, Cost-Efficient Servers
Mirai Labs
How Mirai Labs powers Pegaxy Blaze's worldwide multiplayer races with just-in-time server deployment and fractional vCPU to keep cost per player low.
Case Study

Server Management & Distribution
Matrioshka Games
Read how Matrioshka Games were able to ship a Battle Royale in early access with limited ressources.
Case Study

At my Signal, Unleash Hell!
TyGames
Discover how Indie studio TyGames immerses players in third-person gladiatorial combat multiplayer.
Case Study

Instant Worldwide Orchestration
Soliton Interactive
Discover how Soliton Interactive did the impossible… Ship it's first playable as multiplayer!
Case Study

Competitive play with server-side physics ensures ideal sub-50 ms latency
NS7
Discover why solely Edgegap could enable an indie studio to deliver on its vision for a AAA-quality F2P sports gameplay through server-side physics and authority.
Case Study

Regional Deployments for iGaming
X1 Contra 1
X1 Contra 1 delivers real-time PvP casual games to its Brazilian player base through cost-effective hosting & regional deployments, ensuring data and legal compliance.
Case Study

Pay Only When Players Play: Affordable Multiplayer Infrastructure
Meltdown Interactive
How Edgegap helped indie developer Meltdown Interactive Media solve cost-effective scaling and matchmaking without the complexity, so they could focus on building the game.
Case Study

One Edgegap platform, three very different networking profiles
Warped Games
How Warped Games runs a social hub, real-time co-op, and turn-based co-op, all on the same Edgegap deployment API and the same container pipeline.
Case Study

Pool Live Tour Max
RETA Games
Case Study

Korea’s Web3 POP Extraction Shooter Goes Global, Instantly
NDUS Entertainment
How XOCIETY easily added Edgegap orchestration & integrated custom matchmaking working alongside Edgegap Ping Beacons to optimize latency.
Case Study

Multiplayer in Every Dimension
Arcadia.tv
Discover how Arcadia.tv uses Edgegap's edge network to deliver an innovative, team and location-based athletic VR sport.
Case Study

F2P Mobile Fighter Cuts Infrastructure Costs With Just-in-Time Servers
Game Changers Worldwide
How Game Changer Worldwide hosted Rumble Rush's real-time 3v3 PvP globally on mobile.
Case Study
Key reasons why they chose Edgegap
Discover the impact of Edgegap's automated game server orchestration for a flawless multiplayer experience.









